[PATCH liburing v2 0/3] Add restrictions stuff in the man pages

[PATCH liburing v2 0/3] Add restrictions stuff in the man pages

[Stefano Garzarella]

Hi Jens,
this series adds description of restrictions, how to enable io_uring
ring, and related errors in the man pages.
The patches are also available here:

https://github.com/stefano-garzarella/liburing (branch: restrictions-man-pages)

v2:
  - rebased on master after the split of ERRORS section in man/io_uring_enter.2
  - Patch 2: fixed grammar issues [Jens]
  - Patch 3: put the errors in right section

v1: https://lore.kernel.org/io-uring/20200911133408.62506-1-sgarzare@redhat.com

Thanks,
Stefano

Stefano Garzarella (3):
  man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description
  man/io_uring_register.2: add description of restrictions
  man/io_uring_enter.2: add EACCES and EBADFD errors

 man/io_uring_enter.2    | 17 +++++++++
 man/io_uring_register.2 | 79 +++++++++++++++++++++++++++++++++++++++--
 man/io_uring_setup.2    |  7 ++++
 3 files changed, 101 insertions(+), 2 deletions(-)

-- 
2.26.2

[PATCH liburing v2 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description

[Stefano Garzarella]

This new flag is available starting from Linux 5.10.

Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
---
 man/io_uring_setup.2 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/man/io_uring_setup.2 b/man/io_uring_setup.2
index f0aebde..a903b04 100644
--- a/man/io_uring_setup.2
+++ b/man/io_uring_setup.2
@@ -173,6 +173,13 @@ being set to an existing io_uring ring file descriptor. When set, the
 io_uring instance being created will share the asynchronous worker
 thread backend of the specified io_uring ring, rather than create a new
 separate thread pool.
+.TP
+.B IORING_SETUP_R_DISABLED
+If this flag is specified, the io_uring ring starts in a disabled state.
+In this state, restrictions can be registered, but submissions are not allowed.
+See
+.BR io_uring_register (2)
+for details on how to enable the ring. Available since 5.10.
 .PP
 If no flags are specified, the io_uring instance is setup for
 interrupt driven I/O.  I/O may be submitted using
-- 
2.26.2

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

[Stefano Garzarella]

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

[PATCH liburing v2 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors

[Stefano Garzarella]

These new errors are added with the restriction series recently
merged in io_uring (Linux 5.10).

Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
---
v2:
- put the errors in right section
---
 man/io_uring_enter.2 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 8b87e23..15a5a4a 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -869,6 +869,13 @@ try again.
 .I fd
 is not a valid file descriptor.
 .TP
+.B EBADFD
+.I fd
+is a valid file descriptor, but the io_uring ring is not in the right state
+(enabled). See
+.BR io_uring_register (2)
+for details on how to enable the ring.
+.TP
 .B EBUSY
 The application is attempting to overcommit the number of requests it can have
 pending. The application should wait for some completions and try again. May
@@ -904,6 +911,16 @@ These io_uring-specific errors are returned as a negative value in the
 .I res
 field of the completion queue entry.
 .TP
+.B EACCES
+The
+.I flags
+field or
+.I opcode
+in a submission queue entry is not allowed due to registered restrictions.
+See
+.BR io_uring_register (2)
+for details on how restrictions work.
+.TP
 .B EBADF
 The
 .I fd
-- 
2.26.2

Re: [PATCH liburing v2 0/3] Add restrictions stuff in the man pages

[Jens Axboe]

On 9/29/20 7:23 AM, Stefano Garzarella wrote:
> Hi Jens,
> this series adds description of restrictions, how to enable io_uring
> ring, and related errors in the man pages.
> The patches are also available here:
> 
> https://github.com/stefano-garzarella/liburing (branch: restrictions-man-pages)
> 
> v2:
>   - rebased on master after the split of ERRORS section in man/io_uring_enter.2
>   - Patch 2: fixed grammar issues [Jens]
>   - Patch 3: put the errors in right section
> 
> v1: https://lore.kernel.org/io-uring/20200911133408.62506-1-sgarzare@redhat.com

Applied, thanks!

-- 
Jens Axboe