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
