diff options
| author | klu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524> | 2010-04-12 04:38:44 +0000 |
|---|---|---|
| committer | klu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524> | 2010-04-12 04:38:44 +0000 |
| commit | 18c97f53ea089437a3e053c834deb737ccbc9576 (patch) | |
| tree | 1ed85202fd41c00dc52f43906c1534652b71465f /PcAtChipsetPkg/PciHostBridgeDxe | |
| parent | 9af300fc22f347bf6bda74f6183340bf37aaeb24 (diff) | |
| download | edk2-platforms-18c97f53ea089437a3e053c834deb737ccbc9576.tar.xz | |
Refine the file/function comments to follow doxygen format
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@10359 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'PcAtChipsetPkg/PciHostBridgeDxe')
| -rw-r--r-- | PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c | 395 | ||||
| -rw-r--r-- | PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridgeDxe.inf | 4 | ||||
| -rw-r--r-- | PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c | 965 |
3 files changed, 1073 insertions, 291 deletions
diff --git a/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c b/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c index c879057846..c2f04ec807 100644 --- a/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c +++ b/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c @@ -1,15 +1,14 @@ /** @file
- Pci Host Bridge driver:
Provides the basic interfaces to abstract a PCI Host Bridge Resource Allocation
- Copyright (c) 2008 - 2009, Intel Corporation<BR> All rights
- reserved. This program and the accompanying materials are
- licensed and made available under the terms and conditions of the BSD License
- which 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.
+Copyright (c) 2008 - 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
+which 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.
**/
@@ -79,26 +78,22 @@ PCI_HOST_BRIDGE_INSTANCE mPciHostBridgeInstanceTemplate = { //
// Implementation
//
+/**
+ Entry point of this driver
+
+ @param ImageHandle Handle of driver image
+ @param SystemTable Point to EFI_SYSTEM_TABLE
+
+ @retval EFI_OUT_OF_RESOURCES Can not allocate memory resource
+ @retval EFI_DEVICE_ERROR Can not install the protocol instance
+ @retval EFI_SUCCESS Success to initialize the Pci host bridge.
+**/
EFI_STATUS
EFIAPI
InitializePciHostBridge (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- Entry point of this driver
-
-Arguments:
-
- ImageHandle -
-
- SystemTable -
-
-Returns:
-
---*/
{
EFI_STATUS Status;
UINTN Loop1;
@@ -194,24 +189,76 @@ Returns: }
+/**
+ These are the notifications from the PCI bus driver that it is about to enter a certain
+ phase of the PCI enumeration process.
+
+ This member function can be used to notify the host bridge driver to perform specific actions,
+ including any chipset-specific initialization, so that the chipset is ready to enter the next phase.
+ Eight notification points are defined at this time. See belows:
+ EfiPciHostBridgeBeginEnumeration Resets the host bridge PCI apertures and internal data
+ structures. The PCI enumerator should issue this notification
+ before starting a 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 Allocates resources per previously submitted requests for all the PCI
+ root bridges. These resource settings are returned on the next call to
+ GetProposedResources(). Before calling NotifyPhase() with a Phase of
+ EfiPciHostBridgeAllocateResource, the PCI bus enumerator is responsible
+ for gathering I/O and memory requests for
+ all the PCI root bridges and submitting these requests using
+ SubmitResources(). This function pads the resource amount
+ to suit the root bridge hardware, takes care of dependencies between
+ the PCI root bridges, and calls the Global Coherency Domain (GCD)
+ with the allocation request. In the case of padding, the allocated range
+ could be bigger than what was requested.
+ EfiPciHostBridgeSetResources Programs the host bridge hardware to decode previously allocated
+ resources (proposed resources) for all the PCI root bridges. After the
+ hardware is programmed, reassigning resources will not be supported.
+ The bus settings are not affected.
+ EfiPciHostBridgeFreeResources Deallocates resources that were previously allocated for all the PCI
+ root bridges and resets the I/O and memory apertures to their initial
+ state. The bus settings are not affected. If the request to allocate
+ resources fails, the PCI enumerator can use this notification to
+ deallocate previous resources, adjust the requests, and retry
+ allocation.
+ EfiPciHostBridgeEndResourceAllocation The resource allocation phase is completed. No specific action is
+ required here. This notification can be used to perform any chipsetspecific
+ programming.
+
+ @param[in] PciResAlloc The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
+ @param[in] Phase The phase during enumeration
+
+ @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_INVALID_PARAMETER Invalid phase parameter
+ @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.
+ @retval EFI_SUCCESS The notification was accepted without any errors.
+
+**/
EFI_STATUS
EFIAPI
NotifyPhase(
IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE Phase
)
-/*++
-
-Routine Description:
- Enter a certain phase of the PCI enumeration process
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance
- Phase -- The phase during enumeration
-
-Returns:
-
---*/
{
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
PCI_ROOT_BRIDGE_INSTANCE *RootBridgeInstance;
@@ -460,28 +507,34 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Return the device handle of the next PCI root bridge that is associated with this Host Bridge.
+
+ This function is called multiple times to retrieve the device handles of all the PCI root bridges that
+ are associated with this PCI host bridge. Each PCI host bridge is associated with one or more PCI
+ root bridges. On each call, the handle that was returned by the previous call is passed into the
+ interface, and on output the interface returns the device handle of the next PCI root bridge. The
+ caller can use the handle to obtain the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
+ for that root bridge. When there are no more PCI root bridges to report, the interface returns
+ EFI_NOT_FOUND. A PCI enumerator must enumerate the PCI root bridges in the order that they
+ are returned by this function.
+ For D945 implementation, there is only one root bridge in PCI host bridge.
+
+ @param[in] This The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
+ @param[in][out] RootBridgeHandle Returns the device handle of the next PCI root bridge.
+
+ @retval EFI_SUCCESS If parameter RootBridgeHandle = NULL, then return the first Rootbridge handle of the
+ specific Host bridge and return EFI_SUCCESS.
+ @retval EFI_NOT_FOUND Can not find the any more root bridge in specific host bridge.
+ @retval EFI_INVALID_PARAMETER RootBridgeHandle is not an EFI_HANDLE that was
+ returned on a previous call to GetNextRootBridge().
+**/
EFI_STATUS
EFIAPI
GetNextRootBridge(
IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,
IN OUT EFI_HANDLE *RootBridgeHandle
)
-/*++
-
-Routine Description:
- Return the device handle of the next PCI root bridge that is associated with
- this Host Bridge
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- Returns the device handle of the next PCI Root Bridge.
- On input, it holds the RootBridgeHandle returned by the most
- recent call to GetNextRootBridge().The handle for the first
- PCI Root Bridge is returned if RootBridgeHandle is NULL on input
-
-Returns:
-
---*/
{
BOOLEAN NoRootBridge;
LIST_ENTRY *List;
@@ -528,6 +581,44 @@ Returns: }
}
+/**
+ Returns the allocation attributes of a PCI root bridge.
+
+ The function returns the allocation attributes of a specific PCI root bridge. The attributes can vary
+ from one PCI root bridge to another. These attributes are different from the decode-related
+ attributes that are returned by the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() member function. The
+ RootBridgeHandle parameter is used to specify the instance of the PCI root bridge. The device
+ handles of all the root bridges that are associated with this host bridge must be obtained by calling
+ GetNextRootBridge(). The attributes are static in the sense that they do not change during or
+ after the enumeration process. The hardware may provide mechanisms to change the attributes on
+ the fly, but such changes must be completed before EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is
+ installed. The permitted values of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES are defined in
+ "Related Definitions" below. The caller uses these attributes to combine multiple resource requests.
+ For example, if the flag EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM is set, the PCI bus enumerator needs to
+ include requests for the prefetchable memory in the nonprefetchable memory pool and not request any
+ prefetchable memory.
+ Attribute Description
+ ------------------------------------ ----------------------------------------------------------------------
+ EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM If this bit is set, then the PCI root bridge does not support separate
+ windows for nonprefetchable and prefetchable memory. A PCI bus
+ driver needs to include requests for prefetchable memory in the
+ nonprefetchable memory pool.
+
+ EFI_PCI_HOST_BRIDGE_MEM64_DECODE 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 a 64-bit memory address in the corresponding 32-bit
+ memory pool.
+
+ @param[in] This The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL
+ @param[in] RootBridgeHandle The device handle of the PCI root bridge in which the caller is interested. Type
+ EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 Specification.
+ @param[out] Attributes The pointer to attribte of root bridge, it is output parameter
+
+ @retval EFI_INVALID_PARAMETER Attribute pointer is NULL
+ @retval EFI_INVALID_PARAMETER RootBridgehandle is invalid.
+ @retval EFI_SUCCESS Success to get attribute of interested root bridge.
+
+**/
EFI_STATUS
EFIAPI
GetAttributes(
@@ -535,20 +626,6 @@ GetAttributes( IN EFI_HANDLE RootBridgeHandle,
OUT UINT64 *Attributes
)
-/*++
-
-Routine Description:
- Returns the attributes of a PCI Root Bridge.
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The device handle of the PCI Root Bridge
- that the caller is interested in
- Attribute -- The pointer to attributes of the PCI Root Bridge
-
-Returns:
-
---*/
{
LIST_ENTRY *List;
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
@@ -577,6 +654,21 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ Sets up the specified PCI root bridge for the bus enumeration process.
+
+ This member function sets up the root bridge for bus enumeration and returns the PCI bus range
+ over which the search should be performed in ACPI 2.0 resource descriptor format.
+
+ @param[in] This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.
+ @param[in] RootBridgeHandle The PCI Root Bridge to be set up.
+ @param[out] Configuration Pointer to the pointer to the PCI bus resource descriptor.
+
+ @retval EFI_INVALID_PARAMETER Invalid Root bridge's handle
+ @retval EFI_OUT_OF_RESOURCES Fail to allocate ACPI resource descriptor tag.
+ @retval EFI_SUCCESS Sucess to allocate ACPI resource descriptor.
+
+**/
EFI_STATUS
EFIAPI
StartBusEnumeration(
@@ -584,20 +676,6 @@ StartBusEnumeration( IN EFI_HANDLE RootBridgeHandle,
OUT VOID **Configuration
)
-/*++
-
-Routine Description:
- This is the request from the PCI enumerator to set up
- the specified PCI Root Bridge for bus enumeration process.
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The PCI Root Bridge to be set up
- Configuration -- Pointer to the pointer to the PCI bus resource descriptor
-
-Returns:
-
---*/
{
LIST_ENTRY *List;
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
@@ -653,6 +731,30 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ Programs the PCI root bridge hardware so that it decodes the specified PCI bus range.
+
+ This member function programs the specified PCI root bridge to decode the bus range that is
+ specified by the input parameter Configuration.
+ The bus range information is specified in terms of the ACPI 2.0 resource descriptor format.
+
+ @param[in] This 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_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 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 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.
+ @retval EFI_SUCCESS The bus range for the PCI root bridge was programmed.
+
+**/
EFI_STATUS
EFIAPI
SetBusNumbers(
@@ -660,20 +762,6 @@ SetBusNumbers( IN EFI_HANDLE RootBridgeHandle,
IN VOID *Configuration
)
-/*++
-
-Routine Description:
- This function programs the PCI Root Bridge hardware so that
- it decodes the specified PCI bus range
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The PCI Root Bridge whose bus range is to be programmed
- Configuration -- The pointer to the PCI bus resource descriptor
-
-Returns:
-
---*/
{
LIST_ENTRY *List;
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
@@ -746,6 +834,31 @@ Returns: }
+/**
+ Submits the I/O and memory resource requirements for the specified PCI root bridge.
+
+ This function is used to submit all the I/O and memory resources that are required by the specified
+ PCI root bridge. The input parameter Configuration is used to specify the following:
+ - The various types of resources that are required
+ - The associated lengths in terms of ACPI 2.0 resource descriptor format
+
+ @param[in] This 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 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.
+
+**/
EFI_STATUS
EFIAPI
SubmitResources(
@@ -753,19 +866,6 @@ SubmitResources( IN EFI_HANDLE RootBridgeHandle,
IN VOID *Configuration
)
-/*++
-
-Routine Description:
- Submits the I/O and memory resource requirements for the specified PCI Root Bridge
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The PCI Root Bridge whose I/O and memory resource requirements
- are being submitted
- Configuration -- The pointer to the PCI I/O and PCI memory resource descriptor
-Returns:
-
---*/
{
LIST_ENTRY *List;
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
@@ -883,6 +983,26 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ Returns the proposed resource settings for the specified PCI root bridge.
+
+ This member function returns the proposed resource settings for the specified PCI root bridge. The
+ proposed resource settings are prepared when NotifyPhase() is called with a Phase of
+ EfiPciHostBridgeAllocateResources. The output parameter Configuration
+ specifies the following:
+ - The various types of resources, excluding bus resources, that are allocated
+ - The associated lengths in terms of ACPI 2.0 resource descriptor format
+
+ @param[in] This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
+ @param[in] RootBridgeHandle The PCI root bridge handle. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 Specification.
+ @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.
+
+**/
EFI_STATUS
EFIAPI
GetProposedResources(
@@ -890,21 +1010,6 @@ GetProposedResources( IN EFI_HANDLE RootBridgeHandle,
OUT VOID **Configuration
)
-/*++
-
-Routine Description:
- This function returns the proposed resource settings for the specified
- PCI Root Bridge
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The PCI Root Bridge handle
- Configuration -- The pointer to the pointer to the PCI I/O
- and memory resource descriptor
-
-Returns:
-
---*/
{
LIST_ENTRY *List;
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
@@ -1053,6 +1158,12 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ Update attribute for PCI root bridge for specifc device.
+
+ @param RootBridge Point to PCI root bridge.
+ @param PciAddress The specific device PCI address
+**/
STATIC
VOID
UpdateRootBridgeAttributes (
@@ -1151,6 +1262,33 @@ UpdateRootBridgeAttributes ( RootBridge->Supports = Attributes;
}
+/**
+ 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.
+
+ This function is called during the PCI enumeration process. No specific action is expected from this
+ member function. It allows the host bridge driver to preinitialize individual PCI controllers before
+ enumeration.
+
+ @param This Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
+ @param RootBridgeHandle The associated PCI root bridge handle. Type EFI_HANDLE is defined in
+ InstallProtocolInterface() in the UEFI 2.0 Specification.
+ @param PciAddress The address of the PCI device on the PCI bus. This address can be passed to the
+ EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL member functions to access the PCI
+ configuration space of the device. See Table 12-1 in the UEFI 2.0 Specification for
+ the definition of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.
+ @param 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.
+
+**/
EFI_STATUS
EFIAPI
PreprocessController (
@@ -1159,21 +1297,6 @@ PreprocessController ( IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS PciAddress,
IN EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE Phase
)
-/*++
-
-Routine Description:
- This function is called for all the PCI controllers that the PCI
- bus driver finds. Can be used to Preprogram the controller.
-
-Arguments:
- This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance
- RootBridgeHandle -- The PCI Root Bridge handle
- PciBusAddress -- Address of the controller on the PCI bus
- Phase -- The Phase during resource allocation
-
-Returns:
- EFI_SUCCESS
---*/
{
PCI_HOST_BRIDGE_INSTANCE *HostBridgeInstance;
PCI_ROOT_BRIDGE_INSTANCE *RootBridgeInstance;
diff --git a/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridgeDxe.inf b/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridgeDxe.inf index 2cd9314481..ea373b3c73 100644 --- a/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridgeDxe.inf +++ b/PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridgeDxe.inf @@ -2,8 +2,8 @@ #
# Component description file a sinngle segment PCI Host Bridge driver.
#
-# Copyright (c) 2008 - 2010, Intel Corporation. <BR>
-# All rights reserved. This program and the accompanying materials
+# Copyright (c) 2008 - 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
# which accompanies this distribution. The full text of the license may be found at
# http://opensource.org/licenses/bsd-license.php
diff --git a/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c b/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c index 36f83f62e0..9230434185 100644 --- a/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c +++ b/PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c @@ -1,14 +1,14 @@ /** @file
PCI Root Bridge Io Protocol implementation
- Copyright (c) 2008 - 2009, Intel Corporation<BR> All rights
- reserved. This program and the accompanying materials are
- licensed and made available under the terms and conditions of the BSD License
- which 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.
+Copyright (c) 2008 - 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
+which 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.
**/
@@ -33,6 +33,35 @@ RESOURCE_CONFIGURATION Configuration = { // Protocol Member Function Prototypes
//
+/**
+ Polls an address in memory mapped I/O space until an exit condition is met, or
+ a timeout occurs.
+
+ This function provides a standard way to poll a PCI memory location. A PCI memory read
+ operation is performed at the PCI memory address specified by Address for the width specified
+ by Width. The result of this PCI memory read operation is stored in Result. This PCI memory
+ read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result &
+ Mask) is equal to Value.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the memory operations. The caller is
+ responsible for aligning Address if required.
+ @param[in] Mask Mask used for the polling criteria. Bytes above Width in Mask
+ are ignored. The bits in the bytes below Width which are zero in
+ Mask are ignored when polling the memory address.
+ @param[in] Value The comparison value used for the polling exit criteria.
+ @param[in] Delay The number of 100 ns units to poll. Note that timer available may
+ be of poorer granularity.
+ @param[out] Result Pointer to the last value read from the memory location.
+
+ @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
+ @retval EFI_INVALID_PARAMETER Width is invalid.
+ @retval EFI_INVALID_PARAMETER Result is NULL.
+ @retval EFI_TIMEOUT Delay expired before a match occurred.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPollMem (
@@ -45,6 +74,35 @@ RootBridgeIoPollMem ( OUT UINT64 *Result
);
+/**
+ Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is
+ satisfied or after a defined duration.
+
+ This function provides a standard way to poll a PCI I/O location. A PCI I/O read operation is
+ performed at the PCI I/O address specified by Address for the width specified by Width.
+ The result of this PCI I/O read operation is stored in Result. This PCI I/O read operation is
+ repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal
+ to Value.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the I/O operations.
+ @param[in] Address The base address of the I/O operations. The caller is responsible
+ for aligning Address if required.
+ @param[in] Mask Mask used for the polling criteria. Bytes above Width in Mask
+ are ignored. The bits in the bytes below Width which are zero in
+ Mask are ignored when polling the I/O address.
+ @param[in] Value The comparison value used for the polling exit criteria.
+ @param[in] Delay The number of 100 ns units to poll. Note that timer available may
+ be of poorer granularity.
+ @param[out] Result Pointer to the last value read from the memory location.
+
+ @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
+ @retval EFI_INVALID_PARAMETER Width is invalid.
+ @retval EFI_INVALID_PARAMETER Result is NULL.
+ @retval EFI_TIMEOUT Delay expired before a match occurred.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPollIo (
@@ -57,6 +115,29 @@ RootBridgeIoPollIo ( OUT UINT64 *Result
);
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
+
+ The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller
+ registers in the PCI root bridge memory space.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operation.
+ @param[in] Address The base address of the memory operation. The caller is
+ responsible for aligning the Address if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMemRead (
@@ -67,6 +148,28 @@ RootBridgeIoMemRead ( IN OUT VOID *Buffer
);
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
+
+ The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller
+ registers in the PCI root bridge memory space.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operation.
+ @param[in] Address The base address of the memory operation. The caller is
+ responsible for aligning the Address if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMemWrite (
@@ -77,6 +180,24 @@ RootBridgeIoMemWrite ( IN OUT VOID *Buffer
);
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the I/O operation. The caller is responsible for
+ aligning the Address if required.
+ @param[in] Count The number of I/O operations to perform. Bytes moved is Width
+ size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoIoRead (
@@ -87,6 +208,24 @@ RootBridgeIoIoRead ( IN OUT VOID *UserBuffer
);
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the I/O operation. The caller is responsible for
+ aligning the Address if required.
+ @param[in] Count The number of I/O operations to perform. Bytes moved is Width
+ size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoIoWrite (
@@ -97,6 +236,30 @@ RootBridgeIoIoWrite ( IN OUT VOID *UserBuffer
);
+/**
+ Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI
+ root bridge memory space.
+
+ The CopyMem() function enables a PCI driver to copy one region of PCI root bridge memory
+ space to another region of PCI root bridge memory space. This is especially useful for video scroll
+ operation on a memory mapped video buffer.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI root bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] DestAddress The destination address of the memory operation. The caller is
+ responsible for aligning the DestAddress if required.
+ @param[in] SrcAddress The source address of the memory operation. The caller is
+ responsible for aligning the SrcAddress if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at DestAddress and SrcAddress.
+
+ @retval EFI_SUCCESS The data was copied from one memory region to another memory region.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoCopyMem (
@@ -107,6 +270,29 @@ RootBridgeIoCopyMem ( IN UINTN Count
);
+/**
+ Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.
+
+ The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration
+ registers for a PCI controller.
+ The PCI Configuration operations are carried out exactly as requested. The caller is responsible for
+ any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might
+ require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPciRead (
@@ -117,6 +303,29 @@ RootBridgeIoPciRead ( IN OUT VOID *Buffer
);
+/**
+ Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.
+
+ The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration
+ registers for a PCI controller.
+ The PCI Configuration operations are carried out exactly as requested. The caller is responsible for
+ any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might
+ require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPciWrite (
@@ -127,6 +336,32 @@ RootBridgeIoPciWrite ( IN OUT VOID *Buffer
);
+/**
+ Provides the PCI controller-specific addresses required to access system memory from a
+ DMA bus master.
+
+ The Map() function provides the PCI controller specific addresses needed to access system
+ memory. This function is used to map system memory for PCI bus master DMA accesses.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Operation Indicates if the bus master is going to read or write to system memory.
+ @param[in] HostAddress The system memory address to map to the PCI controller.
+ @param[in][out] NumberOfBytes On input the number of bytes to map. On output the number of bytes that were mapped.
+ @param[out] DeviceAddress The resulting map address for the bus master PCI controller to use
+ to access the system memory's HostAddress.
+ @param[out] Mapping The value to pass to Unmap() when the bus master DMA operation is complete.
+
+ @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
+ @retval EFI_INVALID_PARAMETER Operation is invalid.
+ @retval EFI_INVALID_PARAMETER HostAddress is NULL.
+ @retval EFI_INVALID_PARAMETER NumberOfBytes is NULL.
+ @retval EFI_INVALID_PARAMETER DeviceAddress is NULL.
+ @retval EFI_INVALID_PARAMETER Mapping is NULL.
+ @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
+ @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMap (
@@ -138,6 +373,22 @@ RootBridgeIoMap ( OUT VOID **Mapping
);
+/**
+ Completes the Map() operation and releases any corresponding resources.
+
+ The Unmap() function completes the Map() operation and releases any corresponding resources.
+ If the operation was an EfiPciOperationBusMasterWrite or
+ EfiPciOperationBusMasterWrite64, the data is committed to the target system memory.
+ Any resources used for the mapping are freed.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Mapping The mapping value returned from Map().
+
+ @retval EFI_SUCCESS The range was unmapped.
+ @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
+ @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoUnmap (
@@ -145,6 +396,27 @@ RootBridgeIoUnmap ( IN VOID *Mapping
);
+/**
+ Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or
+ EfiPciOperationBusMasterCommonBuffer64 mapping.
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Type This parameter is not used and must be ignored.
+ @param MemoryType The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData.
+ @param Pages The number of pages to allocate.
+ @param HostAddress A pointer to store the base system memory address of the allocated range.
+ @param Attributes The requested bit mask of attributes for the allocated range. Only
+ the attributes EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, EFI_PCI_ATTRIBUTE_MEMORY_CACHED,
+ and EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this function.
+
+ @retval EFI_SUCCESS The requested memory pages were allocated.
+ @retval EFI_INVALID_PARAMETER MemoryType is invalid.
+ @retval EFI_INVALID_PARAMETER HostAddress is NULL.
+ @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.
+ @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoAllocateBuffer (
@@ -156,6 +428,20 @@ RootBridgeIoAllocateBuffer ( IN UINT64 Attributes
);
+/**
+ Frees memory that was allocated with AllocateBuffer().
+
+ The FreeBuffer() function frees memory that was allocated with AllocateBuffer().
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Pages The number of pages to free.
+ @param HostAddress The base system memory address of the allocated range.
+
+ @retval EFI_SUCCESS The requested memory pages were freed.
+ @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
+ was not allocated with AllocateBuffer().
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoFreeBuffer (
@@ -164,12 +450,51 @@ RootBridgeIoFreeBuffer ( OUT VOID *HostAddress
);
+/**
+ Flushes all PCI posted write transactions from a PCI host bridge to system memory.
+
+ The Flush() function flushes any PCI posted write transactions from a PCI host bridge to system
+ memory. Posted write transactions are generated by PCI bus masters when they perform write
+ transactions to target addresses in system memory.
+ This function does not flush posted write transactions from any PCI bridges. A PCI controller
+ specific action must be taken to guarantee that the posted write transactions have been flushed from
+ the PCI controller and from all the PCI bridges into the PCI host bridge. This is typically done with
+ a PCI read transaction from the PCI controller prior to calling Flush().
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+
+ @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host
+ bridge to system memory.
+ @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI
+ host bridge due to a hardware error.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoFlush (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This
);
+/**
+ Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the
+ attributes that a PCI root bridge is currently using.
+
+ The GetAttributes() function returns the mask of attributes that this PCI root bridge supports
+ and the mask of attributes that the PCI root bridge is currently using.
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Supported A pointer to the mask of attributes that this PCI root bridge
+ supports setting with SetAttributes().
+ @param Attributes A pointer to the mask of attributes that this PCI root bridge is
+ currently using.
+
+ @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root
+ bridge supports is returned in Supports. If Attributes is
+ not NULL, then the attributes that the PCI root bridge is currently
+ using is returned in Attributes.
+ @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoGetAttributes (
@@ -178,6 +503,36 @@ RootBridgeIoGetAttributes ( OUT UINT64 *Attributes
);
+/**
+ Sets attributes for a resource range on a PCI root bridge.
+
+ The SetAttributes() function sets the attributes specified in Attributes for the PCI root
+ bridge on the resource range specified by ResourceBase and ResourceLength. Since the
+ granularity of setting these attributes may vary from resource type to resource type, and from
+ platform to platform, the actual resource range and the one passed in by the caller may differ. As a
+ result, this function may set the attributes specified by Attributes on a larger resource range
+ than the caller requested. The actual range is returned in ResourceBase and
+ ResourceLength. The caller is responsible for verifying that the actual range for which the
+ attributes were set is acceptable.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Attributes The mask of attributes to set. If the attribute bit
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, or
+ MEMORY_DISABLE is set, then the resource range is specified by
+ ResourceBase and ResourceLength. If
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, and
+ MEMORY_DISABLE are not set, then ResourceBase and
+ ResourceLength are ignored, and may be NULL.
+ @param[in][out] ResourceBase A pointer to the base address of the resource range to be modified
+ by the attributes specified by Attributes.
+ @param[in][out] ResourceLength A pointer to the length of the resource range to be modified by the
+ attributes specified by Attributes.
+
+ @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in Resources.
+ @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.
+ @retval EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoSetAttributes (
@@ -187,6 +542,29 @@ RootBridgeIoSetAttributes ( IN OUT UINT64 *ResourceLength
);
+/**
+ Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0
+ resource descriptors.
+
+ There are only two resource descriptor types from the ACPI Specification that may be used to
+ describe the current resources allocated to a PCI root bridge. These are the QWORD Address
+ Space Descriptor (ACPI 2.0 Section 6.4.3.5.1), and the End Tag (ACPI 2.0 Section 6.4.2.8). The
+ QWORD Address Space Descriptor can describe memory, I/O, and bus number ranges for dynamic
+ or fixed resources. The configuration of a PCI root bridge is described with one or more QWORD
+ Address Space Descriptors followed by an End Tag.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[out] Resources A pointer to the ACPI 2.0 resource descriptors that describe the
+ current configuration of this PCI root bridge. The storage for the
+ ACPI 2.0 resource descriptors is allocated by this function. The
+ caller must treat the return buffer as read-only data, and the buffer
+ must not be freed by the caller.
+
+ @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in Resources.
+ @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.
+ @retval EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoConfiguration (
@@ -197,6 +575,24 @@ RootBridgeIoConfiguration ( //
// Sub Function Prototypes
//
+/**
+ Internal help function for read and write PCI configuration space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Write Switch value for Read or Write.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] UserAddress The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] UserBuffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
RootBridgeIoPciRW (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
@@ -213,6 +609,18 @@ RootBridgeIoPciRW ( EFI_METRONOME_ARCH_PROTOCOL *mMetronome;
EFI_CPU_IO2_PROTOCOL *mCpuIo;
+/**
+
+ Construct the Pci Root Bridge Io protocol
+
+ @param Protocol Point to protocol instance
+ @param HostBridgeHandle Handle of host bridge
+ @param Attri Attribute of host bridge
+ @param ResAppeture ResourceAppeture for host bridge
+
+ @retval EFI_SUCCESS Success to initialize the Pci Root Bridge.
+
+**/
EFI_STATUS
RootBridgeConstructor (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *Protocol,
@@ -220,21 +628,6 @@ RootBridgeConstructor ( IN UINT64 Attri,
IN PCI_ROOT_BRIDGE_RESOURCE_APPETURE *ResAppeture
)
-/*++
-
-Routine Description:
-
- Construct the Pci Root Bridge Io protocol
-
-Arguments:
-
- Protocol - protocol to initialize
-
-Returns:
-
- None
-
---*/
{
EFI_STATUS Status;
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
@@ -322,6 +715,35 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Polls an address in memory mapped I/O space until an exit condition is met, or
+ a timeout occurs.
+
+ This function provides a standard way to poll a PCI memory location. A PCI memory read
+ operation is performed at the PCI memory address specified by Address for the width specified
+ by Width. The result of this PCI memory read operation is stored in Result. This PCI memory
+ read operation is repeated until either a timeout of Delay 100 ns units has expired, or (Result &
+ Mask) is equal to Value.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the memory operations. The caller is
+ responsible for aligning Address if required.
+ @param[in] Mask Mask used for the polling criteria. Bytes above Width in Mask
+ are ignored. The bits in the bytes below Width which are zero in
+ Mask are ignored when polling the memory address.
+ @param[in] Value The comparison value used for the polling exit criteria.
+ @param[in] Delay The number of 100 ns units to poll. Note that timer available may
+ be of poorer granularity.
+ @param[out] Result Pointer to the last value read from the memory location.
+
+ @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
+ @retval EFI_INVALID_PARAMETER Width is invalid.
+ @retval EFI_INVALID_PARAMETER Result is NULL.
+ @retval EFI_TIMEOUT Delay expired before a match occurred.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPollMem (
@@ -333,16 +755,6 @@ RootBridgeIoPollMem ( IN UINT64 Delay,
OUT UINT64 *Result
)
-/*++
-
-Routine Description:
- Memory Poll
-
-Arguments:
-
-Returns:
-
---*/
{
EFI_STATUS Status;
UINT64 NumberOfTicks;
@@ -406,6 +818,35 @@ Returns: return EFI_TIMEOUT;
}
+/**
+ Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is
+ satisfied or after a defined duration.
+
+ This function provides a standard way to poll a PCI I/O location. A PCI I/O read operation is
+ performed at the PCI I/O address specified by Address for the width specified by Width.
+ The result of this PCI I/O read operation is stored in Result. This PCI I/O read operation is
+ repeated until either a timeout of Delay 100 ns units has expired, or (Result & Mask) is equal
+ to Value.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the I/O operations.
+ @param[in] Address The base address of the I/O operations. The caller is responsible
+ for aligning Address if required.
+ @param[in] Mask Mask used for the polling criteria. Bytes above Width in Mask
+ are ignored. The bits in the bytes below Width which are zero in
+ Mask are ignored when polling the I/O address.
+ @param[in] Value The comparison value used for the polling exit criteria.
+ @param[in] Delay The number of 100 ns units to poll. Note that timer available may
+ be of poorer granularity.
+ @param[out] Result Pointer to the last value read from the memory location.
+
+ @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria.
+ @retval EFI_INVALID_PARAMETER Width is invalid.
+ @retval EFI_INVALID_PARAMETER Result is NULL.
+ @retval EFI_TIMEOUT Delay expired before a match occurred.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPollIo (
@@ -417,16 +858,6 @@ RootBridgeIoPollIo ( IN UINT64 Delay,
OUT UINT64 *Result
)
-/*++
-
-Routine Description:
- Io Poll
-
-Arguments:
-
-Returns:
-
---*/
{
EFI_STATUS Status;
UINT64 NumberOfTicks;
@@ -488,6 +919,29 @@ Returns: return EFI_TIMEOUT;
}
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
+
+ The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller
+ registers in the PCI root bridge memory space.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operation.
+ @param[in] Address The base address of the memory operation. The caller is
+ responsible for aligning the Address if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMemRead (
@@ -497,16 +951,6 @@ RootBridgeIoMemRead ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Memory read
-
-Arguments:
-
-Returns:
-
---*/
{
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH OldWidth;
@@ -546,6 +990,28 @@ Returns: Address, OldCount, Buffer);
}
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge memory space.
+
+ The Mem.Read(), and Mem.Write() functions enable a driver to access PCI controller
+ registers in the PCI root bridge memory space.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI Root Bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operation.
+ @param[in] Address The base address of the memory operation. The caller is
+ responsible for aligning the Address if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMemWrite (
@@ -555,16 +1021,6 @@ RootBridgeIoMemWrite ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Memory write
-
-Arguments:
-
-Returns:
-
---*/
{
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH OldWidth;
@@ -603,6 +1059,24 @@ Returns: Address, OldCount, Buffer);
}
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the I/O operation. The caller is responsible for
+ aligning the Address if required.
+ @param[in] Count The number of I/O operations to perform. Bytes moved is Width
+ size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoIoRead (
@@ -612,16 +1086,6 @@ RootBridgeIoIoRead ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Io read
-
-Arguments:
-
-Returns:
-
---*/
{
@@ -671,6 +1135,24 @@ Returns: }
+/**
+ Enables a PCI driver to access PCI controller registers in the PCI root bridge I/O space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The base address of the I/O operation. The caller is responsible for
+ aligning the Address if required.
+ @param[in] Count The number of I/O operations to perform. Bytes moved is Width
+ size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoIoWrite (
@@ -680,16 +1162,6 @@ RootBridgeIoIoWrite ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Io write
-
-Arguments:
-
-Returns:
-
---*/
{
UINTN AlignMask;
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
@@ -737,6 +1209,30 @@ Returns: }
+/**
+ Enables a PCI driver to copy one region of PCI root bridge memory space to another region of PCI
+ root bridge memory space.
+
+ The CopyMem() function enables a PCI driver to copy one region of PCI root bridge memory
+ space to another region of PCI root bridge memory space. This is especially useful for video scroll
+ operation on a memory mapped video buffer.
+ The memory operations are carried out exactly as requested. The caller is responsible for satisfying
+ any alignment and memory width restrictions that a PCI root bridge on a platform might require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] DestAddress The destination address of the memory operation. The caller is
+ responsible for aligning the DestAddress if required.
+ @param[in] SrcAddress The source address of the memory operation. The caller is
+ responsible for aligning the SrcAddress if required.
+ @param[in] Count The number of memory operations to perform. Bytes moved is
+ Width size * Count, starting at DestAddress and SrcAddress.
+
+ @retval EFI_SUCCESS The data was copied from one memory region to another memory region.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoCopyMem (
@@ -746,16 +1242,6 @@ RootBridgeIoCopyMem ( IN UINT64 SrcAddress,
IN UINTN Count
)
-/*++
-
-Routine Description:
- Memory copy
-
-Arguments:
-
-Returns:
-
---*/
{
EFI_STATUS Status;
BOOLEAN Direction;
@@ -812,6 +1298,29 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.
+
+ The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration
+ registers for a PCI controller.
+ The PCI Configuration operations are carried out exactly as requested. The caller is responsible for
+ any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might
+ require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPciRead (
@@ -821,16 +1330,6 @@ RootBridgeIoPciRead ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Pci read
-
-Arguments:
-
-Returns:
-
---*/
{
if (Buffer == NULL) {
@@ -846,6 +1345,29 @@ Returns: return RootBridgeIoPciRW (This, FALSE, Width, Address, Count, Buffer);
}
+/**
+ Enables a PCI driver to access PCI controller registers in a PCI root bridge's configuration space.
+
+ The Pci.Read() and Pci.Write() functions enable a driver to access PCI configuration
+ registers for a PCI controller.
+ The PCI Configuration operations are carried out exactly as requested. The caller is responsible for
+ any alignment and PCI configuration width issues that a PCI Root Bridge on a platform might
+ require.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] Address The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] Buffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoPciWrite (
@@ -855,16 +1377,6 @@ RootBridgeIoPciWrite ( IN UINTN Count,
IN OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Pci write
-
-Arguments:
-
-Returns:
-
---*/
{
if (Buffer == NULL) {
@@ -880,6 +1392,32 @@ Returns: return RootBridgeIoPciRW (This, TRUE, Width, Address, Count, Buffer);
}
+/**
+ Provides the PCI controller-specific addresses required to access system memory from a
+ DMA bus master.
+
+ The Map() function provides the PCI controller specific addresses needed to access system
+ memory. This function is used to map system memory for PCI bus master DMA accesses.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Operation Indicates if the bus master is going to read or write to system memory.
+ @param[in] HostAddress The system memory address to map to the PCI controller.
+ @param[in][out] NumberOfBytes On input the number of bytes to map. On output the number of bytes that were mapped.
+ @param[out] DeviceAddress The resulting map address for the bus master PCI controller to use
+ to access the system memory's HostAddress.
+ @param[out] Mapping The value to pass to Unmap() when the bus master DMA operation is complete.
+
+ @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
+ @retval EFI_INVALID_PARAMETER Operation is invalid.
+ @retval EFI_INVALID_PARAMETER HostAddress is NULL.
+ @retval EFI_INVALID_PARAMETER NumberOfBytes is NULL.
+ @retval EFI_INVALID_PARAMETER DeviceAddress is NULL.
+ @retval EFI_INVALID_PARAMETER Mapping is NULL.
+ @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
+ @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoMap (
@@ -890,7 +1428,6 @@ RootBridgeIoMap ( OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
OUT VOID **Mapping
)
-
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS PhysicalAddress;
@@ -999,13 +1536,28 @@ RootBridgeIoMap ( return EFI_SUCCESS;
}
+/**
+ Completes the Map() operation and releases any corresponding resources.
+
+ The Unmap() function completes the Map() operation and releases any corresponding resources.
+ If the operation was an EfiPciOperationBusMasterWrite or
+ EfiPciOperationBusMasterWrite64, the data is committed to the target system memory.
+ Any resources used for the mapping are freed.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Mapping The mapping value returned from Map().
+
+ @retval EFI_SUCCESS The range was unmapped.
+ @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
+ @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoUnmap (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
IN VOID *Mapping
)
-
{
MAP_INFO *MapInfo;
@@ -1041,6 +1593,27 @@ RootBridgeIoUnmap ( return EFI_SUCCESS;
}
+/**
+ Allocates pages that are suitable for an EfiPciOperationBusMasterCommonBuffer or
+ EfiPciOperationBusMasterCommonBuffer64 mapping.
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Type This parameter is not used and must be ignored.
+ @param MemoryType The type of memory to allocate, EfiBootServicesData or EfiRuntimeServicesData.
+ @param Pages The number of pages to allocate.
+ @param HostAddress A pointer to store the base system memory address of the allocated range.
+ @param Attributes The requested bit mask of attributes for the allocated range. Only
+ the attributes EFI_PCI_ATTRIBUTE_MEMORY_WRITE_COMBINE, EFI_PCI_ATTRIBUTE_MEMORY_CACHED,
+ and EFI_PCI_ATTRIBUTE_DUAL_ADDRESS_CYCLE may be used with this function.
+
+ @retval EFI_SUCCESS The requested memory pages were allocated.
+ @retval EFI_INVALID_PARAMETER MemoryType is invalid.
+ @retval EFI_INVALID_PARAMETER HostAddress is NULL.
+ @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, and DUAL_ADDRESS_CYCLE.
+ @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoAllocateBuffer (
@@ -1051,7 +1624,6 @@ RootBridgeIoAllocateBuffer ( OUT VOID **HostAddress,
IN UINT64 Attributes
)
-
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS PhysicalAddress;
@@ -1092,6 +1664,20 @@ RootBridgeIoAllocateBuffer ( return EFI_SUCCESS;
}
+/**
+ Frees memory that was allocated with AllocateBuffer().
+
+ The FreeBuffer() function frees memory that was allocated with AllocateBuffer().
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Pages The number of pages to free.
+ @param HostAddress The base system memory address of the allocated range.
+
+ @retval EFI_SUCCESS The requested memory pages were freed.
+ @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
+ was not allocated with AllocateBuffer().
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoFreeBuffer (
@@ -1099,25 +1685,34 @@ RootBridgeIoFreeBuffer ( IN UINTN Pages,
OUT VOID *HostAddress
)
-
{
return gBS->FreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) HostAddress, Pages);
}
+/**
+ Flushes all PCI posted write transactions from a PCI host bridge to system memory.
+
+ The Flush() function flushes any PCI posted write transactions from a PCI host bridge to system
+ memory. Posted write transactions are generated by PCI bus masters when they perform write
+ transactions to target addresses in system memory.
+ This function does not flush posted write transactions from any PCI bridges. A PCI controller
+ specific action must be taken to guarantee that the posted write transactions have been flushed from
+ the PCI controller and from all the PCI bridges into the PCI host bridge. This is typically done with
+ a PCI read transaction from the PCI controller prior to calling Flush().
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+
+ @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host
+ bridge to system memory.
+ @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI
+ host bridge due to a hardware error.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoFlush (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This
)
-/*++
-
-Routine Description:
-
-Arguments:
-
-Returns:
-
---*/
{
//
// not supported yet
@@ -1125,6 +1720,26 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Gets the attributes that a PCI root bridge supports setting with SetAttributes(), and the
+ attributes that a PCI root bridge is currently using.
+
+ The GetAttributes() function returns the mask of attributes that this PCI root bridge supports
+ and the mask of attributes that the PCI root bridge is currently using.
+
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Supported A pointer to the mask of attributes that this PCI root bridge
+ supports setting with SetAttributes().
+ @param Attributes A pointer to the mask of attributes that this PCI root bridge is
+ currently using.
+
+ @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI root
+ bridge supports is returned in Supports. If Attributes is
+ not NULL, then the attributes that the PCI root bridge is currently
+ using is returned in Attributes.
+ @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoGetAttributes (
@@ -1132,15 +1747,6 @@ RootBridgeIoGetAttributes ( OUT UINT64 *Supported,
OUT UINT64 *Attributes
)
-/*++
-
-Routine Description:
-
-Arguments:
-
-Returns:
-
---*/
{
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
@@ -1164,6 +1770,36 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Sets attributes for a resource range on a PCI root bridge.
+
+ The SetAttributes() function sets the attributes specified in Attributes for the PCI root
+ bridge on the resource range specified by ResourceBase and ResourceLength. Since the
+ granularity of setting these attributes may vary from resource type to resource type, and from
+ platform to platform, the actual resource range and the one passed in by the caller may differ. As a
+ result, this function may set the attributes specified by Attributes on a larger resource range
+ than the caller requested. The actual range is returned in ResourceBase and
+ ResourceLength. The caller is responsible for verifying that the actual range for which the
+ attributes were set is acceptable.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Attributes The mask of attributes to set. If the attribute bit
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, or
+ MEMORY_DISABLE is set, then the resource range is specified by
+ ResourceBase and ResourceLength. If
+ MEMORY_WRITE_COMBINE, MEMORY_CACHED, and
+ MEMORY_DISABLE are not set, then ResourceBase and
+ ResourceLength are ignored, and may be NULL.
+ @param[in][out] ResourceBase A pointer to the base address of the resource range to be modified
+ by the attributes specified by Attributes.
+ @param[in][out] ResourceLength A pointer to the length of the resource range to be modified by the
+ attributes specified by Attributes.
+
+ @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in Resources.
+ @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.
+ @retval EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoSetAttributes (
@@ -1172,15 +1808,6 @@ RootBridgeIoSetAttributes ( IN OUT UINT64 *ResourceBase,
IN OUT UINT64 *ResourceLength
)
-/*++
-
-Routine Description:
-
-Arguments:
-
-Returns:
-
---*/
{
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
@@ -1205,21 +1832,35 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Retrieves the current resource settings of this PCI root bridge in the form of a set of ACPI 2.0
+ resource descriptors.
+
+ There are only two resource descriptor types from the ACPI Specification that may be used to
+ describe the current resources allocated to a PCI root bridge. These are the QWORD Address
+ Space Descriptor (ACPI 2.0 Section 6.4.3.5.1), and the End Tag (ACPI 2.0 Section 6.4.2.8). The
+ QWORD Address Space Descriptor can describe memory, I/O, and bus number ranges for dynamic
+ or fixed resources. The configuration of a PCI root bridge is described with one or more QWORD
+ Address Space Descriptors followed by an End Tag.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[out] Resources A pointer to the ACPI 2.0 resource descriptors that describe the
+ current configuration of this PCI root bridge. The storage for the
+ ACPI 2.0 resource descriptors is allocated by this function. The
+ caller must treat the return buffer as read-only data, and the buffer
+ must not be freed by the caller.
+
+ @retval EFI_SUCCESS The current configuration of this PCI root bridge was returned in Resources.
+ @retval EFI_UNSUPPORTED The current configuration of this PCI root bridge could not be retrieved.
+ @retval EFI_INVALID_PARAMETER Invalid pointer of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
+
+**/
EFI_STATUS
EFIAPI
RootBridgeIoConfiguration (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
OUT VOID **Resources
)
-/*++
-
-Routine Description:
-
-Arguments:
-
-Returns:
-
---*/
{
PCI_ROOT_BRIDGE_INSTANCE *PrivateData;
UINTN Index;
@@ -1241,6 +1882,24 @@ Returns: //
// Internal function
//
+/**
+ Internal help function for read and write PCI configuration space.
+
+ @param[in] This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param[in] Write Switch value for Read or Write.
+ @param[in] Width Signifies the width of the memory operations.
+ @param[in] UserAddress The address within the PCI configuration space for the PCI controller.
+ @param[in] Count The number of PCI configuration operations to perform. Bytes
+ moved is Width size * Count, starting at Address.
+ @param[out] UserBuffer For read operations, the destination buffer to store the results. For
+ write operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Width is invalid for this PCI root bridge.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+
+**/
EFI_STATUS
RootBridgeIoPciRW (
IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *This,
|