RTIO API. More...

Modules
	RTIO Priorities
	RTIO Predefined Priorties.

	RTIO SQE Flags
	RTIO SQE Flags.

Data Structures
struct	rtio_sqe
	A submission queue event. More...

struct	rtio_sq
	Submission queue. More...

struct	rtio_cqe
	A completion queue event. More...

struct	rtio_cq
	Completion queue. More...

struct	rtio_executor_api

struct	rtio_executor
	An executor does the work of executing the submissions. More...

struct	rtio
	An RTIO queue pair that both the kernel and application work with. More...

struct	rtio_iodev_api
	API that an RTIO IO device should implement. More...

struct	rtio_iodev_sqe

struct	rtio_iodev_sq
	IO device submission queue. More...

struct	rtio_iodev
	An IO device with a function table for submitting requests. More...

Macros
#define	RTIO_OP_NOP 0

#define	RTIO_OP_RX 1

#define	RTIO_OP_TX 2

#define	RTIO_SQ_DEFINE(name, len) RTIO_SPSC_DEFINE(name, struct rtio_sqe, len)
	Statically define and initialize a fixed length submission queue. More...

#define	RTIO_CQ_DEFINE(name, len) RTIO_SPSC_DEFINE(name, struct rtio_cqe, len)
	Statically define and initialize a fixed length completion queue. More...

#define	RTIO_IODEV_SQ_DEFINE(name, len) RTIO_SPSC_DEFINE(name, struct rtio_iodev_sqe, len)
	Statically define and initialize a fixed length iodev submission queue. More...

#define	RTIO_IODEV_DEFINE(name, iodev_api, qsize, iodev_data)
	Statically define and initialize an RTIO IODev. More...

#define	RTIO_DEFINE(name, exec, sq_sz, cq_sz)
	Statically define and initialize an RTIO context. More...

Functions
static void	rtio_sqe_prep_nop (struct rtio_sqe sqe, const struct rtio_iodev iodev, void *userdata)
	Prepare a nop (no op) submission. More...

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. More...

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. More...

static void	rtio_set_executor (struct rtio r, struct rtio_executor exc)
	Set the executor of the rtio context. More...

static void	rtio_iodev_submit (const struct rtio_sqe sqe, struct rtio r)
	Perform a submitted operation with an iodev. More...

static uint32_t	rtio_sqe_acquirable (struct rtio *r)
	Count of acquirable submission queue events. More...

static struct rtio_sqe *	rtio_sqe_acquire (struct rtio *r)
	Acquire a single submission queue event if available. More...

static void	rtio_sqe_produce_all (struct rtio *r)
	Produce all previously acquired sqe. More...

static void	rtio_sqe_drop_all (struct rtio *r)
	Drop all previously acquired sqe. More...

static struct rtio_cqe *	rtio_cqe_consume (struct rtio *r)
	Consume a single completion queue event if available. More...

static struct rtio_cqe *	rtio_cqe_consume_block (struct rtio *r)
	Wait for and consume a single completion queue event. More...

static void	rtio_cqe_release_all (struct rtio *r)
	Release all consumed completion queue events. More...

static void	rtio_sqe_ok (struct rtio r, const struct rtio_sqe sqe, int result)
	Inform the executor of a submission completion with success. More...

static void	rtio_sqe_err (struct rtio r, const struct rtio_sqe sqe, int result)
	Inform the executor of a submissions completion with error. More...

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

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

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. More...

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. More...

int	rtio_submit (struct rtio *r, uint32_t wait_count)
	Submit I/O requests to the underlying executor. More...

Detailed Description

RTIO API.

Macro Definition Documentation

◆ RTIO_CQ_DEFINE

#define RTIO_CQ_DEFINE	(	name,
		len
	)	RTIO_SPSC_DEFINE(name, struct rtio_cqe, len)

#include <include/zephyr/rtio/rtio.h>

Statically define and initialize a fixed length completion queue.

Parameters

name	Name of the completion queue.
len	Queue length, power of 2 required (2, 4, 8).

◆ RTIO_DEFINE

#define RTIO_DEFINE	(	name,
		exec,
		sq_sz,
		cq_sz
	)

#include <include/zephyr/rtio/rtio.h>

