4    Data Structures That PCI Bus Device Drivers Use

Data structures are the mechanism used to pass information between the Digital UNIX kernel and device driver interfaces. PCI bus device driver writers must understand the data structures described in Writing Device Drivers: Tutorial. In addition to the structures described in Writing Device Drivers: Tutorial, device driver writers must understand the following data structures and files related to developing device drivers on the PCI bus:

• The pci_config_hdr data structure

• The PCI_Option entries in the sysconfigtab file fragment

• The /etc/sysconfigtab database file

4.1    The pci_config_hdr Data Structure

The pci_config_hdr data structure contains information that is derived from a PCI device's configuration space header. This information identifies the device, describes its behavior with regard to PCI bus cycles, records status, and locates its address spaces. The PCI bus configuration code creates a pci_config_hdr data structure for each device function connected to a PCI bus. The device driver's xxprobe interface (and, if applicable, its xxslave interface) can read the members of the pci_config_hdr data structure to obtain information about a PCI device.

The first 16 bytes of this header are the same for all types of devices. The remaining bytes have different layouts depending upon the base function supported by the device. The hdr_type member of the pci_config_hdr data structure indicates the header layout of a given device. Currently, two header types exist:

• Type 00h, as represented by the constant HDR_LAYOUT_V2, has the layout shown in Table 4-1.

• Type 01h is used for PCI-to-PCI bridge devices and has the layout shown in Table 5-2.

Table 4-1: Members of the pci_config_hdr Data Structure

Note

Although they are part of the pci_config_hdr structure, the config_base and private members are defined as part of the type 00h (HDR_LAYOUT_V2) header. They are listed in this table and described in this chapter to facilitate discussion of the pci_config_hdr structure.

The following sections describe the members of the pci_config_hdr structure.

4.1.1    The vendor_id, device_id, and rev_id Members

The PCI bus configuration code matches device drivers to PCI devices by using the Vendor ID, Device ID, Revision ID, Class Code, Subsystem Vendor ID, and Subsystem ID device registers in the device's configuration space header. You can determine which device registers participate in selecting a driver by creating PCI_Option entries in a sysconfigtab file fragment, as discussed in Section 4.2. Section 5.3 describes the mechanism by which the PCI bus configuration code identifies the driver associated with a given device.

This section describes the Vendor ID, Device ID, and Revision ID device registers. Section 4.1.4 describes the Class Code device register. Section 4.1.11 describes the Subsystem Vendor ID and Subsystem ID registers.

The contents of the Vendor ID device register, copied to the vendor_id member of the pci_config_hdr data structure by the PCI bus configuration code, identifies the manufacturer of the device. Manufacturers can request a vendor ID to avoid conflict with other vendors. 0FFFFh is an invalid value for a vendor ID.

The Device ID device register, copied to the device_id member of the pci_config_hdr data structure by the PCI bus configuration code, identifies the specific PCI device. The device's manufacturer determines its device ID.

The Revision ID device register identifies a device-specific revision. The device's manufacturer determines its revision ID.

4.1.2    The command Member

The Command device register, copied to the command member of the pci_config_hdr structure by the PCI bus configuration code, provides general control over a device's ability to generate and respond to PCI bus cycles.

Typically, power-on self-test code initializes the bits in the Command device register. The PCI bus configuration code can set the Command device register, as represented in the command member, to the bitwise inclusive OR of the following bits:

Value	Meaning
CMD_IO_SPACE	Controls a device's response to I/O space accesses. If this bit is set, the device can respond to I/O space accesses. If this bit is clear, the device cannot respond to I/O space accesses.
CMD_MEM_SPACE	Controls a device's response to memory space accesses. If this bit is set, the device can respond to memory space accesses. If this bit is clear, the device cannot respond to memory space accesses.
CMD_BUS_MASTER	Controls a device's ability to act as a master on the PCI bus (that is, it has DMA capability). If this bit is set, the device can act as a master on the PCI bus. If this bit is clear, the device cannot act as a master on the PCI bus.
CMD_SPEC_CYCLE	Controls a device's action on special cycle operations. If this bit is set, the device can monitor special cycle operations. If this bit is clear, the device ignores special cycle operations.
CMD_MEM_WR_INV	Controls a device's ability to use the memory write and invalidate bus command. If this bit is set, the device (acting as a master on the PCI bus) generates the memory write and invalidate bus command. If this bit is clear, the device (acting as a master on the PCI bus) generates the memory write bus command.
CMD_VGA_PALETTE	Controls how VGA-compatible and graphics devices handle accesses to VGA palette registers. If this bit is set, special palette-snooping behavior is enabled (that is, the device does not respond to palette register writes and snoops the data). If this bit is reset, the device should treat palette accesses like all other accesses.
CMD_PAR_ERR_RSP	Controls a device's response to parity errors. If this bit is set, the device must take its normal action when it detects a parity error. If this bit is reset, the device must ignore any parity errors that it detects and continue normal operation.
CMD_WAIT_CYCLE	Controls whether a device performs address/data stepping. If this bit is set, the device performs address/data stepping. If this bit is clear, the device does not perform address/data stepping.
CMD_SERR_EN	Indicates an enable bit for the SERR (System Error) pin driver. If this bit is set, the SERR driver is enabled. If this bit is clear, the SERR driver is disabled.
CMD_FAST_BBE	Controls whether a device (acting as a master on the PCI bus) can perform fast back-to-back transactions to different devices. If this bit is set, the device can generate fast back-to-back transactions to different devices. If this bit is clear, the device can generate fast back-to-back transactions only to the same device.

