On Wed, Jun 12, 2024 at 01:01:11AM +0200, Alejandro Colomar wrote:

Hi Joe,

On Tue, Jun 11, 2024 at 09:09:41PM GMT, Joe Damato wrote:

quoted

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 <redacted>
---
 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@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
+.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.

Thanks!

quoted

+.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 ^.

I removed the "denotes" because I thought you asked me to do so in a
previous message?

Or maybe I removed it from this one but forgot to remove from the
one above?

Either way adding it back here seems fine to me, sorry for my
confusion on that.

quoted

+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).

That's right; your wording is more clear.

These changes look good to me, thank you for applying them.

<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>.

Cool !!

Thanks for this manual page!  :-)

Thanks for your patience on this one and sorry for the numerous
revisions you had to sort through.

Thanks,
Joe