A    PCI Bus-Specific Reference Information

This appendix describes the following PCI bus-specific information:

• Conventions for reference pages

• Header file

• Data structures

• Device driver interfaces

A.1    Conventions for Reference Pages

The following sections describe the conventions used for:

• Header files

• Data structures

• Driver interfaces

A.1.1    Conventions for Header File

The description of the header file associated with PCI bus device drivers can include the following sections.

Name

This section lists the name of the header file along with a summary description of its contents.

Location

This section presents the pathname for the header file. The pathname makes it easier for you to locate specific header files.

Description

This section briefly describes the contents of the header file.

When to Include

This section explains when to include a header file for block and character drivers.

Of Special Interest

This section lists specific structures, macros, constant values, and so forth that are of interest to device driver writers.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.1.2    Conventions for Data Structures

The description of the data structures associated with PCI bus device drivers are presented in alphabetical order and in reference page style. The descriptions can include the following sections.

Name

This section lists the name of the structure along with a summary description of its purpose.

Include File

This section lists the header file, including the path, where the structure is defined.

Synopsis

This section considers the following when describing structures:

• The C structure declaration is shown

  This occurs when you need to understand or initialize all of the members of a structure.

• The structure members are shown in a table

  This occurs when you need to understand or reference some of the members of a particular structure.

• No structure declaration or structure table is shown

  This occurs when the structure is opaque. This means the members of the structure are manipulated by the Digital UNIX operating system. You do not manipulate or reference any of the members.

Members

This section provides a short description of each member of the structure.

Description

This section gives more details about the purpose of the structure.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.1.3    Conventions for Device Driver Interfaces

The descriptions of the device driver interfaces associated with PCI bus device drivers are presented in alphabetical order and in reference page style. The descriptions can include the following sections.

Name

This section lists the name of the driver interface along with a summary description of its purpose. In general, there is one interface described for each reference page. However, in some cases it makes sense to describe more than one interface on the same page if the interfaces are related. When this occurs, this section lists the names of all the interfaces it describes.

Entry Point

This section lists the structure or file where you specify the entry for the device driver interface.

Synopsis

This section shows the device driver interface function definition. The style used is that of the function definition, not the function call. This book assumes that you understand how to interpret the function definition and how to write an appropriate call for a specific interface. The presentation shown in the following example is of the function definition:

int xxprobe (slot_cnfg_p, ctlr)
struct pci_config_hdr *slot_cnfg_p;
struct controller *ctlr;
The previous interface function definition gives you the following information:

• Return type

  Gives the data type of the return value, if the interface returns data. If the interface does not return a value, the function definition shows a void data type.

• Interface name

  Gives the driver interface name. In the example, xxprobe is the name of the driver interface. The prefix xx indicates that this part of the name is variable. Replace it with the character prefix that represents the name of the device for which the driver is being written.

• Argument names

  Gives the name of each driver interface argument. In the example, the argument names are slot_cnfg_p and ctlr.

• Argument types

  Gives the types for each of the arguments. If you must define the type of the argument, a void * is used. In the example, these types are struct pci_config_hdr * and struct controller *.

  The term driver interface is used instead of driver routine to establish consistent terminology with that used for the kernel interfaces.

Arguments

This section provides descriptions for the arguments associated with a given driver interface. In most cases, argument descriptions begin with the word specifies to indicate that the driver writer passes the argument (with some specified value) to the driver interface.

Description

This section contains explanations of the tasks performed by the driver interface.

Notes

This section contains information about the driver interface pertinent to the device driver writer.

Return Values

This section describes the values that a given driver interface can return.

Related Information

This section lists related kernel interfaces, structures, system calls, and so forth.

A.2    Header File

The /usr/sys/include/io/dec/pci/pci.h file is the only header file used exclusively by PCI bus device drivers.

Device driver writers should include header files by using the relative pathname instead of the explicit pathname. For example, although buf.h resides in /usr/sys/include/sys/buf.h, a device driver writer should include it as <sys/buf.h>.

pci.h

Contains definitions for PCI bus support

Location

/usr/sys/include/io/dec/pci/pci.h

Description

The pci.h file contains definitions for PCI bus support.

When to Include

You include this file in device drivers that connect to the PCI bus.

Of Special Interest

Items of interest to device driver writers are:

• The pci_config_hdr data structure

• PCI_Option sysconfigtab entries

• Defines for the register bits and class_code members of the pci_config_hdr data structure

A.3    Data Structures

