[PATCH liburing 1/1] man: add io_uring_register_region.3

[PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

Describe the region API. As it was created for a bunch of ideas in mind,
it doesn't go into details about wait argument passing, which I assume
will be a separate page the region description can refer to.

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_register_region.3 | 123 +++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 man/io_uring_register_region.3

diff --git a/man/io_uring_register_region.3 b/man/io_uring_register_region.3
new file mode 100644
index 00000000..06ebd466
--- /dev/null
+++ b/man/io_uring_register_region.3
@@ -0,0 +1,123 @@
+.\" Copyright (C) 2026 Pavel Begunkov <asml.silence@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_region 3 "Jan 13, 2026" "liburing-2.14" "liburing Manual"
+.SH NAME
+io_uring_register_region \- register a memory region
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_region(struct io_uring *" ring ",
+.BI "                             struct io_uring_mem_region_reg *" reg ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_region (3)
+function registers a memory region to io_uring. The memory region can after be
+used, for example, to pass waiting parameters to the
+.BR io_uring_enter (2)
+system call in an efficient manner. The
+.IR ring
+argument should point to the ring in question, and the
+.IR reg
+argument should be a pointer to a
+.B struct io_uring_mem_region_reg .
+
+The
+.IR reg
+argument must be filled in with the appropriate information. It looks as
+follows:
+.PP
+.in +4n
+.EX
+struct io_uring_mem_region_reg {
+    __u64 region_uptr;
+    __u64 flags;
+    __u64 __resv[2];
+};
+.EE
+.in
+.PP
+The
+.I region_uptr
+field must contain a pointer to an appropriately filled
+.B struct io_uring_region_desc.
+.PP
+The
+.I flags
+field must contain a bitmask of the following values:
+.TP
+.B IORING_MEM_REGION_REG_WAIT_ARG
+allows to use the region topass waiting parameters to the
+.BR io_uring_enter (2)
+system call. If set, the registration is only allowed while the ring
+is in a disabled mode. See
+.B IORING_SETUP_R_DISABLED.
+.PP
+The __resv fields must be filled with zeroes.
+
+.PP
+.B struct io_uring_region_desc
+is defined as following:
+.PP
+.in +4n
+.EX
+struct io_uring_region_desc {
+    __u64 user_addr;
+    __u64 size;
+    __u32 flags;
+    __u32 id;
+    __u64 mmap_offset;
+    __u64 __resv[4];
+};
+.EE
+.in
+
+.PP
+The
+.I user_addr
+field must contain a pointer to the memory the user wants to register. It's
+only valid if
+.B IORING_MEM_REGION_TYPE_USER
+is set, and should be zero otherwise.
+
+.PP
+The
+.I size
+field should contain the size of the region.
+
+The
+.I flags
+field must contain a bitmask of the following values:
+.TP
+.B IORING_MEM_REGION_TYPE_USER
+tells the kernel to use memory specified by the
+.I user_addr
+field. If not set, the kernel will allocate memory for the region, which can
+then be mapped into the user space.
+
+.PP
+On a successful registration of a region with kernel provided memory, the
+.I mmap_offset
+field will contain an offset that can be passed to the
+.B mmap(2)
+system call to map the region into the user space.
+
+The
+.I id
+field is reserved and must be set to zero.
+
+The
+.I __resv
+fields must be filled with zeroes.
+
+Available since kernel 6.13.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_region (3)
+returns 0. On failure it returns
+.BR -errno .
-- 
2.52.0

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Jens Axboe]

On Tue, 13 Jan 2026 20:05:05 +0000, Pavel Begunkov wrote:
> Describe the region API. As it was created for a bunch of ideas in mind,
> it doesn't go into details about wait argument passing, which I assume
> will be a separate page the region description can refer to.
> 
> 

Applied, thanks!

[1/1] man: add io_uring_register_region.3
      commit: 416ca5e33c07f8eb8a5bb83d10d4594cd2def528

Best regards,
-- 
Jens Axboe

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Gabriel Krisman Bertazi]

Pavel Begunkov <asml.silence@gmail.com> writes:

> Describe the region API. As it was created for a bunch of ideas in mind,
> it doesn't go into details about wait argument passing, which I assume
> will be a separate page the region description can refer to.
>