4.1.3    The status Member

The Status device register, copied to the status member of the pci_config_hdr data structure by the PCI bus configuration code, records status information for PCI bus-related events. Reads to the Status device register behave normally, but writes are handled specially. Some bits may not be set by a write. For instance, most error bits are designated as W1C (write 1 to clear). That is, whenever data is written to the register, those register bits are cleared that correspond to those data bit positions that are set. No other register bits are affected by the write.

The following Status device register bits are defined:

Value	Meaning
STAT_66MHZ	A read-only bit in the Status register that indicates whether this device can or cannot run at 66 MHz. A value of 0 indicates 33 MHz; a value of 1 indicates 66 MHz.
STAT_UDF	A read-only bit in the Status register that indicates whether this device supports user-definable features. Functions that do not support these features return a 0 when this bit is read. Functions that have device-specific configuration selections that must be presented to the user return a 1.
STAT_FAST_BBE	A read-only bit in the Status device register that indicates whether the target device can accept fast back-to-back transactions when the transactions are not to the same agent. If this bit is set, the target device can accept fast back-to-back transactions. If this bit is clear, the device cannot accept fast back-to-back transactions.
STAT_DATA_PAR	A data parity bit in the Status device register of a PCI bus master indicating that it has reported data parity. It is set when: - The bus agent asserted the PERR (Parity Error) pin itself or observed the PERR pin asserted - The parity error response bit (CMD_PAR_ERR_RSP) in the Command device register (command member of the pci_config_hdr data structure) is set - The agent setting the bit acted as the bus master for the operation in which the error occurred
STAT_DEVSEL_MASK	A read-only bit in the Status device register of a PCI bus master that indicates the slowest time the device asserts the DEVSEL (device select) pin for any bus command except a read or write to configuration address space. The following constants represent the valid timings: STAT_DEVSEL_SLOW (device select slow), STAT_DEVSEL_MED (device select medium), and STAT_DEVSEL_FAST (device select fast).
STAT_SIG_TARG_ABRT	A bit in the Status device register of a target device that is set whenever it terminates a transaction with target-abort.
STAT_RCVD_TARG_ABRT	A bit in the Status device register of a PCI bus master that is set whenever a transaction it has initiated terminates with target-abort.
STAT_RCVD_MSTR_ABRT	A bit in the Status device register of a PCI bus master that is set whenever a transaction it has initiated (except for special cycle) terminates with master-abort.
STAT_SIG_SYS_ERR	A bit in the Status device register that is set whenever a device asserts the SERR (system error) pin.
STAT_DET_PAR_ERR	A bit in the Status device register that is set whenever a device detects a parity error.

4.1.4    The class_code Member

The contents of the Class Code device register, copied to the class_code member of the pci_config_hdr data structure by the PCI bus configuration code, identifies the generic function of a device and, in some cases, a specific register-level programming interface. This member is a data structure that includes the following members:

Member	Data Type
base	u_char
sub_class	u_char
pio_int	u_char

The following sections describe these members.

4.1.4.1    The base Member

The contents of the base element of the Class Code device register, copied to the base member of the class_code member of the pci_config_hdr data structure by the PCI bus configuration code, broadly classify the type of function the device performs. The PCI bus configuration code can match the base member to the following base class code bits:

Value	Meaning
BASE_BC	Device was built before class code definitions were finalized.
BASE_MASS	Device performs the function of a mass storage controller.
BASE_NETWORK	Device performs the function of a network controller.
BASE_DISPLAY	Device performs the function of a display controller.
BASE_MULTMEDIA	Device performs the function of a multimedia device.
BASE_MEM	Device performs the function of a memory controller.
BASE_BRIDGE	Device performs the function of a bridge device.
BASE_COMM	Simple communications controller.
BASE_SYS_PERIPH	Generic system peripheral.
BASE_INPUT	Input device, such as a mouse or keyboard.
BASE_DOCK	Docking station.
BASE_PROCESSOR	Processor.
BASE_SERIAL_BUS	Serial bus controller.
BASE_UNKNOWN	Device fits in no known class.

4.1.4.2    The sub_class Member

