Skip to contentSkip to conversation

liburing updates for 2.4

PATCH Applied Ammar Faizi 3 participants 8 messages Jan 12, 2023 io_uring

lore
Share & tools
lore
#0 lore raw

cover liburing updates for 2.4

From: Ammar Faizi <[email protected]>

Hi Jens,

I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.

Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice". Let's explain it there.

Additionally, this series also contains:

- Fix a typo: 's/is adjust/is adjusted/' and indentation in liburing.h.

- Add io_uring_prep_msg_ring_cqe_flags() to liburing-ffi.map. Commit 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function") adds a new inline function in liburing.h, but it doesn't update the liburing-ffi.map file. Update it.

- Note about --nolibc configure option deprecation in the CHANGELOG. Since commit bfb432f4cce5 ("configure: Always enable CONFIG_NOLIBC if the arch is supported"), the --nolibc configure option is deprecated and has no effect. Plus, building liburing on x86-64, x86, and aarch64 always enables CONFIG_NOLIBC. Note these changes in the CHANGELOG file.

---

Ammar Faizi (4):
liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function
CHANGELOG: Note about --nolibc configure option deprecation liburing.h: 's/is adjust/is adjusted/' and fix indentation man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

 CHANGELOG                  |  2 ++
 man/io_uring_prep_splice.3 | 38 ++++++++++++++++++++++++++++++++++++++
 src/include/liburing.h     |  4 ++--
 src/liburing-ffi.map       |  1 +
 4 files changed, 43 insertions(+), 2 deletions(-)

base-commit: 47679a9019e48bf4293a4f55adade9eae715f9e4

Signature · 1 line
Ammar Faizi
#1 lore raw

PATCH 1/4 liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function

From: Ammar Faizi <[email protected]>

Commit 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function") adds a new inline function in liburing.h, but it doesn't update the liburing-ffi.map file. Update it.

Cc Breno Leitao <[email protected]>
Cc Christian Mazakas <[email protected]>
Fixes 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function")
---
 src/liburing-ffi.map | 1 +
 1 file changed, 1 insertion(+)
src/liburing-ffi.map +1 -0
index 8dd4641..1a6df50 100644
@@ -164,6 +164,7 @@ LIBURING_2.4 {
 		io_uring_register_restrictions;
 		io_uring_prep_write;
 		io_uring_prep_recv;
+		io_uring_prep_msg_ring_cqe_flags;
 	local:
 		*;
 };
Signature · 1 line
Ammar Faizi
#2 lore raw

PATCH 2/4 CHANGELOG: Note about --nolibc configure option deprecation

In reply to Ammar Faizi

From: Ammar Faizi <[email protected]>

Since commit bfb432f4cce5 ("configure: Always enable CONFIG_NOLIBC if the arch is supported"), the --nolibc configure option is deprecated and has no effect. Plus, building liburing on x86-64, x86, and aarch64 always enables CONFIG_NOLIBC. Note these changes in the CHANGELOG file.

---
 CHANGELOG | 2 ++
 1 file changed, 2 insertions(+)
CHANGELOG +2 -0
index 93c500f..0722aae 100644
@@ -4,6 +4,8 @@ liburing-2.4 release
 - Add IO_URING_{MAJOR,MINOR,CHECK}_VERSION() macros.
 - FFI support (for non-C/C++ languages integration).
 - Add io_uring_prep_msg_ring_cqe_flags() function.
+- Deprecate --nolibc configure option.
+- CONFIG_NOLIBC is always enabled on x86-64, x86, and aarch64.
 
 liburing-2.3 release
 
Signature · 1 line
Ammar Faizi
#3 lore raw

PATCH 3/4 liburing.h: 's/is adjust/is adjusted/' and fix indentation

In reply to Ammar Faizi

From: Ammar Faizi <[email protected]>

- Fix a typo: 's/is adjust/is adjusted/'.

- Fix indentation.

---
 src/include/liburing.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
