Print this page
8634 epoll fails to wake on certain edge-triggered conditions
8635 epoll should not emit POLLNVAL
8636 recursive epoll should emit EPOLLRDNORM
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Toomas Soome <tsoome@me.com>
Reviewed by: Igor Kozhukhov <igor@dilos.org>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/chpoll.9e
+++ new/usr/src/man/man9e/chpoll.9e
1 1 '\" te
2 2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 1989 AT&T
4 +.\" Copyright 2017 Joyent, Inc
4 5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 -.TH CHPOLL 9E "May 7, 2008"
8 +.TH CHPOLL 9E "Jan 18, 2017"
8 9 .SH NAME
9 10 chpoll \- poll entry point for a non-STREAMS character driver
10 11 .SH SYNOPSIS
11 12 .LP
12 13 .nf
13 14 #include <sys/types.h>
14 15 #include <sys/poll.h>
15 16 #include <sys/ddi.h>
16 17 #include <sys/sunddi.h>
17 18
18 19
19 20
20 21 \fBint prefix\fR\fBchpoll\fR(\fBdev_t\fR \fIdev\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR,
21 22 \fBshort *\fR\fIreventsp\fR, \fBstruct pollhead **\fR\fIphpp\fR);
22 23 .fi
23 24
24 25 .SH INTERFACE LEVEL
25 26 .LP
26 27 This entry point is optional. Architecture independent level 1 (DDI/DKI).
27 28 .SH PARAMETERS
28 29 .ne 2
29 30 .na
30 31 \fB\fIdev\fR\fR
31 32 .ad
32 33 .RS 12n
33 34 The device number for the device to be polled.
34 35 .RE
35 36
36 37 .sp
37 38 .ne 2
38 39 .na
39 40 \fB\fIevents\fR\fR
40 41 .ad
41 42 .RS 12n
42 43 The events that may occur. Valid events are:
43 44 .sp
44 45 .ne 2
45 46 .na
46 47 \fB\fBPOLLIN\fR\fR
47 48 .ad
48 49 .RS 14n
49 50 Data other than high priority data may be read without blocking.
50 51 .RE
51 52
52 53 .sp
53 54 .ne 2
54 55 .na
55 56 \fB\fBPOLLOUT\fR\fR
56 57 .ad
57 58 .RS 14n
58 59 Normal data may be written without blocking.
59 60 .RE
60 61
61 62 .sp
62 63 .ne 2
63 64 .na
64 65 \fB\fBPOLLPRI\fR\fR
65 66 .ad
66 67 .RS 14n
67 68 High priority data may be received without blocking.
68 69 .RE
69 70
70 71 .sp
71 72 .ne 2
72 73 .na
73 74 \fB\fBPOLLHUP\fR\fR
74 75 .ad
75 76 .RS 14n
76 77 A device hangup has occurred.
77 78 .RE
78 79
79 80 .sp
80 81 .ne 2
81 82 .na
82 83 \fB\fBPOLLERR\fR\fR
83 84 .ad
84 85 .RS 14n
85 86 An error has occurred on the device.
86 87 .RE
87 88
88 89 .sp
89 90 .ne 2
90 91 .na
91 92 \fB\fBPOLLRDNORM\fR\fR
92 93 .ad
93 94 .RS 14n
94 95 Normal data (priority band = 0) may be read without blocking.
95 96 .RE
96 97
97 98 .sp
98 99 .ne 2
99 100 .na
100 101 \fB\fBPOLLRDBAND\fR\fR
101 102 .ad
102 103 .RS 14n
103 104 Data from a non-zero priority band may be read without blocking
104 105 .RE
105 106
106 107 .sp
107 108 .ne 2
108 109 .na
109 110 \fB\fBPOLLWRNORM\fR\fR
110 111 .ad
111 112 .RS 14n
112 113 The same as \fBPOLLOUT\fR.
113 114 .RE
114 115
115 116 .sp
116 117 .ne 2
117 118 .na
118 119 \fB\fBPOLLWRBAND\fR\fR
119 120 .ad
120 121 .RS 14n
121 122 Priority data (priority band > 0) may be written.
122 123 .RE
123 124
124 125 .sp
125 126 .ne 2
126 127 .na
127 128 \fB\fBPOLLET\fR\fR
128 129 .ad
129 130 .RS 14n
130 131 The desired event is to be edge-triggered; calls to \fBpollwakeup\fR(9F)
131 132 should not be suppressed, even if the event is pending at the time of
132 133 call to the \fBchpoll()\fR function.
133 134 .RE
134 135
135 136 .RE
136 137
137 138 .sp
138 139 .ne 2
139 140 .na
140 141 \fB\fIanyyet\fR\fR
141 142 .ad
142 143 .RS 12n
143 144 A flag that is non-zero if any other file descriptors in the \fBpollfd\fR array
144 145 have events pending. The \fBpoll\fR(2) system call takes a pointer to an array
145 146 of \fBpollfd\fR structures as one of its arguments. See the \fBpoll\fR(2)
146 147 reference page for more details.
147 148 .RE
148 149
149 150 .sp
150 151 .ne 2
151 152 .na
152 153 \fB\fIreventsp\fR\fR
153 154 .ad
154 155 .RS 12n
155 156 A pointer to a bitmask of the returned events satisfied.
156 157 .RE
157 158
158 159 .sp
159 160 .ne 2
160 161 .na
161 162 \fB\fIphpp\fR\fR
162 163 .ad
163 164 .RS 12n
164 165 A pointer to a pointer to a \fBpollhead\fR structure.
165 166 .RE
166 167
167 168 .SH DESCRIPTION
168 169 .LP
169 170 The \fBchpoll()\fR entry point routine is used by non-STREAMS character device
170 171 drivers that wish to support polling. The driver must implement the polling
171 172 discipline itself. The following rules must be followed when implementing the
172 173 polling discipline:
173 174 .RS +4
174 175 .TP
|
↓ open down ↓ |
157 lines elided |
↑ open up ↑ |
175 176 1.
176 177 Implement the following algorithm when the \fBchpoll()\fR entry point is
177 178 called:
178 179 .sp
179 180 .in +2
180 181 .nf
181 182 if (specified_events_are_satisfied_now) {
182 183 *reventsp = satisfied_events & events;
183 184 } else {
184 185 *reventsp = 0;
185 - if (!anyyet)
186 - *phpp = &my_local_pollhead_structure;
187 186 }
187 +if ((*reventsp == 0 && !anyyet) || (events & POLLET))
188 + *phpp = &my_local_pollhead_structure;
188 189 return (0);
189 190 .fi
190 191 .in -2
191 192
193 +Note: Prior to the integration of \fBepoll\fR(5), which included
194 +edge-triggering via the \fBPOLLET\fR flag, standard chpoll mechanisms would
195 +only provide a pollhead in \fBphpp\fR if there were no matching events.
196 +Edge-triggered polling requires that \fBpollwakeup()\fR always be called for a
197 +resource, so if \fBPOLLET\fR is set in the \fBevents\fR of interest, the chpoll
198 +method must yield a pollhead and prepare to issue \fBpollwakeup()\fR calls on
199 +it.
200 +
201 +Drivers which are not wired up to make \fBpollwakeup()\fR calls on a pollhead
202 +when their status changes should emit one from their \fBchpoll\fR routine.
203 +This will exclude the resource from caching by pollers, since it cannot alert
204 +them to new events without \fBpollwakeup()\fR notification.
205 +
192 206 .RE
193 207 .RS +4
194 208 .TP
195 209 2.
196 210 Allocate an instance of the \fBpollhead\fR structure. This instance may be
197 211 tied to the per-minor data structure defined by the driver. The \fBpollhead\fR
198 212 structure should be treated as a "black box" by the driver. Initialize the
199 213 \fBpollhead\fR structure by filling it with zeroes. The size of this structure
200 214 is guaranteed to remain the same across releases.
201 215 .RE
202 216 .RS +4
203 217 .TP
204 218 3.
205 219 Call the \fBpollwakeup()\fR function with \fBevents\fR listed above whenever
206 220 pollable \fBevents\fR which the driver should monitor occur. This function can
207 221 be called with multiple events at one time. The \fBpollwakup()\fR can be called
208 222 regardless of whether or not the \fBchpoll()\fR entry is called; it should be
209 223 called every time the driver detects the pollable event. The driver must not
210 224 hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its
211 225 \fBchpoll()\fR entry point, or a deadlock may result. Note that if
212 226 \fBPOLLET\fR is set in the specified events, the driver must call
213 227 \fBpollwakeup\fR(9F) on subsequent events, even if events are pending at
214 228 the time of the call to \fBchpoll()\fR.
215 229
216 230 .RE
217 231 .RS +4
218 232 .TP
219 233 4.
220 234 In the \fBclose\fR(9E) entry point, the driver should call \fBpollwakeup()\fR
221 235 on the \fBpollhead\fR structure that corresponds to the closing software
222 236 state, specifying \fBPOLLERR\fR for the events. Further, upon return from
223 237 \fBpollwakeup()\fR, the driver's \fBclose\fR(9E) entry point should call
224 238 the \fBpollhead_clean\fR(9F) function, specifying the \fBpollhead\fR that
225 239 corresponds to the structure that will be deallocated:
226 240
227 241 .sp
228 242 .in +2
229 243 .nf
230 244 static int
231 245 mydriver_close(dev_t dev, int flag, int otyp, cred_t *cp)
232 246 {
233 247 minor_t minor = getminor(dev);
234 248 mydriver_state_t *state;
235 249
236 250 state = ddi_get_soft_state(mydriver_softstate, minor);
237 251
238 252 pollwakeup(&state->mydriver_pollhd, POLLERR);
239 253 pollhead_clean(&state->mydriver_pollhd);
240 254 ...
241 255 .fi
242 256 .in -2
243 257
244 258 This step is necessary to inform other kernel subsystems that the memory
|
↓ open down ↓ |
43 lines elided |
↑ open up ↑ |
245 259 associated with the \fBpollhead\fR is about to be deallocated by the
246 260 \fBclose\fR(9E) entry point.
247 261
248 262 .RE
249 263 .SH RETURN VALUES
250 264 .LP
251 265 \fBchpoll()\fR should return \fB0\fR for success, or the appropriate error
252 266 number.
253 267 .SH SEE ALSO
254 268 .LP
255 -\fBpoll\fR(2), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F)
269 +\fBpoll\fR(2), \fBepoll\fR(5), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F)
256 270 .sp
257 271 .LP
258 272 \fIWriting Device Drivers\fR
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX