* [PATCH liburing 0/3] Add restrictions stuff in the man pages @ 2020-09-11 13:34 Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description Stefano Garzarella ` (2 more replies) 0 siblings, 3 replies; 11+ messages in thread From: Stefano Garzarella @ 2020-09-11 13:34 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH liburing 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description 2020-09-11 13:34 [PATCH liburing 0/3] Add restrictions stuff in the man pages Stefano Garzarella @ 2020-09-11 13:34 ` Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors Stefano Garzarella 2 siblings, 0 replies; 11+ messages in thread From: Stefano Garzarella @ 2020-09-11 13:34 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring This new flag is available starting from Linux 5.10. Signed-off-by: Stefano Garzarella <[email protected]> --- 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions 2020-09-11 13:34 [PATCH liburing 0/3] Add restrictions stuff in the man pages Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description Stefano Garzarella @ 2020-09-11 13:34 ` Stefano Garzarella 2020-09-11 15:33 ` Jens Axboe 2020-09-11 13:34 ` [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors Stefano Garzarella 2 siblings, 1 reply; 11+ messages in thread From: Stefano Garzarella @ 2020-09-11 13:34 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring 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 <[email protected]> --- 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions 2020-09-11 13:34 ` [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions Stefano Garzarella @ 2020-09-11 15:33 ` Jens Axboe 2020-09-14 8:02 ` Stefano Garzarella 0 siblings, 1 reply; 11+ messages in thread From: Jens Axboe @ 2020-09-11 15:33 UTC (permalink / raw) To: Stefano Garzarella; +Cc: io-uring 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 <[email protected]> > --- > 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions 2020-09-11 15:33 ` Jens Axboe @ 2020-09-14 8:02 ` Stefano Garzarella 0 siblings, 0 replies; 11+ messages in thread From: Stefano Garzarella @ 2020-09-14 8:02 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring 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 <[email protected]> > > --- > > 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-11 13:34 [PATCH liburing 0/3] Add restrictions stuff in the man pages Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions Stefano Garzarella @ 2020-09-11 13:34 ` Stefano Garzarella 2020-09-11 15:36 ` Jens Axboe 2 siblings, 1 reply; 11+ messages in thread From: Stefano Garzarella @ 2020-09-11 13:34 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring These new errors are added with the restriction series recently merged in io_uring (Linux 5.10). Signed-off-by: Stefano Garzarella <[email protected]> --- 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 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-11 13:34 ` [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors Stefano Garzarella @ 2020-09-11 15:36 ` Jens Axboe 2020-09-14 8:05 ` Stefano Garzarella 0 siblings, 1 reply; 11+ messages in thread From: Jens Axboe @ 2020-09-11 15:36 UTC (permalink / raw) To: Stefano Garzarella; +Cc: io-uring 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 <[email protected]> > --- > 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-11 15:36 ` Jens Axboe @ 2020-09-14 8:05 ` Stefano Garzarella 2020-09-14 15:38 ` Jens Axboe 0 siblings, 1 reply; 11+ messages in thread From: Stefano Garzarella @ 2020-09-14 8:05 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring 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 <[email protected]> > > --- > > 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-14 8:05 ` Stefano Garzarella @ 2020-09-14 15:38 ` Jens Axboe 2020-09-14 16:02 ` Stefano Garzarella 0 siblings, 1 reply; 11+ messages in thread From: Jens Axboe @ 2020-09-14 15:38 UTC (permalink / raw) To: Stefano Garzarella; +Cc: io-uring 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 <[email protected]> >>> --- >>> 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-14 15:38 ` Jens Axboe @ 2020-09-14 16:02 ` Stefano Garzarella 2020-09-15 1:35 ` Jens Axboe 0 siblings, 1 reply; 11+ messages in thread From: Stefano Garzarella @ 2020-09-14 16:02 UTC (permalink / raw) To: Jens Axboe; +Cc: io-uring 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 <[email protected]> > >>> --- > >>> 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors 2020-09-14 16:02 ` Stefano Garzarella @ 2020-09-15 1:35 ` Jens Axboe 0 siblings, 0 replies; 11+ messages in thread From: Jens Axboe @ 2020-09-15 1:35 UTC (permalink / raw) To: Stefano Garzarella; +Cc: io-uring 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 <[email protected]> >>>>> --- >>>>> 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2020-09-15 1:35 UTC | newest] Thread overview: 11+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-09-11 13:34 [PATCH liburing 0/3] Add restrictions stuff in the man pages Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 1/3] man/io_uring_setup.2: add IORING_SETUP_R_DISABLED description Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 2/3] man/io_uring_register.2: add description of restrictions Stefano Garzarella 2020-09-11 15:33 ` Jens Axboe 2020-09-14 8:02 ` Stefano Garzarella 2020-09-11 13:34 ` [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors Stefano Garzarella 2020-09-11 15:36 ` Jens Axboe 2020-09-14 8:05 ` Stefano Garzarella 2020-09-14 15:38 ` Jens Axboe 2020-09-14 16:02 ` Stefano Garzarella 2020-09-15 1:35 ` Jens Axboe
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox