liburing: add man pages for helper functions.

This adds man pages for the following functions:
- io_uring_cq_advance
- io_uring_cq_ready
- io_uring_free_probe
- io_uring_get_probe
- io_uring_opcode_supported
- io_uring_sq_ready
- io_uring_sq_space_left
- io_uring_sqe_set_flags
- io_uring_sqring_wait

Signed-off-by: Stefan Roesch <shr@fb.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>

9 files changed, 277 insertions, 0 deletions

diff --git a/man/io_uring_cq_advance.3 b/man/io_uring_cq_advance.3
new file mode 100644
index 0000000..59bb681
--- /dev/null
+++ b/man/io_uring_cq_advance.3
@@ -0,0 +1,35 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_cq_advance 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_cq_advance - Mark one or more io_uring completion events as processed
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "void io_uring_cqe_advance(struct io_uring *ring,"
+.BI "                          unsigned nr)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The io_uring_cq_advance() function marks
+.I nr
+IO completions
+belonging to the
+.I ring
+param as processed.
+
+After the caller has submitted a request with io_uring_submit(), he can retrieve
+the completion with io_uring_wait_cqe() and mark it then as processed with
+io_uring_cqe_seen(). 
+
+The function io_uring_cqe_seen() calls the function io_uring_cq_advance().
+
+Completions must be marked as completed, so their slot can get reused.
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_submit (3), io_uring_wait_cqe (3), io_uring_cqe_seen (3)
\ No newline at end of file
diff --git a/man/io_uring_cq_ready.3 b/man/io_uring_cq_ready.3
new file mode 100644
index 0000000..a540d2a
--- /dev/null
+++ b/man/io_uring_cq_ready.3
@@ -0,0 +1,25 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_cq_ready "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_cq_ready - number of unconsumed ready entries in the CQ ring
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "unsigned io_uring_cq_ready(const struct io_uring *ring)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The io_uring_cq_ready() function retuns the number of unconsumed entries that
+are ready belonging to the
+.I ring
+param.
+
+.SH RETURN VALUE
+Returns the number of unconsumed ready entries in the CQ ring.
+.SH SEE ALSO
+.BR io_uring_submit (3),  io_uring_wait_cqe (3)
\ No newline at end of file
diff --git a/man/io_uring_free_probe.3 b/man/io_uring_free_probe.3
new file mode 100644
index 0000000..bc674ca
--- /dev/null
+++ b/man/io_uring_free_probe.3
@@ -0,0 +1,24 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_free_probe "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_free_probe - free probe instance
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "void io_uring_free_probe(struct io_uring_probe *probe)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The function io_uring_free_probe() frees the
+.I probe
+instance allocated with the io_uring_get_probe() function.
+
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_get_probe (3)
\ No newline at end of file
diff --git a/man/io_uring_get_probe.3 b/man/io_uring_get_probe.3
new file mode 100644
index 0000000..1bb8b14
--- /dev/null
+++ b/man/io_uring_get_probe.3
@@ -0,0 +1,25 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_get_probe "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_get_probe - get probe instance
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "io_uring_probe *io_uring_get_probe(void)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The function io_uring_get_probe() returns an allocated io_uring_probe
+structure to the caller. The caller is responsible for freeing the
+structure with the function io_uring_free_probe().
+
+.SH RETURN VALUE
+On success it returns an allocated io_uring_probe structure, otherwise
+it returns NULL.
+.SH SEE ALSO
+.BR io_uring_free_probe (3)
\ No newline at end of file
diff --git a/man/io_uring_opcode_supported.3 b/man/io_uring_opcode_supported.3
new file mode 100644
index 0000000..4d03027
--- /dev/null
+++ b/man/io_uring_opcode_supported.3
@@ -0,0 +1,29 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_opcode_supported "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_opcode_supported - is op code supported?
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_opcode_supported(struct io_uring_probe *probe,"
+.BI "                              int opode)
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The function io_uring_opcode_supported allows the caller to determine if
+the passed in
+.I opcode
+belonging to the
+.I probe
+param is supported. An instance of the io_uring_probe instance can be
+obtained by calling the function io_uring_get_probe().
+
+.SH RETURN VALUE
+On success it returns 1, otherwise it returns 0.
+.SH SEE ALSO
+.BR io_uring_get_probe (3)
\ No newline at end of file
diff --git a/man/io_uring_sq_ready.3 b/man/io_uring_sq_ready.3
new file mode 100644
index 0000000..f583903
--- /dev/null
+++ b/man/io_uring_sq_ready.3
@@ -0,0 +1,25 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_sq_ready "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_sq_ready - number of unconsumed or unsubmitted entries in the SQ ring
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "unsigned io_uring_sq_ready(const struct io_uring *ring)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The io_uring_sq_ready() function retuns the number of unconsumed (if SQPOLL) or
+unsubmitted entries that exist in the SQ ring belonging to the
+.I ring
+param.
+
+.SH RETURN VALUE
+Returns the number of unconsumed or unsubmitted entries in the  SQ ring.
+.SH SEE ALSO
+.BR io_uring_cq_ready (3)
\ No newline at end of file
diff --git a/man/io_uring_sq_space_left.3 b/man/io_uring_sq_space_left.3
new file mode 100644
index 0000000..45d229a
--- /dev/null
+++ b/man/io_uring_sq_space_left.3
@@ -0,0 +1,25 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_sq_space-left "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_sq_space_left - free space in the SQ ring
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "unsigned io_uring_sq_space_left(const struct io_uring *ring)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The io_uring_sq_space_left() function retuns how much space is left in the
+SQ ring belonging to the
+.I ring
+param.
+
+.SH RETURN VALUE
+Returns the free space in the SQ ring.
+.SH SEE ALSO
+.BR io_uring_sq_ready (3)
\ No newline at end of file
diff --git a/man/io_uring_sqe_set_flags.3 b/man/io_uring_sqe_set_flags.3
new file mode 100644
index 0000000..bbe62b5
--- /dev/null
+++ b/man/io_uring_sqe_set_flags.3
@@ -0,0 +1,59 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_sqe_set_flags "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_sqe_set_flags - set flags for submission queue entry
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "void io_uring_sqe_set_flags(struct io_uring_sqe *sqe,"
+.BI "                            unsigned flags)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The io_uring_sqe_set_flags() function allows the caller to change the
+behavior of the submission queue entry by specifying flags. It enables the
+.I flags
+belonging to the
+.I sqe
+submission queue entry param.
+
+.I flags
+is a bit mask of 0 or more of the following values ORed together:
+.TP
+.B IOSQE_FIXED_FILE
+Use registered files that previously registered buffers.
+.TP
+.B IOSQE_ASYNC
+Normal operation for io_uring is to try and issue an sqe as non-blocking first,
+and if that fails, execute it in an async manner. To support more efficient
+overlapped operation of requests that the application knows/assumes will
+always (or most of the time) block, the application can ask for an sqe to be
+issued async from the start.
+.TP
+.B IOSQE_IO_LINK
+When this flag is specified, the SQE forms a link with the next SQE in the
+submission ring. That next SQE will not be started before the previous request
+completes. This, in effect, forms a chain of SQEs, which can be arbitrarily
+long. The tail of the chain is denoted by the first SQE that does not have this
+flag set. Chains are not supported across submission boundaries. EVen if the
+last SQE in a submission has this flag set, it will still terminate the current
+chain. This flag has no effect on previous SQE submissions, nor does it impact
+SQEs that are outside of the chain tail. This means that multiple chains can be
+executing in parallel, or chains and individual SQEs. Only members inside the
+chain are serialized. A chain of SQEs will be broken, if any request in that
+chain ends in error.
+.TP
+.B IOSQE_IO_DRAIN
+When this flag is specified, the SQE will not be started before previously
+submitted SQEs have completed, and new SQEs will not be started before this
+one completes.
+
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_submit (3),  io_uring_register(3)
\ No newline at end of file
diff --git a/man/io_uring_sqring_wait.3 b/man/io_uring_sqring_wait.3
new file mode 100644
index 0000000..e0fb731
--- /dev/null
+++ b/man/io_uring_sqring_wait.3
@@ -0,0 +1,30 @@
+.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_sqring_wait "January 25, 2022" "liburing-2.1" "liburing Manual"
+.SH NAME
+io_uring_sqring_wait - wait for free space in the SQ ring
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_sqring_wait(struct io_uring *ring)"
+.fi
+.PP
+.SH DESCRIPTION
+.PP
+The function io_uring_sqring_wait() allows the caller to wait for space
+to free up in the SQ ring belonging to the
+.I ring
+param, which happens when the kernel side thread
+has consumed one or more entries. If the SQ ring is currently non-full,
+no action is taken.
+
+This feature can only be used when SQPOLL is enabled.
+
+.SH RETURN VALUE
+On success it returns the free space. If the kernel does not support the
+feature, -EINVAL is returned.
+.SH SEE ALSO
+.BR io_uring_submit (3),  io_uring_wait_cqe (3),  io_uring_wait_cqes (3)
\ No newline at end of file