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

[Stefano Garzarella <sgarzare@redhat.com>]

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