vendor/liburing/man/io_uring.7 in polyphony-0.94 vs vendor/liburing/man/io_uring.7 in polyphony-0.95

@@ -1,10 +1,10 @@
 .\" Copyright (C) 2020 Shuveb Hussain <[e-mail]>
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
 
-.TH IO_URING 7 2020-07-26 "Linux" "Linux Programmer's Manual"
+.TH io_uring 7 2020-07-26 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_uring \- Asynchronous I/O facility
 .SH SYNOPSIS
 .nf
 .B "#include <linux/io_uring.h>"
@@ -275,11 +275,12 @@
 .BR io_uring ,
 you need to acquire a submission queue entry (SQE) from the submission
 queue (SQ),
 fill it up with details of the operation you want to submit and call 
 .BR io_uring_enter (2). 
-If you want to avoid calling 
+There are helper functions of the form io_uring_prep_X to enable proper
+setup of the SQE. If you want to avoid calling
 .BR io_uring_enter (2),
 you have the option of setting up Submission Queue Polling.
 .PP
 SQEs are added to the tail of the submission queue.
 The kernel picks up SQEs off the head of the SQ.
@@ -402,14 +403,40 @@
 this field can be used to correlate a submission with a completion.
 .I res
 is the result from the system call that was performed as part of the
 submission;
 its return value.
+
 The
 .I flags
-field could carry request-specific metadata in the future,
-but is currently unused.
+field carries request-specific information. As of the 6.0 kernel, the following
+flags are defined:
+
+.TP
+.B IORING_CQE_F_BUFFER
+If set, the upper 16 bits of the flags field carries the buffer ID that was
+chosen for this request. The request must have been issued with
+.B IOSQE_BUFFER_SELECT
+set, and used with a request type that supports buffer selection. Additionally,
+buffers must have been provided upfront either via the
+.B IORING_OP_PROVIDE_BUFFERS
+or the
+.B IORING_REGISTER_PBUF_RING
+methods.
+.TP
+.B IORING_CQE_F_MORE
+If set, the application should expect more completions from the request. This
+is used for requests that can generate multiple completions, such as multi-shot
+requests, receive, or accept.
+.TP
+.B IORING_CQE_F_SOCK_NONEMPTY
+If set, upon receiving the data from the socket in the current request, the
+socket still had data left on completion of this request.
+.TP
+.B IORING_CQE_F_NOTIF
+Set for notification CQEs, as seen with the zero-copy networking send and
+receive support.
 .PP
 The general sequence to read completion events off the completion queue is
 as follows:
 .PP
 .in +4n
@@ -482,11 +509,11 @@
 by having the kernel poll and pick up your SQEs for processing as you add
 them to the submission queue. This avoids the
 .BR io_uring_enter (2)
 call you need to make to tell the kernel to pick SQEs up.
 For high-performance applications,
-this means even lesser system call overheads.
+this means even fewer system call overheads.
 .SH CONFORMING TO
 .B io_uring
 is Linux-specific.
 .SH EXAMPLES
 The following example uses
@@ -549,12 +576,12 @@
 }
 
 int io_uring_enter(int ring_fd, unsigned int to_submit,
                    unsigned int min_complete, unsigned int flags)
 {
-    return (int) syscall(__NR_io_uring_enter, ring_fd, to_submit, min_complete,
-                         flags, NULL, 0);
+    return (int) syscall(__NR_io_uring_enter, ring_fd, to_submit,
+    			 min_complete, flags, NULL, 0);
 }
 
 int app_setup_uring(void) {
     struct io_uring_params p;
     void *sq_ptr, *cq_ptr;
@@ -694,13 +721,13 @@
 
     /* Update the tail */
     io_uring_smp_store_release(sring_tail, tail);
 
     /*
-    * Tell the kernel we have submitted events with the io_uring_enter() system
-    * call. We also pass in the IOURING_ENTER_GETEVENTS flag which causes the
-    * io_uring_enter() call to wait until min_complete (the 3rd param) events
-    * complete.
+    * Tell the kernel we have submitted events with the io_uring_enter()
+    * system call. We also pass in the IOURING_ENTER_GETEVENTS flag which
+    * causes the io_uring_enter() call to wait until min_complete
+    * (the 3rd param) events complete.
     * */
     int ret =  io_uring_enter(ring_fd, 1,1,
                               IORING_ENTER_GETEVENTS);
     if(ret < 0) {
         perror("io_uring_enter");