VxWorks API Reference : Driver Libraries

pciAutoConfigLib

NAME

pciAutoConfigLib - PCI bus scan and resource allocation facility

ROUTINES

pciAutoConfigLibInit( ) - initialize PCI autoconfig library.
pciAutoCfg( ) - Automatically configure all nonexcluded PCI headers.
pciAutoCfgCtl( ) - set or get pciAutoConfigLib options.
pciAutoDevReset( ) - Quiesce a PCI device and reset all writeable status bits.
pciAutoBusNumberSet( ) - Set the primary, secondary, and subordinate bus number.
pciAutoFuncDisable( ) - Disable a specific PCI function.
pciAutoFuncEnable( ) - Perform final configuration and enable a function.
pciAutoGetNextClass( ) - find the next device of specific type from probe list.
pciAutoRegConfig( ) - Assign PCI space to a single PCI base address register.
pciAutoAddrAlign( ) - Align a PCI address and check boundary conditions.
pciAutoConfig( ) - Automatically configure all nonexcluded PCI headers. Obsolete.

DESCRIPTION

This library provides a facility for automated PCI device scanning and configuration on PCI-based systems.
Modern PCI based systems incorporate many peripherals and may span multiple physical bus segments, and these bus segments may be connected via PCI-to-PCI Bridges. Bridges are identified and properly numbered before a recursive scan identifies all resources on the bus implemented by the bridge. Post-scan configuration of the subordinate bus number is performed.
Resource requirements of each device are identified and allocated according to system resource pools that are specified by the BSP Developer. Devices may be conditionally excluded, and interrupt routing information obtained via optional routines provided by the BSP Developer.

GENERAL ALGORITHM

The library must first be initialized by a call to pciAutoConfigLibInit( ). The return value, pCookie, must be passed to each subsequent call from the library. Options can be set using the function pciAutoCfgCtl( ). The available options are described in the documentation for pciAutoCfgCtl( ).
After initialization of the library and configuration of any options, autoconfiguration takes place in two phases. In the first phase, all devices and subordinate busses in a given system are scanned and each device that is found causes an entry to be created in the Probelist or list of devices found during the probe/configuration process.
In the second phase each device that is on the Probelist is checked to see if it has been excluded from automatic configuration by the BSP developer. If a particular function has not been excluded, then it is first disabled. The Base Address Registers of the particular function are read to ascertain the resource requirements of the function. Each resource requirement is checked against available resources in the applicable pool based on size and alignment constraints.
After all functions on the Probelist have been processed, each function and it's appropriate Memory or I/O decoder(s) are enabled for operation.
HOST BRIDGE DETECTION/CONFIGURATION
Note that the PCI Host Bridge is automatically excluded from configuration by the autoconfig routines, as it is often already configured as part of the system bootstrap device configuration.
PCI-PCI BRIDGE DETECTION/CONFIGURATION
Busses are scanned by first writing the primary, secondary, and subordinate bus information into the bridge that implements the bus. Specifically, the primary and secondary bus numbers are set to their corresponding value, and the subordinate bus number is set to 0xFF, because the final number of sub-busses is not known. The subordinate bus number is later updated to indicate the highest numbered sub-bus that was scanned once the scan is complete.
GENERIC DEVICE DETECTION/CONFIGURATION
The autoconfiguration library creates a list of devices during the process of scanning all of the busses in a system. Devices with vendor IDs of 0xFFFF and 0x0000 are skipped. Once all busses have been scanned, all non-excluded devices are then disabled prior to configuration.
Devices that are not excluded will have Resources allocated according to Base Address Registers that are implemented by the device and available space in the applicable resource pool. PCI Natural alignment constraints are adhered to when allocating resources from pools.
Also initialized are the cache line size register and the latency timer. Bus mastering is unconditionally enabled.
If an interrupt assignment routine is registered, then the interrupt pin register of the PCI Configuration space is passed to this routine along with the bus, device, and function number of the device under consideration.
There are two different schemes to determine when the BSP interrupt assignment routine is called by autoconfig. The call is done either only for bus-0 devices or for all devices depending upon how the autoIntRouting is set by the BSP developer (see the section "INTERRUPT ROUTING ACROSS PCI-TO-PCI BRIDGES" below for more details).
The interrupt level number returned by this routine is then written into the interrupt line register of the PCI Configuration Space for subsequent use by device drivers. If no interrupt assignment routine is registered, 0xFF is written into the interrupt line register, specifying an unknown interrupt binding.
Lastly, the functions are enabled with what resources were able to be provided from the applicable resource pools.

RESOURCE ALLOCATION

Resource pools include the 32-bit Prefetchable Memory pool, the 32-bit Non-prefetchable Memory ("MemIO") pool, the 32-bit I/O pool, and the 16-bit I/O allocation pool. The allocation in each pool begins at the specified base address and progresses to higher numbered addresses. Each allocated address adheres to the PCI natural alignment constraints of the given resource requirement specified in the Base Address Register.

DATA STRUCTURES

Data structures are either allocated statically or allocated dynamically, depending on the value of the build macro PCI_AUTO_STATIC_LIST, discussed below. In either case, the structures are initialized by the call to pciAutoConfigLibInit( ).
For ease of upgrading from the older method which used the PCI_SYSTEM structure, the option PCI_SYSTEM_STRUCT_COPY has been implemented. See the in the documentation for for pciAutoCfgCtl( ) for more information.

