io_uring_enter.2 man page

Initial man page for io_uring_enter.

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

1 files changed, 378 insertions, 0 deletions

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
new file mode 100644
index 0000000..dc81fc4
--- /dev/null
+++ b/man/io_uring_enter.2
@@ -0,0 +1,378 @@
+.\" 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_ENTER 2 2019-01-22 "Linux" "Linux Programmer's Manual"
+.SH NAME
+io_uring_enter \- initiate and/or complete asynchronous I/O
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/io_uring.h>"
+.PP
+.BI "int io_uring_enter(unsigned int " fd ", unsigned int " to_submit ,
+.BI "                   unsigned int " min_complete ", unsigned int " flags)
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+.BR io_uring_enter ()
+is used to initiate and complete I/O using the shared submission and
+completion queues setup by a call to
+.BR io_uring_setup(2).
+A single call can both submit new I/O and wait for completions of I/O
+initiated by this call or previous calls to
+.BR io_uring_enter ().
+
+.I fd
+is the file descriptor returned by
+.BR io_uring_setup(2).
+.I to_submit
+specifies the number of I/Os to submit from the submission queue.  If
+the
+.B IORING_ENTER_GETEVENTS
+bit is set in
+.I flags,
+then the system call will attempt to wait for
+.I min_events
+I/O completions.  Note that it is valid to specify
+.B IORING_ENTER_GETEVENTS
+in
+.I flags
+and pass in
+.I min_complete
+as 0 at the same time.  This allows the kernel to return already
+completed events without waiting.  This is useful only when the
+io_uring instance was configured for polling (by specifying the
+.B IORING_SETUP_IOPOLL
+flag in
+.BR io_uring_setup(2)),
+as for IRQ driven I/O, the application can just check the completion
+queue without entering the kernel.
+
+Submission queue entries are represented using the following data
+structure:
+.PP
+.in +4n
+.EX
+/*
+ * IO submission data structure (Submission Queue Entry)
+ */
+struct io_uring_sqe {
+    __u8    opcode;         /* type of operation for this sqe */
+    __u8    flags;          /* IOSQE_ flags */
+    __u16   ioprio;         /* ioprio for the request */
+    __s32   fd;             /* file descriptor to do IO on */
+    __u64   off;            /* offset into file */
+    __u64   addr;           /* pointer to buffer or iovecs */
+    __u32   len;            /* buffer size or number of iovecs */
+    union {
+        __kernel_rwf_t  rw_flags;
+        __u32    fsync_flags;
+        __u16    poll_events;
+    };
+    __u64    user_data;     /* data passed back at completion time */
+    union {
+        __u16    buf_index; /* index into fixed buffers, if used */
+        __u64    __pad2[3];
+    };
+};
+.EE
+.in
+.PP
+The
+.I opcode
+describes the operation to be performed.  It can be one of:
+.TP
+.BR IORING_OP_NOP
+Do not perform any I/O.  This is useful for testing the performance of
+the io_uring implementation itself.
+.TP
+.BR IORING_OP_READV
+.TP
+.BR IORING_OP_WRITEV
+Vectored read and write operations, similar to
+.BR preadv2(2)
+and
+.BR pwritev2(2).
+
+.TP
+.BR IORING_OP_READ_FIXED
+.TP
+.BR IORING_OP_WRITE_FIXED
+Read from or write to pre-mapped buffers.  See
+.BR io_uring_register(2)
+for details on how to setup a context for fixed reads and writes.
+
+.TP
+.BR IORING_OP_FSYNC
+File sync.  See also
+.BR fsync(2).
+Note that, while I/O is initiated in the order in which it appears in
+the submission queue, completions are unordered.  For example, an
+application which places a write I/O followed by an fsync in the
+submission queue cannot expect the fsync to apply to the write.  The
+two operations execute in parallel, so the fsync may complete before
+the write is issued to the storage.  The same is also true for
+previously issued writes that have not completed prior to the fsync.
+
+.TP
+.BR IORING_OP_POLL_ADD
+Poll the
+.I fd
+specified in the submission queue entry for the events
+specified in the
+.I poll_events
+field.  Unlike poll or epoll without
+.B EPOLLONESHOT,
+this interface always works in one shot mode.  That is, once the poll
+operation is completed, it will have to be resubmitted.
+
+.TP
+.BR IORING_OP_POLL_REMOVE
+Remove an existing poll request.  If found, the
+.I res
+field of the
+.I struct io_uring_cqe
+will contain 0.  If not found,
+.I res
+will contain
+.B -ENOENT.
+
+.PP
+The
+.I flags
+field is a bit mask.  Currently, the only supported flag is
+.B IOSQE_FIXED_FILE.
+This flag must be specified for io_uring instances that registered
+files using the
+.BR io_uring_register(2)
+system call.  When specified,
+.I fd
+contains an index into the files array registered with the io_uring
+instance.
+
+.I ioprio
+specifies the I/O priority.  See
+.BR ioprio_get(2)
+for a description of Linux I/O priorities.
+
+.I fd
+specifies the file descriptor against which the operation will be
+performed, with the exception noted above.
+
+If the operation is one of
+.B IORING_OP_READ_FIXED
+or
+.B IORING_OP_WRITE_FIXED,
+.I addr
+and
+.I len
+must fall within the buffer located at
+.I buf_index
+in the fixed buffer array.  If the operation is either
+.B IORING_OP_READV
+or
+.B IORING_OP_WRITEV,
+then
+.I addr
+points to an iovec array of
+.I len
+entries.
+
+.I rw_flags,
+specified for read and write operations, contains a bitwise OR of
+per-I/O flags, as described in the
+.BR preadv2(2)
+man page.
+
+The
+.I fsync_flags
+bit mask may contain either 0, for a normal file integrity sync, or
+.B IORING_FSYNC_DATASYNC
+to provide data sync only semantics.  See the descriptions of
+.B O_SYNC
+and
+.B O_DSYNC
+in the
+.BR open(2)
+manual page for more information.
+
+The bits that may be set in
+.I poll_events
+are defined in \fI<poll.h>\fP, and documented in
+.BR poll(2).
+
+.I user_data
+is an application-supplied value that will be copied into
+the completion queue entry (see below).
+.I buf_index
+is an index into an array of fixed buffers, and is only valid if fixed
+buffers were registered
+.PP
+Once the submission queue entry is initialized, I/O is submitted by
+placing the index of the submission queue entry into the tail of the
+submission queue.  After one or more indexes are added to the queue,
+and the queue tail is advanced, the io_uring_enter(2) system call can
+be invoked to initiate the I/O.
+
+Completions use the following data structure:
+.PP
+.in +4n
+.EX
+/*
+ * IO completion data structure (Completion Queue Entry)
+ */
+struct io_uring_cqe {
+    __u64    user_data; /* sqe->data submission passed back */
+    __s32    res;       /* result code for this event */
+    __u32    flags;
+};
+.EE
+.in
+.PP
+.I user_data
+is copied from the field of the same name in the submission queue
+entry.  The primary use case is to store data that the application
+will need to access upon completion of this particular I/O.  The
+.I flags
+bit mask may contain 0 or more of the following values, ORed together:
+.TP
+.BR IOCQE_FLAG_CACHEHIT
+The page(s) associated with the buffered I/O operation were present in
+the page cache.
+.I res
+is the operation-specific result.
+.PP
+For read and write opcodes, the
+return values match those documented in the
+.BR preadv2(2)
+and
+.BR pwritev2(2)
+man pages.
+Return codes for the io_uring-specific opcodes are documented in the
+description of the opcodes above.
+.PP
+.SH RETURN VALUE
+.BR io_uring_enter ()
+returns the number of I/Os successfully submitted.  This can be zero
+if
+.I to_submit
+was zero, if there were invalid entries in the submission queue, or if
+the submission queue was empty.
+
+On error, -1 is returned and
+.I errno
+is set appropriately.
+.PP
+.SH ERRORS
+.TP
+.BR EAGAIN
+The kernel was unable to allocate memory for the request.
+.TP
+.BR EBADF
+The
+.I fd
+field in the submission queue entry is invalid, or the
+.B IOSQE_FIXED_FILE
+flag was set in the submission queue entry, but no files were registered
+with the io_uring instance
+.TP
+.BR EBUSY
+the io_uring instance is being acted on by another thread
+.TP
+.BR EFAULT
+buffer is outside of the process' accessible address space
+.TP
+.BR EFAULT
+.B IORING_OP_READ_FIXED
+or
+.B IORING_OP_WRITE_FIXED
+was specified in the
+.I opcode
+field of the submission queue entry, but either buffers were not
+registered for this io_uring instance, or the address range described
+by
+.I addr
+and
+.I len
+does not fit within the buffer registered at
+.I buf_index
+.TP
+.BR EINVAL
+The
+.I index
+member of the submission queue entry is invalid.
+.TP
+.BR EINVAL
+the
+.I flags
+field or
+.I opcode
+in a submission queue entry is invalid
+.TP
+.BR EINVAL
+.B IORING_OP_NOP
+was specified in the submission queue entry, but the io_uring context
+was setup for polling (
+.B IORING_SETUP_IOPOLL
+was specified in the call to io_uring_setup)
+.TP
+.BR EINVAL
+.B IORING_OP_READV
+or
+.B IORING_OP_WRITEV
+was specified in the submission queue entry, but the io_uring instance
+has fixed buffers registered.
+.TP
+.BR EINVAL
+.B IORING_OP_READ_FIXED
+or
+.B IORING_OP_WRITE_FIXED
+was specified in the submission queue entry, and the
+.I buf_index
+is invalid
+.TP
+.BR EINVAL
+.B IORING_OP_READV, IORING_OP_WRITEV, IORING_OP_READ_FIXED,
+.B IORING_OP_WRITE_FIXED
+or
+.B IORING_OP_FSYNC
+was specified in the submission queue entry, but the io_uring instance
+was configured for IOPOLLing, or any of
+.I addr, ioprio, off, len,
+or
+.I buf_index
+was set in the submission queue entry.
+.TP
+.BR EINVAL
+.B IORING_OP_POLL_ADD
+or
+.B IORING_OP_POLL_REMOVE
+was specified in the
+.I opcode
+field of the submission queue entry, but the io_uring instance was
+configured for busy-wait polling
+.B (IORING_SETUP_IOPOLL),
+or any of
+.I ioprio, off, len
+or
+.I buf_index
+was non-zero in the submission queue entry.
+.TP
+.BR EINVAL
+.B IORING_OP_POLL_ADD
+was specified in the
+.I opcode
+field of the submission queue entry, and the
+.I addr
+field was non-zero.
+.TP
+.BR ENXIO
+the io_uring instance is in the process of being torn down
+.TP
+.BR EOPNOTSUPP
+.I fd
+does not refer to an io_uring instance