diff options
author | Guo Mang <mang.guo@intel.com> | 2016-12-22 15:57:14 +0800 |
---|---|---|
committer | Guo Mang <mang.guo@intel.com> | 2016-12-26 19:14:41 +0800 |
commit | 1760cf81e4b1847c6823ea3514a78dd120e19b6e (patch) | |
tree | 64a874b14050fe24d3bbc1bc13cd293abf8ae018 /Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h | |
parent | 7f05fa00f73038b425002566d3afe6c3ade2ccdb (diff) | |
download | edk2-platforms-1760cf81e4b1847c6823ea3514a78dd120e19b6e.tar.xz |
MdePkg: Move to new location
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Guo Mang <mang.guo@intel.com>
Diffstat (limited to 'Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h')
-rw-r--r-- | Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h | 428 |
1 files changed, 428 insertions, 0 deletions
diff --git a/Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h b/Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h new file mode 100644 index 0000000000..e3200de442 --- /dev/null +++ b/Core/MdePkg/Include/Protocol/PciHostBridgeResourceAllocation.h @@ -0,0 +1,428 @@ +/** @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 - 2010, Intel Corporation. All rights reserved.<BR>
+This program and the accompanying materials are licensed and made available under
+the terms and conditions of the BSD License that accompanies this distribution.
+The full text of the license may be found at
+http://opensource.org/licenses/bsd-license.php.
+
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+ @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
|