polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_register_buffers.3

@@ -4,38 +4,58 @@
 .\"
 .TH io_uring_register_buffers 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_register_buffers - register buffers for fixed buffer operations
-.fi
+io_uring_register_buffers \- register buffers for fixed buffer operations
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_register_buffers(struct io_uring *ring,"
-.BI "                              const struct iovec *iovecs,
-.BI "                              unsigned nr_iovecs)"
+.BI "int io_uring_register_buffers(struct io_uring *" ring ",
+.BI "                              const struct iovec *" iovecs ",
+.BI "                              unsigned " nr_iovecs ");"
 .PP
+.BI "int io_uring_register_buffers_sparse(struct io_uring *" ring ",
+.BI "                              unsigned " nr_iovecs ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_register_buffers() function registers
+The
+.BR io_uring_register_buffers (3)
+function registers
 .I nr_iovecs
 number of buffers defined by the array
 .I iovecs
 belonging to the
-.I ring.
+.IR ring .
+
+The
+.BR io_uring_register_buffers_sparse (3)
+function registers
+.I nr_iovecs
+empty buffers belonging to the
+.IR ring .
+These buffers must be updated before use, using eg
+.BR io_uring_register_buffers_update_tag (3).
 
 After the caller has registered the buffers, they can be used with one of the
 fixed buffers functions.
 
 Registered buffers is an optimization that is useful in conjunction with
 .B O_DIRECT
-reads and writes, where maps the specified range into the kernel once when
-the buffer is registered, rather than doing a map and unmap for each IO
+reads and writes, where it maps the specified range into the kernel once when
+the buffer is registered rather than doing a map and unmap for each IO
 every time IO is performed to that region. Additionally, it also avoids
 manipulating the page reference counts for each IO.
 
 .SH RETURN VALUE
 On success
 .BR io_uring_register_buffers (3)
-returns 0. On failure it returns -errno.
+and
+.BR io_uring_register_buffers_sparse (3)
+return 0. On failure they return
+.BR -errno .
 .SH SEE ALSO
-.BR io_uring_get_sqe (3), io_uring_unregister_buffers (3), io_uring_prep_read_fixed (3), io_uring_prep_write_fixed (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_unregister_buffers (3),
+.BR io_uring_register_buf_ring (3),
+.BR io_uring_prep_read_fixed (3),
+.BR io_uring_prep_write_fixed (3)

data/vendor/liburing/man/io_uring_register_eventfd.3

@@ -0,0 +1,51 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_eventfd 3 "April 16, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_eventfd \- register an eventfd with a ring
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_eventfd(struct io_uring *" ring ","
+.BI "                              int " fd ");"
+.PP
+.BI "int io_uring_register_eventfd_async(struct io_uring *" ring ","
+.BI "                                    int " fd ");"
+.PP
+.BI "int io_uring_unregister_eventfd(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+.BR io_uring_register_eventfd (3)
+registers the eventfd file descriptor
+.I fd
+with the ring identified by
+.IR ring .
+
+Whenever completions are posted to the CQ ring, an eventfd notification
+is generated with the registered eventfd descriptor. If
+.BR io_uring_register_eventfd_async (3)
+is used, only events that completed out-of-line will trigger a notification.
+
+It notifications are no longer desired,
+.BR io_uring_unregister_eventfd (3)
+may be called to remove the eventfd registration. No eventfd argument is
+needed, as a ring can only have a single eventfd registered.
+
+.SH NOTES
+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.
+.SH RETURN VALUE
+Returns 0 on success, or
+or
+.BR -errno
+on error.
+.SH SEE ALSO
+.BR eventfd (2)

data/vendor/liburing/man/io_uring_register_eventfd_async.3

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

data/vendor/liburing/man/io_uring_register_file_alloc_range.3

@@ -0,0 +1,52 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_file_alloc_range 3 "Oct 21, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_register_file_alloc_range \- set range for fixed file allocations
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_file_alloc_range(struct io_uring *" ring ",
+.BI "                                       unsigned " off ","
+.BI "                                       unsigned " len ");"
+.BI "
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_file_alloc_range (3)
+function 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. Calling
+this function with
+.I off
+set to the starting offset and
+.I len
+set to the number of descriptors, the application can limit the allocated
+descriptors to that particular range. This effectively allows the application
+to set aside a range just for dynamic allocations, with the remainder being
+used for specific values.
+
+The application must have registered a fixed file table upfront, eg through
+.BR io_uring_register_files (3)
+or
+.BR io_uring_register_files_sparse (3) .
+
+Available since 6.0.
+
+.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_register_files (3)
+.BR io_uring_prep_accept_direct (3)
+.BR io_uring_prep_openat_direct (3)
+.BR io_uring_prep_socket_direct (3)

data/vendor/liburing/man/io_uring_register_files.3

@@ -4,19 +4,23 @@
 .\"
 .TH io_uring_register_files 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_register_files - register file descriptors
-.fi
+io_uring_register_files \- register file descriptors
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_register_files(struct io_uring *ring,"
-.BI "                            const int *files,"
-.BI "                            unsigned nr_files)"
+.BI "int io_uring_register_files(struct io_uring *" ring ","
+.BI "                            const int *" files ","
+.BI "                            unsigned " nr_files ");"
 .PP
+.BI "int io_uring_register_files_sparse(struct io_uring *" ring ","
+.BI "                            unsigned " nr_files ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_register_files() function registers
+The
+.BR io_uring_register_files (3)
+function registers
 .I nr_files
 number of file descriptors defined by the array
 .I files
@@ -24,12 +28,30 @@ belonging to the
 .I ring
 for subsequent operations.
 
-After the caller has registered the buffers, they can be used with the
-submission queue polling operations.
+The
+.BR io_uring_register_files_sparse (3)
+function registers an empty file table of
+.I nr_files
+number of file descriptors. The sparse variant is available in kernels 5.19
+and later.
+
+Registering a file table is a prerequisite for using any request that uses
+direct descriptors.
+
+Registered files have less overhead per operation than normal files. This
+is due to the kernel grabbing a reference count on a file when an operation
+begins, and dropping it when it's done. When the process file table is
+shared, for example if the process has ever created any threads, then this
+cost goes up even more. Using registered files reduces the overhead of
+file reference management across requests that operate on a file.
 
 .SH RETURN VALUE
 On success
 .BR io_uring_register_files (3)
-returns 0. On failure it returns -errno.
+and
+.BR io_uring_register_files_sparse (3)
+return 0. On failure they return
+.BR -errno .
 .SH SEE ALSO
-.BR io_uring_get_sqe (3), io_uring_unregister_files (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_unregister_files (3)

data/vendor/liburing/man/io_uring_register_files_sparse.3

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

data/vendor/liburing/man/io_uring_register_iowq_aff.3

@@ -0,0 +1,61 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_iowq_aff 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_iowq_aff \- register async worker CPU affinities
+.SH SYNOPSIS
+.nf
+.B #include <sched.h>
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_iowq_aff(struct io_uring *" ring ","
+.BI "                               size_t " cpusz ","
+.BI "                               const cpu_set_t *" mask ");
+.PP
+.BI "void io_uring_unregister_iowq_aff(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_register_iowq_aff (3)
+function registers a set of CPU affinities to be used by the io_uring async
+workers. By default, io_uring async workers are allowed to run on any CPU in
+the system. If this function is called with
+.I ring
+set to the ring in question and
+.I mask
+set to a pointer to a
+.B cpu_set_t
+value and
+.I cpusz
+set to the size of the CPU set, then async workers will only be allowed to run
+on the CPUs specified in the mask. Existing workers may need to hit a schedule
+point before they are migrated.
+
+For unregistration,
+.BR io_uring_unregister_iowq_aff (3)
+may be called to restore CPU affinities to the default.
+
+.SH RETURN VALUE
+Returns
+.B 0
+on success, or any of the following values in case of error.
+.TP
+.B -EFAULT
+The kernel was unable to copy the memory pointer to by
+.I mask
+as it was invalid.
+.TP
+.B -ENOMEM
+The kernel was unable to allocate memory for the new CPU mask.
+.TP
+.B -EINVAL
+.I cpusz
+or
+.I mask
+was NULL/0, or any other value specified was invalid.
+.SH SEE ALSO
+.BR io_uring_queue_init (3),
+.BR io_uring_register (2)

data/vendor/liburing/man/io_uring_register_iowq_max_workers.3

@@ -0,0 +1,71 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_iowq_max_workers 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_iowq_max_workers \- modify the maximum allowed async workers
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_iowq_max_workers(struct io_uring *" ring ","
+.BI "                                       unsigned int *" values ");"
+.fi
+.SH DESCRIPTION
+.PP
+io_uring async workers are split into two types:
+.TP
+.B Bounded
+These workers have a bounded execution time. Examples of that are filesystem
+reads, which normally complete in a relatively short amount of time. In case
+of disk failures, they are still bounded by a timeout operation that will
+abort them if exceeded.
+.TP
+.B Unbounded
+Work items here may take an indefinite amount of time to complete. Examples
+include doing IO to sockets, pipes, or any other non-regular type of file.
+
+.PP
+By default, the amount of bounded IO workers is limited to how many SQ entries
+the ring was setup with, or 4 times the number of online CPUs in the system,
+whichever is smaller. Unbounded workers are only limited by the process task
+limit, as indicated by the rlimit
+.B RLIMIT_NPROC
+limit.
+
+This can be modified by calling
+.B io_uring_register_iowq_max_workers
+with
+.I ring
+set to the ring in question, and
+.I values
+pointing to an array of two values. The first element should contain the number
+of desired bounded workers, and the second element should contain the number
+of desired unbounded workers. These are both maximum values, io_uring will
+not maintain a high count of idle workers, they are reaped when they are not
+necessary anymore.
+
+If called with both values set to 0, the existing values are returned.
+
+.SH RETURN VALUE
+Returns
+.B 0
+on success, with
+.I values
+containing the previous values for the settings. On error, any of the following
+may be returned.
+.TP
+.B -EFAULT
+The kernel was unable to copy the memory pointer to by
+.I values
+as it was invalid.
+.TP
+.B -EINVAL
+.I values
+was
+.B NULL
+or the new values exceeded the maximum allowed value.
+.SH SEE ALSO
+.BR io_uring_queue_init (3),
+.BR io_uring_register (2)

data/vendor/liburing/man/io_uring_register_ring_fd.3

@@ -0,0 +1,49 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_ring_fd 3 "March 11, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_ring_fd \- register a ring file descriptor
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_ring_fd(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+.BR io_uring_register_ring_fd (3)
+registers the file descriptor of the ring.
+
+Whenever
+.BR io_uring_enter (2)
+is called to submit request or wait for completions, the kernel must grab a
+reference to the file descriptor. If the application using io_uring is threaded,
+the file table is marked as shared, and the reference grab and put of the file
+descriptor count is more expensive than it is for a non-threaded application.
+
+Similarly to how io_uring allows registration of files, this allow registration
+of the ring file descriptor itself. This reduces the overhead of the
+.BR io_uring_enter (2)
+system call.
+
+If an application using liburing is threaded, then an application should call
+this function to register the ring descriptor when a ring is set up. See NOTES
+for restrictions when a ring is shared.
+
+.SH NOTES
+When the ring descriptor is registered, it is stored internally in the
+.I struct io_uring
+structure. For applications that share a ring between threads, for example
+having one thread do submits and another reap events, then this optimization
+cannot be used as each thread may have a different index for the registered
+ring fd.
+.SH RETURN VALUE
+Returns 1 on success, indicating that one file descriptor was registered,
+or
+.BR -errno
+on error.
+.SH SEE ALSO
+.BR io_uring_unregister_ring_fd (3),
+.BR io_uring_register_files (3)

data/vendor/liburing/man/io_uring_register_sync_cancel.3

@@ -0,0 +1,71 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_sync_cancel 3 "September 21, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_register_sync_cancel \- issue a synchronous cancelation request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_sync_cancel(struct io_uring *" ring ",
+.BI "                                  struct io_uring_sync_cancel_reg *" reg ");
+.PP
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_sync_cancel (3)
+function performs a synchronous cancelation request based on the parameters
+specified in
+.I reg .
+
+The
+.I reg
+argument must be filled in with the appropriate information for the
+cancelation request. It looks as follows:
+.PP
+.in +4n
+.EX
+struct io_uring_sync_cancel_reg {
+    __u64 addr;
+    __s32 fd;
+    __u32 flags;
+    struct __kernel_timespec timeout;
+    __u64 pad[4];
+};
+.EE
+.in
+.PP
+
+The arguments largely mirror what the async prep functions support, see
+.BR io_uring_prep_cancel (3)
+for details. Similarly, the return value is the same. The exception is the
+.I timeout
+argument, which can be used to limit the time that the kernel will wait for
+cancelations to be successful. If the
+.I tv_sec
+and
+.I tv_nsec
+values are set to anything but
+.B -1UL ,
+then they indicate a relative timeout upon which cancelations should be
+completed by.
+
+The
+.I pad
+values must be zero filled.
+
+.SH RETURN VALUE
+See
+.BR io_uring_prep_cancel (3)
+for details on the return value. If
+.I timeout
+is set to indicate a timeout, then
+.B -ETIME
+will be returned if exceeded. If an unknown value is set in the request,
+or if the pad values are not cleared to zero, then
+.I -EINVAL
+is returned.
+.SH SEE ALSO
+.BR io_uring_prep_cancel (3)