Document io_uring feature

This was released with Linux 5.1, so we can document it now as the
API won't change.

Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/HOWTO b/HOWTO
index 142b83e5020f9b77303756354c9a3ef8cdbaa682..812440648815d97af8f89b40a20efc35695b967a 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -1805,6 +1805,11 @@ I/O engine
                **pvsync2**
                        Basic :manpage:`preadv2(2)` or :manpage:`pwritev2(2)` I/O.
 
                **pvsync2**
                        Basic :manpage:`preadv2(2)` or :manpage:`pwritev2(2)` I/O.
 

+               **io_uring**
+                       Fast Linux native asynchronous I/O. Supports async IO
+                       for both direct and buffered IO.
+                       This engine defines engine specific options.
+

                **libaio**
                        Linux native asynchronous I/O. Note that Linux may only support
                        queued behavior with non-buffered I/O (set ``direct=1`` or
                **libaio**
                        Linux native asynchronous I/O. Note that Linux may only support
                        queued behavior with non-buffered I/O (set ``direct=1`` or


@@ -2002,6 +2007,35 @@ In addition, there are some parameters which are only valid when a specific
 with the caveat that when used on the command line, they must come after the
 :option:`ioengine` that defines them is selected.
 
 with the caveat that when used on the command line, they must come after the
 :option:`ioengine` that defines them is selected.
 

+.. option:: hipri : [io_uring]
+
+       If this option is set, fio will attempt to use polled IO completions.
+       Normal IO completions generate interrupts to signal the completion of
+       IO, polled completions do not. Hence they are require active reaping
+       by the application. The benefits are more efficient IO for high IOPS
+       scenarios, and lower latencies for low queue depth IO.
+
+.. option:: fixedbufs : [io_uring]
+
+       If fio is asked to do direct IO, then Linux will map pages for each
+       IO call, and release them when IO is done. If this option is set, the
+       pages are pre-mapped before IO is started. This eliminates the need to
+       map and release for each IO. This is more efficient, and reduces the
+       IO latency as well.
+
+.. option:: sqthread_poll : [io_uring]
+
+       Normally fio will submit IO by issuing a system call to notify the
+       kernel of available items in the SQ ring. If this option is set, the
+       act of submitting IO will be done by a polling thread in the kernel.
+       This frees up cycles for fio, at the cost of using more CPU in the
+       system.
+
+.. option:: sqthread_poll_cpu : [io_uring]
+
+       When :option:`sqthread_poll` is set, this option provides a way to
+       define which CPU should be used for the polling thread.
+

 .. option:: userspace_reap : [libaio]
 
        Normally, with the libaio engine in use, fio will use the
 .. option:: userspace_reap : [libaio]
 
        Normally, with the libaio engine in use, fio will use the

diff --git a/fio.1 b/fio.1
index 156201ad7822528043a39546810865bbe5e0968a..2966d9d5f0e35acb45e4f1b099bd6a7c0bd381e1 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -1762,6 +1762,29 @@ In addition, there are some parameters which are only valid when a specific
 with the caveat that when used on the command line, they must come after the
 \fBioengine\fR that defines them is selected.
 .TP
 with the caveat that when used on the command line, they must come after the
 \fBioengine\fR that defines them is selected.
 .TP

+.BI (io_uring)hipri
+If this option is set, fio will attempt to use polled IO completions. Normal IO
+completions generate interrupts to signal the completion of IO, polled
+completions do not. Hence they are require active reaping by the application.
+The benefits are more efficient IO for high IOPS scenarios, and lower latencies
+for low queue depth IO.
+.TP
+.BI (io_uring)fixedbufs
+If fio is asked to do direct IO, then Linux will map pages for each IO call, and
+release them when IO is done. If this option is set, the pages are pre-mapped
+before IO is started. This eliminates the need to map and release for each IO.
+This is more efficient, and reduces the IO latency as well.
+.TP
+.BI (io_uring)sqthread_poll
+Normally fio will submit IO by issuing a system call to notify the kernel of
+available items in the SQ ring. If this option is set, the act of submitting IO
+will be done by a polling thread in the kernel. This frees up cycles for fio, at
+the cost of using more CPU in the system.
+.TP
+.BI (io_uring)sqthread_poll_cpu
+When `sqthread_poll` is set, this option provides a way to define which CPU
+should be used for the polling thread.
+.TP

 .BI (libaio)userspace_reap
 Normally, with the libaio engine in use, fio will use the
 \fBio_getevents\fR\|(3) system call to reap newly returned events. With
 .BI (libaio)userspace_reap
 Normally, with the libaio engine in use, fio will use the
 \fBio_getevents\fR\|(3) system call to reap newly returned events. With