The contents of the sub-class element of the Class Code device register, copied to the sub_class member of the class_code member of the pci_config_hdr data structure by the PCI bus configuration code, more specifically identify the function of the device. The PCI bus configuration code can match the sub_class member to a subclass code bit. The following tables group the bits according to the base Class Code device register bits, which are discussed in Section 4.1.4.1. For certain subclasses, the tables indicate the meaning of related programming interface element values. The register-level programming interface element of the Class Code device register is described in Section 4.1.4.3.

Value	Meaning
Subclass codes for BASE_BC:
SUB_PREDEF	Provides backward compatibility for devices that were built before the class code was defined.
SUB_PRE_VGA	This is a VGA-compatible device.
Subclass codes for BASE_MASS:
SUB_SCSI	Device is a SCSI bus controller.
SUB_IDE	Device is an IDE controller. See PCI IDE Controller Specification and Programming Interface for Bus Master IDE Controller for a description of the meaning of the programming interface bits (PIF_IDE_MASTER, PIF_IDE_PROG_SEC, PIF_IDE_PROG_PRI, PIF_ODE_OPM_SEC, and PIF_IDE_OPM_PRI) defined for this subclass.
SUB_FDI	Device is a diskette controller.
SUB_IPI	Device is an IPI bus controller.
SUB_MASS_OTHER	Device is some other mass storage controller.
Subclass codes for BASE_NETWORK:
SUB_ETHERNET	Device is an Ethernet controller.
SUB_TOKEN_RING	Device is a Token Ring controller.
SUB_FDDI	Device is an FDDI controller.
SUB_NETWORK_OTHER	Device is some other network controller.
Subclass codes for BASE_DISPLAY:
SUB_VGA	Device is a VGA-compatible controller. PIF_VGA_COMPAT and PIF_8514_COMPAT indicate VGA-compatible and 8514-compatible controllers, respectively.
SUB_XGA	Device is an XGA controller.
SUB_DISPLAY_OTHER	Device is some other display controller.
Subclass codes for BASE_MULTMEDIA:
SUB_VIDEO	Device is video.
SUB_AUDIO	Device is audio.
SUB_MULTMEDIA_OTHER	Device is some other multimedia device.
Subclass codes for BASE_MEM:
SUB_RAM	Device is a random-access memory (RAM) controller.
SUB_FLASH	Device is a FLASH controller.
SUB_MEM_OTHER	Device is some other memory controller.
Subclass codes for BASE_BRIDGE:
SUB_HOST	Device is a host bridge.
SUB_ISA	Device is an ISA bridge.
SUB_EISA	Device is an EISA bridge.
SUB_MC	Device is an MCA bridge.
SUB_PCI	Device is a PCI-to-PCI bridge.
SUB_PCMCIA	Device is a PCMCIA bridge.
SUB_NUBUS	Device is a NuBus bridge.
SUB_CARDBUS	Device is a CardBus bridge.
SUB_BRIDGE_OTHER	Device is some other bridge.
Value	Meaning
Subclass codes for BASE_COMM:
SUB_PC_COMM	Device is a serial PC communications controller. PIF_XT_SERIAL, PIF_16450_SERIAL, and PIF_16550_SERIAL indicate XT-compatible, 16450-compatible, and 16550-compatible serial controllers, respectively.
SUB_PARALLEL	Device is a parallel port communications controller. PIF_PARALLEL, PIF_BI_PARALLEL and PIF_ECP_PARALLEL indicate parallel port, bidirectional parallel port, and ECP 1.X compliant parallel port controllers, respectively.
SUB_COMM_OTHER	Device is some other communications controller.
Subclass codes for BASE_SYS_PERIPH:
SUB_8259_PIC	Device is an 8259 programmed-I/O controller (PIC). PIF_8259_PIC, PIF_ISA_8259, PIF_EISA_8259 indicate generic, ISA, and EISA PIC, respectively.
SUB_SLV_DMA	Device is an 8237 direct-memory access (DMA) controller. PIF_8237_DMA, PIF_ISA_DMA, PIF_EISA_DMA indicate generic, ISA, and EISA DMA controllers, respectively.
SUB_TIMER	Device is an 8254 quantum timer. PIF_8254_TIMER, PIF_ISA_TIMER, PIF_EISA_TIMER indicate generic, ISA, and EISA timers, respectively.
SUB_RTC_TIMER	Device is a realtime timer. PIF_RTC_TIMER and PIF_ISA_RTC indicate generic and ISA RTC controllers, respectively.
Subclass codes for BASE_INPUT:
SUB_KEYBOARD	Device is a keyboard controller.
SUB_PEN	Device is a digitizer pen.
SUB_MOUSE	Device is a mouse controller.
SUB_INPUT_OTHER	Device is some other input controller.
Subclass codes for BASE_DOCK:
SUB_DOCKING	Device is a generic docking station.
SUB_DOCK_OTHER	Device is some other docking station.
Subclass codes for BASE_PROCESSOR:
SUB_386	Device is a 386-based processor.
SUB_486	Device is a 486-based processor.
SUB_PENTIUM	Device is a Pentium processor.
SUB_ALPHA	Device is an Alpha processor.
SUB_COPROC	Device is a coprocessor.
Subclass codes for BASE_SERIAL_BUS:
SUB_P1394	Device is a Firewire (IEEE 1394) controller.
SUB_ACCESS	Device is an ACCESS.bus.
SUB_SSA	Device is an SSA controller.

