1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH ioctl_eventpoll 2 2025-05-17 "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
.fi
.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 */"
\&
/* pad the struct to a multiple of 64bits */
.BR " uint8_t __pad;" " /* Must be zero */"
.B };
.EE
.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 .
.P
.I argp.busy_poll_budget
denotes the maximum number of packets that the network stack will retrieve
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
is an invalid address.
.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.rst
|
