polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_prep_writev2.3

@@ -4,24 +4,24 @@
 .\"
 .TH io_uring_prep_writev2 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_prep_writev2 - prepare vector I/O write request with flags
-
+io_uring_prep_writev2 \- prepare vector I/O write request with flags
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <sys/uio.h>
+.B #include <liburing.h>
 .PP
-.BI "void io_uring_prep_writev2(struct io_uring_sqe *sqe,"
-.BI "                           int fd,"
-.BI "                           const struct iovec *iovecs,"
-.BI "                           unsigned nr_vecs,"
-.BI "                           __u64 offset,"
-.BI "                           int flags)"
+.BI "void io_uring_prep_writev2(struct io_uring_sqe *" sqe ","
+.BI "                           int " fd ","
+.BI "                           const struct iovec *" iovecs ","
+.BI "                           unsigned " nr_vecs ","
+.BI "                           __u64 " offset ","
+.BI "                           int " flags ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_writev2() prepares a vectored IO write request. The
-submission queue entry
+The
+.BR io_uring_prep_writev2 (3)
+prepares a vectored IO write request. The submission queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -30,7 +30,7 @@ to start writing
 from the
 .I iovecs
 array at the specified
-.I offset.
+.IR offset .
 The behavior of the function can be controlled with the
 .I flags
 parameter.
@@ -58,21 +58,54 @@ per-IO O_APPEND
 
 .P
 On files that support seeking, if the offset is set to
-.B -1,
+.BR -1 ,
 the write operation commences at the file offset, and the file offset is
 incremented by the number of bytes written. See
 .BR write (2)
 for more details. Note that for an async API, reading and updating the
 current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
+to the file is serialized. It is not encouraged to use this feature if it's
 possible to provide the desired IO offset from the application or library.
 
-On files that are not capable of seeking, the offset is ignored.
+On files that are not capable of seeking, the offset must be 0 or -1.
 
 After the write has been prepared, it can be submitted with one of the submit
 functions.
 
 .SH RETURN VALUE
 None
+.SH ERRORS
+The CQE
+.I res
+field will contain the result of the operation. See the related man page for
+details on possible values. Note that where synchronous system calls will return
+.B -1
+on failure and set
+.I errno
+to the actual error value, io_uring never uses
+.IR errno .
+Instead it returns the negated
+.I errno
+directly in the CQE
+.I res
+field.
+.SH NOTES
+Unless an application explicitly needs to pass in more than iovec, it is more
+efficient to use
+.BR io_uring_prep_write (3)
+rather than this function, as no state has to be maintained for a
+non-vectored IO request.
+As with any request that passes in data in a struct, that data must remain
+valid until the request has been successfully submitted. It need not remain
+valid until completion. Once a request has been submitted, the in-kernel
+state is stable. Very early kernels (5.4 and earlier) required state to be
+stable until the completion occurred. Applications can test for this
+behavior by inspecting the
+.B IORING_FEAT_SUBMIT_STABLE
+flag passed back from
+.BR io_uring_queue_init_params (3).
 .SH SEE ALSO
