Solaris Card Services Interface Overview

Solaris Card Services is an architecture-neutral implementation of the PC Card Services Standard. As illustrated in Figure 3-1, Solaris Card Services defines the software interface between PC Card device drivers and the bus nexus adapter drivers that manage the PC Card hardware. The Card Services interface is independent of the hardware that manipulates PC Cards. As a result, Card Services enables a PC Card driver to control the adapter without knowledge of the specific adapter hardware.

The Solaris PCMCIA framework maps the Card Services interface into hardware-specific functions through bus nexus adapter drivers. In the Solaris system, a PCMCIA nexus is the child of the system bus nexus, and a PCMCIA nexus driver is the parent of all PC Card drivers for cards in that adapter's sockets. Unlike other device drivers in the Solaris architecture, a PC Card driver does not interact directly with its parent nexus. Instead, as specified by the PC Card Standard, the PC Card driver calls into the Card Services layer, and the Card Services layer calls into the nexus adapter driver.

Figure 3-1

PC Card drivers use the Card Services interfaces to determine hardware configuration and manage allocation of system resources. In addition, drivers use Card Services interfaces to handle PC Card insertion and removal. PC Card drivers are clients of Card Services; other Card Services clients include application programs and utility programs.

The Solaris implementation of Card Services is a collection of function entry points in the kernel. These functions are located in a kernel module that is not part of the device driver hierarchy. The module handles all Card Services requests from all PC Card device drivers and makes the calls into the appropriate parent nexus.

There can be only one Card Services implementation per host system. This is in contrast to PCMCIA bus nexus adapter drivers, where there can be multiple bus nexus drivers to accommodate multiple adapters.

Card Services Functionality

Card Services provides the following operating system services to PC Card drivers:

• Driver registration
• PC Card identification and configuration
• Event notification
• Resource allocation

The following sections provide overview information on these services.

Driver Registration

To inform Card Services of its presence, a driver must register with Card Services by calling csx_RegisterClient(9F). Driver registration is typically done in the driver's attach(9E) entry point. In the registration call, the driver specifies whether it is a memory or I/O client, and it also notifies Card Services of its interest in certain events.

The Card Services functions require the driver to pass in a client handle that uniquely identifies the requesting driver instance. The handle is returned by csx_RegisterClient(9F) as an opaque value to Card Services.

For more information on driver autoconfiguration routines, see Chapter 5, "PC Card Driver Autoconfiguration."

PC Card Identification and Configuration

The PC Card Standard specifies a structure called the Card Information Structure (CIS), which stores PC Card identification and configuration information. This structure enables the system software to configure the card without reference to any external card information, thereby making a PC Card self-identifying. Most PC Cards provide a CIS structure.

The CIS structure provides a variety of information about PC Card attributes, such as device size. Card Services configuration software uses the CIS structure to determine the configuration requirements of the PC Card.

See Chapter 4, "Card Information Structure (CIS)," for more information on the CIS structure. See Chapter 7, "PC Card Configuration," for information on PC Card configuration.

Event Notification

PCMCIA events inform the PC Card driver of changes to the state of the PC Card or changes in the system. Card Services provides a way to abstract the physical event, such as card insertion or removal, into a software callback mechanism in order to inform client software (through PC Card drivers) that an event has taken place. A PC Card driver may receive callbacks for any set of predefined events and may receive notification that an event has occurred at any time.

Card Services notifies clients of hardware and software events through an event handler. Information about events is passed back to the client event handler based on the type of event that occurred.

The event handler is registered with Card Services. At registration time, the PC Card driver supplies an address for the event handler and a description of the events it wants to be notified of. When events occur, the driver event handler processes known events, ignores unknown events, and returns a status result code to Card Services. For more information on how the driver handles PCMCIA events, see Chapter 6, "PC Card Event Management."

Resource Allocation

A PC Card driver interacts with Card Services to determine a PC Card's characteristics and to configure and activate the card based on the card's resource requirements. Card Services coordinates the mapping of PC Card resources to system resources.

System Resources

