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_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, 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_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_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.

Topics

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RTIO_BMEM

◆ RTIO_DEFINE

◆ RTIO_DEFINE_WITH_MEMPOOL

◆ RTIO_DMEM

◆ RTIO_IODEV_DEFINE

◆ RTIO_IODEV_I2C_10_BITS

◆ RTIO_IODEV_I2C_RESTART

◆ RTIO_IODEV_I2C_STOP

◆ RTIO_OP_CALLBACK

◆ RTIO_OP_I2C_CONFIGURE

◆ RTIO_OP_I2C_RECOVER

◆ RTIO_OP_NOP

◆ RTIO_OP_RX

◆ RTIO_OP_TINY_TX

◆ RTIO_OP_TX

◆ RTIO_OP_TXRX

Typedef Documentation

◆ rtio_callback_t

Function Documentation

◆ rtio_access_grant()

◆ rtio_block_pool_alloc()

◆ rtio_block_pool_free()

◆ rtio_chain_next()

◆ rtio_cqe_acquire()

◆ rtio_cqe_compute_flags()

◆ rtio_cqe_consume()

◆ rtio_cqe_consume_block()

◆ rtio_cqe_copy_out()

◆ rtio_cqe_get_mempool_buffer()

◆ rtio_cqe_pool_alloc()

◆ rtio_cqe_pool_free()

◆ rtio_cqe_produce()

◆ rtio_cqe_release()

◆ rtio_cqe_submit()

◆ rtio_executor_err()

◆ rtio_executor_ok()

◆ rtio_executor_submit()

◆ rtio_iodev_sqe_err()

◆ rtio_iodev_sqe_next()

◆ rtio_iodev_sqe_ok()

◆ rtio_mempool_block_size()

◆ rtio_release_buffer()

◆ rtio_sqe_acquirable()

◆ rtio_sqe_acquire()

◆ rtio_sqe_cancel()

◆ rtio_sqe_copy_in()

◆ rtio_sqe_copy_in_get_handles()

◆ rtio_sqe_drop_all()

◆ rtio_sqe_pool_alloc()

◆ rtio_sqe_pool_free()

◆ rtio_sqe_prep_callback()

◆ rtio_sqe_prep_callback_no_cqe()

◆ rtio_sqe_prep_nop()

◆ rtio_sqe_prep_read()

◆ rtio_sqe_prep_read_multishot()

◆ rtio_sqe_prep_read_with_pool()

◆ rtio_sqe_prep_tiny_write()

◆ rtio_sqe_prep_transceive()

◆ rtio_sqe_prep_write()

◆ rtio_sqe_rx_buf()

◆ rtio_submit()

◆ rtio_txn_next()

Variable Documentation

◆ rtio_partition