PCI RESOURCE POOLS

Resources used by pciAutoConfigLib can be divided into two groups.
The first group of information is the Memory and I/O resources, that are available in the system and that autoconfig can use to allocate to functions. These resource pools consist of a base address and size. The base address specified here should be the address relative to the PCI bus. Each of these values in the PCI_SYSTEM data structure is described below:

pciMem32
Specifies the 32-bit prefetchable memory pool base address. Normally, this is given by the BSP constant PCI_MEM_ADRS. It can be set with the pciAutoCfgCtl( ) command PCI_MEM32_LOC_SET.

pciMem32Size
Specifies the 32-bit prefetchable memory pool size. Normally, this is given by the BSP constant PCI_MEM_SIZE. It can be set with the pciAutoCfgCtl( ) command PCI_MEM32_SIZE_SET.

pciMemIo32
Specifies the 32-bit non-prefetchable memory pool base address. Normally, this is given by the BSP constant PCI_MEMIO_ADRS. It can be set with the pciAutoCfgCtl( ) command PCI_MEMIO32_LOC_SET.

pciMemIo32Size
Specifies the 32-bit non-prefetchable memory pool size Normally, this is given by the BSP constant PCI_MEMIO_SIZE. It can be set with the pciAutoCfgCtl( ) command PCI_MEMIO32_SIZE_SET.

pciIo32
Specifies the 32-bit I/O pool base address. Normally, this is given by the BSP constant PCI_IO_ADRS. It can be set with the pciAutoCfgCtl( ) command PCI_IO32_LOC_SET.

pciIo32Size
Specifies the 32-bit I/O pool size. Normally, this is given by the BSP constant PCI_IO_SIZE. It can be set with the pciAutoCfgCtl( ) command PCI_IO32_SIZE_SET.

pciIo16
Specifies the 16-bit I/O pool base address. Normally, this is given by the BSP constant PCI_ISA_IO_ADDR. It can be set with the pciAutoCfgCtl( ) command PCI_IO16_LOC_SET.

pciIo16Size
Specifies the 16-bit I/O pool size. Normally, this is given by the BSP constant PCI_ISA_IO_SIZE. It can be set with the pciAutoCfgCtl( ) command PCI_IO16_SIZE_SET.

PREFETCH MEMORY ALLOCATION

The pciMem32 pointer is assumed to point to a pool of prefetchable PCI memory. If the size of this pool is non-zero, then prefetch memory will be allocated to devices that request it given that there is enough memory in the pool to satisfy the request, and the host bridge or PCI-to-PCI bridge that implements the bus that the device resides on is capable of handling prefetchable memory. If a device requests it, and no prefetchable memory is available or the bridge implementing the bus does not handle prefetchable memory then the request will be attempted from the non-prefetchable memory pool.
PCI-to-PCI bridges are queried as to whether they support prefetchable memory by writing a non-zero value to the prefetchable memory base address register and reading back a non-zero value. A zero value would indicate the the bridge does not support prefetchable memory.

BSP-SPECIFIC ROUTINES

Several routines can be provided by the BSP Developer to customize the degree to which the system can be automatically configured. These routines are normally put into a file called sysBusPci.c in the BSP directory. The trivial cases of each of these routines are shown in the USAGE section below to illustrate the API to the BSP Developer.

DEVICE INCLUSION

Specific devices other than bridges can be excluded from auto configuration and either not used or manually configured later. For more information, see the PCI_INCLUDE_FUNC_SET section in the documentation for pciAutoCfgCtl( ).

INTERRUPT ASSIGNMENT

Interrupt assignment can be specified by the BSP developer by specifying a routine for pciAutoConfigLib to call at the time each device or bridge is configured. See the PCI_INT_ASSIGN_FUNC_SET section in the documentation for pciAutoCfgCtl( ) for more information.

INTERRUPT ROUTING ACROSS PCI-TO-PCI BRIDGES

PCI autoconfig allows use of two interrupt routing strategies for handling devices that reside across a PCI-to-PCI Bridge. The BSP-specific interrupt assignment routine described in the above section is called for all devices that reside on bus 0. For devices residing across a PCI-to-PCI bridge, one of two supported interrupt routing strategies may be selected by setting the PCI_AUTO_INT_ROUTE_SET command using pciAutoCfgCtl( ) to the boolean value TRUE or FALSE:

TRUE
If automatic interrupt routing is set to TRUE, then autoconfig only calls the BSP interrupt routing routine for devices on bus number 0. If a device resides on a higher numbered bus, then a cyclic algorithm is applied to the IRQs that are routed through the bridge. The algorithm is based on computing a route offset that is the device number modulo 4 for every bridge device that is traversed. This offset is used with the device number and interrupt pin register of the device of interest to compute the contents of the interrupt line register.

FALSE
If automatic interrupt routing is set to FALSE, then autoconfig calls the BSP interrupt assignment routine to do all interrupt routing regardless of the bus on which the device resides. The return value represents the contents of the interrupt line register in all cases.

BRIDGE CONFIGURATION