Table A-1 lists the data structures specific to PCI bus device drivers, along with short descriptions of their contents.

Table A-1: Summary Descriptions of Data Structures

pci_config_hdr

Contains configuration and register layout information

Include File

/usr/sys/include/io/dec/pci/pci.h

Synopsis

Member Name	Data Type
vendor_id	u_short
device_id	u_short
command	u_short
status	u_short
rev_id	u_char
class_code	struct class_code
cache_line_size	u_char
latency_timer	u_char
hdr_type	u_char
bist	u_char
bar0	io_handle_t
bar1	io_handle_t
bar2	io_handle_t
bar3	io_handle_t
bar4	io_handle_t
bar5	io_handle_t
cis_ptr	io_handle_t
sub_vendor_id	u_short
sub_device_id	u_short
exp_rom_bar	io_handle_t
intr_line	u_char
intr_pin	u_char
min_gnt	u_char
max_lat	u_char
config_base	io_handle_t
private	u_long

Members

vendor_id

Specifies a vendor ID. The PCI bus configuration code obtains this vendor ID from the vendor ID device register. This ID identifies the manufacturer of the device that operates on the PCI bus. Manufacturers who are members of the PCI special interest group (SIG) can request a vendor ID to avoid conflict with other vendors.

device_id

Specifies a device ID that identifies the specific device. The PCI bus configuration code obtains this device ID from the device ID device register. The device's manufacturer determines its device ID.

command

Specifies a command that provides general control over a device's ability to generate and respond to PCI bus cycles. The PCI bus configuration code obtains the command from 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 command device register bits defined in /usr/sys/include/io/dec/pci/pci.h. See Section 4.1.2 for descriptions of the valid command device register bits.

status

Records status information for PCI bus-related events. The PCI bus configuration code copies this status information from the status device register to the status member. 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 status device register bits are defined in /usr/sys/include/io/dec/pci/pci.h and described in Section 4.1.2.

rev_id

Specifies a device-specific revision ID. The PCI bus configuration code obtains this device-specific revision ID from the revision ID device register. The device's manufacturer determines its revision ID.

class_code

Specifies a class code. This member is a data structure that stores information related to the device's class code device register. See Section 4.1.4 for a description of the members of the class_code structure.

cache_line_size

Specifies a cache line size in units of 32-bit words. The PCI bus configuration code obtains this cache line size from the cache line size device register. Power-on self-test code sets the cache_line_size member according to PCI Local Bus Specification Revision 2.1.

latency_timer

Indicates the value of a bus master's latency timer in units of PCI bus clock ticks. The PCI bus configuration code obtains this latency timer from the latency timer device register.

hdr_type

Identifies a multifunction device and specifies the layout of bytes 16 through 63 in the configuration space header. The PCI bus configuration code obtains this information from the header type device register. See Section 4.1.7 for a description of the possible values of this member.

bist

Controls and records the status of a device's built-in self test. The PCI bus configuration code obtains this value from the built-in self test device register. See Section 4.1.8 for a description of possible values for this member.

bar0

Contains an I/O handle to the address space specified by the base address zero (BAR0) device register. A driver can read the I/O handle from the bar0 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

bar1

Contains an I/O handle to the address space specified by the base address one (BAR1) device register. A driver can read the I/O handle from the bar1 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

bar2

Contains an I/O handle to the address space specified by the base address two (BAR2) device register. A driver can read the I/O handle from the bar2 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

bar3

Contains an I/O handle to the address space specified by the base address three (BAR3) device register. A driver can read the I/O handle from the bar3 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

bar4

Contains an I/O handle to the address space specified by the base address four (BAR4) device register. A driver can read the I/O handle from the bar4 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

bar5

Contains an I/O handle to the address space specified by the base address five (BAR5) device register. A driver can read the I/O handle from the bar5 member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.9 for a discussion of the mechanism by which the contents of a base address device register is mapped to an I/O handle.

cis_ptr

Points to the Card Information Structure (CIS) for a CardBus card. This read-only register contains an offset to where the CIS begins in configuration space, memory space, or expansion ROM space. See Section 4.1.10 for a discussion of the contents of the cis_ptr member.

sub_vendor_id

Specifies a subsystem vendor ID. The PCI bus configuration code obtains this subsystem vendor ID from the subsystem vendor ID device register. This ID identifies the manufacturer of a device that operates on the PCI bus from the same controller card as other devices with the same vendor and device IDs. The device's manufacturer determines its subsystem device ID.

