Card Information Structure (CIS)

 

This chapter describes the Card Information Structure (CIS) and lists the Card Services tuple parsing functions.

Card Information Structure Overview

The Card Information Structure (CIS) is a data structure accessed through Card Services that contains identification and configuration information about PC Cards. The CIS includes information such as device speed, data size, and system resources required for PC Card operation. A PC Card driver accesses the CIS during initialization to determine the configuration options supported by a PC Card.

The CIS is a singly linked list of variable-length data blocks (called tuples) that describe the function and characteristics of a PC Card. Each tuple has a one-byte code describing the tuple type, and a one-byte link that is the offset to the start of the next tuple in the list. Each tuple can contain subtuples that elaborate on the information provided by the parent tuple.

PC Card drivers use the csx_GetFirstTuple(9F), csx_GetNextTuple(9F), and csx_GetTupleData(9F) functions to determine the exact configuration requirements of a PC Card. Drivers can then verify through Card Services the availability of the resources needed by the PC Card. If Card Services is able to allocate these resources, PC Card drivers secure them one at a time until all resources are obtained. Once all card resources are obtained, the PC Card driver can configure the PC Card.

Self-Identifying PC Cards

The CIS provides the mechanism for making a PC Card self-identifying. A self-identifying card provides information to the framework identifying the driver that needs to be used with a particular device.

Because PC Cards are self-identifying, PC Card drivers do not require a .conf file. However, a driver may provide a .conf file to define driver-specific properties. See Writing Device Drivers for more information on self-identifying devices.

---

Note - Currently, the Open Boot PROM does not recognize PC Cards (or the CIS) and does not use FCode to interpret data for use with self-identifying devices. The Solaris kernel and Card Services, however, are able to use CIS information to establish PC Card resource requirements.

---

PC Card Attribute and Common Memory

PC Cards (whether memory card or I/O card) provide a type of memory on the card called attribute memory, in which CIS card information is stored and where configuration registers (if any) are mapped. This information is later accessed by the PCMCIA framework during configuration and evaluated against platform hardware to determine the most appropriate configuration options for the card.

To simplify card design and accommodate 8-bit host systems, the CIS is only placed into attribute memory space at even-byte addresses. The contents of odd-byte addresses of attribute memory space are not defined. Attribute memory is always 8-bit, and data is only meaningful on even-byte addresses.

PC Cards also provide a type of memory on the card called common memory. Common memory may be used to store configuration information or to map memory arrays for stored data. Common memory is either 8-bit or (by default) 16-bit, and the data is only addressible on even-byte addresses. Note that access to 16-bit common memory should be done on even addresses only.

---

Note - Both PC Memory Cards and PC I/O Cards use attribute and common memory. PC I/O Cards, however, have a third address range reserved exclusively for I/O space. For more information, see the PC Card Standard.

---

Metaformat

The PCMCIA specification refers to the combination of all the tuples used to describe a PC Card as a metaformat. Because of the Metaformat structure, the CIS can be read by any operating system.

There are four different types of Metaformat. Solaris CIS parsing functions account for the differences in information storage when reading the CIS information, and present the CIS information in a defined structure. However, for vendor-specific tuples, a PC Card driver may have to parse the CIS information and handle the organization of the data itself. See the PC Card Standard for information on parsing vendor-specific tuples.

16-Bit PC Card Metaformat in Attribute Memory Space The CIS always begins at location zero of attribute memory space and is stored only in even bytes. Odd-byte data stored in the attribute memory space is not defined.

16-bit PC Card Metaformat in Common Memory Space The CIS information always begin at location zero of attribute memory and can be stored only in even bytes. The common memory CIS can be stored immediately following the attribute memory CIS. The CIS attribute information can be stored in both even and odd bytes in common memory space; however, data can only be accessed on even-byte addresses.

16-bit PC Card Metaformat for Multiple Function Cards The multiple function link tuple, CISTPL_LONGLINK_MFC, must be included in the first or global CIS on a 16-bit PC Card to identify the card as containing multiple functions. This tuple does not apply to and must never be used by a CardBus PC Card. The 16-bit PC Card is also required to contain multiple CIS structures for each set of configuration registers on the card.

CardBus PC Card Metaformat Tuple chains may be located in any of the card space with the exception of I/O space. Tuple chains can be located in the configuration space, memory space, or expansion ROM. Multiple function CardBus PC Cards have an independent configuration space and CIS for each function.

Tuple Parsing

