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

Jens Axboe
2020-09-11T15:33:42Z

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