4.1.4.3    The pio_int Member

The contents of the register-level programming interface element of the Class Code device register, copied to the pio_int member of the class_code member of the pci_config_hdr data structure by the PCI bus configuration code, identify a specific register-level programming interface so that device-independent software can interact with the device.

4.1.5    The cache_line_size Member

The contents of the Cache Line Size device register, copied to the cache_line_size member of the pci_config_hdr data structure by the PCI bus configuration code, indicate the system's cache line size in units of 32-bit words. Power-on self-test code sets the cache_line_size member according to PCI Local Bus Specification Revision 2.1.

4.1.6    The latency_timer Member

The contents of the Latency Timer device register for a PCI bus master, copied to the latency_timer member of the pci_config_hdr data structure by the PCI bus configration code, indicate the value of a bus master's latency timer in units of PCI bus clock ticks.

4.1.7    The hdr_type Member

The contents of the Header Type device register, copied to the hdr_type member of the pci_config_hdr data structure by the PCI bus configuration code, identify multifunction devices and specify the second part of the predefined header portion of configuration space (beginning at byte 16). The following values are defined:

Value	Meaning
HDR_MULTI_FCN	Device is multifunction if this bit is set.
HDR_LAYOUT_MASK	Mask used to extract configuration header type.
HDR_LAYOUT_V2	Configuration type defined in PCI Local Bus Specification Revision 2.1.

4.1.8    The bist Member

The contents of the Built-in Self Test device register, copied to the bist member of the pci_config_hdr data structure by the PCI bus configuration code, control and record the status of a device's built-in self test. The bits in the bist member have the following meaning:

Value	Meaning
BIST	The device supports a built-in self test.
BIST_START	The device has started its built-in self test.
BIST_STAT_MASK	This is a built-in self test completion code mask.
BIST_PASSED	The device passed the built-in self test.

4.1.9    The bar0, bar1, bar2, bar3, bar4, and bar5 Members

The contents of the base address device registers (BAR0, BAR1, BAR2, BAR3, BAR4, and BAR5) specify the mapping of a base address into bus memory space or bus I/O space. Bit 0 in a base address device register is read-only and indicates the register's specific mapping, as follows:

Value	Meaning
BAR_MEM_MAP	The base address device register maps into bus memory space.
BAR_IO_MAP	The base address device register maps into bus I/O space.

Base registers that map into I/O space are always 32 bits wide with bit <0> hardwired to 1. Base registers that map into memory space can be either 32 or 64 bits wide, with bit <0> hardwired to 0. Bits <2:1> in memory space base registers are hardwired in the device and have an encoded meaning, as represented by the values defined in the following table. Bit <3> is set to 1 if the data is prefetchable, or 0 otherwise. Power-on self-test code reads these bits to determine to which address space it assigns the device.

Value	Meaning
BAR_MEM_MAP_32B	Map this base address device register into the 32-bit PCI address space.
BAR_MEM_MAP_1M	Map this base address device register into the low 1-megabyte PCI address space.
BAR_MEM_MAP_64B	Map this base address device register into the low 64-bit PCI address space.
BAR_PREFETCH	Indicates that there are no read side effects for this base address device register.

The PCI bus configuration code reads the base address device registers and maps their contents to a proper I/O handle, which it then stores in the barx members (bar0, bar1, bar2, bar3, bar4, and bar5). A driver can read the I/O handle from the barx member and use it in calls to the read_io_port and write_io_port interfaces to access the address space.

4.1.10    The cis_ptr Member

The CardBus CIS Pointer register points to the Card Information Structure (CIS) for a CardBus card. This optional read-only register contains an offset to where the CIS begins in configuration space, memory space, or expansion ROM space.

Bits <30:28> of the CIS pointer (as indicated by the mask constant CISPTR_SPACE_MASK) indicate the address space in which the CIS resides, as follows:

Value	Meaning
CISPTR_SPACE_CONFIG	CIS in configuration space.
CISPTR_SPACE_BAR0	CIS in base address 0 space.
CISPTR_SPACE_BAR1	CIS in base address 1 space.
CISPTR_SPACE_BAR2	CIS in base address 2 space.
CISPTR_SPACE_BAR3	CIS in base address 3 space.
CISPTR_SPACE_BAR4	CIS in base address 4 space.
CISPTR_SPACE_BAR5	CIS in base address 5 space.
CISPTR_SPACE_EXPROM	CIS in expansion ROM space.

