5. Card Services Event Handling

Card Services events have several sources:

• Card status changes reported by the low-level socket drivers.
• Artificial events generated by Card Services itself.
• Advanced Power Management (APM) events.
• Events generated by other Card Services clients.

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

CS_EVENT_CARD_INSERTION

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.

CS_EVENT_CARD_REMOVAL

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.

CS_EVENT_BATTERY_LOW

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

CS_EVENT_BATTERY_DEAD

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

CS_EVENT_READY_CHANGE

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

CS_EVENT_WRITE_PROTECT

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

CS_EVENT_REGISTRATION_COMPLETE

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

CS_EVENT_RESET_REQUEST

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

CS_EVENT_RESET_PHYSICAL

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

CS_EVENT_CARD_RESET

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

CS_EVENT_RESET_COMPLETE

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

CS_EVENT_PM_SUSPEND

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.

CS_EVENT_PM_RESUME

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

CS_EVENT_MTD_REQUEST

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.

CS_EVENT_ERASE_COMPLETE

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.