[PATCH v3 1/1] ioctl_eventpoll.2: New page describing epoll ioctl(2)

[Joe Damato <jdamato@fastly.com>]

A new page is added which describes epoll fd ioctls: EPIOCSPARAMS and
EPIOCGPARAMS which allow the user to control epoll-based busy polling.

Also add link pages for EPIOCSPARAMS and EPIOCGPARAMS.

Signed-off-by: Joe Damato <jdamato@fastly.com>
---
 man/man2/epoll_create.2           |   1 +
 man/man2/epoll_ctl.2              |   1 +
 man/man2/ioctl.2                  |   1 +
 man/man2/ioctl_eventpoll.2        | 173 ++++++++++++++++++++++++++++++
 man/man2const/EPIOCGPARAMS.2const |   1 +
 man/man2const/EPIOCSPARAMS.2const |   1 +
 man/man7/epoll.7                  |   1 +
 7 files changed, 179 insertions(+)
 create mode 100644 man/man2/ioctl_eventpoll.2
 create mode 100644 man/man2const/EPIOCGPARAMS.2const
 create mode 100644 man/man2const/EPIOCSPARAMS.2const

diff --git a/man/man2/epoll_create.2 b/man/man2/epoll_create.2
index f0327e8ba..013f81b64 100644
--- a/man/man2/epoll_create.2
+++ b/man/man2/epoll_create.2
@@ -141,4 +141,5 @@ on overrun.
 .BR close (2),
 .BR epoll_ctl (2),
 .BR epoll_wait (2),
+.BR ioctl_eventpoll (2),
 .BR epoll (7)
diff --git a/man/man2/epoll_ctl.2 b/man/man2/epoll_ctl.2
index 6d5bc032e..29a6da375 100644
--- a/man/man2/epoll_ctl.2
+++ b/man/man2/epoll_ctl.2
@@ -425,5 +425,6 @@ flag.
 .SH SEE ALSO
 .BR epoll_create (2),
 .BR epoll_wait (2),
+.BR ioctl_eventpoll (2),
 .BR poll (2),
 .BR epoll (7)
diff --git a/man/man2/ioctl.2 b/man/man2/ioctl.2
index 5b8c28a9c..6f7725904 100644
--- a/man/man2/ioctl.2
+++ b/man/man2/ioctl.2
@@ -225,6 +225,7 @@ for the various architectures.
 .BR ioctl_ns (2),
 .BR ioctl_tty (2),
 .BR ioctl_userfaultfd (2),
+.BR ioctl_eventpoll (2),
 .BR open (2),
 .\" .BR mt (4),
 .BR sd (4),