Hey, Pavel.


> diff --git a/man/io_uring_register_region.3 b/man/io_uring_register_region.3
> new file mode 100644
> index 00000000..06ebd466
> --- /dev/null
> +++ b/man/io_uring_register_region.3
> @@ -0,0 +1,123 @@
> +.\" Copyright (C) 2026 Pavel Begunkov <asml.silence@gmail.com>
> +.\"
> +.\" SPDX-License-Identifier: LGPL-2.0-or-later
> +.\"
> +.TH io_uring_register_region 3 "Jan 13, 2026" "liburing-2.14" "liburing Manual"
> +.SH NAME
> +io_uring_register_region \- register a memory region
> +.SH SYNOPSIS
> +.nf
> +.B #include <liburing.h>
> +.PP
> +.BI "int io_uring_register_region(struct io_uring *" ring ",
> +.BI "                             struct io_uring_mem_region_reg *" reg ");"
> +.fi
> +.SH DESCRIPTION
> +.PP
> +The
> +.BR io_uring_register_region (3)
> +function registers a memory region to io_uring. The memory region can after be
> +used, for example, to pass waiting parameters to the
> +.BR io_uring_enter (2)
> +system call in an efficient manner. The
> +.IR ring

.I ring

> +argument should point to the ring in question, and the
> +.IR reg

.I reg

> +argument should be a pointer to a
> +.B struct io_uring_mem_region_reg .

.IR  struct io_uring_mem_region_reg .

> +
> +The
> +.IR reg

.I reg

> +argument must be filled in with the appropriate information. It looks as
> +follows:
> +.PP
> +.in +4n
> +.EX
> +struct io_uring_mem_region_reg {
> +    __u64 region_uptr;
> +    __u64 flags;
> +    __u64 __resv[2];
> +};
> +.EE
> +.in
> +.PP
> +The
> +.I region_uptr
> +field must contain a pointer to an appropriately filled
> +.B struct io_uring_region_desc.

.IR struct io_uring_region_desc .

> +.PP
> +The
> +.I flags
> +field must contain a bitmask of the following values:
> +.TP
> +.B IORING_MEM_REGION_REG_WAIT_ARG
> +allows to use the region topass waiting parameters to the

"to pass"

> +.BR io_uring_enter (2)
> +system call. If set, the registration is only allowed while the ring
> +is in a disabled mode.

While the ring is disabled.

> + See
> +.B IORING_SETUP_R_DISABLED.

.BR IORING_SETUP_R_DISABLED .

> +.PP
> +The __resv fields must be filled with zeroes.
> +
> +.PP
> +.B struct io_uring_region_desc

.I struct io_uring_region_desc

> +is defined as following:
> +.PP
> +.in +4n
> +.EX
> +struct io_uring_region_desc {
> +    __u64 user_addr;
> +    __u64 size;
> +    __u32 flags;
> +    __u32 id;
> +    __u64 mmap_offset;
> +    __u64 __resv[4];
> +};
> +.EE
> +.in
> +
> +.PP
> +The
> +.I user_addr
> +field must contain a pointer to the memory the user wants to register. It's
> +only valid if
> +.B IORING_MEM_REGION_TYPE_USER
> +is set, and should be zero otherwise.

must be set to zero otherwise.

> +.PP
> +The
> +.I size
> +field should contain the size of the region.

must contain
> +
> +The
> +.I flags
> +field must contain a bitmask of the following values:
> +.TP
> +.B IORING_MEM_REGION_TYPE_USER
> +tells the kernel to use memory specified by the
> +.I user_addr
> +field. If not set, the kernel will allocate memory for the region, which can
> +then be mapped into the user space.
> +
> +.PP
> +On a successful registration of a region with kernel provided memory, the

"On success, the"

> +.I mmap_offset
> +field will contain an offset that can be passed to the
> +.B mmap(2)

.BR mmap (2)

> +system call to map the region into the user space.
> +
> +The
> +.I id
> +field is reserved and must be set to zero.
> +
> +The
> +.I __resv
> +fields must be filled with zeroes.
> +
> +Available since kernel 6.13.
> +
> +.SH RETURN VALUE
> +On success
> +.BR io_uring_register_region (3)
> +returns 0. On failure it returns
> +.BR -errno .