The BSP developer may wish to perform configuration of bridges before and/or after the normal configuration of the bus they reside on. Two routines can be specified for this purpose.
The bridge pre-configuration pass initialization routine is provided so that the BSP Developer can initialize a bridge device prior to the configuration pass on the bus that the bridge implements.
The bridge post-configuration pass initialization routine is provided so that the BSP Developer can initialize the bridge device after the bus that the bridge implements has been enumerated.
These routines are configured by calling pciAutoCfgCtl( ) with the command PCI_BRIDGE_PRE_CONFIG_FUNC_SET and the command PCI_BRIDGE_POST_CONFIG_FUNC_SET, respectively.

HOST BRIDGE CONFIGURATION

The PCI Local Bus Specification, rev 2.1 does not specify the content or initialization requirements of the configuration space of PCI Host Bridges. Due to this fact, no host bridge specific assumptions are made by autoconfig and any PCI Host Bridge initialization that must be done before either scan or configuration of the bus must be done in the BSP. Comments illustrating where this initialization could be called in relation to invoking the pciAutoConfig( ) routine are in the USAGE section below.

LIBRARY CONFIGURATION MACROS

The following four macros can be defined by the BSP Developer in config.h to govern the operation of the autoconfig library.

PCI_AUTO_MAX_FUNCTIONS
Defines the maximum number of functions that can be stored in the probe list during the autoconfiguration pass. The default value for this define is 32, but this may be overridden by defining PCI_AUTO_MAX_FUNCTIONS in config.h.

PCI_AUTO_STATIC_LIST
If defined, then a statically allocated array of size PCI_AUTO_MAX_FUNCTION instances of the PCI_LOC structure will be instantiated.

PCI_AUTO_RECLAIM_LIST
This define may only be used if PCI_AUTO_STATIC_LIST is not defined. If defined, this allows the autoconfig routine to perform a free( ) operation on a dynamically allocated probe list. Note that if PCI_AUTO_RECLAIM_LIST is defined and PCI_AUTO_STATIC_LIST is also, a compiler error will be generated.

USAGE

The following code sample illustrates the usage of the PCI_SYSTEM structure and invocation of the autoconfig library. Note that the example BSP-specific routines are merely stubs. The code in each routine varies by BSP and application.

#include "pciAutoConfigLib.h"

LOCAL PCI_SYSTEM sysParams;

void sysPciAutoConfig (void)
    {
    void * pCookie;

    /* initialize the library */
    pCookie = pciAutoConfigLibInit(NULL);

    /* 32-bit Prefetchable Memory Space */

    pciAutoCfgCtl(pCookie, PCI_MEM32_LOC_SET, PCI_MEM_ADRS);
    pciAutoCfgCtl(pCookie, PCI_MEM32_SIZE_SET, PCI_MEM_SIZE);

    /* 32-bit Non-prefetchable Memory Space */

    pciAutoCfgCtl(pCookie, PCI_MEMIO32_LOC_SET, PCI_MEMIO_ADRS);
    pciAutoCfgCtl(pCookie, PCI_MEMIO32_SIZE_SET, PCI_MEMIO_SIZE);

    /* 16-bit ISA I/O Space */

    pciAutoCfgCtl(pCookie, PCI_IO16_LOC_SET, PCI_ISA_IO_ADRS);
    pciAutoCfgCtl(pCookie, PCI_IO16_SIZE_SET, PCI_ISA_IO_SIZE);

    /* 32-bit PCI I/O Space */

    pciAutoCfgCtl(pCookie, PCI_IO32_LOC_SET, PCI_IO_ADRS);
    pciAutoCfgCtl(pCookie, PCI_IO32_SIZE_SET, PCI_IO_SIZE);

    /* Configuration space parameters */

    pciAutoCfgCtl(pCookie, PCI_MAX_BUS_SET, 0);
    pciAutoCfgCtl(pCookie, PCI_MAX_LAT_ALL_SET, PCI_LAT_TIMER);
    pciAutoCfgCtl(pCookie, PCI_CACHE_SIZE_SET,
                        ( _CACHE_ALIGN_SIZE / 4 ));

    /*
     * Interrupt routing strategy
     * across PCI-to-PCI Bridges
     */

    pciAutoCfgCtl(pCookie, PCI_AUTO_INT_ROUTE_SET, TRUE);

    /* Device inclusion and interrupt routing routines */

    pciAutoCfgCtl(pCookie, PCI_INCLUDE_FUNC_SET,
                        sysPciAutoconfigInclude);
    pciAutoCfgCtl(pCookie, PCI_INT_ASSIGN_FUNC_SET,
                        sysPciAutoconfigIntrAssign);

    /*
     * PCI-to-PCI Bridge Pre-
     * and Post-enumeration init
     * routines
     */

    pciAutoCfgCtl(pCookie, PCI_BRIDGE_PRE_CONFIG_FUNC_SET,
        sysPciAutoconfigPreEnumBridgeInit);
    pciAutoCfgCtl(pCookie, PCI_BRIDGE_POST_CONFIG_FUNC_SET,
        sysPciAutoconfigPostEnumBridgeInit);

    /*
     * Perform any needed PCI Host Bridge
     * Initialization that needs to be done
     * before pciAutoConfig is invoked here
     * utilizing the information in the
     * newly-populated sysParams structure.
     */

    pciAutoCfg (&sysParams);

    /*
     * Perform any needed post-enumeration
     * PCI Host Bridge Initialization here.
     * Information about the actual configuration
     * from the scan and configuration passes
     * can be obtained using the assorted
     * PCI_*_GET commands to pciAutoCfgCtl().
     */

    }

    /*
     * Local BSP-Specific routines
     * supplied by BSP Developer
     */

