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@xxxxxxxxxx>
---
man/man2/epoll_create.2 | 1 +
man/man2/epoll_ctl.2 | 1 +
man/man2/ioctl.2 | 1 +
man/man2/ioctl_epoll.2 | 171 ++++++++++++++++++++++++++++++
man/man2const/EPIOCGPARAMS.2const | 1 +
man/man2const/EPIOCSPARAMS.2const | 1 +
man/man7/epoll.7 | 1 +
7 files changed, 177 insertions(+)
create mode 100644 man/man2/ioctl_epoll.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..2aa1745f5 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_epoll (2),
.BR epoll (7)
diff --git a/man/man2/epoll_ctl.2 b/man/man2/epoll_ctl.2
index 6d5bc032e..24bbe7405 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_epoll (2),
.BR poll (2),
.BR epoll (7)
diff --git a/man/man2/ioctl.2 b/man/man2/ioctl.2
index 5b8c28a9c..d96777d1f 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_epoll (2),
.BR open (2),
.\" .BR mt (4),
.BR sd (4),
diff --git a/man/man2/ioctl_epoll.2 b/man/man2/ioctl_epoll.2
new file mode 100644
index 000000000..458e72e9a
--- /dev/null
+++ b/man/man2/ioctl_epoll.2
@@ -0,0 +1,171 @@
+.\" Copyright (c) 2024, Joe Damato
+.\" Written by Joe Damato <jdamato@xxxxxxxxxx>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH ioctl_epoll 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_epoll \- ioctl() operations for epoll file descriptors
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.EX
+.BR "#include <linux/eventpoll.h>" " /* Definition of " EPIOC* " constants and struct epoll_params */"
+.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 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.
+.TP
+All
+.BR ioctl (2)
+operations documented above must be performed on an epoll file descriptor,
+which can be created with a call to
+.BR epoll_create (2)
+or
+.BR epoll_create1 (2).
+.\" kernel commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61
+.\" glibc commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
+.P
+.I argp.busy_poll_usecs
+field 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
+field denotes the maximum number of packets that the network stack will
+retrieve on each poll attempt. This value cannot exceed
+.B NAPI_POLL_WEIGHT
+which, as of Linux 6.9, is 64, unless the process is run with
+.B CAP_NET_ADMIN.
+.P
+.I argp.prefer_busy_poll
+field 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.
+.P
+.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 op
+specified is invalid.
+.TP
+.B EINVAL
+.I argp.__pad
+was 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
+(which is 64 as of Linux 6.9).
+.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(¶ms, 0, sizeof(struct epoll_params));
+\&
+params.busy_poll_usecs = 25;
+params.busy_poll_budget = 8;
+params.prefer_busy_poll = 1;
+\&
+if (ioctl(epollfd, EPIOCSPARAMS, ¶ms) == \-1) {
+ perror("ioctl");
+ exit(EXIT_FAILURE);
+}
+\&
+/* Code to show how to retrieve the current settings */
+\&
+memset(¶ms, 0, sizeof(struct epoll_params));
+\&
+if (ioctl(epollfd, EPIOCGPARAMS, ¶ms) == \-1) {
+ perror("ioctl");
+ exit(EXIT_FAILURE);
+}
+\&
+/* params struct now contains the current parameters */
+\&
+fprintf(stderr, "epoll usecs: %lu\\n", params.busy_poll_usecs);
+fprintf(stderr, "epoll packet budget: %u\\n", params.busy_poll_budget);
+fprintf(stderr, "epoll prefer busy poll: %u\\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
+and
+.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..6fbc5f0f8
--- /dev/null
+++ b/man/man2const/EPIOCGPARAMS.2const
@@ -0,0 +1 @@
+.so man2/ioctl_epoll.2
diff --git a/man/man2const/EPIOCSPARAMS.2const b/man/man2const/EPIOCSPARAMS.2const
new file mode 100644
index 000000000..6fbc5f0f8
--- /dev/null
+++ b/man/man2const/EPIOCSPARAMS.2const
@@ -0,0 +1 @@
+.so man2/ioctl_epoll.2
diff --git a/man/man7/epoll.7 b/man/man7/epoll.7
index e7892922e..4ad032bdd 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_epoll (2),
.BR poll (2),
.BR select (2)
--
2.34.1
