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@xxxxxxxxx>
---
v2: bunch of small changes (Jens)
fix incorrect struct names
man/io_uring_register.2 | 151 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 150 insertions(+), 1 deletion(-)
diff --git a/man/io_uring_register.2 b/man/io_uring_register.2
index a17e411..1a348d1 100644
--- a/man/io_uring_register.2
+++ b/man/io_uring_register.2
@@ -95,6 +95,99 @@ 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,
+and
+.I nr_args
+should be set to the number of bytes in the structure.
+
+.PP
+.in +8n
+.EX
+struct io_uring_rsrc_register {
+ __u32 nr;
+ __u32 resv;
+ __u64 resv2;
+ __aligned_u64 data;
+ __aligned_u64 tags;
+};
+
+.EE
+.in
+.PP
+
+.in +8n
+
+The
+.I data
+field contains a pointer to a
+.I struct iovec
+array of
+.I nr
+entries.
+The
+.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 deallocate resources by the time it returns, but they might
+be held alive until all requests using it complete.
+
+Available since 5.13.
+
+.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_rsrc_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.
+.I nr
+must contain the number of descriptors in the passed in arrays.
+See
+.B IORING_REGISTER_BUFFERS2
+for the resource tagging description.
+
+.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
+
+.in +8n
+
+Available since 5.13.
+
.TP
.B IORING_UNREGISTER_BUFFERS
This operation takes no argument, and
@@ -138,6 +231,37 @@ 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,
+and
+.I nr_args
+should be set to the number of bytes in the structure.
+
+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 deallocate 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 +270,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 +284,29 @@ 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_rsrc_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.
+.I nr
+must contain the number of descriptors in the passed in arrays.
+See
+.B IORING_REGISTER_BUFFERS2
+for the resource tagging description.
+
+Available since 5.13.
.TP
.B IORING_UNREGISTER_FILES
--
2.33.0