STATUS sysPciAutoconfigInclude
    (
    PCI_SYSTEM * pSys,                  /* PCI_SYSTEM structure pointer */
    PCI_LOC * pLoc,                     /* pointer to function in question */
    UINT devVend                        /* deviceID/vendorID of device */
    )
    {
    return OK; /* Autoconfigure all devices */
    }

UCHAR sysPciAutoconfigIntrAssign
    (
    PCI_SYSTEM * pSys,                  /* PCI_SYSTEM structure pointer */
    PCI_LOC * pLoc,                     /* pointer to function in question */
    UCHAR pin                           /* contents of PCI int pin register */
    )
    {
    return (UCHAR)0xff;
    }

void sysPciAutoconfigPreEnumBridgeInit
    (
    PCI_SYSTEM * pSys,                  /* PCI_SYSTEM structure pointer */
    PCI_LOC * pLoc,                     /* pointer to function in question */
    UINT devVend                        /* deviceID/vendorID of device */
    )
    {
    return;
    }

void sysPciAutoconfigPostEnumBridgeInit
    (
    PCI_SYSTEM * pSys,                  /* PCI_SYSTEM structure pointer */
    PCI_LOC * pLoc,                     /* pointer to function in question */
    UINT devVend                        /* deviceID/vendorID of device */
    )
    {
    return;
    }

CONFIGURATION SPACE PARAMETERS

The cache line size register specifies the cacheline size in longwords. This register is required when a device can generate a memory write and Invalidate bus cycle, or when a device provides cacheable memory to the system.
Note that in the above example, the macro _CACHE_ALIGN_SIZE is utilized. This macro is implemented for all supported architectures and is located in the architecture.h file in .../target/h/arch/architecture. The value of the macro indicates the cache line size in bytes for the particular architecture. For example, the PowerPC architecture defines this macro to be 32, while the ARM 810 defines it to be 16. The PCI cache line size field and the cacheSize element of the PCI_SYSTEM structure expect to see this quantity in longwords, so the byte value must be divided by 4.

LIMITATIONS

The current version of the autoconfig facility does not support 64-bit prefetchable memory behind PCI-to-PCI bridges, but it does support 32-bit prefetchable memory.
The autoconfig code also depends upon the BSP Developer specifying resource pools that do not conflict with any resources that are being used by statically configured devices.

INCLUDE FILES

pciAutoConfigLib.h

pciAutoConfigLibInit( )

NAME

pciAutoConfigLibInit( ) - initialize PCI autoconfig library.

SYNOPSIS

void * pciAutoConfigLibInit
    (
    void * pArg               /* reserved for future use */
    )

DESCRIPTION

pciAutoConfigLib initialization function.

ERRNO

not set

RETURNS

A cookie for use by subsequent pciAutoConfigLib function
calls.

pciAutoCfg( )

NAME

pciAutoCfg( ) - Automatically configure all nonexcluded PCI headers.

SYNOPSIS

STATUS pciAutoCfg
    (
    void * pCookie            /* cookie returned by pciAutoConfigLibInit() */
    )

DESCRIPTION

Top level function in the PCI configuration process.

CALLING SEQUENCE

pCookie = pciAutoConfigLibInit(NULL);
pciAutoCfgCtl(pCookie, COMMAND, VALUE);
...
pciAutoCfgCtl(pCookie, COMMAND, VALUE);
pciAutoCfg(pCookie);
For ease in converting from the old interface to the new one, a pciAutoCfgCtl( ) command PCI_PSYSTEM_STRUCT_COPY has been implemented. This can be used just like any other pciAutoCfgCtl( ) command, and it will initialize all the values in pSystem. If used, it should be the first call to pciAutoCfgCtl( ).
For a description of the COMMANDs and VALUEs to pciAutoCfgCtl( ), see the pciAutoCfgCtl( ) documentation.
For all nonexcluded PCI functions on all PCI bridges, this routine will automatically configure the PCI configuration headers for PCI devices and subbridges. The fields that are programmed are:

1. Status register.

2. Command Register.

3. Latency timer.

4. Cache Line size.

5. Memory and/or I/O base address and limit registers.

6. Primary, secondary, subordinate bus number (for PCI-PCI bridges).

7. Expansion ROM disable.

8. Interrupt Line.

ALGORITHM

Probe PCI config space and create a list of available PCI functions. Call device exclusion function, if registered, to exclude/include device. Disable all devices before we initialize any. Allocate and assign PCI space to each device. Calculate and set interrupt line value. Initialize and enable each device.

RETURNS

N/A.

pciAutoCfgCtl( )

NAME

pciAutoCfgCtl( ) - set or get pciAutoConfigLib options.

SYNOPSIS

STATUS pciAutoCfgCtl
    (
    void * pCookie,           /* system configuration information */
    int    cmd,               /* command word */
    void * pArg               /* argument for the cmd */
    )

DESCRIPTION

pciAutoCfgCtl( ) can be considered analogous to ioctl( ) calls: the call takes arguments of (1) a pCookie, returned by pciAutoConfigLibInit( ). (2) A command, macros for which are defined in pciAutoConfigLib.h. And, (3) an argument, the type of which depends on the specific command, but will always fit in a pointer variable. Currently, only globally effective commands are implemented.
The commands available are:
PCI_FBB_ENABLE - BOOL * pArg