.I errno

-- 
Gabriel Krisman Bertazi

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Jens Axboe]

On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
> Pavel Begunkov <asml.silence@gmail.com> writes:
> 
>> Describe the region API. As it was created for a bunch of ideas in mind,
>> it doesn't go into details about wait argument passing, which I assume
>> will be a separate page the region description can refer to.
>>
> 
> Hey, Pavel.

I did a bunch of spelling and phrasing fixups when applying, can you
take a look at the repo and send a patch for the others? Thanks!

-- 
Jens Axboe

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/13/26 22:37, Jens Axboe wrote:
> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>
>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>> it doesn't go into details about wait argument passing, which I assume
>>> will be a separate page the region description can refer to.
>>>
>>
>> Hey, Pavel.
> 
> I did a bunch of spelling and phrasing fixups when applying, can you
> take a look at the repo and send a patch for the others? Thanks!

"Upon successful completion, the memory region may then be used, for
example, to pass waiting parameters to the io_uring_enter(2) system
call in a more efficient manner as it avoids copying wait related data
for each wait event."

Doesn't matter much, but this change is somewhat misleading. Both copy
args same number of times (i.e. unsafe_get_user() instead of
copy_from_user()), which is why I was a bit vague with that
"in an efficient manner".

-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/14/26 14:42, Pavel Begunkov wrote:
> On 1/13/26 22:37, Jens Axboe wrote:
>> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>>
>>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>>> it doesn't go into details about wait argument passing, which I assume
>>>> will be a separate page the region description can refer to.
>>>>
>>>
>>> Hey, Pavel.
>>
>> I did a bunch of spelling and phrasing fixups when applying, can you
>> take a look at the repo and send a patch for the others? Thanks!
> 
> "Upon successful completion, the memory region may then be used, for
> example, to pass waiting parameters to the io_uring_enter(2) system
> call in a more efficient manner as it avoids copying wait related data
> for each wait event."
> 
> Doesn't matter much, but this change is somewhat misleading. Both copy
> args same number of times (i.e. unsafe_get_user() instead of
> copy_from_user()), which is why I was a bit vague with that
> "in an efficient manner".

Hmm, actually the normal / non-registered way does make an extra
copy, even though it doesn't have to.

-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/14/26 14:54, Pavel Begunkov wrote:
> On 1/14/26 14:42, Pavel Begunkov wrote:
>> On 1/13/26 22:37, Jens Axboe wrote:
>>> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>>>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>>>
>>>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>>>> it doesn't go into details about wait argument passing, which I assume
>>>>> will be a separate page the region description can refer to.
>>>>>
>>>>
>>>> Hey, Pavel.
>>>
>>> I did a bunch of spelling and phrasing fixups when applying, can you
>>> take a look at the repo and send a patch for the others? Thanks!
>>
>> "Upon successful completion, the memory region may then be used, for
>> example, to pass waiting parameters to the io_uring_enter(2) system
>> call in a more efficient manner as it avoids copying wait related data
>> for each wait event."
>>
>> Doesn't matter much, but this change is somewhat misleading. Both copy
>> args same number of times (i.e. unsafe_get_user() instead of
>> copy_from_user()), which is why I was a bit vague with that
>> "in an efficient manner".
> 
> Hmm, actually the normal / non-registered way does make an extra
> copy, even though it doesn't have to.

And the compiler is smart enough to optimise it out since
it's all on stack.

-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Jens Axboe]

On 1/14/26 9:04 AM, Pavel Begunkov wrote:
> On 1/14/26 14:54, Pavel Begunkov wrote:
>> On 1/14/26 14:42, Pavel Begunkov wrote:
>>> On 1/13/26 22:37, Jens Axboe wrote:
>>>> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>>>>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>>>>
>>>>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>>>>> it doesn't go into details about wait argument passing, which I assume
>>>>>> will be a separate page the region description can refer to.
>>>>>>
>>>>>
>>>>> Hey, Pavel.
>>>>
>>>> I did a bunch of spelling and phrasing fixups when applying, can you
>>>> take a look at the repo and send a patch for the others? Thanks!
>>>
>>> "Upon successful completion, the memory region may then be used, for
>>> example, to pass waiting parameters to the io_uring_enter(2) system
>>> call in a more efficient manner as it avoids copying wait related data
>>> for each wait event."
>>>
>>> Doesn't matter much, but this change is somewhat misleading. Both copy
>>> args same number of times (i.e. unsafe_get_user() instead of
>>> copy_from_user()), which is why I was a bit vague with that
>>> "in an efficient manner".
>>
>> Hmm, actually the normal / non-registered way does make an extra
>> copy, even though it doesn't have to.
> 
> And the compiler is smart enough to optimise it out since
> it's all on stack.