PC Cards may require the use of three types of system resources: I/O address space, interrupt requests (IRQs), and memory address space. A client acquires resources through requests to Card Services. If the resource is available and the socket hardware is capable of using it, Card Services allocates the resources.

Card Services maintains a table of system resources available to PC Cards and sockets. Resources are allocated to PC Cards through the csx_RequestIO(9F), csx_RequestIRQ(9F), and csx_RequestWindow(9F) functions. These functions are discussed in Chapter 7, "PC Card Configuration."

For most efficient system resource utilization, PC Card drivers must deallocate resources obtained during card insertion and reacquire the resources when the card is reinserted.

PC Card Resources

PC Cards have three distinct address spaces on the card: attribute memory space, common memory space, and I/O space. Each address space is 64 Mbytes in length, although usually only a fraction of the available address space is used by a PC Card.

Attribute memory is typically used to store CIS configuration information and configuration registers. This configuration information is used by the PCMCIA framework during card configuration. Common memory typically contains shared memory registers and may contain CIS information. A PC Card driver maps its memory space into allocated system memory and then specifies the area of the PC Card that appears in the allocated memory. PC Card I/O space contains registers and may contain shared memory.

To determine what resources a particular card provides in each of its address spaces, a device driver writer should consult the specifications for the card.

Solaris Modifications to the Card Services Interface

The PC Card Standard is oriented to the MS-DOS operating system and the x86 processor architecture. The standard specifies that Card Services has a single-function entry point through which all Card Services requests are vectored. This single entry point is specified to require the same number of arguments no matter which Card Services function is being requested. The arguments specified in the standard are of fixed type, and different arguments for different Card Services calls must be packed as untyped bytes into a variable-length byte array.

In the current PC Card Standard, each processor type, processor mode (protected, real, and so on), subroutine call method (near, far), and operating system on which Card Services is implemented specifies an implementation-specific binding that dictates the details required to make the call. The model is similar to an MS-DOS INT 21 function call.

This design hinders driver portability for operating systems such as the Solaris system that run on multiple system architectures and multiple processors. As part of Sun's efforts on behalf of the PC Card Standard, a C language calling convention has been developed. This binding implements a Card Services function entry point for each Card Services function with a variable argument list of pointers to function-specific structures and/or opaque data types.

Details such as the sizes of various address and data types, byte ordering for shared structure members, and generic system resources managed by the kernel are kept hidden from the driver developer. Selective data hiding allows a device driver to be source compatible between the Solaris system on the SPARC architecture and the Solaris system on the x86 architecture.

Certain differences between the SPARC and x86 architectures, such as card I/O port accesses, are handled through Card Services common access functions. Some adapters for SPARC machines map virtual registers into the device driver virtual memory address space, while other adapters on an x86 machine, for example, may use privileged I/O instructions.

Solaris Card Services differs from the PC Card Standard in that the Solaris Card Services functions are strongly typed with explicit parameters. For example, the following call is similar to the PC Card Standard Card Services specification, but eliminates null arguments and variable-length argument lists.

int32_t csx_RegisterClient(client_handle_t *, client_reg_t *)

Solaris Card Services Interfaces

Solaris Card Services provides interface functions that allow PC Card drivers to communicate with devices. These interfaces fall into the following functional groups:

• PC Card registration and information interfaces
• PC Card configuration interfaces
• System resource interfaces

PC Card Registration and Information Interfaces

Table 3-1 lists the interfaces available for registering with Card Services and retrieving information from Card Services.

Table 3-1

Functional Category	Function Name	Description
Card Services registration	csx_RegisterClient(9F)	Registers a client
	csx_DeregisterClient(9F)	Removes a client from Card Services list
Card Services information	csx_GetStatus(9F)	Returns the current status of the PC Card
	csx_MapLogSocket(9F)	Returns the physical socket number associated with the client handle

PC Card Configuration Interfaces

Table 3-2 lists the interfaces that a driver can use for PC Card configuration.

Table 3-2

