User-side I/O Ring Interface

Programmable submission/completion interface. More...

Collaboration diagram for User-side I/O Ring Interface:

Detailed Description

Programmable submission/completion interface.

The ring interface acts as the interface for all asynchronous operations in the kernel.

See also

I/O Subsystem for more information about the I/O ring system.

Data Structures
struct	ioring_t
	User I/O ring structure. More...

Typedefs
typedef uint64_t	ioring_id_t
	I/O ring ID type.

Functions
ioring_id_t	ioring_setup (ioring_t *ring, void *address, size_t sentries, size_t centries)
	System call to initialize the I/O ring.
uint64_t	ioring_teardown (ioring_id_t id)
	System call to deinitialize the I/O ring.
uint64_t	ioring_enter (ioring_id_t id, size_t amount, size_t wait)
	System call to notify the kernel of new submission queue entries (SQEs).
static bool	sqe_push (ioring_t *ring, sqe_t *sqe)
	Pushes a submission queue entry (SQE) to the submission queue.
static bool	cqe_pop (ioring_t *ring, cqe_t *cqe)
	Pops a completion queue entry (CQE) from the completion queue.

Typedef Documentation

ioring_id_t

typedef uint64_t ioring_id_t

I/O ring ID type.

Definition at line 195 of file ioring.h.

Function Documentation

ioring_setup()

ioring_id_t ioring_setup	(	ioring_t *	ring,
		void *	address,
		size_t	sentries,
		size_t	centries
	)

System call to initialize the I/O ring.

This system call will populate the given structure with the necessary pointers and metadata for the submission and completion ring.

Parameters

ring	Pointer to the ring structure to populate.
address	Desired address to allocate the ring, or NULL to let the kernel choose.
sentries	Number of entires to allocate for the submission queue, must be a power of two.
centries	Number of entries to allocate for the completion queue, must be a power of two.

Returns

On success, the ID of the new I/O ring. On failure, ERR and errno is set.

Definition at line 5 of file ioring_setup.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ioring_teardown()

uint64_t ioring_teardown

(

ioring_id_t

id

)

System call to deinitialize the I/O ring.

Parameters

id	The ID of the I/O ring to teardown.

Returns

On success, 0. On failure, ERR and errno is set.

Definition at line 5 of file ioring_teardown.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ioring_enter()

uint64_t ioring_enter	(	ioring_id_t	id,
		size_t	amount,
		size_t	wait
	)

System call to notify the kernel of new submission queue entries (SQEs).

Parameters

id	The ID of the I/O ring to notify.
amount	The number of SQEs that the kernel should process.
wait	The minimum number of completion queue entries (CQEs) to wait for.

Returns

On success, the number of SQEs successfully processed. On failure, ERR and errno is set.

Definition at line 5 of file ioring_enter.c.

Here is the call graph for this function:

Here is the caller graph for this function:

sqe_push()

static bool sqe_push ( ioring_t *  ring, sqe_t *  sqe  )

inlinestatic

Pushes a submission queue entry (SQE) to the submission queue.

After pushing SQEs, enter() must be called to notify the kernel of the new entries.

Parameters

ring	Pointer to the I/O ring structure.
sqe	Pointer to the SQE to push.

Returns

true if the SQE was pushed, false if the submission queue is full.

Definition at line 256 of file ioring.h.

Here is the caller graph for this function:

cqe_pop()

static bool cqe_pop ( ioring_t *  ring, cqe_t *  cqe  )

inlinestatic

Pops a completion queue entry (CQE) from the completion queue.

Parameters

ring	Pointer to the I/O ring structure.
cqe	Pointer to the CQE to pop.

Returns

true if a CQE was popped, false if the completion queue is empty.

Definition at line 279 of file ioring.h.

Here is the caller graph for this function: