From 5c62768b9e16e875b1cf8a856bbc815ea7d75b8b Mon Sep 17 00:00:00 2001 From: Jens Axboe Date: Sat, 2 Nov 2024 15:12:39 -0600 Subject: [PATCH] man: document io_uring_setup_reg_wait() and io_uring_free_reg_wait() Signed-off-by: Jens Axboe --- man/io_uring_free_reg_wait.3 | 35 ++++++++++ man/io_uring_setup_reg_wait.3 | 120 ++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 man/io_uring_free_reg_wait.3 create mode 100644 man/io_uring_setup_reg_wait.3 diff --git a/man/io_uring_free_reg_wait.3 b/man/io_uring_free_reg_wait.3 new file mode 100644 index 000000000..3a6f9d1a8 --- /dev/null +++ b/man/io_uring_free_reg_wait.3 @@ -0,0 +1,35 @@ +.\" Copyright (C) 2024 Jens Axboe +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_free_reg_wait 3 "November 2, 2024" "liburing-2.9" "liburing Manual" +.SH NAME +io_uring_free_reg_wait \- Frees a previously registered wait region +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void io_uring_free_reg_wait(struct io_uring *" ring "," +.BI " unsigned " nentries ");" +.PP +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_free_reg_wait (3) +function frees a wait region for the ring +.IR ring +of +.IR nentries +previously setup with +.BR io_uring_setup_reg_wait (3) . +As registered wait regions persist for the life time of the ring, on the +kernel side the wait regions still remain active, and may in fact still +be used by the application for wait operations. They may just no longer +be modified by the application. + +Available since kernel 6.13. + +.SH SEE ALSO +.BR io_uring_submit_and_wait_reg (3), +.BR io_uring_free_reg_wait (3) diff --git a/man/io_uring_setup_reg_wait.3 b/man/io_uring_setup_reg_wait.3 new file mode 100644 index 000000000..ad2bb6c30 --- /dev/null +++ b/man/io_uring_setup_reg_wait.3 @@ -0,0 +1,120 @@ +.\" Copyright (C) 2024 Jens Axboe +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_setup_reg_wait 3 "November 2, 2024" "liburing-2.9" "liburing Manual" +.SH NAME +io_uring_setup_reg_wait \- Sets up and registers fixed wait regions +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "struct io_uring_reg_wait *io_uring_setup_reg_wait(struct io_uring *" ring "," +.BI " unsigned " nentries "," +.BI " int *"err ");" +.PP +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_setup_reg_wait (3) +function allocates and registers a fixed wait region of +.IR nentries +entries. Upon successful return, the function returns a non-NULL pointer. On +error, it returns +.B NULL +and fills in +.IR err +with the error value. + +A registered wait region is a contigious range of +.IR struct io_uring_reg_wait , +which look as follows: +.PP +.EX +struct io_uring_reg_wait { + struct __kernel_timespec ts; + __u32 min_wait_usec; + __u32 flags; + __u64 sigmask; + __u32 sigmask_sz; + __u32 pad[3]; + __u64 pad2[2]; +}; +.EE +where +.IR ts +is the wait related information for this wait, +.IR min_wait_usec +is the minimum wait period (for a two-stage wait), if set to non-zero, +.IR flags +tells the kernel about the wait region, +.IR sigmask +is a pointer to a signal mask, if used, and +.IR sigmask_sz +is the size of the signal mask, if used. + +Currently the only valid flag is +.B IORING_REG_WAIT_TS , +which, if set, indicates that the value in +.IR ts +is valid and should be used for the wait operation. + +A signal mask is used for the wait, if +.IR sigmask +is set to a valid, non-zero, pointer value. If used, +.IR sigmask_sz +must also be set. + +Each of the wait regions are indicated by the offset of the structure. The +first wait region is index +.B 0 , +the next is index +.B 1 , +and so forth, up to the registered number of regions set by +.IR nentries. + +The wait regions may be modified by an application at any time before calling +.BR io_uring_submit_and_reg_wait (3) . +If modified while a wait region for that given offset is currently in use +by the kernel, the results are undefined - the kernel may see the new value +in time to use it, or it may not. + +The main purpose of registered wait regions and the associated submit-and-wait +helpers is to reduce the overhead of a wait operation. A normal wait for +events with a timeout will pass in a +.IR struct io_uring_getevents_arg +which will need to be copied for each wait. For high frequency wait operations, +this adds noticeable overhead for each wait. With registered wait regions, +no such copying needs to take place for each wait. + +Once a wait region has been setup, it persists for the life time of the ring. +It's currently not possible to unregister or resize a wait region. +Additionally, a wait region may currently only use a single page of memory. +On a 4k page size system, this means an application is limited to +.B 64 +wait regions. That should be enough, as each wait index may be modified as +needed. With at least 64 indices available, hopefully applications can just +use the appropriately setup wait region for each specific type of wait, with +different indices having different wait settings. + +While a region cannot get unregistered from the kernel, once a ring has been +closed, the application may free the associated memory by calling +.BR io_uring_free_reg_wait (3) . +An application may also do this before closing a ring, but then wait regions +may no longer be modified by the application. + +Available since kernel 6.13. + +On success +.BR io_uring_register_reg_wait (3) +returns a pointer to the start of the wait regions. On failure, it returns +.B NULL +and sets +.IR err +to the appropriate +.BR -errno +value. +.SH SEE ALSO +.BR io_uring_submit_and_wait_reg (3), +.BR io_uring_free_reg_wait (3)