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