Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_sqertio_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_cqertio_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_sqertio_txn_next (const struct rtio_iodev_sqe *iodev_sqe)
 Get the next sqe in the transaction.
 
static struct rtio_iodev_sqertio_chain_next (const struct rtio_iodev_sqe *iodev_sqe)
 Get the next sqe in the chain.
 
static struct rtio_iodev_sqertio_iodev_sqe_next (const struct rtio_iodev_sqe *iodev_sqe)
 Get the next sqe in the chain or transaction.
 
static struct rtio_sqertio_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_cqertio_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_cqertio_cqe_consume (struct rtio *r)
 Consume a single completion queue event if available.
 
static struct rtio_cqertio_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.