mirror of https://github.com/acidanthera/audk.git
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>
This commit is contained in:
Ruiyu Ni
Laszlo Ersek
parent
762d8ddb28
commit
63b90643af
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 an EfiPciOperationBusMasterCommonBuffer
|
||||
or EfiPciOperationBusMasterCommonBuffer64 mapping.
|
||||
|
||||
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.
|
||||
@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 (
|
|||
;
|
||||
|
||||
/**
|
||||
Gets the attributes that a PCI root bridge supports setting with
|
||||
SetAttributes(), and the attributes that a PCI root bridge is currently
|
||||
using.
|
||||
|
||||
Get the attributes that a PCI root bridge supports and
|
||||
the attributes the 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 - 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.
|
||||
@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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue