From 63b90643afb19f84e4cd3681a9a402ec65b1cf8d Mon Sep 17 00:00:00 2001 From: Ruiyu Ni Date: Thu, 25 Feb 2016 09:14:29 +0800 Subject: [PATCH] MdeModulePkg/PciHostBridge: Refine function header comments. Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Ruiyu Ni Cc: Shumin Qiu Reviewed-by: Qiu Shumin --- .../Bus/Pci/PciHostBridgeDxe/PciHostBridge.c | 14 ++ .../Bus/Pci/PciHostBridgeDxe/PciHostBridge.h | 26 ++-- .../Bus/Pci/PciHostBridgeDxe/PciRootBridge.h | 141 ++++++++++-------- .../Pci/PciHostBridgeDxe/PciRootBridgeIo.c | 3 - 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 -- 2.39.2