Linux PCMCIA Programmer's Guide: Card Information Structure Definitions

4. Card Information Structure Definitions

4.1 CIS Tuple Definitions

The Card Services ParseTuple function interprets raw CIS tuple data from a call to GetTupleData and returns the tuple contents in a form dependant on the tuple type. This section describes the parsed tuple contents.


#include "cistpl.h"

CISTPL_CHECKSUM

The cistpl_checksum_t structure is given by:


typedef struct cistpl_checksum_t {
        u_short         addr;
        u_short         len;
        u_char          sum;
} cistpl_checksum_t;

CISTPL_LONGLINK_A, CISTPL_LONGLINK_C, CISTPL_LINKTARGET,CISTPL_NOLINK

The cistpl_longlink_t structure is given by:


typedef struct cistpl_longlink_t {
        u_int           addr;
} cistpl_longlink_t;

These tuples are pointers to additional chains of CIS tuples, either in attribute or common memory. Each CIS tuple chain can have at most one long link. CISTPL_LONGLINK_A tuples point to attribute memory, and CISTPL_LONGLINK_C tuples point to common memory. The standard CIS chain starting at address 0 in attribute memory has an implied long link to address 0 in common memory. A CISTPL_NOLINK tuple can be used to cancel this default link.

The first tuple of a chain pointed to by a long link must be a CISTPL_LINKTARGET. The CS tuple handling code will automatically follow long links and verify link targets; these tuples are normally invisible unless the TUPLE_RETURN_LINK attribute is specified in GetNextTuple.

CISTPL_LONGLINK_MFC

The cistpl_longlink_mfc_t structure is given by:


