liburing: add api for napi busy poll timeout

This adds two new api's to set and clear the napi busy poll timeout. The two new functions are called:
- io_uring_register_busy_poll_timeout and
- io_uring_unregister_busy_poll_timeout.

The patch series also contains the documentation for the two new functions and two test programs. The client program is called napi-busy-poll-client and the server program napi-busy-poll-server. The client measures the roundtrip times of requests.

There is also a kernel patch "io-uring: support napi busy poll" to enable this feature on the kernel side.

Changes:
- V2:
- Updated the liburing.map file for the two new functions. (added a 2.4 section)
- Added a description of the new feature to the changelog file
- Fixed the indentation of the longopts structure
- Used defined exit constants
- Fixed encodeUserData to support 32 bit builds

Stefan Roesch (4):
liburing: add api to set napi busy poll timeout
liburing: add documentation for new napi busy polling
liburing: add test programs for napi busy poll
liburing: update changelog with new feature

 CHANGELOG                       |   3 +
 man/io_uring_register_napi.3    |  35 +++
 man/io_uring_unregister_napi.3  |  26 ++
 src/include/liburing.h          |   4 +
 src/include/liburing/io_uring.h |   4 +
 src/liburing.map                |   8 +
 src/register.c                  |  15 ++
 test/Makefile                   |   2 +
 test/napi-busy-poll-client.c    | 422 ++++++++++++++++++++++++++++++++
 test/napi-busy-poll-server.c    | 372 ++++++++++++++++++++++++++++
 10 files changed, 891 insertions(+)
 create mode 100644 man/io_uring_register_napi.3
 create mode 100644 man/io_uring_unregister_napi.3
 create mode 100644 test/napi-busy-poll-client.c
 create mode 100644 test/napi-busy-poll-server.c

base-commit: 754bc068ec482c5338a07dd74b7d3892729bb847

2.30.2

This adds the two functions to register and unregister the napi busy poll timeout:
- io_uring_register_napi_busy_poll_timeout
- io_uring_unregister_napi_busy_poll_timeout

---
 src/include/liburing.h          |  4 ++++
 src/include/liburing/io_uring.h |  4 ++++
 src/liburing.map                |  8 ++++++++
 src/register.c                  | 15 +++++++++++++++
 4 files changed, 31 insertions(+)

