1csx_event_handler(9E) Driver Entry Points csx_event_handler(9E)
2
6 csx_event_handler - PC Card driver event handler
7
9 #include <sys/pccard.h>
10 int32_t prefixevent_handler(event_t event, int32_t priority,
14 event_callback_args_t *args);
15
18 Solaris architecture specific (Solaris DDI)
19
21 event The event.
22 priority The priority of the event.
25 args A pointer to the event_callback_t structure.
28
31 Each instance of a PC Card driver must register an event handler to
32 manage events associated with its PC Card. The driver event handler is
33 registered using the event_handler field of the client_req_t structure
34 passed to csx_RegisterClient(9F). The driver may also supply a parame‐
35 ter to be passed to its event handler function using the event_call‐
36 back_args.client_data field. Typically, this argument is the driver
37 instance's soft state pointer. The driver also registers which events
38 it is interested in receiving through the EventMask field of the
39 client_req_t structure.
40 Each event is delivered to the driver with a priority, priority. High
43 priority events with CS_EVENT_PRI_HIGH set in priority are delivered
44 above lock level, and the driver must use its high-level event mutex
45 initialized with the iblk_cookie returned by csx_RegisterClient(9F) to
46 protect such events. Low priority events with CS_EVENT_PRI_LOW set in
47 priority are delivered below lock level, and the driver must use its
48 low-level event mutex initialized with a NULL interrupt cookie to pro‐
49 tect these events.
50 csx_RegisterClient(9F) registers the driver's event handler, but no
53 events begin to be delivered to the driver until after a successful
54 call to csx_RequestSocketMask(9F).
55 In all cases, Card Services delivers an event to each driver instance
58 associated with a function on a multiple function PC Card.
59 Event Indications
61 The events and their indications are listed below; they are always
62 delivered as low priority unless otherwise noted:
63 CS_EVENT_REGISTRATION_COMPLETE
65 A registration request processed in the background has been com‐
67 pleted.
68 CS_EVENT_CARD_INSERTION
71 A PC Card has been inserted in a socket.
73 CS_EVENT_CARD_READY
76 A PC Card's READY line has transitioned from the busy to ready
78 state.
79 CS_EVENT_CARD_REMOVAL
82 A PC Card has been removed from a socket. This event is delivered
84 twice; first as a high priority event, followed by delivery as a
85 low priority event. As a high priority event, the event handler
86 should only note that the PC Card is no longer present to prevent
87 accesses to the hardware from occurring. As a low priority event,
88 the event handler should release the configuration and free all
89 I/O, window and IRQ resources for use by other PC Cards.
90 CS_EVENT_BATTERY_LOW
93 The battery on a PC Card is weak and is in need of replacement.
95 CS_EVENT_BATTERY_DEAD
98 The battery on a PC Card is no longer providing operational volt‐
100 age.
101 CS_EVENT_PM_RESUME
104 Card Services has received a resume notification from the system's
106 Power Management software.
107 CS_EVENT_PM_SUSPEND
110 Card Services has received a suspend notification from the system's
112 Power Management software.
113 CS_EVENT_CARD_LOCK
116 A mechanical latch has been manipulated preventing the removal of
118 the PC Card from the socket.
119 CS_EVENT_CARD_UNLOCK
122 A mechanical latch has been manipulated allowing the removal of the
124 PC Card from the socket.
125 CS_EVENT_EJECTION_REQUEST
128 A request that the PC Card be ejected from a socket using a motor-
130 driven mechanism.
131 CS_EVENT_EJECTION_COMPLETE
134 A motor has completed ejecting a PC Card from a socket.
136 CS_EVENT_ERASE_COMPLETE
139 A queued erase request that is processed in the background has been
141 completed.
142 CS_EVENT_INSERTION_REQUEST
145 A request that a PC Card be inserted into a socket using a motor-
147 driven mechanism.
148 CS_EVENT_INSERTION_COMPLETE
151 A motor has completed inserting a PC Card in a socket.
153 CS_EVENT_CARD_RESET
156 A hardware reset has occurred.
158 CS_EVENT_RESET_REQUEST
161 A request for a physical reset by a client.
163 CS_EVENT_RESET_COMPLETE
166 A reset request that is processed in the background has been com‐
168 pleted.
169 CS_EVENT_RESET_PHYSICAL
172 A reset is about to occur.
174 CS_EVENT_CLIENT_INFO
177 A request that the client return its client information data. If
179 GET_CLIENT_INFO_SUBSVC(args->client_info.Attributes) is equal to
180 CS_CLIENT_INFO_SUBSVC_CS, the driver should fill in the other
181 fields in the client_info structure as described below, and return
182 CS_SUCCESS. Otherwise, it should return CS_UNSUPPORTED_EVENT.
183 args->client_data.Attributes
185 Must be OR'ed with CS_CLIENT_INFO_VALID.
187 args->client_data.Revision
190 Must be set to a driver-private version number.
192 args->client_data.CSLevel
195 Must be set to CS_VERSION.
197 args->client_data.RevDate
200 Must be set to the revision date of the PC Card driver, using
202 CS_CLIENT_INFO_MAKE_DATE(day, month, year). day must be the day
203 of the month, month must be the month of the year, and year
204 must be the year, offset from a base of 1980. For example, this
205 field could be set to a revision date of July 4 1997 with
206 CS_CLIENT_INFO_MAKE_DATE(4, 7, 17).
207 args->client_data.ClientName
210 A string describing the PC Card driver should be copied into
212 this space.
213 args->client_data.VendorName
216 A string supplying the name of the PC Card driver vendor should
218 be copied into this space.
219 args->client_data.DriverName
222 A string supplying the name of the PC Card driver will be
224 copied into this space by Card Services after the PC Card
225 driver has successfully processed this event; the driver does
226 not need to initialize this field.
227 CS_EVENT_WRITE_PROTECT
231 The write protect status of the PC Card in the indicated socket has
233 changed. The current write protect state of the PC Card is in the
234 args->info field:
235 CS_EVENT_WRITE_PROTECT_WPOFF
237 Card is not write protected.
239 CS_EVENT_WRITE_PROTECT_WPON
242 Card is write protected.
244
248 The structure members of event_callback_args_t are:
249 void *info; /* event-specific information */
251 void *client_data; /* driver-private data */
252 client_info_t client_info; /* client information*/
253 The structure members of client_info_t are:
257 unit32_t Attributes; /* attributes */
259 unit32_t Revisions; /* version number */
260 uint32_t CSLevel; /* Card Services version */
261 uint32_t RevDate; /* revision date */
262 char ClientName[CS_CLIENT_INFO_MAX_NAME_LEN];
263 /*PC Card driver description */
264 char VendorName[CS_CLIENT_INFO_MAX_NAME_LEN];
265 /*PC Card driver vendor name */
266 char DriverName[MODMAXNAMELEN];
267 /* PC Card driver name */
268
271 CS_SUCCESS The event was handled successfully.
272 CS_UNSUPPORTED_EVENT Driver does not support this event.
275 CS_FAILURE Error occurred while handling this event.
278
281 This function is called from high-level interrupt context in the case
282 of high priority events, and from kernel context in the case of low
283 priority events.
284
286 static int
287 xx_event(event_t event, int priority, event_callback_args_t *args)
288 {
289 int rval;
290 struct xxx *xxx = args->client_data;
291 client_info_t *info = &args->client_info;
292 switch (event) {
294 case CS_EVENT_REGISTRATION_COMPLETE:
295 ASSERT(priority & CS_EVENT_PRI_LOW);
296 mutex_enter(&xxx->event_mutex);
297 xxx->card_state |= XX_REGISTRATION_COMPLETE;
298 mutex_exit(&xxx->event_mutex);
299 rval = CS_SUCCESS;
300 break;
301 case CS_EVENT_CARD_READY:
303 ASSERT(priority & CS_EVENT_PRI_LOW);
304 rval = xx_card_ready(xxx);
305 mutex_exit(&xxx->event_mutex);
306 break;
307 case CS_EVENT_CARD_INSERTION:
309 ASSERT(priority & CS_EVENT_PRI_LOW);
310 mutex_enter(&xxx->event_mutex);
311 rval = xx_card_insertion(xxx);
312 mutex_exit(&xxx->event_mutex);
313 break;
314 case CS_EVENT_CARD_REMOVAL:
316 if (priority & CS_EVENT_PRI_HIGH) {
317 mutex_enter(&xxx->hi_event_mutex);
318 xxx->card_state &= ~XX_CARD_PRESENT;
319 mutex_exit(&xxx->hi_event_mutex);
320 } else {
321 mutex_enter(&xxx->event_mutex);
322 rval = xx_card_removal(xxx);
323 mutex_exit(&xxx->event_mutex);
324 }
325 break;
326 case CS_EVENT_CLIENT_INFO:
328 ASSERT(priority & CS_EVENT_PRI_LOW);
329 if (GET_CLIENT_INFO_SUBSVC_CS(info->Attributes) ==
330 CS_CLIENT_INFO_SUBSVC_CS) {
331 info->Attributes |= CS_CLIENT_INFO_VALID;
332 info->Revision = 4;
333 info->CSLevel = CS_VERSION;
334 info->RevDate = CS_CLIENT_INFO_MAKE_DATE(4, 7, 17);
335 (void)strncpy(info->ClientName,
336 "WhizBang Ultra Zowie PC card driver",
337 CS_CLIENT_INFO_MAX_NAME_LEN)
338 "ACME PC card drivers, Inc.",
340 CS_CLIENT_INFO_MAX_NAME_LEN);
341 rval = CS_SUCCESS;
342 } else {
343 rval = CS_UNSUPPORTED_EVENT;
344 }
345 break;
346 case CS_EVENT_WRITE_PROTECT:
349 ASSERT(priority & CS_EVENT_PRI_LOW);
350 mutex_enter(&xxx->event_mutex);
351 if (args->info == CS_EVENT_WRITE_PROTECT_WPOFF) {
352 xxx->card_state &= ~XX_WRITE_PROTECTED;
353 } else {
354 xxx->card_state |= XX_WRITE_PROTECTED;
355 }
356 mutex_exit(&xxx->event_mutex);
357 rval = CS_SUCCESS;
358 break;
359 default:
361 rval = CS_UNSUPPORTED_EVENT;
362 break;
363 }
364 return (rval);
366 }
367
370 csx_Event2Text(9F), csx_RegisterClient(9F), csx_RequestSocketMask(9F)
371 PC Card 95 Standard, PCMCIA/JEIDA
374SunOS 5.11 22 Nov 1996 csx_event_handler(9E)