10. PCI Host Bridge¶

10.1. PCI Host Bridge Overview¶

This specification defines the core code and services that are required for an implementation of the PCI Host Bridge Resource Allocation Protocol. This protocol is used by a PCI bus driver to program the PCI host bridge and configure the root PCI buses. The registers inside the PCI host bridge that control root PCI bus configuration are not governed by the PCI specification and vary from chipset to chipset. The PCI Host Bridge Resource Allocation Protocol is therefore specific to a particular chipset.

This specification does the following:

Describes the basic components of the PCI Host Bridge Resource Allocation Protocol
Describes several sample PCI architectures and a sample implementation of the PCI Host Bridge Resource Allocation Protocol
Provides code definitions for the PCI Host Bridge Resource Allocation Protocol and the PCI-host-bridge-related type definitions that are architecturally required by this specification.

The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL does not describe platform policies. The platform policies are described by the EFI_PCI_PLATFORM_PROTOCOL , which is desribed in PCI Platform Protocol . Silicon-related policies are described by the EFI_PCI_OVERRIDE_PROTOCOL , which is described in PCI Override Protocol .

10.2. PCI Host Bridge Design Discussion¶

This section provides background and design information for the PCI Host Bridge Resource Allocation Protocol. A PCI bus driver, running in the EFI Boot Services environment, uses this protocol to program PCI host bridge hardware. This protocol abstracts a PCI host bridge. In particular, functions for programming a PCI host bridge are defined here although other bus types may be supported in a similar fashion as extensions to this specification.

This chapter discusses the following:

PCI terms that are used in this document
An overview of the PCI Host Bridge Resource Allocation Protocol
Sample PCI architectures
ISA aliasing considerations
Programming of standard PCI configuration registers
Sample implementation

10.3. PCI Host Bridge Resource Allocation Protocol¶

10.3.1. PCI Host Bridge Resource Allocation ProtocolOverview¶

The PCI Host Bridge Resource Allocation Protocol is used by a PCI bus driver to program a PCI host bridge. The registers inside a PCI host bridge that control configuration of PCI root buses are not governed by the PCI specification and vary from chipset to chipset. The PCI Host Bridge Resource Allocation Protocol implementation is therefore specific to a particular chipset.

Each PCI host bridge is comprised of one or more PCI root bridges, and there are hardware registers associated with each PCI root bridge. These registers control the bus, I/O, and memory resources that are decoded by the PCI root bus that the PCI root bridge produces and all the PCI buses that are children of that PCI root bus.

The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL allows for future innovation of the chipsets. It abstracts the PCI bus driver from the chipset details. This design allows system designers to make changes to the host bridge hardware without impacting a platform-independent PCI bus driver.

See PCI Host Bridge Resource Allocation Protocol in Code Definitions for the definition of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.

10.3.2. Host Bus Controllers¶

A platform can be viewed as the following:

A set of processors
A set of core chipset components that may produce one or more host buses

The figure below shows a platform with n processors (CPUs) and a set of core chipset components that produce m host bridges (HBs).

Most systems with one PCI host bus controller will contain a single instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL . More complex systems may contain multiple instances of this protocol.

Note

There is no relationship between the number of chipset components in a platform and the number of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instances. This protocol is an abstraction from a software point of view. This protocol is attached to the device handle of a PCI host bus controller, which itself is composed of one or more PCI root bridges. A PCI root bridge is a chipset component(s) that produces a physical PCI bus whose parent is not another physical PCI bus.

_images/V5_PCI_HostBridge-2.png — Fig. 10.9 Host Bus Controllers¶

10.3.3. Producing the PCI Host Bridge ResourceAllocation Protocol¶

EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instances are produced by DXE drivers–most often by early DXE drivers.

The figure below shows how the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is used to identify the associated PCI root bridges. After the steps in the figure are completed, the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL can then be queried to identify the device handles of the associated PCI root bridges. See the UEFI 2.1 Specification for details of the PCI Root Bridge I/O Protocol.

_images/V5_PCI_HostBridge-3.png — Fig. 10.10 Producing the PCI Host Bridge Resource Allocation Protocol¶

10.3.4. Required PCI Protocols¶

The following protocols are mandatory if the system supports PCI devices or slots:

EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

See the UEFI 2.1 Specification for more information on the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

10.3.5. Relationship withEFI_PCI_ROOT_BRIDGE_IO_PROTOCOL¶

It is expected, although not necessary, that a chipset-aware driver will produce the following protocol instances:

EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

Care has been taken to avoid overlap between the member functions of the two protocols. For example, EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL does not describe the SegmentNumber or the final resource assignment for a root bridge, because these attributes are available using the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. Both protocols contain links to the associated instances of the other protocols, as follows:

EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL: Includes the handle of the PCI host bridge that is associated with the root bridge.
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL: Provides a member function to retrieve the handles of the associated root bridges.

The definition of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL attempts to maintain compatibility with the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL definition.

See the UEFI 2.1 Specification for more information on the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

10.4. Sample PCI Architectures¶

10.4.1. Sample PCI Architectures Overview¶

The PCI Host Bridge Resource Allocation Protocol is a protocol that is designed to provide a software abstraction for a wide variety of PCI architectures. This section provides examples of the following PCI architectures:

Desktop system with 1 PCI root bridge
Server system with 4 PCI root bridges
Server system with 2 PCI segments
Server system with 2 PCI host buses

This section is not intended to be an exhaustive list of the PCI architectures that the PCI Host Bridge Resource Allocation Protocol can support. Instead, it is intended to show the flexibility of this protocol to adapt to current and future platform designs.

10.4.2. Desktop System with 1 PCI Root Bridge¶

The figure below shows an example of a PCI host bus with one PCI root bridge. This PCI root bridge produces one PCI local bus that can contain PCI devices on the motherboard and/or PCI slots. This setup would be typical of a desktop system. In this system, the PCI root bridge needs minimal setup. Typically, the PCI root bridge will decode the following:

The entire bus range on Segment 0
The entire I/O space of the processor
All the memory above the top of system memory

The firmware for this platform would produce the following:

One instance of the PCI Host Bridge Resource Allocation Protocol
One instance of PCI Root Bridge I/O Protocol

See the UEFI 2.1 Specification, Chapter 13, for details of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

_images/V5_PCI_HostBridge-4.png — Fig. 10.11 Desktop System with 1 PCI Root Bridge¶

10.4.3. Server System with 4 PCI Root Bridges¶

The figure below shows an example of a larger server with one PCI host Bus with four PCI root bridges (RBs). The PCI devices that are attached to the PCI root bridges are all part of the same coherency domain, which means they share the following:

A common PCI I/O space
A common PCI memory space
A common PCI prefetchable memory space

As a result, each PCI root bridge must get resources out of a common pool. Each PCI root bridge produces one PCI local bus that can contain PCI devices on the motherboard or PCI slots. The firmware for this platform would produce the following:

One instance of the PCI Host Bridge Resource Allocation Protocol
Four instances of the PCI Root Bridge I/O Protocol

See the UEFI 2.1 Specification, Chapter 13, for details of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

_images/V5_PCI_HostBridge-5.png — Fig. 10.12 Server System with 4 PCI Root Bridges¶

10.4.4. Server System with 2 PCI Segments¶

