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

[Jens Axboe <axboe@kernel.dk>]

On 9/11/20 7:34 AM, Stefano Garzarella wrote:
> 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>
> ---
>  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..ce39ada 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 io_uring ring started in a disabled state

enables an io_uring

> +.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 or files or restrictions
> +registered.

buffers, files, or restrictions

>  .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

Apart from that, looks good to me.

-- 
Jens Axboe