rtio.h File Reference

Real-Time IO device API for moving bytes with low effort. More...

#include <zephyr/rtio/rtio_spsc.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <syscalls/rtio.h>

Go to the source code of this file.

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_PRIO_LOW   0U
	Low priority. More...
#define	RTIO_PRIO_NORM   127U
	Normal priority. More...
#define	RTIO_PRIO_HIGH   255U
	High priority. More...
#define	RTIO_SQE_CHAINED   BIT(0)
	The next request in the queue should wait on this one. More...
#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

Real-Time IO device API for moving bytes with low effort.

RTIO uses a SPSC lock-free queue pair to enable a DMA and ISR friendly I/O API.

I/O like operations are setup in a pre-allocated queue with a fixed number of submission requests. Each submission request takes the device to operate on and an operation. The rest is information needed to perform the operation such as a register or mmio address of the device, a source/destination buffers to read from or write to, and other pertinent information.

These operations may be chained in a such a way that only when the current operation is complete will the next be executed. If the current request fails all chained requests will also fail.

The completion of these requests are pushed into a fixed size completion queue which an application may actively poll for completions.

An executor (could use a dma controller!) takes the queues and determines how to perform each requested operation. By default there is a software executor which does all operations in software using software device APIs.