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:
> > 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.
Thanks!
> > +.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.
> > +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.
> 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
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