The figure below shows an example of a server with one PCI host bus and two PCI root bridges (RBs). Each of these PCI root bridges is on a different PCI segment, which allows the system to have up to 512 PCI buses. A single PCI segment is limited to 256 PCI buses. These two segments do not share the same PCI configuration space, but they do share the following, which is why they can be described with a single PCI host bus:

A common PCI I/O space
A common PCI memory space
A common PCI prefetchable memory space

The firmware for this platform would produce the following:

One instance of the PCI Host Bridge Resource Allocation Protocol
Two instances of the PCI Root Bridge I/O Protocol

See the UEFI 2.1 Specification, Chapter 13, for details of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

_images/V5_PCI_HostBridge-6.png — Fig. 10.13 Server System with 2 PCI Segments¶

10.4.5. Server System with 2 PCI Host Buses¶

The figure below shows a server system with two PCI host buses and one PCI root bridge (RB) per PCI host bus. As in Server System with 2 PCI Segments, this system supports up to 512 PCI buses, but the following resources are not shared between the two PCI root bridges:

PCI I/O space
PCI memory space
PCI prefetchable memory space

The firmware for this platform would produce the following:

Two instances of the PCI Host Bridge Resource Allocation Protocol
Two instances of the PCI Root Bridge I/O Protocol

See the UEFI 2.1 Specification, Chapter 13, for details of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

_images/V5_PCI_HostBridge-7.png — Fig. 10.14 Server System with 2 PCI Host Buses¶

10.5. ISA Aliasing Considerations¶

The PCI host bridge driver will handle the ISA alias addresses based on the platform policy. The platform communicates the policy to the PCI host bridge driver using the EFI_PCI_PLATFORM_PROTOCOL . If the PCI host bridge driver cannot locate an instance of EFI_PCI_PLATFORM_PROTOCOL, it will not reserve the ISA alias addresses. The PCI bus driver is not aware of this policy and probes devices to gather resource requirements regardless of this policy. The EFI_PCI_PLATFORM_PROTOCOL is defined in PCI Platform Protocol.

Note

When it is started, a PCI device may request that the ISA alias ranges be forwarded to it through the EFI_PCI_IO_PROTOCOL.Attributes() member function by setting the input parameter Attributes to EFI_PCI_IO_ATTRIBUTE_ISA_IO. If the ISA alias I/O addresses are not reserved during enumeration, such a request may fail because one or more PCI devices may be occupying aliased addresses.

If the ISA alias I/O addresses are to be reserved during enumeration, the PCI host bridge driver is responsible for allocating four times the amount of the requested I/O. The PCI bus driver obtains the resources by calling one of the following member functions:

EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.*GetProposedResources()*
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.*Configuration()*

The PCI host bridge driver sets the _RNG bit to communicate the availability of the ISA alias range to the PCI bus driver. If the _RNG flag is set, the PCI bus enumerator is not allowed to allocate the ISA alias addresses to any PCI device. See Standard PCI Devices - Header Type 0 in the “Description” section of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL for the definition of the _RNG flag. In this case, a PCI device’s request to turn on aliasing will succeed because one or more PCI devices may be occupying aliased addresses. The _RNG flag is the only aspect of the protocol interface structure that is affected by ISA aliasing.

10.6. Programming of Standard PCI Configuration Registers¶

This topic defines design guidelines for programming PCI configuration registers in the standard PCI header. It defines roles and responsibilities of various drivers.

Table 10.17 Standard PCI Devices - Header Type 0¶
PCI Configuration Register Bits	Programmed By
PCI command register I O Memory and Bus Master enable	PCI bus driver This driver sets these values as requested by the device driver through the EFI_PCI_IO_PROTOCOL member functions
PCI command register SERR PERR MWI Special Cycle Enable Fast Back to Back Enable	Chipset platform specific code
PCI command register VGA palette snoop	PCI device driver
Cache line size	Chipset platform code to match the processor s cache line size or some other value
Latency timer	PCI bus driver This driver programs this register to default values before it sends the EfiPciBeforeResourceCollection notification For PCI devices this value is 0x20 PCI X devices come out of reset with this register set to 0x40 The PCI bus driver does not change the setting The PCI bus driver will also make sure that the default value for PCI devices is consistent with the MIN_LAT and MAX_LAT register values in the device s PCI configuration space Chipset platform code can overwrite this register during the EfiPciBeforeResourceCollection notification call The new value may come from the end user using configuration options The device driver may overwrite this value during its own Start function
BIST	PCI bus driver
Base address registers	PCI bus driver
Interrupt line	Not touched
Subsystem vendor ID and Device ID	Chipset platform code Per the PCI Specification these registers must get programmed before system software accesses the device Some noncompliant or chipset devices may require that these registers be programmed during the preboot phase

Table 10.18 PCI-to-PCI Bridge - Header Type 1¶
PCI Configuration Register Bits	Programmed By
PCI command register - I/O,Memory, Bus Master enable, VGApalette snoop	PCI bus driver. This driver setsthese values as requested by thedevice driver through theEFI_PCI_IO_PROTOCOL memberfunctions.
PCI command register - SERR,PERR, MWI, Fast Back to BackEnable, Special Cycle Enable	Chipset/platform-specific code.
Cache line size	Chipset/platform code to matchthe processor’s cache line sizeor some other value.
Latency timer	PCI bus driver. This driverprograms to default values beforeit sends theEfiPciBeforeResourceCollectionnotification. For PCI devices,this value is 0x20. PCI-X devicescome out of reset with thisregister set to 0x40.The PCI busdriver does not change thesetting. The PCI bus driver willalso make sure that the defaultvalue for PCI devices isconsistent with the MIN_LAT andMAX_LAT register values in thedevice’s PCI configuration space.Chipset/platform code canoverwrite this register duringtheEfiPciBeforeResourceCollectionnotification call. The new valuemay come from the end user usingconfiguration options.
Base addresses registers, bus,I/O, and memory apertureregisters	PCI bus driver.
Interrupt line	Not touched.
Bridge control register - ISAEnable, VGA Enable	PCI bus driver. This driver setsthese values as requested by thedevice driver through theEFI_PCI_IO_PROTOCOL memberfunctions.
Bridge control register - PERREnable, SERR Enable, Fast Back toBack, Discard Timers	Chipset/platform-specific code.
Bridge control register -Secondary Bus Reset	PCI bus driver is permitted toreset the secondary bus duringenumeration. The chipset/platformcode may also reset the secondarybus during theEfiPciBeforeChildBusEnumerationnotification.

10.7. Sample Implementation¶

Typically, the PCI bus driver will enumerate and allocate resources to all devices for a PCI host bridge. A sample algorithm for PCI enumeration is described below to clarify some of the finer points of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL . Actual implementations may vary. Calls to EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL . PreprocessController() are not included for the sake of clarity.

Unless noted otherwise, all functions that are listed below are member functions of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.

If the hardware supports dynamically changing the number of PCI root buses or changing the segment number that is associated with a PCI root bus, such changes must be completed before the next steps.
The chipset/platform driver(s) creates a device handle for the PCI host bridges in the system(s) and installs an instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL on that handle.
The chipset/platform driver(s) creates a device handle for every PCI root bridge and installs the following on that handle:

An instance of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

An instance of EFI_DEVICE_PATH_PROTOCOL

It is expected that a single driver will handle a PCI host bridge, as well as all the associated PCI root bridges. The ParentHandle field of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL must be initialized with the handle for the PCI host bridge that contains an instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL…Other initialization activities take place.

