/** @file\r
This file declares Pci Host Bridge Resource Allocation Protocol which \r
- Provides the basic interfaces to abstract a PCI host bridge resource allocation. This protocol is\r
- mandatory if the system includes PCI devices.\r
+ Provides the basic interfaces to abstract a PCI host bridge resource allocation. \r
+ This protocol is mandatory if the system includes PCI devices.\r
\r
Copyright (c) 2007 - 2009, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
\r
typedef UINT64 EFI_RESOURCE_ALLOCATION_STATUS;\r
\r
+///\r
/// The request of this resource type could be fulfilled.\r
+///\r
#define EFI_RESOURCE_SATISFIED 0x0000000000000000ULL\r
\r
+///\r
/// The request of this resource type could not be fulfilled for its\r
/// absence in the host bridge resource pool.\r
+///\r
#define EFI_RESOURCE_NOT_SATISFIED 0xFFFFFFFFFFFFFFFFULL\r
\r
//\r
} EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE;\r
\r
///\r
-/// EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE\r
+/// Definitions of 2 notification points.\r
///\r
typedef enum {\r
///\r
} EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE;\r
\r
/**\r
- Enter a certain phase of the PCI enumeration process\r
+ These are the notifications from the PCI bus driver that it is about to enter a certain phase of the PCI \r
+ enumeration process.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
@param Phase The phase during enumeration\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_OUT_OF_RESOURCES If SubmitResources ( ) could not allocate resources\r
- @retval EFI_INVALID_PARAMETER The Phase is invalid\r
- @retval EFI_NOT_READY This phase cannot be entered at this time\r
- @retval EFI_DEVICE_ERROR SetResources failed due to HW error.\r
+ @retval EFI_SUCCESS The notification was accepted without any errors.\r
+ @retval EFI_INVALID_PARAMETER The Phase is invalid.\r
+ @retval EFI_NOT_READY This phase cannot be entered at this time. For example, this error \r
+ is valid for a Phase of EfiPciHostBridgeAllocateResources if \r
+ SubmitResources() has not been called for one or more \r
+ PCI root bridges before this call.\r
+ @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. This error is valid for \r
+ a Phase of EfiPciHostBridgeSetResources.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. \r
+ This error is valid for a Phase of EfiPciHostBridgeAllocateResources\r
+ if the previously submitted resource requests cannot be fulfilled or were only \r
+ partially fulfilled\r
\r
**/\r
typedef\r
\r
\r
/**\r
- Return the device handle of the next PCI root bridge that is associated with\r
- this Host Bridge\r
+ Returns the device handle of the next PCI root bridge that is associated with this host bridge.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle Returns the device handle of the next PCI Root Bridge.\r
- On input, it holds the RootBridgeHandle returned by the most\r
- recent call to GetNextRootBridge().The handle for the first\r
- PCI Root Bridge is returned if RootBridgeHandle is NULL on input\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
+ @param RootBridgeHandle Returns the device handle of the next PCI root bridge. On input, it holds the \r
+ RootBridgeHandle that was returned by the most recent call to \r
+ GetNextRootBridge(). If RootBridgeHandle is NULL on input, the handle \r
+ for the first PCI root bridge is returned.\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_NOT_FOUND There are no more PCI root bridge device handles.\r
+ @retval EFI_SUCCESS The requested attribute information was returned.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was returned \r
+ on a previous call to GetNextRootBridge().\r
+ @retval EFI_NOT_FOUND There are no more PCI root bridge device handles.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- Returns the attributes of a PCI Root Bridge.\r
+ Returns the allocation attributes of a PCI root bridge.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The device handle of the PCI Root Bridge\r
- that the caller is interested in\r
- @param Attribute The pointer to attributes of the PCI Root Bridge\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
+ @param RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested.\r
+ @param Attribute The pointer to attributes of the PCI root bridge.\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_INVALID_PARAMETER Attributes is NULL\r
+ @retval EFI_SUCCESS The requested attribute information was returned.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
+ @retval EFI_INVALID_PARAMETER Attributes is NULL.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- This is the request from the PCI enumerator to set up\r
- the specified PCI Root Bridge for bus enumeration process.\r
+ Sets up the specified PCI root bridge for the bus enumeration process.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The PCI Root Bridge to be set up\r
- @param Configuration Pointer to the pointer to the PCI bus resource descriptor\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
+ @param RootBridgeHandle The PCI root bridge to be set up.\r
+ @param Configuration Pointer to the pointer to the PCI bus resource descriptor.\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_DEVICE_ERROR Request failed due to hardware error\r
- @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources\r
+ @retval EFI_SUCCESS The PCI root bridge was set up and the bus range was returned in \r
+ Configuration.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
+ @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- This function programs the PCI Root Bridge hardware so that\r
- it decodes the specified PCI bus range\r
+ Programs the PCI root bridge hardware so that it decodes the specified PCI bus range.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The PCI Root Bridge whose bus range is to be programmed\r
- @param Configuration The pointer to the PCI bus resource descriptor\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+ instance. \r
+ @param RootBridgeHandle The PCI root bridge whose bus range is to be programmed.\r
+ @param Configuration The pointer to the PCI bus resource descriptor..\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
+ @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
@retval EFI_INVALID_PARAMETER Configuration is NULL\r
- @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor\r
- @retval EFI_INVALID_PARAMETER Configuration contains one or more memory or IO ACPI resource descriptor\r
- @retval EFI_INVALID_PARAMETER Address Range Minimum or Address Range Length fields in Configuration\r
- are invalid for this Root Bridge.\r
- @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource descriptor\r
- @retval EFI_DEVICE_ERROR Request failed due to hardware error\r
- @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources\r
+ @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) \r
+ resource descriptor.\r
+ @retval EFI_INVALID_PARAMETER Configuration does not include a valid ACPI 2.0 bus resource\r
+ descriptor.\r
+ @retval EFI_INVALID_PARAMETER Configuration includes valid ACPI (2.0 & 3.0) resource \r
+ descriptors other than bus descriptors.\r
+ @retval EFI_INVALID_PARAMETER Configuration contains one or more invalid ACPI resource \r
+ descriptors.\r
+ @retval EFI_INVALID_PARAMETER "Address Range Minimum" is invalid for this root bridge.\r
+ @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this root bridge.\r
+ @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- Submits the I/O and memory resource requirements for the specified PCI Root Bridge\r
-\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The PCI Root Bridge whose I/O and memory resource requirements\r
- are being submitted\r
- @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor\r
-\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_INVALID_PARAMETER Configuration is NULL\r
- @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI resource descriptor\r
- @retval EFI_INVALID_PARAMETER Configuration includes a resource descriptor of unsupported type\r
+ Submits the I/O and memory resource requirements for the specified PCI root bridge.\r
+\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
+ @param RootBridgeHandle The PCI root bridge whose I/O and memory resource requirements are being \r
+ submitted.\r
+ @param Configuration The pointer to the PCI I/O and PCI memory resource descriptor.\r
+\r
+ @retval EFI_SUCCESS The I/O and memory resource requests for a PCI root bridge were \r
+ accepted.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
+ @retval EFI_INVALID_PARAMETER Configuration is NULL.\r
+ @retval EFI_INVALID_PARAMETER Configuration does not point to a valid ACPI (2.0 & 3.0) \r
+ resource descriptor.\r
+ @retval EFI_INVALID_PARAMETER Configuration includes requests for one or more resource \r
+ types that are not supported by this PCI root bridge. This error will \r
+ happen if the caller did not combine resources according to \r
+ Attributes that were returned by GetAllocAttributes().\r
+ @retval EFI_INVALID_PARAMETER "Address Range Maximum" is invalid.\r
+ @retval EFI_INVALID_PARAMETER "Address Range Length" is invalid for this PCI root bridge.\r
+ @retval EFI_INVALID_PARAMETER "Address Space Granularity" is invalid for this PCI root bridge.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- This function returns the proposed resource settings for the specified\r
- PCI Root Bridge\r
+ Returns the proposed resource settings for the specified PCI root bridge.\r
\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The PCI Root Bridge handle\r
- @param Configuration The pointer to the pointer to the PCI I/O\r
- and memory resource descriptor\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL \r
+ instance.\r
+ @param RootBridgeHandle The PCI root bridge handle.\r
+ @param Configuration The pointer to the pointer to the PCI I/O and memory resource descriptor.\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_DEVICE_ERROR Request failed due to hardware error\r
- @retval EFI_OUT_OF_RESOURCES Request failed due to lack of resources\r
+ @retval EFI_SUCCESS The requested parameters were returned.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
+ @retval EFI_DEVICE_ERROR Programming failed due to a hardware error.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
\r
**/\r
typedef\r
\r
\r
/**\r
- This function is called for all the PCI controllers that the PCI\r
- bus driver finds. Can be used to Preprogram the controller.\r
-\r
- @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
- @param RootBridgeHandle The PCI Root Bridge handle\r
- @param PciBusAddress Address of the controller on the PCI bus\r
- @param Phase The Phase during resource allocation\r
-\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_INVALID_PARAMETER RootBridgeHandle is invalid\r
- @retval EFI_DEVICE_ERROR Device pre-initialization failed due to hardware error.\r
+ Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various \r
+ stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual \r
+ PCI controllers before enumeration.\r
+\r
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
+ @param RootBridgeHandle The associated PCI root bridge handle.\r
+ @param PciAddress The address of the PCI device on the PCI bus.\r
+ @param Phase The phase of the PCI device enumeration.\r
+\r
+ @retval EFI_SUCCESS The requested parameters were returned.\r
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not a valid root bridge handle.\r
+ @retval EFI_INVALID_PARAMETER Phase is not a valid phase that is defined in \r
+ EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.\r
+ @retval EFI_DEVICE_ERROR Programming failed due to a hardware error. The PCI enumerator \r
+ should not enumerate this device, including its child devices if it is \r
+ a PCI-to-PCI bridge.\r
\r
**/\r
typedef\r
IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase\r
);\r
\r
-/**\r
- Provides the basic interfaces to abstract a PCI host bridge resource allocation.\r
-**/\r
+///\r
+/// Provides the basic interfaces to abstract a PCI host bridge resource allocation.\r
+///\r
struct _EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL {\r
///\r
/// The notification from the PCI bus enumerator that it is about to enter\r
projects / mirror_edk2.git / blobdiff