8.4. PCI Support

eCos provides a Peripheral Component Interconnect (PCI) bus library. The PCI bus is a high-performance 32- or 64-bit bus that has multiplexed address and data lines. The bus is intended to connect peripheral controller components, add-in boards, and processor/memory systems. The PCI bus is commonly found in PCs today, but is has also made its way into embedded system designs. The current version of the PCI bus specification is 2.2. Additional information about the PCI specification can be found online at:

www.pcisig.com

The eCos PCI Configuration Library (CYGPKG_IO_PCI) package can be found in the pci subdirectory under the I/O Sub-System packages subdirectory, io. See Figure 1.3 in Chapter 1 for an overall view of the directory structure. This library provides the following functionality:

  • Scan the bus for specific devices based on Device and Vendor ID or on a particular device class code.

  • Read and modify the generic PCI information.

  • Read and modify the device-specific PCI information.

  • Allocate PCI memory and I/O space for devices.

  • Translate device specific PCI interrupts into HAL vectors.

8.4.1. PCI Library API

The eCos PCI library package contains two main source files, pci.c, high-level PCI library API functions; and pci_hw.c, low-level HAL interface routines. The high-level API routines are used by applications to control the devices on the PCI bus. There are also low-level PCI routines, which are used by the high-level API to access the HAL platform-specific PCI functionality. The high-level PCI library API functions are described in Item List 8.4 and can be found in the file pci.h.

Item list 8.4. PCI Library API Functions
Syntax: 
void
cyg_pci_init(
 void
 );

Parameters:None
Description:Initialize the PCI bus allowing access to the configuration space. This should be the first function called, although certain HALs might call this function as part of the platform initialization procedure.
Syntax: 
cyg_bool
cyg_pci_find_device(
 cyg_uint16 vendor,
 cyg_uint16 device,
 cyg_pci_device_id *devid
 );

Parameters:

vendor— Vendor ID of the device to find.

device— Device ID of the device to find.

devid— pointer to the Device ID where to start the scan. When the function returns, this points to the Device ID of the next device.

Description:Scans the PCI bus configuration space for a device with the given Vendor and Device IDs. The search begins with the device specified in the devid parameter; specifying CYG_PCI_NULL_DEVID starts the search at the first slot. This function returns TRUE if the specified device is found; otherwise, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_find_class(
 cyg_uint32 dev_class,
 cyg_pci_device_id *devid
 );

Parameters:

dev_class— Class Code of the device to find.

devid— pointer to the bus number, device number, and functional number of the device where to start the scan. When the function returns, this points to the bus number, device number, and functional number of the next device.

Description:Searches the PCI bus configuration space for the device with the Class Code specified in the dev_class parameter. The search begins with the device specified in the devid parameter; specifying CYG_PCI_NULL_DEVID starts the search at the first slot. This function returns TRUE if the specified device is found; otherwise, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_find_next(
 cyg_pci_device_id cur_devid,
 cyg_pci_device_id *next_devid
 );

Parameters:

cur_devid— bus number, device number, and functional number of the device where the search begins.

next_devid— pointer to the bus number, device number, and functional number of the next device. This parameter can also point to cur_devid.

Description:Scans the PCI configuration space for the next valid device after the device specified in the cur_devid parameter. The search begins with the device specified in the devid parameter; specifying CYG_PCI_NULL_DEVID starts the search at the first slot. This function returns TRUE if another device is found; otherwise, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_find_matching(
 cyg_pci_match_func *matchp,
 void *match_callback_data,
 cyg_pci_device_id *devid
 );

Parameters:

matchp— pointer to function, supplied by the caller, that checks if the device returned matches.

match_callback_data— pointer to user data to pass to the matchp callback function.

devid— pointer to device information to begin search.

Description:Searches the PCI bus configuration space for a device whose properties match those required by the matchp function. The matchp function is called for each device on the bus. The search begins with the device pointed to in the devid parameter. This function returns TRUE if a matching device is found; otherwise, FALSE is returned.
Syntax: 
void
cyg_pci_get_device_info(
 cyg_pci_device_id devid,
 cyg_pci_device *dev_info
 );

Parameters:

devid— bus number, device number, and functional number of the device.

dev_info— pointer to returned configuration information for the device.

Description:Gets the generic PCI configuration information for the device specified in the devid parameter.
Syntax: 
void
cyg_pci_set_device_info(
 cyg_pci_device_id devid,
 cyg_pci_device_id *dev_info
 );

Parameters:

devid— bus number, device number, and functional number of the device.

dev_info— pointer to configuration information to set the device. The function sets this parameter to the configuration information by reading back the written information when it returns.