Not sure I follow these emails. For the normal case,
io_validate_ext_arg() copies in the args via a normal user copy, which
depending on options and the arch (or even sub-arch, amd more expensive)
is more or less expensive. For the registered case, it's a simple memory
dereference. Doesn't cover the signal parts as I believe those are way
less commonly used.

-- 
Jens Axboe

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/14/26 17:23, Jens Axboe wrote:
> On 1/14/26 9:04 AM, Pavel Begunkov wrote:
>> On 1/14/26 14:54, Pavel Begunkov wrote:
>>> On 1/14/26 14:42, Pavel Begunkov wrote:
>>>> On 1/13/26 22:37, Jens Axboe wrote:
>>>>> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>>>>>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>>>>>
>>>>>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>>>>>> it doesn't go into details about wait argument passing, which I assume
>>>>>>> will be a separate page the region description can refer to.
>>>>>>>
>>>>>>
>>>>>> Hey, Pavel.
>>>>>
>>>>> I did a bunch of spelling and phrasing fixups when applying, can you
>>>>> take a look at the repo and send a patch for the others? Thanks!
>>>>
>>>> "Upon successful completion, the memory region may then be used, for
>>>> example, to pass waiting parameters to the io_uring_enter(2) system
>>>> call in a more efficient manner as it avoids copying wait related data
>>>> for each wait event."
>>>>
>>>> Doesn't matter much, but this change is somewhat misleading. Both copy
>>>> args same number of times (i.e. unsafe_get_user() instead of
>>>> copy_from_user()), which is why I was a bit vague with that
>>>> "in an efficient manner".
>>>
>>> Hmm, actually the normal / non-registered way does make an extra
>>> copy, even though it doesn't have to.
>>
>> And the compiler is smart enough to optimise it out since
>> it's all on stack.
> 
> Not sure I follow these emails. For the normal case,
> io_validate_ext_arg() copies in the args via a normal user copy, which
> depending on options and the arch (or even sub-arch, amd more expensive)
> is more or less expensive.

In the end, after prep that is still just a move instruction, e.g.
for x86. And it loads into a register and stores it into ext_arg,
just like with registration. User copy needs to prepare page fault
handling / etc., which could be costly (e.g. I see stac + lfence
in asm), but that's not exactly about avoiding copies.

> For the registered case, it's a simple memory
> dereference. Doesn't cover the signal parts as I believe those are way
> less commonly used.
-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Jens Axboe]

On 1/14/26 11:50 AM, Pavel Begunkov wrote:
> On 1/14/26 17:23, Jens Axboe wrote:
>> On 1/14/26 9:04 AM, Pavel Begunkov wrote:
>>> On 1/14/26 14:54, Pavel Begunkov wrote:
>>>> On 1/14/26 14:42, Pavel Begunkov wrote:
>>>>> On 1/13/26 22:37, Jens Axboe wrote:
>>>>>> On 1/13/26 2:31 PM, Gabriel Krisman Bertazi wrote:
>>>>>>> Pavel Begunkov <asml.silence@gmail.com> writes:
>>>>>>>
>>>>>>>> Describe the region API. As it was created for a bunch of ideas in mind,
>>>>>>>> it doesn't go into details about wait argument passing, which I assume
>>>>>>>> will be a separate page the region description can refer to.
>>>>>>>>
>>>>>>>
>>>>>>> Hey, Pavel.
>>>>>>
>>>>>> I did a bunch of spelling and phrasing fixups when applying, can you
>>>>>> take a look at the repo and send a patch for the others? Thanks!
>>>>>
>>>>> "Upon successful completion, the memory region may then be used, for
>>>>> example, to pass waiting parameters to the io_uring_enter(2) system
>>>>> call in a more efficient manner as it avoids copying wait related data
>>>>> for each wait event."
>>>>>
>>>>> Doesn't matter much, but this change is somewhat misleading. Both copy
>>>>> args same number of times (i.e. unsafe_get_user() instead of
>>>>> copy_from_user()), which is why I was a bit vague with that
>>>>> "in an efficient manner".
>>>>
>>>> Hmm, actually the normal / non-registered way does make an extra
>>>> copy, even though it doesn't have to.
>>>
>>> And the compiler is smart enough to optimise it out since
>>> it's all on stack.
>>
>> Not sure I follow these emails. For the normal case,
>> io_validate_ext_arg() copies in the args via a normal user copy, which
>> depending on options and the arch (or even sub-arch, amd more expensive)
>> is more or less expensive.
> 
> In the end, after prep that is still just a move instruction, e.g.
> for x86. And it loads into a register and stores it into ext_arg,
> just like with registration. User copy needs to prepare page fault
> handling / etc., which could be costly (e.g. I see stac + lfence
> in asm), but that's not exactly about avoiding copies.