sub_device_id

Specifies a subsystem device ID that identifies the specific device. The PCI bus configuration code obtains this subsystem device ID from the subsystem device ID device register. This ID identifies a device that operates on the PCI bus from the same controller card as other devices with the same vendor and device IDs. The device's manufacturer determines its subsystem device ID.

exp_rom_bar

Contains an I/O handle to the address space specified by the expansion ROM base address device register. A driver can read the I/O handle from the exp_rom_bar member and use it in calls to the read_io_port and write_io_port interfaces to access the address space. See Section 4.1.12 for a discussion of the mechanism by which the contents of the expansion ROM base address device register is mapped to an I/O handle.

intr_line

Specifies interrupt routing information for a PCI bus device. This member 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.

intr_pin

Determines the mapping of handler_add calls to system interrupt request line logic. It can contain any of the bit values defined in Section 4.1.14.

min_gnt

Specifies 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.

max_lat

Specifies 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.

config_base

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.

private

Specifies a private storage area that the device driver can use for storing driver-specific data.

Description

The pci_config_hdr data structure contains information that describes configuration and device register layout information for each device connected to a controller that operates on a PCI bus.

Related Information

Section 4.1: The pci_config_hdr Data Structure

pci.h

PCI_Option

Defines PCI bus options in the sysconfigtab file

Include File

/usr/sys/include/io/dec/pci/pci.h

Synopsis

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 \ ]

Members (Attributes)

PCI_SE_Rev

Provides a PCI software version ID that indicates major and minor revisions to the PCI local bus specification, and software revisions to comply with the major revisions. This member helps to maintain binary compatibility for PCI bus device drivers that rely on earlier versions of the PCI data structures.

Vendor_Id

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.

Device_Id

Specifies a device ID. This device ID is 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.

Rev

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.

Base

Specifies a value that generally identifies the function of a device. This 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.

Sub

Identifies the specific function of a device. This 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.

Pif

Identifies a specific register-level programming interface for a device. This 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.

Sub_Vid

Specifies a subsystem vendor ID. This subsystem vendor ID is a hexadecimal value that is identical to the subsystem vendor ID stored in the sub_vendor_id member of the pci_config_hdr data structure, as discussed in Section 4.1.11.

Sub_Did

Specifies a subsystem device ID. This subsystem device ID is a hexadecimal value that is identical to the subsystem device ID stored in the sub_device_id member of the pci_config_hdr data structure, as discussed in Section 4.1.11.

Vid_Mo_Flag

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

Did_Mo_Flag

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

Rev_Mo_Flag

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

Base_Mo_Flag

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

Sub_Mo_Flag

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

Pif_Mo_Flag

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

Sub_Vid_Mo_Flag

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

Sub_Did_Mo_Flag

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

Driver_Name

Specifies the name of the controlling device driver. You set Driver_Name to the character string that represents the name of the controlling device driver. You may use up to a maximum of 16 characters.

Type

Specifies the type of device. Set Type to C if the device is a controller, or to A if the device is a bus or a bus adapter. The default value is C.

Adpt_Config

Specifies the name of the bus (or bus adapter) configuration interface. If Type is set to A, set Adpt_Config to the string that identifies the PCI bus adapter hardware-specific initialization and setup interface. If Type is set to C, the Adpt_Config attribute has no significance and should not be set.

Description

The PCI_Option sysconfigtab entry contains information about a PCI bus device option that 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 entry in determining the driver for a PCI bus device.

Related Information

Section 4.2: PCI_Option Entries

Section A.2, Header File: pci.h

pci.h

pci_rom_exp_header

Describes the address space of a PCI device's expansion ROM

Include File

/usr/sys/include/io/dec/pci/pci.h

Synopsis

Member Name	Data Type
rom_sig	u_short
rom_sig_len	u_char
init_vec	struct init_vec
pci_rom_data_off	u_short

Members

rom_sig

Contains a 2-byte signature (the symbolic constant PCI_ROM_SIGNATURE).

rom_sig_len

Contains the length of the ROM segment in 512-byte blocks.

init_vec

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.

pci_rom_data_off

Contains an offset to the PCI data structure from the start of the pci_rom_exp_header data structure.

Description

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.

Related Information

Section 4.1: The pci_config_hdr Data Structure

Section 4.1.12.2: The pci_rom_data Structure

pci.h

pci_rom_data

Describes a PCI device's expansion ROM image

Include File

/usr/sys/include/io/dec/pci/pci.h

Synopsis

