[PATCH liburing v2 2/3] man/io_uring_register.2: add description of restrictions

[Stefano Garzarella <sgarzare@redhat.com>]

Starting from Linux 5.10 io_uring supports restrictions.
This patch describes how to register restriction, enable io_uring
ring, and potential errors returned by io_uring_register(2).

Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
---
v2:
- fixed grammar issues [Jens]
---
 man/io_uring_register.2 | 79 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 77 insertions(+), 2 deletions(-)

diff --git a/man/io_uring_register.2 b/man/io_uring_register.2
index 5022c03..225e461 100644
--- a/man/io_uring_register.2
+++ b/man/io_uring_register.2
@@ -19,7 +19,8 @@ io_uring_register \- register files or user buffers for asynchronous I/O
 
 The
 .BR io_uring_register ()
-system call registers user buffers or files for use in an
+system call registers resources (e.g. user buffers, files, eventfd,
+personality, restrictions) for use in an
 .BR io_uring (7)
 instance referenced by
 .IR fd .
@@ -232,6 +233,58 @@ must be set to the id in question, and
 .I arg
 must be set to NULL. Available since 5.6.
 
+.TP
+.B IORING_REGISTER_ENABLE_RINGS
+This operation enables an io_uring ring started in a disabled state
+.RB (IORING_SETUP_R_DISABLED
+was specified in the call to
+.BR io_uring_setup (2)).
+While the io_uring ring is disabled, submissions are not allowed and
+registrations are not restricted.
+
+After the execution of this operation, the io_uring ring is enabled:
+submissions and registration are allowed, but they will
+be validated following the registered restrictions (if any).
+This operation takes no argument, must be invoked with
+.I arg
+set to NULL and
+.I nr_args
+set to zero. Available since 5.10.
+
+.TP
+.B IORING_REGISTER_RESTRICTIONS
+.I arg
+points to a
+.I struct io_uring_restriction
+array of
+.I nr_args
+entries.
+
+With an entry it is possible to allow an
+.BR io_uring_register ()
+.I opcode,
+or specify which
+.I opcode
+and
+.I flags
+of the submission queue entry are allowed,
+or require certain
+.I flags
+to be specified (these flags must be set on each submission queue entry).
+
+All the restrictions must be submitted with a single
+.BR io_uring_register ()
+call and they are handled as an allowlist (opcodes and flags not registered,
+are not allowed).
+
+Restrictions can be registered only if the io_uring ring started in a disabled
+state
+.RB (IORING_SETUP_R_DISABLED
+must be specified in the call to
+.BR io_uring_setup (2)).
+
+Available since 5.10.
+
 .SH RETURN VALUE
 
 On success,
@@ -242,16 +295,30 @@ is set accordingly.
 
 .SH ERRORS
 .TP
+.B EACCES
+The
+.I opcode
+field is not allowed due to registered restrictions.
+.TP
 .B EBADF
 One or more fds in the
 .I fd
 array are invalid.
 .TP
+.B EBADFD
+.B IORING_REGISTER_ENABLE_RINGS
+or
+.B IORING_REGISTER_RESTRICTIONS
+was specified, but the io_uring ring is not disabled.
+.TP
 .B EBUSY
 .B IORING_REGISTER_BUFFERS
 or
 .B IORING_REGISTER_FILES
-was specified, but there were already buffers or files registered.
+or
+.B IORING_REGISTER_RESTRICTIONS
+was specified, but there were already buffers, files, or restrictions
+registered.
 .TP
 .B EFAULT
 buffer is outside of the process' accessible address space, or
@@ -283,6 +350,14 @@ is non-zero or
 .I arg
 is non-NULL.
 .TP
+.B EINVAL
+.B IORING_REGISTER_RESTRICTIONS
+was specified, but
+.I nr_args
+exceeds the maximum allowed number of restrictions or restriction
+.I opcode
+is invalid.
+.TP
 .B EMFILE
 .B IORING_REGISTER_FILES
 was specified and
-- 
2.26.2