Those are implementation details. The user copy is stac/clac, and then
the loads. This is what makes it more expensive. I don't want to be
writing about stac/clac in the man page, that's irrelevant to the user.

-- 
Jens Axboe

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/14/26 23:53, Jens Axboe wrote:
...
>>>> And the compiler is smart enough to optimise it out since
>>>> it's all on stack.
>>>
>>> Not sure I follow these emails. For the normal case,
>>> io_validate_ext_arg() copies in the args via a normal user copy, which
>>> depending on options and the arch (or even sub-arch, amd more expensive)
>>> is more or less expensive.
>>
>> In the end, after prep that is still just a move instruction, e.g.
>> for x86. And it loads into a register and stores it into ext_arg,
>> just like with registration. User copy needs to prepare page fault
>> handling / etc., which could be costly (e.g. I see stac + lfence
>> in asm), but that's not exactly about avoiding copies.
> 
> Those are implementation details. The user copy is stac/clac, and then
> the loads. This is what makes it more expensive. I don't want to be
> writing about stac/clac in the man page, that's irrelevant to the user.

Confused why would you be thinking about putting that into the
man page. I'm saying that it claims copy avoidance, but there is
no difference in the number of copies. It's also uncomfortable
that it's in a commit with my name attached, while the change
wouldn't fall under the "language edits" note.

-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Jens Axboe]

On 1/15/26 6:06 AM, Pavel Begunkov wrote:
> On 1/14/26 23:53, Jens Axboe wrote:
> ...
>>>>> And the compiler is smart enough to optimise it out since
>>>>> it's all on stack.
>>>>
>>>> Not sure I follow these emails. For the normal case,
>>>> io_validate_ext_arg() copies in the args via a normal user copy, which
>>>> depending on options and the arch (or even sub-arch, amd more expensive)
>>>> is more or less expensive.
>>>
>>> In the end, after prep that is still just a move instruction, e.g.
>>> for x86. And it loads into a register and stores it into ext_arg,
>>> just like with registration. User copy needs to prepare page fault
>>> handling / etc., which could be costly (e.g. I see stac + lfence
>>> in asm), but that's not exactly about avoiding copies.
>>
>> Those are implementation details. The user copy is stac/clac, and then
>> the loads. This is what makes it more expensive. I don't want to be
>> writing about stac/clac in the man page, that's irrelevant to the user.
> 
> Confused why would you be thinking about putting that into the
> man page. I'm saying that it claims copy avoidance, but there is
> no difference in the number of copies. It's also uncomfortable
> that it's in a commit with my name attached, while the change
> wouldn't fall under the "language edits" note.

Sheesh let's turn down the sensitivity. If you want it changed, send a
patch. I'm trying to phrase it in such a way that it makes sense to
people without getting into too much detail. It avoids copying from
USERSPACE, which is the expensive part.

I think we've spent enough time on this detail at this point, no?