Bits <27:0> of the CIS pointer indicate the offset into the indicated address space at which the CIS is located. Use the following masks to obtain this offset:

Mask	Meaning
CISPTR_CONFIG_MASK	Address in device-dependent configuration space at which the CIS starts.
CISPTR_BAR_MASK	Offset into the indicated base address register space. Add this value to the value in the indicated Base Address register to obtain the starting location of the CIS.
CISPTR_EXPROM_MASK	Offset from the start of the image indicated by CISPRT_IMAGE_NUM_MASK to the start of the CIS. Add this offset to the starting offset of the image to obtain the starting location of the CIS.
CISPTR_IMAGE_NUM_MASK	Number of the image, in the expansion ROM address space indicated by the Expansion ROM base register, that contains the CIS.

4.1.11    The sub_vendor_id and sub_device_id Members

As mentioned in Section 4.1.1, the PCI bus configuration code matches device drivers to PCI devices by using the Vendor ID, Device ID, Revision ID, Class Code, Subsystem Vendor ID, and Subsystem ID device registers in the device's configuration space header. You can select which device registers participate in selecting a driver by creating PCI_Option entries in a sysconfigtab file fragment, as discussed in Section 4.2. Section 5.3 describes the mechanism by which the PCI bus configuration code identifies the driver associated with a given device.

The PCI bus configuration code copies the contents of the Subsystem Vendor ID and Subsystem ID device registers to the sub_vendor_id and sub_device_id members of the pci_config_hdr data structure. These values uniquely identify the add-in card or subsystem where a PCI device resides. These fields provide a mechanism to distinguish add-in cards even though the cards may have the same PCI front-end interface (and therefore the same vendor and device IDs). A value of 0 in these registers indicates that the device does not support subsystem identification.

4.1.12    The exp_rom_bar Member

The Expansion Read-Only-Memory (ROM) base address device register provides base address and size information for a PCI device that requires local EPROMs for expansion ROM. The upper 21 bits of the register correspond to the upper 21 bits of the expansion ROM base address. The number of these bits a device actually implements depends on its address alignment requirements. Bit <0> of this register, when set, indicates that the device accepts accesses to its expansion ROM.

The following constants are defined to allow the PCI bus configuration code to interpret the contents of this device register:

Value	Meaning
EXP_ROM_BASE_MASK	Mask used to extract upper 21 bits of the expansion ROM base address.
EXP_ROM_ENABLE	Enable expansion ROM address decoding. Note that the memory space bit (CMD_MEM_SPACE) in the Command device register ( command member of the pci_config_hdr) must also be set to allow access to the expansion ROM.

Power-on self-test code sets this register. The PCI bus configuration code reads it, mapping its contents to a proper I/O handle, which it then stores in the exp_rom_bar member of the pci_config_hdr data structure. The driver can use this I/O handle in calls to the read_io_port and write_io_port interfaces.

PCI device expansion ROMs can contain code for more than one processor architecture, implementing multiple code images for the different architectures in a single physical ROM. Each image must start on a 512-byte boundary and contain two data structures:

• A PCI expansion ROM header (pci_rom_exp_header), located at the beginning of the image

• A PCI data structure (pci_rom_data), located with the image's first 64K bytes

The starting point of each image depends on the size of previous images. The last image's PCI expansion ROM header contains special encoding to identify it as the last image.

4.1.12.1    The pci_rom_exp_header Data Structure

The pci_rom_exp_header data structure describes the address space of a PCI device's expansion ROM. The data structure itself is located at the beginning of the ROM image.

Table 4-2 lists the members of the pci_rom_exp_header data structure with their associated data types.

Table 4-2: Members of the pci_rom_exp_header Data Structure

The following list describes these members:

• The rom_sig member contains a 2-byte signature (the symbolic constant PCI_ROM_SIGNATURE).

• The rom_sig_len member contains the length of the ROM segment in 512-byte blocks.

• The init_vec member is a structure that contains (for Intel architectures) a 3-byte jump instruction to the start of the initialization code. For other architectures, it contains a 32-bit offset to the initialization code from the start of the pci_rom_exp_header data structure.

• The pci_rom_data_off member contains an offset to the pci_rom_data data structure from the start of the pci_rom_exp_header data structure.

4.1.12.2    The pci_rom_data Data Structure

The pci_rom_data data structure describes a PCI device's expansion ROM image. The data structure itself is located within the first 64K bytes of the ROM image and must be longword aligned.

Table 4-3 lists its members with their associated data types.

Table 4-3: Members of the pci_rom_data Data Structure

The following list describes these members:

• The signature member contains the string PCIR to uniquely identify the PCI data structure.

• The vendor_id member contains the vendor ID as defined in the Vendor ID device register ( vendor_id member of pci_config_hdr). See Section 4.1.1 for a description of the vendor ID.

