ioctl_eventpoll.2: Add eventpoll ioctl documentation
v4 cover ioctl_eventpoll.2: Add eventpoll ioctl documentation
Greetings:
Welcome to v4.
This revision includes several major changes:
1. Remove redundant copyright/author line.
2. Fix alignment of struct epoll_params fields
3. Add appropriate .nf/.fi and .EX/.EE sections, as suggested.
4. Shortened struct field comments
5. Moved linux/glibc commit sha comments to HISTORY
6. Fixed several B to BR issues
7. Rearranged sections according to documentation on section ordering
8. Updated commit message for Patch 1/1.
Thanks,
Joe
v3->v4:
- Remove redundant copyright/author line.
- Fix alignment of struct epoll_params fields
- Add appropriate .nf/.fi and .EX/.EE sections, as suggested.
- Shortened struct field comments
- Moved linux/glibc commit sha comments to HISTORY
- Fixed several B to BR issues
- Rearranged sections according to documentation on section ordering
- Updated commit message for Patch 1/1.
v2->v3:
- Rename file from man/man2/ioctl_epoll.2 to man/man2/ioctl_eventpoll.2.
- Attempt to use semantic newlines.
- Replace includes with sys/epoll.h, since this code is in glibc.
- Several style changes suggested by Alejandro.
- Replacing \e with \[rs] in the sample code included.
- Replacing all instances of ioctl_epoll with ioctl_eventpoll
v1->v2:
- Add link pages for EPIOCSPARAMS and EPIOCGPARAMS.
- Many edits to the main ioctl_epoll file to better describe the operations and document the interface.
*** BLURB HERE ***
Joe Damato (1):
ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll
ioctl(2)
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
Signature · 1 line
2.34.1
PATCH v4 1/1 ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
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.
--- 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
man/man2/epoll_create.2 +1 -0
@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)
man/man2/epoll_ctl.2 +1 -0
@@ -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)
man/man2/ioctl.2 +1 -0
@@ -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),
man/man2/ioctl_eventpoll.2 new file +175 -0
175 lines not on this page · raw message
man/man2const/EPIOCGPARAMS.2const new file +1 -0
@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
@@ -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)
Signature · 1 line
2.34.1
Alejandro Colomar
maintainerRe: [PATCH v4 1/1] ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Hi Joe,
Quoted 110 lines · Joe Damato
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 <[email protected]>--- 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.2constman/man2/epoll_create.2 +1
-0@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)man/man2/epoll_ctl.2 +1
-0@@ -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)man/man2/ioctl.2 +1
-0@@ -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),man/man2/ioctl_eventpoll.2 new file +52
-0@@ -0,0 +1,175 @@ +.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" 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)
man/man2/ioctl_eventpoll.2 line 62
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+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.
man/man2/ioctl_eventpoll.2 line 65
Quoted 3 lines
man/man2/ioctl_eventpoll.2 new file +3
-0+.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 ^.
Quoted 47 lines
man/man2/ioctl_eventpoll.2 new file +47
-0+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
man/man2/ioctl_eventpoll.2 line 122
Quoted 10 lines
man/man2/ioctl_eventpoll.2 new file +10
-0+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.
man/man2/ioctl_eventpoll.2 +2 -3
@@ -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
Quoted 81 lines
man/man2/ioctl_eventpoll.2 new file +53
-0+.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.rstman/man2const/EPIOCGPARAMS.2const new file +1
-0@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2man/man2const/EPIOCSPARAMS.2const new file +1
-0@@ -0,0 +1 @@ +.so man2/ioctl_eventpoll.2man/man7/epoll.7 +1
-0@@ -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)Signature · 1 line
2.34.1
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH v4 1/1] ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Quoted 117 lines · Alejandro Colomar
Hi Joe,
Quoted 114 lines · Joe Damato
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 <[email protected]>--- 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.2constman/man2/epoll_create.2 +1
-0@@ -141,4 +141,5 @@ on overrun. .BR close (2), .BR epoll_ctl (2), .BR epoll_wait (2), +.BR ioctl_eventpoll (2), .BR epoll (7)man/man2/epoll_ctl.2 +1
-0@@ -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)man/man2/ioctl.2 +1
-0@@ -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),man/man2/ioctl_eventpoll.2 new file +56
-0@@ -0,0 +1,175 @@ +.\" Copyright 2024, Joe Damato <[email protected]> +.\" +.\" 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
Quoted 8 lines
man/man2/ioctl_eventpoll.2 line 62
Quoted 6 lines
man/man2/ioctl_eventpoll.2 new file +6
-0+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 . +.inI hadn't noticed this glitch. This '.in' is spurious.
Thanks!
Quoted 5 lines
man/man2/ioctl_eventpoll.2 line 65
Quoted 3 lines
man/man2/ioctl_eventpoll.2 new file +3
-0+.P +.I argp.busy_poll_budget +the maximum number of packets that the network stack will retrieveAlso, 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 53 lines
Quoted 53 lines
man/man2/ioctl_eventpoll.2 new file +53
-0+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 .
Quoted 8 lines
man/man2/ioctl_eventpoll.2 line 122
Quoted 4 lines
man/man2/ioctl_eventpoll.2 new file +4
-0+.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.
Quoted 20 lines
I've applied these three edits myself, and have already applied this patch.
man/man2/ioctl_eventpoll.2 +1
-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
man/man2/ioctl_eventpoll.2 .SH ERRORS · line 124
Quoted 8 lines
man/man2/ioctl_eventpoll.2 +1
-1@@ -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.
Quoted 3 lines
<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 !!
Quoted 1 line
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
Alejandro Colomar
maintainerRe: [PATCH v4 1/1] ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Hi Joe,
Quoted 20 lines · Joe Damato
Quoted 19 lines · Alejandro Colomar
Quoted 18 lines · Joe Damato
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 <[email protected]>--- 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
[...]
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
+.B "#include <
sys/epoll.h>"
+.P
+.EX
+.B structepoll_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:
man/man2/ioctl_eventpoll.2 +5 -5
@@ -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.
Quoted 11 lines
Quoted 5 lines
Quoted 3 lines
+.P
+.I argp.busy_poll_budget
+the maximum number of packets that the network stack will retrieveAlso, 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.
Quoted 2 lines
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.
Quoted 46 lines
Quoted 8 lines
Quoted 4 lines
+.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.
Quoted 20 lines
I've applied these three edits myself, and have already applied this patch.
man/man2/ioctl_eventpoll.2 +1
-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_WEIGHTman/man2/ioctl_eventpoll.2 .SH ERRORS · line 124
Quoted 8 lines
man/man2/ioctl_eventpoll.2 +1
-1@@ -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 HISTORYThese changes look good to me, thank you for applying them.
Quoted 3 lines
<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>.
Quoted 6 lines
Cool !!
Quoted 1 line
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
Signature · 1 line
<https://www.alejandro-colomar.es/>
Re: [PATCH v4 1/1] ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Quoted 38 lines · Alejandro Colomar
Hi Joe,
Quoted 20 lines · Joe Damato
Quoted 19 lines · Alejandro Colomar
Quoted 18 lines · Joe Damato
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 <[email protected]>--- 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[...]
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
+.B "#include <
sys/epoll.h>"
+.P
+.EX
+.B structepoll_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 };
Quoted 2 lines
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:
Ah, OK. Sorry about the misunderstanding on my part.
Quoted 35 lines
man/man2/ioctl_eventpoll.2 +5
-5@@ -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 }; .EEWhich renders as:
struct
epoll_params{
uint32_tbusy_poll_usecs; /* Number of usecs to busy poll */
uint16_tbusy_poll_budget; /* Max packets per poll */
uint8_tprefer_busy_poll; /* Boolean preference *//* pad the struct to a multiple of 64bits */
uint8_t__pad; /* Must be zero */
};That is:
man/man2/ioctl_eventpoll.2
Quoted 2 lines
man/man2/ioctl_eventpoll.2 +0
-2- 4-space indentation. - At a minimum, 2 spaces between member type and name.
Understood for next time.
Quoted 2 lines
While at it, I tried aligning the comment of
__pad, and seemed slightly better, so I did it.
OK thanks!
Quoted 2 lines
Since the commit was not yet on <kernel.org>, I've ammended and force- pushed. Sorry for the confusion.
No problem; apologies for making more work for you.
[...]
Quoted 4 lines
Quoted 4 lines
Quoted 3 lines
<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>.
Quoted 8 lines
Quoted 6 lines
Cool !!
Quoted 1 line
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. :-)
Thanks again! I was refreshing kernel.org's gitweb to see if the commit made it, looks like it is there:
Very cool!
Does the ioctl branch get merged into master before you do releases? Was mostly just curious because I'll be excited to see the new page in an official release in the future ;)
Alejandro Colomar
maintainerRe: [PATCH v4 1/1] ioctl_eventpoll.2, EPIOC[GS]PARAMS.2const: New page describing epoll ioctl(2)
Hi Joe,
Quoted 10 lines · Joe Damato
Thanks again! I was refreshing kernel.org's gitweb to see if the commit made it, looks like it is there:
Very cool!
Does the ioctl branch get merged into master before you do releases? Was mostly just curious because I'll be excited to see the new page in an official release in the future ;)
Yep, I created that branch a few days ago for doing a huge refactor of the ioctl*(2), which I expect to finish this week. (Also, I have a contract starting in a couple of weeks where I'll need to learn some ioctl(2), so this refactor will help get me started.) When I finish that refactor, I'll rebase on master and fast-forward master to it. Then, I'll probably release 6.9. I plan to release 6.9 before the end of this month, after which I'll merge another massive churny patch, MR.sed, which will be the main change in 6.10, which I might release in July.
BTW, I will probably cherry-pick your patch to master later today, not waiting for the rest of the ioctl(2) branch.
Have a lovely day!
Alex
Signature · 1 line
<https://www.alejandro-colomar.es/>