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

Stefano Garzarella
2020-09-14T08:02:58Z

On Fri, Sep 11, 2020 at 09:33:01AM -0600, Jens Axboe wrote:
> 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.
>

Thanks,
I'll fix the issues in the v2.

Stefano