[PATCH liburing v1 0/4] liburing updates for 2.4

[PATCH liburing v1 0/4] liburing updates for 2.4

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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.

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

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
-- 
Ammar Faizi

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

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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 <leitao@debian.org>
Cc: Christian Mazakas <christian.mazakas@gmail.com>
Fixes: 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function")
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 src/liburing-ffi.map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/liburing-ffi.map b/src/liburing-ffi.map
index 8dd4641..1a6df50 100644
--- a/src/liburing-ffi.map
+++ b/src/liburing-ffi.map
@@ -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:
 		*;
 };
-- 
Ammar Faizi

[PATCH liburing v1 2/4] CHANGELOG: Note about --nolibc configure option deprecation

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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.

Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 CHANGELOG | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG b/CHANGELOG
index 93c500f..0722aae 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -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
 
-- 
Ammar Faizi

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

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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

  - Fix indentation.

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 cc3677e..c7139ef 100644
--- a/src/include/liburing.h
+++ b/src/include/liburing.h
@@ -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.
-- 
Ammar Faizi

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

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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!

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

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(+)

diff --git a/man/io_uring_prep_splice.3 b/man/io_uring_prep_splice.3
index cb82ad0..a177bc6 100644
--- a/man/io_uring_prep_splice.3
+++ b/man/io_uring_prep_splice.3
@@ -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.
-- 
Ammar Faizi

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

[Gabriel Krisman Bertazi]

Ammar Faizi <ammarfaizi2@gnuweeb.org> writes:

> From: Ammar Faizi <ammarfaizi2@gnuweeb.org>
>
> 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!

Hi Ammar,

A few suggestions below:

> --- a/man/io_uring_prep_splice.3
> +++ b/man/io_uring_prep_splice.3
> @@ -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."

> +
> +If
> +.I fd_in
> +does not refer to a pipe and
> +.I off_in
> +is -1, then bytes are read from

bytes -> nbytes ?

> +.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.

> +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

failed -> fail

Thanks,

-- 
Gabriel Krisman Bertazi

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

[Jens Axboe]

On 1/12/23 10:26 AM, Gabriel Krisman Bertazi wrote:
> Ammar Faizi <ammarfaizi2@gnuweeb.org> writes:
> 
>> From: Ammar Faizi <ammarfaizi2@gnuweeb.org>
>>
>> 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!
> 
> Hi Ammar,
> 
> A few suggestions below:

[snip]

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

-- 
Jens Axboe

Re: [PATCH liburing v1 0/4] liburing updates for 2.4

[Jens Axboe]

On Thu, 12 Jan 2023 22:57:05 +0700, Ammar Faizi wrote:
> 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,
-- 
Jens Axboe