pciautoconfiglib.c

LoPEC Early Access VxWorks BSP

/* pciAutoConfigLib.c - PCI bus scan and resource allocation facility */

/* Copyright 1997-2001 Motorola, Inc. All Rights Reserved */
/* Copyright 1997-2001 Wind River Systems, Inc. All Rights Reserved */

/*
modification history
--------------------
01t,10aug00,wef  Removed redundant call to pciAutoListCreate in 
		 pciAutoConfig: SPR 33636
01s,07jun00,dmw  Update to PrPMC name convention.
01r,03feb00,rhv  Making pciAutoIoAlloc, pciAutoMemAlloc and pciAutoIntAssign
                 externally callable. Modifying PCI-to-PCI bridge setup to
                 open Memory I/O window for Slave-Mode PrPMC support. Setting up
                 PCI interrupt routing earlier to support interrupt assignment
                 outside of pciAutoFuncEnable as required by Slave-Mode PrPMC
                 support.
01q,04oct99,scb  Fix broken roll call, interrupt routing. SPRs 29158, 31254
01p,20jul99,tm   AddrAlign ret assign before base+align+alloc check (SPR 28243)
01o,10jun99,scb  Update to latest WRS version.
01n,08jun99,scb  Moved from T1 base to T2 base.
01m,13apr99,djs  Made FuncEnable, FuncDisable, RegConfig global (SPR 26484)
01l,12apr99,scb  added roll call capability
01k,05may99,tm   Moved bridge Prefetch detection/attribute set to probe phase
                 Prefetch enable gated by parent bridge prefetch support
                 Added pciAutoAddrAlign to handle address alignment/checking
		 BAR scanning now not stopped at first unimplemented BAR
01j,30mar99,dat  changed class to pciClass (SPR 25312)
01i,02mar99,tm   Fixed Prefetch bridge attrib (SPR 25396) / doc cleanup
01h,10feb99,tm   Prefetch bit is now gated correctly from BARs (SPR 25033)
01g,21jan99,tm   Fixed attribute inheritance mask (SPR 24605)
01f,18nov98,tm   Limit non-bus-0 I/O addresses to 16-bit decode (SPR 23428)
01e,23oct98,dat  fixed CSR accesses to not reset status.
01d,30jul98,tm   more code review revisions / Prefetchable Memory support added
01c,01jul98,tm   code review revisions / Raven-like host bridge init removed 
                   Cyclic interrupt routing for non-bus0 devices added
		   Corrected non-spec existence check (SPR 21934)
01b,20mar98,tm   adapted from pciAutoLib
01a,05Jan98,scb	 written based on Motorola bug code
*/

/*
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

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) is 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 also 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

In order to utilize the PCI Autoconfig facility, the user instantiates a 
data structure that describes resource pools that the autoconfig facility 
uses.  This structure is the PCI_SYSTEM structure, and has two groups of
information that are specifiable by the BSP Developer. 

PCI RESOURCE POOLS

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:

.IP "pciMem32" 16
Specifies the 32-bit prefetchable memory pool base address. 
Normally, this is given by the BSP constant PCI_MEM_ADRS

.IP "pciMem32Size" 16
Specifies the 32-bit prefetchable memory pool size.
Normally, this is given by the BSP constant PCI_MEM_SIZE

.IP "pciMemIo32" 16
Specifies the 32-bit non-prefetchable memory pool base address.
Normally, this is given by the BSP constant PCI_MEMIO_ADRS

.IP "pciMemIo32Size" 16
Specifies the 32-bit non-prefetchable memory pool size
Normally, this is given by the BSP constant PCI_MEMIO_SIZE

.IP "pciIo32" 16
Specifies the 32-bit I/O pool base address. 
Normally, this is given by the BSP constant PCI_IO_ADRS

.IP "pciIo32Size" 16
Specifies the 32-bit I/O pool size. 
Normally, this is given by the BSP constant PCI_IO_SIZE

.IP "pciIo16" 16
Specifies the 16-bit I/O pool base address. 
Normally, this is given by the BSP constant PCI_ISA_IO_ADDR

.IP "pciIo16Size" 16
Specifies the 16-bit I/O pool size. 
Normally, this is given by the BSP constant PCI_ISA_IO_SIZE

.LP

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

Four 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

The device inclusion routine is specified by assigning a function pointer
to the includeRtn member of the PCI_SYSTEM structure: 

.CS
    sysParams.includeRtn = sysPciAutoconfigInclude;
.CE

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:

.CS
    STATUS sysPciAutoconfigInclude
	(
	PCI_SYSTEM *pSys,
	PCI_LOC *pLoc, 
	UINT devVend
	);
.CE

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.

INTERRUPT ASSIGNMENT

The interrupt assignment routine is specified by assigning a function pointer
to the intAssignRtn member of the PCI_SYSTEM structure: 

.CS
    sysParams.intAssignRtn = sysPciAutoconfigIntrAssign;
.CE

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:

.CS
    STATUS sysPciAutoconfigIntrAssign
	(
	PCI_SYSTEM *pSys,
	PCI_LOC *pLoc, 
	UCHAR pin
	);
.CE

This routine may use any combination of these data to ascertain the 
interrupt level. This value is returned from the function, and should 
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.

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 autoIntRouting variable in the PCI_SYSTEM structure to the boolean
value TRUE or FALSE:

.IP "TRUE" 12
If autoIntRouting 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.

.IP "FALSE" 12
If autoIntRouting 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 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 assigning a function pointer to the bridgePreInit
member of the PCI_SYSTEM structure: 

.CS
    sysParams.bridgePreInit
	= sysPciAutoconfigPreEnumBridgeInit;
.CE

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:

.CS
    STATUS sysPciAutoconfigPreEnumBridgeInit 
	(
	PCI_SYSTEM *pSys,
	PCI_LOC *pLoc, 
	UINT devVend
	);
.CE

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.

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 assigning a function pointer to the bridgePostInit
member of the PCI_SYSTEM structure: 

.CS
    sysParams.bridgePostInit
	= sysPciAutoconfigPostEnumBridgeInit;
.CE

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:

.CS
     STATUS sysPciAutoconfigPostEnumBridgeInit 
	(
	PCI_SYSTEM *pSys,
	PCI_LOC *pLoc, 
	UINT devVend
	);
.CE

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.

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 auto-
config 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.

.IP "PCI_AUTO_MAX_FUNCTIONS" 32
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.

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

.IP "PCI_AUTO_RECLAIM_LIST" 32
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.

.LP

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.

.CS

#include "pciAutoConfigLib.h"

LOCAL PCI_SYSTEM sysParams;

void sysPciAutoConfig (void)
    {

    /@ 32-bit Prefetchable Memory Space @/

    sysParams.pciMem32 = PCI_MEM_ADRS;
    sysParams.pciMem32Size = PCI_MEM_SIZE;

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