-.BR io_uring_get_sqe (3), io_uring_prep_write (3), io_uring_prep_writev (3), io_uring_submit (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_prep_write (3),
+.BR io_uring_prep_writev (3),
+.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_queue_exit.3

@@ -5,14 +5,13 @@
 .\"
 .TH io_uring_queue_exit 3 "July 10, 2020" "liburing-0.7" "liburing Manual"
 .SH NAME
-io_uring_queue_exit - tear down io_uring submission and completion queues
+io_uring_queue_exit \- tear down io_uring submission and completion queues
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "void io_uring_queue_exit(struct io_uring * ring );"
+.BI "void io_uring_queue_exit(struct io_uring *" ring ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
 .BR io_uring_queue_exit (3)

data/vendor/liburing/man/io_uring_queue_init.3

@@ -5,40 +5,85 @@
 .\"
 .TH io_uring_queue_init 3 "July 10, 2020" "liburing-0.7" "liburing Manual"
 .SH NAME
-io_uring_queue_init - setup io_uring submission and completion queues
+io_uring_queue_init \- setup io_uring submission and completion queues
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_queue_init(unsigned " entries ", struct io_uring *" ring ,
-.BI "                        unsigned " flags );
-.fi
+.BI "int io_uring_queue_init(unsigned " entries ","
+.BI "                        struct io_uring *" ring ","
+.BI "                        unsigned " flags ");"
 .PP
+.BI "int io_uring_queue_init_params(unsigned " entries ","
+.BI "                               struct io_uring *" ring ","
+.BI "                               struct io_uring_params *" params ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_queue_init() function executes the io_uring_setup syscall to
-initialize the submission and completion queues in the kernel with at least
+The
+.BR io_uring_queue_init (3)
+function executes the
+.BR io_uring_setup (2)
+system call to initialize the submission and completion queues in the kernel
+with at least
 .I entries
-entries and then maps the resulting file descriptor to memory shared between the
-application and the kernel.
+entries in the submission queue and then maps the resulting file descriptor to
+memory shared between the application and the kernel.
 
-On success io_uring_queue_init() returns 0 and
+By default, the CQ ring will have twice the number of entries as specified by
+.I entries
+for the SQ ring. This is adequate for regular file or storage workloads, but
+may be too small networked workloads. The SQ ring entries do not impose a limit
+on the number of in-flight requests that the ring can support, it merely limits
+the number that can be submitted to the kernel in one go (batch). if the CQ
+ring overflows, e.g. more entries are generated than fits in the ring before the
+application can reap them, then the ring enters a CQ ring overflow state. This
+is indicated by
+.B IORING_SQ_CQ_OVERFLOW
+being set in the SQ ring flags. Unless the kernel runs out of available memory,
+entries are not dropped, but it is a much slower completion path and will slow
+down request processing. For that reason it should be avoided and the CQ
+ring sized appropriately for the workload. Setting
+.I cq_entries
+in
+.I struct io_uring_params
+will tell the kernel to allocate this many entries for the CQ ring, independent
+of the SQ ring size in given in
+.IR entries .
+If the value isn't a power of 2, it will be rounded up to the nearest power of
+2.
+
+On success,
+.BR io_uring_queue_init (3)
+returns 0 and
 .I ring
 will point to the shared memory containing the io_uring queues. On failure
--errno is returned.
+.BR -errno
+is returned.
 
 .I flags
-will be passed through to the io_uring_setup syscall (see 
+will be passed through to the io_uring_setup syscall (see
 .BR io_uring_setup (2)).
 
+If the
+.BR io_uring_queue_init_params (3)
+variant is used, then the parameters indicated by
+.I params
+will be passed straight through to the
+.BR io_uring_setup (2)
+system call.
+
 On success, the resources held by
 .I ring
 should be released via a corresponding call to
 .BR io_uring_queue_exit (3).
 .SH RETURN VALUE
 .BR io_uring_queue_init (3)
-returns 0 on success and -errno on failure.
+returns 0 on success and
+.BR -errno
+on failure.
 .SH SEE ALSO
 .BR io_uring_setup (2),
+.BR io_uring_register_ring_fd (3),
 .BR mmap (2),
 .BR io_uring_queue_exit (3)

data/vendor/liburing/man/io_uring_queue_init_params.3

@@ -0,0 +1 @@
+io_uring_queue_init.3

data/vendor/liburing/man/io_uring_recvmsg_cmsg_firsthdr.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_recvmsg_cmsg_nexthdr.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_recvmsg_name.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_recvmsg_out.3

@@ -0,0 +1,78 @@
+.\" Copyright (C), 2022  Dylan Yudaken <dylany@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_recvmsg_out 3 "Julyu 26, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_recvmsg_out - access data from multishot recvmsg
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "struct io_uring_recvmsg_out *io_uring_recvmsg_validate(void *" buf ","
+.BI "                                                       int " buf_len ","
+.BI "                                                       struct msghdr *" msgh ");"
+.PP
+.BI "void *io_uring_recvmsg_name(struct io_uring_recvmsg_out *" o ");"
+.PP
+.BI "struct cmsghdr *io_uring_recvmsg_cmsg_firsthdr(struct io_uring_recvmsg_out * " o ","
+.BI "                                                struct msghdr *" msgh ");"
+.BI "struct cmsghdr *io_uring_recvmsg_cmsg_nexthdr(struct io_uring_recvmsg_out * " o ","
+.BI "                                              struct msghdr *" msgh ","
+.BI "                                              struct cmsghdr *" cmsg ");"
+.PP
+.BI "void *io_uring_recvmsg_payload(struct io_uring_recvmsg_out * " o ","
+.BI "                               struct msghdr *" msgh ");"
+.BI "unsigned int io_uring_recvmsg_payload_length(struct io_uring_recvmsg_out *" o ","
+.BI "                                             int " buf_len ","
+.BI "                                             struct msghdr *" msgh ");"
+.PP
+.fi
+
+.SH DESCRIPTION
+
+These functions are used to access data in the payload delivered by
+.BR io_uring_prep_recv_multishot (3)
+.
+.PP
+.BR io_uring_recvmsg_validate (3)
+will validate a buffer delivered by
+.BR io_uring_prep_recv_multishot (3)
+and extract the
+.I io_uring_recvmsg_out
+if it is valid, returning a pointer to it or else NULL.
+.PP
+The structure is defined as follows:
+.PP
+.in +4n
+.EX
+
+struct io_uring_recvmsg_out {
+        __u32 namelen;    /* Name byte count as would have been populated
+                           * by recvmsg(2) */
+        __u32 controllen; /* Control byte count */
+        __u32 payloadlen; /* Payload byte count as would have been returned
+                           * by recvmsg(2) */
+        __u32 flags;      /* Flags result as would have been populated
+                           * by recvmsg(2) */
+};
+
+.IP * 3
+.BR io_uring_recvmsg_name (3)
+returns a pointer to the name in the buffer.
+.IP *
+.BR io_uring_recvmsg_cmsg_firsthdr (3)
+returns a pointer to the first cmsg in the buffer, or NULL.
+.IP *
+.BR io_uring_recvmsg_cmsg_nexthdr (3)
+returns a pointer to the next cmsg in the buffer, or NULL.
+.IP *
+.BR io_uring_recvmsg_payload (3)
+returns a pointer to the payload in the buffer.
+.IP *
+.BR io_uring_recvmsg_payload_length (3)
+Calculates the usable payload length in bytes.
+
+
+.SH "SEE ALSO"
+.BR io_uring_prep_recv_multishot (3)

data/vendor/liburing/man/io_uring_recvmsg_payload.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_recvmsg_payload_length.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_recvmsg_validate.3

@@ -0,0 +1 @@
+io_uring_recvmsg_out.3

data/vendor/liburing/man/io_uring_register.2

@@ -3,12 +3,12 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH IO_URING_REGISTER 2 2019-01-17 "Linux" "Linux Programmer's Manual"
+.TH io_uring_register 2 2019-01-17 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_uring_register \- register files or user buffers for asynchronous I/O 
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/io_uring.h>"
+.BR "#include <liburing.h>"
 .PP
 .BI "int io_uring_register(unsigned int " fd ", unsigned int " opcode ,
 .BI "                      void *" arg ", unsigned int " nr_args );
@@ -18,7 +18,7 @@ io_uring_register \- register files or user buffers for asynchronous I/O
 .PP
 
 The
-.BR io_uring_register ()
+.BR io_uring_register (2)
 system call registers resources (e.g. user buffers, files, eventfd,
 personality, restrictions) for use in an
 .BR io_uring (7)
@@ -85,7 +85,7 @@ region.
 An application can increase or decrease the size or number of
 registered buffers by first unregistering the existing buffers, and
 then issuing a new call to
-.BR io_uring_register ()
+.BR io_uring_register (2)
 with the new buffers.
 
 Note that before 5.13 registering buffers would wait for the ring to idle.
@@ -328,7 +328,13 @@ registered through this operation.
 .I arg
 must contain a pointer to the eventfd file descriptor, and
 .I nr_args
-must be 1. Available since 5.2.
+must be 1. Note that while io_uring generally takes care to avoid spurious
+events, they can occur. Similarly, batched completions of CQEs may only trigger
+a single eventfd notification even if multiple CQEs are posted. The application
+should make no assumptions on number of events being available having a direct
+correlation to eventfd notifications posted. An eventfd notification must thus
+only be treated as a hint to check the CQ ring for completions. Available since
+5.2.
 
 An application can temporarily disable notifications, coming through the
 registered eventfd, by setting the
@@ -422,7 +428,7 @@ array of
 entries.
 
 With an entry it is possible to allow an
-.BR io_uring_register ()
+.BR io_uring_register (2)
 .I opcode,
 or specify which
 .I opcode
@@ -434,7 +440,7 @@ or require certain
 to be specified (these flags must be set on each submission queue entry).
 
 All the restrictions must be submitted with a single
-.BR io_uring_register ()
+.BR io_uring_register (2)
 call and they are handled as an allowlist (opcodes and flags not registered,
 are not allowed).
 
@@ -540,7 +546,7 @@ for the system call. This flag tells the kernel that a registered descriptor
 is used rather than a real file descriptor.
 
 Each thread or process using a ring must register the file descriptor directly
-by issuing this request.o
+by issuing this request.
 
 The maximum number of supported registered ring descriptors is currently
 limited to
@@ -573,15 +579,149 @@ slot, making it available for future use.
 
 Available since 5.18.
 
+.TP
+.B IORING_REGISTER_PBUF_RING
+Registers a shared buffer ring to be used with provided buffers. This is a
+newer alternative to using
+.B IORING_OP_PROVIDE_BUFFERS
+which is more efficient, to be used with request types that support the
+.B IOSQE_BUFFER_SELECT
+flag.
+
+The
+.I arg
+argument must be filled in with the appropriate information. It looks as
+follows:
+.PP
+.in +12n
+.EX
+struct io_uring_buf_reg {
+    __u64 ring_addr;
+    __u32 ring_entries;
+    __u16 bgid;
+    __u16 pad;
+    __u64 resv[3];
+};
+.EE
+.in
+.PP
+.in +8n
+The
+.I ring_addr
+field must contain the address to the memory allocated to fit this ring.
+The memory must be page aligned and hence allocated appropriately using eg
+.BR posix_memalign (3)
+or similar. The size of the ring is the product of
+.I ring_entries
+and the size of
+.IR "struct io_uring_buf" .
+.I ring_entries
+is the desired size of the ring, and must be a power-of-2 in size. The maximum
+size allowed is 2^15 (32768).
+.I bgid
+is the buffer group ID associated with this ring. SQEs that select a buffer
+has a buffer group associated with them in their
+.I buf_group
+field, and the associated CQE will have
+.B IORING_CQE_F_BUFFER
+set in their
+.I flags
+member, which will also contain the specific ID of the buffer selected. The rest
+of the fields are reserved and must be cleared to zero.
+
+The
+.I flags
+argument is currently unused and must be set to zero.
+
+.i nr_args
+must be set to 1.
+
+Also see
+.BR io_uring_register_buf_ring (3)
+for more details. Available since 5.19.
+
+.TP
+.B IORING_UNREGISTER_PBUF_RING
+Unregister a previously registered provided buffer ring.
+.I arg
+must be set to the address of a struct io_uring_buf_reg, with just the
+.I bgid
+field set to the buffer group ID of the previously registered provided buffer
+group.
+.I nr_args
+must be set to 1. Also see
+.B IORING_REGISTER_PBUF_RING .
+
+Available since 5.19.
+
+.TP
+.B IORING_REGISTER_SYNC_CANCEL
+Performs a synchronous cancelation request, which works in a similar fashion to
+.B IORING_OP_ASYNC_CANCEL
+except it completes inline. This can be useful for scenarios where cancelations
+should happen synchronously, rather than needing to issue an SQE and wait for
+completion of that specific CQE.
+
+.I arg
+must be set to a pointer to a struct io_uring_sync_cancel_reg structure, with
+the details filled in for what request(s) to target for cancelation. See
+.BR io_uring_register_sync_cancel (3)
+for details on that. The return values are the same, except they are passed
+back synchronously rather than through the CQE
+.I res
+field.
+.I nr_args
+must be set to 1.
+
+Available since 6.0.
+
+.TP
+.B IORING_REGISTER_FILE_ALLOC_RANGE
+sets the allowable range for fixed file index allocations within the
+kernel. When requests that can instantiate a new fixed file are used with
+.B IORING_FILE_INDEX_ALLOC ,
+the application is asking the kernel to allocate a new fixed file descriptor
+rather than pass in a specific value for one. By default, the kernel will
+pick any available fixed file descriptor within the range available.
+This effectively allows the application to set aside a range just for dynamic
+allocations, with the remainder being used for specific values.
+
+.I nr_args
+must be set to 1 and
+.I arg
+must be set to a pointer to a struct io_uring_file_index_range:
+.PP
+.in +12n
+.EX
+struct io_uring_file_index_range {
+    __u32 off;
+    __u32 len;
+    __u64 resv;
+};
+.EE
+.in
+.PP
+.in +8n
+with
+.I off
+being set to the starting value for the range, and
+.I len
+being set to the number of descriptors. The reserved
+.I resv
+field must be cleared to zero.
+
+The application must have registered a file table first.
+
+Available since 6.0.
+
 .SH RETURN VALUE
 
 On success,
-.BR io_uring_register ()
-returns 0.  On error,
-.B -1
-is returned, and
+.BR io_uring_register (2)
+returns 0.  On error, a negative error code is returned. The caller should not
+rely on
 .I errno
-is set accordingly.
+variable.
 
 .SH ERRORS
 .TP

data/vendor/liburing/man/io_uring_register_buf_ring.3

@@ -0,0 +1,140 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_buf_ring \- register buffer ring for provided buffers
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_buf_ring(struct io_uring *" ring ",
+.BI "                               struct io_uring_buf_reg *" reg ",
+.BI "                               unsigned int " flags ");"
+.BI "
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_buf_ring (3)
+function registers a shared buffer ring to be used with provided buffers. For
+the request types that support it, provided buffers are given to the ring and
+one is selected by a request if it has
+.B IOSQE_BUFFER_SELECT
+set in the SQE
+.IR flags ,
+when the request is ready to receive data. This allows both clear ownership
+of the buffer lifetime, and a way to have more read/receive type of operations
+in flight than buffers available.
+
+The
+.I reg
+argument must be filled in with the appropriate information. It looks as
+follows:
+.PP
+.in +4n
+.EX
+struct io_uring_buf_reg {
+    __u64 ring_addr;
+    __u32 ring_entries;
+    __u16 bgid;
+    __u16 pad;
+    __u64 resv[3];
+};
+.EE
+.in
+.PP
+The
+.I ring_addr
+field must contain the address to the memory allocated to fit this ring.
+The memory must be page aligned and hence allocated appropriately using eg
+.BR posix_memalign (3)
+or similar. The size of the ring is the product of
+.I ring_entries
+and the size of
+.IR "struct io_uring_buf" .
+.I ring_entries
+is the desired size of the ring, and must be a power-of-2 in size. The maximum
+size allowed is 2^15 (32768).
+.I bgid
+is the buffer group ID associated with this ring. SQEs that select a buffer
+has a buffer group associated with them in their
+.I buf_group
+field, and the associated CQE will have
+.B IORING_CQE_F_BUFFER
+set in their
+.I flags
+member, which will also contain the specific ID of the buffer selected. The rest
+of the fields are reserved and must be cleared to zero.
+
+The
+.I flags
+argument is currently unused and must be set to zero.
+
+A shared buffer ring looks as follows:
+.PP
+.in +4n
+.EX
+struct io_uring_buf_ring {
+    union {
+	struct {
+            __u64 resv1;
+            __u32 resv2;
+            __u16 resv3;
+            __u16 tail;
+	};
+	struct io_uring_buf bufs[0];
+    };
+};
+.EE
+.in
+.PP
+where
+.I tail
+is the index at which the application can insert new buffers for consumption
+by requests, and
+.I struct io_uring_buf
+is buffer definition:
+.PP
+.in +4n
+.EX
+struct io_uring_buf {
+    __u64 addr;
+    __u32 len;
+    __u16 bid;
+    __u16 resv;
+};
+.EE
+.in
+.PP
+where
+.I addr
+is the address for the buffer,
+.I len
+is the length of the buffer in bytes, and
+.I bid
+is the buffer ID that will be returned in the CQE once consumed.
+
+Reserved fields must not be touched. Applications must use
+.BR io_uring_buf_ring_init (3)
+to initialise the buffer ring. Applications may use
+.BR io_uring_buf_ring_add (3)
+and
+.BR io_uring_buf_ring_advance (3)
+or
+.BR io_uring_buf_ring_advance (3)
+to provide buffers, which will set these fields and update the tail.
+
+Available since 5.19.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_buf_ring (3)
+returns 0. On failure it returns
+.BR -errno .
+.SH SEE ALSO
+.BR io_uring_buf_ring_init (3),
+.BR io_uring_buf_ring_add (3),
+.BR io_uring_buf_ring_advance (3),
+.BR io_uring_buf_ring_cq_advance (3)