Member Name	Data Type
signature	u_int
vendor_id	u_short
device_id	u_short
vital_data_off	u_short
struct_len	u_short
struct_rev	u_short
class_code	struct class_code
image_length	u_short
code_revision	u_short
code_type	u_char
indicator	u_char

Members

signature

Contains the string PCIR to uniquely identify the PCI data structure.

vendor_id

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.

device_id

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.

vital_data_off

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 contents of the vital product data structure.

struct_len

Contains the size (in bytes) of the pci_rom_data data structure.

struct_rev

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.

class_code

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.

image_length

Contains the length of the image in 512-byte blocks.

code_revision

Contains the revision level of the code in the ROM image.

code_type

Identifies the type of code contained in this section of the ROM. You use the constants INTEL_ROM_CODE_TYPE or OPENFW_ROM_CODE_TYPE in this member. (OPENBOOT_ROM_CODE_TYPE is supported in pci.h for backward compatibility; OPENFW_ROM_CODE_TYPE is the preferred symbol.)

indicator

Contains the constant ROM_LAST_IMAGE (bit <7> set) if this is the last image in the ROM. All other values are reserved.

Description

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.

Related Information

pci.h

Section 4.1.12.1: The pci_rom_exp_header Data Structure

Section 4.1: The pci_config_hdr Data Structure

A.4    Device Driver Interfaces

Table A-2 lists the device driver interfaces specific to PCI bus device drivers, along with short descriptions of their contents.

Table A-2: Summary Descriptions of Driver Interfaces Specific to PCI Bus Device Drivers

See Writing Device Drivers: Tutorial for other interfaces the driver needs to provide, which are not PCI-specific.

xxprobe

Determines whether the device exists

Entry Point

The driver structure

Synopsis

int xxprobe (slot_cnfg_p, ctlr)
struct pci_config_hdr *slot_cnfg_p;
struct controller *ctlr;

Arguments

slot_cnfg_p

Specifies a pointer to a pci_config_hdr data structure. There is one pci_config_hdr data structure for each device function connected to the slot associated with this PCI bus. The bus configuration code passes this pointer to the driver's xxprobe interface. The device driver can reference configuration and device register-related information contained in the pci_config_hdr structure pointer.

ctlr

Specifies a pointer to the controller structure associated with this device. The bus configuration code passes this pointer to the driver's xxprobe interface. The device driver can reference hardware resources and other information contained in the controller structure pointer.

Description

The PCI bus code calls the xxprobe interface for each device on the PCI bus for which it finds a matching PCI_Option entry in the /etc/sysconfigtab database file. For a statically configured driver, this happens during autoconfiguration at system startup. For a dynamically configured driver, it happens when the driver calls the configure_driver interface.

The driver's xxprobe interface performs the following tasks to determine if the device exists and is functional on a given bus in the system:

• Checks a device control status register (CSR) to determine whether the physical device is present. If the device is not present, the device is not initialized and not available for use.

• Creates and deletes interrupt handlers by calling the handler_add and handler_delete interfaces, and enables and disables them with the handler_enable and handler_disable interfaces.

Return Values

The xxprobe interface returns a nonzero value if the probe operation is successful. It returns the value zero (0) to indicate that the driver did not complete the probe operation.

Related Information

xxslave

Writing Device Drivers: Reference: controller structure

xxslave

Checks that the device is valid for this controller

Entry Point

The driver structure

Synopsis

int xxslave (device, slot_cnfg_p)
struct device *device;
struct pci_config_hdr *slot_cnfg_p ;

Arguments

device

Specifies a pointer to a device structure for this device. The bus configuration code passes this pointer to the driver's xxslave interface. The device driver can reference such information as the logical unit number of the device, whether the device is functional, and the bus number the device resides on.

slot_cnfg_p

Specifies a pointer to a pci_config_hdr data structure. There is one pci_config_hdr data structure for each device function connected to the slot associated with this PCI bus. The bus configuration code passes this pointer to the driver's xxslave interface. The device driver can reference configuration and device register-related information contained in the pci_config_hdr structure pointer.

Description

A device driver's xxslave interface is called only for a controller that has slave devices connected to it. This interface is called once for each slave attached to the controller. You (or the system manager) specify the attachments of these slave devices in the driver's xxconfigure interface by calling the configure_device and configure_driver interfaces.

Return Values

The xxslave interface returns a nonzero value if the device is present.

Related Information

xxprobe

Writing Device Drivers: Reference: device structure