From 18c97f53ea089437a3e053c834deb737ccbc9576 Mon Sep 17 00:00:00 2001 From: klu2 Date: Mon, 12 Apr 2010 04:38:44 +0000 Subject: 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 --- PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c | 395 ++++++--- .../PciHostBridgeDxe/PciHostBridgeDxe.inf | 4 +- PcAtChipsetPkg/PciHostBridgeDxe/PciRootBridgeIo.c | 965 +++++++++++++++++---- 3 files changed, 1073 insertions(+), 291 deletions(-) (limited to 'PcAtChipsetPkg/PciHostBridgeDxe') 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
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.
+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.
-# All rights reserved. This program and the accompanying materials +# Copyright (c) 2008 - 2010, Intel Corporation. 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 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
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.
+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, -- cgit v1.2.3