A tuple provides information to the PCMCIA framework and PC Card drivers about configuration options available for a PC Card. This information is presented in a raw format; Solaris Card Services provides tuple parsing functions that allow drivers to interpret the raw tuple information into card configuration options.

Each tuple contains a unique identifier that describes the type of information contained in the tuple, the number of bytes contained in the tuple, and a data area that contains the tuple information. Tuples can be defined in relation to three PC Card layers:

• The basic compatibility layer defines the tuples necessary for PC Cards to be compatible on all host systems.
• The data recording format layer defines the tuple format of PC Memory Cards. Memory cards may be either block addressable or byte addressable.
• The data organization layer defines the organization of a particular partition on a PC Memory Card. For example, a tuple could specify whether the partition contains a file system, application-specific information, or executable code images.

Solaris Card Services CIS Parser

The Solaris Card Services framework provides a set of CIS structure tuple parsers that parse tuples into structures defined in the Solaris PCMCIA header files. The CIS parser performs the following functions:

• Creates a tuple list in memory to handle PC Cards on which the CIS is nonaccessible once the card is configured
• Prevents duplication of tuple parsing code
• Provides tuple parsing functions for most tuples described in the PC Card 95 Standard Metaformat specification

A client device driver need not include any tuple parsing code unless information from a nonstandard tuple is required. For nonstandard tuples, the device driver is required to handle tuple parsing itself using Card Services functions that return the raw contents of a tuple.

The Solaris PCMCIA framework depends on accurate, complete CIS information to bind drivers to PC Cards. At a minimum, the CIS must follow the PCMCIA 2.1 CIS/Metaformat specification for single-function cards and must follow the PC Card 95 Standard for multifunction cards.

The PC Card Standard requires that I/O cards have at least one configuration tuple to specify where the configuration registers are. PC Cards with no CIS (or with a CIS but no configuration tuple) are treated by default as memory cards.

---

Note - The Solaris 2.6 PCMCIA framework only supports multifunction cards that conform to the PC Card 95 Standard specification.

---

Tuple Parsing Functions

A PC Card driver can use the tuple parsing functions listed in to parse CIS tuple entries into a usable form.

Table 4-1

Tuple Parsing Function	Description
csx_Parse_CISTPL_DEVICE(9F)	Device information
csx_Parse_CISTPL_CHECKSUM(9F)	Checksum control
csx_Parse_CISTPL_LONGLINK_A(9F)	Long-link to attribute memory
csx_Parse_CISTPL_LONGLINK_C(9F)	Long-link to common memory
csx_Parse_CISTPL_LONGLINK_MFC(9F)	Multifunction
csx_Parse_CISTPL_LINKTARGET(9F)	Link target control
csx_Parse_CISTPL_NO_LINK(9F)	No link control
csx_Parse_CISTPL_VERS_1(9F)	Level 1 version information
csx_Parse_CISTPL_ALTSTR(9F)	Alternate language string
csx_Parse_CISTPL_DEVICE_A(9F)	Attribute memory device information
csx_Parse_CISTPL_JEDEC_C(9F)	JEDEC programming information for common memory
csx_Parse_CISTPL_JEDEC_A(9F)	JEDEC programming information for attribute memory
csx_Parse_CISTPL_CONFIG(9F)	Configuration

Table 4-1 (Continued)

