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.man.txt
+++ new/usr/src/man/man9e/chpoll.9e.man.txt
1 1 CHPOLL(9E) Driver Entry Points CHPOLL(9E)
2 2
3 3
4 4
5 5 NAME
6 6 chpoll - poll entry point for a non-STREAMS character driver
7 7
8 8 SYNOPSIS
9 9 #include <sys/types.h>
10 10 #include <sys/poll.h>
11 11 #include <sys/ddi.h>
12 12 #include <sys/sunddi.h>
13 13
14 14
15 15
16 16 int prefixchpoll(dev_t dev, short events, int anyyet,
17 17 short *reventsp, struct pollhead **phpp);
18 18
19 19
20 20 INTERFACE LEVEL
21 21 This entry point is optional. Architecture independent level 1
22 22 (DDI/DKI).
23 23
24 24 PARAMETERS
25 25 dev
26 26 The device number for the device to be polled.
27 27
28 28
29 29 events
30 30 The events that may occur. Valid events are:
31 31
32 32 POLLIN
33 33 Data other than high priority data may be
34 34 read without blocking.
35 35
36 36
37 37 POLLOUT
38 38 Normal data may be written without blocking.
39 39
40 40
41 41 POLLPRI
42 42 High priority data may be received without
43 43 blocking.
44 44
45 45
46 46 POLLHUP
47 47 A device hangup has occurred.
48 48
49 49
50 50 POLLERR
51 51 An error has occurred on the device.
52 52
53 53
54 54 POLLRDNORM
55 55 Normal data (priority band = 0) may be read
56 56 without blocking.
57 57
58 58
59 59 POLLRDBAND
60 60 Data from a non-zero priority band may be
61 61 read without blocking
62 62
63 63
64 64 POLLWRNORM
65 65 The same as POLLOUT.
66 66
67 67
68 68 POLLWRBAND
69 69 Priority data (priority band > 0) may be
70 70 written.
71 71
72 72
73 73 POLLET
74 74 The desired event is to be edge-triggered;
75 75 calls to pollwakeup(9F) should not be
76 76 suppressed, even if the event is pending at
77 77 the time of call to the chpoll() function.
78 78
79 79
80 80
81 81 anyyet
82 82 A flag that is non-zero if any other file descriptors in
83 83 the pollfd array have events pending. The poll(2) system
84 84 call takes a pointer to an array of pollfd structures as
85 85 one of its arguments. See the poll(2) reference page for
86 86 more details.
87 87
88 88
89 89 reventsp
90 90 A pointer to a bitmask of the returned events satisfied.
91 91
92 92
93 93 phpp
94 94 A pointer to a pointer to a pollhead structure.
95 95
96 96
97 97 DESCRIPTION
98 98 The chpoll() entry point routine is used by non-STREAMS character
99 99 device drivers that wish to support polling. The driver must implement
|
↓ open down ↓ |
99 lines elided |
↑ open up ↑ |
100 100 the polling discipline itself. The following rules must be followed
101 101 when implementing the polling discipline:
102 102
103 103 1. Implement the following algorithm when the chpoll() entry
104 104 point is called:
105 105
106 106 if (specified_events_are_satisfied_now) {
107 107 *reventsp = satisfied_events & events;
108 108 } else {
109 109 *reventsp = 0;
110 - if (!anyyet)
111 - *phpp = &my_local_pollhead_structure;
112 110 }
111 + if ((*reventsp == 0 && !anyyet) || (events & POLLET))
112 + *phpp = &my_local_pollhead_structure;
113 113 return (0);
114 114
115 + Note: Prior to the integration of epoll(5), which included
116 + edge-triggering via the POLLET flag, standard chpoll
117 + mechanisms would only provide a pollhead in phpp if there
118 + were no matching events. Edge-triggered polling requires
119 + that pollwakeup() always be called for a resource, so if
120 + POLLET is set in the events of interest, the chpoll method
121 + must yield a pollhead and prepare to issue pollwakeup()
122 + calls on it.
115 123
124 + Drivers which are not wired up to make pollwakeup() calls on
125 + a pollhead when their status changes should emit one from
126 + their chpoll routine. This will exclude the resource from
127 + caching by pollers, since it cannot alert them to new events
128 + without pollwakeup() notification.
129 +
130 +
116 131 2. Allocate an instance of the pollhead structure. This
117 132 instance may be tied to the per-minor data structure defined
118 133 by the driver. The pollhead structure should be treated as a
119 134 "black box" by the driver. Initialize the pollhead structure
120 135 by filling it with zeroes. The size of this structure is
121 136 guaranteed to remain the same across releases.
122 137
123 138 3. Call the pollwakeup() function with events listed above
124 139 whenever pollable events which the driver should monitor
125 140 occur. This function can be called with multiple events at
126 141 one time. The pollwakup() can be called regardless of
127 142 whether or not the chpoll() entry is called; it should be
128 143 called every time the driver detects the pollable event. The
129 144 driver must not hold any mutex across the call to
130 145 pollwakeup(9F) that is acquired in its chpoll() entry point,
131 146 or a deadlock may result. Note that if POLLET is set in the
132 147 specified events, the driver must call pollwakeup(9F) on
133 148 subsequent events, even if events are pending at the time of
134 149 the call to chpoll().
135 150
136 151
137 152 4. In the close(9E) entry point, the driver should call
138 153 pollwakeup() on the pollhead structure that corresponds to
139 154 the closing software state, specifying POLLERR for the
140 155 events. Further, upon return from pollwakeup(), the
141 156 driver's close(9E) entry point should call the
142 157 pollhead_clean(9F) function, specifying the pollhead that
143 158 corresponds to the structure that will be deallocated:
144 159
145 160
146 161 static int
147 162 mydriver_close(dev_t dev, int flag, int otyp, cred_t *cp)
148 163 {
149 164 minor_t minor = getminor(dev);
150 165 mydriver_state_t *state;
151 166
152 167 state = ddi_get_soft_state(mydriver_softstate, minor);
153 168
154 169 pollwakeup(&state->mydriver_pollhd, POLLERR);
155 170 pollhead_clean(&state->mydriver_pollhd);
156 171 ...
|
↓ open down ↓ |
31 lines elided |
↑ open up ↑ |
157 172
158 173 This step is necessary to inform other kernel subsystems
159 174 that the memory associated with the pollhead is about to be
160 175 deallocated by the close(9E) entry point.
161 176
162 177
163 178 RETURN VALUES
164 179 chpoll() should return 0 for success, or the appropriate error number.
165 180
166 181 SEE ALSO
167 - poll(2), nochpoll(9F), pollwakeup(9F)
182 + poll(2), epoll(5), nochpoll(9F), pollwakeup(9F)
168 183
169 184
170 185 Writing Device Drivers
171 186
172 187
173 188
174 - May 7, 2008 CHPOLL(9E)
189 + January 18, 2017 CHPOLL(9E)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX