'\" te .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved .\" 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. .\" 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. .\" 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] .TH CSX_EVENT_HANDLER 9E "Nov 22, 1996" .SH NAME csx_event_handler \- PC Card driver event handler .SH SYNOPSIS .nf #include \fBint32_t prefix\fR\fBevent_handler\fR(\fBevent_t\fR \fIevent\fR, \fBint32_t\fR \fIpriority\fR, \fBevent_callback_args_t *\fR\fIargs\fR); .fi .SH INTERFACE LEVEL illumos architecture specific (illumos \fBDDI) \fR .SH PARAMETERS .ne 2 .na \fB\fIevent\fR\fR .ad .RS 12n The event. .RE .sp .ne 2 .na \fB\fIpriority\fR\fR .ad .RS 12n The priority of the event. .RE .sp .ne 2 .na \fB\fIargs\fR\fR .ad .RS 12n A pointer to the \fBevent_callback_t\fR structure. .RE .SH DESCRIPTION Each instance of a \fBPC \fRCard driver must register an event handler to manage events associated with its \fBPC \fRCard. The driver event handler is registered using the \fBevent_handler\fR field of the \fBclient_req_t\fR structure passed to \fBcsx_RegisterClient\fR(9F). The driver may also supply a parameter to be passed to its event handler function using the \fBevent_callback_args.client_data\fR field. Typically, this argument is the driver instance's soft state pointer. The driver also registers which events it is interested in receiving through the \fBEventMask\fR field of the \fBclient_req_t\fR structure. .sp .LP Each event is delivered to the driver with a priority, \fIpriority\fR. High priority events with \fBCS_EVENT_PRI_HIGH\fR set in \fIpriority\fR are delivered above lock level, and the driver must use its high-level event mutex initialized with the \fBiblk_cookie\fR returned by \fBcsx_RegisterClient\fR(9F) to protect such events. Low priority events with \fBCS_EVENT_PRI_LOW\fR set in \fIpriority\fR are delivered below lock level, and the driver must use its low-level event mutex initialized with a \fBNULL \fRinterrupt cookie to protect these events. .sp .LP \fBcsx_RegisterClient\fR(9F) registers the driver's event handler, but no events begin to be delivered to the driver until after a successful call to \fBcsx_RequestSocketMask\fR(9F). .sp .LP In all cases, Card Services delivers an event to each driver instance associated with a function on a multiple function \fBPC \fRCard. .SS "Event Indications" The events and their indications are listed below; they are always delivered as low priority unless otherwise noted: .sp .ne 2 .na \fB\fBCS_EVENT_REGISTRATION_COMPLETE\fR\fR .ad .sp .6 .RS 4n A registration request processed in the background has been completed. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_INSERTION\fR\fR .ad .sp .6 .RS 4n A \fBPC \fRCard has been inserted in a socket. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_READY\fR\fR .ad .sp .6 .RS 4n A \fBPC \fRCard's \fBREADY \fRline has transitioned from the busy to ready state. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_REMOVAL\fR\fR .ad .sp .6 .RS 4n A \fBPC \fRCard has been removed from a socket. This event is delivered twice; first as a high priority event, followed by delivery as a low priority event. As a high priority event, the event handler should only note that the \fBPC \fRCard is no longer present to prevent accesses to the hardware from occurring. As a low priority event, the event handler should release the configuration and free all \fBI/O\fR, window and \fBIRQ \fRresources for use by other \fBPC \fRCards. .RE .sp .ne 2 .na \fB\fBCS_EVENT_BATTERY_LOW\fR\fR .ad .sp .6 .RS 4n The battery on a \fBPC \fRCard is weak and is in need of replacement. .RE .sp .ne 2 .na \fB\fBCS_EVENT_BATTERY_DEAD\fR\fR .ad .sp .6 .RS 4n The battery on a \fBPC \fRCard is no longer providing operational voltage. .RE .sp .ne 2 .na \fB\fBCS_EVENT_PM_RESUME\fR\fR .ad .sp .6 .RS 4n Card Services has received a resume notification from the system's Power Management software. .RE .sp .ne 2 .na \fB\fBCS_EVENT_PM_SUSPEND\fR\fR .ad .sp .6 .RS 4n Card Services has received a suspend notification from the system's Power Management software. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_LOCK\fR\fR .ad .sp .6 .RS 4n A mechanical latch has been manipulated preventing the removal of the \fBPC \fRCard from the socket. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_UNLOCK\fR\fR .ad .sp .6 .RS 4n A mechanical latch has been manipulated allowing the removal of the \fBPC \fRCard from the socket. .RE .sp .ne 2 .na \fB\fBCS_EVENT_EJECTION_REQUEST\fR\fR .ad .sp .6 .RS 4n A request that the \fBPC \fRCard be ejected from a socket using a motor-driven mechanism. .RE .sp .ne 2 .na \fB\fBCS_EVENT_EJECTION_COMPLETE\fR\fR .ad .sp .6 .RS 4n A motor has completed ejecting a \fBPC \fRCard from a socket. .RE .sp .ne 2 .na \fB\fBCS_EVENT_ERASE_COMPLETE\fR\fR .ad .sp .6 .RS 4n A queued erase request that is processed in the background has been completed. .RE .sp .ne 2 .na \fB\fBCS_EVENT_INSERTION_REQUEST\fR\fR .ad .sp .6 .RS 4n A request that a \fBPC \fRCard be inserted into a socket using a motor-driven mechanism. .RE .sp .ne 2 .na \fB\fBCS_EVENT_INSERTION_COMPLETE\fR\fR .ad .sp .6 .RS 4n A motor has completed inserting a \fBPC \fRCard in a socket. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CARD_RESET\fR\fR .ad .sp .6 .RS 4n A hardware reset has occurred. .RE .sp .ne 2 .na \fB\fBCS_EVENT_RESET_REQUEST\fR\fR .ad .sp .6 .RS 4n A request for a physical reset by a client. .RE .sp .ne 2 .na \fB\fBCS_EVENT_RESET_COMPLETE\fR\fR .ad .sp .6 .RS 4n A reset request that is processed in the background has been completed. .RE .sp .ne 2 .na \fB\fBCS_EVENT_RESET_PHYSICAL\fR\fR .ad .sp .6 .RS 4n A reset is about to occur. .RE .sp .ne 2 .na \fB\fBCS_EVENT_CLIENT_INFO\fR\fR .ad .sp .6 .RS 4n A request that the client return its client information data. If \fBGET_CLIENT_INFO_SUBSVC(args->client_info.Attributes)\fR is equal to \fBCS_CLIENT_INFO_SUBSVC_CS\fR, the driver should fill in the other fields in the \fBclient_info\fR structure as described below, and return \fBCS_SUCCESS\fR. Otherwise, it should return \fBCS_UNSUPPORTED_EVENT.\fR .sp .ne 2 .na \fB\fBargs->client_data.Attributes\fR\fR .ad .sp .6 .RS 4n Must be \fBOR\fR'ed with \fBCS_CLIENT_INFO_VALID\fR. .RE .sp .ne 2 .na \fB\fBargs->client_data.Revision\fR\fR .ad .sp .6 .RS 4n Must be set to a driver-private version number. .RE .sp .ne 2 .na \fB\fBargs->client_data.CSLevel\fR\fR .ad .sp .6 .RS 4n Must be set to \fBCS_VERSION\fR. .RE .sp .ne 2 .na \fB\fBargs->client_data.RevDate\fR\fR .ad .sp .6 .RS 4n Must be set to the revision date of the \fBPC \fRCard driver, using \fBCS_CLIENT_INFO_MAKE_DATE(\fIday\fR,\fR \fImonth\fR, \fIyear\fR). \fIday\fR must be the day of the month, \fImonth\fR must be the month of the year, and \fIyear\fR must be the year, offset from a base of 1980. For example, this field could be set to a revision date of July 4 1997 with \fBCS_CLIENT_INFO_MAKE_DATE(4, 7, 17)\fR. .RE .sp .ne 2 .na \fB\fBargs->client_data.ClientName\fR\fR .ad .sp .6 .RS 4n A string describing the \fBPC \fRCard driver should be copied into this space. .RE .sp .ne 2 .na \fB\fBargs->client_data.VendorName\fR\fR .ad .sp .6 .RS 4n A string supplying the name of the \fBPC \fRCard driver vendor should be copied into this space. .RE .sp .ne 2 .na \fB\fBargs->client_data.DriverName\fR\fR .ad .sp .6 .RS 4n A string supplying the name of the \fBPC \fRCard driver will be copied into this space by Card Services after the \fBPC \fRCard driver has successfully processed this event; the driver does not need to initialize this field. .RE .RE .sp .ne 2 .na \fB\fBCS_EVENT_WRITE_PROTECT\fR\fR .ad .sp .6 .RS 4n The write protect status of the \fBPC \fRCard in the indicated socket has changed. The current write protect state of the \fBPC \fRCard is in the \fBargs->info\fR field: .sp .ne 2 .na \fB\fBCS_EVENT_WRITE_PROTECT_WPOFF\fR\fR .ad .sp .6 .RS 4n Card is not write protected. .RE .sp .ne 2 .na \fB\fBCS_EVENT_WRITE_PROTECT_WPON\fR\fR .ad .sp .6 .RS 4n Card is write protected. .RE .RE .SH STRUCTURE MEMBERS The structure members of \fBevent_callback_args_t\fR are: .sp .in +2 .nf void *info; /* event-specific information */ void *client_data; /* driver-private data */ client_info_t client_info; /* client information*/ .fi .in -2 .sp .LP The structure members of \fBclient_info_t\fR are: .sp .in +2 .nf unit32_t Attributes; /* attributes */ unit32_t Revisions; /* version number */ uint32_t CSLevel; /* Card Services version */ uint32_t RevDate; /* revision date */ char ClientName[CS_CLIENT_INFO_MAX_NAME_LEN]; /*PC Card driver description */ char VendorName[CS_CLIENT_INFO_MAX_NAME_LEN]; /*PC Card driver vendor name */ char DriverName[MODMAXNAMELEN]; /* PC Card driver name */ .fi .in -2 .SH RETURN VALUES .ne 2 .na \fB\fBCS_SUCCESS\fR\fR .ad .RS 24n The event was handled successfully. .RE .sp .ne 2 .na \fB\fBCS_UNSUPPORTED_EVENT\fR\fR .ad .RS 24n Driver does not support this event. .RE .sp .ne 2 .na \fB\fBCS_FAILURE\fR\fR .ad .RS 24n Error occurred while handling this event. .RE .SH CONTEXT This function is called from high-level interrupt context in the case of high priority events, and from kernel context in the case of low priority events. .SH EXAMPLES .in +2 .nf static int xx_event(event_t event, int priority, event_callback_args_t *args) { int rval; struct xxx *xxx = args->client_data; client_info_t *info = &args->client_info; switch (event) { case CS_EVENT_REGISTRATION_COMPLETE: ASSERT(priority & CS_EVENT_PRI_LOW); mutex_enter(&xxx->event_mutex); xxx->card_state |= XX_REGISTRATION_COMPLETE; mutex_exit(&xxx->event_mutex); rval = CS_SUCCESS; break; case CS_EVENT_CARD_READY: ASSERT(priority & CS_EVENT_PRI_LOW); rval = xx_card_ready(xxx); mutex_exit(&xxx->event_mutex); break; case CS_EVENT_CARD_INSERTION: ASSERT(priority & CS_EVENT_PRI_LOW); mutex_enter(&xxx->event_mutex); rval = xx_card_insertion(xxx); mutex_exit(&xxx->event_mutex); break; case CS_EVENT_CARD_REMOVAL: if (priority & CS_EVENT_PRI_HIGH) { mutex_enter(&xxx->hi_event_mutex); xxx->card_state &= ~XX_CARD_PRESENT; mutex_exit(&xxx->hi_event_mutex); } else { mutex_enter(&xxx->event_mutex); rval = xx_card_removal(xxx); mutex_exit(&xxx->event_mutex); } break; case CS_EVENT_CLIENT_INFO: ASSERT(priority & CS_EVENT_PRI_LOW); if (GET_CLIENT_INFO_SUBSVC_CS(info->Attributes) == CS_CLIENT_INFO_SUBSVC_CS) { info->Attributes |= CS_CLIENT_INFO_VALID; info->Revision = 4; info->CSLevel = CS_VERSION; info->RevDate = CS_CLIENT_INFO_MAKE_DATE(4, 7, 17); (void)strncpy(info->ClientName, "WhizBang Ultra Zowie PC card driver", CS_CLIENT_INFO_MAX_NAME_LEN) "ACME PC card drivers, Inc.", CS_CLIENT_INFO_MAX_NAME_LEN); rval = CS_SUCCESS; } else { rval = CS_UNSUPPORTED_EVENT; } break; case CS_EVENT_WRITE_PROTECT: ASSERT(priority & CS_EVENT_PRI_LOW); mutex_enter(&xxx->event_mutex); if (args->info == CS_EVENT_WRITE_PROTECT_WPOFF) { xxx->card_state &= ~XX_WRITE_PROTECTED; } else { xxx->card_state |= XX_WRITE_PROTECTED; } mutex_exit(&xxx->event_mutex); rval = CS_SUCCESS; break; default: rval = CS_UNSUPPORTED_EVENT; break; } return (rval); } .fi .in -2 .SH SEE ALSO .BR csx_Event2Text (9F), .BR csx_RegisterClient (9F), .BR csx_RequestSocketMask (9F) .sp .LP \fIPC Card 95 Standard\fR, PCMCIA/JEIDA