Value:

        IF_ENABLED(CONFIG_RTIO_SUBMIT_SEM,                                                         \
                   (static K_SEM_DEFINE(_submit_sem_##name, 0, K_SEM_MAX_LIMIT)))                  \
        IF_ENABLED(CONFIG_RTIO_CONSUME_SEM,                                                        \
                   (static K_SEM_DEFINE(_consume_sem_##name, 0, 1)))                               \
        static RTIO_SQ_DEFINE(_sq_##name, sq_sz);                                                  \
        static RTIO_CQ_DEFINE(_cq_##name, cq_sz);                                                  \
        STRUCT_SECTION_ITERABLE(rtio, name) = {                                                    \
                .executor = (exec),                                                                \
                .xcqcnt = ATOMIC_INIT(0),                                                          \
                IF_ENABLED(CONFIG_RTIO_SUBMIT_SEM, (.submit_sem = &_submit_sem_##name,))           \
                IF_ENABLED(CONFIG_RTIO_SUBMIT_SEM, (.submit_count = 0,))                           \
                IF_ENABLED(CONFIG_RTIO_CONSUME_SEM, (.consume_sem = &_consume_sem_##name,))        \
                .sq = (struct rtio_sq *const)&_sq_##name,                                          \
                .cq = (struct rtio_cq *const)&_cq_##name,                                          \
        };

Statically define and initialize an RTIO context.

Parameters

name	Name of the RTIO
exec	Symbol for rtio_executor (pointer)
sq_sz	Size of the submission queue, must be power of 2
cq_sz	Size of the completion queue, must be power of 2

◆ RTIO_IODEV_DEFINE

#define RTIO_IODEV_DEFINE	(	name,
		iodev_api,
		qsize,
		iodev_data
	)

#include <include/zephyr/rtio/rtio.h>

Value:

        static RTIO_IODEV_SQ_DEFINE(_iodev_sq_##name, qsize);                                      \
        const STRUCT_SECTION_ITERABLE(rtio_iodev, name) = {                                        \
                .api = (iodev_api),                                                                \
                .iodev_sq = (struct rtio_iodev_sq *const)&_iodev_sq_##name,                        \
                .data = (iodev_data),                                                              \
        }

Statically define and initialize an RTIO IODev.

Parameters

name	Name of the iodev
iodev_api	Pointer to struct rtio_iodev_api
qsize	Size of the submission queue, must be power of 2
iodev_data	Data pointer

◆ RTIO_IODEV_SQ_DEFINE

#define RTIO_IODEV_SQ_DEFINE	(	name,
		len
	)	RTIO_SPSC_DEFINE(name, struct rtio_iodev_sqe, len)

#include <include/zephyr/rtio/rtio.h>

Statically define and initialize a fixed length iodev submission queue.

Parameters

name	Name of the queue.
len	Queue length, power of 2 required

◆ RTIO_OP_NOP

#define RTIO_OP_NOP 0

#include <include/zephyr/rtio/rtio.h>

An operation that does nothing and will complete immediately

◆ RTIO_OP_RX

#define RTIO_OP_RX 1

#include <include/zephyr/rtio/rtio.h>

An operation that receives (reads)

◆ RTIO_OP_TX

#define RTIO_OP_TX 2

#include <include/zephyr/rtio/rtio.h>

An operation that transmits (writes)

◆ RTIO_SQ_DEFINE

#define RTIO_SQ_DEFINE	(	name,
		len
	)	RTIO_SPSC_DEFINE(name, struct rtio_sqe, len)

#include <include/zephyr/rtio/rtio.h>

Statically define and initialize a fixed length submission queue.

Parameters

name	Name of the submission queue.
len	Queue length, power of 2 required (2, 4, 8).

Function Documentation

◆ rtio_access_grant()

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

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Grant access to an RTIO context to a user thread

◆ rtio_cqe_consume()

static struct rtio_cqe * rtio_cqe_consume ( struct rtio * r )

inlinestatic

#include <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 <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 <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_release_all()

static void rtio_cqe_release_all ( struct rtio * r )

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Release all consumed completion queue events.

Parameters

r	RTIO context

◆ rtio_cqe_submit()

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

inlinestatic

#include <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

◆ rtio_iodev_submit()

static void rtio_iodev_submit	(	const struct rtio_sqe *	sqe,
		struct rtio *	r
	)

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Perform a submitted operation with an iodev.

Parameters

sqe	Submission to work on
r	RTIO context

◆ rtio_set_executor()

static void rtio_set_executor	(	struct rtio *	r,
		struct rtio_executor *	exc
	)

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Set the executor of the rtio context.

◆ rtio_sqe_acquirable()

static uint32_t rtio_sqe_acquirable ( struct rtio * r )

inlinestatic

#include <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 <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_copy_in()

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

#include <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_drop_all()

static void rtio_sqe_drop_all ( struct rtio * r )

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Drop all previously acquired sqe.

Parameters

r	RTIO context

◆ rtio_sqe_err()

static void rtio_sqe_err	(	struct rtio *	r,
		const struct rtio_sqe *	sqe,
		int	result
	)

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Inform the executor of a submissions completion with error.

This SHALL fail the remaining submissions in the chain.

Parameters

r	RTIO context
sqe	Submission that has failed
result	Result of the request

◆ rtio_sqe_ok()

static void rtio_sqe_ok	(	struct rtio *	r,
		const struct rtio_sqe *	sqe,
		int	result
	)

inlinestatic

#include <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

r	RTIO context
sqe	Submission that has succeeded
result	Result of the request

◆ rtio_sqe_prep_nop()

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

inlinestatic

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

Prepare a read op submission.

◆ rtio_sqe_prep_write()

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
	)

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Prepare a write op submission.

◆ rtio_sqe_produce_all()

static void rtio_sqe_produce_all ( struct rtio * r )

inlinestatic

#include <include/zephyr/rtio/rtio.h>

Produce all previously acquired sqe.

Parameters

r	RTIO context

◆ rtio_submit()

int rtio_submit	(	struct rtio *	r,
		uint32_t	wait_count
	)

#include <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

Modules

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RTIO_CQ_DEFINE

◆ RTIO_DEFINE

◆ RTIO_IODEV_DEFINE

◆ RTIO_IODEV_SQ_DEFINE

◆ RTIO_OP_NOP

◆ RTIO_OP_RX

◆ RTIO_OP_TX

◆ RTIO_SQ_DEFINE

Function Documentation

◆ rtio_access_grant()

◆ rtio_cqe_consume()

◆ rtio_cqe_consume_block()

◆ rtio_cqe_copy_out()

◆ rtio_cqe_release_all()

◆ rtio_cqe_submit()

◆ rtio_iodev_submit()

◆ rtio_set_executor()

◆ rtio_sqe_acquirable()

◆ rtio_sqe_acquire()

◆ rtio_sqe_copy_in()

◆ rtio_sqe_drop_all()

◆ rtio_sqe_err()

◆ rtio_sqe_ok()

◆ rtio_sqe_prep_nop()

◆ rtio_sqe_prep_read()

◆ rtio_sqe_prep_write()

◆ rtio_sqe_produce_all()

◆ rtio_submit()