mirror of
https://git.proxmox.com/git/mirror_edk2
synced 2025-11-04 02:40:26 +00:00
9095d37b8f
1. Do not use tab characters 2. No trailing white space in one line 3. All files must end with CRLF Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Liming Gao <liming.gao@intel.com>
429 lines
19 KiB
C
429 lines
19 KiB
C
/** @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>
|
|
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
|