PCI_FBB_DISABLE - void

PCI_FBB_UPDATE - BOOL * pArg

PCI_FBB_STATUS_GET - BOOL * pArg
Enable and disable the functions which check Fast Back To Back functionality. PCI_FBB_UPDATE is for use with dynamic/HA applications. It will first disable FBB on all functions, then enable FBB on all functions, if appropriate. In HA applications, it should be called any time a card is added or removed. The BOOL pointed to by pArg for PCI_FBB_ENABLE and PCI_FBB_UPDATE will be set to TRUE if all cards allow FBB functionality and FALSE if either any card does not allow FBB functionality or if FBB is disabled. The BOOL pointed to by pArg for PCI_FBB_STATUS_GET will be set to TRUE if PCI_FBB_ENABLE has been called and FBB is enabled, even if FBB is not activated on any card. It will be set to FALSE otherwise.
Note that in the current implementation, FBB will be enabled or disabled on the entire bus. If any device anywhere on the bus cannot support FBB, then it is not enabled, even if specific sub-busses could support it.

PCI_MAX_LATENCY_FUNC_SET - FUNCPTR * pArg
This routine will be called for each function present on the bus when discovery takes place. The routine must accept four arguments, specifying bus, device, function, and a user-supplied argument of type void *. See PCI_MAX_LATENCY_ARG_SET. The routine should return a UINT8 value, which will be put into the MAX_LAT field of the header structure. The user supplied routine must return a valid value each time it is called. There is no mechanism for any ERROR condition, but a default value can be returned in such a case. Default = NULL.

PCI_MAX_LATENCY_ARG_SET - void * pArg
When the routine specified in PCI_MAX_LATENCY_FUNC_SET is called, this will be passed to it as the fourth argument.

PCI_MAX_LAT_ALL_SET - int pArg
Specifies a constant max latency value for all cards, if no function has been specified with PCI_MAX_LATENCY_FUNC_SET..

PCI_MAX_LAT_ALL_GET - UINT * pArg
Retrieves the value of max latency for all cards, if no function has been specified with PCI_MAX_LATENCY_FUNC_SET. Otherwise, the integer pointed to by pArg is set to the value 0xffffffff.

PCI_MSG_LOG_SET - FUNCPTR * pArg
The argument specifies a routine will be called to print warning or error messages from pciAutoConfigLib if logMsg( ) has not been initialized at the time pciAutoConfigLib is used. The specified routine must accept arguments in the same format as logMsg( ), but it does not necessarily need to print the actual message. An example of this routine is presented below, which saves the message into a safe memory space and turns on an LED. This command is useful for BSPs which call pciAutoCfg( ) before message logging is enabled. Note that after logMsg( ) is configured, output will go to logMsg( ) even if this command has been called. Default = NULL.
/* sample PCI_MSG_LOG_SET function */
int pciLogMsg(char *fmt,int a1,int a2,int a3,int a4,int a5,int a6)
    {
    sysLedOn(4);
    return(sprintf(sysExcMsg,fmt,a1,a2,a3,a4,a5,a6));
    }
PCI_MAX_BUS_GET - int * pArg
During autoconfiguration, the library will maintain a counter with the highest numbered bus. This can be retrieved by
pciAutoCfgCtl(pCookie, PCI_MAX_BUS_GET, &maxBus)
PCI_CACHE_SIZE_SET - int pArg
Sets the pci cache line size to the specified value. See CONFIGURATION SPACE PARAMETERS in the pciAutoConfigLib documentation for more details.

PCI_CACHE_SIZE_GET - int * pArg
Retrieves the value of the pci cache line size.

PCI_AUTO_INT_ROUTE_SET - BOOL pArg
Enables or disables automatic interrupt routing across bridges during the autoconfig process. See "INTERRUPT ROUTING ACROSS PCI-TO-PCI BRIDGES" in the pciAutoConfigLib documentation for more details.

PCI_AUTO_INT_ROUTE_GET - BOOL * pArg
Retrieves the status of automatic interrupt routing.

PCI_MEM32_LOC_SET - UINT32 pArg
Sets the base address of the PCI 32-bit memory space. Normally, this is given by the BSP constant PCI_MEM_ADRS.

PCI_MEM32_SIZE_SET - UINT32 pArg
Sets the maximum size to use for the PCI 32-bit memory space. Normally, this is given by the BSP constant PCI_MEM_SIZE.

PCI_MEM32_SIZE_GET - UINT32 * pArg
After autoconfiguration has been completed, this retrieves the actual amount of space which has been used for the PCI 32-bit memory space.

PCI_MEMIO32_LOC_SET - UINT32 pArg
Sets the base address of the PCI 32-bit non-prefetch memory space. Normally, this is given by the BSP constant PCI_MEMIO_ADRS.

PCI_MEMIO32_SIZE_SET - UINT32 pArg
Sets the maximum size to use for the PCI 32-bit non-prefetch memory space. Normally, this is given by the BSP constant PCI_MEMIO_SIZE.

PCI_MEMIO32_SIZE_GET - UINT32 * pArg
After autoconfiguration has been completed, this retrieves the actual amount of space which has been used for the PCI 32-bit non-prefetch memory space.

