1io_uring_register_buf_ring(3) liburing Manual io_uring_register_buf_ring(3)
2
6 io_uring_register_buf_ring - register buffer ring for provided buffers
7
9 #include <liburing.h>
10 int io_uring_register_buf_ring(struct io_uring *ring,
12 struct io_uring_buf_reg *reg,
13 unsigned int flags);
14
17 The io_uring_register_buf_ring(3) function registers a shared buffer
18 ring to be used with provided buffers. For the request types that sup‐
19 port it, provided buffers are given to the ring and one is selected by
20 a request if it has IOSQE_BUFFER_SELECT set in the SQE flags, when the
21 request is ready to receive data. This allows both clear ownership of
22 the buffer lifetime, and a way to have more read/receive type of opera‐
23 tions in flight than buffers available.
24 The reg argument must be filled in with the appropriate information. It
26 looks as follows:
27 struct io_uring_buf_reg {
29 __u64 ring_addr;
30 __u32 ring_entries;
31 __u16 bgid;
32 __u16 pad;
33 __u64 resv[3];
34 };
35 The ring_addr field must contain the address to the memory allocated to
37 fit this ring. The memory must be page aligned and hence allocated ap‐
38 propriately using eg posix_memalign(3) or similar. The size of the ring
39 is the product of ring_entries and the size of struct io_uring_buf.
40 ring_entries is the desired size of the ring, and must be a power-of-2
41 in size. The maximum size allowed is 2^15 (32768). bgid is the buffer
42 group ID associated with this ring. SQEs that select a buffer has a
43 buffer group associated with them in their buf_group field, and the as‐
44 sociated CQE will have IORING_CQE_F_BUFFER set in their flags member,
45 which will also contain the specific ID of the buffer selected. The
46 rest of the fields are reserved and must be cleared to zero.
47 The flags argument is currently unused and must be set to zero.
49 A shared buffer ring looks as follows:
51 struct io_uring_buf_ring {
53 union {
54 struct {
55 __u64 resv1;
56 __u32 resv2;
57 __u16 resv3;
58 __u16 tail;
59 };
60 struct io_uring_buf bufs[0];
61 };
62 };
63 where tail is the index at which the application can insert new buffers
65 for consumption by requests, and struct io_uring_buf is buffer defini‐
66 tion:
67 struct io_uring_buf {
69 __u64 addr;
70 __u32 len;
71 __u16 bid;
72 __u16 resv;
73 };
74 where addr is the address for the buffer, len is the length of the buf‐
76 fer in bytes, and bid is the buffer ID that will be returned in the CQE
77 once consumed.
78 Reserved fields must not be touched. Applications must use io_ur‐
80 ing_buf_ring_init(3) to initialise the buffer ring. Applications may
81 use io_uring_buf_ring_add(3) and io_uring_buf_ring_advance(3) or io_ur‐
82 ing_buf_ring_advance(3) to provide buffers, which will set these fields
83 and update the tail.
84 Available since 5.19.
86
89 On success io_uring_register_buf_ring(3) returns 0. On failure it re‐
90 turns -errno.
91
93 io_uring_buf_ring_init(3), io_uring_buf_ring_add(3), io_ur‐
94 ing_buf_ring_advance(3), io_uring_buf_ring_cq_advance(3)
95liburing-2.2 May 18, 2022 io_uring_register_buf_ring(3)