[PATCH liburing 3/4] add io_uring_buf_ring_init

[Dylan Yudaken <dylany@fb.com>]

Kernel expects the tail to start at 0, so provide an API to init the
ring appropriately.

Signed-off-by: Dylan Yudaken <dylany@fb.com>
---
 man/io_uring_buf_ring_init.3     | 30 ++++++++++++++++++++++++++++++
 man/io_uring_register_buf_ring.3 |  5 ++++-
 src/include/liburing.h           |  5 +++++
 test/send_recvmsg.c              |  1 +
 4 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 man/io_uring_buf_ring_init.3

diff --git a/man/io_uring_buf_ring_init.3 b/man/io_uring_buf_ring_init.3
new file mode 100644
index 0000000..50cf69a
--- /dev/null
+++ b/man/io_uring_buf_ring_init.3
@@ -0,0 +1,30 @@
+.\" Copyright (C) 2022 Dylan Yudaken <dylany@fb.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_buf_ring_init 3 "June 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_buf_ring_init \- Initialise a  buffer ring
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_buf_ring_init(struct io_uring_buf_ring *" br ");"
+.fi
+.SH DESCRIPTION
+.PP
+.BR io_uring_buf_ring_init (3)
+initialises
+.IR br
+so that it is ready to be used. It may be called after
+.BR io_uring_register_buf_ring (3)
+but must be called before the buffer ring is used in any other way.
+
+.SH RETURN VALUE
+None
+
+.SH SEE ALSO
+.BR io_uring_register_buf_ring (3),
+.BR io_uring_buf_ring_add (3)
+.BR io_uring_buf_ring_advance (3),
+.BR io_uring_buf_ring_cq_advance (3)
diff --git a/man/io_uring_register_buf_ring.3 b/man/io_uring_register_buf_ring.3
index 9e0b53d..9e520bf 100644
--- a/man/io_uring_register_buf_ring.3
+++ b/man/io_uring_register_buf_ring.3
@@ -115,7 +115,9 @@ 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
+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)
@@ -131,6 +133,7 @@ On success
 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)
diff --git a/src/include/liburing.h b/src/include/liburing.h
index 9beef0b..c31ece2 100644
--- a/src/include/liburing.h
+++ b/src/include/liburing.h
@@ -1097,6 +1097,11 @@ static inline int io_uring_buf_ring_mask(__u32 ring_entries)
 	return ring_entries - 1;
 }
 
+static inline void io_uring_buf_ring_init(struct io_uring_buf_ring *br)
+{
+	br->tail = 0;
+}
+
 /*
  * Assign 'buf' with the addr/len/buffer ID supplied
  */
diff --git a/test/send_recvmsg.c b/test/send_recvmsg.c
index 6f18bae..cce6c45 100644
--- a/test/send_recvmsg.c
+++ b/test/send_recvmsg.c
@@ -199,6 +199,7 @@ static void *recv_fn(void *data)
 			}
 
 			br = ptr;
+			io_uring_buf_ring_init(br);
 			io_uring_buf_ring_add(br, buf, sizeof(buf), BUF_BID,
 					      io_uring_buf_ring_mask(1), 0);
 			io_uring_buf_ring_advance(br, 1);
-- 
2.30.2