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/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/sys/mpsc_lockfree.h>
#include <zephyr/syscalls/rtio.h>

Go to the source code of this file.

Data Structures
struct	rtio_sqe
	A submission queue event. More...
struct	rtio_cqe
	A completion queue event. More...
struct	rtio_sqe_pool
struct	rtio_cqe_pool
struct	rtio
	An RTIO context containing what can be viewed as a pair of queues. More...
struct	rtio_iodev_sqe
	Compute the mempool block index for a given pointer. More...
struct	rtio_iodev_api
	API that an RTIO IO device should implement. More...
struct	rtio_iodev
	An IO device with a function table for submitting requests. More...

Macros
#define	RTIO_PRIO_LOW   0U
	Low priority.
#define	RTIO_PRIO_NORM   127U
	Normal priority.
#define	RTIO_PRIO_HIGH   255U
	High priority.
#define	RTIO_SQE_CHAINED   BIT(0)
	The next request in the queue should wait on this one.
#define	RTIO_SQE_TRANSACTION   BIT(1)
	The next request in the queue is part of a transaction.
#define	RTIO_SQE_MEMPOOL_BUFFER   BIT(2)
	The buffer should be allocated by the RTIO mempool.
#define	RTIO_SQE_CANCELED   BIT(3)
	The SQE should not execute if possible.
#define	RTIO_SQE_MULTISHOT   BIT(4)
	The SQE should continue producing CQEs until canceled.
#define	RTIO_SQE_NO_RESPONSE   BIT(5)
	The SQE does not produce a CQE.
#define	RTIO_CQE_FLAG_MEMPOOL_BUFFER   BIT(0)
	The entry's buffer was allocated from the RTIO's mempool.
#define	RTIO_CQE_FLAG_GET(flags)   FIELD_GET(GENMASK(7, 0), (flags))
#define	RTIO_CQE_FLAG_MEMPOOL_GET_BLK_IDX(flags)   FIELD_GET(GENMASK(19, 8), (flags))
	Get the block index of a mempool flags.
#define	RTIO_CQE_FLAG_MEMPOOL_GET_BLK_CNT(flags)   FIELD_GET(GENMASK(31, 20), (flags))
	Get the block count of a mempool flags.
#define	RTIO_CQE_FLAG_PREP_MEMPOOL(blk_idx, blk_cnt)
	Prepare CQE flags for a mempool read.
#define	RTIO_IODEV_I2C_STOP   BIT(1)
	Equivalent to the I2C_MSG_STOP flag.
#define	RTIO_IODEV_I2C_RESTART   BIT(2)
	Equivalent to the I2C_MSG_RESTART flag.
#define	RTIO_IODEV_I2C_10_BITS   BIT(3)
	Equivalent to the I2C_MSG_ADDR_10_BITS.
#define	RTIO_OP_NOP   0
	An operation that does nothing and will complete immediately.
#define	RTIO_OP_RX   (RTIO_OP_NOP+1)
	An operation that receives (reads)
#define	RTIO_OP_TX   (RTIO_OP_RX+1)
	An operation that transmits (writes)
#define	RTIO_OP_TINY_TX   (RTIO_OP_TX+1)
	An operation that transmits tiny writes by copying the data to write.
#define	RTIO_OP_CALLBACK   (RTIO_OP_TINY_TX+1)
	An operation that calls a given function (callback)
#define	RTIO_OP_TXRX   (RTIO_OP_CALLBACK+1)
	An operation that transceives (reads and writes simultaneously)
#define	RTIO_OP_I2C_RECOVER   (RTIO_OP_TXRX+1)
	An operation to recover I2C buses.
#define	RTIO_OP_I2C_CONFIGURE   (RTIO_OP_I2C_RECOVER+1)
	An operation to configure I2C buses.
#define	RTIO_IODEV_DEFINE(name, iodev_api, iodev_data)
	Statically define and initialize an RTIO IODev.
#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(name, sq_sz, cq_sz)
	Statically define and initialize an RTIO context.
#define	RTIO_DEFINE_WITH_MEMPOOL(name, sq_sz, cq_sz, num_blks, blk_size, balign)
	Statically define and initialize an RTIO context.

Typedefs
typedef void(*	rtio_callback_t) (struct rtio *r, const struct rtio_sqe *sqe, void *arg0)
	Callback signature for RTIO_OP_CALLBACK.

Functions
static size_t	rtio_mempool_block_size (const struct rtio *r)
	Get the mempool block size of the RTIO context.
static void	rtio_sqe_prep_nop (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, void *userdata)
	Prepare a nop (no op) submission.
static void	rtio_sqe_prep_read (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, uint8_t *buf, uint32_t len, void *userdata)
	Prepare a read op submission.
static void	rtio_sqe_prep_read_with_pool (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, void *userdata)
	Prepare a read op submission with context's mempool.
static void	rtio_sqe_prep_read_multishot (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, void *userdata)
static void	rtio_sqe_prep_write (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, uint8_t *buf, uint32_t len, void *userdata)
	Prepare a write op submission.
static void	rtio_sqe_prep_tiny_write (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, const uint8_t *tiny_write_data, uint8_t tiny_write_len, void *userdata)
	Prepare a tiny write op submission.
static void	rtio_sqe_prep_callback (struct rtio_sqe *sqe, rtio_callback_t callback, void *arg0, void *userdata)
	Prepare a callback op submission.
static void	rtio_sqe_prep_transceive (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, uint8_t *tx_buf, uint8_t *rx_buf, uint32_t buf_len, void *userdata)
	Prepare a transceive op submission.
static struct rtio_iodev_sqe *	rtio_sqe_pool_alloc (struct rtio_sqe_pool *pool)
static void	rtio_sqe_pool_free (struct rtio_sqe_pool *pool, struct rtio_iodev_sqe *iodev_sqe)
static struct rtio_cqe *	rtio_cqe_pool_alloc (struct rtio_cqe_pool *pool)
static void	rtio_cqe_pool_free (struct rtio_cqe_pool *pool, struct rtio_cqe *cqe)
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_iodev_sqe *	rtio_txn_next (const struct rtio_iodev_sqe *iodev_sqe)
	Get the next sqe in the transaction.
static struct rtio_iodev_sqe *	rtio_chain_next (const struct rtio_iodev_sqe *iodev_sqe)
	Get the next sqe in the chain.
static struct rtio_iodev_sqe *	rtio_iodev_sqe_next (const struct rtio_iodev_sqe *iodev_sqe)
	Get the next sqe in the chain or transaction.
static struct rtio_sqe *	rtio_sqe_acquire (struct rtio *r)
	Acquire a single submission queue event 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 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.
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.

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.