PCI_IO32_LOC_SET - UINT32 pArg
Sets the base address of the PCI 32-bit I/O space. Normally, this is given by the BSP constant PCI_IO_ADRS.

PCI_IO32_SIZE_SET - UINT32 pArg
Sets the maximum size to use for the PCI 32-bit I/O space. Normally, this is given by the BSP constant PCI_IO_SIZE.

PCI_IO32_SIZE_GET - UINT32 * pArg
After autoconfiguration has been completed, this retrieves the actual amount of space which has been used for the PCI 32-bit I/O space.

PCI_IO16_LOC_SET - UINT32 pArg
Sets the base address of the PCI 16-bit I/O space. Normally, this is given by the BSP constant PCI_ISA_IO_ADRS

PCI_IO16_SIZE_SET - UINT32 pArg
Sets the maximum size to use for the PCI 16-bit I/O space. Normally, this is given by the BSP constant PCI_ISA_IO_SIZE

PCI_IO16_SIZE_GET - UINT32 * pArg
After autoconfiguration has been completed, this retrieves the actual amount of space which has been used for the PCI 16-bit I/O space.

PCI_INCLUDE_FUNC_SET - FUNCPTR * pArg
The device inclusion routine is specified by assigning a function pointer with the PCI_INCLUDE_FUNC_SET pciAutoCfgCtl( ) command:
pciAutoCfgCtl(pSystem, PCI_INCLUDE_FUNC_SET,sysPciAutoconfigInclude);
This optional user-supplied routine takes as input both the bus-device-function tuple, and a 32-bit quantity containing both the PCI vendorID and deviceID of the function. The function prototype for this function is shown below:
STATUS sysPciAutoconfigInclude
    (
    PCI_SYSTEM *pSys,
    PCI_LOC *pLoc,
    UINT devVend
    );
This optional user-specified routine is called by PCI AutoConfig for each and every function encountered in the scan phase. The BSP developer may use any combination of the input data to ascertain whether a device is to be excluded from the autoconfig process. The exclusion routine then returns ERROR if a device is to be excluded, and OK if a device is to be included in the autoconfiguration process.
Note that PCI-to-PCI Bridges may not be excluded, regardless of the value returned by the BSP device inclusion routine. The return value is ignored for PCI-to-PCI bridges.
The Bridge device will be always be configured with proper primary, secondary, and subordinate bus numbers in the device scanning phase and proper I/O and Memory aperture settings in the configuration phase of autoconfig regardless of the value returned by the BSP device inclusion routine.
PCI_INT_ASSIGN_FUNC_SET - FUNCPTR * pArg
The interrupt assignment routine is specified by assigning a function pointer with the PCI_INCLUDE_FUNC_SET pciAutoCfgCtl( ) command:
pciAutoCfgCtl(pCookie, PCI_INT_ASSIGN_FUNC_SET, sysPciAutoconfigIntrAssign);
This optional user-specified routine takes as input both the bus-device-function tuple, and an 8-bit quantity containing the contents of the interrupt Pin register from the PCI configuration header of the device under consideration. The interrupt pin register specifies which of the four PCI Interrupt request lines available are connected. The function prototype for this function is shown below:
UCHAR sysPciAutoconfigIntrAssign
    (
    PCI_SYSTEM *pSys,
    PCI_LOC *pLoc,
    UCHAR pin
    );
This routine may use any combination of these data to ascertain the interrupt level. This value is returned from the function, and will be programmed into the interrupt line register of the function's PCI configuration header. In this manner, device drivers may subsequently read this register in order to calculate the appropriate interrupt vector which to attach an interrupt service routine.
PCI_BRIDGE_PRE_CONFIG_FUNC_SET - FUNCPTR * pArg
The bridge pre-configuration pass initialization routine is provided so that the BSP Developer can initialize a bridge device prior to the configuration pass on the bus that the bridge implements. This routine is specified by calling pciAutoCfgCtl( ) with the PCI_BRIDGE_PRE_CONFIG_FUNC_SET command:
pciAutoCfgCtl(pCookie, PCI_BRIDGE_PRE_CONFIG_FUNC_SET,
        sysPciAutoconfigPreEnumBridgeInit);
This optional user-specified routine takes as input both the bus-device-function tuple, and a 32-bit quantity containing both the PCI deviceID and vendorID of the device. The function prototype for this function is shown below:
STATUS sysPciAutoconfigPreEnumBridgeInit
    (
    PCI_SYSTEM *pSys,
    PCI_LOC *pLoc,
    UINT devVend
    );
This routine may use any combination of these input data to ascertain any special initialization requirements of a particular type of bridge at a specified geographic location.
PCI_BRIDGE_POST_CONFIG_FUNC_SET - FUNCPTR * pArg
The bridge post-configuration pass initialization routine is provided so that the BSP Developer can initialize the bridge device after the bus that the bridge implements has been enumerated. This routine is specified by calling pciAutoCfgCtl( ) with the PCI_BRIDGE_POST_CONFIG_FUNC_SET command
pciAutoCfgCtl(pCookie, PCI_BRIDGE_POST_CONFIG_FUNC_SET,
        sysPciAutoconfigPostEnumBridgeInit);