Description:Set the generic PCI configuration information for the device specified in the devid parameter.
Syntax: 
void
cyg_pci_read_config_uintX(
 cyg_pci_device_id devid,
 cyg_uint8 offset,
 cyg_uintX *val
 );

Parameters:

devid— bus number, device number, and functional number of the device.

offset— register offset.

val— pointer to the returned register value.

Description:Reads the device-specific register from the PCI configuration space for the device specified in the devid parameter. The X in the function name and the type of the val parameter are 8, 16, or 32 and determine the size of the read performed. This routine should be used to access device-specific registers; general accesses should use the cyg_pci_get_device_info function.
Syntax: 
void
cyg_pci_write_config_uintX(
 cyg_pci_device_id devid,
 cyg_uint8 offset,
 cyg_uintX val
 );

Parameters:

devid— bus number, device number, and functional number of the device.

offset— register offset.

val— value to set in the specified register.

Description:Sets the device specific register in the PCI configuration space for the device specified in the devid parameter. The X in the function name and the type of the val parameter are 8, 16, or 32 and determine the size of the write performed. This routine should be used to access device-specific registers; general accesses should use the cyg_pci_set_device_info function.
Syntax: 
cyg_bool
cyg_pci_configure_device(
 cyg_pci_device *dev_info
 );

Parameters:

dev_info— pointer to the device configuration header information. When the function returns, this parameter contains the resource allocations for the device.

Description:Handles all I/O and memory regions that need configuration on a device by allocating memory to all Base Address Registers (BARs). These allocated base addresses are stored in the dev_info parameter. If the dev_info parameter does not contain valid base size values, false is returned. This function also calls cyg_pci_translate_interrupt.
Syntax: 
cyg_bool
cyg_pci_configure_bus(
 cyg_uint8 bus,
 cyg_uint8 *next_bus
 );

Parameters:

bus— current bus number.

bus_next— pointer to the subordinate buses. This parameter specifies the bus number to assign to the next subordinate bus found. The number is incremented for new buses discovered.

Description:Allocates memory and I/O space for all Base Address Registers (BAR) on all devices for the bus specified by the bus parameter and subordinate buses specified by the bus_next parameter. This function is used in systems with multiple buses connected by bridges. On success, TRUE is returned; otherwise, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_translate_interrupt(
 cyg_pci_device *dev_info,
 CYG_ADDRWORD *vec
 );

Parameters:

dev_info— pointer to the device configuration header information.

vec— pointer to translated interrupt vector number.

Description:Translates the PCI interrupt signal (INTA, INTB, INTC or INTD) to the associated HAL interrupt vector. If the device generates interrupts, the translated vector number is placed in the vec parameter and TRUE is returned; otherwise, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_allocate_memory(
 cyg_pci_device *dev_info,
 cyg_uint32 bar,
 CYG_PCI_ADDRESS64 *base
 );

Parameters:

dev_info— pointer to the device configuration header information.

bar— Base Address Register to allocate memory.

base— pointer to the base address to allocate the memory. The address of the next free location is returned in this parameter if the allocation succeeds.

Description:Allocates memory to the BAR specified in the bar parameter, which allows a device driver to set up its own memory mappings. If the BAR is the wrong type or the dev_info parameter does not contain valid base sizes, FALSE is returned.
Syntax: 
cyg_bool
cyg_pci_allocate_io(
 cyg_pci_device *dev_info,
 cyg_uint32 bar,
 CYG_PCI_ADDRESS32 *base
 );

Parameters:

dev_info— pointer to the device configuration header information.

bar— Base Address Register to allocate I/O space.

base— pointer to the base address to allocate the I/O space. The address of the next free location is returned in this parameter if the allocation succeeds.

Description:Allocates I/O space to the BAR specified in the bar parameter, which allows a device driver to set up its own I/O mappings. If the BAR is the wrong type or the dev_info parameter does not contain valid base sizes, FALSE is returned.
Syntax: 
void
cyg_pci_set_memory_base(
 CYG_PCI_ADDRESS64 base
 );

Parameters:

base— address for BAR memory mapping.

Description:Set the base address for memory mapping, overriding the default values set in the platform PCI initialization.
Syntax: 
void
cyg_pci_set_io_base(
 CYG_PCI_ADDRESS32 base
 );

Parameters:

base— address for BAR I/O mapping.

Description:Set the base address for I/O mapping, overriding the default values set in the platform PCI initialization.

A good source for example code on using the PCI library API functions can be found in the PCI Library package test file pci1.c. Within this file is the routine pci_test. This routine shows how to initialize the PCI bus and then scan the bus for all devices present.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.222.200.143