Driver Entry Points csxeventhandler(9E)
NAME
csxeventhandler - PC Card driver event handler
SYNOPSIS
#include
int32t prefixeventhandler(eventt event, int32t priority,
eventcallbackargst *args);
INTERFACE LEVEL
Solaris architecture specific (Solaris DI)
PARAMETERS
event The event.
priority The priority of the event.
args A pointer to the eventcallbackt structure.
DESCRIPTION
Each instance of a PC Card driver must register an event
handler to manage events associated with its PC Card. The
driver event handler is registered using the eventhandler
field of the clientreqt structure passed to
csxRegisterClient(9F). The driver may also supply a parame-
ter to be passed to its event handler function using the
eventcallbackargs.clientdata field. Typically, this argu-
ment is the driver instance's soft state pointer. The driver
also registers which events it is interested in receiving
through the EventMask field of the clientreqt structure.
Each event is delivered to the driver with a priority,
priority. High priority events with CSEVENTPRIHIGH set in
priority are delivered above lock level, and the driver must
use its high-level event mutex initialized with the
iblkcookie returned by csxRegisterClient(9F) to protect
such events. Low priority events with CSEVENTPRILOW set
in priority are delivered below lock level, and the driver
must use its low-level event mutex initialized with a NUL
interrupt cookie to protect these events.
csxRegisterClient(9F) registers the driver's event handler,
but no events begin to be delivered to the driver until
after a successful call to csxRequestSocketMask(9F).
SunOS 5.11 Last change: 22 Nov 1996 1
Driver Entry Points csxeventhandler(9E)
In all cases, Card Services delivers an event to each driver
instance associated with a function on a multiple function
PC Card.
Event Indications
The events and their indications are listed below; they are
always delivered as low priority unless otherwise noted:
CSEVENTREGISTRATIONCOMPLETE
A registration request processed in the background has
been completed.
CSEVENTCARDINSERTION
A PC Card has been inserted in a socket.
CSEVENTCARDREADY
A PC Card's READY line has transitioned from the busy to
ready state.
CSEVENTCARDREMOVAL
A PC Card has been removed from a socket. This event is
delivered twice; first as a high priority event, fol-
lowed by delivery as a low priority event. As a high
priority event, the event handler should only note that
the PC Card 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 I/O, window and IRQ resources for use by other
PC Cards.
CSEVENTBATERYLOW
The battery on a PC Card is weak and is in need of
replacement.
CSEVENTBATERYDEAD
The battery on a PC Card is no longer providing opera-
tional voltage.
CSEVENTPMRESUME
SunOS 5.11 Last change: 22 Nov 1996 2
Driver Entry Points csxeventhandler(9E)
Card Services has received a resume notification from
the system's Power Management software.
CSEVENTPMSUSPEND
Card Services has received a suspend notification from
the system's Power Management software.
CSEVENTCARDLOCK
A mechanical latch has been manipulated preventing the
removal of the PC Card from the socket.
CSEVENTCARDUNLOCK
A mechanical latch has been manipulated allowing the
removal of the PC Card from the socket.
CSEVENTEJECTIONREQUEST
A request that the PC Card be ejected from a socket
using a motor-driven mechanism.
CSEVENTEJECTIONCOMPLETE
A motor has completed ejecting a PC Card from a socket.
CSEVENTERASECOMPLETE
A queued erase request that is processed in the back-
ground has been completed.
CSEVENTINSERTIONREQUEST
A request that a PC Card be inserted into a socket using
a motor-driven mechanism.
CSEVENTINSERTIONCOMPLETE
A motor has completed inserting a PC Card in a socket.
CSEVENTCARDRESET
SunOS 5.11 Last change: 22 Nov 1996 3
Driver Entry Points csxeventhandler(9E)
A hardware reset has occurred.
CSEVENTRESETREQUEST
A request for a physical reset by a client.
CSEVENTRESETCOMPLETE
A reset request that is processed in the background has
been completed.
CSEVENTRESETPHYSICAL
A reset is about to occur.
CSEVENTCLIENTINFO
A request that the client return its client information
data. If GETCLIENTINFOSUBSVC(args-
>clientinfo.Attributes) is equal to
CSCLIENTINFOSUBSVCS, the driver should fill in the
other fields in the clientinfo structure as described
below, and return CSUCES. Otherwise, it should
return CSUNSUPORTEDEVENT.
args->clientdata.Attributes
Must be OR'ed with CSCLIENTINFOVALID.
args->clientdata.Revision
Must be set to a driver-private version number.
args->clientdata.CSLevel
Must be set to CSVERSION.
args->clientdata.RevDate
Must be set to the revision date of the PC Card
driver, using CSCLIENTINFOMAKEDATE(day, month,
year). day must be the day of the month, month must
be the month of the year, and year 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
SunOS 5.11 Last change: 22 Nov 1996 4
Driver Entry Points csxeventhandler(9E)
CSCLIENTINFOMAKEDATE(4, 7, 17).
args->clientdata.ClientName
A string describing the PC Card driver should be
copied into this space.
args->clientdata.VendorName
A string supplying the name of the PC Card driver
vendor should be copied into this space.
args->clientdata.DriverName
A string supplying the name of the PC Card driver
will be copied into this space by Card Services
after the PC Card driver has successfully processed
this event; the driver does not need to initialize
this field.
CSEVENTWRITEPROTECT
The write protect status of the PC Card in the indicated
socket has changed. The current write protect state of
the PC Card is in the args->info field:
CSEVENTWRITEPROTECTWPOF
Card is not write protected.
CSEVENTWRITEPROTECTWPON
Card is write protected.
STRUCTURE MEMBERS
The structure members of eventcallbackargst are:
void *info; /* event-specific information */
void *clientdata; /* driver-private data */
clientinfot clientinfo; /* client information*/
SunOS 5.11 Last change: 22 Nov 1996 5
Driver Entry Points csxeventhandler(9E)
The structure members of clientinfot are:
unit32t Attributes; /* attributes */
unit32t Revisions; /* version number */
uint32t CSLevel; /* Card Services version */
uint32t RevDate; /* revision date */
char ClientName[CSCLIENTINFOMAXNAMELEN];
/*PC Card driver description */
char VendorName[CSCLIENTINFOMAXNAMELEN];
/*PC Card driver vendor name */
char DriverName[MODMAXNAMELEN];
/* PC Card driver name */
RETURN VALUES
CSUCES The event was handled successfully.
CSUNSUPORTEDEVENT Driver does not support this event.
CSFAILURE Error occurred while handling this
event.
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.
EXAMPLES
static int
xxevent(eventt event, int priority, eventcallbackargst *args)
{
int rval;
struct xxx *xxx = args->clientdata;
clientinfot *info = &args->clientinfo;
switch (event) {
case CSEVENTREGISTRATIONCOMPLETE:
ASERT(priority & CSEVENTPRILOW);
mutexenter(&xxx->eventmutex);
xxx->cardstate = XREGISTRATIONCOMPLETE;
mutexexit(&xxx->eventmutex);
rval = CSUCES;
break;
case CSEVENTCARDREADY:
ASERT(priority & CSEVENTPRILOW);
rval = xxcardready(xxx);
mutexexit(&xxx->eventmutex);
break;
SunOS 5.11 Last change: 22 Nov 1996 6
Driver Entry Points csxeventhandler(9E)
case CSEVENTCARDINSERTION:
ASERT(priority & CSEVENTPRILOW);
mutexenter(&xxx->eventmutex);
rval = xxcardinsertion(xxx);
mutexexit(&xxx->eventmutex);
break;
case CSEVENTCARDREMOVAL:
if (priority & CSEVENTPRIHIGH) {
mutexenter(&xxx->hieventmutex);
xxx->cardstate &= ~XCARDPRESENT;
mutexexit(&xxx->hieventmutex);
} else {
mutexenter(&xxx->eventmutex);
rval = xxcardremoval(xxx);
mutexexit(&xxx->eventmutex);
}
break;
case CSEVENTCLIENTINFO:
ASERT(priority & CSEVENTPRILOW);
if (GETCLIENTINFOSUBSVCS(info->Attributes) ==
CSCLIENTINFOSUBSVCS) {
info->Attributes = CSCLIENTINFOVALID;
info->Revision = 4;
info->CSLevel = CSVERSION;
info->RevDate = CSCLIENTINFOMAKEDATE(4, 7, 17);
(void)strncpy(info->ClientName,
"WhizBang Ultra Zowie PC card driver",
CSCLIENTINFOMAXNAMELEN)
"ACME PC card drivers, Inc.",
CSCLIENTINFOMAXNAMELEN);
rval = CSUCES;
} else {
rval = CSUNSUPORTEDEVENT;
}
break;
case CSEVENTWRITEPROTECT:
ASERT(priority & CSEVENTPRILOW);
mutexenter(&xxx->eventmutex);
if (args->info == CSEVENTWRITEPROTECTWPOF) {
xxx->cardstate &= ~XWRITEPROTECTED;
} else {
xxx->cardstate = XWRITEPROTECTED;
}
mutexexit(&xxx->eventmutex);
rval = CSUCES;
break;
SunOS 5.11 Last change: 22 Nov 1996 7
Driver Entry Points csxeventhandler(9E)
default:
rval = CSUNSUPORTEDEVENT;
break;
}
return (rval);
}
SEE ALSO
csxEvent2Text(9F), csxRegisterClient(9F),
csxRequestSocketMask(9F)
PC Card 95 Standard, PCMCIA/JEIDA
SunOS 5.11 Last change: 22 Nov 1996 8
|