Tuple Parsing Function	Description
csx_Parse_CISTPL_CFTABLE_ENTRY(9F csx_Parse_CISTPL_DEVICE_OC(9F)	Configuration table entry Device information under a set of operating conditions for common memory
csx_Parse_CISTPL_DEVICE_OA(9F)	Device information under a set of operating conditions for attribute memory
csx_Parse_CISTPL_MANFID(9F)	Manufacturer identification
csx_Parse_CISTPL_FUNCID(9F)	Function identification
csx_Parse_CISTPL_FUNCE(9F)	Function extension
csx_Parse_CISTPL_SWIL(9F)	Software interleave
csx_Parse_CISTPL_VERS_2(9F)	Level 2 version information
csx_Parse_CISTPL_FORMAT(9F)	Format type
csx_Parse_CISTPL_GEOMETRY(9F)	Geometry
csx_Parse_CISTPL_BYTEORDER(9F)	Byte order
csx_Parse_CISTPL_DATE(9F)	Card initialization date
csx_Parse_CISTPL_BATTERY(9F)	Battery replacement date
csx_Parse_CISTPL_ORG(9F)	Organization
csx_Parse_CISTPL_SPCL(9F)	Special purpose
csx_ParseTuple(9F)	Generic tuple parser entry point

No tuple parsing routines are provided for the following tuples:

• CISTPL_NULL
• Any vendor-specific tuples (tuple codes in the range of 0x80 to 0x8f)
• CISTPL_END

Example Driver Alias Construction

The following sections provide examples of how raw tuple data is parsed into meaningful configuration information so that the system can bind a particular PC Card device driver to a particular PC Card, PC Card function, or to a class of PC Cards. The driver-device bindings are typically added to the /etc/driver_aliases file by the add_drv(1M) command when the driver is first installed in the system, and they are referred to as driver aliases.

Using the CISTPL_FUNCID Tuple (Generic Names) In this example, any PC Card that has a CISTPL_FUNCID tuple of type serial will cause the pcser driver to be bound to that card.

Using the CISTPL_MANFID Tuple In this example, any PC Card that has a CISTPL_MANFID tuple that contains TPLMID_MANF = 123 and TPLMID_CARD = 456 will cause the pcser driver to be bound to that card. The TPLMID_MANF and TPLMID_CARD values are specified in hexadecimal. Note that there is no comma between pccard and the value for TPLMID_MANF.

Using the CISTPL_VERS_1 Tuple In this example, any PC Card that has a CISTPL_VERS_1 tuple that contains the string(s) Intel_MODEM_2400+_iNC110US will cause the pcser driver to be bound to that card. Spaces in the PC Card's CISTPL_VERS_1 string must be replaced by underscores "_".

Matching is done using the string specified in the alias. The shorter of the alias string and the CISTPL_VERS_1 strings determines how many characters in the strings are matched against.

For example, the following alias:

    pcser "pccard,Intel_MODEM_2400+"

would match PC Cards that contain the string "Intel_MODEM_2400+" in their CISTPL_VERS_1 tuple.

The following alias:

    pcser "pccard,Intel_MODEM"

would match PC Cards that contain the string "Intel_MODEM" in their CISTPL_VERS_1 tuple, which would include PC Cards that contain one of the following strings in their CISTPL_VERS_1 tuple:

"Intel_MODEM"
"Intel_MODEM_2400+"
"Intel_MODEM_2400+_iNC110US"

All strings in the CISTPL_VERS_1 are concatentated into one string for matching purposes. All trailing spaces in the string are removed before matching.

Using the CISTPL_MANFID Tuple for Multifunction Cards In this example, any PC Card function that has a CISTPL_MANFID tuple that contains TPLMID_MANF = 123 and TPLMID_CARD = 456 and is function number 1 will cause the pcser driver to be bound to that function on that card. The TPLMID_MANF, TPLMID_CARD, and function number values are specified in decimal. Note that there is no comma between pccard and the value for TPLMID_MANF.

This form of alias is only usable for multifunction PC Cards that comply with the PC Card 95 Multifunction CIS specification. Older PC Cards that use vendor-specific multifunction CIS layouts will appear to the Solaris system as a single-function card and will very likely require a custom device driver.

Driver Alias Matching

The general rule for determining which one of several driver aliases will match a particular PC Card and PC Card function is that the more specific alias will always take precedence over the less-specific alias. The order of matching, from most specific to least specific, is:

For example, given the following driver aliases:

pcxxx "pccard,serial"
pcyyy "pccard,Intel_MODEM_2400+_iNC110US"
pczzz "pccard123,456"

if a PC Card with the following tuples is inserted:

    CISTPL_FUNCID = "serial"
    CISTPL_VERS_1 = "Acme Serial Card"
    CISTPL_MANFID = "654,321"

the pcxxx driver would be bound to that card, since neither the CISTPL_VERS_1 nor the CISTPL_MANFID tuples match any of the aliases.

If a PC Card with the following tuples is inserted:

CISTPL_FUNCID = "serial"
CISTPL_MANFID = "654,321"
CISTPL_VERS_1 = "Intel_MODEM_2400+"

the pcyyy driver would be bound to that card, since the CISTPL_VERS_1 tuple (partially) matches that driver alias. The CISTPL_FUNCID tuple also matches the pccard,serial alias; however, the CISTPL_VERS_1 match is more specific than the CISTPL_FUNCID match.

If a PC Card with the following tuples is inserted:

    CISTPL_FUNCID = "serial"
    CISTPL_MANFID = "123,456"
    CISTPL_VERS_1 = "Intel_MODEM_2400+"

the pczzz driver would be bound to that card, since the CISTPL_MANFID matches the 123,456 alias. Although the CISTPL_VERS_1 tuple matches the string in the pccard,Intel_MODEM_2400+_iNC110US alias, the CISTPL_MANFID match is performed before the CISTPL_VERS_1 match.

If a PC Card has no CIS or a malformed CIS, the driver that matches the pccard,memory alias will get bound to that card. This is to handle the case of older PCMCIA memory cards that do not have a CIS. Use of PC Cards without a proper CIS is discouraged.

General Rules for PC Card-Driver Bindings

PC Card devices use a generic name whenever it can be determined. Generic names describe the function of a device without identifying the specified driver for the device. Devices with a Function ID tuple will always be in generic form with the following recognized names:

• memory
• network

  · ethernet (if the sys extension tuple funce is present)

  · token-ring (if the sys extension tuple funce is present)

  · localtalk

  · fddi

  · atm

  · wireless

  · reserved

• disk (ata)
• parallel
• video
• aims
• scsi
• serial
• security

Devices with generic device names must support a compatible property. The compatible property contains a list of one or more possible driver names for the device; it is initialized with a set of aliases derived from the Card Information Structure. PC Card driver-to-device binding is done by the Solaris framework from aliases listed in the compatible property. The naming rules are:

• If no CIS is present, then compatible is pccard,memory or memory.
• If Version 1 strings are present, an alias is constructed of the form: pccard,. is the Version 1 tuple string with all spaces replaced with '_' and using ',' as the separator between strings. The resulting alias is appended to the compatible property.
• If a Manufacturer tuple is present, pccardVVVV,DDDD, where VVVV is the Vendor ID in hexadecimal (lowercase, no leading 0s) and DDDD is the device information in hexadecimal (lowercase, no leading 0s), is appended to the compatible property.
• If the PC Card is a multifunction card, another form of the Manufacturer tuple alias is constructed for each function. The format for each alias is pccardVVVV,DDDD.F where F is the function number. These aliases (if present) appear in the compatible property list before the Manufacturer tuple alias.

• If a Function ID tuple is present, the function ID tuple specifies the generic name. The generic name is used to construct two aliases: the first is pccard, and the second is .
• If no generic name is found, then the device node is named according to the pccardVVVV,DDDD format if possible; otherwise, the name pccard is used.

For cards such as modem/serial cards, ATA cards, and memory cards, the naming string follows the definitions listed in .

Table 4-2

Card Type	Generic Device Name
Memory nexus	memory
SRAM memory	pcram
Modem/Serial	serial
3COM EtherLinkIII	network
ATA card	disk

---

Note - For more information on generic device names, refer to the Writing Device Drivers manual.

---

Tuple Utility Functions

The tuple utility functions listed in enable CIS tuple entries to be converted from a Card Services internal representation into common units usable by PC Card drivers.

Table 4-3

Tuple Utility Function	Description
csx_ConvertSize(9F)	Converts device size units from Card Services internal representation to bytes and vice versa.
csx_ConvertSpeed(9F)	Converts device speed units from Card Services internal representation to nanoseconds and vice versa.

demonstrates the use of csx_ConvertSpeed(9F).

Code Example 4-1 Use of csx_ConvertSpeed(9F)

pcsram_state_t *rs;
int                ret;
win_req_t          win_req;
convert_speed_t convert_speed;

/ * Get a memory window for Common Memory space */
win_req.Attributes = (WIN_MEMORY_TYPE_CM |
                          WIN_DATA_WIDTH_16 |
                          WIN_ENABLE |
                          WIN_ACC_NEVER_SWAP |
                          WIN_ACC_STRICT_ORDER);

win_req.Base.base = 0; /*let CardService find us a base addr */
win_req.Size = 0;         /* let CardService return the smallest */
                          /* size window it finds */

/* Use csx_ConvertSpeed(9F) function to generate the */
/* appropriate AccessSpeed code unit. */

convert_speed.Attributes = CONVERT_NS_TO_DEVSPEED;
convert_speed.nS = 250;

csx_ConvertSpeed(&convert_speed);
win_req.win_params.AccessSpeed = convert_speed.devspeed;
if ((ret = csx_RequestWindow(rs->client_handle,
                 &rs->window_handle, &win_req)) != CS_SUCCESS) {
        error2text_tcft;
        cft.item = ret;
        csx_Error2Text(&cft);
        cmn_err(CE_CONT, "pcsram: RequestWindow failed %s
                      (0x%x)\n", cft.text, ret);
        return (ret);
};