Hi Joe,
On Tue, Jun 11, 2024 at 04:14:46PM GMT, Joe Damato wrote:
> On Wed, Jun 12, 2024 at 01:01:11AM +0200, Alejandro Colomar wrote:
> > 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
[...]
> > > +.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 };
I didn't notice that you had changed the indentation to 2. There was a
misunderstanding. I've amended it myself with what I meant:
diff --git i/man/man2/ioctl_eventpoll.2 w/man/man2/ioctl_eventpoll.2
index 64a8770e7..79931eb7e 100644
--- i/man/man2/ioctl_eventpoll.2
+++ w/man/man2/ioctl_eventpoll.2
@@ -24,12 +24,12 @@ .SH SYNOPSIS
.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 " 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 */"
+ /* pad the struct to a multiple of 64bits */
+.BR " uint8_t __pad;" " /* Must be zero */"
.B };
.EE
Which renders as:
struct epoll_params {
uint32_t busy_poll_usecs; /* Number of usecs to busy poll */
uint16_t busy_poll_budget; /* Max packets per poll */
uint8_t prefer_busy_poll; /* Boolean preference */
/* pad the struct to a multiple of 64bits */
uint8_t __pad; /* Must be zero */
};
That is:
- 4-space indentation.
- At a minimum, 2 spaces between member type and name.
While at it, I tried aligning the comment of __pad, and seemed slightly
better, so I did it.
Since the commit was not yet on <kernel.org>, I've ammended and force-
pushed. Sorry for the confusion.
> > > +.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?
I don't remember.
> Either way adding it back here seems fine to me, sorry for my
> confusion on that.
Maybe it was my confusion. Anyway; it's good now.
> > > +.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.
You're welcome; and no need to be sorry. :-)
Have a lovely night!
Alex
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
