usr/src/man/man9e/chpoll.9e

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