RTIO

RTIO . More...

Topics
	RTIO CQE Flags
	RTIO CQE Flags .
	RTIO Priorities
	RTIO Predefined Priorities .
	RTIO SQE Flags
	RTIO SQE Flags .

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_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_IODEV_I3C_STOP   BIT(1)
	Equivalent to the I3C_MSG_STOP flag.
#define	RTIO_IODEV_I3C_RESTART   BIT(2)
	Equivalent to the I3C_MSG_RESTART flag.
#define	RTIO_IODEV_I3C_HDR   BIT(3)
	Equivalent to the I3C_MSG_HDR.
#define	RTIO_IODEV_I3C_NBCH   BIT(4)
	Equivalent to the I3C_MSG_NBCH.
#define	RTIO_IODEV_I3C_HDR_MODE_MASK   GENMASK(15, 8)
	I3C HDR Mode Mask.
#define	RTIO_IODEV_I3C_HDR_MODE_SET(flags)
	I3C HDR Mode Mask.
#define	RTIO_IODEV_I3C_HDR_MODE_GET(flags)
	I3C HDR Mode Mask.
#define	RTIO_IODEV_I3C_HDR_CMD_CODE_MASK   GENMASK(22, 16)
	I3C HDR 7b Command Code.
#define	RTIO_IODEV_I3C_HDR_CMD_CODE_SET(flags)
	I3C HDR 7b Command Code.
#define	RTIO_IODEV_I3C_HDR_CMD_CODE_GET(flags)
	I3C HDR 7b Command Code.
#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_OP_I3C_RECOVER   (RTIO_OP_I2C_CONFIGURE+1)
	An operation to recover I3C buses.
#define	RTIO_OP_I3C_CONFIGURE   (RTIO_OP_I3C_RECOVER+1)
	An operation to configure I3C buses.
#define	RTIO_OP_I3C_CCC   (RTIO_OP_I3C_CONFIGURE+1)
	An operation to sends I3C CCC.
#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, const 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_callback_no_cqe (struct rtio_sqe *sqe, rtio_callback_t callback, void *arg0, void *userdata)
	Prepare a callback op submission that does not create a CQE.
static void	rtio_sqe_prep_transceive (struct rtio_sqe *sqe, const struct rtio_iodev *iodev, int8_t prio, const 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

RTIO .

Since

3.2

Version

0.1.0

Macro Definition Documentation

RTIO_BMEM

#define RTIO_BMEM   COND_CODE_1(CONFIG_USERSPACE, (K_APP_BMEM(rtio_partition) static), (static))

#include <zephyr/rtio/rtio.h>

Allocate to bss if available.

If CONFIG_USERSPACE is selected, allocate to the rtio_partition bss. Maps to: K_APP_BMEM(rtio_partition) static

If CONFIG_USERSPACE is disabled, allocate as plain static: static

RTIO_DEFINE

#define RTIO_DEFINE	(		name,
			sq_sz,
			cq_sz )

#include <zephyr/rtio/rtio.h>

Value:

        Z_RTIO_SQE_POOL_DEFINE(CONCAT(name, _sqe_pool), sq_sz);                 \
        Z_RTIO_CQE_POOL_DEFINE(CONCAT(name, _cqe_pool), cq_sz);                 \
        Z_RTIO_DEFINE(name, &CONCAT(name, _sqe_pool),                           \
                      &CONCAT(name, _cqe_pool), NULL)

Statically define and initialize an RTIO context.

Parameters

name	Name of the RTIO
sq_sz	Size of the submission queue entry pool
cq_sz	Size of the completion queue entry pool

RTIO_DEFINE_WITH_MEMPOOL

#define RTIO_DEFINE_WITH_MEMPOOL	(		name,
			sq_sz,
			cq_sz,
			num_blks,
			blk_size,
			balign )

#include <zephyr/rtio/rtio.h>

