[PATCH liburing v2 0/3] Manpage updates for iowait toggle feature and one extra FFI fix

[PATCH liburing v2 0/3] Manpage updates for iowait toggle feature and one extra FFI fix

[Ammar Faizi]

[ 
  v2: Keep using IOURINGINLINE on __io_uring_buf_ring_cq_advance
      because it is in the FFI map file.

  Now, only remove `IOURINGINLINE` from these two private helpers:
    - __io_uring_set_target_fixed_file
    - __io_uring_peek_cqe

  I have verified these two functions are not in liburing-ffi.map.
  I will be more careful next time verifying the FFI map file.
]

Hi Jens,

As previously discussed on Discord, here are two manpage updates
about the iowait toggle feature. And then I have one extra FFI
trivial fix. The FFI fix is safe to apply for the liburing 2.12
release.

  - Add `io_uring_set_iowait(3)` manpage.

  - Add `IORING_ENTER_NO_IOWAIT` flag to `io_uring_enter(2)`

  - Don't use `IOURINGINLINE` on private helpers in `liburing.h`.

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>

Ammar Faizi (3):
  man: Add `io_uring_set_iowait(3)`
  man: Add `IORING_ENTER_NO_IOWAIT` flag
  liburing: Don't use `IOURINGINLINE` on private helpers

 man/io_uring_enter.2      | 16 ++++++++++-
 man/io_uring_set_iowait.3 | 57 +++++++++++++++++++++++++++++++++++++++
 src/include/liburing.h    |  4 +--
 3 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 man/io_uring_set_iowait.3


base-commit: 6d3d27bc42733f5a407424c76aadcc84bd4b0cf0
-- 
Ammar Faizi

[PATCH liburing v2 1/3] man: Add `io_uring_set_iowait(3)`

[Ammar Faizi]

Based on an explanation from the Linux kernel upstream commit:

  07754bfd9aee ("io_uring: enable toggle of iowait usage when waiting on CQEs")

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 man/io_uring_set_iowait.3 | 57 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 man/io_uring_set_iowait.3