• The device_id member contains the device ID as defined in the Device ID device register ( device_id member of pci_config_hdr). See Section 4.1.1 for a description of the device ID.

• The vital_data_off member contains the offset to the vital product data from the start of the ROM image. PCI Local Bus Specification Revision 2.1 does not define the structure of the vital product data.

• The struct_len member contains the size (in bytes) of the pci_rom_data structure.

• The struct_rev member identifies the pci_rom_data data structure revision level. For ROM images compliant with PCI Local Bus Specification Revision 2.1, this member contains the constant PCI_DATA_STRUCT_V2.

• The class_code member contains the class code as defined in the Class Code device register ( class_code member of pci_config_hdr). See Section 4.1.4 for a description of the class code.

• The image_length member contains the length of the image in 512-byte blocks.

• The code_revision member contains the revision level of the code in the ROM image.

• The code_type member identifies the type of code contained in this section of the ROM. You use the constants INTEL_ROM_CODE_TYPE, OPENFW_ROM_CODE_TYPE, or OPENBOOT_ROM_CODE_TYPE in this member.

• The indicator member contains the constant ROM_LAST_IMAGE (bit <7> set) if this is the last image in the ROM. All other values are reserved.

4.1.13    The intr_line Member

The contents of the Interrupt Line device register, copied to the intr_line member of the pci_config_hdr data structure by the PCI bus configuration code, specify interrupt routing information for a PCI bus device. They may or may not indicate to which input of the system interrupt controllers the device's interrupt pin is connected. Device drivers use the ihandler_id_t key returned from the handler_add interface to enable, disable, and delete an interrupt service interface in the operating system.

See Writing Device Drivers: Tutorial and Writing Device Drivers: Reference for more information about interrupt handler registration-related interfaces.

4.1.14    The intr_pin Member

The contents of the Interrupt Pin device register, copied to the intr_pin member of the pci_config_hdr data structure by the PCI bus configuration code, determine the mapping of handler_add calls to system interrupt request line logic.

The Interrupt Pin device register is hardwired by the device to one of the following bit values:

Value	Meaning
INTR_PIN_INTA	The device uses the PCI INTA interrupt pin.
INTR_PIN_INTB	The device uses the PCI INTB interrupt pin.
INTR_PIN_INTC	The device uses the PCI INTC interrupt pin.
INTR_PIN_INTD	The device uses the PCI INTD interrupt pin.

4.1.15    The min_gnt and max_lat Members

The contents of the MIN_GNT device register, copied to the min_gnt member of the pci_config_hdr data structure by the PCI bus configuration code, specify a minimal time period for which the device requires a bus grant. The min_gnt member stores a value that specifies how long a burst period the device needs. The period of time is expressed in units of 1/4 microseconds.

The contents of the MAX_LAT device register, copied to the max_lat member of the pci_config_hdr data structure by the PCI bus configuration code, specify maximum latency information. The max_lat member stores a value that specifies how often the device needs to gain access to the PCI bus. The period of time is expressed in units of 1/4 microseconds.

4.1.16    The config_base Member

The config_base member provides an I/O handle to the base of a PCI bus device's configuration address space. The driver can use this I/O handle in calls to the read_io_port and write_io_port interfaces.

4.1.17    The private Member

The private member specifies a private storage area that the device driver writer can use for storing driver-specific data.

4.2    PCI_Option Entries

The /etc/sysconfigtab database file contains information about PCI bus device options, which allows the PCI bus configuration code to identify the driver associated with the device and to configure the device. Section 5.3 discusses the role of the PCI_Option entries in determining the driver for a PCI bus device.

To support configuration, device drivers must provide a sysconfigtab file fragment, which contains a description of the devices that the driver can control. The information in the file fragment is added to the system's /etc/sysconfigtab database file when the driver is installed. This entry is used by both the startup procedure and the sysconfig utility to locate the driver module and to set device attributes.

The information provided in the sysconfigtab file fragment depends on the bus on which the device can operate. PCI_Option entries specify attributes of the PCI bus, as follows. Although many attributes are shown as optional, some combination of these attributes is required. Section 5.3 lists the valid combinations. If an optional attribute is not used in the configuration, you can omit it from the sysconfigtab entry, and its value is set to zero (0).

PCI_Option = \
PCI_SE_Rev - se_rev \
[ Vendor_Id - vendor_id \ ]
[ Device_Id - device_id \ ]
[ Rev - rev \ ]
[ Base - base \ ]
[ Sub - sub \ ]
[ Pif - pif \ ]
[ Sub_Vid - sub_vid \ ]
[ Sub_Did - sub_did \ ]
[ Vid_Mo_Flag - vid_mo_flag \ ]
[ Did_Mo_Flag - did_mo_flag \ ]
[ Rev_Mo_Flag - rev_mo_flag \ ]
[ Base_Mo_Flag - base_mo_flag \ ]
[ Sub_Mo_Flag - sub_mo_flag \ ]
[ Pif_Mo_Flag - pif_mo_flag \ ]
[ Sub_Vid_Mo_Flag - sub_vid_mo_flag \ ]
[ Sub_Did_Mo_Flag - sub_did_mo_flag \ ]
Driver_Name - driver_name \
Type - type \
Adpt_Config - adpt_config \
[ Comment - comment \ ]