Functional Category	Function Name	Description
PC Card configuration information	csx_RequestConfiguration(9F)	Configures the PC Card and socket
	csx_ModifyConfiguration(9F)	Modifies the socket and PC Card Configuration Register
	csx_ReleaseConfiguration(9F)	Releases the PC Card and socket
	csx_AccessConfigurationRegister (9F)	Reads or writes a PC Card Configuration Register
CIS tuple information	See Chapter 4, "Card Information Structure (CIS)" for the CIS Tuple Function and Utility tables

System Resource Interfaces

Table 3-3 lists the interfaces needed for resource allocation. These interfaces can be categorized as follows:

• I/O resources
• IRQ resources
• Memory resources
• Event resources
• Common access functions

For information on additional interfaces, see "Additional Card Services Functions Provided in the Solaris System" on page 21.

Table 3-3

Functional Category	Function Name	Description
I/O resources	csx_RequestIO(9F)	Requests I/O resources for the client
	csx_ReleaseIO(9F)	Releases I/O resources for the client
IRQ resources	csx_RequestIRQ(9F)	Requests IRQ resource
	csx_ReleaseIRQ(9F)	Releases IRQ resource
Memory resources	csx_RequestWindow(9F)	Requests window resources
	csx_ReleaseWindow(9F)	Releases window resources
	csx_ModifyWindow(9F)	Modifies window attributes
	csx_MapMemPage(9F)	Maps the memory area on a PC Card
Event resources	csx_RequestSocketMask(9F)	Starts event handling
	csx_GetEventMask(9F)	Returns the client event mask
	csx_SetEventMask(9F)	Sets the client event mask
	csx_ReleaseSocketMask(9F)	Clears the client event mask
Common access	csx_Put8(9F)	Writes 1 byte to device register
	csx_Put16(9F)	Writes 2 bytes to device register
	csx_Put32(9F)	Writes 4 bytes to device register
	csx_Put64(9F)	Writes 8 bytes to device register

Table 3-3 (Continued)

Functional Category	Function Name	Description
	csx_Get8(9F) csx_Get16(9F) csx_Get32(9F) csx_Get64(9F)	Reads data from device register
	csx_RepPut8(9F) csx_RepPut16(9F) csx_RepPut32(9F) csx_RepPut64(9F)	Writes repetitively to device register
	csx_RepGet8(9F) csx_RepGet16(9F) csx_RepGet32(9F) csx_RepGet64(9F)	Reads repetitively from device register
	csx_GetMappedAddr(9F)	Returns mapped virtual address
	csx_DupHandle(9F)	Duplicates access handle
	csx_FreeHandle(9F)	Frees access handle

Additional Card Services Functions Provided in the Solaris System

Card Services provides the following utility functions in addition to the functions defined by the PC Card Standard.

csx_ConvertSize(9F)

This utility function converts device size units from devsize format to bytes and vice versa. See "Tuple Utility Functions" in Chapter 4, "Card Information Structure (CIS)" for more information.

csx_ConvertSpeed(9F)

This utility function converts device speed units from devspeed format to nanoseconds and vice versa. See "Tuple Utility Functions" in Chapter 4, "Card Information Structure (CIS)" for more information.

csx_CS_DDI_Info(9F)

This function returns the dev_info_t and instance number associated with a particular PC Card driver and socket number. Some PC Card drivers encode the physical socket number as part of the dev_t of device nodes that they create.

The xx_getinfo(9E) driver entry point is required for drivers that export cb_ops(9S) entry points, and the driver's xx_getinfo(9E) function is required to return either the dev_info_t pointer or the instance number associated with the passed dev_t argument. Card Services maintains a table of dev_info_t pointers and instance numbers that correspond to particular client/socket number combinations; csx_CS_DDI_Info(9F) is the mechanism by which a PC Card driver can retrieve this information.

csx_Event2Text(9F)

This function returns text strings corresponding to an event. It is normally used for printing error messages.

csx_Error2Text(9F)

This function returns text strings corresponding to a Card Services error return code. It is normally used for printing error messages.

csx_MakeDeviceNode(9F)

This function creates minor nodes on behalf of PC Card drivers.

csx_RemoveDeviceNode(9F)

This function removes minor nodes on behalf of PC Card drivers.