This optional user-specified routine takes as input both the bus-device-function tuple, and a 32-bit quantity containing both the PCI deviceID and vendorID of the device. The function prototype for this function is shown below:
STATUS sysPciAutoconfigPostEnumBridgeInit
    (
    PCI_SYSTEM *pSys,
    PCI_LOC *pLoc,
    UINT devVend
    );
This routine may use any combination of these input data to ascertain any special initialization requirements of a particular type of bridge at a specified geographic location.
PCI_ROLLCALL_FUNC_SET - FUNCPTR * pArg
The specified routine will be configured as a roll call routine.
If a roll call routine has been configured, before any configuration is actually done, the roll call routine is called repeatedly until it returns TRUE. A return value of TRUE indicates that either (1) the specified number and type of devices named in the roll call list have been found during PCI bus enumeration or (2) the timeout has expired without finding all of the specified number and type of devices. In either case, it is assumed that all of the PCI devices which are going to appear on the busses have appeared and we can proceed with PCI bus configuration.

PCI_TEMP_SPACE_SET - char * pArg
This command is not currently implemented. It allows the user to set aside memory for use during pciAutoConfigLib execution, e.g. memory set aside using USER_RESERVED_MEM. After PCI configuration has been completed, the memory can be added to the system memory pool using memAddToPool( ).

PCI_MINIMIZE_RESOURCES
This command is not currently implemented. It specifies that pciAutoConfigLib minimize requirements for memory and I/O space.

PCI_PSYSTEM_STRUCT_COPY - PCI_SYSTEM * pArg
This command has been added for ease of converting from the old interface to the new one. This will set each value as specified in the pSystem structure. If the PCI_SYSTEM structure has already been filled, the pciAutoConfig(pSystem) call can be changed to:
void *pCookie;
pCookie = pciAutoConfigLibInit(NULL);
pciAutoCfgCtl(pCookie, PCI_PSYSTEM_STRUCT_COPY, (void *)pSystem);
pciAutoCfgFunc(pCookie);
The fields of the PCI_SYSTEM structure are defined below. For more information about each one, see the paragraphs above and the documentation for pciAutoConfigLib.
pciMem32
Specifies the 32-bit prefetchable memory pool base address.

pciMem32Size
Specifies the 32-bit prefetchable memory pool size.

pciMemIo32
Specifies the 32-bit non-prefetchable memory pool base address.

pciMemIo32Size
Specifies the 32-bit non-prefetchable memory pool size

pciIo32
Specifies the 32-bit I/O pool base address.

pciIo32Size
Specifies the 32-bit I/O pool size.

pciIo16
Specifies the 16-bit I/O pool base address.

pciIo16Size
Specifies the 16-bit I/O pool size.

includeRtn
Specifies the device inclusion routine.

intAssignRtn
Specifies the interrupt assignment routine.

autoIntRouting
Can be set to TRUE to configure pciAutoConfig( ) only to call the BSP interrupt routing routine for devices on bus number 0. Setting autoIntRoutine to FALSE will configure pciAutoConfig( ) to call the BSP interrupt routing routine for every device regardless of the bos on which the device resides.

bridgePreInit
Specifies the bridge initialization routine to call before initializing devices on the bus that the bridge implements.

bridgePostInit
Specifies the bridge initialization routine to call after initializing devices on the bus that the bridge implements.

ERRNO

EINVAL if pCookie is not NULL or cmd is not recognized

RETURNS

OK, or ERROR if the command or argument is invalid.

pciAutoDevReset( )

NAME

pciAutoDevReset( ) - Quiesce a PCI device and reset all writeable status bits.

SYNOPSIS

STATUS pciAutoDevReset
    (
    PCI_LOC * pPciLoc         /* device to be reset */
    )

DESCRIPTION

This routine turns off a PCI device by disabling the Memory decoders, I/O decoders, and Bus Master capability. The routine also resets all writeable status bits in the status word that follows the command word sequentially in PCI config space by performing a longword access.

RETURNS

OK, always.

pciAutoBusNumberSet( )

NAME

pciAutoBusNumberSet( ) - Set the primary, secondary, and subordinate bus number.

SYNOPSIS

STATUS pciAutoBusNumberSet
    (
    PCI_LOC * pPciLoc,        /* device affected */
    UINT      primary,        /* primary bus specification */
    UINT      secondary,      /* secondary bus specification */
    UINT      subordinate     /* subordinate bus specification */
    )

DESCRIPTION

This routine sets the primary, secondary, and subordinate bus numbers for a device that implements the Type 1 PCI Configuration Space Header.
This routine has external visibility to enable it to be used by BSP Developers for initialization of PCI Host Bridges that may implement registers similar to those found in the Type 1 Header.

RETURNS

OK, always.

pciAutoFuncDisable( )

NAME

pciAutoFuncDisable( ) - Disable a specific PCI function.

SYNOPSIS

void pciAutoFuncDisable
    (
    PCI_LOC * pPciFunc        /* input: Pointer to PCI function struct */
    )

DESCRIPTION

This routine clears the I/O, mem, master, & ROM space enable bits for a single PCI function.
The PCI spec says that devices should normally clear these by default after reset but in actual practice, some PCI devices do not fully comply. This routine ensures that the devices have all been disabled before configuration is started.

RETURNS

N/A.

pciAutoFuncEnable( )

NAME

pciAutoFuncEnable( ) - Perform final configuration and enable a function.

SYNOPSIS