typedef struct cistpl_longlink_mfc_t {
        int     nfn;
        struct {
                u_char  space;
                u_int   addr;
        } fn[CISTPL_MAX_FUNCTIONS;
} cistpl_longlink_mfc_t;

This tuple identifies a multifunction card, and specifies long link pointers to CIS chains specific for each function. The space field is either CISTPL_MFC_ATTR or CISTPL_MFC_COMMON for attribute or common memory space.

CISTPL_DEVICE, CISTPL_DEVICE_A

The cistpl_device_t structure is given by:


typedef struct cistpl_device_t {
        int             ndev;
        struct {
                u_char          type;
                u_char          wp;
                u_int           speed;
                u_int           size;
        } dev[CISTPL_MAX_DEVICES];
} cistpl_device_t;

The CISTPL_DEVICE tuple describes address regions in a card's common memory. The CISTPL_DEVICE_A tuple describes regions in attribute memory. The type flag indicates the type of memory device for this region. The wp flag indicates if this region is write protected. The speed field is in nanoseconds, and size is in bytes. Address regions are assumed to be ordered consecutively starting with address 0. The following device types are defined:

CISTPL_DTYPE_NULL: Specifies that there is no device, or a ``hole'' in the card address space.
CISTPL_DTYPE_ROM: Masked ROM
CISTPL_DTYPE_OTPROM: One-type programmable ROM.
CISTPL_DTYPE_EPROM: UV erasable PROM.
CISTPL_DTYPE_EEPROM: Electrically erasable PROM.
CISTPL_DTYPE_FLASH: Flash EPROM.
CISTPL_DTYPE_SRAM: Static or non-volatile RAM.
CISTPL_DTYPE_DRAM: Dynamic or volatile RAM.
CISTPL_DTYPE_FUNCSPEC: Specifies a function-specific device, such as a memory-mapped IO device or buffer, as opposed to general purpose storage.
CISTPL_DTYPE_EXTEND: Specifies an extended device type. This type is reserved for future use.

CISTPL_VERS_1

The cistpl_vers_1_t structure is given by:


typedef struct cistpl_vers_1_t {
        u_char          major;
        u_char          minor;
        int             ns;
        int             ofs[CISTPL_VERS_1_MAX_PROD_STRINGS];
        char            str[254];
} cistpl_vers_1_t;

The ns field specifies the number of product information strings in the tuple. The string data is contained in the str array. Each string is null terminated, and ofs gives the offset to the start of each string.

CISTPL_ALTSTR

The cistpl_altstr_t structure is given by:


typedef struct cistpl_altstr_t {
        int             ns;
        int             ofs[CISTPL_ALTSTR_MAX_STRINGS];
        char            str[254];
} cistpl_altstr_t;

The ns field specifies the number of alternate language strings in the tuple. The string data is contained in the str array. Each string is null terminated, and ofs gives the offset to the start of each string.

CISTPL_JEDEC_C, CISTPL_JEDEC_A

The cistpl_jedec_t structure is given by:


typedef struct cistpl_jedec_t {
        int             nid;
        struct {
                u_char  mfr;
                u_char  info;
        } id[CISTPL_MAX_DEVICES];
} cistpl_jedec_t;

JEDEC identifiers describe the specific device type used to implement a region of card memory. The nid field specifies the number of JEDEC identifiers in the tuple. There should be a one-to-one correspondence between JEDEC identifiers and device descriptions in the corresponding CISTPL_DEVICE tuple.

CISTPL_CONFIG, CISTPL_CONFIG_CB

The cistpl_config_t structure is given by:


typedef struct cistpl_config_t {
        u_char          last_idx;
        u_int           base;
        u_int           rmask[4];
        u_char          subtuples;
} cistpl_config_t;

The last_idx field gives the index of the highest numbered configuration table entry. The base field gives the offset of a card's configuration registers in attribute memory. The rmask array is a series of bit masks indicating which configuration registers are present. Bit 0 of rmask[0] is for the COR, bit 1 is for the CCSR, and so on. The subtuples field gives the number of bytes of subtuples following the normal tuple contents.

For CISTPL_CONFIG_CB, rmask is undefined, and base points to the CardBus status registers.

CISTPL_BAR

The cistpl_bar_t structure is given by:


typedef struct cistpl_bar_t {
        u_char          attr;
        u_int           size;
} cistpl_long_t;

A CISTPL_BAR tuple describes the characteristics of an address space region pointed to by a PCI base address register, for CardBus cards.

The following bit fields are defined in attr:

CISTPL_BAR_SPACE: Identifies the base address register, from 1 to 6. A value of 7 describes the card's Extension ROM space.
CISTPL_BAR_SPACE_IO: If set, this address register maps IO space (as opposed to memory space).
CISTPL_BAR_PREFETCH: If set, this region can be prefetched. controller.
CISTPL_BAR_CACHEABLE: If set, this region is cacheable as well as prefetchable.
CISTPL_BAR_1MEG_MAP: If set, this region should only be mapped into the first 1MB of the host's physical address space.

CISTPL_CFTABLE_ENTRY

The cistpl_cftable_entry_t structure is given by:


typedef struct cistpl_cftable_entry_t {
        u_char          index;
        u_char          flags;
        u_char          interface;
        cistpl_power_t  vcc, vpp1, vpp2;
        cistpl_timing_t timing;
        cistpl_io_t     io;
        cistpl_irq_t    irq;
        cistpl_mem_t    mem;
        u_char          subtuples;
} cistpl_cftable_entry_t;

A CISTPL_CFTABLE_ENTRY structure describes a complete operating mode for a card. Many sections are optional. The index field gives the configuration index for this operating mode; writing this value to the card's Configuration Option Register selects this mode. The following fields are defined in flags:

CISTPL_CFTABLE_DEFAULT: Specifies that this is the default configuration table entry.
CISTPL_CFTABLE_BVDS: Specifies that this configuration implements the BVD1 and BVD2 signals in the Pin Replacement Register.
CISTPL_CFTABLE_WP: Specifies that this configuration implements the write protect signal in the Pin Replacement Register.
CISTPL_CFTABLE_RDYBSY: Specifies that this configuration implements the Ready/Busy signal in the Pin Replacement Register.
CISTPL_CFTABLE_MWAIT: Specifies that the WAIT signal should be observed during memory access cycles.
CISTPL_CFTABLE_AUDIO: Specifies that this configuration generates an audio signal that can be routed to the host system speaker.
CISTPL_CFTABLE_READONLY: Specifies that the card has a memory region that is read-only in this configuration.
CISTPL_CFTABLE_PWRDOWN: Specifies that this configuration supports a power down mode, via the Card Configuration and Status Register.

The cistpl_power_t structure is given by:


typedef struct cistpl_power_t {
        u_char          present;
        u_char          flags;
        u_int           param[7];
} cistpl_power_t;

The present field is bit mapped and indicates which parameters are present for this power signal. The following indices are defined:

CISTPL_POWER_VNOM: The nominal supply voltage.
CISTPL_POWER_VMIN: The minimum supply voltage.
CISTPL_POWER_VMAX: The maximum supply voltage.
CISTPL_POWER_ISTATIC: The continuous supply current required.
CISTPL_POWER_IAVG: The maximum current averaged over one second.
CISTPL_POWER_IPEAK: The maximum current averaged over 10 ms.
CISTPL_POWER_IDOWN: The current required in power down mode.

Voltages are given in units of 10 microvolts. Currents are given in units of 100 nanoamperes.

The cistpl_timing_t structure is given by:


typedef cistpl_timing_t {
        u_int           wait, waitscale;
        u_int           ready, rdyscale;
        u_int           reserved, rsvscale;
} cistpl_timing_t;

Each time consists of a base time in nanoseconds, and a scale multiplier. Unspecified times have values of 0.

The cistpl_io_t structure is given by:


typedef struct cistpl_io_t {
        u_char          flags;
        int             nwin;
        struct {
                u_int           base;
                u_int           len;
        } win[CISTPL_IO_MAX_WIN;
} cistpl_io_t;

The number of IO windows is given by nwin. Each window is described by a base address, base, and a length in bytes, len. The following bit fields are defined in flags:

CISTPL_IO_LINES_MASK: The number of IO lines decoded by this card.
CISTPL_IO_8BIT: Indicates that the card supports split 8-bit accesses to 16-bit IO registers.
CISTPL_IO_16BIT: Indicates that the card supports full 16-bit accesses to IO registers.

The cistpl_irq_t structure is given by:


typedef struct cistpl_irq_t {
        u_int           IRQInfo1;
        u_int           IRQInfo2;
} cistpl_irq_t;

The following bit fields are defined in IRQInfo1:

IRQ_MASK: A specific interrupt number that this card should use.
IRQ_NMI_ID, IRQ_IOCK_ID, IRQ_BERR_ID, IRQ_VEND_ID: When IRQ_INFO2_VALID is set, these indicate if a corresponding special interrupt signal may be assigned to this card. The four flags are for the non-maskable, IO check, bus error, and vendor specific interrupts.
IRQ_INFO2_VALID: Indicates that IRQInfo2 contains a valid bit mask of allowed interrupt request numbers.
IRQ_LEVEL_ID: Indicates that the card supports level mode interrupts.
IRQ_PULSE_ID: Indicates that the card supports pulse mode interrupts.
IRQ_SHARE_ID: Indicates that the card supports sharing interrupts.

If IRQInfo1 is 0, then no interrupt information is available.

The cistpl_mem_t structure is given by:


typedef struct cistpl_mem_t {
        u_char          nwin;
        struct {
                u_int           len;
                u_int           card_addr;
                u_int           host_addr;
        } win[CISTPL_MEM_MAX_WIN;
} cistpl_mem_t;

The number of memory windows is given by nwin. Each window is described by an address in the card memory space, card_addr, an address in the host memory space, host_addr, and a length in bytes, len. If the host address is 0, the position of the window is arbitrary.

CISTPL_CFTABLE_ENTRY_CB

The cistpl_cftable_entry_cb_t structure is given by:


typedef struct cistpl_cftable_entry_cb_t {
        u_char          index;
        u_char          flags;
        cistpl_power_t  vcc, vpp1, vpp2;
        u_char          io;
        cistpl_irq_t    irq;
        u_char          mem;
        u_char          subtuples;
} cistpl_cftable_entry_cb_t;

A CISTPL_CFTABLE_ENTRY_CB structure describes a complete operating mode for a CardBus card. Many fields are identical to corresponding fields in CISTPL_CFTABLE_ENTRY.

The io and mem fields specify which base address registers need to be initialized for this configuration. Bits 1 through 6 correspond to the six base address registers, and bit 7 indicates the expansion ROM base register.

CISTPL_MANFID

The cistpl_manfid_t structure is given by:


typedef struct cistpl_manfid_t {
        u_short         manf;
        u_short         card;
} cistpl_manfid_t;

The manf field identifies the card manufacturer. The card field is chosen by the vendor and should identify the card type and model.

CISTPL_FUNCID

The cistpl_funcid_t structure is given by:


typedef struct cistpl_funcid_t {
        u_char          func;
        u_char          sysinit;
} cistpl_funcid_t;

The func field identifies the card function. The sysinit field contains several bit-mapped flags describing how the card should be configured at boot time.

The following functions are defined:

CISTPL_FUNCID_MULTI: A multi-function card.
CISTPL_FUNCID_MEMORY: A simple memory device.
CISTPL_FUNCID_SERIAL: A serial port or modem device.
CISTPL_FUNCID_PARALLEL: A parallel port device.
CISTPL_FUNCID_FIXED: A fixed disk device.
CISTPL_FUNCID_VIDEO: A video interface.
CISTPL_FUNCID_NETWORK: A network adapter.
CISTPL_FUNCID_AIMS: An auto-incrementing mass storage device.

The following flags are defined in sysinit:

CISTPL_SYSINIT_POST: Indicates that the system should attempt to configure this card during its power-on initialization.
CISTPL_SYSINIT_ROM: Indicates that the card contains a system expansion ROM that should be configured at boot time.

CISTPL_DEVICE_GEO

The cistpl_device_geo_t structure is given by:


typedef struct cistpl_device_geo_t {
        int             ngeo;
        struct {
                u_char          buswidth;
                u_int           erase_block;
                u_int           read_block;
                u_int           write_block;
                u_int           partition;
                u_int           interleave;
        } geo[CISTPL_MAX_DEVICES];
} cistpl_device_geo_t;

The erase_block, read_block, and write_block sizes are in units of buswidth bytes times interleave. The partition size is in units of erase_block.

CISTPL_VERS_2

The cistpl_vers_2_t structure is given by:


typedef struct cistpl_vers_2_t {
        u_char          vers;
        u_char          comply;
        u_short         dindex;
        u_char          vspec8, vspec9;
        u_char          nhdr;
        int             vendor, info;
        char            str[244];
} cistpl_vers_2_t;

The vers field should always be 0. The comply field indicates the degree of standard compliance and should also be 0. The dindex field reserves the specified number of bytes at the start of common memory. The vspec8 and vspec9 fields may contain vendor-specific information. The nhdr field gives the number of copies of the CIS that are present on this card. The str array contains two strings: a vendor name, and an informational message describing the card. The offset of the vendor string is given by vendor, and the offset of the product info string is in info.

CISTPL_ORG

The cistpl_org_t structure is given by:


typedef struct cistpl_org_t {
        u_char          data_org;
        char            desc[30];

This tuple describes the data organization of a memory partition. The following values are defined for data_org:

CISTPL_ORG_FS: The partition contains a filesystem.
CISTPL_ORG_APPSPEC: The partition is in an application specific format.
CISTPL_ORG_XIP: The partition follows the Execute-In-Place specification.

The desc field gives a text description of the data organization.

CISTPL_FORMAT

The cistpl_format_t structure is given by:


typedef struct cistpl_org_t {
        u_char          type;
        u_char          edc;
        u_int           offset;
        u_int           length;

This tuple describes the data recording format for a memory region. The following values are defined for type:

CISTPL_FORMAT_DISK: The partition uses a disk-like format.
CISTPL_FORMAT_MEM: The partition uses a memory-like format.

The following values are defined for edc:

CISTPL_EDC_NONE: No error detection code is used.
CISTPL_EDC_CKSUM: Each block has a one-byte arithmetic checksum.
CISTPL_EDC_CRC: Each block has a two-byte cyclic redundancy check.
CISTPL_EDC_PCC: The entire partition has a one-byte checksum.

The offset field specifies the address of the first data byte, and length specifies the total number of data bytes in this partition.

4.2 CIS configuration register definitions

The PC Card standard defines a few standard configuration registers located in a card's attribute memory space. A card's CONFIG tuple specifies which of these registers are implemented. Programs using these definitions should include:


#include "cisreg.h"

Configuration Option Register

This register should be present for virtually all IO cards. Writing to this register selects a configuration table entry and enables a card's IO functions.