Data Structures
struct	_EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL

Macros
#define	EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID

#define	EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1

#define	EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2

#define	EFI_RESOURCE_SATISFIED 0x0000000000000000ULL

#define	EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL

Typedefs
typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL	EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL

typedef UINT64	EFI_RESOURCE_ALLOCATION_STATUS

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)

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)

typedef EFI_STATUS(EFIAPI *	EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES )(IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL This, IN EFI_HANDLE RootBridgeHandle, OUT UINT64 Attributes)

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

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

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

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

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)

Enumerations
enum	EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE { EfiPciHostBridgeBeginEnumeration, EfiPciHostBridgeBeginBusAllocation, EfiPciHostBridgeEndBusAllocation, EfiPciHostBridgeBeginResourceAllocation, EfiPciHostBridgeAllocateResources, EfiPciHostBridgeSetResources, EfiPciHostBridgeFreeResources, EfiPciHostBridgeEndResourceAllocation, EfiPciHostBridgeEndEnumeration, EfiMaxPciHostBridgeEnumerationPhase }

enum	EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE { EfiPciBeforeChildBusEnumeration, EfiPciBeforeResourceCollection }

Variables
EFI_GUID	gEfiPciHostBridgeResourceAllocationProtocolGuid

Detailed Description

This file declares PCI Host Bridge Resource Allocation Protocol which provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is mandatory if the system includes PCI devices.

Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Revision Reference:: This Protocol is defined in UEFI Platform Initialization Specification 1.2 Volume 5: Standards.

Macro Definition Documentation

#define EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM 1

If this bit is set, then the PCI Root Bridge does not support separate windows for Non-prefetchable and Prefetchable memory. A PCI bus driver needs to include requests for Prefetchable memory in the Non-prefetchable memory pool.

#define EFI_PCI_HOST_BRIDGE_MEM64_DECODE 2

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 64 bit memory address in the corresponding 32 bit memory pool.

#define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID

Value:

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

Global ID for the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.

#define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL

The request of this resource type could not be fulfilled for its absence in the host bridge resource pool. Used in the Configuration parameter returned by GetProposedResources() to identify a PCI resources request that can not be satisfied.

#define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL

The request of this resource type could be fulfilled. Used in the Configuration parameter returned by GetProposedResources() to identify a PCI resources request that can be satisfied.

Typedef Documentation

typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL

Forward declaration for EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL.

typedef EFI_STATUS(EFIAPI * EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES)(IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, IN EFI_HANDLE RootBridgeHandle, OUT UINT64 *Attributes)

Returns the allocation attributes of a PCI root bridge.

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The device handle of the PCI root bridge in which the caller is interested.
[out]	Attribute	The pointer to attributes of the PCI root bridge.

Return values

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.

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)

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in,out]	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.

Return values

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.

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

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The PCI root bridge handle.
[out]	Configuration	The pointer to the pointer to the PCI I/O and memory resource descriptor.

Return values

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.

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)

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	Phase	The phase during enumeration.

Return values

EFI_SUCCESS	The notification was accepted without any errors.
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 a Phase of EfiPciHostBridgeAllocateResources if SubmitResources() has not been called for one or more PCI root bridges before this call.
EFI_DEVICE_ERROR	Programming failed due to a hardware error. This error is valid for a Phase of EfiPciHostBridgeSetResources.
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources. This error is valid for a Phase of EfiPciHostBridgeAllocateResources if the previously submitted resource requests cannot be fulfilled or were only partially fulfilled

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)

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.

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The associated PCI root bridge handle.
[in]	PciAddress	The address of the PCI device on the PCI bus.
[in]	Phase	The phase of the PCI device enumeration.

Return values

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.

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

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The PCI root bridge whose bus range is to be programmed.
[in]	Configuration	The pointer to the PCI bus resource descriptor.

Return values

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.

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

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The PCI root bridge to be set up.
[out]	Configuration	The pointer to the pointer to the PCI bus resource descriptor.

Return values

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.

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

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

Parameters

[in]	This	The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
[in]	RootBridgeHandle	The PCI root bridge whose I/O and memory resource requirements are being submitted.
[in]	Configuration	The pointer to the PCI I/O and PCI memory resource descriptor.

Return values

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.

typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS

A UINT64 value that contains the status of a PCI resource requested in the Configuration parameter returned by GetProposedResources() The legal values are EFI_RESOURCE_SATISFIED and EFI_RESOURCE_NOT_SATISFIED

Enumeration Type Documentation

enum EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE

Definitions of 2 notification points.

Enumerator
EfiPciBeforeChildBusEnumeration	This notification is only applicable to PCI-PCI bridges and indicates that the PCI enumerator is about to begin enumerating the bus behind the PCI-PCI Bridge. This notification is sent after the primary bus number, the secondary bus number and the subordinate bus number registers in the PCI-PCI Bridge are programmed to valid (not necessary final) values
EfiPciBeforeResourceCollection	This notification is sent before the PCI enumerator probes BAR registers for every valid PCI function.

enum EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE

This enum is used to specify the phase of the PCI enumaeration process.

Enumerator
EfiPciHostBridgeBeginEnumeration	Reset the host bridge PCI apertures and internal data structures. PCI enumerator should issue this notification before starting fresh enumeration process. Enumeration cannot be restarted after sending any other notification such as EfiPciHostBridgeBeginBusAllocation.
EfiPciHostBridgeBeginBusAllocation	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.
EfiPciHostBridgeBeginResourceAllocation	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.
EfiPciHostBridgeAllocateResources	Allocate resources per previously submitted requests for all the PCI Root Bridges. These resource settings are returned on the next call to GetProposedResources().
EfiPciHostBridgeSetResources	Program the Host Bridge hardware to decode previously allocated resources (proposed resources) for all the PCI Root Bridges.
EfiPciHostBridgeFreeResources	De-allocate previously allocated resources previously for all the PCI Root Bridges and reset the I/O and memory apertures to initial state.
EfiPciHostBridgeEndResourceAllocation	The resource allocation phase is completed. No specific action is required here. This notification can be used to perform any chipset specific programming.
EfiPciHostBridgeEndEnumeration	The Host Bridge Enumeration is completed. No specific action is required here. This notification can be used to perform any chipset specific programming.
EfiMaxPciHostBridgeEnumerationPhase

Variable Documentation

EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid

Data Structures

Macros

Typedefs

Enumerations

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Variable Documentation