dankwiki

Io uring: Difference between revisions

← Older edit

Dank (talk | contribs)

2 user groups
11,305 edits
 
(8 intermediate revisions by the same user not shown)
Line 11: Line 11:


==Rings==
==Rings==
Central to every uring are two ringbuffers holding CQEs (Completion Queue Entries) and SQE (Submission Queue Entries) descriptors (as best I can tell, this terminology was borrowed from the [https://nvmexpress.org/specifications/ NVMe specification]; I've also seen it with Mellanox NICs). Note that SQEs are allocated externally to the SQ descriptor ring (the same is not true for CQEs). SQEs roughly correspond to a single system call: they are tagged with an operation type, and filled in with the values that would traditionally be supplied as arguments to the appropriate function. Userspace is provided references to SQEs on the SQE ring, which it fills in and submits. Submission operates up through a specified SQE, and thus all SQEs before it in the ring must also be ready to go (this is likely the main reason why the SQ holds descriptors to an external ring of SQEs: you can acquire SQEs, and then submit them out of order). The kernel places results in the CQE ring. These rings are shared between kernel- and userspace. The rings must be distinct unless the kernel specifies the <tt>IORING_FEAT_SINGLE_MMAP</tt> feature (see below).
Central to every uring are two ringbuffers holding CQEs (Completion Queue Entries) and SQE (Submission Queue Entries) descriptors (as best I can tell, this terminology was borrowed from the [https://nvmexpress.org/specifications/ NVMe specification]; I've also seen it with Mellanox NICs). Note that SQEs are allocated externally to the SQ descriptor ring (the same is not true for CQEs). SQEs roughly correspond to a single system call: they are tagged with an operation type, and filled in with the values that would traditionally be supplied as arguments to the appropriate function. Userspace is provided references to SQEs on the SQE ring, which it fills in and submits. Submission operates up through a specified SQE, and thus all SQEs before it in the ring must also be ready to go (this is likely the main reason why the SQ holds descriptors to an external ring of SQEs: you can acquire SQEs, and then submit them out of order, but see <tt>IORING_SETUP_NO_SQARRAY</tt>). The kernel places results in the CQE ring. These rings are shared between kernel- and userspace. The rings must be distinct unless the kernel specifies the <tt>IORING_FEAT_SINGLE_MMAP</tt> feature (see below).


uring does not generally make use of <tt>errno</tt>. Synchronous functions return the negative error code as their result. Completion queue entries have the negated error code placed in their <tt>res</tt> fields.
uring does not generally make use of <tt>errno</tt>. Synchronous functions return the negative error code as their result. Completion queue entries have the negated error code placed in their <tt>res</tt> fields.
Line 57: Line 57:
|-
|-
| <tt>IORING_ENTER_REGISTERED_RING</tt> || <tt>ring_fd</tt> is an offset into the registered ring pool rather than a normal file descriptor.
| <tt>IORING_ENTER_REGISTERED_RING</tt> || <tt>ring_fd</tt> is an offset into the registered ring pool rather than a normal file descriptor.
|-
| <tt>IORING_ENTER_ABS_TIMER</tt> || (Since Linux 6.12) The timeout argument in the <tt>io_uring_getevents_arg</tt> is an absolute time, using the registered clock.
|-
|-
|}
|}
Line 219: Line 221:
|-
|-
| IORING_SETUP_REGISTERED_FD_ONLY || 6.6 || Registers the ring fd for use with <tt>IORING_REGISTER_USE_REGISTERED_RING</tt>. Returns a registered fd index.
| IORING_SETUP_REGISTERED_FD_ONLY || 6.6 || Registers the ring fd for use with <tt>IORING_REGISTER_USE_REGISTERED_RING</tt>. Returns a registered fd index.
|-
| IORING_SETUP_NO_SQARRAY || 6.6 || Do not use an indirection array for the submission queue, instead submitting them strictly in order.
|-
|-
|}
|}
Line 260: Line 264:
|-
|-
| <tt>IORING_FEAT_REG_REG_RING</tt> || 6.3 || Ring descriptors can be registered with <tt>IORING_REGISTER_USE_REGISTERED_RING</tt>.
| <tt>IORING_FEAT_REG_REG_RING</tt> || 6.3 || Ring descriptors can be registered with <tt>IORING_REGISTER_USE_REGISTERED_RING</tt>.
|-
| <tt>IORING_FEAT_RECVSEND_BUNDLE</tt> || 6.10 || <tt>send</tt> and <tt>recv</tt> operations can be bundled.
|-
| <tt>IORING_FEAT_MIN_TIMEOUT</tt> || 6.12 || A minimum batch wait timeout is supported.
|-
|-
|}
|}
Line 419: Line 427:
|-
|-
| <tt>IORING_RECV_MULTISHOT</tt> ||
| <tt>IORING_RECV_MULTISHOT</tt> ||
|-
| <tt>IORING_SEND_MULTISHOT</tt> || Introduced in 6.8.
|-
|-
| <tt>IORING_ACCEPT_MULTISHOT</tt> ||
| <tt>IORING_ACCEPT_MULTISHOT</tt> ||
Line 730: Line 740:
|-
|-
| <tt>IORING_CQE_F_NOTIF</tt> || Notification CQE for zero-copy sends
| <tt>IORING_CQE_F_NOTIF</tt> || Notification CQE for zero-copy sends
|-
| <tt>IORING_CQE_F_BUF_MORE</tt> || There will be more CQEs to the specified registered buffer
|-
|-
|}
|}
Line 843: Line 855:
** "[https://lwn.net/Articles/863071/ Discriptorless files for io_uring]" 2021-07-19
** "[https://lwn.net/Articles/863071/ Discriptorless files for io_uring]" 2021-07-19
** "[https://lwn.net/Articles/879724/ Zero-copy network transmission with io_uring]" 2021-12-30
** "[https://lwn.net/Articles/879724/ Zero-copy network transmission with io_uring]" 2021-12-30
** "[https://lwn.net/Articles/1002371/ Process creation in io_uring]" 2024-12-20


[[CATEGORY: Networking]]
[[CATEGORY: Networking]]
Retrieved from "https://nick-black.com/dankwiki/index.php?title=Io_uring"