summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJens Axboe <axboe@kernel.dk>2022-05-18 14:16:32 -0600
committerJens Axboe <axboe@kernel.dk>2022-05-18 14:24:54 -0600
commitf01ed8b0037457ff845adecb39a01540eaa332c0 (patch)
treea648b45817e20defed6c6cf7bc690a902e5e2d3f
parentc41c48558809e9332afe99f6665ed488b1634ac0 (diff)
downloadliburing-f01ed8b0037457ff845adecb39a01540eaa332c0.tar.gz
liburing-f01ed8b0037457ff845adecb39a01540eaa332c0.tar.bz2
Add man pages for shared provided buffer rings
Signed-off-by: Jens Axboe <axboe@kernel.dk>
-rw-r--r--man/io_uring_buf_ring_add.347
-rw-r--r--man/io_uring_buf_ring_advance.330
-rw-r--r--man/io_uring_buf_ring_cq_advance.340
-rw-r--r--man/io_uring_register_buf_ring.3133
-rw-r--r--man/io_uring_unregister_buf_ring.330
5 files changed, 280 insertions, 0 deletions
diff --git a/man/io_uring_buf_ring_add.3 b/man/io_uring_buf_ring_add.3
new file mode 100644
index 0000000..7fd751e
--- /dev/null
+++ b/man/io_uring_buf_ring_add.3
@@ -0,0 +1,47 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_buf_ring_add 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_buf_ring_add - add buffers to a shared buffer ring
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_buf_ring_add(struct io_uring_buf_ring *" br ",
+.BI " void *" addr ",
+.BI " unsigned int " len ",
+.BI " unsigned short " bid ",
+.BI " int " buf_offset ");"
+.PP
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_buf_ring_add (3)
+adds a new buffer to the shared buffer ring
+.I br.
+The buffer address is indicated by
+.I addr
+and is of
+.I len
+bytes of length.
+.I bid
+is the buffer ID, which will be returned in the CQE.
+.I buf_offset
+is the offset to insert at from the current tail. If just one buffer is provided
+before the ring tail is committed with
+.BR io_uring_buf_ring_advance (3)
+or
+.BR io_uring_buf_ring_cq_advance (3),
+then
+.I buf_offset
+should be 0. If buffers are provided in a loop before being committed, the
+.I buf_offset
+must be incremented by one for each buffer added.
+
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_register_buf_ring (3), io_uring_buf_ring_advance (3), io_uring_buf_ring_cq_advance (3)
diff --git a/man/io_uring_buf_ring_advance.3 b/man/io_uring_buf_ring_advance.3
new file mode 100644
index 0000000..60c16a1
--- /dev/null
+++ b/man/io_uring_buf_ring_advance.3
@@ -0,0 +1,30 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_buf_ring_advance 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_buf_ring_advance - advance index of provided buffer in buffer ring
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_buf_ring_advance(struct io_uring_buf_ring *" br ",
+.BI " int " count ");"
+.PP
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_buf_ring_advance (3)
+commits
+.I count
+previously added buffers to the shared buffer ring
+.I br,
+making them visible to the kernel and hence consumable. This passes ownership
+of the buffer to the ring.
+
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_register_buf_ring (3), io_uring_buf_ring_add (3), io_uring_buf_ring_cq_advance (3)
diff --git a/man/io_uring_buf_ring_cq_advance.3 b/man/io_uring_buf_ring_cq_advance.3
new file mode 100644
index 0000000..5b693b7
--- /dev/null
+++ b/man/io_uring_buf_ring_cq_advance.3
@@ -0,0 +1,40 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_buf_ring_cq_advance 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_buf_ring_cq_advance - advance index of provided buffer and CQ ring
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_buf_ring_cq_advance(struct io_uring *" ring ",
+.BI " struct io_uring_buf_ring *" br ",
+.BI " int " count ");"
+.PP
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_buf_ring_cq_advance (3)
+commits
+.I count
+previously added buffers to the shared buffer ring
+.I br,
+making them visible to the kernel and hence consumable. This passes ownership
+of the buffer to the ring. At the same time, it advances the CQ ring of
+.I ring
+by
+.I count
+amount. This effectively bundles both a
+.BR io_uring_buf_ring_advance (3)
+call and a
+.BR io_uring_cq_avance (3)
+into one operation. Since updating either ring index entails a store memory
+barrier, doing both at once is more efficient.
+
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_register_buf_ring (3), io_uring_buf_ring_add (3), io_uring_buf_ring_advance (3)
diff --git a/man/io_uring_register_buf_ring.3 b/man/io_uring_register_buf_ring.3
new file mode 100644
index 0000000..28cbf96
--- /dev/null
+++ b/man/io_uring_register_buf_ring.3
@@ -0,0 +1,133 @@
+.\" 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
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#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 "
+.PP
+.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
+.I 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
+.I 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 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.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_buf_ring (3)
+returns 0. On failure it returns
+.B -errno.
+.SH SEE ALSO
+.BR io_uring_buf_ring_alloc (3), io_uring_buf_ring_add (3), io_uring_buf_ring_advance (3), io_uring_buf_ring_cq_advance (3)
diff --git a/man/io_uring_unregister_buf_ring.3 b/man/io_uring_unregister_buf_ring.3
new file mode 100644
index 0000000..8743328
--- /dev/null
+++ b/man/io_uring_unregister_buf_ring.3
@@ -0,0 +1,30 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_unregister_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_unregister_buf_ring - unregister a previously registered buffer ring
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#include <liburing.h>"
+.PP
+.BI "int io_uring_unregister_buf_ring(struct io_uring *" ring ",
+.BI " int " bgid ");"
+.BI "
+.PP
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_unregister_buf_ring (3)
+function unregisters a previously registered shared buffer ring indicated by
+.I bgid.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_unregister_buf_ring (3)
+returns 0. On failure it returns
+.B -errno.
+.SH SEE ALSO
+.BR io_uring_register_buf_ring (3), io_uring_buf_ring_free (3)