1 files changed, 139 insertions, 0 deletions
diff --git a/man/io_uring_register_buf_ring.3 b/man/io_uring_register_buf_ring.3
new file mode 100644
index 0000000..9e520bf
--- /dev/null
+++ b/man/io_uring_register_buf_ring.3
@@ -0,0 +1,139 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_register_buf_ring \- register buffer ring for provided buffers
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_buf_ring(struct io_uring *" ring ",
+.BI "                               struct io_uring_buf_reg *" reg ",
+.BI "                               unsigned int " flags ");"
+.BI "
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_buf_ring (3)
+function registers a shared buffer ring to be used with provided buffers. For
+the request types that support it, provided buffers are given to the ring and
+one is selected by a request if it has
+.B IOSQE_BUFFER_SELECT
+set in the SQE
+.IR flags ,
+when the request is ready to receive data. This allows both clear ownership
+of the buffer lifetime, and a way to have more read/receive type of operations
+in flight than buffers available.
+
+The
+.I reg
+argument must be filled in with the appropriate information. It looks as
+follows:
+.PP
+.in +4n
+.EX
+struct io_uring_buf_reg {
+    __u64 ring_addr;
+    __u32 ring_entries;
+    __u16 bgid;
+    __u16 pad;
+    __u64 resv[3];
+};
+.EE
+.in
+.PP
+The
+.I ring_addr
+field must contain the address to the memory allocated to fit this ring.
+The memory must be page aligned and hence allocated appropriately using eg
+.BR posix_memalign (3)
+or similar. The size of the ring is the product of
+.I ring_entries
+and the size of
+.IR "struct io_uring_buf" .
+.I ring_entries
+is the desired size of the ring, and must be a power-of-2 in size.
+.I bgid
+is the buffer group ID associated with this ring. SQEs that select a buffer
+has a buffer group associated with them in their
+.I buf_group
+field, and the associated CQE will have
+.B IORING_CQE_F_BUFFER
+set in their
+.I flags
+member, which will also contain the specific ID of the buffer seleted. The rest
+of the fields are reserved and must be cleared to zero.
+
+The
+.I flags
+argument is currently unused and must be set to zero.
+
+A shared buffer ring looks as follows:
+.PP
+.in +4n
+.EX
+struct io_uring_buf_ring {
+    union {
+	struct {
+            __u64 resv1;
+            __u32 resv2;
+            __u16 resv3;
+            __u16 tail;
+	};
+	struct io_uring_buf bufs[0];
+    };
+};
+.EE
+.in
+.PP
+where
+.I tail
+is the index at which the application can insert new buffers for consumption
+by requests, and
+.I struct io_uring_buf
+is buffer definition:
+.PP
+.in +4n
+.EX
+struct io_uring_buf {
+    __u64 addr;
+    __u32 len;
+    __u16 bid;
+    __u16 resv;
+};
+.EE
+.in
+.PP
+where
+.I addr
+is the address for the buffer,
+.I len
+is the length of the buffer in bytes, and
+.I bid
+is the buffer ID that will be returned in the CQE once consumed.
+
+Reserved fields must not be touched. Applications must use
+.BR io_uring_buf_ring_init (3)
+to initialise the buffer ring. Applications may use
+.BR io_uring_buf_ring_add (3)
+and
+.BR io_uring_buf_ring_advance (3)
+or
+.BR io_uring_buf_ring_advance (3)
+to provide buffers, which will set these fields and update the tail.
+
+Available since 5.19.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_buf_ring (3)
+returns 0. On failure it returns
+.BR -errno .
+.SH SEE ALSO
+.BR io_uring_buf_ring_init (3),
+.BR io_uring_buf_ring_add (3),
+.BR io_uring_buf_ring_advance (3),
+.BR io_uring_buf_ring_cq_advance (3)