src/include/liburing.h +2 -2
index cc3677e..c7139ef 100644
@@ -388,8 +388,8 @@ IOURINGINLINE void io_uring_prep_rw(int op, struct io_uring_sqe *sqe, int fd,
  * @param off_in If fd_in refers to a pipe, off_in must be (int64_t) -1;
  *		 If fd_in does not refer to a pipe and off_in is (int64_t) -1,
  *		 then bytes are read from fd_in starting from the file offset
- *		 and it is adjust appropriately;
- *               If fd_in does not refer to a pipe and off_in is not
+ *		 and it is adjusted appropriately;
+ *		 If fd_in does not refer to a pipe and off_in is not
  *		 (int64_t) -1, then the  starting offset of fd_in will be
  *		 off_in.
  * @param off_out The description of off_in also applied to off_out.
Signature · 1 line
Ammar Faizi
#4 lore raw

PATCH 4/4 man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

In reply to Ammar Faizi

From: Ammar Faizi <[email protected]>

I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.

Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice".

Let's explain it there!

---

Stolen from liburing comment (with some modifications):

If fd_in refers to a pipe, off_in must be -1.

If fd_in does not refer to a pipe and off_in is -1, then bytes are read from fd_in starting from the file offset and it is adjusted appropriately.

If fd_in does not refer to a pipe and off_in is not -1, then the starting offset of fd_in will be off_in.

The same rules apply to fd_out and off_out.

Note that even if fd_in or fd_out refers to a pipe, the splice operation can still failed with EINVAL if one of the fd doesn't explicitly support splice operation, e.g. reading from terminal is unsupported from kernel 5.7 to 5.11.

 man/io_uring_prep_splice.3 | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
man/io_uring_prep_splice.3 +38 -0
index cb82ad0..a177bc6 100644
@@ -52,6 +52,34 @@ and
 .I fd_in
 given as a registered file descriptor offset.
 
+If
+.I fd_in
+refers to a pipe,
+.IR off_in
+must be -1.
+
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is -1, then bytes are read from
+.I fd_in
+starting from the file offset and it is adjusted appropriately.
+
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is not -1, then the starting offset of
+.I fd_in
+will be
+.IR off_in .
+
+The same rules apply to
+.I fd_out
+and
+.IR off_out .
+
 This function prepares an async
 .BR splice (2)
 request. See that man page for details.
@@ -78,3 +106,13 @@ field.
 .BR io_uring_submit (3),
 .BR io_uring_register (2),
 .BR splice (2)
+
+.SH NOTES
+Note that even if
+.I fd_in
+or
+.I fd_out
+refers to a pipe, the splice operation can still failed with
+.B EINVAL
+if one of the fd doesn't explicitly support splice operation, e.g. reading from
+terminal is unsupported from kernel 5.7 to 5.11.
Signature · 1 line
Ammar Faizi
#5 lore raw

Re: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

Quoted 7 lines · Ammar Faizi

From: Ammar Faizi <[email protected]>

I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.

Quoted 5 lines

Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice".

Let's explain it there!

Hi Ammar,

A few suggestions below:

man/io_uring_prep_splice.3 and · line 59

Quoted 11 lines
man/io_uring_prep_splice.3 +5 -0
@@ -52,6 +52,34 @@ and
 .I fd_in
 given as a registered file descriptor offset.
 
+If
+.I fd_in
+refers to a pipe,
+.IR off_in
+must be -1.

Maybe

"off_in is ignored and must be set to -1."

man/io_uring_prep_splice.3 and · line 65

Quoted 6 lines
man/io_uring_prep_splice.3 +6 -0
+
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is -1, then bytes are read from

bytes -> nbytes ?

man/io_uring_prep_splice.3 and · line 67

Quoted 2 lines
man/io_uring_prep_splice.3 +2 -0
+.I fd_in
+starting from the file offset and it is adjusted appropriately.

What do you think:

starting from the file offset, which is incremented by the number of bytes read.

Quoted 18 lines
man/io_uring_prep_splice.3 +14 -0
+If
+.I fd_in
+does not refer to a pipe and
+.I off_in
+is not -1, then the starting offset of
+.I fd_in
+will be
+.IR off_in .
+
+The same rules apply to
+.I fd_out
+and
+.IR off_out .
+
 This function prepares an async
 .BR splice (2)
 request. See that man page for details.

man/io_uring_prep_splice.3 field. · line 115

Quoted 10 lines
man/io_uring_prep_splice.3 +7 -0
@@ -78,3 +106,13 @@ field.
 .BR io_uring_submit (3),
 .BR io_uring_register (2),
 .BR splice (2)
+
+.SH NOTES
+Note that even if
+.I fd_in
+or
+.I fd_out
+refers to a pipe, the splice operation can still failed with

failed -> fail

Thanks,

Signature · 1 line
Gabriel Krisman Bertazi
maintainer
#6 lore raw

Re: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

Quoted 13 lines · Gabriel Krisman Bertazi
Quoted 11 lines · Ammar Faizi

From: Ammar Faizi <[email protected]>

I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.

Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice".

Quoted 5 lines
Quoted 1 line

Let's explain it there!

Hi Ammar,

A few suggestions below:

[snip]

Shoot, missed this. Ammar, can you send a fixup patch with the below suggestions?

Signature · 1 line
Jens Axboe
maintainer Applied
#7 lore raw
In reply to Ammar Faizi
Quoted 10 lines · Ammar Faizi

I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.

Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice". Let's explain it there.

[...]

Applied, thanks!

[1/4] liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function

      commit: 390b4f6a1314f8b1c51ced51c70b8646a51ad081
[2/4] CHANGELOG: Note about --nolibc configure option deprecation
      commit: 68c2a983819edae4e724b49b2e644767684eb103
[3/4] liburing.h: 's/is adjust/is adjusted/' and fix indentation
      commit: f63a594cbc58bb0f680e7d424f2d8f836142aa35
[4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
      commit: 55bbe5b71c7d39c9ea44e5abb886846010c67baa

Best regards,

Signature · 1 line
Jens Axboe