Thank you! Regards, Ray
>-----Original Message----- >From: Laszlo Ersek [mailto:[email protected]] >Sent: Friday, February 26, 2016 8:30 PM >To: Qiu, Shumin <[email protected]>; Ni, Ruiyu <[email protected]>; >[email protected] ><[email protected]> >Subject: Re: [edk2] [Patch] MdeModulePkg/PciHostBridge: Refine function header >comments. > >On 02/25/16 04:13, Qiu, Shumin wrote: >> Reviewed-by: Qiu Shumin <[email protected]> > >Committed as 63b90643afb19f84e4cd3681a9a402ec65b1cf8d. > >Thanks >Laszlo > >> >> -----Original Message----- >> From: Ni, Ruiyu >> Sent: Thursday, February 25, 2016 9:14 AM >> To: [email protected] >> Cc: Ni, Ruiyu; Qiu, Shumin >> Subject: [Patch] MdeModulePkg/PciHostBridge: Refine function header comments. >> >> Contributed-under: TianoCore Contribution Agreement 1.0 >> Signed-off-by: Ruiyu Ni <[email protected]> >> Cc: Shumin Qiu <[email protected]> >> --- >> .../Bus/Pci/PciHostBridgeDxe/PciHostBridge.c | 14 ++ >> .../Bus/Pci/PciHostBridgeDxe/PciHostBridge.h | 26 ++-- >> .../Bus/Pci/PciHostBridgeDxe/PciRootBridge.h | 141 >> +++++++++++---------- >> .../Bus/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 08285d8..edf042c 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 288823c..9a8ca21 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 2915981..b1e83f1 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 6a9294d..332860e 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.7.0.windows.1 >> >> _______________________________________________ >> edk2-devel mailing list >> [email protected] >> https://lists.01.org/mailman/listinfo/edk2-devel >> _______________________________________________ edk2-devel mailing list [email protected] https://lists.01.org/mailman/listinfo/edk2-devel
