| Current File : //usr/man/man9e/csx_event_handler.9e |
'\" te
.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
.TH csx_event_handler 9E "22 Nov 1996" "SunOS 5.11" "Driver Entry Points"
.SH NAME
csx_event_handler \- PC Card driver event handler
.SH SYNOPSIS
.LP
.nf
#include <sys/pccard.h>
\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
.sp
.LP
Solaris architecture specific (Solaris \fBDDI) \fR
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIevent\fR\fR
.ad
.RS 12n
.rt
The event.
.RE
.sp
.ne 2
.mk
.na
\fB\fIpriority\fR\fR
.ad
.RS 12n
.rt
The priority of the event.
.RE
.sp
.ne 2
.mk
.na
\fB\fIargs\fR\fR
.ad
.RS 12n
.rt
A pointer to the \fBevent_callback_t\fR structure.
.RE
.SH DESCRIPTION
.sp
.LP
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"
.sp
.LP
The events and their indications are listed below; they are always delivered as low priority unless otherwise noted:
.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fBCS_EVENT_CARD_RESET\fR\fR
.ad
.sp .6
.RS 4n
A hardware reset has occurred.
.RE
.sp
.ne 2
.mk
.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
.mk
.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
.mk
.na
\fB\fBCS_EVENT_RESET_PHYSICAL\fR\fR
.ad
.sp .6
.RS 4n
A reset is about to occur.
.RE
.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fBargs->client_data.CSLevel\fR\fR
.ad
.sp .6
.RS 4n
Must be set to \fBCS_VERSION\fR.
.RE
.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fBCS_EVENT_WRITE_PROTECT_WPOFF\fR\fR
.ad
.sp .6
.RS 4n
Card is not write protected.
.RE
.sp
.ne 2
.mk
.na
\fB\fBCS_EVENT_WRITE_PROTECT_WPON\fR\fR
.ad
.sp .6
.RS 4n
Card is write protected.
.RE
.RE
.SH STRUCTURE MEMBERS
.sp
.LP
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
.sp
.ne 2
.mk
.na
\fB\fBCS_SUCCESS\fR\fR
.ad
.RS 24n
.rt
The event was handled successfully.
.RE
.sp
.ne 2
.mk
.na
\fB\fBCS_UNSUPPORTED_EVENT\fR\fR
.ad
.RS 24n
.rt
Driver does not support this event.
.RE
.sp
.ne 2
.mk
.na
\fB\fBCS_FAILURE\fR\fR
.ad
.RS 24n
.rt
Error occurred while handling this event.
.RE
.SH CONTEXT
.sp
.LP
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
.sp
.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
.sp
.LP
\fBcsx_Event2Text\fR(9F), \fBcsx_RegisterClient\fR(9F), \fBcsx_RequestSocketMask\fR(9F)
.sp
.LP
\fIPC Card 95 Standard\fR, PCMCIA/JEIDA