From: "Ni, Ruiyu" <ruiyu.ni@intel.com>
To: "Bi, Dandan" <dandan.bi@intel.com>,
"edk2-devel@lists.01.org" <edk2-devel@lists.01.org>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Subject: Re: [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions
Date: Fri, 16 Dec 2016 04:59:46 +0000 [thread overview]
Message-ID: <734D49CCEBEEF84792F5B80ED585239D5B832B64@SHSMSX103.ccr.corp.intel.com> (raw)
In-Reply-To: <1481855136-115456-2-git-send-email-dandan.bi@intel.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>
Regards,
Ray
>-----Original Message-----
>From: Bi, Dandan
>Sent: Friday, December 16, 2016 10:26 AM
>To: edk2-devel@lists.01.org
>Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>; Ni, Ruiyu <ruiyu.ni@intel.com>
>Subject: [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions
>
>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 4:59 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 ` [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions Dandan Bi
2016-12-16 4:59 ` Ni, Ruiyu [this message]
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=734D49CCEBEEF84792F5B80ED585239D5B832B64@SHSMSX103.ccr.corp.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