diff options
Diffstat (limited to 'man/io_uring_register_buf_ring.3')
-rw-r--r-- | man/io_uring_register_buf_ring.3 | 139 |
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) |