8 Anatomy of a Card Services Client Driver

All loadable modules must supply init_module() and cleanup_module() functions, which are invoked by the module support code when the module is installed and removed. A PCMCIA client driver's init function should register the driver with Driver Services, via the register_pcmcia_driver() call. The cleanup function should use unregister_pcmcia_driver() to unregister with Driver Services. Depending on the driver, the cleanup function may also need to free any device structures that still exist at shutdown time.

The *_attach() entry point is responsible for creating an ``instance'' of the driver, setting up any data structures needed to manage one PCMCIA card. The *_attach() function should allocate and initialize a dev_link_t structure, and call RegisterClient to establish a link with Card Services. It returns a pointer to the new dev_link_t structure, or NULL if the new instance could not be created.

The *_detach() entry point deletes a driver instance created by a previous call to *_attach. It also breaks the link with Card Services, using DeregisterClient.

The *_attach() entry point is called by Driver Services when a card has been successfully identified and mapped to a matching driver by a DS_BIND_REQUEST ioctl(). The *_detach() entry point is called in response to a DS_UNBIND_REQUEST ioctl() call.

The *_config() function is called to prepare a card for IO. Most drivers read some configuration details from the card itsef, but most have at least some built-in knowledge of how the device should be set up. For example, the serial card driver reads a card's CFTABLE_ENTRY tuples to determine appropriate IO port base addresses and corresponding configuration indices, but the driver ignores the interrupt information in the CIS. The *_config function will parse relevant parts of a card's CIS, then make calls to RequestIO, RequestIRQ, and/or RequestWindow, then call RequestConfiguration.

When a card is successfully configured, the *_config() routine should fill in the dev_name, major, and minor fields in the dev_link_t structure. These fields will be returned to user programs by Driver Services in response to a DS_GET_DEVICE_INFO ioctl().

The *_release() function should release any resource allocated by a previous call to *_config(), and blank out the device's dev_name field.

The *_config() and *_release functions are normally called in response to card status change events or from timer interrupts. Thus, they cannot sleep, and should not call other kernel functions that might block.

The *_event() entry point is called from Card Services to notify a driver of card status change events.

A configured socket should only be released when all associated devices are closed. Releasing a socket allows its system resources to be allocated for use by another device. If the released resources are reallocated while IO to the original device is still in progress, the original driver may interfere with use of the new device.

A driver instance should only be freed after its corresponding socket configuration has been released. Card Services requires that a client explicitly release any allocated resources before a call to DeregisterClient will succeed.

All loadable modules have a ``use count'' that is used by the system to determine when it is safe to unload a module. The convention in the PCMCIA client drivers is to increment the use count when a device is opened, and to decrement the count when a device is closed. So, a driver can be unloaded whenever all associated devices are closed. in particular, a driver can be unloaded even if it is still bound to a socket, and the module cleanup code needs to be able to appropriately free any such resources that are still allocated. This should always be safe, because if the driver has a use count of zero, all devices are closed, which means all active sockets can be released, and all device instances can be detached.

If a driver's *_release() function is called while a device is still open, it should set the DEV_STALE_CONFIG flag in the device state, to signal that the device should be released when the driver's close() function is called. If *_detach() is called for a configured device, the DEV_STALE_LINK flag should be set to signal that the instance should be detached when the *_release() function is called.

Many of the current PCMCIA client drivers use existing Linux driver code to perform device IO operations. The Card Services client module handles card configuration and responds to card status change events, but delegates device IO to a compatible driver for a conventional ISA bus card. In some cases, a conventional driver can be used without modification. However, to fully support PCMCIA features like hot swapping and power management, there needs to be some communication between the PCMCIA client code and the device IO code.

Most Linux drivers expect to probe for devices at boot time, and are not designed to handle adding and removing devices. One side-effect of the move towards driver modularization is that it is usually easier to adapt a modularized driver to handle removable devices.

It is important that a device driver be able to recover from having a device disappear at an inappropriate time. At best, the driver should check for device presence before attempting any IO operation or before handling an IO interrupt. Loops that check device status should have timeouts so they will eventually exit if a device never responds.