The EFI_DRIVER_BINDING_PROTOCOL.Start() function of the PCI bus driver is called and is passed the device handle of a PCI root bridge. The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance that is associated with the PCI root bridge can be found by using the ParentHandle field of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL must be present in PI Architecture systems.
Begin the PCI enumeration process. The order in which the various member functions are called cannot be changed. Between any two steps, there can be any amount of implementation-specific code as long as it does not call any member functions of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. This requirement is necessary to keep the state machines in the PCI host bridge allocation driver and the PCI bus enumerator in sync.
Notify the host bridge driver that PCI enumeration is about to begin by calling NotifyPhase (EfiPciHostBridgeBeginEnumeration ). This member function must be the first one that gets called. PCI enumeration has two steps: bus enumeration and resource enumeration.
Notify the host bridge driver that bus enumeration is about to begin by calling NotifyPhase (EfiPciHostBridgeBeginBusAllocation ).
Do the following for every PCI root bridge handle:

Call StartBusEnumeration ( This , RootBridgeHandle ).

Make sure each PCI root bridge handle supports the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.

Allocate memory to hold resource requirements. These resources can be two resource trees: one to hold bus requirements and another to hold the I/O and memory requirements.

Call GetAllocAttributes() to get the attributes of this PCI root bridge. This information is used to combine different types of memory resources in the next step.

Scan all the devices in the specified bus range and on the specified segment. If it is a PCI-to-PCI bridge, update the bus numbers and program the bus number registers in the PCI-to-PCI bridge hardware. If it is an ordinary device, collect the resource request and add up all of these requests in multiple pools (e.g., I/O, 32-bit prefetchable memory). Combine different types of memory requests at an appropriate level based on the PCI root bridge attributes. Update the resource requirement information accordingly. On every PCI root bridge, reserve space to cover the largest expansion ROMs on that bus, which will allow the PCI bus driver to retrieve expansion ROMs from the PCI card or device without having to reprogram the PCI host bridge. Because the memory and I/O resource collection step does not call any member function of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL, it can be performed at a later time.

Once the number of PCI buses under this PCI root bridge is known, call SetBusNumbers() with this information.

Notify the host bridge driver that the bus allocation phase is over by calling NotifyPhase ( EfiPciHostBridgeEndBusAllocation ).
Notify the host bridge driver that resource allocation is about to begin by calling NotifyPhase (EfiPciHostBridgeBeginResourceAllocation).
For every PCI root bridge handle, call SubmitResources() . The Configuration information is derived from the resource requirements that were computed in step 8 above.
Call NotifyPhase (EfiPciHostBridgeAllocateResources ) to allocate the necessary resources. This call should not be made unless resource requirements for all the PCI root bridges have been submitted. If the call succeeds, go to next step. Otherwise, there are two options:

Make do with the smaller ranges.

Call GetProposedResources() to retrieve the proposed settings and examine the differences. Prioritize various requests and drop lower-priority requests. Call NotifyPhase( EfiPciHostBridgeFreeResources ) to undo the previous allocation. Go back to step 11 with reduced requirements, which includes resubmitting requests for all the root bridges.

Call NotifyPhase ( EfiPciHostBridgeSetResources ) to program the hardware. At this point, the decode logic in this host bridge is fully set up.
Do the following for every root bridge handle:

Obtain the resource range that is assigned to a PCI root bridge by calling the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Configuration() member function on that handle.

From the resource range that is assigned to the PCI root bridge, assign resources to all the devices. Program the Base Address Registers (BARs) in all the PCI functions and decode registers in PCI-to-PCI bridges. If a PCI device has a PCI option ROM, copy the contents to a buffer in memory. It is possible to defer the BAR programming for a PCI controller until a connect request for the device is received.

Create a device handle for each PCI device as required.

Install an instance of EFI_PCI_IO_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL on each of these handles.

Notify the host bridge driver that resource allocation is complete by calling NotifyPhase( EfiPciHostBridgeEndResourceAllocation ).
Deallocate any temporary buffers.

Looping on PCI root bridges is accomplished with the following algorithm:

