| /** @file |
| 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.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @par Revision Reference: |
| This Protocol is defined in UEFI Platform Initialization Specification 1.2 |
| Volume 5: Standards. |
| |
| **/ |
| |
| #ifndef _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ |
| #define _PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_H_ |
| |
| // |
| // This file must be included because EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| // uses EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS |
| // |
| #include <Protocol/PciRootBridgeIo.h> |
| |
| /// |
| /// Global ID for the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. |
| /// |
| #define EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GUID \ |
| { \ |
| 0xCF8034BE, 0x6768, 0x4d8b, {0xB7,0x39,0x7C,0xCE,0x68,0x3A,0x9F,0xBE } \ |
| } |
| |
| /// |
| /// Forward declaration for EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. |
| /// |
| typedef struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL; |
| |
| /// 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_COMBINE_MEM_PMEM 1 |
| |
| /// |
| /// 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_MEM64_DECODE 2 |
| |
| /// |
| /// 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 |
| /// |
| typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS; |
| |
| /// |
| /// 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. |
| /// |
| #define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL |
| |
| /// |
| /// 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_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL |
| |
| /// |
| /// This enum is used to specify the phase of the PCI enumaeration process. |
| /// |
| typedef enum { |
| /// |
| /// 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. |
| /// |
| EfiPciHostBridgeBeginEnumeration, |
| |
| /// |
| /// 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. |
| /// |
| EfiPciHostBridgeBeginBusAllocation, |
| |
| /// |
| /// 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. |
| /// |
| EfiPciHostBridgeEndBusAllocation, |
| |
| /// |
| /// 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. |
| /// |
| EfiPciHostBridgeBeginResourceAllocation, |
| |
| /// |
| /// Allocate resources per previously submitted requests for all the PCI Root |
| /// Bridges. These resource settings are returned on the next call to |
| /// GetProposedResources(). |
| /// |
| EfiPciHostBridgeAllocateResources, |
| |
| /// |
| /// Program the Host Bridge hardware to decode previously allocated resources |
| /// (proposed resources) for all the PCI Root Bridges. |
| /// |
| EfiPciHostBridgeSetResources, |
| |
| /// |
| /// De-allocate previously allocated resources previously for all the PCI |
| /// Root Bridges and reset the I/O and memory apertures to initial state. |
| /// |
| EfiPciHostBridgeFreeResources, |
| |
| /// |
| /// The resource allocation phase is completed. No specific action is required |
| /// here. This notification can be used to perform any chipset specific programming. |
| /// |
| EfiPciHostBridgeEndResourceAllocation, |
| |
| /// |
| /// The Host Bridge Enumeration is completed. No specific action is required here. |
| /// This notification can be used to perform any chipset specific programming. |
| /// |
| EfiPciHostBridgeEndEnumeration, |
| EfiMaxPciHostBridgeEnumerationPhase |
| } EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE; |
| |
| /// |
| /// Definitions of 2 notification points. |
| /// |
| typedef enum { |
| /// |
| /// 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 |
| /// |
| EfiPciBeforeChildBusEnumeration, |
| |
| /// |
| /// This notification is sent before the PCI enumerator probes BAR registers |
| /// for every valid PCI function. |
| /// |
| EfiPciBeforeResourceCollection |
| } EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE; |
| |
| /** |
| These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI |
| enumeration process. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] Phase The phase during enumeration. |
| |
| @retval EFI_SUCCESS The notification was accepted without any errors. |
| @retval EFI_INVALID_PARAMETER The Phase is invalid. |
| @retval 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. |
| @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for |
| a Phase of EfiPciHostBridgeSetResources. |
| @retval 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_NOTIFY_PHASE)( |
| IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, |
| IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase |
| ); |
| |
| /** |
| Returns the device handle of the next PCI root bridge that is associated with this host bridge. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[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. |
| |
| @retval EFI_SUCCESS The requested attribute information was returned. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned |
| on a previous call to GetNextRootBridge(). |
| @retval EFI_NOT_FOUND There are no more PCI root bridge device handles. |
| |
| **/ |
| 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 allocation attributes of a PCI root bridge. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested. |
| @param[out] Attribute The pointer to attributes of the PCI root bridge. |
| |
| @retval EFI_SUCCESS The requested attribute information was returned. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_INVALID_PARAMETER Attributes is NULL. |
| |
| **/ |
| 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 |
| ); |
| |
| /** |
| Sets up the specified PCI root bridge for the bus enumeration process. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] RootBridgeHandle The PCI root bridge to be set up. |
| @param[out] Configuration The pointer to the pointer to the PCI bus resource descriptor. |
| |
| @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in |
| Configuration. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. |
| @retval 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_START_BUS_ENUMERATION)( |
| IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, |
| IN EFI_HANDLE RootBridgeHandle, |
| OUT VOID **Configuration |
| ); |
| |
| /** |
| Programs the PCI root bridge hardware so that it decodes the specified PCI bus range. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] RootBridgeHandle The PCI root bridge whose bus range is to be programmed. |
| @param[in] Configuration The pointer to the PCI bus resource descriptor. |
| |
| @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_INVALID_PARAMETER Configuration is NULL |
| @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) |
| resource descriptor. |
| @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource |
| descriptor. |
| @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource |
| descriptors other than bus descriptors. |
| @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource |
| descriptors. |
| @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge. |
| @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge. |
| @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. |
| |
| **/ |
| 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 |
| ); |
| |
| /** |
| Submits the I/O and memory resource requirements for the specified PCI root bridge. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being |
| submitted. |
| @param[in] Configuration The pointer to the PCI I/O and PCI memory resource descriptor. |
| |
| @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were |
| accepted. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_INVALID_PARAMETER Configuration is NULL. |
| @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) |
| resource descriptor. |
| @retval 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(). |
| @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid. |
| @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge. |
| @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge. |
| |
| **/ |
| 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 |
| ); |
| |
| /** |
| Returns the proposed resource settings for the specified PCI root bridge. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL |
| instance. |
| @param[in] RootBridgeHandle The PCI root bridge handle. |
| @param[out] Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor. |
| |
| @retval EFI_SUCCESS The requested parameters were returned. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. |
| @retval 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_GET_PROPOSED_RESOURCES)( |
| IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This, |
| IN EFI_HANDLE RootBridgeHandle, |
| OUT VOID **Configuration |
| ); |
| |
| /** |
| 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. |
| |
| @param[in] This The pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance. |
| @param[in] RootBridgeHandle The associated PCI root bridge handle. |
| @param[in] PciAddress The address of the PCI device on the PCI bus. |
| @param[in] Phase The phase of the PCI device enumeration. |
| |
| @retval EFI_SUCCESS The requested parameters were returned. |
| @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle. |
| @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in |
| EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE. |
| @retval 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_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 basic interfaces to abstract a PCI host bridge resource allocation. |
| /// |
| struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL { |
| /// |
| /// The notification from the PCI bus enumerator that it is about to enter |
| /// a certain phase during the enumeration process. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_NOTIFY_PHASE NotifyPhase; |
| |
| /// |
| /// 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. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_NEXT_ROOT_BRIDGE GetNextRootBridge; |
| |
| /// |
| /// Retrieves the allocation-related attributes of a PCI root bridge. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_ATTRIBUTES GetAllocAttributes; |
| |
| /// |
| /// Sets up a PCI root bridge for bus enumeration. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_START_BUS_ENUMERATION StartBusEnumeration; |
| |
| /// |
| /// Sets up the PCI root bridge so that it decodes a specific range of bus numbers. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SET_BUS_NUMBERS SetBusNumbers; |
| |
| /// |
| /// Submits the resource requirements for the specified PCI root bridge. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_SUBMIT_RESOURCES SubmitResources; |
| |
| /// |
| /// Returns the proposed resource assignment for the specified PCI root bridges. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_GET_PROPOSED_RESOURCES GetProposedResources; |
| |
| /// |
| /// 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. |
| /// |
| EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL_PREPROCESS_CONTROLLER PreprocessController; |
| }; |
| |
| extern EFI_GUID gEfiPciHostBridgeResourceAllocationProtocolGuid; |
| |
| #endif |