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

[Pavel Begunkov <asml.silence@gmail.com>]

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