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

[PATCH liburing 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)

I didn't put the details of struct io_uring_restriction and
IORING_RESTRICTION_* op codes.
Do you think I should put the definition of the structure and opcodes in
man/io_uring_register.2?

I know I'm not very good at writing documentation, so tell me what to change
or write better ;-)

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    | 18 ++++++++++
 man/io_uring_register.2 | 79 +++++++++++++++++++++++++++++++++++++++--
 man/io_uring_setup.2    |  7 ++++
 3 files changed, 102 insertions(+), 2 deletions(-)

-- 
2.26.2

[PATCH liburing 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 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>
---
 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
+.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.
 .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 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>
---
 man/io_uring_enter.2 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 5443d5f..4773dfd 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -842,6 +842,16 @@ is set appropriately.
 .PP
 .SH ERRORS
 .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 EAGAIN
 The kernel was unable to allocate memory for the request, or otherwise ran out
 of resources to handle it. The application should wait for some completions and
@@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
 flag was set in the submission queue entry, but no files were registered
 with the io_uring instance.
 .TP
+.B EBADFD
+The
+.I fd
+field in the submission queue entry is valid, 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 EFAULT
 buffer is outside of the process' accessible address space
 .TP
-- 
2.26.2

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

[Jens Axboe]

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

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

[Jens Axboe]

On 9/11/20 7:34 AM, Stefano Garzarella wrote:
> 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>
> ---
>  man/io_uring_enter.2 | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
> index 5443d5f..4773dfd 100644
> --- a/man/io_uring_enter.2
> +++ b/man/io_uring_enter.2
> @@ -842,6 +842,16 @@ is set appropriately.
>  .PP
>  .SH ERRORS
>  .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 EAGAIN
>  The kernel was unable to allocate memory for the request, or otherwise ran out
>  of resources to handle it. The application should wait for some completions and
> @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
>  flag was set in the submission queue entry, but no files were registered
>  with the io_uring instance.
>  .TP
> +.B EBADFD
> +The
> +.I fd
> +field in the submission queue entry is valid, 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

I actually think some of this needs general updating. io_uring_enter()
will not return an error on behalf of an sqe, it'll only return an error
if one happened outside the context of a specific sqe. Any error
specific to an sqe will generate a cqe with the result.

-- 
Jens Axboe

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

[Stefano Garzarella]

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

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

[Stefano Garzarella]

On Fri, Sep 11, 2020 at 09:36:02AM -0600, Jens Axboe wrote:
> On 9/11/20 7:34 AM, Stefano Garzarella wrote:
> > 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>
> > ---
> >  man/io_uring_enter.2 | 18 ++++++++++++++++++
> >  1 file changed, 18 insertions(+)
> > 
> > diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
> > index 5443d5f..4773dfd 100644
> > --- a/man/io_uring_enter.2
> > +++ b/man/io_uring_enter.2
> > @@ -842,6 +842,16 @@ is set appropriately.
> >  .PP
> >  .SH ERRORS
> >  .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 EAGAIN
> >  The kernel was unable to allocate memory for the request, or otherwise ran out
> >  of resources to handle it. The application should wait for some completions and
> > @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
> >  flag was set in the submission queue entry, but no files were registered
> >  with the io_uring instance.
> >  .TP
> > +.B EBADFD
> > +The
> > +.I fd
> > +field in the submission queue entry is valid, 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
> 
> I actually think some of this needs general updating. io_uring_enter()
> will not return an error on behalf of an sqe, it'll only return an error
> if one happened outside the context of a specific sqe. Any error
> specific to an sqe will generate a cqe with the result.

Mmm, right.

For example in this case, EACCES is returned by a cqe and EBADFD is
returned by io_uring_enter().

Should we create 2 error sections?

Thanks,
Stefano

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

[Jens Axboe]

On 9/14/20 2:05 AM, Stefano Garzarella wrote:
> On Fri, Sep 11, 2020 at 09:36:02AM -0600, Jens Axboe wrote:
>> On 9/11/20 7:34 AM, Stefano Garzarella wrote:
>>> 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>
>>> ---
>>>  man/io_uring_enter.2 | 18 ++++++++++++++++++
>>>  1 file changed, 18 insertions(+)
>>>
>>> diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
>>> index 5443d5f..4773dfd 100644
>>> --- a/man/io_uring_enter.2
>>> +++ b/man/io_uring_enter.2
>>> @@ -842,6 +842,16 @@ is set appropriately.
>>>  .PP
>>>  .SH ERRORS
>>>  .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 EAGAIN
>>>  The kernel was unable to allocate memory for the request, or otherwise ran out
>>>  of resources to handle it. The application should wait for some completions and
>>> @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
>>>  flag was set in the submission queue entry, but no files were registered
>>>  with the io_uring instance.
>>>  .TP
>>> +.B EBADFD
>>> +The
>>> +.I fd
>>> +field in the submission queue entry is valid, 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
>>
>> I actually think some of this needs general updating. io_uring_enter()
>> will not return an error on behalf of an sqe, it'll only return an error
>> if one happened outside the context of a specific sqe. Any error
>> specific to an sqe will generate a cqe with the result.
> 
> Mmm, right.
> 
> For example in this case, EACCES is returned by a cqe and EBADFD is
> returned by io_uring_enter().
> 
> Should we create 2 error sections?

Yep, I think we should. One that describes that io_uring_enter() would
return in terms of errors, and one that describes cqe->res returns.

Are you up for this? Would be a great change, making it a lot more
accurate.

-- 
Jens Axboe

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

[Stefano Garzarella]

On Mon, Sep 14, 2020 at 09:38:25AM -0600, Jens Axboe wrote:
> On 9/14/20 2:05 AM, Stefano Garzarella wrote:
> > On Fri, Sep 11, 2020 at 09:36:02AM -0600, Jens Axboe wrote:
> >> On 9/11/20 7:34 AM, Stefano Garzarella wrote:
> >>> 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>
> >>> ---
> >>>  man/io_uring_enter.2 | 18 ++++++++++++++++++
> >>>  1 file changed, 18 insertions(+)
> >>>
> >>> diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
> >>> index 5443d5f..4773dfd 100644
> >>> --- a/man/io_uring_enter.2
> >>> +++ b/man/io_uring_enter.2
> >>> @@ -842,6 +842,16 @@ is set appropriately.
> >>>  .PP
> >>>  .SH ERRORS
> >>>  .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 EAGAIN
> >>>  The kernel was unable to allocate memory for the request, or otherwise ran out
> >>>  of resources to handle it. The application should wait for some completions and
> >>> @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
> >>>  flag was set in the submission queue entry, but no files were registered
> >>>  with the io_uring instance.
> >>>  .TP
> >>> +.B EBADFD
> >>> +The
> >>> +.I fd
> >>> +field in the submission queue entry is valid, 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
> >>
> >> I actually think some of this needs general updating. io_uring_enter()
> >> will not return an error on behalf of an sqe, it'll only return an error
> >> if one happened outside the context of a specific sqe. Any error
> >> specific to an sqe will generate a cqe with the result.
> > 
> > Mmm, right.
> > 
> > For example in this case, EACCES is returned by a cqe and EBADFD is
> > returned by io_uring_enter().
> > 
> > Should we create 2 error sections?
> 
> Yep, I think we should. One that describes that io_uring_enter() would
> return in terms of errors, and one that describes cqe->res returns.

Yeah, that would be much better!

> 
> Are you up for this? Would be a great change, making it a lot more
> accurate.

Sure! I'll prepare a patch with this change, and I'll also try to catch
all possible return values, then I'll rebase this series on top of that.

Thanks,
Stefano

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

[Jens Axboe]

On 9/14/20 10:02 AM, Stefano Garzarella wrote:
> On Mon, Sep 14, 2020 at 09:38:25AM -0600, Jens Axboe wrote:
>> On 9/14/20 2:05 AM, Stefano Garzarella wrote:
>>> On Fri, Sep 11, 2020 at 09:36:02AM -0600, Jens Axboe wrote:
>>>> On 9/11/20 7:34 AM, Stefano Garzarella wrote:
>>>>> 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>
>>>>> ---
>>>>>  man/io_uring_enter.2 | 18 ++++++++++++++++++
>>>>>  1 file changed, 18 insertions(+)
>>>>>
>>>>> diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
>>>>> index 5443d5f..4773dfd 100644
>>>>> --- a/man/io_uring_enter.2
>>>>> +++ b/man/io_uring_enter.2
>>>>> @@ -842,6 +842,16 @@ is set appropriately.
>>>>>  .PP
>>>>>  .SH ERRORS
>>>>>  .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 EAGAIN
>>>>>  The kernel was unable to allocate memory for the request, or otherwise ran out
>>>>>  of resources to handle it. The application should wait for some completions and
>>>>> @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
>>>>>  flag was set in the submission queue entry, but no files were registered
>>>>>  with the io_uring instance.
>>>>>  .TP
>>>>> +.B EBADFD
>>>>> +The
>>>>> +.I fd
>>>>> +field in the submission queue entry is valid, 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
>>>>
>>>> I actually think some of this needs general updating. io_uring_enter()
>>>> will not return an error on behalf of an sqe, it'll only return an error
>>>> if one happened outside the context of a specific sqe. Any error
>>>> specific to an sqe will generate a cqe with the result.
>>>
>>> Mmm, right.
>>>
>>> For example in this case, EACCES is returned by a cqe and EBADFD is
>>> returned by io_uring_enter().
>>>
>>> Should we create 2 error sections?
>>
>> Yep, I think we should. One that describes that io_uring_enter() would
>> return in terms of errors, and one that describes cqe->res returns.
> 
> Yeah, that would be much better!
> 
>>
>> Are you up for this? Would be a great change, making it a lot more
>> accurate.
> 
> Sure! I'll prepare a patch with this change, and I'll also try to catch
> all possible return values, then I'll rebase this series on top of that.

Awesome! It'll be a really nice improvement.

-- 
Jens Axboe