[PATCH liburing 0/3] improve sendzc man pages

[PATCH liburing 0/3] improve sendzc man pages

[Pavel Begunkov]

Add a note about failing zc requests with -EOPNOTSUPP and add a paragraph
about IORING_RECVSEND_FIXED_BUF.

Pavel Begunkov (3):
  io_uring_enter.2: add sendzc -EOPNOTSUPP note
  io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST
  io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF

 man/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 2 deletions(-)

-- 
2.38.0

[PATCH liburing 1/3] io_uring_enter.2: add sendzc -EOPNOTSUPP note

[Pavel Begunkov]

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_enter.2 | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 2ebc6e3..25fdc1e 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -1098,8 +1098,11 @@ Available since 5.19.
 Issue the zerocopy equivalent of a
 .BR send(2)
 system call. Similar to IORING_OP_SEND, but tries to avoid making intermediate
-copies of data. Zerocopy execution is not guaranteed and it may fall back to
-copying.
+copies of data. Zerocopy execution is not guaranteed and may fall back to
+copying. The request may also fail with
+.B -EOPNOTSUPP,
+for instance when a protocol doesn't support zerocopy in the first place, in
+which case users are recommended to use copying sends instead.
 
 The
 .I flags
-- 
2.38.0

[PATCH liburing 2/3] io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST

[Pavel Begunkov]

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_enter.2 | 85 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 25fdc1e..d98ae59 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -394,12 +394,46 @@ holds the flags associated with the system call. See also
 .BR sendmsg (2)
 for the general description of the related system call. Available since 5.3.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_RECVMSG
 Works just like IORING_OP_SENDMSG, except for
 .BR recvmsg(2)
 instead. See the description of IORING_OP_SENDMSG. Available since 5.3.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently empty and attempting to
+receive data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a receive of the data when the socket has data to be read.
+This initial receive attempt can be wasteful for the case where the socket
+is expected to be empty, setting this flag will bypass the initial receive
+attempt and go straight to arming poll. If poll does indicate that data is
+ready to be received, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_SEND
 Issue the equivalent of a
@@ -416,12 +450,46 @@ holds the flags associated with the system call. See also
 .BR send(2)
 for the general description of the related system call. Available since 5.6.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_RECV
 Works just like IORING_OP_SEND, except for
 .BR recv(2)
 instead. See the description of IORING_OP_SEND. Available since 5.6.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently empty and attempting to
+receive data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a receive of the data when the socket has data to be read.
+This initial receive attempt can be wasteful for the case where the socket
+is expected to be empty, setting this flag will bypass the initial receive
+attempt and go straight to arming poll. If poll does indicate that data is
+ready to be received, the operation will proceed.
+.EE
+.in
+.PP
+
 .TP
 .B IORING_OP_TIMEOUT
 This command will register a timeout operation. The
@@ -1150,6 +1218,23 @@ system call equivalent.
 
 Available since 6.0.
 
+This command also supports the following modifiers in
+.I ioprio:
+
+.PP
+.in +12
+.B IORING_RECVSEND_POLL_FIRST
+If set, io_uring will assume the socket is currently full and attempting to
+send data will be unsuccessful. For this case, io_uring will arm internal
+poll and trigger a send of the data when there is enough space available.
+This initial send attempt can be wasteful for the case where the socket
+is expected to be full, setting this flag will bypass the initial send
+attempt and go straight to arming poll. If poll does indicate that data can
+be sent, the operation will proceed.
+.EE
+.in
+.PP
+
 .PP
 The
 .I flags
-- 
2.38.0

[PATCH liburing 3/3] io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF

[Pavel Begunkov]

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_enter.2 | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index d98ae59..2a8705f 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -1231,6 +1231,12 @@ This initial send attempt can be wasteful for the case where the socket
 is expected to be full, setting this flag will bypass the initial send
 attempt and go straight to arming poll. If poll does indicate that data can
 be sent, the operation will proceed.
+
+.B IORING_RECVSEND_FIXED_BUF
+instructs to use a pre-mapped buffer. If set, the
+.I buf_index
+field should contain an index into an array of fixed buffers. See
+io_uring_register(2) for details on how to setup a context for fixed buffer I/O.
 .EE
 .in
 .PP
-- 
2.38.0

Re: [PATCH liburing 0/3] improve sendzc man pages

[Jens Axboe]

On 10/21/22 6:10 AM, Pavel Begunkov wrote:
> Add a note about failing zc requests with -EOPNOTSUPP and add a paragraph
> about IORING_RECVSEND_FIXED_BUF.
> 
> Pavel Begunkov (3):
>   io_uring_enter.2: add sendzc -EOPNOTSUPP note
>   io_uring_enter.2: document IORING_RECVSEND_POLL_FIRST
>   io_uring_enter.2: document IORING_RECVSEND_FIXED_BUF
> 
>  man/io_uring_enter.2 | 98 +++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 96 insertions(+), 2 deletions(-)

Applied with minor edits, thanks!

-- 
Jens Axboe