diff options
author | Ruiyu Ni <ruiyu.ni@intel.com> | 2016-02-25 09:14:29 +0800 |
---|---|---|
committer | Hao Wu <hao.a.wu@intel.com> | 2016-03-04 10:48:31 +0800 |
commit | 3eb9d5cc5d91bcd1f14ea591b68dd1e69e5eb416 (patch) | |
tree | d7b71362c469c1c265a04e85be4aef3d3751a435 /MdeModulePkg | |
parent | 88e61ced4642aad305e7ff455616253b55e7d742 (diff) | |
download | edk2-platforms-3eb9d5cc5d91bcd1f14ea591b68dd1e69e5eb416.tar.xz |
MdeModulePkg/PciHostBridge: Refine function header comments.
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Shumin Qiu <shumin.qiu@intel.com>
Reviewed-by: Qiu Shumin <shumin.qiu@intel.com>
(cherry picked from commit 63b90643afb19f84e4cd3681a9a402ec65b1cf8d)
Diffstat (limited to 'MdeModulePkg')
4 files changed, 103 insertions, 81 deletions
diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c index 08285d84d5..edf042cc25 100644 --- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c +++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.c @@ -258,6 +258,19 @@ ResourceConflict ( FreePool (Resources);
}
+/**
+ Allocate Length of MMIO or IO resource with alignment BitsOfAlignment
+ from GCD range [BaseAddress, Limit).
+
+ @param Mmio TRUE for MMIO and FALSE for IO.
+ @param Length Length of the resource to allocate.
+ @param BitsOfAlignment Alignment of the resource to allocate.
+ @param BaseAddress The starting address the allocation is from.
+ @param Limit The ending address the allocation is to.
+
+ @retval The base address of the allocated resource or MAX_UINT64 if allocation
+ fails.
+**/
UINT64
AllocateResource (
BOOLEAN Mmio,
@@ -306,6 +319,7 @@ AllocateResource ( }
return MAX_UINT64;
}
+
/**
Enter a certain phase of the PCI enumeration process.
diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h index 288823c778..9a8ca21f48 100644 --- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h +++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciHostBridge.h @@ -65,12 +65,12 @@ InitializePciHostBridge ( Enter a certain phase of the PCI enumeration process.
- @param This - The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
- @param Phase - The phase during enumeration.
+ @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.
+ @param Phase The phase during enumeration.
- @retval EFI_SUCCESS - Succeed.
- @retval EFI_INVALID_PARAMETER - Wrong phase parameter passed in.
- @retval EFI_NOT_READY - Resources have not been submitted yet.
+ @retval EFI_SUCCESS Succeed.
+ @retval EFI_INVALID_PARAMETER Wrong phase parameter passed in.
+ @retval EFI_NOT_READY Resources have not been submitted yet.
**/
EFI_STATUS
@@ -85,15 +85,15 @@ NotifyPhase ( Return the device handle of the next PCI root bridge that is associated with
this Host Bridge.
- @param 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.
+ @param This The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.
+ @param 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.
- @retval EFI_SUCCESS - Succeed.
- @retval EFI_NOT_FOUND - Next PCI root bridge not found.
- @retval EFI_INVALID_PARAMETER - Wrong parameter passed in.
+ @retval EFI_SUCCESS Succeed.
+ @retval EFI_NOT_FOUND Next PCI root bridge not found.
+ @retval EFI_INVALID_PARAMETER Wrong parameter passed in.
**/
EFI_STATUS
diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h index 2915981ea5..b1e83f1c90 100644 --- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h +++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridge.h @@ -86,15 +86,13 @@ typedef struct { #define ROOT_BRIDGE_FROM_LINK(a) CR (a, PCI_ROOT_BRIDGE_INSTANCE, Link, PCI_ROOT_BRIDGE_SIGNATURE)
/**
+ Construct the Pci Root Bridge instance.
- Construct the Pci Root Bridge Io protocol.
-
- @param Protocol - Protocol to initialize.
- @param HostBridgeHandle - Handle to the HostBridge.
-
- @retval EFI_SUCCESS - Success.
- @retval Others - Fail.
+ @param Bridge The root bridge instance.
+ @param HostBridgeHandle Handle to the HostBridge.
+ @return The pointer to PCI_ROOT_BRIDGE_INSTANCE just created
+ or NULL if creation fails.
**/
PCI_ROOT_BRIDGE_INSTANCE *
CreateRootBridge (
@@ -359,30 +357,25 @@ RootBridgeIoPciWrite ( ;
/**
-
Provides the PCI controller-specific address needed to access
system memory for DMA.
- @param This - A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
- @param Operation - Indicate if the bus master is going to read or write
- to system memory.
- @param HostAddress - The system memory address to map on the PCI controller.
- @param NumberOfBytes - On input the number of bytes to map.
- On output the number of bytes that were mapped.
- @param DeviceAddress - The resulting map address for the bus master PCI
- controller to use to access the system memory's HostAddress.
- @param Mapping - The value to pass to Unmap() when the bus master DMA
- operation is complete.
-
- @retval EFI_SUCCESS - Success.
- @retval EFI_INVALID_PARAMETER - Invalid parameters found.
- @retval EFI_UNSUPPORTED - The HostAddress cannot be mapped as a common
- @retval buffer.
- @retval EFI_DEVICE_ERROR - The System hardware could not map the requested
- @retval address.
- @retval EFI_OUT_OF_RESOURCES - The request could not be completed due to
- @retval lack of resources.
-
+ @param This A pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.
+ @param Operation Indicate if the bus master is going to read or write
+ to system memory.
+ @param HostAddress The system memory address to map on the PCI controller.
+ @param NumberOfBytes On input the number of bytes to map.
+ On output the number of bytes that were mapped.
+ @param DeviceAddress The resulting map address for the bus master PCI
+ controller to use to access the system memory's HostAddress.
+ @param Mapping The value to pass to Unmap() when the bus master DMA
+ operation is complete.
+
+ @retval EFI_SUCCESS Success.
+ @retval EFI_INVALID_PARAMETER Invalid parameters found.
+ @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 lack of resources.
**/
EFI_STATUS
EFIAPI
@@ -397,18 +390,21 @@ RootBridgeIoMap ( ;
/**
-
Completes the Map() operation and releases any corresponding resources.
- @param This - Pointer to the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL instance.
- Mapping - The value returned from Map() operation.
+ 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.
- @retval EFI_SUCCESS - The range was unmapped successfully.
- @retval EFI_INVALID_PARAMETER - Mapping is not a value that was returned
- @retval by Map operation.
- @retval EFI_DEVICE_ERROR - The data was not committed to the target
- @retval system memory.
+ @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
@@ -419,22 +415,30 @@ RootBridgeIoUnmap ( ;
/**
-
- Allocates pages that are suitable for a common buffer mapping.
-
- @param This - Pointer to EFI_ROOT_BRIDGE_IO_PROTOCOL instance.
- @param Type - Not used and can be ignored.
- @param MemoryType - Type of memory to allocate.
- @param Pages - Number of pages to allocate.
- @param HostAddress - Pointer to store the base system memory address
- of the allocated range.
- @param Attributes - Requested bit mask of attributes of the allocated
- range.
-
- @retval EFI_SUCCESS - The requested memory range were allocated.
- @retval EFI_INVALID_PARAMETER - Invalid parameter found.
- @retval EFI_UNSUPPORTED - Attributes is unsupported.
-
+ 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
@@ -491,19 +495,26 @@ RootBridgeIoFlush ( ;
/**
-
- Get the attributes that a PCI root bridge supports and
- the attributes the PCI root bridge is currently using.
-
- @param This - Pointer to EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
- instance.
- @param Supports - A pointer to the mask of attributes that
- this PCI root bridge supports.
- @param Attributes - A pointer to the mask of attributes that
- this PCI root bridge is currently using.
- @retval EFI_SUCCESS - Success.
- @retval EFI_INVALID_PARAMETER - Invalid parameter found.
-
+ 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
diff --git a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c index 6a9294d349..332860eb38 100644 --- a/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c +++ b/MdeModulePkg/Bus/Pci/PciHostBridgeDxe/PciRootBridgeIo.c @@ -399,7 +399,6 @@ RootBridgeIoCheckParameter ( @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a
lack of resources.
**/
-
EFI_STATUS
EFIAPI
RootBridgeIoPollMem (
@@ -987,7 +986,6 @@ RootBridgeIoPciWrite ( }
/**
-
Provides the PCI controller-specific address needed to access
system memory for DMA.
@@ -1007,7 +1005,6 @@ RootBridgeIoPciWrite ( @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 lack of resources.
-
**/
EFI_STATUS
EFIAPI
|