public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
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



  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