index 12a703f..6722fa2 100644
@@ -235,6 +235,10 @@ int io_uring_register_sync_cancel(struct io_uring *ring,
 int io_uring_register_file_alloc_range(struct io_uring *ring,
 					unsigned off, unsigned len);
 
+int io_uring_register_napi_busy_poll_timeout(struct io_uring *ring,
+					     unsigned int to);
+int io_uring_unregister_napi_busy_poll_timeout(struct io_uring *ring);
+
 int io_uring_get_events(struct io_uring *ring);
 int io_uring_submit_and_get_events(struct io_uring *ring);
 

index a3e0920..0919d9e 100644
@@ -499,6 +499,10 @@ enum {
 	/* register a range of fixed file slots for automatic slot allocation */
 	IORING_REGISTER_FILE_ALLOC_RANGE	= 25,
 
+	/* set/clear busy poll timeout */
+	IORING_REGISTER_NAPI_BUSY_POLL_TIMEOUT	= 26,
+	IORING_UNREGISTER_NAPI_BUSY_POLL_TIMEOUT= 27,
+
 	/* this goes last */
 	IORING_REGISTER_LAST
 };

index 06c64f8..793766e 100644
@@ -60,6 +60,8 @@ LIBURING_2.3 {
 	global:
 		io_uring_register_sync_cancel;
 		io_uring_register_file_alloc_range;
+		io_uring_register_busy_poll_timeout;
+		io_uring_unregister_busy_poll_timeout;
 		io_uring_enter;
 		io_uring_enter2;
 		io_uring_setup;

@@ -67,3 +69,9 @@ LIBURING_2.3 {
 		io_uring_get_events;
 		io_uring_submit_and_get_events;
 } LIBURING_2.2;
+
+LIBURING_2.4 {
+	global:
+		io_uring_napi_register_busy_poll_timeout;
+		io_uring_napi_unregister_busy_poll_timeout;
+} LIBURING_2.3;

index e849825..ffbfb8a 100644
@@ -367,3 +367,18 @@ int io_uring_register_file_alloc_range(struct io_uring *ring,
 				       IORING_REGISTER_FILE_ALLOC_RANGE, &range,
 				       0);
 }
+
+int io_uring_register_napi_busy_poll_timeout(struct io_uring *ring,
+					     unsigned int to)
+{
+	return __sys_io_uring_register(ring->ring_fd,
+				IORING_REGISTER_NAPI_BUSY_POLL_TIMEOUT,
+				NULL, to);
+}
+
+int io_uring_unregister_napi_busy_poll_timeout(struct io_uring *ring)
+{
+	return __sys_io_uring_register(ring->ring_fd,
+				IORING_UNREGISTER_NAPI_BUSY_POLL_TIMEOUT,
+				NULL, 0);
+}

2.30.2

This adds two man pages for the two new functions:
- io_uring_register_napi_busy_poll_timeout
- io_uring_unregister_napi_busy_poll_timeout

---
 man/io_uring_register_napi.3   | 35 ++++++++++++++++++++++++++++++++++
 man/io_uring_unregister_napi.3 | 26 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 man/io_uring_register_napi.3
 create mode 100644 man/io_uring_unregister_napi.3

new file mode 100644
index 0000000..4ef591c
@@ -0,0 +1,35 @@
+.\" Copyright (C) 2022 Stefan Roesch <[email protected]>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_register_napi_busy_poll_timeout 3 "November 1, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_register_napi_busy_poll_timeout \- register NAPI busy poll timeout
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_register_napi_busy_poll_timeout(struct io_uring *" ring ","
+.BI "                                             unsigned int " timeout)
+.PP
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_register_napi_busy_poll_timeout (3)
+function registers the NAPI busy poll
+.I timeout
+for subsequent operations.
+
+Registering a NAPI busy poll timeout is a requirement to be able to use
+NAPI busy polling. The other way to enable NAPI busy polling is to set the
+proc setting /proc/sys/net/core/busy_poll.
+
+NAPI busy poll can reduce the network roundtrip time.
+
+
+.SH RETURN VALUE
+On success
+.BR io_uring_register_napi_busy_poll_timeout (3)
+return 0. On failure they return
+.BR -errno .

new file mode 100644
index 0000000..3a73327
@@ -0,0 +1,26 @@
+.\" Copyright (C) 2022 Stefan Roesch <[email protected]>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_unregister_napi_busy_poll_timeout 3 "November 1, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_unregister_napi_busy_poll_timeout \- unregister NAPI busy poll timeout
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_unregister_napi_busy_poll_timeout(struct io_uring *" ring ")
+.PP
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_unregister_napi_busy_poll_timeout (3)
+function unregisters the NAPI busy poll
+for subsequent operations.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_unregister_napi_busy_poll_timeout (3)
+return 0. On failure they return
+.BR -errno .

2.30.2

[...]

liburing-2.3 has already been released. These two should go to liburing-2.4.

See:

https://github.com/axboe/liburing/tags

for the liburing version list.

Ammar Faizi

This adds two test programs to test the napi busy poll functionality. It consists of a client program and a server program. To get a napi id, the client and the server program need to be run on different hosts.

To test the napi busy poll timeout, the -t needs to be specified. A reasonable value for the busy poll timeout is 100. By specifying the busy poll timeout on the server and the client the best results are accomplished.

---
 test/Makefile                |   2 +
 test/napi-busy-poll-client.c | 422 +++++++++++++++++++++++++++++++++++
 test/napi-busy-poll-server.c | 372 ++++++++++++++++++++++++++++++
 3 files changed, 796 insertions(+)
 create mode 100644 test/napi-busy-poll-client.c
 create mode 100644 test/napi-busy-poll-server.c

index 8263e9f..8c606f9 100644
@@ -105,6 +105,8 @@ test_srcs := \
 	mkdir.c \
 	msg-ring.c \
 	multicqes_drain.c \
+	napi-busy-poll-client.c \
+	napi-busy-poll-server.c \
 	nolibc.c \
 	nop-all-sizes.c \
 	nop.c \

2.30.2

Hi Stefan,

We don't write liburing tests this way. Your new tests break the "make runtests" command:

...
...
Running test napi-busy-poll-client.t address option is mandatory
Usage: ./napi-busy-poll-client.t [-l|--listen] [-a|--address ip_address] [-p|--port port-no] [-s|--sqpoll] [-b|--busy] [-n|--num pings] [-t|--timeout busy-poll-timeout] [-h|--help] ... snip ...

Test napi-busy-poll-client.t failed with ret 1
Running test napi-busy-poll-server.t address option is mandatory
Usage: ./napi-busy-poll-server.t [-l|--listen] [-a|--address ip_address] [-p|--port port-no] [-s|--sqpoll] [-b|--busy] [-n|--num pings] [-t|--timeout busy-poll-timeout] [-h|--help] ... snip ...
...
...
Tests failed (3): <napi-busy-poll-client.t> <napi-busy-poll-server.t> <pipe-bug.t>
make[1]: *** [Makefile:235: runtests] Error 1
make[1]: Leaving directory '/home/ammarfaizi2/app/liburing/test'
make: *** [Makefile:21: runtests] Error 2

All test programs in the "test/" directory are run by "make runtests" command. Please try to run them with "make runtests" command.

If you want to test several arguments combination variants, you can do something like this:

https://github.com/axboe/liburing/blob/754bc068ec482/test/socket.c#L369-L409

Note: Since you're adding a new feature, your test program should check whether the running kernel supports the new feature. If the running kernel doesn't support it, use T_EXIT_SKIP as the exit code.

Ammar Faizi

Note: In that example, it doesn't use T_EXIT_* as the exit code because this exit code protocol is a new framework. We haven't finished to port the old tests to follow this rule.

It's introduced in commit (in liburing-2.3):

ed430fbeb3336 ("tests: migrate some tests to use enum-based exit codes")

New tests should follow the T_EXIT_* convention for exit code.

Ammar Faizi

Add a new entry to the changelog file for the napi busy poll feature.

---
 CHANGELOG | 3 +++
 1 file changed, 3 insertions(+)

index 09511af..1db0269 100644
@@ -1,3 +1,6 @@
+liburing-2.4 release
+- Support for napi busy polling
+
 liburing-2.3 release
 
 - Support non-libc build for aarch64.

2.30.2