[DRAFT liburing] man: document new register/update API

[DRAFT liburing] man: document new register/update API

[Pavel Begunkov]

Document
- IORING_REGISTER_FILES2
- IORING_REGISTER_FILES_UPDATE2,
- IORING_REGISTER_BUFFERS2
- IORING_REGISTER_BUFFERS_UPDATE,

And add a couple of words on registered resources (buffers, files)
tagging.

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---

Most likely there is a bunch of silly typos, half-edited phrases and
mixed "buffer" with "file". Draft, will proof-read later.

 man/io_uring_register.2 | 141 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 140 insertions(+), 1 deletion(-)

diff --git a/man/io_uring_register.2 b/man/io_uring_register.2
index a8479fd..ac99847 100644
--- a/man/io_uring_register.2
+++ b/man/io_uring_register.2
@@ -95,6 +95,92 @@ wait for those to finish before proceeding.
 An application need not unregister buffers explicitly before shutting
 down the io_uring instance. Available since 5.1.
 
+.TP
+.B IORING_REGISTER_BUFFERS2
+Register buffers for I/O. similar to
+.B IORING_REGISTER_BUFFERS
+but aims to have a more extensible ABI.
+
+.I arg
+points to a
+.I struct io_uring_rsrc_register,
+.I nr_args
+should be set to the number of bytes in the structure.
+
+Field
+.I data
+contains a pointer to a
+.I struct iovec
+array of
+.I nr
+entries.
+.I tags
+field should either be 0, then tagging is disabled, or point to an array
+of
+.I nr
+"tags" (unsigned 64 bit integers). If a tag is zero, then tagging for this
+particular resource (a buffer in this case) is disabled. Otherwise, after the
+resource had been unregistered and it's not anymore used, a CQE will be
+posted with
+.I user_data
+set to the specified tag and all other fields zeroed.
+
+Note that resource updates, e.g.
+.B IORING_REGISTER_BUFFERS_UPDATE,
+don't necessarily deallocates resources by the time it returns, but they might
+be hold alive until all requests using it complete.
+
+Available since 5.13.
+
+.PP
+.in +8n
+.EX
+struct io_uring_rsrc_register {
+    __u32 nr;
+    __u32 resv;
+    __u64 resv2;
+    __aligned_u64 data;
+    __aligned_u64 tags;
+};
+
+.EE
+.in
+.PP
+
+.TP
+.B IORING_REGISTER_BUFFERS_UPDATE
+Updates registered buffers with new ones, either turning a sparse entry into
+a real one, or replacing an existing entry.
+
+.I arg
+must contain a pointer to a struct io_uring_files_update2, which contains
+an offset on which to start the update, and an array of
+.I struct iovec.
+.I tags
+points to an array of tags, for resource tagging description see
+.B IORING_REGISTER_BUFFERS2.
+.I nr
+must contain the number of descriptors in the passed in arrays.
+
+Available since 5.13.
+
+.PP
+.in +8n
+.EX
+
+struct io_uring_rsrc_update2 {
+    __u32 offset;
+    __u32 resv;
+    __aligned_u64 data;
+    __aligned_u64 tags;
+    __u32 nr;
+    __u32 resv2;
+};
+.EE
+.in
+.PP
+
+
 .TP
 .B IORING_UNREGISTER_BUFFERS
 This operation takes no argument, and
@@ -138,6 +224,36 @@ Files are automatically unregistered when the io_uring instance is
 torn down. An application need only unregister if it wishes to
 register a new set of fds. Available since 5.1.
 
+.TP
+.B IORING_REGISTER_FILES2
+Register files for I/O. similar to
+.B IORING_REGISTER_FILES.
+
+.I arg
+points to a
+.I struct io_uring_rsrc_register,
+.I nr_args
+should be set to the number of bytes in the structure.
+
+Field
+.I data
+contains a pointer to an array of
+.I nr
+file descriptors (signed 32 bit integers).
+.I tags
+field should either be 0 or or point to an array of
+.I nr
+"tags" (unsigned 64 bit integers). See
+.B IORING_REGISTER_BUFFERS2
+for more info on resource tagging.
+
+Note that resource updates, e.g.
+.B IORING_REGISTER_FILES_UPDATE,
+don't necessarily deallocates resources, but might hold it until all
+requests using it complete.
+
+Available since 5.13.
+
 .TP
 .B IORING_REGISTER_FILES_UPDATE
 This operation replaces existing files in the registered file set with new
@@ -146,7 +262,9 @@ real one, removing an existing entry (new one is set to -1), or replacing
 an existing entry with a new existing entry.
 
 .I arg
-must contain a pointer to a struct io_uring_files_update, which contains
+must contain a pointer to a
+.I struct io_uring_files_update,
+which contains
 an offset on which to start the update, and an array of file descriptors to
 use for the update.
 .I nr_args
@@ -158,6 +276,27 @@ File descriptors can be skipped if they are set to
 Skipping an fd will not touch the file associated with the previous
 fd at that index. Available since 5.12.
 
+.TP
+.B IORING_REGISTER_FILES_UPDATE2
+Similar to IORING_REGISTER_FILES_UPDATE, replaces existing files in the
+registered file set with new ones, either turning a sparse entry (one where
+fd is equal to -1) into a real one, removing an existing entry (new one is
+set to -1), or replacing an existing entry with a new existing entry.
+
+.I arg
+must contain a pointer to a
+.I struct io_uring_files_update2,
+which contains
+an offset on which to start the update, and an array of file descriptors to
+use for the update stored in
+.I data.
+.I tags
+points to an array of tags, for resource tagging description see
+.B IORING_REGISTER_BUFFERS2.
+.I nr
+must contain the number of descriptors in the passed in arrays.
+
+Available since 5.13.
 
 .TP
 .B IORING_UNREGISTER_FILES