The following sections describe these attributes.

4.2.1    The PCI_SE_Rev Attribute

The PCI_SE_Rev attribute provides a PCI software version ID. Its contents are defined as follows:

Bits	Meaning
Bits <11:8>	Major revision of the PCI specification.
Bits <7:4>	Minor revision of the PCI specification.
Bits <3:0>	Software revision in support of a major revision of the PCI specification.

4.2.2    The Vendor_Id Attribute

The Vendor_Id attribute specifies a vendor ID. This vendor ID is a hexadecimal value that is identical to the vendor ID stored in the vendor_id member of the pci_config_hdr data structure, as discussed in Section 4.1.1.

The /usr/sys/include/io/dec/pci/pci.h file defines symbolic constants for all known vendor IDs. You cannot use these constants as values for the attribute, but you can look up the values for known vendor IDs in this file.

Digital defines the following vendor IDs in the /usr/sys/include/io/dec/pci/pci.h file:

.
.
.

/*
 * Vendor ID defines (for readability)
 */
#define OLD_NCR_ID      0x1000
#define ATI_ID          0x1002
#define DEC_ID          0x1011
#define CIRRUS_ID       0x1013
#define IBM_ID          0x1014
#define NCR_ID          0x101A
#define AMD_ID          0x1022
#define COMPAQ_ID       0x1032
#define NEC_ID          0x1033
#define HP_ID           0x103C
#define KPC_ID          0x1040 /* Kubota Pacific Corp. */
#define TI_ID           0x104C
#define SONY_ID         0x104D
#define MOT_ID          0x1057 /* Motorola */
#define MYLEX_ID        0x1069
#define APPLE_ID        0x106B
#define QLOGIC_ID       0x1077
#define BIT3_ID         0x108A
#define CABLETRON_ID    0x10B1
#define THREE_COM_ID    0x10B7
#define CERN_ID         0x10DC
#define ECP_ID          0x10DC
#define ECU_ID          0x10DC
#define ES_ID           0x10DD /* Evans & Sutherland */
#define PROTEON_ID      0x1108
#define INTEL_ID        0x8086
#define ADP_ID          0x9004
#define PCI_VID_INVALID 0xFFFF

.
.
.

4.2.3    The Device_Id Attribute

The Device_Id attribute specifies a hexadecimal value that is identical to the device ID stored in the device_id member of the pci_config_hdr data structure, as discussed in Section 4.1.1.

The /usr/sys/include/io/dec/pci/pci.h file defines symbolic constants for all known device IDs. You cannot use these constants as values for the attribute, but you can look up the values for known vendor IDs in this file.

Digital defines the following device IDs in the /usr/sys/include/io/dec/pci/pci.h file:

.
.
.

/*
 * Device ID defines (for readability)
 */
#define DEC_PPB         0x0001  /* PCI-PCI bridge */
#define DEC_21040       0x0002  /* TULIP ethernet */
#define DEC_21140       0x0009  /* FasterNet fast ethernet */
#define DEC_PACER       0x000F  /* PACER fddi */
#define DEC_TGA         0x0004  /* TGA graphics */
#define DEC_NVRAM       0x0007  /* ZEPHYR presto-nvram */
#define DEC_PZA         0x0008  /* PZA SCSI */
#define DEC_7407        0x0010  /* VME interface processor */
#define DEC_RM_SPUR     0x0018  /* DEC Reflective Memory */
#define INTEL_PCEB      0x0482  /* PCI-EISA bridge */
#define INTEL_SIO       0x0484  /* PCI-ISA bridge */
#define NCR_810         0x0001
#define QLOGIC_ISP1020  0x1020  /* QLOGIC ISP1020 SCSI adapter */
#define ADP_7870        0x7078
#define ATI_MACH32      0x4158
#define ATI_MACH64_CX   0x4358
#define ATI_MACH64_GX   0x4758
#define MYLEX_960P      0x0001  /* PCI RAID */
#define S3_VISION864    0x88c0

.
.
.

4.2.4    The Rev Attribute

The Rev attribute specifies a revision ID. This revision ID is identical to the manufacturer-specified value stored in the rev_id member of the pci_config_hdr data structure, as discussed in Section 4.1.1.

4.2.5    The Base Attribute

The Base attribute specifies a value that generally identifies the function of a device. The Base classification is identical to the value stored in the base member of the class_code data structure in the pci_config_hdr data structure, as discussed in Section 4.1.4.1.

