man: add a man page for io_uring_register

Initial content was taken from the kernel commits (Jens Axboe).

Signed-off-by: Jeff Moyer <jmoyer@redhat.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>

1 files changed, 197 insertions, 0 deletions

diff --git a/man/io_uring_register.2 b/man/io_uring_register.2
new file mode 100644
index 0000000..168d600
--- /dev/null
+++ b/man/io_uring_register.2
@@ -0,0 +1,197 @@
+.\" Copyright (C) 2019 Jens Axboe <axboe@kernel.dk>
+.\" Copyright (C) 2019 Red Hat, Inc.
+.\"
+.\" %%%LICENSE_START(LGPL_V2.1)
+.\" This file is distributed according to the GNU Lesser General Public License.
+.\" %%%LICENSE_END
+.\"
+.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>"
+.PP
+.BI "int io_uring_register(unsigned int " fd ", unsigned int " opcode ,
+.BI "                      void *" arg ", unsigned int " nr_args)
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+
+The
+.BR io_uring_register ()
+system call registers user buffers or files for use in an
+.BR io_uring (7)
+instance referenced by
+.I fd.
+Registering files or user buffers allows the kernel to take long term
+references to internal data structures or create long term mappings of
+application memory, greatly reducing per-I/O overhead.
+
+.I fd
+is the file descriptor returned by a call to
+.BR io_uring_setup (2).
+.I opcode
+can be one of:
+
+.BR IORING_REGISTER_BUFFERS
+
+.I arg
+points to a
+.I struct iovec
+array of
+.I nr_args
+entries.  The buffers associated with the iovecs will be locked in
+memory and charged against the user's
+.B RLIMIT_MEMLOCK resource limit.  See
+.BR getrlimit (2)
+for more information.  Additionally, there is a size limit of 1GiB per
+buffer.  Currently, the buffers must be anonymous, non-file-backed
+memory, such as that returned by
+.BR malloc (3)
+or
+.BR mmap (2)
+with the
+.B MAP_ANONYMOUS
+flag set.  It is expected that this limitation will be lifted in the
+future.
+
+After a successful call, the supplied buffers are mapped into the
+kernel and eligible for I/O.  To make use of them, the application
+must specify the
+.B IORING_OP_READ_FIXED
+or
+.B IORING_OP_WRITE_FIXED
+opcodes in the submission queue entry (see the
+.I struct io_uring_sqe
+definition in
+.BR io_uring_enter (2)),
+and set the
+.I buf_index
+field to the desired buffer index.  The memory range described by the
+submission queue entry's
+.I addr
+and
+.I len
+fields must fall within the indexed buffer.
+
+It is perfectly valid to setup a large buffer and then only use part
+of it for an I/O, as long as the range is within the originally mapped
+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 ()
+with the new buffers.
+
+An application need not unregister buffers explicitly before shutting
+down the io_uring instance.
+
+.BR IORING_UNREGISTER_BUFFERS
+
+This operation takes no argument, and
+.I arg
+must be passed as NULL.  All previously registered buffers associated
+with the io_uring instance will be released.
+
+.BR IORING_REGISTER_FILES
+
+Register files for I/O.
+.I arg
+contains a pointer to an array of
+.I nr_args
+file descriptors (signed 32 bit integers).
+
+When used, the application must set
+.B IOSQE_FIXED_FILE
+in the
+.I flags
+member of the
+.I struct io_uring_sqe.
+Then,
+.I fd
+is set to the index of the buffer in the array supplied to
+.B IORING_REGISTER_FILES.
+
+Files are automatically unregistered when the io_uring instance is
+torn down. An application need only unregister if it wishes to
+register a few set of fds.
+
+.BR IORING_UNREGISTER_FILES
+
+This operation requires no argument, and
+.I arg
+must be passed as NULL.  All previously registered files associated
+with the io_uring instance will be unregistered.
+
+.SH RETURN VALUE
+
+On success,
+.BR io_uring_register ()
+returns 0.  On error, -1 is returned, and
+.I errno
+is set accordingly.
+
+.SH ERRORS
+
+.B EINVAL
+.BR IORING_REGISTER_BUFFERS
+or
+.BR IORING_REGISTER_FILES
+was specified, but
+.I nr_args
+is 0.
+
+.B EINVAL
+.BR IORING_REGISTER_BUFFERS
+was specified, but
+.I nr_args
+exceeds
+.BR UIO_MAXIOV
+
+.B EINVAL
+.BR IORING_UNREGISTER_BUFFERS
+or
+.BR IORING_UNREGISTER_FILES
+was specified, and
+.I nr_args
+is non-zero or
+.I arg
+is non-NULL.
+
+.B ENXIO
+.BR IORING_UNREGISTER_BUFFERS
+or
+.BR IORING_UNREGISTER_FILES
+was specified, but there were no buffers or files registered.
+
+.B EBUSY
+.BR IORING_REGISTER_BUFFERS
+or
+.BR IORING_REGISTER_FILES
+was specified, but there were already buffers or files registered.
+
+.B ENOMEM
+Insufficient kernel resources are available, or the caller had a
+non-zero
+.BR RLIMIT_MEMLOCK
+soft resource limit, but tried to lock more memory than the limit
+permitted.  This limit is not enforced if the process is privileged
+(
+.BR CAP_IPC_LOCK
+).
+
+.B EBADF
+One or more fds in the
+.I fd
+array are invalid.
+
+.B EFAULT
+buffer is outside of the process' accessible address space, or
+.I iov_len
+is greater than 1GiB.
+
+.B EOPNOTSUPP
+User buffers point to file-backed memory.