/* 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 3363601s,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, 3125401p,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 capability01k,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 BAR01j,30mar99,dat  changed class to pciClass (SPR 25312)01i,02mar99,tm   Fixed Prefetch bridge attrib (SPR 25396) / doc cleanup01h,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 added01c,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 pciAutoLib01a,05Jan98,scb	 written based on Motorola bug code*//*DESCRIPTIONThis library provides a facility for automated PCI device scanning andconfiguration on PCI-based systems.Modern PCI based systems incorporate many peripherals and may span multiplephysical bus segments, and these bus segments may be connected viaPCI-to-PCI Bridges. Bridges are identified and properly numberedbefore a recursive scan identifies all resources on the bus implementedby the bridge. Post-scan configuration of the subordinate bus numberis performed. Resource requirements of each device are identified and allocated accordingto system resource pools that are specified by the BSP Developer. Devices maybe conditionally excluded, and interrupt routing information obtained viaoptional routines provided by the BSP Developer.GENERAL ALGORITHMAutoconfiguration takes place in two phases. In the first phase, alldevices 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 seeif 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 ascertainthe resource requirements of the function. Each resource requirement ischecked against available resources in the applicable pool based on sizeand alignment constraints.After all functions on the Probelist have been processed, each functionand it's appropriate Memory or I/O decoder(s) is enabled for operation.HOST BRIDGE DETECTION/CONFIGURATIONNote that the PCI Host Bridge is automatically excluded from configurationby the autoconfig routines as it is often already configured as part ofthe system bootstrap device configuration.PCI-PCI BRIDGE DETECTION/CONFIGURATIONBusses are scanned by first writing the primary, secondary, and subordinatebus 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 toindicate the highest numbered sub-bus that was scanned once the scan iscomplete. GENERIC DEVICE DETECTION/CONFIGURATIONThe autoconfiguration library creates a list of devices during the processof scanning all of the busses in a system.  Devices with vendorIDs 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 accordingto Base Address Registers that are implemented by the device and available space in the applicable resource pool. PCI 'Natural' alignmentconstraints 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 interruptpin register of the PCI Configuration space is passed to this routinealong with the bus, device, and function number of the device underconsideration.There are two different schemes to determine when the BSP interruptassignment routine is called by autoconfig. The call is done eitheronly for bus-0 devices or for all devices depending upon how theautoIntRouting 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 writteninto the interrupt line register of the PCI Configuration Space forsubsequent use by device drivers. If no interrupt assignment routineis 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 beprovided from the applicable resource pools.RESOURCE ALLOCATIONResource 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 atthe specified base address and progresses to higher numbered addresses. Each allocated address adheres to the PCI 'natural' alignment constraintsof the given resource requirement specified in the Base Address Register.DATA STRUCTURESIn 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 ofinformation that are specifiable by the BSP Developer. PCI RESOURCE POOLSThe first group of information is the Memory and I/O resources, that areavailable 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 thesevalues in the PCI_SYSTEM data structure is described below:.IP "pciMem32" 16Specifies the 32-bit prefetchable memory pool base address. Normally, this is given by the BSP constant PCI_MEM_ADRS.IP "pciMem32Size" 16Specifies the 32-bit prefetchable memory pool size.Normally, this is given by the BSP constant PCI_MEM_SIZE.IP "pciMemIo32" 16Specifies the 32-bit non-prefetchable memory pool base address.Normally, this is given by the BSP constant PCI_MEMIO_ADRS.IP "pciMemIo32Size" 16Specifies the 32-bit non-prefetchable memory pool sizeNormally, this is given by the BSP constant PCI_MEMIO_SIZE.IP "pciIo32" 16Specifies the 32-bit I/O pool base address. Normally, this is given by the BSP constant PCI_IO_ADRS.IP "pciIo32Size" 16Specifies the 32-bit I/O pool size. Normally, this is given by the BSP constant PCI_IO_SIZE.IP "pciIo16" 16Specifies the 16-bit I/O pool base address. Normally, this is given by the BSP constant PCI_ISA_IO_ADDR.IP "pciIo16Size" 16Specifies the 16-bit I/O pool size. Normally, this is given by the BSP constant PCI_ISA_IO_SIZE.LPPREFETCH MEMORY ALLOCATIONThe pciMem32 pointer is assumed to point to a pool of prefetchable PCImemory. If the size of this pool is non-zero, then prefetch memory willbe 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 iscapable of handling prefetchable memory. If a device requests it, and no prefetchable memory is available or the bridge implementing the busdoes not handle prefetchable memory then the request will be attemptedfrom the non-prefetchable memory pool. PCI-to-PCI bridges are queried as to whether they support prefetchablememory by writing a non-zero value to the prefetchable memory baseaddress register and reading back a non-zero value. A zero value wouldindicate the the bridge does not support prefetchable memory.BSP-SPECIFIC ROUTINESFour routines can be provided by the BSP Developer to customize the degreeto which the system can be automatically configured.  These routines arenormally put into a file called sysBusPci.c in the BSP directory. The trivialcases of each of these routines are shown in the USAGE section below toillustrate the API to the BSP Developer. DEVICE INCLUSIONThe device inclusion routine is specified by assigning a function pointerto the includeRtn member of the PCI_SYSTEM structure: .CS    sysParams.includeRtn = sysPciAutoconfigInclude;.CEThis optional user-supplied routine takes as input both thebus-device-function tuple, and a 32-bit quantity containing both the PCIvendorID and deviceID of the function. The function prototype for thisfunction is shown below:.CS    STATUS sysPciAutoconfigInclude	(	PCI_SYSTEM *pSys,	PCI_LOC *pLoc, 	UINT devVend	);.CEThis optional user-specified routine is called by PCI AutoConfig for each and every function encountered in the scan phase. The BSP developermay use any combination of the input data to ascertain whether a deviceis 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 valuereturned by the BSP device inclusion routine. The return value is ignored forPCI-to-PCI bridges. The Bridge device will be always be configured with proper primary,secondary, and subordinate bus numbers in the device scanning phaseand proper I/O and Memory aperture settings in the configuration phaseof autoconfig regardless of the value returned by the BSP device inclusion routine.INTERRUPT ASSIGNMENTThe interrupt assignment routine is specified by assigning a function pointerto the intAssignRtn member of the PCI_SYSTEM structure: .CS    sysParams.intAssignRtn = sysPciAutoconfigIntrAssign;.CEThis optional user-specified routine takes as input both the bus-device-functiontuple, 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 requestlines available are connected.  The function prototype for this function is shown below:.CS    STATUS sysPciAutoconfigIntrAssign	(	PCI_SYSTEM *pSys,	PCI_LOC *pLoc, 	UCHAR pin	);.CEThis 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 BRIDGESPCI Autoconfig allows use of two interrupt routing strategies for handlingdevices that reside across a PCI-to-PCI Bridge. The BSP-specific interruptassignment routine described in the above section is called for all devicesthat reside on bus 0. For devices residing across a PCI-to-PCI bridge, oneof two supported interrupt routing strategies may be selected by settingthe autoIntRouting variable in the PCI_SYSTEM structure to the booleanvalue TRUE or FALSE:.IP "TRUE" 12If autoIntRouting is set to TRUE, then autoconfig only calls the BSP interrupt routing routine for devices on bus number 0. If a device resideson a higher numbered bus, then a cyclic algorithm is applied to the IRQsthat 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 interruptpin register of the device of interest to compute the contents of theinterrupt line register..IP "FALSE" 12If autoIntRouting is set to FALSE, then autoconfig calls the BSPinterrupt assignment routine to do all interrupt routing regardlessof the bus on which the device resides. The return value represents thecontents of the interrupt line register in all cases.BRIDGE CONFIGURATIONThe bridge pre-configuration pass initialization routine is providedso that the BSP Developer can initialize a bridge device prior to theconfiguration pass on the bus that the bridge implements. This routineis specified by assigning a function pointer to the bridgePreInitmember of the PCI_SYSTEM structure: .CS    sysParams.bridgePreInit	= sysPciAutoconfigPreEnumBridgeInit;.CEThis optional user-specified routine takes as input both the bus-device-functiontuple, 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	);.CEThis 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 providedso that the BSP Developer can initialize the bridge device after the busthat the bridge implements has been enumerated. This routineis specified by assigning a function pointer to the bridgePostInitmember of the PCI_SYSTEM structure: .CS    sysParams.bridgePostInit	= sysPciAutoconfigPostEnumBridgeInit;.CEThis optional user-specified routine takes as input both the bus-device-functiontuple, 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	);.CEThis 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 CONFIGURATIONThe 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 eitherscan or configuration of the bus must be done in the BSP. Commentsillustrating where this initialization could be called in relation to invoking the pciAutoConfig() routine are in the USAGE section below.LIBRARY CONFIGURATION MACROSThe following four macros can be defined by the BSP Developer in config.hto govern the operation of the autoconfig library..IP "PCI_AUTO_MAX_FUNCTIONS" 32Defines the maximum number of functions that can be stored in the probe listduring 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" 32If defined, then a statically allocated array of size PCI_AUTO_MAX_FUNCTIONinstances of the PCI_LOC structure will be instantiated. .IP "PCI_AUTO_RECLAIM_LIST" 32This define may only be used if PCI_AUTO_STATIC_LIST is not defined. Ifdefined, this allows the autoconfig routine to perform a free() operation on a dynamically allocated probe list. Note that if PCI_AUTO_RECLAIM_LISTis defined and PCI_AUTO_STATIC_LIST is also, a compiler error will be generated..LPUSAGEThe following code sample illustrates the usage of the PCI_SYSTEM structureand invocation of the autoconfig library.  Note that the example BSP-specificroutines 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 @/