| blob | 66a4369844ab78c980ee8b80fee1a45464eba1ce |
1 '\" te
2 .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH CSX_EVENT_HANDLER 9E "Nov 22, 1996"
7 .SH NAME
8 csx_event_handler \- PC Card driver event handler
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/pccard.h>
16 \fBint32_t prefix\fR\fBevent_handler\fR(\fBevent_t\fR \fIevent\fR, \fBint32_t\fR \fIpriority\fR,
17 \fBevent_callback_args_t *\fR\fIargs\fR);
18 .fi
20 .SH INTERFACE LEVEL
21 .sp
22 .LP
23 Solaris architecture specific (Solaris \fBDDI) \fR
24 .SH PARAMETERS
25 .sp
26 .ne 2
27 .na
28 \fB\fIevent\fR\fR
29 .ad
30 .RS 12n
31 The event.
32 .RE
34 .sp
35 .ne 2
36 .na
37 \fB\fIpriority\fR\fR
38 .ad
39 .RS 12n
40 The priority of the event.
41 .RE
43 .sp
44 .ne 2
45 .na
46 \fB\fIargs\fR\fR
47 .ad
48 .RS 12n
49 A pointer to the \fBevent_callback_t\fR structure.
50 .RE
52 .SH DESCRIPTION
53 .sp
54 .LP
55 Each instance of a \fBPC \fRCard driver must register an event handler to
56 manage events associated with its \fBPC \fRCard. The driver event handler is
57 registered using the \fBevent_handler\fR field of the \fBclient_req_t\fR
58 structure passed to \fBcsx_RegisterClient\fR(9F). The driver may also supply a
59 parameter to be passed to its event handler function using the
60 \fBevent_callback_args.client_data\fR field. Typically, this argument is the
61 driver instance's soft state pointer. The driver also registers which events it
62 is interested in receiving through the \fBEventMask\fR field of the
63 \fBclient_req_t\fR structure.
64 .sp
65 .LP
66 Each event is delivered to the driver with a priority, \fIpriority\fR. High
67 priority events with \fBCS_EVENT_PRI_HIGH\fR set in \fIpriority\fR are
68 delivered above lock level, and the driver must use its high-level event mutex
69 initialized with the \fBiblk_cookie\fR returned by \fBcsx_RegisterClient\fR(9F)
70 to protect such events. Low priority events with \fBCS_EVENT_PRI_LOW\fR set in
71 \fIpriority\fR are delivered below lock level, and the driver must use its
72 low-level event mutex initialized with a \fBNULL \fRinterrupt cookie to protect
73 these events.
74 .sp
75 .LP
76 \fBcsx_RegisterClient\fR(9F) registers the driver's event handler, but no
77 events begin to be delivered to the driver until after a successful call to
78 \fBcsx_RequestSocketMask\fR(9F).
79 .sp
80 .LP
81 In all cases, Card Services delivers an event to each driver instance
82 associated with a function on a multiple function \fBPC \fRCard.
83 .SS "Event Indications"
84 .sp
85 .LP
86 The events and their indications are listed below; they are always delivered as
87 low priority unless otherwise noted:
88 .sp
89 .ne 2
90 .na
91 \fB\fBCS_EVENT_REGISTRATION_COMPLETE\fR\fR
92 .ad
93 .sp .6
94 .RS 4n
95 A registration request processed in the background has been completed.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBCS_EVENT_CARD_INSERTION\fR\fR
102 .ad
103 .sp .6
104 .RS 4n
105 A \fBPC \fRCard has been inserted in a socket.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fBCS_EVENT_CARD_READY\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 A \fBPC \fRCard's \fBREADY \fRline has transitioned from the busy to ready
116 state.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fB\fBCS_EVENT_CARD_REMOVAL\fR\fR
123 .ad
124 .sp .6
125 .RS 4n
126 A \fBPC \fRCard has been removed from a socket. This event is delivered twice;
127 first as a high priority event, followed by delivery as a low priority event.
128 As a high priority event, the event handler should only note that the \fBPC
129 \fRCard is no longer present to prevent accesses to the hardware from
130 occurring. As a low priority event, the event handler should release the
131 configuration and free all \fBI/O\fR, window and \fBIRQ \fRresources for use by
132 other \fBPC \fRCards.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fBCS_EVENT_BATTERY_LOW\fR\fR
139 .ad
140 .sp .6
141 .RS 4n
142 The battery on a \fBPC \fRCard is weak and is in need of replacement.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBCS_EVENT_BATTERY_DEAD\fR\fR
149 .ad
150 .sp .6
151 .RS 4n
152 The battery on a \fBPC \fRCard is no longer providing operational voltage.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBCS_EVENT_PM_RESUME\fR\fR
159 .ad
160 .sp .6
161 .RS 4n
162 Card Services has received a resume notification from the system's Power
163 Management software.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fBCS_EVENT_PM_SUSPEND\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 Card Services has received a suspend notification from the system's Power
174 Management software.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fBCS_EVENT_CARD_LOCK\fR\fR
181 .ad
182 .sp .6
183 .RS 4n
184 A mechanical latch has been manipulated preventing the removal of the \fBPC
185 \fRCard from the socket.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fBCS_EVENT_CARD_UNLOCK\fR\fR
192 .ad
193 .sp .6
194 .RS 4n
195 A mechanical latch has been manipulated allowing the removal of the \fBPC
196 \fRCard from the socket.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fBCS_EVENT_EJECTION_REQUEST\fR\fR
203 .ad
204 .sp .6
205 .RS 4n
206 A request that the \fBPC \fRCard be ejected from a socket using a motor-driven
207 mechanism.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBCS_EVENT_EJECTION_COMPLETE\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 A motor has completed ejecting a \fBPC \fRCard from a socket.
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB\fBCS_EVENT_ERASE_COMPLETE\fR\fR
224 .ad
225 .sp .6
226 .RS 4n
227 A queued erase request that is processed in the background has been completed.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBCS_EVENT_INSERTION_REQUEST\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 A request that a \fBPC \fRCard be inserted into a socket using a motor-driven
238 mechanism.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBCS_EVENT_INSERTION_COMPLETE\fR\fR
245 .ad
246 .sp .6
247 .RS 4n
248 A motor has completed inserting a \fBPC \fRCard in a socket.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fBCS_EVENT_CARD_RESET\fR\fR
255 .ad
256 .sp .6
257 .RS 4n
258 A hardware reset has occurred.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fBCS_EVENT_RESET_REQUEST\fR\fR
265 .ad
266 .sp .6
267 .RS 4n
268 A request for a physical reset by a client.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBCS_EVENT_RESET_COMPLETE\fR\fR
275 .ad
276 .sp .6
277 .RS 4n
278 A reset request that is processed in the background has been completed.
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fB\fBCS_EVENT_RESET_PHYSICAL\fR\fR
285 .ad
286 .sp .6
287 .RS 4n
288 A reset is about to occur.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBCS_EVENT_CLIENT_INFO\fR\fR
295 .ad
296 .sp .6
297 .RS 4n
298 A request that the client return its client information data. If
299 \fBGET_CLIENT_INFO_SUBSVC(args->client_info.Attributes)\fR is equal to
300 \fBCS_CLIENT_INFO_SUBSVC_CS\fR, the driver should fill in the other fields in
301 the \fBclient_info\fR structure as described below, and return
302 \fBCS_SUCCESS\fR. Otherwise, it should return \fBCS_UNSUPPORTED_EVENT.\fR
303 .sp
304 .ne 2
305 .na
306 \fB\fBargs->client_data.Attributes\fR\fR
307 .ad
308 .sp .6
309 .RS 4n
310 Must be \fBOR\fR'ed with \fBCS_CLIENT_INFO_VALID\fR.
311 .RE
313 .sp
314 .ne 2
315 .na
316 \fB\fBargs->client_data.Revision\fR\fR
317 .ad
318 .sp .6
319 .RS 4n
320 Must be set to a driver-private version number.
321 .RE
323 .sp
324 .ne 2
325 .na
326 \fB\fBargs->client_data.CSLevel\fR\fR
327 .ad
328 .sp .6
329 .RS 4n
330 Must be set to \fBCS_VERSION\fR.
331 .RE
333 .sp
334 .ne 2
335 .na
336 \fB\fBargs->client_data.RevDate\fR\fR
337 .ad
338 .sp .6
339 .RS 4n
340 Must be set to the revision date of the \fBPC \fRCard driver, using
341 \fBCS_CLIENT_INFO_MAKE_DATE(\fIday\fR,\fR \fImonth\fR, \fIyear\fR). \fIday\fR
342 must be the day of the month, \fImonth\fR must be the month of the year, and
343 \fIyear\fR must be the year, offset from a base of 1980. For example, this
344 field could be set to a revision date of July 4 1997 with
345 \fBCS_CLIENT_INFO_MAKE_DATE(4, 7, 17)\fR.
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fBargs->client_data.ClientName\fR\fR
352 .ad
353 .sp .6
354 .RS 4n
355 A string describing the \fBPC \fRCard driver should be copied into this space.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBargs->client_data.VendorName\fR\fR
362 .ad
363 .sp .6
364 .RS 4n
365 A string supplying the name of the \fBPC \fRCard driver vendor should be copied
366 into this space.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBargs->client_data.DriverName\fR\fR
373 .ad
374 .sp .6
375 .RS 4n
376 A string supplying the name of the \fBPC \fRCard driver will be copied into
377 this space by Card Services after the \fBPC \fRCard driver has successfully
378 processed this event; the driver does not need to initialize this field.
379 .RE
381 .RE
383 .sp
384 .ne 2
385 .na
386 \fB\fBCS_EVENT_WRITE_PROTECT\fR\fR
387 .ad
388 .sp .6
389 .RS 4n
390 The write protect status of the \fBPC \fRCard in the indicated socket has
391 changed. The current write protect state of the \fBPC \fRCard is in the
392 \fBargs->info\fR field:
393 .sp
394 .ne 2
395 .na
396 \fB\fBCS_EVENT_WRITE_PROTECT_WPOFF\fR\fR
397 .ad
398 .sp .6
399 .RS 4n
400 Card is not write protected.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBCS_EVENT_WRITE_PROTECT_WPON\fR\fR
407 .ad
408 .sp .6
409 .RS 4n
410 Card is write protected.
411 .RE
413 .RE
415 .SH STRUCTURE MEMBERS
416 .sp
417 .LP
418 The structure members of \fBevent_callback_args_t\fR are:
419 .sp
420 .in +2
421 .nf
422 void *info; /* event-specific information */
423 void *client_data; /* driver-private data */
424 client_info_t client_info; /* client information*/
425 .fi
426 .in -2
428 .sp
429 .LP
430 The structure members of \fBclient_info_t\fR are:
431 .sp
432 .in +2
433 .nf
434 unit32_t Attributes; /* attributes */
435 unit32_t Revisions; /* version number */
436 uint32_t CSLevel; /* Card Services version */
437 uint32_t RevDate; /* revision date */
438 char ClientName[CS_CLIENT_INFO_MAX_NAME_LEN];
439 /*PC Card driver description */
440 char VendorName[CS_CLIENT_INFO_MAX_NAME_LEN];
441 /*PC Card driver vendor name */
442 char DriverName[MODMAXNAMELEN];
443 /* PC Card driver name */
444 .fi
445 .in -2
447 .SH RETURN VALUES
448 .sp
449 .ne 2
450 .na
451 \fB\fBCS_SUCCESS\fR\fR
452 .ad
453 .RS 24n
454 The event was handled successfully.
455 .RE
457 .sp
458 .ne 2
459 .na
460 \fB\fBCS_UNSUPPORTED_EVENT\fR\fR
461 .ad
462 .RS 24n
463 Driver does not support this event.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB\fBCS_FAILURE\fR\fR
470 .ad
471 .RS 24n
472 Error occurred while handling this event.
473 .RE
475 .SH CONTEXT
476 .sp
477 .LP
478 This function is called from high-level interrupt context in the case of high
479 priority events, and from kernel context in the case of low priority events.
480 .SH EXAMPLES
481 .sp
482 .in +2
483 .nf
484 static int
485 xx_event(event_t event, int priority, event_callback_args_t *args)
486 {
487 int rval;
488 struct xxx *xxx = args->client_data;
489 client_info_t *info = &args->client_info;
491 switch (event) {
492 case CS_EVENT_REGISTRATION_COMPLETE:
493 ASSERT(priority & CS_EVENT_PRI_LOW);
494 mutex_enter(&xxx->event_mutex);
495 xxx->card_state |= XX_REGISTRATION_COMPLETE;
496 mutex_exit(&xxx->event_mutex);
497 rval = CS_SUCCESS;
498 break;
500 case CS_EVENT_CARD_READY:
501 ASSERT(priority & CS_EVENT_PRI_LOW);
502 rval = xx_card_ready(xxx);
503 mutex_exit(&xxx->event_mutex);
504 break;
506 case CS_EVENT_CARD_INSERTION:
507 ASSERT(priority & CS_EVENT_PRI_LOW);
508 mutex_enter(&xxx->event_mutex);
509 rval = xx_card_insertion(xxx);
510 mutex_exit(&xxx->event_mutex);
511 break;
513 case CS_EVENT_CARD_REMOVAL:
514 if (priority & CS_EVENT_PRI_HIGH) {
515 mutex_enter(&xxx->hi_event_mutex);
516 xxx->card_state &= ~XX_CARD_PRESENT;
517 mutex_exit(&xxx->hi_event_mutex);
518 } else {
519 mutex_enter(&xxx->event_mutex);
520 rval = xx_card_removal(xxx);
521 mutex_exit(&xxx->event_mutex);
522 }
523 break;
525 case CS_EVENT_CLIENT_INFO:
526 ASSERT(priority & CS_EVENT_PRI_LOW);
527 if (GET_CLIENT_INFO_SUBSVC_CS(info->Attributes) ==
528 CS_CLIENT_INFO_SUBSVC_CS) {
529 info->Attributes |= CS_CLIENT_INFO_VALID;
530 info->Revision = 4;
531 info->CSLevel = CS_VERSION;
532 info->RevDate = CS_CLIENT_INFO_MAKE_DATE(4, 7, 17);
533 (void)strncpy(info->ClientName,
534 "WhizBang Ultra Zowie PC card driver",
535 CS_CLIENT_INFO_MAX_NAME_LEN)
537 "ACME PC card drivers, Inc.",
538 CS_CLIENT_INFO_MAX_NAME_LEN);
539 rval = CS_SUCCESS;
540 } else {
541 rval = CS_UNSUPPORTED_EVENT;
542 }
543 break;
546 case CS_EVENT_WRITE_PROTECT:
547 ASSERT(priority & CS_EVENT_PRI_LOW);
548 mutex_enter(&xxx->event_mutex);
549 if (args->info == CS_EVENT_WRITE_PROTECT_WPOFF) {
550 xxx->card_state &= ~XX_WRITE_PROTECTED;
551 } else {
552 xxx->card_state |= XX_WRITE_PROTECTED;
553 }
554 mutex_exit(&xxx->event_mutex);
555 rval = CS_SUCCESS;
556 break;
558 default:
559 rval = CS_UNSUPPORTED_EVENT;
560 break;
561 }
563 return (rval);
564 }
565 .fi
566 .in -2
568 .SH SEE ALSO
569 .sp
570 .LP
571 \fBcsx_Event2Text\fR(9F), \fBcsx_RegisterClient\fR(9F),
572 \fBcsx_RequestSocketMask\fR(9F)
573 .sp
574 .LP
575 \fIPC Card 95 Standard\fR, PCMCIA/JEIDA