-- 
Jens Axboe

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/15/26 14:14, Jens Axboe wrote:
> On 1/15/26 6:06 AM, Pavel Begunkov wrote:
>> On 1/14/26 23:53, Jens Axboe wrote:
>> ...
>>>>>> And the compiler is smart enough to optimise it out since
>>>>>> it's all on stack.
>>>>>
>>>>> Not sure I follow these emails. For the normal case,
>>>>> io_validate_ext_arg() copies in the args via a normal user copy, which
>>>>> depending on options and the arch (or even sub-arch, amd more expensive)
>>>>> is more or less expensive.
>>>>
>>>> In the end, after prep that is still just a move instruction, e.g.
>>>> for x86. And it loads into a register and stores it into ext_arg,
>>>> just like with registration. User copy needs to prepare page fault
>>>> handling / etc., which could be costly (e.g. I see stac + lfence
>>>> in asm), but that's not exactly about avoiding copies.
>>>
>>> Those are implementation details. The user copy is stac/clac, and then
>>> the loads. This is what makes it more expensive. I don't want to be
>>> writing about stac/clac in the man page, that's irrelevant to the user.
>>
>> Confused why would you be thinking about putting that into the
>> man page. I'm saying that it claims copy avoidance, but there is
>> no difference in the number of copies. It's also uncomfortable
>> that it's in a commit with my name attached, while the change
>> wouldn't fall under the "language edits" note.
> 
> Sheesh let's turn down the sensitivity. If you want it changed, send a

Not sure what kind of sensitivity you mean, but no worries, there
wasn't any. I still believe, however, that technicalities like in
this case matter.

> patch. I'm trying to phrase it in such a way that it makes sense to
> people without getting into too much detail. It avoids copying from
> USERSPACE, which is the expensive part.
> 
> I think we've spent enough time on this detail at this point, no?

-- 
Pavel Begunkov

Re: [PATCH liburing 1/1] man: add io_uring_register_region.3

[Pavel Begunkov]

On 1/13/26 21:31, Gabriel Krisman Bertazi wrote:
> Pavel Begunkov <asml.silence@gmail.com> writes:
> 
>> Describe the region API. As it was created for a bunch of ideas in mind,
>> it doesn't go into details about wait argument passing, which I assume
>> will be a separate page the region description can refer to.
>>
> 
> Hey, Pavel.

Hey Gabriel,

thanks for taking a look

...
>> +.BR io_uring_register_region (3)
>> +function registers a memory region to io_uring. The memory region can after be
>> +used, for example, to pass waiting parameters to the
>> +.BR io_uring_enter (2)
>> +system call in an efficient manner. The
>> +.IR ring
> 
> .I ring

I copied most of the macro choices from another liburing man
page, I can't say if diverging them worth it and/or what is
more commonly used. But in either case, I don't have any
opinion on that.

...
>> +.I region_uptr
>> +field must contain a pointer to an appropriately filled
>> +.B struct io_uring_region_desc.
> 
> .IR struct io_uring_region_desc .
> 
>> +.PP
>> +The
>> +.I flags
>> +field must contain a bitmask of the following values:
>> +.TP
>> +.B IORING_MEM_REGION_REG_WAIT_ARG
>> +allows to use the region topass waiting parameters to the
> 
> "to pass"

Oops, slipped through, thanks!

>> +.BR io_uring_enter (2)
>> +system call. If set, the registration is only allowed while the ring
>> +is in a disabled mode.
> 
> While the ring is disabled.

I was thinking that "disabled state" is clearer, but I guess doesn't
really matter, especially since R_DISABLED is mentioned.


>> +.I user_addr
>> +field must contain a pointer to the memory the user wants to register. It's
>> +only valid if
>> +.B IORING_MEM_REGION_TYPE_USER
>> +is set, and should be zero otherwise.
> 
> must be set to zero otherwise.

Agreed, "must" is more appropriate here.

...
>> +The
>> +.I flags
>> +field must contain a bitmask of the following values:
>> +.TP
>> +.B IORING_MEM_REGION_TYPE_USER
>> +tells the kernel to use memory specified by the
>> +.I user_addr
>> +field. If not set, the kernel will allocate memory for the region, which can
>> +then be mapped into the user space.
>> +
>> +.PP
>> +On a successful registration of a region with kernel provided memory, the
> 
> "On success, the"

The "kernel provided memory" part is important here, which is why the
sentence is expanded.

-- 
Pavel Begunkov