void pciAutoFuncEnable
    (
    PCI_SYSTEM * pSys,        /* for backwards compatibility */
    PCI_LOC *    pFunc        /* input: Pointer to PCI function structure */
    )

DESCRIPTION

Depending upon whether the device is included, this routine initializes a single PCI function as follows:
Initialize the cache line size register Initialize the PCI-PCI bridge latency timers Enable the master PCI bit for non-display devices Set the interrupt line value with the value from the BSP.

RETURNS

N/A.

pciAutoGetNextClass( )

NAME

pciAutoGetNextClass( ) - find the next device of specific type from probe list.

SYNOPSIS

STATUS pciAutoGetNextClass
    (
    PCI_SYSTEM * pSys,        /* for backwards compatibility */
    PCI_LOC *    pPciFunc,    /* output: Contains the BDF of the device found */
    UINT *       index,       /* Zero-based device instance number */
    UINT         pciClass,    /* class code field from the PCI header */
    UINT         mask         /* mask is ANDed with the class field */
    )

DESCRIPTION

The function uses the probe list which was built during the probing process. Using configuration accesses, it searches for the occurrence of the device subject to the class and mask restrictions outlined below. Setting class to zero and mask to zero allows searching the entire set of devices found regardless of class.

RETURNS

TRUE if a device was found, else FALSE.

pciAutoRegConfig( )

NAME

pciAutoRegConfig( ) - Assign PCI space to a single PCI base address register.

SYNOPSIS

UINT pciAutoRegConfig
    (
    PCI_SYSTEM * pSys,        /* backwards compatibility */
    PCI_LOC *    pPciFunc,    /* Pointer to function in device list */
    UINT         baseAddr,    /* Offset of base PCI address */
    UINT         nSize,       /* Size and alignment requirements */
    UINT         addrInfo     /* PCI address type information */
    )

DESCRIPTION

This routine allocates and assigns PCI space (either memory or I/O) to a single PCI base address register.

RETURNS

Returns (1) if BAR supports mapping anywhere in 64-bit address space. Returns (0) otherwise.

pciAutoAddrAlign( )

NAME

pciAutoAddrAlign( ) - Align a PCI address and check boundary conditions.

SYNOPSIS

STATUS pciAutoAddrAlign
    (
    UINT32   base,            /* base of available memory */
    UINT32   limit,           /* last addr of available memory */
    UINT32   reqSize,         /* required size */
    UINT32 * pAlignedBase     /* output: aligned address put here */
    )

DESCRIPTION

RETURNS

OK, or ERROR if available memory has been exceeded.

pciAutoConfig( )

NAME

pciAutoConfig( ) - Automatically configure all nonexcluded PCI headers. Obsolete.

SYNOPSIS

void pciAutoConfig
    (
    PCI_SYSTEM * pSystem      /* PCI system to configure */
    )

DESCRIPTION

This routine is obsolete. It is included for backward compatibility only. It is recommended that you use the pciAutoCfg( ) interface instead of this one.
Top level function in the PCI configuration process.
For all nonexcluded PCI functions on all PCI bridges, this routine will automatically configure the PCI configuration headers for PCI devices and subbridges. The fields that are programmed are:

1. Status register.

2. Command Register.

3. Latency timer.

4. Cache Line size.

5. Memory and/or I/O base address and limit registers.

6. Primary, secondary, subordinate bus number (for PCI-PCI bridges).

7. Expansion ROM disable.

8. Interrupt Line.

ALGORITHM

Probe PCI config space and create a list of available PCI functions. Call device exclusion function, if registered, to exclude/include device. Disable all devices before we initialize any. Allocate and assign PCI space to each device. Calculate and set interrupt line value. Initialize and enable each device.

RETURNS

N/A.

1.	Status register.
2.	Command Register.
3.	Latency timer.
4.	Cache Line size.
5.	Memory and/or I/O base address and limit registers.
6.	Primary, secondary, subordinate bus number (for PCI-PCI bridges).
7.	Expansion ROM disable.
8.	Interrupt Line.

pciAutoConfigLib

NAME

ROUTINES

DESCRIPTION

GENERAL ALGORITHM

RESOURCE ALLOCATION

DATA STRUCTURES

PCI RESOURCE POOLS

PREFETCH MEMORY ALLOCATION

BSP-SPECIFIC ROUTINES

DEVICE INCLUSION

INTERRUPT ASSIGNMENT

INTERRUPT ROUTING ACROSS PCI-TO-PCI BRIDGES

BRIDGE CONFIGURATION

HOST BRIDGE CONFIGURATION

LIBRARY CONFIGURATION MACROS

USAGE

CONFIGURATION SPACE PARAMETERS

LIMITATIONS

INCLUDE FILES

SEE ALSO

pciAutoConfigLibInit( )

NAME

SYNOPSIS

DESCRIPTION

ERRNO

RETURNS

SEE ALSO

pciAutoCfg( )

NAME

SYNOPSIS

DESCRIPTION

CALLING SEQUENCE

ALGORITHM

RETURNS

SEE ALSO

pciAutoCfgCtl( )

NAME

SYNOPSIS

DESCRIPTION

ERRNO

RETURNS

SEE ALSO

pciAutoDevReset( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoBusNumberSet( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoFuncDisable( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoFuncEnable( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoGetNextClass( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoRegConfig( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

pciAutoAddrAlign( )