Next Previous Contents

5. Card Services Event Handling

Card Services events have several sources:

Socket driver events may be either interrupt-driven or polled.

5.1 Event handler operations

When Card Services recognizes that an event has occurred, it checks the event mask of each client to determine which clients should receive an event notification. When a client registers with Card Services, it specifies an event handler callback function. This handler should have the form:

int (*event_handler)(event_t event, int priority, event_callback_args_t *args);

The priority parameter is set to either CS_EVENT_PRI_LOW for ordinary events, or CS_EVENT_PRI_HIGH for events that require an immediate response. The only high priority event is CS_EVENT_CARD_REMOVAL. A client event handler should process this event as efficiently as possible so that Card Services can quickly notify other clients.

The event_callback_args_t structure is given by:

typedef struct event_callback_args_t {
        client_handle_t         client_handle;
        void                    *info;
        void                    *mtdrequest;
        void                    *buffer;
        void                    *misc;
        void                    *client_data;
        struct bus_operations   *bus;
} event_callback_args_t;

The client_handle member is set to the handle of the client whose socket was responsible for the event. This is useful if a driver is bound to several sockets. The info field is currently only used to return an exit status from a call to ResetCard. The client_data field may be used by a driver to point to a local data structure associated with this device. The remaining fields are currently unused.

For sockets that do not directly map cards into the host IO and memory space, the bus field is a pointer to a table of entry points for IO primitives for this socket.

5.2 Event descriptions


This event signals that a card has been inserted. If a driver is bound to an already occupied socket, Card Services will send the driver an artificial insertion event.


This event signals that a card has been removed. This event should be handled with minimum delay so that Card Services can notify all clients as quickly as possible.


This event signals a change of state of the ``battery low'' signal.


This event signals a change of state of the ``battery dead'' signal.


This event signals a change of state of the ``ready'' signal.


This event signals a change of state of the ``write protect'' signal.


This event is sent to a driver after a successful call to RegisterClient.


This event is sent when a client calls ResetCard. An event handler can veto the reset operation by returning failure.


This is sent to all clients just before a reset signal is sent to a card.


This event signals that a reset operation is finished. The success or failure of the reset should be determined using GetStatus.


This event is sent to a client that has called ResetCard to signal the end of reset processing.


This event signals that Card Services has received either a user initiated or APM suspend request. An event handler can veto the suspend by returning failure.


This signals that the system is back on line after a suspend/resume cycle.


This is used to initiate an MTD memory operation. A description of the request is passed in the mtdrequest field of the callback arguments. A host buffer address may be passed in buffer.


This is used to signal a client that a queued erase operation has completed. A pointer to the erase queue entry is returned in the info field of the callback arguments.

5.3 Client driver event handling responsibilities

A client driver should respond to CS_EVENT_CARD_INSERTION and CS_EVENT_CARD_REMOVAL events by configuring and un-configuring the socket. Because card removal is a high priority event, the driver should immediately block IO to the socket, perhaps by setting a flag in a device structure, and schedule all other shutdown processing to happen later using a timer interrupt.

When a CS_EVENT_PM_RESET_REQUEST event is received, a driver should block IO and release a locked socket configuration. When a CS_EVENT_CARD_RESET is received, a driver should restore the socket configuration and unblock IO.

A CS_EVENT_PM_SUSPEND event should be handled somewhat like a CS_EVENT_PM_RESET_REQUEST event, in that IO should be blocked and the socket configuration should be released. When a CS_EVENT_PM_RESUME event is received, a driver can expect a card to be ready to be reconfigured, similar to when a CS_EVENT_CARD_RESET event is received.

Next Previous Contents