diff --git a/man/man2/ioctl_eventpoll.2 b/man/man2/ioctl_eventpoll.2
new file mode 100644
index 000000000..0fe03d6d4
--- /dev/null
+++ b/man/man2/ioctl_eventpoll.2
@@ -0,0 +1,173 @@
+.\" Copyright (c) 2024, Joe Damato
+.\" Copyright 2024, Joe Damato <jdamato@fastly.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH ioctl_eventpoll 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_eventpoll,
+EPIOCSPARAMS,
+EPIOCGPARAMS
+\-
+ioctl() operations for epoll file descriptors
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.EX
+.BR "#include <sys/epoll.h>" "  /* Definition of " EPIOC* " constants */"
+.B "#include <sys/ioctl.h>"
+.P
+.BI "int ioctl(int " fd ", EPIOCSPARAMS, const struct epoll_params *" argp );
+.BI "int ioctl(int " fd ", EPIOCGPARAMS, struct epoll_params *" argp );
+.P
+.B "#include <sys/epoll.h>"
+.P
+.B struct epoll_params {
+.BR "    uint32_t busy_poll_usecs;" "  /* Number of usecs to busy poll */"
+.BR "    uint16_t busy_poll_budget;" " /* Maximum number of packets to retrieve per poll */"
+.BR "    uint8_t prefer_busy_poll;" "  /* Boolean to enable or disable prefer busy poll  */"
+\&
+.BR " " "   /* pad the struct to a multiple of 64bits */"
+.BR "    uint8_t __pad;"            "  /* Must be zero */"
+.B };
+.EE
+.SH DESCRIPTION
+.TP
+.B EPIOCSPARAMS
+Set the
+.I epoll_params
+structure to configure the operation of epoll.
+Refer to the structure description below
+to learn what configuration is supported.
+.TP
+.B EPIOCGPARAMS
+Get the current
+.I epoll_params
+configuration settings.
+.P
+All operations documented above must be performed on an epoll file descriptor,
+which can be obtained with a call to
+.BR epoll_create (2)
+or
+.BR epoll_create1 (2).
+.\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61
+.\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
+.SS The epoll_params structure
+.I argp.busy_poll_usecs
+denotes the number of microseconds that the network stack will busy poll.
+During this time period,
+the network device will be polled repeatedly for packets.
+This value cannot exceed
+.B INT_MAX.
+.in
+.P
+.I argp.busy_poll_budget
+the maximum number of packets that the network stack will retrieve
+on each poll attempt.
+This value cannot exceed
+.B NAPI_POLL_WEIGHT
+(which is 64 as of Linux 6.9), unless the process is run with
+.B CAP_NET_ADMIN.
+.P
+.I argp.prefer_busy_poll
+is a boolean field and
+must be either 0 (disabled) or 1 (enabled).
+If enabled,
+this indicates to the network stack that
+busy poll is the preferred method of processing network data
+and the network stack should give the application the opportunity to busy poll.
+Without this option,
+very busy systems may continue to do network processing
+via the normal method of IRQs triggering softIRQ and NAPI.
+.P
+.I argp.__pad
+must be zero.
+.SH RETURN VALUE
+On success, 0 is returned.
+On failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EOPNOTSUPP
+The kernel was not compiled with busy poll support.
+.TP
+.B EINVAL
+.I fd
+is not a valid file descriptor.
+.TP
+.B EINVAL
+.I argp.__pad
+is not zero.
+.TP
+.B EINVAL
+.I argp.busy_poll_usecs
+exceeds
+.B INT_MAX .
+.TP
+.B EINVAL
+.I argp.prefer_busy_poll
+is not 0 or 1.
+.TP
+.B EPERM
+The process is being run without
+.I CAP_NET_ADMIN
+and the specified
+.I argp.busy_poll_budget
+exceeds
+.B NAPI_POLL_WEIGHT.
+.TP
+.B EFAULT
+.I argp
+does not point to a valid memory address.
+.SH EXAMPLES
+.EX
+/* Code to set the epoll params to enable busy polling */
+\&
+int epollfd = epoll_create1(0);
+struct epoll_params params;
+\&
+if (epollfd == \-1) {
+    perror("epoll_create1");
+    exit(EXIT_FAILURE);
+}
+\&
+memset(&params, 0, sizeof(struct epoll_params));
+\&
+params.busy_poll_usecs = 25;
+params.busy_poll_budget = 8;
+params.prefer_busy_poll = 1;
+\&
+if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
+    perror("ioctl");
+    exit(EXIT_FAILURE);
+}
+\&
+/* Code to show how to retrieve the current settings */
+\&
+memset(&params, 0, sizeof(struct epoll_params));
+\&
+if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-1) {
+    perror("ioctl");
+    exit(EXIT_FAILURE);
+}
+\&
+/* params struct now contains the current parameters */
+\&
+fprintf(stderr, "epoll usecs: %lu\[rs]n", params.busy_poll_usecs);
+fprintf(stderr, "epoll packet budget: %u\[rs]n", params.busy_poll_budget);
+fprintf(stderr, "epoll prefer busy poll: %u\[rs]n", params.prefer_busy_poll);
+\&
+.SH History
+Linux 6.9.
+glibc 2.40.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR epoll_create (2),
+.BR epoll_create1 (2),
+.BR epoll (7)
+.P
+.I linux.git/Documentation/networking/napi.rst
+.P
+.I linux.git/Documentation/admin-guide/sysctl/net.rst
diff --git a/man/man2const/EPIOCGPARAMS.2const b/man/man2const/EPIOCGPARAMS.2const
new file mode 100644
index 000000000..b70a1a565
--- /dev/null
+++ b/man/man2const/EPIOCGPARAMS.2const
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
diff --git a/man/man2const/EPIOCSPARAMS.2const b/man/man2const/EPIOCSPARAMS.2const
new file mode 100644
index 000000000..b70a1a565
--- /dev/null
+++ b/man/man2const/EPIOCSPARAMS.2const
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
diff --git a/man/man7/epoll.7 b/man/man7/epoll.7
index e7892922e..951500131 100644
--- a/man/man7/epoll.7
+++ b/man/man7/epoll.7
@@ -606,5 +606,6 @@ is present in an epoll instance.
 .BR epoll_create1 (2),
 .BR epoll_ctl (2),
 .BR epoll_wait (2),
+.BR ioctl_eventpoll (2),
 .BR poll (2),
 .BR select (2)
-- 
2.34.1