share/man/man9e/chpoll.9e

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Copyright 2017 Joyent, Inc
   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.
   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.
   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]
   8 .TH CHPOLL 9E "Jan 18, 2017"
   9 .SH NAME
  10 chpoll \- poll entry point for a non-STREAMS character driver
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/types.h>
  15 #include <sys/poll.h>
  16 #include <sys/ddi.h>
  17 #include <sys/sunddi.h>
  18
  19
  20
  21 \fBint prefix\fR\fBchpoll\fR(\fBdev_t\fR \fIdev\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR,
  22      \fBshort *\fR\fIreventsp\fR, \fBstruct pollhead **\fR\fIphpp\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .LP
  27 This entry point is optional. Architecture independent level 1 (DDI/DKI).
  28 .SH PARAMETERS
  29 .ne 2
  30 .na
  31 \fB\fIdev\fR\fR
  32 .ad
  33 .RS 12n
  34 The device number for the device to be polled.
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIevents\fR\fR
  41 .ad
  42 .RS 12n
  43 The events that may occur. Valid events are:
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBPOLLIN\fR\fR
  48 .ad
  49 .RS 14n
  50 Data other than high priority data may be read without blocking.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBPOLLOUT\fR\fR
  57 .ad
  58 .RS 14n
  59 Normal data may be written without blocking.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBPOLLPRI\fR\fR
  66 .ad
  67 .RS 14n
  68 High priority data may be received without blocking.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBPOLLHUP\fR\fR
  75 .ad
  76 .RS 14n
  77 A device hangup has occurred.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBPOLLERR\fR\fR
  84 .ad
  85 .RS 14n
  86 An error has occurred on the device.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBPOLLRDNORM\fR\fR
  93 .ad
  94 .RS 14n
  95 Normal data (priority band = 0) may be read without blocking.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBPOLLRDBAND\fR\fR
 102 .ad
 103 .RS 14n
 104 Data from a non-zero priority band may be read without blocking
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBPOLLWRNORM\fR\fR
 111 .ad
 112 .RS 14n
 113 The same as \fBPOLLOUT\fR.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBPOLLWRBAND\fR\fR
 120 .ad
 121 .RS 14n
 122 Priority data (priority band > 0) may be written.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBPOLLET\fR\fR
 129 .ad
 130 .RS 14n
 131 The desired event is to be edge-triggered; calls to \fBpollwakeup\fR(9F)
 132 should not be suppressed, even if the event is pending at the time of
 133 call to the \fBchpoll()\fR function.
 134 .RE
 135
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fIanyyet\fR\fR
 142 .ad
 143 .RS 12n
 144 A flag that is non-zero if any other file descriptors in the \fBpollfd\fR array
 145 have events pending. The \fBpoll\fR(2) system call takes a pointer to an array
 146 of \fBpollfd\fR structures as one of its arguments. See the \fBpoll\fR(2)
 147 reference page for more details.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fIreventsp\fR\fR
 154 .ad
 155 .RS 12n
 156 A pointer to a bitmask of the returned events satisfied.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fIphpp\fR\fR
 163 .ad
 164 .RS 12n
 165 A pointer to a pointer to a \fBpollhead\fR structure.
 166 .RE
 167
 168 .SH DESCRIPTION
 169 .LP
 170 The \fBchpoll()\fR entry point routine is used by non-STREAMS character device
 171 drivers that wish to support polling. The driver must implement the polling
 172 discipline itself. The following rules must be followed when implementing the
 173 polling discipline:
 174 .RS +4
 175 .TP
 176 1.
 177 Implement the following algorithm when the \fBchpoll()\fR entry point is
 178 called:
 179 .sp
 180 .in +2
 181 .nf
 182 if (specified_events_are_satisfied_now) {
 183       *reventsp = satisfied_events & events;
 184 } else {
 185       *reventsp = 0;
 186 }
 187 if ((*reventsp == 0 && !anyyet) || (events & POLLET))
 188       *phpp = &my_local_pollhead_structure;
 189 return (0);
 190 .fi
 191 .in -2
 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
 206 .RE
 207 .RS +4
 208 .TP
 209 2.
 210 Allocate an instance of the \fBpollhead\fR structure. This instance may be
 211 tied to the per-minor data structure defined by the driver. The \fBpollhead\fR
 212 structure should be treated as a "black box" by the driver. Initialize the
 213 \fBpollhead\fR structure by filling it with zeroes. The size of this structure
 214 is guaranteed to remain the same across releases.
 215 .RE
 216 .RS +4
 217 .TP
 218 3.
 219 Call the \fBpollwakeup()\fR function with \fBevents\fR listed above whenever
 220 pollable \fBevents\fR which the driver should monitor occur. This function can
 221 be called with multiple events at one time. The \fBpollwakup()\fR can be called
 222 regardless of whether or not the \fBchpoll()\fR entry is called; it should be
 223 called every time the driver detects the pollable event. The driver must not
 224 hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its
 225 \fBchpoll()\fR entry point, or a deadlock may result.  Note that if
 226 \fBPOLLET\fR is set in the specified events, the driver must call
 227 \fBpollwakeup\fR(9F) on subsequent events, even if events are pending at
 228 the time of the call to \fBchpoll()\fR.
 229
 230 .RE
 231 .RS +4
 232 .TP
 233 4.
 234 In the \fBclose\fR(9E) entry point, the driver should call \fBpollwakeup()\fR
 235 on the \fBpollhead\fR structure that corresponds to the closing software
 236 state, specifying \fBPOLLERR\fR for the events.  Further, upon return from
 237 \fBpollwakeup()\fR, the driver's \fBclose\fR(9E) entry point should call
 238 the \fBpollhead_clean\fR(9F) function, specifying the \fBpollhead\fR that
 239 corresponds to the structure that will be deallocated:
 240
 241 .sp
 242 .in +2
 243 .nf
 244 static int
 245 mydriver_close(dev_t dev, int flag, int otyp, cred_t *cp)
 246 {
 247       minor_t minor = getminor(dev);
 248       mydriver_state_t *state;
 249
 250       state = ddi_get_soft_state(mydriver_softstate, minor);
 251
 252       pollwakeup(&state->mydriver_pollhd, POLLERR);
 253       pollhead_clean(&state->mydriver_pollhd);
 254       ...
 255 .fi
 256 .in -2
 257
 258 This step is necessary to inform other kernel subsystems that the memory
 259 associated with the \fBpollhead\fR is about to be deallocated by the
 260 \fBclose\fR(9E) entry point.
 261
 262 .RE
 263 .SH RETURN VALUES
 264 .LP
 265 \fBchpoll()\fR should return \fB0\fR for success, or the appropriate error
 266 number.
 267 .SH SEE ALSO
 268 .LP
 269 \fBpoll\fR(2), \fBepoll\fR(5), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F)
 270 .sp
 271 .LP
 272 \fIWriting Device Drivers\fR