RootBridgeHandle = NULL;
while (GetNextRootBridge(RootBridgeHandle) == EFI_SUCCESS) {
  . . .

10.7.1. PCI enumeration process¶

If the hardware supports dynamically changing the number of PCI root buses or changing the segment number that is associated with a PCI root bus, such changes must be completed before the next steps.
The PCI host bridge driver (s) creates a device handle for the PCI host bridges in the system(s) and installs an instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL on that handle.
The PCI root bridge driver(s) creates a device handle for every PCI root bridge and installs the following on that handle:

An instance of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL

An instance of EFI_DEVICE_PATH_PROTOCOL

It is expected that a single driver will handle a PCI host bridge, as well as all the associated PCI root bridges. The ParentHandle field of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL must be initialized with the handle for the PCI host bridge that contains an instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL .

10.7.1.1. Other initialization activities take place.¶

The EFI_DRIVER_BINDING_PROTOCOL.Start() function of the PCI bus driver is called and is passed the device handle of a PCI root bridge. The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance that is associated with the PCI root bridge can be found by using the ParentHandle field of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL . EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL must be present.
Begin the PCI enumeration process. The order in which the various member functions are called cannot be changed. Between any two steps, there can be any amount of implementation-specific code as long as it does not call any member functions of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL . This requirement is necessary to keep the state machines in the PCI host bridge allocation driver and the PCI bus enumerator in sync.
Notify drivers that PCI enumeration is about to begin using EfiPciHostBridgeBeginenumeration .

10.7.1.2. PCI enumeration has two steps: bus enumerationand resource enumeration.¶

Notify drivers that PCI bus enumeration is about to begin using EfiPciHostBridgeBeginBusAllocation.
Do the following for every PCI root bridge handle:

Call StartBusEnumeration ( This , RootBridgeHandle).

Make sure each PCI root bridge handle supports the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL .

Allocate memory to hold resource requirements.

Call GetAllocAttributes() to get the attributes of this PCI root bridge. This information is used to combine different types of memory resources in the next step.

Scan all the devices in the specified bus range and on the specified segment.

If it is a PCI-to-PCI bridge, update the bus numbers and program the bus number registers in the PCI-to-PCI bridge hardware. Call the drivers for preprocess notifications using EfiPciBeforeChildBusEnumeration.

If it is an ordinary device, collect the resource request and add up all of these requests in multiple pools (e.g., I/O, 32-bit prefetchable memory). Combine different types of memory requests at an appropriate level based on the PCI root bridge attributes. Update the resource requirement information accordingly.

On every PCI root bridge, reserve space to cover the largest expansion ROMs on that bus, which will allow the PCI bus driver to retrieve expansion ROMs from the PCI card or device without having to reprogram the PCI host bridge. Because the memory and I/O resource collection step does not call any member function of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL , it can be performed at a later time.

Once the number of PCI buses under this PCI root bridge is known, call SetBusNumbers() with this information.

Notify drivers that the bus allocation phase is over using EfiPciHostBridgeEndBusAllocation .
Notify drivers that resource allocation is about to begin using EfiPciHostBridgeBeginResourceAllocation .
For every PCI root bridge handle, call SubmitResources() . The Configuration information is derived from the resource requirements that were computed in step 8 above.
Notify the drivers to allocate the necessary resources using EfiPciHostBridgeAllocateResources . This call should not be made unless resource requirements for all the PCI root bridges have been submitted. If the call succeeds, go to next step. Otherwise, there are two options:

Make do with the smaller ranges.

Call GetProposedResources() to retrieve the proposed settings and examine the differences. Prioritize various requests and drop lower-priority requests. Notify the drivers using EfiPciHostBridgeFreeResources to undo the previous allocation. Go back to step 11 with reduced requirements, which includes resubmitting requests for all the root bridges.

Notify the drivers using EfiPciHostBridgeSetResources to program the hardware. At this point, the decode logic in this host bridge is fully set up.
Do the following for every root bridge handle:

Obtain the resource range that is assigned to a PCI root bridge by calling the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Configuration() member function on that handle.

From the resource range that is assigned to the PCI root bridge, assign resources to all the devices. Program the Base Address Registers (BARs) in all the PCI functions and decode registers in PCI-to-PCI bridges. If a PCI device has a PCI option ROM, copy the contents to a buffer in memory. It is possible to defer the BAR programming for a PCI controller until a connect request for the device is received.

Create a device handle for each PCI device as required.

Install an instance of EFI_PCI_IO_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL on each of these handles.

Notify the drivers that resource allocation is complete by using EfiPciHostBridgeEndResourceAllocation .
Notify the drivers that bus enumeration is complete by calling EfiPciHostBridgeEndEnumeration .
Deallocate any temporary buffers.
Install the EFI_PCI_ENUMERATION_COMPLETE_GUID protocol.

10.7.1.3. Sample PCI Device Set Up Implementation¶

This section describes further the outlines of the process in step 14, second bullet (above).

Call the PCI enumeration preprocess functions using EfiPciBeforeResourceCollection .
Gather PCI device resource requirements.
If present, call EFI_INCOMPATIBLE_PCI_DEVICE_SUPPORT_PROTOCOL to see if there is an alternate set of resources for this device.
Call the EFI_PCI_PLATFORM_PROTOCOL function GetPciRom() . If it returns EFI_SUCCESS, go to step 7.
Call the EFI_PCI_OVERRIDE_PROTOCOL function GetPciRom() . If it returns EFI_SUCCESS, go to step 7.
Find the PCI device’s option ROM and copy its contents into memory. If there is no option ROM, go to step 8.
Find and decompress the UEFI image within the option ROM image.
Exit

10.7.2. Sample Enumeration Implementation¶

Typically, the PCI bus driver will enumerate and allocate resources to all devices for a PCI host bridge. A sample algorithm for PCI enumeration is described below to clarify some of the finer points of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL . Actual implementations may vary.

10.7.2.1. PCI Enumeration Phases¶

There are several phases of the PCI enumeration process. For each phase, the PCI platform drivers and the PCI host bridge drivers are notified as follows:

The PlatformNotify() function of the EFI_PCI_PLATFORM_PROTOCOL is called with the enumeration phase and the execution phase BeforePciHostBridge.
The PlatformNotify() function of the EFI_PCI_OVERRIDE_PROTOCOL is called with the enumeration phase and the execution phase BeforePciHostBridge.
The NotifyPhase function of each instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is called with the enumeration phase.
The PlatformNotify() function of the EFI_PCI_PLATFORM_PROTOCOL is called with the enumeration phase and the execution phase AfterPciHostBridge.
The PlatformNotify () function of the EFI_PCI_OVERRIDE_PROTOCOL is called with the execution phase AfterPciHostBridge.

10.7.2.2. Additional locations to preprocess PCI devices¶

There are a few additional places during the PCI enumeration process where the platform or PCI host bridge drivers are given the opportunity to preprocess individual PCI devices.

The PlatformPrepController function of the EFI_PCI_PLATFORM_PROTOCOL is called with the preprocess phase and the execution phase of BeforePciHostBridge.
The PlatformPrepController function of each instance of the EFI_PCI_OVERRIDE_PROTOCOL is called with the preprocess phase and the execution phase of BeforePciHostBridge.
The PreprocessController function of each instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is called with the preprocess phase.
The PlatformPrepController function of each instance of the EFI_PCI_PLATFORM_PROTOCOL is called with the preprocess phase and the execution phase of AfterPciHostBridge.
The PlatformPrepController function of the EFI_PCI_OVERRIDE_PROTOCOL is called with the preprocess phase and the execution phase of AfterPciHostBridge .

10.8. PCI HostBridge Code Definitions¶

10.8.1. Introduction¶

This section contains the basic definitions of the PCI Host Bridge Resource Allocation Protocol. This section defines the protocol EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL

This section also contains the definitions for additional data types and structures that are subordinate to the structures in which they are called. The following types or structures can be found in “Related Definitions” of the parent function definition:

EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE

10.8.2. PCI Host Bridge Resource Allocation Protocol¶

10.8.3. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL¶

Summary

Provides the basic interfaces to abstract a PCI host bridge resource allocation.

Note

This protocol is mandatory if the system includes PCI devices.

GUID

#define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \
  {
0xCF8034BE,0x6768,0x4d8b,0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE
}

Protocol Interface Structure

typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL {
  EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE
  NotifyPhase;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE
  GetNextRootBridge;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES
  GetAllocAttributes;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION
  StartBusEnumeration;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS
  SetBusNumbers;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES
  SubmitResources;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES
  GetProposedResources;
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER
  PreprocessController;
} EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL;

Parameters

NotifyPhase: The notification from the PCI bus enumerator that it is about to enter a certain phase during the enumeration process. See the NotifyPhase() function description.
GetNextRootBridge: Retrieves the device handle for the next PCI root bridge that is produced by the host bridge to which this instance of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is attached. See the GetNextRootBridge() function description. See Terms Used in this Document for a definition of a PCI root bridge.
GetAllocAttributes: Retrieves the allocation-related attributes of a PCI root bridge. See the GetAllocAttributes() function description.
StartBusEnumeration: Sets up a PCI root bridge for bus enumeration. See the StartBusEnumeration() function description.
SetBusNumbers: Sets up the PCI root bridge so that it decodes a specific range of bus numbers. See the SetBusNumbers() function description.
SubmitResources: Submits the resource requirements for the specified PCI root bridge. See the SubmitResources() function description.
GetProposedResources: Returns the proposed resource assignment for the specified PCI root bridges. See the GetProposedResources() function description.
PreprocessController: Provides hooks from the PCI bus driver to every PCI controller (device/function) at various stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual PCI controllers before enumeration. See the PreprocessController() function description.

Description

The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL provides the basic resource allocation services to the PCI bus driver. There is one EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance for each PCI host bridge in a system. The following will typically have only one PCI host bridge:

Embedded systems
Desktops
Workstations
Most servers

High-end servers may have multiple PCI host bridges. A PCI bus driver that wishes to manage a PCI bus in a system will have to retrieve the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance that is associated with the PCI bus to be managed. A device handle for a PCI host bridge will not contain an EFI_DEVICE_PATH_PROTOCOL instance because the PCI host bridge is a software abstraction and has no equivalent in the ACPI name space.

All applicable member functions use ACPI 2.0 or ACPI 3.0 resource descriptors to describe resources. Using ACPI resource descriptors does the following:

Allows other types of resources to be described in the future because they are very generic in nature.
Avoids multiple structure definitions for describing resources.
Maintains compatibility with the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL definition.

Only the following two resource descriptor types from the ACPI Specification may be used to describe the current resources that are allocated to a PCI root bridge:

QWORD Address Space Descriptor ( ACPI 3.0 )
End Tag ( ACPI 3.0)

The QWORD Address Space Descriptor can describe memory, I/O, and bus number ranges for dynamic or fixed resources. The configuration of a PCI root bridge is described with one or more QWORD Address Space Descriptors, followed by an End Tag. ACPI 2.0 & 3.0 QWORD Address Space Descriptor Usage and ACPI 2.0 & 3.0 End Tag Usage below contain these two descriptor types. I/O Resource Flag (Resource Type = 1) Usage and Memory Resource Flag (Resource Type = 0) Usage define how resource-specific flags are used. See the ACPI Specification for details on the field values.

Table 10.19 ACPI 2.0 & 3.0 QWORD Address Space Descriptor Usage¶
Byte Offset	Byte Length	Data	Description
0x00	0x01	0x8A	QWORD Address Space Descriptor
0x01	0x02	0x2B	Length of this descriptor in bytes not including the first two fields
0x03	0x01		Resource type 0 Memory range 1 I O range 2 Bus number range
0x04	0x01		General flags Flags that are common to all resource types Bits 7 4 Reserved must be 0 Bit 3 _MAF Always returned as 1 while returning allocated requests to indicate that the specified max address is fixed Bit 2 _MIF Always returned as 1 while returning allocated requests to indicate that the specified min address is fixed Bit 1 _DEC Ignored Bit 0 Ignored
0x05	0x01		Type specific flags Ignored
0x06	0x08		Address Space Granularity Used to differentiate between a 32 bit memory request and a 64 bit memory request For a 32 bit memory request this field should be set to 32 For a 64 bit memory request this field should be set to 64 Ignored for I O and bus resource requests Ignored during GetPropo sedResources
0x0E	0x08		Address Range Minimum Set to the base of the allocated address range bus I O memory during GetPropo sedResources Ignored during Sub mitResources
0x16	0x08		Address Range Maximum Used to indicate the BAR Index from 0 to 6 where 6 is the Option Rom BAR Specially UINT64 1 in this field means all the PCI BARs on the device except the Option Rom BAR
0x1E	0x08		Address Translation Offset Used to indicate alignment requirement during Su bmitResources and ignored during GetPropo sedResources This value must be 2n 1 The address base must be a multiple of the granularity field That is if this field is 4KiB 1 the allocated address must be a multiple of 4 KiB Note The interpretation of this field for Platform Initialization is different from the ACPI Specification and PCI Root Bridge I O Protocol
0x26	0x08		Address Range Length This field specifies the amount of resources that are requested or allocated in number of bytes

Table 10.20 ACPI 2.0 & 3.0 End Tag Usage¶
Byte Offset	Byte Length	Data	Description
0x00	0x01	0x79	End Tag.
0x01	0x01	0x00	Checksum. Set to 0 toindicate thatchecksum is tobe ignored.

Table 10.21 I/O Resource Flag (Resource Type = 1) Usage¶
Bits	Meaning
Bits[7:1]	Ignored.
Bit[0]	_RNG. Ignored during anallocation request. Setting thisbit while returning allocatedresources means that the I/Oallocation must be limited to theISA I/O ranges. In that case, thePCI bus driver must allocate I/Oaddresses out of the ISA I/Oranges. The following are the SAI/O ranges:n100-n3FFn500-n7FFn900-nBFFnD00-nFFFSee ISA Aliasing Considerationsfor more details.

Table 10.22 Memory Resource Flag (Resource Type = 0) Usage¶
Bits	Meaning
Bits[7:3]	Ignored.
Bit[2:1]	_MEM. Memory attributes.\| Value and Meaning:\| 0 The memory is nonprefetchable.\| 1 Invalid.\| 2 Invalid.\| 3 The memory is prefetchable.Note: The interpretation of thesebits is somewhat different fromthe ACPI Specification. Accordingto the ACPI Specification, avalue of 0 implies noncacheablememory and the value of 3indicates prefetchable andcacheable memory.
Bit[0]	Ignored.

10.8.4. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.NotifyPhase()¶

Summary

These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI enumeration process.

Prototype

typedef
EFI_STATUS
(EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE)
(
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL   *This,
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE      Phase
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
Phase: The phase during enumeration. Type EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE is defined in “Related Definitions” below.

Description

This member function can be used to notify the host bridge driver to perform specific actions, including any chipset-specific initialization, so that the chipset is ready to enter the next phase. Nine notification points are defined at this time. See “Related Definitions” below for definitions of various notification points and Sample Implementation for usage.

More synchronization points may be added as required in the future.

//******************************************************\*
// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE
//******************************************************\*
typedef enum {
  EfiPciHostBridgeBeginEnumeration,
  EfiPciHostBridgeBeginBusAllocation,
  EfiPciHostBridgeEndBusAllocation,
  EfiPciHostBridgeBeginResourceAllocation,
  EfiPciHostBridgeAllocateResources,
  EfiPciHostBridgeSetResources,
  EfiPciHostBridgeFreeResources,
  EfiPciHostBridgeEndResourceAllocation,
  EfiPciHostBridgeEndEnumeration,
  EfiMaxPciHostBridgeEnumeratonPhase
} EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE;

Enumeration Descriptions provides a description of the fields in the above enumeration:

Table 10.23 Enumeration Descriptions¶
Enumeration	Description
EfiPciHostBridgeBeginEnumeration	Resets the host bridge PCI apertures and internal data structures The PCI enumerator should issue this notification before starting a fresh enumeration process Enumeration cannot be restarted after sending any other notification such as Ef iPciHostBridgeBeginBusAllocation
Ef iPciHostBridgeBeginBusAllocation	The bus allocation phase is about to begin No specific action is required here This notification can be used to perform any chipset specific programming
EfiPciHostBridgeEndBusAllocation	The bus allocation and bus programming phase is complete No specific action is required here This notification can be used to perform any chipset specific programming
EfiPciH ostBridgeBeginResourceAllocation	The resource allocation phase is about to begin No specific action is required here This notification can be used to perform any chipset specific programming
E fiPciHostBridgeAllocateResources	Allocates resources per previously submitted requests for all the PCI root bridges These resource settings are returned on the next call to GetProposedResources Before calling NotifyPhase with a Phase of EfiPciHostBridgeAllocateResource the PCI bus enumerator is responsible for gathering I O and memory requests for all the PCI root bridges and submitting these requests using SubmitResources This function pads the resource amount to suit the root bridge hardware takes care of dependencies between the PCI root bridges and calls the Global Coherency Domain GCD with the allocation request In the case of padding the allocated range could be bigger than what was requested Note that the size of the allocated range could be smaller than what was requested This scenario could happen due to an allocation failure a host bridge hardware limitation or any other reason In that case the call will return an EFI_OUT_OF_RESOURCES error If the allocated windows are smaller than what was requested the PCI bus enumerator may not be able to fit all the devices within the range The PCI bus driver can call GetProposedResouces to find out which of the resource types were partially allocated and the difference between the amount that was requested and the amount that was allocated The PCI bus enumerator should readjust the requested sizes by dropping certain PCI devices or PCI buses to obtain a best fit The PCI bus driver can call NotifyPhase EfiPciHostBridgeFreeResources to free up the original assignments and resubmit the adjusted resource requests with SubmitResources
EfiPciHostBridgeSetResources	Programs the host bridge hardware to decode previously allocated resources proposed resources for all the PCI root bridges After the hardware is programmed reassigning resources will not be supported The bus settings are not affected
EfiPciHostBridgeFreeResources	Deallocates resources that were previously allocated for all the PCI root bridges and resets the I O and memory apertures to their initial state The bus settings are not affected If the request to allocate resources fails the PCI enumerator can use this notification to deallocate previous resources adjust the requests and retry allocation
EfiPc iHostBridgeEndResourceAllocation	The resource allocation phase is completed No specific action is required here This notification can be used to perform any chipset specific programming
E fiPciHostBridgeEndBusEnumeration	The bus enumeration phase is completed No specific action is required here This notification can be used to perform any chipset specific programming

Status Codes Returned

EFI_SUCCESS	The notification was accepted without anyerrors.
EFI_INVALID_PARAMETER	The Phase is invalid.
EFI_NOT_READY	This phase cannot be entered at this time.For example, this error is valid for aPhase ofEfiPciHostBridgeAllocateResources ifSubmitResources() has not been called forone or more PCI root bridges before thiscall.
EFI_DEVICE_ERROR	Programming failed due to a hardware error.This error is valid for a Phase ofEfiPciHostBridgeSetResources.
EFI_OUT_OF_RESOURCES	The request could not be completed due to alack of resources. This error is valid fora Phase ofEfiPciHostBridgeAllocateResources if thepreviously submitted resource requestscannot be fulfilled or were only partiallyfulfilled.

10.8.5. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.GetNextRootBridge()¶

Summary

Returns the device handle of the next PCI root bridge that is associated with this host bridge.

Prototype

typedef
EFI_STATUS
(EFIAPI
*EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,
  IN OUT EFI_HANDLE                                    *RootBridgeHandle
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: Returns the device handle of the next PCI root bridge. On input, it holds the RootBridgeHandle that was returned by the most recent call to GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle for the first PCI root bridge is returned. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.

Description

This function is called multiple times to retrieve the device handles of all the PCI root bridges that are associated with this PCI host bridge. Each PCI host bridge is associated with one or more PCI root bridges. On each call, the handle that was returned by the previous call is passed into the interface, and on output the interface returns the device handle of the next PCI root bridge. The caller can use the handle to obtain the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL for that root bridge. When there are no more PCI root bridges to report, the interface returns EFI_NOT_FOUND. A PCI enumerator must enumerate the PCI root bridges in the order that they are returned by this function.

The search is initiated by passing in a NULL device handle as input. Some of the member functions of the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL operate on a PCI root bridge and expect the RootBridgeHandle as an input.

There is no requirement that this function return the root bridges in any specific relation with the EFI device paths of the root bridges.

This function can also be used to determine the number of PCI root bridges that were produced by this PCI host bridge. The host bridge hardware may provide mechanisms to change the number of root bridges that it produces, but such changes must be completed before the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is installed.

Status Codes Returned

EFI_SUCCESS	The requested attribute information was returned
EFI_INVALID_PARAMETER	RootBridgeHandle is not an EFI_HANDLE that was returned on a previous call to GetNextRootBridge
EFI_NOT_FOUND	There are no more PCI root bridge device handles

10.8.6. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.GetAllocAttributes()¶

Summary

Returns the allocation attributes of a PCI root bridge.

Prototype

typedef
EFI_STATUS
(EFIAPI \*
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_GET_ATTRIBUTES) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
  IN EFI_HANDLE                                       RootBridgeHandle,
  OUT UINT64                                          *Attributes
  );

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The device handle of the PCI root bridge in which the caller is interested. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.
Attributes: The pointer to attributes of the PCI root bridge. The permitted attribute values are defined in “Related Definitions” below.

Description

The function returns the allocation attributes of a specific PCI root bridge. The attributes can vary from one PCI root bridge to another. These attributes are different from the decode-related attributes that are returned by the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() member function. The RootBridgeHandle parameter is used to specify the instance of the PCI root bridge. The device handles of all the root bridges that are associated with this host bridge must be obtained by calling GetNextRootBridge() . The attributes are static in the sense that they do not change during or after the enumeration process. The hardware may provide mechanisms to change the attributes on the fly, but such changes must be completed before EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is installed. The permitted values of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES are defined in “Related Definitions” below. The caller uses these attributes to combine multiple resource requests. For example, if the flag EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM is set, the PCI bus enumerator needs to include requests for the prefetchable memory in the nonprefetchable memory pool and not request any prefetchable memory.

//******************************************************\*
// EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES
//******************************************************\*

#define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM     1
#define EFI_PCI_HOST_BRIDGE_MEM64_DECODE         2

Following is a description of the fields in the above definition:

Table 10.24 EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTESfield descriptions¶
EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM	If this bit is set then the PCI root bridge does not support separate windows for nonprefetchable and prefetchable memory A PCI bus driver needs to include requests for prefetchable memory in the nonprefetchable memory pool
EFI_PCI_HOST_BRIDGE_MEM64_DECODE	If this bit is set then the PCI root bridge supports 64 bit memory windows If this bit is not set the PCI bus driver needs to include requests for a 64 bit memory address in the corresponding 32 bit memory pool

Status Codes Returned

EFI_SUCCESS	The requested attribute information was returned.
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle.
EFI_INVALID_PARAMETER	Attributes is NULL.

10.8.7. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.StartBusEnumeration()¶

Summary

Sets up the specified PCI root bridge for the bus enumeration process.

Prototype

typedef
EFI_STATUS
(EFIAPI
*EFI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,
  IN EFI_HANDLE                                        RootBridgeHandle,
  OUT VOID                                             **Configuration
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The PCI root bridge to be set up. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.
Configuration: Pointer to the pointer to the PCI bus resource descriptor.

Description

This member function sets up the root bridge for bus enumeration and returns the PCI bus range over which the search should be performed in ACPI (2.0 & 3.0) resource descriptor format. The following table lists the fields in the ACPI (2.0 & 3.0) resource descriptor that are set for StartBusEnumeration().

Table 10.25 ACPI 2.0 & 3.0 Resource Descriptor FieldValues for StartBusEnumeration()¶
Field	Setting
Address Range Minimum	Set to the lowest bus number to be scanned
Address Range Length	Set to the number of PCI buses that may be scanned The highest bus number is computed by adding the length to the lowest bus number and subtracting 1
Address Range Maximum	Ignored
All other fields	Ignored

Note

See the “Description” section of the PCI Host Bridge Resource Allocation Protocol definition for a description of these ACPI resource descriptor fields.

This function cannot return resource descriptors for anything other than bus resources. This function can be used to prevent a PCI bus driver from scanning certain PCI buses to work around a chipset limitation. Because the size of ACPI resource descriptors is not fixed, StartBusEnumeration() is responsible for allocating memory for the buffer Configuration.

The PCI segment is implicit and is identified by the SegmentNumber field in the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL that is installed on the PCI root bridge handle RootBridgeHandle.

Status Codes Returned

EFI_SUCCESS	The PCI root bridge was set up and the bus range was returned in Configuration
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle
EFI_DEVICE_ERROR	Programming failed due to a hardware error
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources

10.8.8. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.SetBusNumbers()¶

Summary

Programs the PCI root bridge hardware so that it decodes the specified PCI bus range.

Prototype

typedef
EFI_STATUS
(EFIAPI
*EFI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,
  IN EFI_HANDLE                                        RootBridgeHandle,
  IN VOID                                              *Configuration
  );

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The PCI root bridge whose bus range is to be programmed. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.
Configuration: The pointer to the PCI bus resource descriptor.

Description

This member function programs the specified PCI root bridge to decode the bus range that is specified by the input parameter Configuration.

The bus range information is specified in terms of the ACPI (2.0 & 3.0) resource descriptor format. The following table lists the fields in the ACPI (2.0 & 3.0) resource descriptor that are set for SetBusNumbers().

Table 10.26 ACPI 2.0 & 3.0 Resource Descriptor FieldValues for SetBusNumbers()¶
Field	Setting
Address Range Minimum	Set to the lowest bus number to be decoded
Address Range Length	Set to the number of PCI buses that should be decoded The highest bus number is computed by adding the length to the lowest bus number and subtracting 1
Address Range Maximum	Ignored
All other fields	Ignored

Note

See the “Description” section of the PCI Host Bridge Resource Allocation Protocol definition for a description of these ACPI resource descriptor fields.

This call will return EFI_INVALID_PARAMETER without programming the hardware if either of the following are specified:

Any descriptors other than bus type descriptors
Any invalid descriptors

The bus range is typically a subset of what was returned during StartBusEnumeration() . If SetBusNumbers() is called with incorrect (but valid) parameters, it may cause system failure.

The PCI segment is implicit and is identified by the SegmentNumber field in the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL that is installed on the PCI root bridge handle RootBridgeHandle. This call cannot alter the following:

The SegmentNumber field in the corresponding instances of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
The segment number settings in the hardware

The caller is responsible for allocating and deallocating a buffer to hold Configuration. If the call returns EFI_DEVICE_ERROR, the PCI bus enumerator can optionally attempt another bus setting.

Status Codes Returned

EFI_SUCCESS	The bus range for the PCI root bridge was programmed
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle
EFI_INVALID_PARAMETER	Configuration is NULL
EFI_INVALID_PARAMETER	Configuration does not point to a valid ACPI 2 0 3 0 resource descriptor
EFI_INVALID_PARAMETER	Configuration does not include a valid ACPI 2 0 bus resource descriptor
EFI_INVALID_PARAMETER	Configuration includes valid ACPI 2 0 3 0 resource descriptors other than bus descriptors
EFI_INVALID_PARAMETER	Configuration contains one or more invalid ACPI resource descriptors
EFI_INVALID_PARAMETER	Address Range Minimum is invalid for this root bridge
EFI_INVALID_PARAMETER	Address Range Length is invalid for this root bridge
EFI_DEVICE_ERROR	Programming failed due to a hardware error

10.8.9. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.SubmitResources()¶

Summary

Submits the I/O and memory resource requirements for the specified PCI root bridge.

Prototype

typedef
EFI_STATUS
(EFIAPI *
EFI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL  *This,
  IN EFI_HANDLE                                        RootBridgeHandle,
  IN VOID                                              *Configuration
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The PCI root bridge whose I/O and memory resource requirements are being submitted. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.1 Specification.
Configuration: The pointer to the PCI I/O and PCI memory resource descriptor.

Description

This function is used to submit all the I/O and memory resources that are required by the specified PCI root bridge. The input parameter Configuration is used to specify the following:

The various types of resources that are required
The associated lengths in terms of ACPI (2.0 & 3.0) resource descriptor format

The following table lists the fields in the ACPI (2.0 & 3.0) resource descriptor that are set for SubmitResources().

Table 10.27 ACPI 2.0& 3.0 Resource Descriptor FieldValues for SubmitResources()¶
Field	Setting
Address Range Length	Set to the size of the aperture that is requested
Address Space Granularity	Used to differentiate between a 32 bit memory request and a 64 bit memory request For a 32 bit memory request this field should be set to 32 For a 64 bit memory request this field should be set to 64 All other values result in this function returning the error code of EFI_INVALID_PARAMETER
Address Range Maximum	Used to specify the alignment requirement If Address Range Maximum is of the form 2n 1 this member function returns the error code EFI_INVALID_PARAMETER The address base must be a multiple of the granularity field That is if this field is 4 KiB 1 the allocated address must be a multiple of 4 KiB
Address Range Minimum	Ignored
Address Translation Offset	Ignored
All other fields	Ignored

Note

See the “Description” section of the PCI Host Bridge Resource Allocation Protocol definition for a description of these ACPI resource descriptor fields.

The caller must ask for appropriate alignment using the “Address Range Maximum” field. The caller is responsible for allocating and deallocating a buffer to hold Configuration.

It is considered an error if no resource requests are submitted for a PCI root bridge. If a PCI root bridge does not require any resources, a zero-length resource request must explicitly be submitted.

If the Configuration includes one or more invalid resource descriptors, all the resource descriptors are ignored and the function returns EFI_INVALID_PARAMETER.

Status Codes Returned

EFI_SUCCESS	The I O and memory resource requests for a PCI root bridge were accepted
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle
EFI_INVALID_PARAMETER	Configuration is NULL
EFI_INVALID_PARAMETER	Configuration does not point to a valid ACPI 2 0 3 0 resource descriptor
EFI_INVALID_PARAMETER	Configuration includes requests for one or more resource types that are not supported by this PCI root bridge This error will happen if the caller did not combine resources according to Attributes that were returned by GetAllocAttributes
EFI_INVALID_PARAMETER	Address Range Maximum is invalid
EFI_INVALID_PARAMETER	Address Range Length is invalid for this PCI root bridge
EFI_INVALID_PARAMETER	Address Space Granularity is invalid for this PCI root bridge

10.8.10. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.GetProposedResources()¶

Summary

Returns the proposed resource settings for the specified PCI root bridge.

Prototype

typedef
EFI_STATUS
(EFIAPI *
EFI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
  IN EFI_HANDLE                                       RootBridgeHandle,
  OUT VOID                                            **Configuration
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The PCI root bridge handle. Type EFI_HANDLE is defined in InstallProtocolInterface() in the U EFI 2.1 Specification.
Configuration: The pointer to the pointer to the PCI I/O and memory resource descriptor.

Description

This member function returns the proposed resource settings for the specified PCI root bridge. The proposed resource settings are prepared when NotifyPhase() is called with a Phase of EfiPciHostBridgeAllocateResources. The output parameter Configuration specifies the following:

The various types of resources, excluding bus resources, that are allocated
The associated lengths in terms of ACPI (2.0 & 3.0) resource descriptor format

The following table lists the fields in the ACPI (2.0 & 3.0) resource descriptor that are set for GetProposedResources() .

Table 10.28 ACPI 2.0 & 3.0 GetProposedResources()Resource Descriptor Field Values¶
Field	Setting
Address Range Length	Set to the size of the aperture that is requested
Address Space Granularity	Ignored
Address Range Minimum	Indicates the starting address of the allocated ranges
Address Translation Offset	Indicates the allocation status Allocation status is defined in Related Definitions below
Address Range Maximum	Ignored
All other fields	Ignored

Note

See the “Description” section of the PCI Host Bridge Resource Allocation Protocol definition for a description of these ACPI resource descriptor fields.

The callee is responsible for allocating a buffer to hold Configuration because the caller does not know the number of descriptors that are required. The caller is also responsible for deallocating the buffer.

If NotifyPhase() is called with a Phase of EfiPciHostBridgeAllocateResources and returns EFI_OUT_OF_RESOURCES, the PCI bus enumerator may use GetProposedResources() to retrieve the proposed settings. The EFI_OUT_OF_RESOURCES error status indicates that one or more requests could not be fulfilled or were partially fulfilled. Additional details of the allocation status for each type of resource can be retrieved from the “Address Translation Offset” field in the resource descriptor that was returned by this function; also see “Related Definitions” below for defined allocation status values. This error could happen for the following reasons:

Allocation failure
A limitation in the host bridge hardware
Any other reason

If the allocated windows are smaller than what was requested, the PCI bus enumerator may not be able to fit all the devices within the range. In that case, the PCI bus enumerator may choose to readjust the requested sizes (by dropping certain devices or PCI buses) to obtain a best fit. The PCI bus driver calls NotifyPhase() with a Phase of EfiPciHostBridgeFreeResources to free the original assignments.

If this member function is able to only partially fulfill the requests for one or more resource types, the root bridges that are first in the list will get resources first. The ordering of the root bridges is determined by the output of GetNextRootBridge() . The handle to the first root bridge is obtained by calling GetNextRootBridge() with an input handle of NULL.

In the case of I/O resources, the PCI bus enumerator must check the _RNG flag. If this flag is set, the I/O ranges that are allocated to the devices must come from the non-ISA I/O subset.

For example, if this flag is set, the “Address Range Minimum” is 0x1000, and the “Address Range Length” is 0x1000, then the following I/O ranges can be allocated to PCI devices:

0x1000-0x10FF
0x1400-0x14FF
0x1800-0x18FF
0x1C00-0x1CFF

This call is made before NotifyPhase() is called with a Phase of EfiPciHostBridgeSetResources . After that time, the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Configuration() member function should be used to obtain the resources that were consumed by a particular PCI root bridge.

//**************************************************************\*
// EFI_RESOURCE_ALLOCATION_STATUS
//**************************************************************\*
typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS;

#define EFI_RESOURCE_SATISFIED 0
#define EFI_RESOURCE_NOT_SATISFIED (UINT64) -1

Following is a description of the fields in the above definition. All other values indicate that the request of this resource type could be partially fulfilled. The exact value indicates how much more space is still required to fulfill the requirement.

Table 10.29 EFI_RESOURCE_ALLOCATION_STATUS fielddescriptions¶
EFI_RESOURCE_SATISFIED	The request of this resource type could be fulfilled
EFI_RESOURCE_NOT_SATISFIED	The request of this resource type could not be fulfilled for its absence in the host bridge resource pool

Status Codes Returned

EFI_SUCCESS	The requested parameters were returned
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle
EFI_DEVICE_ERROR	Programming failed due to a hardware error
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources

10.8.11. EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.PreprocessController()¶

Summary

Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual PCI controllers before enumeration.

Prototype

typedef
EFI_STATUS
(EFIAPI *
EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER) (
  IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
  IN EFI_HANDLE                                       RootBridgeHandle,
  IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS      PciAddress,
  IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE     Phase
);

Parameters

This: Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
RootBridgeHandle: The associated PCI root bridge handle. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UE FI 2.1 Specification.
PciAddress: The address of the PCI device on the PCI bus. EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS structure is defined in the “Related Definitions” section below.
Phase: The phase of the PCI device enumeration. Type EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE is defined in “Related Definitions” below.

Description

This function is called during the PCI enumeration process. No specific action is expected from this member function. It allows the host bridge driver to preinitialize individual PCI controllers before enumeration.

The parameter RootBridgeHandle can be used to locate the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL that is installed on the root bridge that is the parent of the specific PCI function. The parameter PciAddress can be passed to the Pci.Read() and Pci.Write() functions of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance to access the PCI configuration space of the specific PCI function.

This member function is invoked during PCI enumeration and before the PCI enumerator has created a handle for the PCI function. As a result, the EFI_PCI_IO_PROTOCOL cannot be used at this point.

Two notification points are defined at this time. See type EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE in “Related Definitions” below for definitions of these notification points and ISA Aliasing Considerations for usage. More synchronization points may be added as required in the future.

//******************************************************\*
// EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
//******************************************************\*
typedef enum {
  EfiPciBeforeChildBusEnumeration,
  EfiPciBeforeResourceCollection
} EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE;

Following is a description of the fields in the above enumeration:

Table 10.30 EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASEfield descriptions¶
EfiPciBeforeChildBusEnumeration	This notification is applicable only to PCI to PCI bridges and indicates that the PCI enumerator is about to begin enumerating the bus behind the PCI to PCI bridge This notification is sent after the primary bus number the secondary bus number and the subordinate bus number registers in the PCI to PCI bridge are programmed to valid but not necessary final values Programming of the bus number register allows the chipset code to scan devices on the bus that are immediately behind the PCI to PCI bridge This notification can be used to reset the secondary PCI bus Some PCI to PCI bridges can drive their secondary bus at various clock speeds 33 MHz or 66 MHz for example and support PCI X or conventional PCI mode These bridges must be set up to operate at the correct speed and correct mode before the downstream devices and buses are enumerated This notification can be used to perform that activity The host bridge code cannot reprogram the bus numbers in the PCI to PCI bridge or reprogram any upstream devices during this notification It can touch the downstream devices because the PCI enumerator has not found these devices If there are multiple PCI to PCI bridges on the same PCI bus the order in which the notification is sent to these bridges is implementation specific On the other hand it is guaranteed that a PCI to PCI bridge will see this notification before the downstream bridge receives this notification or its child devices receive the EfiPciBeforeResourceCollection notification
EfiPciBeforeResourceCollection	This notification is sent before the PCI enumerator probes the Base Address Register BAR registers for every valid PCI function This notification can be used to program the backside registers that determine the BAR size or any other programming such as the master latency timer cache line size and PERR and SERR control This notification is sent regardless of whether the function implements BAR or not In the case of a multifunction device this notification is sent for every function of the device The order within the functions is not specified The order in which this notification is sent to various devices functions on the same bus is implementation specific

typedef struct {
  UINT8 Register;
  UINT8 Function;
  UINT8 Device;
  UINT8 Bus;
  UINT32 ExtendedRegister;
} EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS;

Status Codes Returned

EFI_SUCCESS	The requested parameters were returned.
EFI_INVALID_PARAMETER	RootBridgeHandle is not a valid root bridge handle
EFI_INVALID_PARAMETER	Phase is not a valid phase that is defined in EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE
EFI_DEVICE_ERROR	Programming failed due to a hardware error. The PCI enumerator should not enumerate this device, including its child devices if it is a PCI-to-PCI bridge

10.9. End of PCI Enumeration Overview¶

This specification defines the indicia to inform the platform when the PCI enumeration process has completed. This allows for some post enumeration finalization actions to occur, if necessary.

10.9.1. End of PCI Enumeration Protocol¶

The indicia for this finalization action is a protocol. The obligation of the platform that supports this capability is as follows. Once PCI enumeration is complete, the EFI_PCI_ENUMERATION_PROTOCOL shall be installed on the same handle as the host bridge protocol.

This protocol is always installed with a NULL pointer.

GUID

#define EFI_PCI_ENUMERATION_COMPLETE_GUID \
  { \
    0x30cfe3e7, 0x3de1, 0x4586,
  { 0xbe, 0x20, 0xde, 0xab, 0xa1, 0xb3, 0xb7, 0x93 } \
  }

The protocol can be used as an indicia by other DXE agents that the process of PCI device enumeration has been completed.