diff --git a/man/io_uring_set_iowait.3 b/man/io_uring_set_iowait.3
new file mode 100644
index 000000000000..5caf0a3a4cc6
--- /dev/null
+++ b/man/io_uring_set_iowait.3
@@ -0,0 +1,57 @@
+.\" Copyright (C) 2025 Jens Axboe <axboe@kernel.dk>
+.\" Copyright (C) 2025 Ammar Faizi <ammarfaizi2@gnuweeb.org>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_set_iowait 3 "July 27, 2025" "liburing-2.12" "liburing Manual"
+.SH NAME
+io_uring_set_iowait \- toggle of iowait usage when waiting on CQEs
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_set_iowait(struct io_uring *" ring ",
+.BI "                        bool " enable_iowait ");"
+.fi
+.SH DESCRIPTION
+.PP
+By default, io_uring marks a waiting task as being in iowait if it's
+sleeping waiting on events and there are pending requests. This isn't
+necessarily always useful, and may be confusing on non-storage setups
+where iowait isn't expected. It can also cause extra power usage by
+preventing the CPU from entering lower sleep states.
+
+The
+.BR io_uring_set_iowait (3)
+function allows the user to toggle this behavior. If
+.BI enable_iowait
+is set to true, the iowait behavior is enabled. If it is set to false,
+the iowait behavior is disabled. The iowait behavior is enabled by
+default when a ring is created.
+
+If the iowait is disabled, the submit functions will set
+.B IORING_ENTER_NO_IOWAIT
+in the
+.BI flags
+argument to
+.BR io_uring_enter (2).
+
+If the kernel supports this feature, it will be marked by having
+the
+.B IORING_FEAT_NO_IOWAIT
+feature flag set.
+
+Available since kernel 6.15.
+
+
+.SH RETURN VALUE
+On success,
+.BR io_uring_set_iowait (3)
+returns 0. On failure, it returns
+.BR -EOPNOTSUPP .
+
+
+.SH SEE ALSO
+.BR io_uring_enter (2),
+.BR io_uring_submit (3),
+.BR io_uring_submit_and_wait (3)
-- 
Ammar Faizi

[PATCH liburing v2 2/3] man: Add `IORING_ENTER_NO_IOWAIT` flag

[Ammar Faizi]

Based on an explanation from the Linux kernel upstream commit:

  07754bfd9aee ("io_uring: enable toggle of iowait usage when waiting on CQEs")

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 man/io_uring_enter.2 | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 99c0ab222675..a054a7cdfbd4 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -134,7 +134,21 @@ but merely an offset into an area of wait regions previously registered with
 .BR io_uring_register (2)
 using the
 .B IORING_REGISTER_MEM_REGION
-operation. Available since 6.13
+operation.
+
+Available since 6.13
+
+.TP
+.B IORING_ENTER_NO_IOWAIT
+When this flag is set, the system call will not mark the waiting task as being
+in iowait if it is sleeping waiting on events and there are pending requests.
+This is useful if iowait isn't expected when waiting for events. It can also
+prevent extra power usage by allowing the CPU to enter lower sleep states.
+This flag is only available if the kernel supports the
+.B IORING_FEAT_NO_IOWAIT
+feature.
+
+Available since 6.15.
 
 .PP
 .PP
-- 
Ammar Faizi

[PATCH liburing v2 3/3] liburing: Don't use `IOURINGINLINE` on private helpers

[Ammar Faizi]

These functions:

  __io_uring_set_target_fixed_file
  __io_uring_peek_cqe

are not exported for FFI. Don't use `IOURINGINLINE` on them.

Cc: Christian Mazakas <christian.mazakas@gmail.com>
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 src/include/liburing.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/include/liburing.h b/src/include/liburing.h
index 83434f6eca65..e3f394eab860 100644
--- a/src/include/liburing.h
+++ b/src/include/liburing.h
@@ -522,7 +522,7 @@ IOURINGINLINE void io_uring_sqe_set_buf_group(struct io_uring_sqe *sqe,
 	sqe->buf_group = (__u16) bgid;
 }
 
-IOURINGINLINE void __io_uring_set_target_fixed_file(struct io_uring_sqe *sqe,
+static inline void __io_uring_set_target_fixed_file(struct io_uring_sqe *sqe,
 						    unsigned int file_index)
 	LIBURING_NOEXCEPT
 {
@@ -1742,7 +1742,7 @@ IOURINGINLINE int io_uring_wait_cqe_nr(struct io_uring *ring,
  * "official" versions of this, io_uring_peek_cqe(), io_uring_wait_cqe(),
  * or io_uring_wait_cqes*().
  */
-IOURINGINLINE int __io_uring_peek_cqe(struct io_uring *ring,
+static inline int __io_uring_peek_cqe(struct io_uring *ring,
 				      struct io_uring_cqe **cqe_ptr,
 				      unsigned *nr_available)
 	LIBURING_NOEXCEPT
-- 
Ammar Faizi

Re: [PATCH liburing v2 0/3] Manpage updates for iowait toggle feature and one extra FFI fix

[Ammar Faizi]

On Sun, Jul 27, 2025 at 8:02 AM Ammar Faizi wrote:
> [
>   v2: Keep using IOURINGINLINE on __io_uring_buf_ring_cq_advance
>       because it is in the FFI map file.
>
>   Now, only remove `IOURINGINLINE` from these two private helpers:
>     - __io_uring_set_target_fixed_file
>     - __io_uring_peek_cqe
>
>   I have verified these two functions are not in liburing-ffi.map.
>   I will be more careful next time verifying the FFI map file.
> ]
>
> Hi Jens,

Doh, I missed the To header in v2. Good that it's accessible via the
lore kernel.

-- 
Ammar Faizi

Re: [PATCH liburing v2 0/3] Manpage updates for iowait toggle feature and one extra FFI fix

[Jens Axboe]

On Sun, 27 Jul 2025 08:02:48 +0700, Ammar Faizi wrote:
> [
>   v2: Keep using IOURINGINLINE on __io_uring_buf_ring_cq_advance
>       because it is in the FFI map file.
> 
>   Now, only remove `IOURINGINLINE` from these two private helpers:
>     - __io_uring_set_target_fixed_file
>     - __io_uring_peek_cqe
> 
> [...]

Applied, thanks!

[1/3] man: Add `io_uring_set_iowait(3)`
      commit: 56116db9c371c6d2574709476ba697c0eee59284
[2/3] man: Add `IORING_ENTER_NO_IOWAIT` flag
      commit: 6ce9ab3f928a0959b6959b939c4a7ade652abee9
[3/3] liburing: Don't use `IOURINGINLINE` on private helpers
      commit: f2b6fb85b79baf17f2c0ea24a357c652caa2d7ba

Best regards,
-- 
Jens Axboe