rtio.h File Reference

Real-Time IO device API for moving bytes with low effort. More...

#include <string.h>
#include <zephyr/app_memory/app_memdomain.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <zephyr/kernel_structs.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/mem_blocks.h>
#include <zephyr/sys/util.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/rtio/sqe.h>
#include <zephyr/rtio/cqe.h>
#include <zephyr/rtio/iodev.h>
#include <zephyr/syscalls/rtio.h>

Go to the source code of this file.

Data Structures
struct	rtio
	An RTIO context containing what can be viewed as a pair of queues. More...
struct	rtio_pool
	Pool of RTIO contexts to use with dynamically created threads. More...

Macros
#define	RTIO_DEFINE(name, sq_sz, cq_sz)
	Statically define and initialize an RTIO context.
#define	RTIO_BMEM   COND_CODE_1(CONFIG_USERSPACE, (K_APP_BMEM(rtio_partition) static), (static))
	Allocate to bss if available.
#define	RTIO_DMEM   COND_CODE_1(CONFIG_USERSPACE, (K_APP_DMEM(rtio_partition) static), (static))
	Allocate as initialized memory if available.
#define	RTIO_DEFINE_WITH_MEMPOOL(name, sq_sz, cq_sz, num_blks, blk_size, balign)
	Statically define and initialize an RTIO context.
#define	RTIO_POOL_DEFINE(name, pool_sz, sq_sz, cq_sz)
	Statically define and initialize a pool of RTIO contexts.

Functions
static size_t	rtio_mempool_block_size (const struct rtio *r)
	Get the mempool block size of the RTIO context.
static int	rtio_block_pool_alloc (struct rtio *r, size_t min_sz, size_t max_sz, uint8_t **buf, uint32_t *buf_len)
static void	rtio_block_pool_free (struct rtio *r, void *buf, uint32_t buf_len)
static uint32_t	rtio_sqe_acquirable (struct rtio *r)
	Count of acquirable submission queue events.
static struct rtio_sqe *	rtio_sqe_acquire (struct rtio *r)
	Acquire a single submission queue event if available.
static int	rtio_sqe_acquire_array (struct rtio *r, size_t n, struct rtio_sqe **sqes)
	Acquire a number of submission queue events if available.
static void	rtio_sqe_drop_all (struct rtio *r)
	Drop all previously acquired sqe.
static struct rtio_cqe *	rtio_cqe_acquire (struct rtio *r)
	Acquire a complete queue event if available.
static void	rtio_cqe_produce (struct rtio *r, struct rtio_cqe *cqe)
	Produce a complete queue event if available.
static struct rtio_cqe *	rtio_cqe_consume (struct rtio *r)
	Consume a single completion queue event if available.
static struct rtio_cqe *	rtio_cqe_consume_block (struct rtio *r)
	Wait for and consume a single completion queue event.
static void	rtio_cqe_release (struct rtio *r, struct rtio_cqe *cqe)
	Release consumed completion queue event.
static int	rtio_flush_completion_queue (struct rtio *r)
	Flush completion queue.
void	rtio_sqe_signal (struct rtio_sqe *sqe)
	Signal an AWAIT SQE.
static uint32_t	rtio_cqe_compute_flags (struct rtio_iodev_sqe *iodev_sqe)
	Compute the CQE flags from the rtio_iodev_sqe entry.
int	rtio_cqe_get_mempool_buffer (const struct rtio *r, struct rtio_cqe *cqe, uint8_t **buff, uint32_t *buff_len)
	Retrieve the mempool buffer that was allocated for the CQE.
void	rtio_executor_submit (struct rtio *r)
void	rtio_executor_ok (struct rtio_iodev_sqe *iodev_sqe, int result)
void	rtio_executor_err (struct rtio_iodev_sqe *iodev_sqe, int result)
static void	rtio_iodev_sqe_ok (struct rtio_iodev_sqe *iodev_sqe, int result)
	Inform the executor of a submission completion with success.
static void	rtio_iodev_sqe_err (struct rtio_iodev_sqe *iodev_sqe, int result)
	Inform the executor of a submissions completion with error.
static void	rtio_cqe_submit (struct rtio *r, int result, void *userdata, uint32_t flags)
	Submit a completion queue event with a given result and userdata.
static int	rtio_sqe_rx_buf (const struct rtio_iodev_sqe *iodev_sqe, uint32_t min_buf_len, uint32_t max_buf_len, uint8_t **buf, uint32_t *buf_len)
	Get the buffer associate with the RX submission.
void	rtio_release_buffer (struct rtio *r, void *buff, uint32_t buff_len)
	Release memory that was allocated by the RTIO's memory pool.
static void	rtio_access_grant (struct rtio *r, struct k_thread *t)
	Grant access to an RTIO context to a user thread.
static void	rtio_access_revoke (struct rtio *r, struct k_thread *t)
	Revoke access to an RTIO context from a user thread.
int	rtio_sqe_cancel (struct rtio_sqe *sqe)
	Attempt to cancel an SQE.
int	rtio_sqe_copy_in_get_handles (struct rtio *r, const struct rtio_sqe *sqes, struct rtio_sqe **handle, size_t sqe_count)
	Copy an array of SQEs into the queue and get resulting handles back.
static int	rtio_sqe_copy_in (struct rtio *r, const struct rtio_sqe *sqes, size_t sqe_count)
	Copy an array of SQEs into the queue.
int	rtio_cqe_copy_out (struct rtio *r, struct rtio_cqe *cqes, size_t cqe_count, k_timeout_t timeout)
	Copy an array of CQEs from the queue.
int	rtio_submit (struct rtio *r, uint32_t wait_count)
	Submit I/O requests to the underlying executor.
struct rtio *	rtio_pool_acquire (struct rtio_pool *pool)
	Obtain an RTIO context from a pool.
void	rtio_pool_release (struct rtio_pool *pool, struct rtio *r)
	Return an RTIO context to a pool.

Variables
struct k_mem_partition	rtio_partition
	The memory partition associated with all RTIO context information.

Detailed Description

Real-Time IO device API for moving bytes with low effort.

RTIO is a context for asynchronous batch operations using a submission and completion queue.

Asynchronous I/O operation are setup in a submission queue. Each entry in the queue describes the operation it wishes to perform with some understood semantics.

These operations may be chained in a such a way that only when the current operation is complete the next will be executed. If the current operation fails all chained operations will also fail.

Operations may also be submitted as a transaction where a set of operations are considered to be one operation.

The completion of these operations typically provide one or more completion queue events.