From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id A05BA82011 for ; Thu, 15 Dec 2016 18:25:55 -0800 (PST) Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga104.fm.intel.com with ESMTP; 15 Dec 2016 18:25:54 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.33,355,1477983600"; d="scan'208";a="1099823198" Received: from shwdeopenpsi114.ccr.corp.intel.com ([10.239.157.135]) by fmsmga002.fm.intel.com with ESMTP; 15 Dec 2016 18:25:53 -0800 From: Dandan Bi To: edk2-devel@lists.01.org Cc: Ard Biesheuvel , Ruiyu Ni Date: Fri, 16 Dec 2016 10:25:35 +0800 Message-Id: <1481855136-115456-2-git-send-email-dandan.bi@intel.com> X-Mailer: git-send-email 1.9.5.msysgit.1 In-Reply-To: <1481855136-115456-1-git-send-email-dandan.bi@intel.com> References: <1481855136-115456-1-git-send-email-dandan.bi@intel.com> Subject: [patch 2/3] MdeModulePkg/NonDiscoverablePciDeviceDxe: Add comments for functions X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 16 Dec 2016 02:25:55 -0000 Cc: Ard Biesheuvel Cc: Ruiyu Ni Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Dandan Bi --- .../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