Value:

        Z_RTIO_SQE_POOL_DEFINE(name##_sqe_pool, sq_sz);         \
        Z_RTIO_CQE_POOL_DEFINE(name##_cqe_pool, cq_sz);                 \
        Z_RTIO_BLOCK_POOL_DEFINE(name##_block_pool, blk_size, num_blks, balign); \
        Z_RTIO_DEFINE(name, &name##_sqe_pool, &name##_cqe_pool, &name##_block_pool)

Statically define and initialize an RTIO context.

Parameters

name	Name of the RTIO
sq_sz	Size of the submission queue, must be power of 2
cq_sz	Size of the completion queue, must be power of 2
num_blks	Number of blocks in the memory pool
blk_size	The number of bytes in each block
balign	The block alignment

RTIO_DMEM

#define RTIO_DMEM   COND_CODE_1(CONFIG_USERSPACE, (K_APP_DMEM(rtio_partition) static), (static))

#include <zephyr/rtio/rtio.h>

Allocate as initialized memory if available.

If CONFIG_USERSPACE is selected, allocate to the rtio_partition init. Maps to: K_APP_DMEM(rtio_partition) static

If CONFIG_USERSPACE is disabled, allocate as plain static: static

RTIO_IODEV_DEFINE

#define RTIO_IODEV_DEFINE	(		name,
			iodev_api,
			iodev_data )

#include <zephyr/rtio/rtio.h>

Value:

        STRUCT_SECTION_ITERABLE(rtio_iodev, name) = {           \
                .api = (iodev_api),                             \
                .data = (iodev_data),                           \
        }

Statically define and initialize an RTIO IODev.

Parameters

name	Name of the iodev
iodev_api	Pointer to struct rtio_iodev_api
iodev_data	Data pointer

RTIO_IODEV_I2C_10_BITS

#define RTIO_IODEV_I2C_10_BITS   BIT(3)

#include <zephyr/rtio/rtio.h>

Equivalent to the I2C_MSG_ADDR_10_BITS.

RTIO_IODEV_I2C_RESTART

#define RTIO_IODEV_I2C_RESTART   BIT(2)

#include <zephyr/rtio/rtio.h>

Equivalent to the I2C_MSG_RESTART flag.

RTIO_IODEV_I2C_STOP

#define RTIO_IODEV_I2C_STOP   BIT(1)

#include <zephyr/rtio/rtio.h>

Equivalent to the I2C_MSG_STOP flag.

RTIO_IODEV_I3C_HDR

#define RTIO_IODEV_I3C_HDR   BIT(3)

#include <zephyr/rtio/rtio.h>

Equivalent to the I3C_MSG_HDR.

RTIO_IODEV_I3C_HDR_CMD_CODE_GET

#define RTIO_IODEV_I3C_HDR_CMD_CODE_GET

(

flags

)

#include <zephyr/rtio/rtio.h>

Value:

        FIELD_GET(RTIO_IODEV_I3C_HDR_CMD_CODE_MASK, flags)

I3C HDR 7b Command Code.

RTIO_IODEV_I3C_HDR_CMD_CODE_MASK

#define RTIO_IODEV_I3C_HDR_CMD_CODE_MASK   GENMASK(22, 16)

#include <zephyr/rtio/rtio.h>

I3C HDR 7b Command Code.

RTIO_IODEV_I3C_HDR_CMD_CODE_SET

#define RTIO_IODEV_I3C_HDR_CMD_CODE_SET

(

flags

)

#include <zephyr/rtio/rtio.h>

Value:

        FIELD_PREP(RTIO_IODEV_I3C_HDR_CMD_CODE_MASK, flags)

I3C HDR 7b Command Code.

RTIO_IODEV_I3C_HDR_MODE_GET

#define RTIO_IODEV_I3C_HDR_MODE_GET

(

flags

)

#include <zephyr/rtio/rtio.h>

Value:

        FIELD_GET(RTIO_IODEV_I3C_HDR_MODE_MASK, flags)

I3C HDR Mode Mask.

RTIO_IODEV_I3C_HDR_MODE_MASK

#define RTIO_IODEV_I3C_HDR_MODE_MASK   GENMASK(15, 8)

#include <zephyr/rtio/rtio.h>

I3C HDR Mode Mask.

RTIO_IODEV_I3C_HDR_MODE_SET

#define RTIO_IODEV_I3C_HDR_MODE_SET

(

flags

)

#include <zephyr/rtio/rtio.h>

Value:

        FIELD_PREP(RTIO_IODEV_I3C_HDR_MODE_MASK, flags)

I3C HDR Mode Mask.

RTIO_IODEV_I3C_NBCH

#define RTIO_IODEV_I3C_NBCH   BIT(4)

#include <zephyr/rtio/rtio.h>

Equivalent to the I3C_MSG_NBCH.

RTIO_IODEV_I3C_RESTART

#define RTIO_IODEV_I3C_RESTART   BIT(2)

#include <zephyr/rtio/rtio.h>

Equivalent to the I3C_MSG_RESTART flag.

RTIO_IODEV_I3C_STOP

#define RTIO_IODEV_I3C_STOP   BIT(1)

#include <zephyr/rtio/rtio.h>

Equivalent to the I3C_MSG_STOP flag.

RTIO_OP_CALLBACK

#define RTIO_OP_CALLBACK   (RTIO_OP_TINY_TX+1)

#include <zephyr/rtio/rtio.h>

An operation that calls a given function (callback)

RTIO_OP_I2C_CONFIGURE

#define RTIO_OP_I2C_CONFIGURE   (RTIO_OP_I2C_RECOVER+1)

#include <zephyr/rtio/rtio.h>

An operation to configure I2C buses.

RTIO_OP_I2C_RECOVER

#define RTIO_OP_I2C_RECOVER   (RTIO_OP_TXRX+1)

#include <zephyr/rtio/rtio.h>

An operation to recover I2C buses.

RTIO_OP_I3C_CCC

#define RTIO_OP_I3C_CCC   (RTIO_OP_I3C_CONFIGURE+1)

#include <zephyr/rtio/rtio.h>

An operation to sends I3C CCC.

RTIO_OP_I3C_CONFIGURE

#define RTIO_OP_I3C_CONFIGURE   (RTIO_OP_I3C_RECOVER+1)

#include <zephyr/rtio/rtio.h>

An operation to configure I3C buses.

RTIO_OP_I3C_RECOVER

#define RTIO_OP_I3C_RECOVER   (RTIO_OP_I2C_CONFIGURE+1)

#include <zephyr/rtio/rtio.h>

An operation to recover I3C buses.

RTIO_OP_NOP

#define RTIO_OP_NOP   0

#include <zephyr/rtio/rtio.h>

An operation that does nothing and will complete immediately.

RTIO_OP_RX

#define RTIO_OP_RX   (RTIO_OP_NOP+1)

#include <zephyr/rtio/rtio.h>

An operation that receives (reads)

RTIO_OP_TINY_TX

#define RTIO_OP_TINY_TX   (RTIO_OP_TX+1)

#include <zephyr/rtio/rtio.h>

An operation that transmits tiny writes by copying the data to write.

RTIO_OP_TX

#define RTIO_OP_TX   (RTIO_OP_RX+1)

#include <zephyr/rtio/rtio.h>

An operation that transmits (writes)

RTIO_OP_TXRX

#define RTIO_OP_TXRX   (RTIO_OP_CALLBACK+1)

#include <zephyr/rtio/rtio.h>

An operation that transceives (reads and writes simultaneously)

Typedef Documentation

rtio_callback_t

typedef void(* rtio_callback_t) (struct rtio *r, const struct rtio_sqe *sqe, void *arg0)

#include <zephyr/rtio/rtio.h>

Callback signature for RTIO_OP_CALLBACK.

Parameters

r	RTIO context being used with the callback
sqe	Submission for the callback op
arg0	Argument option as part of the sqe

Function Documentation

rtio_access_grant()

static void rtio_access_grant ( struct rtio * r, struct k_thread * t )

inlinestatic

#include <zephyr/rtio/rtio.h>

Grant access to an RTIO context to a user thread.

rtio_block_pool_alloc()

static int rtio_block_pool_alloc ( struct rtio * r, size_t min_sz, size_t max_sz, uint8_t ** buf, uint32_t * buf_len )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_block_pool_free()

static void rtio_block_pool_free ( struct rtio * r, void * buf, uint32_t buf_len )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_chain_next()

static struct rtio_iodev_sqe * rtio_chain_next ( const struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Get the next sqe in the chain.

Parameters

iodev_sqe

Submission queue entry

Return values

NULL	if current sqe is last in chain
struct	rtio_sqe * if available

rtio_cqe_acquire()

static struct rtio_cqe * rtio_cqe_acquire ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Acquire a complete queue event if available.

rtio_cqe_compute_flags()

static uint32_t rtio_cqe_compute_flags ( struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Compute the CQE flags from the rtio_iodev_sqe entry.

Parameters

iodev_sqe

The SQE entry in question.

Returns

The value that should be set for the CQE's flags field.

rtio_cqe_consume()

static struct rtio_cqe * rtio_cqe_consume ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Consume a single completion queue event if available.

If a completion queue event is returned rtio_cq_release(r) must be called at some point to release the cqe spot for the cqe producer.

Parameters

r	RTIO context

Return values

cqe	A valid completion queue event consumed from the completion queue
NULL	No completion queue event available

rtio_cqe_consume_block()

static struct rtio_cqe * rtio_cqe_consume_block ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Wait for and consume a single completion queue event.

If a completion queue event is returned rtio_cq_release(r) must be called at some point to release the cqe spot for the cqe producer.

Parameters

r	RTIO context

Return values

cqe	A valid completion queue event consumed from the completion queue

rtio_cqe_copy_out()

int rtio_cqe_copy_out	(	struct rtio *	r,
		struct rtio_cqe *	cqes,
		size_t	cqe_count,
		k_timeout_t	timeout )

#include <zephyr/rtio/rtio.h>

Copy an array of CQEs from the queue.

Copies from the RTIO context and its queue completion queue events, waiting for the given time period to gather the number of completions requested.

Parameters

r	RTIO context
cqes	Pointer to an array of SQEs
cqe_count	Count of sqes in array
timeout	Timeout to wait for each completion event. Total wait time is potentially timeout*cqe_count at maximum.

Return values

copy_count

Count of copied CQEs (0 to cqe_count)

rtio_cqe_get_mempool_buffer()

int rtio_cqe_get_mempool_buffer	(	const struct rtio *	r,
		struct rtio_cqe *	cqe,
		uint8_t **	buff,
		uint32_t *	buff_len )

#include <zephyr/rtio/rtio.h>

Retrieve the mempool buffer that was allocated for the CQE.

If the RTIO context contains a memory pool, and the SQE was created by calling rtio_sqe_read_with_pool(), this function can be used to retrieve the memory associated with the read. Once processing is done, it should be released by calling rtio_release_buffer().

Parameters

[in]	r	RTIO context
[in]	cqe	The CQE handling the event.
[out]	buff	Pointer to the mempool buffer
[out]	buff_len	Length of the allocated buffer

Returns

0 on success

-EINVAL if the buffer wasn't allocated for this cqe

-ENOTSUP if memory blocks are disabled

rtio_cqe_pool_alloc()

static struct rtio_cqe * rtio_cqe_pool_alloc ( struct rtio_cqe_pool * pool )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_cqe_pool_free()

static void rtio_cqe_pool_free ( struct rtio_cqe_pool * pool, struct rtio_cqe * cqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_cqe_produce()

static void rtio_cqe_produce ( struct rtio * r, struct rtio_cqe * cqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Produce a complete queue event if available.

rtio_cqe_release()

static void rtio_cqe_release ( struct rtio * r, struct rtio_cqe * cqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Release consumed completion queue event.

Parameters

r	RTIO context
cqe	Completion queue entry

rtio_cqe_submit()

static void rtio_cqe_submit ( struct rtio * r, int result, void * userdata, uint32_t flags )

inlinestatic

#include <zephyr/rtio/rtio.h>

Submit a completion queue event with a given result and userdata.

Called by the executor to produce a completion queue event, no inherent locking is performed and this is not safe to do from multiple callers.

Parameters

r	RTIO context
result	Integer result code (could be -errno)
userdata	Userdata to pass along to completion
flags	Flags to use for the CEQ see RTIO_CQE_FLAG_*

rtio_executor_err()

void rtio_executor_err	(	struct rtio_iodev_sqe *	iodev_sqe,
		int	result )

#include <zephyr/rtio/rtio.h>

rtio_executor_ok()

void rtio_executor_ok	(	struct rtio_iodev_sqe *	iodev_sqe,
		int	result )

#include <zephyr/rtio/rtio.h>

rtio_executor_submit()

void rtio_executor_submit

(

struct rtio *

r

)

#include <zephyr/rtio/rtio.h>

rtio_iodev_sqe_err()

static void rtio_iodev_sqe_err ( struct rtio_iodev_sqe * iodev_sqe, int result )

inlinestatic

#include <zephyr/rtio/rtio.h>

Inform the executor of a submissions completion with error.

This SHALL fail the remaining submissions in the chain.

Parameters

iodev_sqe	Submission that has failed
result	Result of the request

rtio_iodev_sqe_next()

static struct rtio_iodev_sqe * rtio_iodev_sqe_next ( const struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Get the next sqe in the chain or transaction.

Parameters

iodev_sqe

Submission queue entry

Return values

NULL	if current sqe is last in chain
struct	rtio_iodev_sqe * if available

rtio_iodev_sqe_ok()

static void rtio_iodev_sqe_ok ( struct rtio_iodev_sqe * iodev_sqe, int result )

inlinestatic

#include <zephyr/rtio/rtio.h>

Inform the executor of a submission completion with success.

This may start the next asynchronous request if one is available.

Parameters

iodev_sqe	IODev Submission that has succeeded
result	Result of the request

rtio_mempool_block_size()

static size_t rtio_mempool_block_size ( const struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Get the mempool block size of the RTIO context.

Parameters

[in]

r

The RTIO context

Returns

The size of each block in the context's mempool

0 if the context doesn't have a mempool

rtio_release_buffer()

void rtio_release_buffer	(	struct rtio *	r,
		void *	buff,
		uint32_t	buff_len )

#include <zephyr/rtio/rtio.h>

Release memory that was allocated by the RTIO's memory pool.

If the RTIO context was created by a call to RTIO_DEFINE_WITH_MEMPOOL(), then the cqe data might contain a buffer that's owned by the RTIO context. In those cases (if the read request was configured via rtio_sqe_read_with_pool()) the buffer must be returned back to the pool.

Call this function when processing is complete. This function will validate that the memory actually belongs to the RTIO context and will ignore invalid arguments.

Parameters

r	RTIO context
buff	Pointer to the buffer to be released.
buff_len	Number of bytes to free (will be rounded up to nearest memory block).

rtio_sqe_acquirable()

static uint32_t rtio_sqe_acquirable ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Count of acquirable submission queue events.

Parameters

r	RTIO context

Returns

Count of acquirable submission queue events

rtio_sqe_acquire()

static struct rtio_sqe * rtio_sqe_acquire ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Acquire a single submission queue event if available.

Parameters

r	RTIO context

Return values

sqe	A valid submission queue event acquired from the submission queue
NULL	No subsmission queue event available

rtio_sqe_cancel()

int rtio_sqe_cancel

(

struct rtio_sqe *

sqe

)

#include <zephyr/rtio/rtio.h>

Attempt to cancel an SQE.

If possible (not currently executing), cancel an SQE and generate a failure with -ECANCELED result.

Parameters

[in]

sqe

The SQE to cancel

Returns

0 if the SQE was flagged for cancellation

<0 on error

rtio_sqe_copy_in()

static int rtio_sqe_copy_in ( struct rtio * r, const struct rtio_sqe * sqes, size_t sqe_count )

inlinestatic

#include <zephyr/rtio/rtio.h>

Copy an array of SQEs into the queue.

Useful if a batch of submissions is stored in ROM or RTIO is used from user mode where a copy must be made.

Partial copying is not done as chained SQEs need to be submitted as a whole set.

Parameters

r	RTIO context
sqes	Pointer to an array of SQEs
sqe_count	Count of sqes in array

Return values

0	success
-ENOMEM	not enough room in the queue

rtio_sqe_copy_in_get_handles()

int rtio_sqe_copy_in_get_handles	(	struct rtio *	r,
		const struct rtio_sqe *	sqes,
		struct rtio_sqe **	handle,
		size_t	sqe_count )

#include <zephyr/rtio/rtio.h>

Copy an array of SQEs into the queue and get resulting handles back.

Copies one or more SQEs into the RTIO context and optionally returns their generated SQE handles. Handles can be used to cancel events via the rtio_sqe_cancel() call.

Parameters

[in]	r	RTIO context
[in]	sqes	Pointer to an array of SQEs
[out]	handle	Optional pointer to rtio_sqe pointer to store the handle of the first generated SQE. Use NULL to ignore.
[in]	sqe_count	Count of sqes in array

Return values

0	success
-ENOMEM	not enough room in the queue

rtio_sqe_drop_all()

static void rtio_sqe_drop_all ( struct rtio * r )

inlinestatic

#include <zephyr/rtio/rtio.h>

Drop all previously acquired sqe.

Parameters

r	RTIO context

rtio_sqe_pool_alloc()

static struct rtio_iodev_sqe * rtio_sqe_pool_alloc ( struct rtio_sqe_pool * pool )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_sqe_pool_free()

static void rtio_sqe_pool_free ( struct rtio_sqe_pool * pool, struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_sqe_prep_callback()

static void rtio_sqe_prep_callback ( struct rtio_sqe * sqe, rtio_callback_t callback, void * arg0, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a callback op submission.

A somewhat special operation in that it may only be done in kernel mode.

Used where general purpose logic is required in a queue of io operations to do transforms or logic.

rtio_sqe_prep_callback_no_cqe()

static void rtio_sqe_prep_callback_no_cqe ( struct rtio_sqe * sqe, rtio_callback_t callback, void * arg0, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a callback op submission that does not create a CQE.

Similar to rtio_sqe_prep_callback, but the RTIO_SQE_NO_RESPONSE flag is set on the SQE to prevent the generation of a CQE upon completion.

This can be useful when the callback is the last operation in a sequence whose job is to clean up all the previous CQE's. Without RTIO_SQE_NO_RESPONSE the completion itself will result in a CQE that cannot be consumed in the callback.

rtio_sqe_prep_nop()

static void rtio_sqe_prep_nop ( struct rtio_sqe * sqe, const struct rtio_iodev * iodev, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a nop (no op) submission.

rtio_sqe_prep_read()

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 )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a read op submission.

rtio_sqe_prep_read_multishot()

static void rtio_sqe_prep_read_multishot ( struct rtio_sqe * sqe, const struct rtio_iodev * iodev, int8_t prio, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

rtio_sqe_prep_read_with_pool()

static void rtio_sqe_prep_read_with_pool ( struct rtio_sqe * sqe, const struct rtio_iodev * iodev, int8_t prio, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a read op submission with context's mempool.

See also

rtio_sqe_prep_read()

rtio_sqe_prep_tiny_write()

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 )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a tiny write op submission.

Unlike the normal write operation where the source buffer must outlive the call the tiny write data in this case is copied to the sqe. It must be tiny to fit within the specified size of a rtio_sqe.

This is useful in many scenarios with RTL logic where a write of the register to subsequently read must be done.

rtio_sqe_prep_transceive()

static void rtio_sqe_prep_transceive ( struct rtio_sqe * sqe, const struct rtio_iodev * iodev, int8_t prio, const uint8_t * tx_buf, uint8_t * rx_buf, uint32_t buf_len, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a transceive op submission.

rtio_sqe_prep_write()

static void rtio_sqe_prep_write ( struct rtio_sqe * sqe, const struct rtio_iodev * iodev, int8_t prio, const uint8_t * buf, uint32_t len, void * userdata )

inlinestatic

#include <zephyr/rtio/rtio.h>

Prepare a write op submission.

rtio_sqe_rx_buf()

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 )

inlinestatic

#include <zephyr/rtio/rtio.h>

Get the buffer associate with the RX submission.

Parameters

[in]	iodev_sqe	The submission to probe
[in]	min_buf_len	The minimum number of bytes needed for the operation
[in]	max_buf_len	The maximum number of bytes needed for the operation
[out]	buf	Where to store the pointer to the buffer
[out]	buf_len	Where to store the size of the buffer

Returns

0 if buf and buf_len were successfully filled

-ENOMEM Not enough memory for min_buf_len

rtio_submit()

int rtio_submit	(	struct rtio *	r,
		uint32_t	wait_count )

#include <zephyr/rtio/rtio.h>

Submit I/O requests to the underlying executor.

Submits the queue of submission queue events to the executor. The executor will do the work of managing tasks representing each submission chain, freeing submission queue events when done, and producing completion queue events as submissions are completed.

Parameters

r	RTIO context
wait_count	Number of submissions to wait for completion of.

Return values

0	On success

rtio_txn_next()

static struct rtio_iodev_sqe * rtio_txn_next ( const struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/rtio/rtio.h>

Get the next sqe in the transaction.

Parameters

iodev_sqe

Submission queue entry

Return values

NULL	if current sqe is last in transaction
struct	rtio_sqe * if available

Variable Documentation

rtio_partition

struct k_mem_partition rtio_partition

extern

#include <zephyr/rtio/rtio.h>

The memory partition associated with all RTIO context information.