4.2.6    The Sub Attribute

The Sub attribute identifies the specific function of a device. The subclassification is identical to the value stored in the sub_class member of the class_code data structure in the pci_config_hdr data structure, as discussed in Section 4.1.4.2.

4.2.7    The Pif Attribute

The Pif attribute identifies a specific register-level programming interface for a device. The programming interface code is identical to the value stored in the pio_int member of the class_code data structure in the pci_config_hdr data structure, as discussed in Section 4.1.4.3.

4.2.8    The Sub_Vid and Sub_Did Attributes

The Sub_Vid and Sub_Did attributes uniquely identify the add-in card or subsystem where a PCI device resides. These attributes provide a mechanism to distinguish add-in cards even though the cards may have the same PCI front-end interface (and therefore the same vendor and device IDs). A value of zero (0) in these members indicates that the device does not support subsystem identification.

The subsystem vendor and device IDs are hexadecimal values, identical to the subsystem vendor and device IDs stored in the sub_vendor_id and sub_device_id members of the pci_config_hdr data structure, as discussed in Section 4.1.11.

The /usr/sys/include/io/dec/pci/pci.h file defines symbolic constants for all known subsystem vendor and device IDs. You cannot use these constants as values for the attribute, but you can look up their values in this file.

4.2.9    The Vid_Mo_Flag Attribute

When set, the Vid_Mo_Flag attribute indicates that the Vendor_Id attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.10    The Did_Mo_Flag Attribute

When set, the Did_Mo_Flag attribute indicates that the Device_Id attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.11    The Rev_Mo_Flag Attribute

When set, the Rev_Mo_Flag attribute indicates that the Rev attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.12    The Base_Mo_Flag Attribute

When set, the Base_Mo_Flag attribute indicates that the Base attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.13    The Sub_Mo_Flag Attribute

When set, the Sub_Mo_Flag attribute indicates that the Sub attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.14    The Pif_Mo_Flag Attribute

When set, the Pif_Mo_Flag attribute indicates that the Pif attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.15    The Sub_Vid_Mo_Flag Attribute

When set, the Sub_Vid_Mo_Flag attribute indicates that the Sub_Vid attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.16    The Sub_Did_Mo_Flag Attribute

When set, the Sub_Did_Mo_Flag attribute indicates that the Sub_Did attribute of the PCI_Option entry participates in the matching of the device to its driver.

4.2.17    The Driver_Name Attribute

The Driver_Name attribute specifies the name of the controlling device driver. You set Driver_Name to a character string that represents the name of the controlling device driver, up to 16 characters long. For example, the string tu identifies the controlling device driver for the device with the device ID of DEC_4250 and vendor ID of DEC_ID.

4.2.18    The Type Attribute

The Type attribute specifies the type of device. You can set Type to C if the device is a controller, or A if the device is a bus or bus adapter. The default value is C.

4.2.19    The Adpt_Config Attribute

The Adpt_Config attribute specifies the name of the bus (or adapter) configuration interface to call. If Type is A (the device is a bus or a bus adapter), you should set Adpt_Config to the string that identifies the bus adapter's hardware-specific initialization and setup interface. If Type is C (the device is a controller), you should not set the Adpt_Config attribute as it has no significance.

4.3    The /etc/sysconfigtab Database File

The /etc/sysconfigtab database file contains the PCI_Option entries for all PCI buses connected to the system. Each entry stores information about a specific PCI bus option, such as the vendor and device IDs and the name of the controlling device driver. Digital ships the /etc/sysconfigtab database file with its own PCI bus option product information. Third-party device driver writers should supply a sysconfigtab file fragment, which is added to /etc/sysconfigtab during driver installation.

The following shows a sysconfigtab entry to define the NVRAM driver:

PCI_Option =  \
     PCI_SE_Rev - 0x210, Vendor_Id - 0x1011, Device_Id - 0x7, \
     Rev - 0, Base - 0, Sub - 0, Pif - 0, Sub_Vid - 0, \
     Sub_Did - 0, Vid_Mo_Flag - 1, Did_Mo_Flag - 1, \
     Rev_Mo_Flag - 0, Base_Mo_Flag - 0, Sub_Mo_Flag - 0, \
     Pif_Mo_Flag - 0, Sub_Vid_Mo_Flag - 0, Sub_Did_Mo_Flag - 0, \
     Driver_Name - pnvram, Type - C, Adpt_Config - N

At system startup, if the PCI bus configuration code detects a device on the PCI bus that does not have a PCI_Option entry, it reports the following error:

Module <vid:did> not in pci_option table, can't configure it.

The <vid:did> IDs are the vendor and device IDs (in hexadecimal) of the device found on the PCI bus for which the bus configuration code could not find a match in the PCI_Option entries provided in /etc/sysconfigtab.