polyphony 1.0 → 1.0.2

data/vendor/liburing/man/io_uring_register_buf_ring.3

@@ -1,140 +0,0 @@
-.\" 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
-have a buffer group associated with them in their
-.I buf_group
-field, and the associated CQEs 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 before use. Applications may use
-.BR io_uring_buf_ring_add (3)
-and
-.BR io_uring_buf_ring_advance (3)
-or
-.BR io_uring_buf_ring_cq_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)

data/vendor/liburing/man/io_uring_register_buffers.3

@@ -1,104 +0,0 @@
-.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.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
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.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_tags(struct io_uring *" ring ","
-.BI "                                   const struct iovec *" iovecs ","
-.BI "                                   const __u64 *" tags ","
-.BI "                                   unsigned " nr ");"
-.PP
-.BI "int io_uring_register_buffers_sparse(struct io_uring *" ring ","
-.BI "                                     unsigned " nr_iovecs ");"
-.PP
-.BI "int io_uring_register_buffers_update_tag(struct io_uring *" ring ","
-.BI "                                         unsigned " off ","
-.BI "                                         const struct iovec *" iovecs ","
-.BI "                                         const __u64 *" tags ","
-.BI "                                         unsigned " nr ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_register_buffers (3)
-function registers
-.I nr_iovecs
-number of buffers defined by the array
-.I iovecs
-belonging to the
-.IR ring .
-
-The
-.BR io_uring_register_buffers_tags (3)
-function behaves the same as
-.BR io_uring_register_buffers (3)
-function but additionally takes
-.I tags
-parameter. See
-.B IORING_REGISTER_BUFFERS2
-for the resource tagging description.
-
-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 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.
-
-The
-.BR io_uring_register_buffers_update_tag (3)
-function updates registered buffers with new ones, either turning a sparse
-entry into a real one, or replacing an existing entry. The
-.I off
-is offset on which to start the update
-.I nr
-number of buffers defined by the array
-.I iovecs
-belonging to the
-.IR ring .
-The
-.I tags
-points to an array of tags. See
-.B IORING_REGISTER_BUFFERS2
-for the resource tagging description.
-
-.SH RETURN VALUE
-On success
-.BR io_uring_register_buffers (3),
-.BR io_uring_register_buffers_tags (3)
-and
-.BR io_uring_register_buffers_sparse (3)
-return 0.
-.BR io_uring_register_buffers_update_tag (3)
-return number of buffers updated.
-On failure they return
-.BR -errno .
-.SH SEE ALSO
-.BR io_uring_register (2),
-.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_buffers_sparse.3

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

data/vendor/liburing/man/io_uring_register_buffers_tags.3

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

data/vendor/liburing/man/io_uring_register_buffers_update_tag.3

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

data/vendor/liburing/man/io_uring_register_eventfd.3

@@ -1,51 +0,0 @@
-.\" 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

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

data/vendor/liburing/man/io_uring_register_file_alloc_range.3

@@ -1,52 +0,0 @@
-.\" 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

@@ -1,112 +0,0 @@
-.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_register_files 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
-.SH NAME
-io_uring_register_files \- register file descriptors
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.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_tags(struct io_uring *" ring ","
-.BI "                                 const int *" files ","
-.BI "                                 const __u64 *" tags ","
-.BI "                                 unsigned " nr ");"
-.PP
-.BI "int io_uring_register_files_sparse(struct io_uring *" ring ","
-.BI "                                   unsigned " nr_files ");"
-.PP
-.BI "int io_uring_register_files_update(struct io_uring *" ring ","
-.BI "                                   unsigned " off ","
-.BI "                                   const int *" files ","
-.BI "                                   unsigned " nr_files ");"
-.PP
-.BI "int io_uring_register_files_update_tag(struct io_uring *" ring ","
-.BI "                                   unsigned " off ","
-.BI "                                   const int *" files ","
-.BI "                                   const __u64 *" tags ","
-.BI "                                   unsigned " nr_files ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_register_files (3)
-function registers
-.I nr_files
-number of file descriptors defined by the array
-.I files
-belonging to the
-.I ring
-for subsequent operations.
-
-The
-.BR io_uring_register_files_tags (3)
-function behaves the same as
-.BR io_uring_register_files (3)
-function but additionally takes
-.I tags
-parameter. See
-.B IORING_REGISTER_BUFFERS2
-for the resource tagging description.
-
-The
-.BR io_uring_register_files_sparse (3)
-function registers an empty file table of
-.I nr_files
-number of file descriptors. These files must be updated before use, using eg
-.BR io_uring_register_files_update_tag (3).
-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.
-
-The
-.BR io_uring_register_files_update (3)
-function updates existing registered files. The
-.I off
-is offset on which to start the update
-.I nr_files
-number of files defined by the array
-.I files
-belonging to the
-.IR ring .
-
-The
-.BR io_uring_register_files_update_tag (3)
-function behaves the same as
-.BR io_uring_register_files_update (3)
-function but additionally takes
-.I tags
-parameter. See
-.B IORING_REGISTER_BUFFERS2
-for the resource tagging description.
-
-.SH RETURN VALUE
-On success
-.BR io_uring_register_files (3),
-.BR io_uring_register_files_tags (3)
-and
-.BR io_uring_register_files_sparse (3)
-return 0.
-.BR io_uring_register_files_update (3)
-and
-.BR io_uring_register_files_update_tag (3)
-return number of files updated.
-On failure they return
-.BR -errno .
-.SH SEE ALSO
-.BR io_uring_register (2),
-.BR io_uring_get_sqe (3),
-.BR io_uring_unregister_files (3)

data/vendor/liburing/man/io_uring_register_files_sparse.3

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

data/vendor/liburing/man/io_uring_register_files_tags.3

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

data/vendor/liburing/man/io_uring_register_files_update.3

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

data/vendor/liburing/man/io_uring_register_files_update_tag.3

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

data/vendor/liburing/man/io_uring_register_iowq_aff.3

@@ -1,61 +0,0 @@
-.\" 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

@@ -1,71 +0,0 @@
-.\" 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

@@ -1,49 +0,0 @@
-.\" 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)