From: Dandan Bi <dandan.bi@intel.com>
To: edk2-devel@lists.01.org
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>,
Ruiyu Ni <ruiyu.ni@intel.com>
Subject: [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions
Date: Fri, 16 Dec 2016 10:25:35 +0800 [thread overview]
Message-ID: <1481855136-115456-2-git-send-email-dandan.bi@intel.com> (raw)
In-Reply-To: <1481855136-115456-1-git-send-email-dandan.bi@intel.com>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Dandan Bi <dandan.bi@intel.com>
---
.../NonDiscoverablePciDeviceDxe/ComponentName.c | 47 +++
.../NonDiscoverablePciDeviceDxe.c | 50 ++-
.../NonDiscoverablePciDeviceDxe.inf | 18 +-
.../NonDiscoverablePciDeviceIo.c | 362 ++++++++++++++++++++-
.../NonDiscoverablePciDeviceIo.h | 6 +
5 files changed, 469 insertions(+), 14 deletions(-)
diff --git a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/ComponentName.c b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/ComponentName.c
index 6e51d00..0e6ebec 100644
--- a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/ComponentName.c
+++ b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/ComponentName.c
@@ -28,10 +28,31 @@ EFI_UNICODE_STRING_TABLE mDriverNameTable[] = {
{ NULL, NULL }
};
EFI_COMPONENT_NAME_PROTOCOL gComponentName;
+/**
+ Retrieves a Unicode string that is the user readable name of the UEFI Driver.
+
+ @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+ @param Language A pointer to a three character ISO 639-2 language identifier.
+ This is the language of the driver name that that the caller
+ is requesting, and it must match one of the languages specified
+ in SupportedLanguages. The number of languages supported by a
+ driver is up to the driver writer.
+ @param DriverName A pointer to the Unicode string to return. This Unicode string
+ is the name of the driver specified by This in the language
+ specified by Language.
+
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by This
+ and the language specified by Language was returned
+ in DriverName.
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+**/
STATIC
EFI_STATUS
EFIAPI
NonDiscoverablePciGetDriverName (
IN EFI_COMPONENT_NAME_PROTOCOL *This,
@@ -46,10 +67,36 @@ NonDiscoverablePciGetDriverName (
DriverName,
(BOOLEAN)(This == &gComponentName) // Iso639Language
);
}
+/**
+ Retrieves a Unicode string that is the user readable name of the controller
+ that is being managed by an UEFI Driver.
+
+ @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+ @param DeviceHandle The handle of a controller that the driver specified by
+ This is managing. This handle specifies the controller
+ whose name is to be returned.
+ @param ChildHandle The handle of the child controller to retrieve the name
+ of. This is an optional parameter that may be NULL. It
+ will be NULL for device drivers. It will also be NULL
+ for a bus drivers that wish to retrieve the name of the
+ bus controller. It will not be NULL for a bus driver
+ that wishes to retrieve the name of a child controller.
+ @param Language A pointer to a three character ISO 639-2 language
+ identifier. This is the language of the controller name
+ that that the caller is requesting, and it must match one
+ of the languages specified in SupportedLanguages. The
+ number of languages supported by a driver is up to the
+ driver writer.
+ @param ControllerName A pointer to the Unicode string to return. This Unicode
+ string is the name of the controller specified by
+ ControllerHandle and ChildHandle in the language
+ specified by Language from the point of view of the
+ driver specified by This.
+**/
STATIC
EFI_STATUS
EFIAPI
NonDiscoverablePciGetDeviceName (
IN EFI_COMPONENT_NAME_PROTOCOL *This,
diff --git a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.c b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.c
index 0fcf2b2..876e99f 100644
--- a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.c
+++ b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.c
@@ -47,10 +47,23 @@ SupportedNonDiscoverableDevices [] = {
// - 5.1.3.4 OpenProtocol() and CloseProtocol()
// - UEFI Spec 2.3.1 + Errata C
// - 6.3 Protocol Handler Services
//
+/**
+ Supported function of Driver Binding protocol for this driver.
+ Test to see if this driver supports ControllerHandle.
+
+ @param This Protocol instance pointer.
+ @param DeviceHandle Handle of device to test.
+ @param RemainingDevicePath A pointer to the device path.
+ it should be ignored by device driver.
+
+ @retval EFI_SUCCESS This driver supports this device.
+ @retval other This driver does not support this device.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonDiscoverablePciDeviceSupported (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
@@ -101,10 +114,23 @@ CloseProtocol:
This->DriverBindingHandle, DeviceHandle);
return Status;
}
+/**
+ This routine is called right after the .Supported() called and
+ Start this driver on ControllerHandle.
+
+ @param This Protocol instance pointer.
+ @param DeviceHandle Handle of device to bind driver to.
+ @param RemainingDevicePath A pointer to the device path.
+ it should be ignored by device driver.
+
+ @retval EFI_SUCCESS This driver is added to this device.
+ @retval other Some error occurs when binding this driver to this device.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonDiscoverablePciDeviceStart (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
@@ -151,11 +177,22 @@ FreeDev:
FreePool (Dev);
return Status;
}
+/**
+ Stop this driver on ControllerHandle.
+
+ @param This Protocol instance pointer.
+ @param DeviceHandle Handle of device to stop driver on.
+ @param NumberOfChildren Not used.
+ @param ChildHandleBuffer Not used.
+ @retval EFI_SUCCESS This driver is removed from this device.
+ @retval other Some error occurs when removing this driver from this device.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonDiscoverablePciDeviceStop (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
@@ -207,13 +244,20 @@ STATIC EFI_DRIVER_BINDING_PROTOCOL gDriverBinding = {
0x10, // Version, must be in [0x10 .. 0xFFFFFFEF] for IHV-developed drivers
NULL,
NULL
};
-//
-// Entry point of this driver.
-//
+/**
+ Entry point of this driver.
+
+ @param ImageHandle Image handle this driver.
+ @param SystemTable Pointer to the System Table.
+
+ @retval EFI_SUCCESS The entry point is executed successfully.
+ @retval other Some error occurred when executing this entry point.
+
+**/
EFI_STATUS
EFIAPI
NonDiscoverablePciDeviceDxeEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
diff --git a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.inf b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.inf
index 5faa894..ac551a8 100644
--- a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.inf
+++ b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceDxe.inf
@@ -1,6 +1,8 @@
## @file
+# PCI I/O driver for non-discoverable devices.
+#
# Copyright (C) 2016, Linaro Ltd.
#
# This program and the accompanying materials are licensed and made available
# under the terms and conditions of the BSD License which accompanies this
# distribution. The full text of the license may be found at
@@ -42,13 +44,13 @@ [Protocols]
gEfiPciIoProtocolGuid ## BY_START
gEdkiiNonDiscoverableDeviceProtocolGuid ## TO_START
gEfiCpuArchProtocolGuid ## CONSUMES
[Guids]
- gEdkiiNonDiscoverableAhciDeviceGuid
- gEdkiiNonDiscoverableEhciDeviceGuid
- gEdkiiNonDiscoverableNvmeDeviceGuid
- gEdkiiNonDiscoverableOhciDeviceGuid
- gEdkiiNonDiscoverableSdhciDeviceGuid
- gEdkiiNonDiscoverableUfsDeviceGuid
- gEdkiiNonDiscoverableUhciDeviceGuid
- gEdkiiNonDiscoverableXhciDeviceGuid
+ gEdkiiNonDiscoverableAhciDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableEhciDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableNvmeDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableOhciDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableSdhciDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableUfsDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableUhciDeviceGuid ## CONSUMES ## GUID
+ gEdkiiNonDiscoverableXhciDeviceGuid ## CONSUMES ## GUID
diff --git a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.c b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.c
index f9b13a5..1ffbdfa 100644
--- a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.c
+++ b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.c
@@ -26,13 +26,18 @@ typedef struct {
VOID *HostAddress;
EFI_PCI_IO_PROTOCOL_OPERATION Operation;
UINTN NumberOfBytes;
} NON_DISCOVERABLE_PCI_DEVICE_MAP_INFO;
-//
-// Get the resource associated with BAR number 'BarIndex'.
-//
+/**
+ Get the resource associated with BAR number 'BarIndex'.
+
+ @param Dev Point to the NON_DISCOVERABLE_PCI_DEVICE instance.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory operation to perform.
+ @param Descriptor Points to the address space descriptor
+**/
STATIC
EFI_STATUS
GetBarResource (
IN NON_DISCOVERABLE_PCI_DEVICE *Dev,
IN UINT8 BarIndex,
@@ -59,10 +64,25 @@ GetBarResource (
BarIndex -= 1;
}
return EFI_NOT_FOUND;
}
+/**
+ Reads from the memory space of a PCI controller. Returns either when the polling exit criteria is
+ satisfied or after a defined duration.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory operation to perform.
+ @param Offset The offset within the selected BAR to start the memory operation.
+ @param Mask Mask used for the polling criteria.
+ @param Value The comparison value used for the polling exit criteria.
+ @param Delay The number of 100 ns units to poll.
+ @param Result Pointer to the last value read from the memory location.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoPollMem (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -77,10 +97,25 @@ PciIoPollMem (
{
ASSERT (FALSE);
return EFI_UNSUPPORTED;
}
+/**
+ Reads from the memory space of a PCI controller. Returns either when the polling exit criteria is
+ satisfied or after a defined duration.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory operation to perform.
+ @param Offset The offset within the selected BAR to start the memory operation.
+ @param Mask Mask used for the polling criteria.
+ @param Value The comparison value used for the polling exit criteria.
+ @param Delay The number of 100 ns units to poll.
+ @param Result Pointer to the last value read from the memory location.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoPollIo (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -95,10 +130,26 @@ PciIoPollIo (
{
ASSERT (FALSE);
return EFI_UNSUPPORTED;
}
+/**
+ Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space.
+
+ @param Width Signifies the width of the memory or I/O operations.
+ @param Count The number of memory or I/O operations to perform.
+ @param DstStride The stride of the destination buffer.
+ @param Dst For read operations, the destination buffer to store the results. For write
+ operations, the destination buffer to write data to.
+ @param SrcStride The stride of the source buffer.
+ @param Src For read operations, the source buffer to read data from. For write
+ operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI controller.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoMemRW (
IN EFI_PCI_IO_PROTOCOL_WIDTH Width,
@@ -146,10 +197,30 @@ PciIoMemRW (
}
return EFI_SUCCESS;
}
+/**
+ Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory or I/O operation to perform.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI controller.
+ @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
+ @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not
+ valid for the PCI BAR specified by BarIndex.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoMemRead (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -213,10 +284,30 @@ PciIoMemRead (
break;
}
return EFI_INVALID_PARAMETER;
}
+/**
+ Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory or I/O operation to perform.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from.
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI controller.
+ @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
+ @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not
+ valid for the PCI BAR specified by BarIndex.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoMemWrite (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -280,10 +371,23 @@ PciIoMemWrite (
break;
}
return EFI_INVALID_PARAMETER;
}
+/**
+ Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory or I/O operation to perform.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoIoRead (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -296,10 +400,23 @@ PciIoIoRead (
{
ASSERT (FALSE);
return EFI_UNSUPPORTED;
}
+/**
+ Enable a PCI driver to access PCI controller registers in the PCI memory or I/O space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for the memory or I/O operation to perform.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoIoWrite (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -312,10 +429,21 @@ PciIoIoWrite (
{
ASSERT (FALSE);
return EFI_UNSUPPORTED;
}
+/**
+ Enable a PCI driver to access PCI config space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoPciRead (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -348,10 +476,26 @@ PciIoPciRead (
Count -= Length >> ((UINTN)Width & 0x3);
}
return PciIoMemRW (Width, Count, 1, Buffer, 1, Address);
}
+/**
+ Enable a PCI driver to access PCI config space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory or I/O operations.
+ @param Offset The offset within the selected BAR to start the memory or I/O operation.
+ @param Count The number of memory or I/O operations to perform.
+ @param Buffer For read operations, the destination buffer to store the results. For write
+ operations, the source buffer to write data from
+
+ @retval EFI_SUCCESS The data was read from or written to the PCI controller.
+ @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not
+ valid for the PCI BAR specified by BarIndex.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoPciWrite (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -376,10 +520,28 @@ PciIoPciWrite (
}
return PciIoMemRW (Width, Count, 1, Address, 1, Buffer);
}
+/**
+ Enables a PCI driver to copy one region of PCI memory space to another region of PCI
+ memory space.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Width Signifies the width of the memory operations.
+ @param DestBarIndex The BAR index in the standard PCI Configuration header to use as the
+ base address for the memory operation to perform.
+ @param DestOffset The destination offset within the BAR specified by DestBarIndex to
+ start the memory writes for the copy operation.
+ @param SrcBarIndex The BAR index in the standard PCI Configuration header to use as the
+ base address for the memory operation to perform.
+ @param SrcOffset The source offset within the BAR specified by SrcBarIndex to start
+ the memory reads for the copy operation.
+ @param Count The number of memory operations to perform. Bytes moved is Width
+ size * Count, starting at DestOffset and SrcOffset.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoCopyMem (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -393,10 +555,29 @@ PciIoCopyMem (
{
ASSERT (FALSE);
return EFI_UNSUPPORTED;
}
+/**
+ Provides the PCI controller-specific addresses needed to access system memory.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Operation Indicates if the bus master is going to read or write to system memory.
+ @param HostAddress The system memory address to map to 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 hosts HostAddress.
+ @param Mapping A resulting value to pass to Unmap().
+
+ @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
+ @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+ @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
+
+**/
STATIC
EFI_STATUS
EFIAPI
CoherentPciIoMap (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -459,10 +640,19 @@ CoherentPciIoMap (
*Mapping = NULL;
}
return EFI_SUCCESS;
}
+/**
+ Completes the Map() operation and releases any corresponding resources.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Mapping The mapping value returned from Map().
+
+ @retval EFI_SUCCESS The range was unmapped.
+
+**/
STATIC
EFI_STATUS
EFIAPI
CoherentPciIoUnmap (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -482,10 +672,29 @@ CoherentPciIoUnmap (
FreePool (MapInfo);
}
return EFI_SUCCESS;
}
+/**
+ Allocates pages.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @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.
+
+ @retval EFI_SUCCESS The requested memory pages were allocated.
+ @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
+ MEMORY_WRITE_COMBINE and MEMORY_CACHED.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
+
+**/
STATIC
EFI_STATUS
EFIAPI
CoherentPciIoAllocateBuffer (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -524,10 +733,20 @@ CoherentPciIoAllocateBuffer (
*HostAddress = (VOID *)(UINTN)AllocAddress;
}
return Status;
}
+/**
+ Frees memory that was allocated in function CoherentPciIoAllocateBuffer ().
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Pages The number of pages to free.
+ @param HostAddress The base system memory address of the allocated range.
+
+ @retval EFI_SUCCESS The requested memory pages were freed.
+
+**/
STATIC
EFI_STATUS
EFIAPI
CoherentPciIoFreeBuffer (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -537,10 +756,21 @@ CoherentPciIoFreeBuffer (
{
FreePages (HostAddress, Pages);
return EFI_SUCCESS;
}
+/**
+ Frees memory that was allocated in function NonCoherentPciIoAllocateBuffer ().
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Pages The number of pages to free.
+ @param HostAddress The base system memory address of the allocated range.
+
+ @retval EFI_SUCCESS The requested memory pages were freed.
+ @retval others The operation contain some errors.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonCoherentPciIoFreeBuffer (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -602,10 +832,29 @@ NonCoherentPciIoFreeBuffer (
FreeAlloc:
FreePool (Alloc);
return Status;
}
+/**
+ Allocates pages.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @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.
+
+ @retval EFI_SUCCESS The requested memory pages were allocated.
+ @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
+ MEMORY_WRITE_COMBINE and MEMORY_CACHED.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonCoherentPciIoAllocateBuffer (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -700,10 +949,29 @@ RemoveList:
FreeBuffer:
CoherentPciIoFreeBuffer (This, Pages, AllocAddress);
return Status;
}
+/**
+ Provides the PCI controller-specific addresses needed to access system memory.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Operation Indicates if the bus master is going to read or write to system memory.
+ @param HostAddress The system memory address to map to 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 hosts HostAddress.
+ @param Mapping A resulting value to pass to Unmap().
+
+ @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
+ @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+ @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonCoherentPciIoMap (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -814,10 +1082,19 @@ FreeMapInfo:
FreePool (MapInfo);
return Status;
}
+/**
+ Completes the Map() operation and releases any corresponding resources.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Mapping The mapping value returned from Map().
+
+ @retval EFI_SUCCESS The range was unmapped.
+
+**/
STATIC
EFI_STATUS
EFIAPI
NonCoherentPciIoUnmap (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -857,20 +1134,39 @@ NonCoherentPciIoUnmap (
}
FreePool (MapInfo);
return EFI_SUCCESS;
}
+/**
+ Flushes all PCI posted write transactions from a PCI host bridge to system memory.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoFlush (
IN EFI_PCI_IO_PROTOCOL *This
)
{
return EFI_SUCCESS;
}
+/**
+ Retrieves this PCI controller's current PCI bus number, device number, and function number.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param SegmentNumber The PCI controller's current PCI segment number.
+ @param BusNumber The PCI controller's current PCI bus number.
+ @param DeviceNumber The PCI controller's current PCI device number.
+ @param FunctionNumber The PCI controller's current PCI function number.
+
+ @retval EFI_SUCCESS The PCI controller location was returned.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoGetLocation (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -893,10 +1189,29 @@ PciIoGetLocation (
*FunctionNumber = 0;
return EFI_SUCCESS;
}
+/**
+ Performs an operation on the attributes that this PCI controller supports. The operations include
+ getting the set of supported attributes, retrieving the current attributes, setting the current
+ attributes, enabling attributes, and disabling attributes.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Operation The operation to perform on the attributes for this PCI controller.
+ @param Attributes The mask of attributes that are used for Set, Enable, and Disable
+ operations.
+ @param Result A pointer to the result mask of attributes that are returned for the Get
+ and Supported operations.
+
+ @retval EFI_SUCCESS The operation on the PCI controller's attributes was completed.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_UNSUPPORTED one or more of the bits set in
+ Attributes are not supported by this PCI controller or one of
+ its parent bridges when Operation is Set, Enable or Disable.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoAttributes (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -950,10 +1265,32 @@ PciIoAttributes (
Dev->Enabled = TRUE;
}
return EFI_SUCCESS;
}
+/**
+ Gets the attributes that this PCI controller supports setting on a BAR using
+ SetBarAttributes(), and retrieves the list of resource descriptors for a BAR.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for resource range. The legal range for this field is 0..5.
+ @param Supports A pointer to the mask of attributes that this PCI controller supports
+ setting for this BAR with SetBarAttributes().
+ @param Resources A pointer to the ACPI 2.0 resource descriptors that describe the current
+ configuration of this BAR of the PCI controller.
+
+ @retval EFI_SUCCESS If Supports is not NULL, then the attributes that the PCI
+ controller supports are returned in Supports. If Resources
+ is not NULL, then the ACPI 2.0 resource descriptors that the PCI
+ controller is currently using are returned in Resources.
+ @retval EFI_INVALID_PARAMETER Both Supports and Attributes are NULL.
+ @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller.
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate
+ Resources.
+
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoGetBarAttributes (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -1001,10 +1338,23 @@ PciIoGetBarAttributes (
*Resources = Descriptor;
}
return EFI_SUCCESS;
}
+/**
+ Sets the attributes for a range of a BAR on a PCI controller.
+
+ @param This A pointer to the EFI_PCI_IO_PROTOCOL instance.
+ @param Attributes The mask of attributes to set for the resource range specified by
+ BarIndex, Offset, and Length.
+ @param BarIndex The BAR index of the standard PCI Configuration header to use as the
+ base address for resource range. The legal range for this field is 0..5.
+ @param Offset A pointer to the BAR relative base address of the resource range to be
+ modified by the attributes specified by Attributes.
+ @param Length A pointer to the length of the resource range to be modified by the
+ attributes specified by Attributes.
+**/
STATIC
EFI_STATUS
EFIAPI
PciIoSetBarAttributes (
IN EFI_PCI_IO_PROTOCOL *This,
@@ -1037,10 +1387,16 @@ STATIC CONST EFI_PCI_IO_PROTOCOL PciIoTemplate =
PciIoSetBarAttributes,
0,
0
};
+/**
+ Initialize PciIo Protocol.
+
+ @param Dev Point to NON_DISCOVERABLE_PCI_DEVICE instance.
+
+**/
VOID
InitializePciIoProtocol (
NON_DISCOVERABLE_PCI_DEVICE *Dev
)
{
diff --git a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.h b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.h
index 4496148..e641189 100644
--- a/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.h
+++ b/MdeModulePkg/Bus/Pci/NonDiscoverablePciDeviceDxe/NonDiscoverablePciDeviceIo.h
@@ -100,10 +100,16 @@ typedef struct {
// on behalf of this device
//
LIST_ENTRY UncachedAllocationList;
} NON_DISCOVERABLE_PCI_DEVICE;
+/**
+ Initialize PciIo Protocol.
+
+ @param Device Point to NON_DISCOVERABLE_PCI_DEVICE instance.
+
+**/
VOID
InitializePciIoProtocol (
NON_DISCOVERABLE_PCI_DEVICE *Device
);
--
1.9.5.msysgit.1
next prev parent reply other threads:[~2016-12-16 2:25 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-12-16 2:25 [patch 1/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Fix VS2010/2012 build failure Dandan Bi
2016-12-16 2:25 ` Dandan Bi [this message]
2016-12-16 4:59 ` [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions Ni, Ruiyu
2016-12-16 2:25 ` [patch 3/3] MdeModulePkg/NonDiscoverablePciDevice: Make variable definition follow rule Dandan Bi
2016-12-16 4:59 ` Ni, Ruiyu
2016-12-16 4:59 ` [patch 1/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Fix VS2010/2012 build failure Ni, Ruiyu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1481855136-115456-2-git-send-email-dandan.bi@intel.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox