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

* [DRAFT liburing] man: document new register/update API
@ 2021-08-28 19:18 Pavel Begunkov
  2021-08-28 19:35 ` Jens Axboe
  0 siblings, 1 reply; 4+ messages in thread
From: Pavel Begunkov @ 2021-08-28 19:18 UTC (permalink / raw)
  To: Jens Axboe, io-uring

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


^ permalink raw reply related	[flat|nested] 4+ messages in thread