Re: [DRAFT liburing] man: document new register/update API
From: Jens Axboe <axboe@kernel.dk>
Date: 2021-08-28 19:35:55
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.
quoted hunk ↗ jump to hunk
@@ -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?
quoted hunk ↗ jump to hunk
@@ -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