1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
.\" 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. The maximum
size allowed is 2^15 (32768).
.I bgid
is the buffer group ID associated with this ring. SQEs that select a buffer
have a buffer group associated with them in their
.I buf_group
field, and the associated CQEs will have
.B IORING_CQE_F_BUFFER
set in their
.I flags
member, which will also contain the specific ID of the buffer selected. The rest
of the fields are reserved and must be cleared to zero.
The
.I flags
argument can be set to one of the following values:
.TP
.B IOU_PBUF_RING_INC
The buffers in this ring can be incrementally consumed. With partial
consumption, each completion of a given buffer ID will continue where the
previous one left off, or from the start if no completions have been seen yet.
When more completions should be expected for a given buffer ID, the CQE will
have
.B IORING_CQE_F_BUF_MORE
set in the
.I flags
member. Available since 6.12.
.PP
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 before use. Applications may use
.BR io_uring_buf_ring_add (3)
and
.BR io_uring_buf_ring_advance (3)
or
.BR io_uring_buf_ring_cq_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 NOTES
Unless manual setup is needed, it's recommended to use
.BR io_uring_setup_buf_ring (3)
as it provides a simpler way to setup a provided buffer ring.
.SH SEE ALSO
.BR io_uring_buf_ring_init (3),
.BR io_uring_buf_ring_add (3),
.BR io_uring_setup_buf_ring (3),
.BR io_uring_buf_ring_advance (3),
.BR io_uring_buf_ring_cq_advance (3)
|