-- 
2.33.0

Re: [DRAFT liburing] man: document new register/update API

[Jens Axboe]

On 8/28/21 1:18 PM, Pavel Begunkov wrote:
> Document
> - IORING_REGISTER_FILES2
> - IORING_REGISTER_FILES_UPDATE2,
> - IORING_REGISTER_BUFFERS2
> - IORING_REGISTER_BUFFERS_UPDATE,
> 
> And add a couple of words on registered resources (buffers, files)
> tagging.

Just a few comments below.

> @@ -95,6 +95,92 @@ wait for those to finish before proceeding.
>  An application need not unregister buffers explicitly before shutting
>  down the io_uring instance. Available since 5.1.
>  
> +.TP
> +.B IORING_REGISTER_BUFFERS2
> +Register buffers for I/O. similar to
> +.B IORING_REGISTER_BUFFERS
> +but aims to have a more extensible ABI.
> +
> +.I arg
> +points to a
> +.I struct io_uring_rsrc_register,
> +.I nr_args
> +should be set to the number of bytes in the structure.
> +
> +Field
> +.I data

I'd do:

The
.I data
field contains...

> +contains a pointer to a
> +.I struct iovec
> +array of
> +.I nr
> +entries.
> +.I tags
> +field should either be 0, then tagging is disabled, or point to an array

The
.I tags
field shoud be...

> +Note that resource updates, e.g.
> +.B IORING_REGISTER_BUFFERS_UPDATE,
> +don't necessarily deallocates resources by the time it returns, but they might

deallocate

> +be hold alive until all requests using it complete.

s/hold/held

> +
> +Available since 5.13.
> +
> +.PP
> +.in +8n
> +.EX
> +struct io_uring_rsrc_register {
> +    __u32 nr;
> +    __u32 resv;
> +    __u64 resv2;
> +    __aligned_u64 data;
> +    __aligned_u64 tags;
> +};

Move this up to where it's initially mentioned?

> @@ -138,6 +224,36 @@ Files are automatically unregistered when the io_uring instance is
>  torn down. An application need only unregister if it wishes to
>  register a new set of fds. Available since 5.1.
>  
> +.TP
> +.B IORING_REGISTER_FILES2
> +Register files for I/O. similar to
> +.B IORING_REGISTER_FILES.
> +
> +.I arg
> +points to a
> +.I struct io_uring_rsrc_register,
> +.I nr_args
> +should be set to the number of bytes in the structure.
> +
> +Field
> +.I data

The
.I data
field

> +contains a pointer to an array of
> +.I nr
> +file descriptors (signed 32 bit integers).
> +.I tags
> +field should either be 0 or or point to an array of
> +.I nr
> +"tags" (unsigned 64 bit integers). See
> +.B IORING_REGISTER_BUFFERS2
> +for more info on resource tagging.
> +
> +Note that resource updates, e.g.
> +.B IORING_REGISTER_FILES_UPDATE,
> +don't necessarily deallocates resources, but might hold it until all

deallocate

Just minor stuff, apart from that looks pretty good to me.

-- 
Jens Axboe

Re: [DRAFT liburing] man: document new register/update API

[Pavel Begunkov]

On 8/28/21 8:35 PM, Jens Axboe wrote:
> On 8/28/21 1:18 PM, Pavel Begunkov wrote:
>> Document
>> - IORING_REGISTER_FILES2
>> - IORING_REGISTER_FILES_UPDATE2,
>> - IORING_REGISTER_BUFFERS2
>> - IORING_REGISTER_BUFFERS_UPDATE,
>>
>> And add a couple of words on registered resources (buffers, files)
>> tagging.
> 
> Just a few comments below.

Thanks for taking a look, not going to pretend that I'm good at it :)

[...]

>> +.PP
>> +.in +8n
>> +.EX
>> +struct io_uring_rsrc_register {
>> +    __u32 nr;
>> +    __u32 resv;
>> +    __u64 resv2;
>> +    __aligned_u64 data;
>> +    __aligned_u64 tags;
>> +};
> 
> Move this up to where it's initially mentioned?

Do you mean a couple of lines up? like this? 

.I arg
points to a
.I struct io_uring_rsrc_register.

<struct definition section>

.I nr_args
should be set to the number of bytes in the structure.

-- 
Pavel Begunkov

Re: [DRAFT liburing] man: document new register/update API

[Jens Axboe]

On 8/31/21 10:38 AM, Pavel Begunkov wrote:
> On 8/28/21 8:35 PM, Jens Axboe wrote:
>> On 8/28/21 1:18 PM, Pavel Begunkov wrote:
>>> Document
>>> - IORING_REGISTER_FILES2
>>> - IORING_REGISTER_FILES_UPDATE2,
>>> - IORING_REGISTER_BUFFERS2
>>> - IORING_REGISTER_BUFFERS_UPDATE,
>>>
>>> And add a couple of words on registered resources (buffers, files)
>>> tagging.
>>
>> Just a few comments below.
> 
> Thanks for taking a look, not going to pretend that I'm good at it :)
> 
> [...]
> 
>>> +.PP
>>> +.in +8n
>>> +.EX
>>> +struct io_uring_rsrc_register {
>>> +    __u32 nr;
>>> +    __u32 resv;
>>> +    __u64 resv2;
>>> +    __aligned_u64 data;
>>> +    __aligned_u64 tags;
>>> +};
>>
>> Move this up to where it's initially mentioned?
> 
> Do you mean a couple of lines up? like this? 

Yeah, just move it where it's first described.

-- 
Jens Axboe