Skip to contentSkip to conversation

ioctl_eventpoll.2: Add eventpoll ioctl documentation

PATCH In review Joe Damato 2 participants 7 messages Jun 11, 2024 – Jun 12, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Joe Damato

author
#0 lore raw

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
author
#1 lore raw

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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
index e7892922e..951500131 100644
@@ -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
#2 lore raw

Re: [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.

---
 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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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
new file mode 100644
index 000000000..6bbbef2d5
@@ -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
index 6bbbef2d5..64a8770e7 100644
@@ -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(&params, 0, sizeof(struct epoll_params));
+\&
+params.busy_poll_usecs = 25;
+params.busy_poll_budget = 8;
+params.prefer_busy_poll = 1;
+\&
+if (ioctl(epollfd, EPIOCSPARAMS, &params) == \-1) {
+    perror("ioctl");
+    exit(EXIT_FAILURE);
+}
+\&
+/* Code to show how to retrieve the current settings */
+\&
+memset(&params, 0, sizeof(struct epoll_params));
+\&
+if (ioctl(epollfd, EPIOCGPARAMS, &params) == \-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
man/man2const/EPIOCGPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man2const/EPIOCSPARAMS.2const new file +1 -0
new file mode 100644
index 000000000..b70a1a565
@@ -0,0 +1 @@
+.so man2/ioctl_eventpoll.2
man/man7/epoll.7 +1 -0
index e7892922e..951500131 100644
@@ -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/>
author
#3 lore raw

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.

---
 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
index f0327e8ba..013f81b64 100644
@@ -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
index 6d5bc032e..29a6da375 100644
@@ -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
index 5b8c28a9c..6f7725904 100644
@@ -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
new file mode 100644
index 000000000..6bbbef2d5
@@ -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 .
+.in

I 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 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 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
index 6bbbef2d5..64a8770e7 100644
@@ -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

#4 lore raw

Re: [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.

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

man/man2/ioctl_eventpoll.2 +5 -5
index 64a8770e7..79931eb7e 100644
@@ -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 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.

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
index 6bbbef2d5..64a8770e7 100644
@@ -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>.

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/>
author
#5 lore raw

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.

---
 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 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 };

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
index 64a8770e7..79931eb7e 100644
@@ -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:

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:

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?h=ioctl&id=e450bcf6e35a5c227c5e80cdb4e44bb89516a5ee

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 ;)

#6 lore raw

Re: [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:

https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?h=ioctl&id=e450bcf6e35a5c227c5e80cdb4e44bb89516a5ee

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