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_eventpoll.2 | 175 ++++++++++++++++++++++++++++++
man/man2const/EPIOCGPARAMS.2const | 1 +
man/man2const/EPIOCSPARAMS.2const | 1 +
man/man7/epoll.7 | 1 +
7 files changed, 181 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..6bbbef2d5
--- /dev/null
+++ b/man/man2/ioctl_eventpoll.2
@@ -0,0 +1,175 @@
+.\" Copyright 2024, Joe Damato <jdamato@xxxxxxxxxx>
+.\"
+.\" 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
+.nf
+.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
+.EX
+.B struct epoll_params {
+.BR " uint32_t busy_poll_usecs;" " /* Number of usecs to busy poll */"
+.BR " uint16_t busy_poll_budget;" " /* Max packets per poll */"
+.BR " uint8_t prefer_busy_poll;" " /* Boolean preference */"
+\&
+.BR " " "/* pad the struct to a multiple of 64bits */"
+.BR " uint8_t __pad;" " /* Must be zero */"
+.B };
+.EE
+.fi
+.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).
+.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
+.BR 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
+.BR 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
+.BR INT_MAX .
+.TP
+.B EINVAL
+.I argp.prefer_busy_poll
+is not 0 or 1.
+.TP
+.B EPERM
+The process is being run without
+.B CAP_NET_ADMIN
+and the specified
+.I argp.busy_poll_budget
+exceeds
+.BR NAPI_POLL_WEIGHT .
+.TP
+.B EFAULT
+.I argp
+does not point to a valid memory address.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.\" linux.git commit 18e2bf0edf4dd88d9656ec92395aa47392e85b61
+.\" glibc.git commit 92c270d32caf3f8d5a02b8e46c7ec5d9d0315158
+Linux 6.9.
+glibc 2.40.
+.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\[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 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
