Hi Joe,
On Tue, Jun 11, 2024 at 09:09:41PM GMT, Joe Damato wrote:
> 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
I hadn't noticed this glitch. This '.in' is spurious.
> +.P
> +.I argp.busy_poll_budget
> +the maximum number of packets that the network stack will retrieve
Also, this sentence seems to be missing a 'denotes' at ^.
> +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.
And this wording is slightly wrong. A pointer does not point to an
address (unless it's a pointer to a pointer). It _is_ an address (or
rather, its value is an address, but that's too pedantic).
I've applied these three edits myself, and have already applied this
patch.
diff --git i/man/man2/ioctl_eventpoll.2 w/man/man2/ioctl_eventpoll.2
index 6bbbef2d5..64a8770e7 100644
--- i/man/man2/ioctl_eventpoll.2
+++ w/man/man2/ioctl_eventpoll.2
@@ -59,10 +59,9 @@ .SS The epoll_params structure
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
+denotes the maximum number of packets that the network stack will retrieve
on each poll attempt.
This value cannot exceed
.B NAPI_POLL_WEIGHT
@@ -119,7 +118,7 @@ .SH ERRORS
.TP
.B EFAULT
.I argp
-does not point to a valid memory address.
+is an invalid address.
.SH STANDARDS
Linux.
.SH HISTORY
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=e756cd6c0ae9f8121179e3e94201e729e013f5fb>
I'll push it tomorrow to <kernel.org>.
Thanks for this manual page! :-)
Have a lovely night!
Alex
> +.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
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
