From 57076f458585a61a0fa1afb9a6527bc7a625ed64 Mon Sep 17 00:00:00 2001 From: klu2 Date: Wed, 16 Apr 2008 09:24:58 +0000 Subject: [PATCH] Add function doxygen header for PciBus module. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5071 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Bus/Pci/PciBusDxe/PciHotPlugSupport.c | 202 ++-- .../Bus/Pci/PciBusDxe/PciHotPlugSupport.h | 228 ++--- .../Bus/Pci/PciBusDxe/PciIo.c | 956 ++++++++---------- .../Bus/Pci/PciBusDxe/PciIo.h | 897 ++++++++-------- .../Bus/Pci/PciBusDxe/PciLib.c | 285 ++---- .../Bus/Pci/PciBusDxe/PciLib.h | 223 ++-- .../Bus/Pci/PciBusDxe/PciOptionRomSupport.c | 88 +- .../Bus/Pci/PciBusDxe/PciOptionRomSupport.h | 95 +- .../Bus/Pci/PciBusDxe/PciPowerManagement.c | 23 +- .../Bus/Pci/PciBusDxe/PciPowerManagement.h | 25 +- .../Bus/Pci/PciBusDxe/PciResourceSupport.c | 684 +++++-------- .../Bus/Pci/PciBusDxe/PciResourceSupport.h | 700 +++++-------- .../Bus/Pci/PciBusDxe/PciRomTable.c | 70 +- .../Bus/Pci/PciBusDxe/PciRomTable.h | 79 +- 14 files changed, 1800 insertions(+), 2755 deletions(-) diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c index ee95864f1b..22bef0df3d 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.c @@ -1,5 +1,6 @@ /**@file - + This module provide support function for hot plug device. + Copyright (c) 2006, Intel Corporation All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License @@ -20,25 +21,18 @@ EFI_HPC_LOCATION *gPciRootHpcPool; UINTN gPciRootHpcCount; ROOT_HPC_DATA *gPciRootHpcData; +/** + Init HPC private data. + + @param Event event object + @param Context HPC private data. +**/ VOID EFIAPI PciHPCInitialized ( IN EFI_EVENT Event, IN VOID *Context ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Event - add argument and description to function comment -// TODO: Context - add argument and description to function comment { ROOT_HPC_DATA *HpcData; @@ -47,24 +41,20 @@ Returns: } +/** + Compare two device path + + @param DevicePath1 the first device path want to be compared + @param DevicePath2 the first device path want to be compared + + @retval TRUE equal + @retval FALSE different +**/ BOOLEAN EfiCompareDevicePath ( IN EFI_DEVICE_PATH_PROTOCOL *DevicePath1, IN EFI_DEVICE_PATH_PROTOCOL *DevicePath2 ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: DevicePath1 - add argument and description to function comment -// TODO: DevicePath2 - add argument and description to function comment { UINTN Size1; UINTN Size2; @@ -83,24 +73,14 @@ Returns: return TRUE; } +/** + Init hot plug support and root hot plug private data. + +**/ EFI_STATUS InitializeHotPlugSupport ( VOID ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; EFI_HPC_LOCATION *HpcList; @@ -148,26 +128,20 @@ Returns: return EFI_SUCCESS; } +/** + Test whether device path is for root pci hot plug bus + + @param HpbdevicePath tested device path + @param HpIndex Return the index of root hot plug in global array. + + @retval TRUE device path is for root pci hot plug + @retval FALSE device path is not for root pci hot plug +**/ BOOLEAN IsRootPciHotPlugBus ( IN EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath, OUT UINTN *HpIndex ) -/** - -Routine Description: - -Arguments: - - HpcDevicePath - A pointer to the EFI_DEVICE_PATH_PROTOCOL. - HpIndex - A pointer to the Index. - -Returns: - - None - -**/ -// TODO: HpbDevicePath - add argument and description to function comment { UINTN Index; @@ -186,25 +160,20 @@ Returns: return FALSE; } +/** + Test whether device path is for root pci hot plug controller + + @param HpbdevicePath tested device path + @param HpIndex Return the index of root hot plug in global array. + + @retval TRUE device path is for root pci hot plug controller + @retval FALSE device path is not for root pci hot plug controller +**/ BOOLEAN IsRootPciHotPlugController ( IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, OUT UINTN *HpIndex ) -/** - -Routine Description: - -Arguments: - - HpcDevicePath - A pointer to the EFI_DEVICE_PATH_PROTOCOL. - HpIndex - A pointer to the Index. - -Returns: - - None - -**/ { UINTN Index; @@ -223,24 +192,19 @@ Returns: return FALSE; } +/** + Wrapper for creating event object for HPC + + @param HpIndex index of hot plug device in global array + @param Event event object + + @return status of create event invoken +**/ EFI_STATUS CreateEventForHpc ( IN UINTN HpIndex, OUT EFI_EVENT *Event ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: HpIndex - add argument and description to function comment -// TODO: Event - add argument and description to function comment { EFI_STATUS Status; @@ -259,22 +223,15 @@ Returns: return Status; } +/** + Wait for all root HPC initialized. + + @param TimeoutInMicroSeconds microseconds to wait for all root hpc's initialization +**/ EFI_STATUS AllRootHPCInitialized ( IN UINTN TimeoutInMicroSeconds ) -/** - -Routine Description: - -Arguments: - TimeoutInMicroSeconds - microseconds to wait for all root hpc's initialization - -Returns: - EFI_SUCCESS - All root hpc's initialization is finished before the timeout - EFI_TIMEOUT - Time out - -**/ { UINT32 Delay; UINTN Index; @@ -305,25 +262,18 @@ Returns: return EFI_TIMEOUT; } +/** + Check HPC capability register block + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS PCI device is HPC + @retval EFI_NOT_FOUND PCI device is not HPC +**/ EFI_STATUS IsSHPC ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment { EFI_STATUS Status; @@ -352,6 +302,14 @@ Returns: return EFI_NOT_FOUND; } +/** + Get resource padding for hot plug bus + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS success get padding and set it into PCI device instance + @retval EFI_NOT_FOUND PCI device is not a hot plug bus. +**/ EFI_STATUS GetResourcePaddingForHpb ( IN PCI_IO_DEVICE *PciIoDevice @@ -405,25 +363,18 @@ Returns: return EFI_NOT_FOUND; } +/** + Test whether PCI device is hot plug bus. + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS PCI device is hot plug bus + @retval EFI_NOT_FOUND PCI device is not hot plug bus +**/ EFI_STATUS IsPciHotPlugBus ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment { BOOLEAN Result; EFI_STATUS Status; @@ -449,3 +400,4 @@ Returns: return EFI_NOT_FOUND; } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.h index c1d74a3086..4f5037136c 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciHotPlugSupport.h @@ -32,224 +32,144 @@ extern EFI_HPC_LOCATION *gPciRootHpcPool; extern UINTN gPciRootHpcCount; extern ROOT_HPC_DATA *gPciRootHpcData; +/** + Init HPC private data. + + @param Event event object + @param Context HPC private data. +**/ VOID EFIAPI PciHPCInitialized ( IN EFI_EVENT Event, IN VOID *Context ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Event - TODO: add argument description - Context - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Compare two device path + + @param DevicePath1 the first device path want to be compared + @param DevicePath2 the first device path want to be compared + + @retval TRUE equal + @retval FALSE different +**/ BOOLEAN EfiCompareDevicePath ( IN EFI_DEVICE_PATH_PROTOCOL *DevicePath1, IN EFI_DEVICE_PATH_PROTOCOL *DevicePath2 ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - DevicePath1 - TODO: add argument description - DevicePath2 - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Init hot plug support and root hot plug private data. + +**/ EFI_STATUS InitializeHotPlugSupport ( VOID ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - None - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether PCI device is hot plug bus. + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS PCI device is hot plug bus + @retval EFI_NOT_FOUND PCI device is not hot plug bus +**/ EFI_STATUS IsPciHotPlugBus ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether device path is for root pci hot plug bus + + @param HpbdevicePath tested device path + @param HpIndex Return the index of root hot plug in global array. + + @retval TRUE device path is for root pci hot plug + @retval FALSE device path is not for root pci hot plug +**/ BOOLEAN IsRootPciHotPlugBus ( IN EFI_DEVICE_PATH_PROTOCOL *HpbDevicePath, OUT UINTN *HpIndex ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - HpbDevicePath - TODO: add argument description - HpIndex - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether device path is for root pci hot plug controller + + @param HpbdevicePath tested device path + @param HpIndex Return the index of root hot plug in global array. + + @retval TRUE device path is for root pci hot plug controller + @retval FALSE device path is not for root pci hot plug controller +**/ BOOLEAN IsRootPciHotPlugController ( IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath, OUT UINTN *HpIndex ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - HpcDevicePath - TODO: add argument description - HpIndex - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Wrapper for creating event object for HPC + + @param HpIndex index of hot plug device in global array + @param Event event object + + @return status of create event invoken +**/ EFI_STATUS CreateEventForHpc ( IN UINTN HpIndex, OUT EFI_EVENT *Event ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - HpIndex - TODO: add argument description - Event - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Wait for all root HPC initialized. + + @param TimeoutInMicroSeconds microseconds to wait for all root hpc's initialization +**/ EFI_STATUS AllRootHPCInitialized ( IN UINTN TimeoutInMicroSeconds ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - TimeoutInMicroSeconds - microseconds to wait for all root hpc's initialization - -Returns: - EFI_SUCCESS - All root hpc's initialization is finished before the timeout - EFI_TIMEOUT - Time out - -**/ ; +/** + Check HPC capability register block + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS PCI device is HPC + @retval EFI_NOT_FOUND PCI device is not HPC +**/ EFI_STATUS IsSHPC ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Get resource padding for hot plug bus + + @param PciIoDevice PCI device instance + + @retval EFI_SUCCESS success get padding and set it into PCI device instance + @retval EFI_NOT_FOUND PCI device is not a hot plug bus. +**/ EFI_STATUS GetResourcePaddingForHpb ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; #endif diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.c index 79ebe5fabd..ccec7d7244 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.c @@ -1,5 +1,6 @@ /**@file - + Implement all interfaces for EFI_PCI_IO_PROTOCOL. + Copyright (c) 2006, Intel Corporation All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License @@ -60,27 +61,18 @@ static EFI_PCI_IO_PROTOCOL PciIoInterface = { NULL }; +/** + report a error Status code of PCI bus driver controller + + @param PciIoDevice Pci device instance + @param Code status code +**/ STATIC EFI_STATUS ReportErrorStatusCode ( IN PCI_IO_DEVICE *PciIoDevice, IN EFI_STATUS_CODE_VALUE Code ) -/** - -Routine Description: - - report a error Status code of PCI bus driver controller - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: Code - add argument and description to function comment { return REPORT_STATUS_CODE_WITH_DEVICE_PATH ( EFI_ERROR_CODE | EFI_ERROR_MINOR, @@ -89,30 +81,36 @@ Returns: ); } +/** + Initializes a PCI I/O Instance + + @param PciIoDevice Pci device instance + + @retval EFI_SUCCESS Success operation +**/ EFI_STATUS InitializePciIoInstance ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - Initializes a PCI I/O Instance - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { CopyMem (&PciIoDevice->PciIo, &PciIoInterface, sizeof (EFI_PCI_IO_PROTOCOL)); return EFI_SUCCESS; } +/** + Verifies access to a PCI Base Address Register (BAR) + + @param PciIoDevice Pci device instance + @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 Type Operation type could be memory or I/O + @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 Offset The offset within the PCI configuration space for the PCI controller. + + @retval EFI_INVALID_PARAMETER Invalid Width/BarIndex or Bar type. + @retval EFI_SUCCESS Success Operation. +**/ EFI_STATUS PciIoVerifyBarAccess ( PCI_IO_DEVICE *PciIoDevice, @@ -122,31 +120,6 @@ PciIoVerifyBarAccess ( IN UINTN Count, UINT64 *Offset ) -/** - -Routine Description: - - Verifies access to a PCI Base Address Register (BAR) - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Type - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { if (Width < 0 || Width >= EfiPciIoWidthMaximum) { return EFI_INVALID_PARAMETER; @@ -186,6 +159,18 @@ Returns: return EFI_SUCCESS; } +/** + Verifies access to a PCI Config Header + + @param PciIoDevice Pci device instance + @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 Offset The offset within the PCI configuration space for the PCI controller. + + @retval EFI_INVALID_PARAMETER Invalid Width + @retval EFI_UNSUPPORTED Offset overflow + @retval EFI_SUCCESS Success operation +**/ EFI_STATUS PciIoVerifyConfigAccess ( PCI_IO_DEVICE *PciIoDevice, @@ -193,27 +178,6 @@ PciIoVerifyConfigAccess ( IN UINTN Count, IN UINT64 *Offset ) -/** - -Routine Description: - - Verifies access to a PCI Config Header - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 ExtendOffset; @@ -246,6 +210,25 @@ Returns: return EFI_SUCCESS; } +/** + Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is + satisfied or after a defined duration. + + @param This Pointer to protocol instance of EFI_PCI_IO_PROTOCOL + @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 PCI configuration space for the PCI controller. + @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. + + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. + @retval EFI_TIMEOUT Delay expired before a match occurred. + @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. +**/ EFI_STATUS EFIAPI PciIoPollMem ( @@ -258,30 +241,6 @@ PciIoPollMem ( IN UINT64 Delay, OUT UINT64 *Result ) -/** - -Routine Description: - - Poll PCI Memmory - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Mask - add argument and description to function comment -// TODO: Value - add argument and description to function comment -// TODO: Delay - add argument and description to function comment -// TODO: Result - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -318,6 +277,24 @@ Returns: return Status; } +/** + Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is + satisfied or after a defined duration. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL. + @param Width Signifies the width of the memory or I/O operations. + @param Address The base address of the memory or I/O operations. + @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. + + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. + @retval EFI_TIMEOUT Delay expired before a match occurred. + @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. + +**/ EFI_STATUS EFIAPI PciIoPollIo ( @@ -330,30 +307,6 @@ PciIoPollIo ( IN UINT64 Delay, OUT UINT64 *Result ) -/** - -Routine Description: - - Poll PCI IO - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Mask - add argument and description to function comment -// TODO: Value - add argument and description to function comment -// TODO: Delay - add argument and description to function comment -// TODO: Result - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -386,6 +339,26 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoMemRead ( @@ -396,27 +369,6 @@ PciIoMemRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI Memory Read Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -447,6 +399,26 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoMemWrite ( @@ -457,27 +429,6 @@ PciIoMemWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI Memory Write Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -508,6 +459,26 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoIoRead ( @@ -518,27 +489,6 @@ PciIoIoRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI I/O Read Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -569,6 +519,26 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoIoWrite ( @@ -579,27 +549,6 @@ PciIoIoWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI I/O Write Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -630,6 +579,24 @@ Returns: return Status; } +/** + Enable a PCI driver to access PCI controller registers in PCI configuration space. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @param Width Signifies the width of the memory operations. + @param Offset The offset within the PCI configuration space for the PCI controller. + @param Count The number of PCI configuration 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 configuration header of the PCI controller. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. + +**/ EFI_STATUS EFIAPI PciIoConfigRead ( @@ -639,24 +606,6 @@ PciIoConfigRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI Configuration Read Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -685,6 +634,24 @@ Returns: return Status; } +/** + Enable a PCI driver to access PCI controller registers in PCI configuration space. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @param Width Signifies the width of the memory operations. + @param Offset The offset within the PCI configuration space for the PCI controller. + @param Count The number of PCI configuration 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 configuration header of the PCI controller. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. + +**/ EFI_STATUS EFIAPI PciIoConfigWrite ( @@ -694,24 +661,6 @@ PciIoConfigWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - Performs a PCI Configuration Write Cycle - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: Buffer - add argument and description to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -740,6 +689,34 @@ Returns: return Status; } +/** + 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. + + @retval EFI_SUCCESS The data was copied from one memory region to another memory region. + @retval EFI_UNSUPPORTED DestBarIndex not valid for this PCI controller. + @retval EFI_UNSUPPORTED SrcBarIndex not valid for this PCI controller. + @retval EFI_UNSUPPORTED The address range specified by DestOffset, Width, and Count + is not valid for the PCI BAR specified by DestBarIndex. + @retval EFI_UNSUPPORTED The address range specified by SrcOffset, Width, and Count is + not valid for the PCI BAR specified by SrcBarIndex. + @retval EFI_INVALID_PARAMETER Width is invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + +**/ EFI_STATUS EFIAPI PciIoCopyMem ( @@ -751,30 +728,6 @@ PciIoCopyMem ( IN UINT64 SrcOffset, IN UINTN Count ) -/** - -Routine Description: - - Copy PCI Memory - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Width - add argument and description to function comment -// TODO: DestBarIndex - add argument and description to function comment -// TODO: DestOffset - add argument and description to function comment -// TODO: SrcBarIndex - add argument and description to function comment -// TODO: SrcOffset - add argument and description to function comment -// TODO: Count - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -821,6 +774,25 @@ Returns: return Status; } +/** + Provides the PCI controller-Cspecific 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. + +**/ EFI_STATUS EFIAPI PciIoMap ( @@ -831,27 +803,6 @@ PciIoMap ( OUT EFI_PHYSICAL_ADDRESS *DeviceAddress, OUT VOID **Mapping ) -/** - -Routine Description: - - Maps a memory region for DMA - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Operation - add argument and description to function comment -// TODO: HostAddress - add argument and description to function comment -// TODO: NumberOfBytes - add argument and description to function comment -// TODO: DeviceAddress - add argument and description to function comment -// TODO: Mapping - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -886,27 +837,22 @@ Returns: 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. + @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. + +**/ EFI_STATUS EFIAPI PciIoUnmap ( IN EFI_PCI_IO_PROTOCOL *This, IN VOID *Mapping ) -/** - -Routine Description: - - Unmaps a memory region for DMA - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Mapping - add argument and description to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -925,6 +871,26 @@ Returns: return Status; } +/** + Allocates pages that are suitable for an EfiPciIoOperationBusMasterCommonBuffer + mapping. + + @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. + +**/ EFI_STATUS EFIAPI PciIoAllocateBuffer ( @@ -935,26 +901,6 @@ PciIoAllocateBuffer ( OUT VOID **HostAddress, IN UINT64 Attributes ) -/** - -Routine Description: - - Allocates a common buffer for DMA - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Type - add argument and description to function comment -// TODO: MemoryType - add argument and description to function comment -// TODO: Pages - add argument and description to function comment -// TODO: HostAddress - add argument and description to function comment -// TODO: Attributes - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -986,6 +932,18 @@ Returns: return Status; } +/** + Frees memory that was allocated with AllocateBuffer(). + + @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 EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages + was not allocated with AllocateBuffer(). + +**/ EFI_STATUS EFIAPI PciIoFreeBuffer ( @@ -993,22 +951,6 @@ PciIoFreeBuffer ( IN UINTN Pages, IN VOID *HostAddress ) -/** - -Routine Description: - - Frees a common buffer - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Pages - add argument and description to function comment -// TODO: HostAddress - add argument and description to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -1028,25 +970,22 @@ Returns: return Status; } +/** + 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. + + @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host + bridge to system memory. + @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI + host bridge due to a hardware error. + +**/ EFI_STATUS EFIAPI PciIoFlush ( IN EFI_PCI_IO_PROTOCOL *This ) -/** - -Routine Description: - - Flushes a DMA buffer - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -1063,6 +1002,19 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoGetLocation ( @@ -1072,26 +1024,6 @@ PciIoGetLocation ( OUT UINTN *Device, OUT UINTN *Function ) -/** - -Routine Description: - - Gets a PCI device's current bus number, device number, and function number. - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Segment - add argument and description to function comment -// TODO: Bus - add argument and description to function comment -// TODO: Device - add argument and description to function comment -// TODO: Function - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *PciIoDevice; @@ -1109,28 +1041,22 @@ Returns: return EFI_SUCCESS; } +/** + Check BAR type for PCI resource. + + @param PciIoDevice PCI device instance + @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 BarType Memory or I/O + + @return whether Pci device's bar type is same with input BarType. +**/ BOOLEAN CheckBarType ( IN PCI_IO_DEVICE *PciIoDevice, UINT8 BarIndex, PCI_BAR_TYPE BarType ) -/** - -Routine Description: - - Sets a PCI controllers attributes on a resource range - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: BarType - add argument and description to function comment { switch (BarType) { @@ -1160,31 +1086,22 @@ Returns: return FALSE; } +/** + Set/Disable new attributes to a Root Bridge + + @param PciIoDevice Pci device instance + @param Attributes New attribute want to be set + @param Operation Set or Disable + + @retval EFI_UNSUPPORTED If root bridge does not support change attribute + @retval EFI_SUCCESS Success operation. +**/ EFI_STATUS ModifyRootBridgeAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN UINT64 Attributes, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation ) -/** - -Routine Description: - - Set new attributes to a Root Bridge - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: Attributes - add argument and description to function comment -// TODO: Operation - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 PciRootBridgeSupports; UINT64 PciRootBridgeAttributes; @@ -1239,35 +1156,20 @@ Returns: } +/** + Check whether this device can be enable/disable to snoop + + @param PciIoDevice Pci device instance + @param Operation Enable/Disable + + @retval EFI_UNSUPPORTED Pci device is not GFX device or not support snoop + @retval EFI_SUCCESS Snoop can be supported. +**/ EFI_STATUS SupportPaletteSnoopAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation ) -/** - -Routine Description: - - Check whether this device can be enable/disable to snoop - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: Operation - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *Temp; UINT16 VGACommand; @@ -1364,6 +1266,25 @@ Returns: 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. + +**/ EFI_STATUS EFIAPI PciIoAttributes ( @@ -1372,33 +1293,6 @@ PciIoAttributes ( IN UINT64 Attributes, OUT UINT64 *Result OPTIONAL ) -/** - -Routine Description: - - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Operation - add argument and description to function comment -// TODO: Attributes - add argument and description to function comment -// TODO: Result - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment { EFI_STATUS Status; @@ -1658,6 +1552,28 @@ Returns: return Status; } +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoGetBarAttributes ( @@ -1666,26 +1582,6 @@ PciIoGetBarAttributes ( OUT UINT64 *Supports, OPTIONAL OUT VOID **Resources OPTIONAL ) -/** - -Routine Description: - - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Supports - add argument and description to function comment -// TODO: Resources - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT8 *Configuration; @@ -1821,6 +1717,30 @@ Returns: 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. + + @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource + range specified by BarIndex, Offset, and Length were + set on the PCI controller, and the actual resource range is returned + in Offset and Length. + @retval EFI_INVALID_PARAMETER Offset or Length is NULL. + @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the + resource range specified by BarIndex, Offset, and + Length. + +**/ EFI_STATUS EFIAPI PciIoSetBarAttributes ( @@ -1830,28 +1750,6 @@ PciIoSetBarAttributes ( IN OUT UINT64 *Offset, IN OUT UINT64 *Length ) -/** - -Routine Description: - - -Arguments: - -Returns: - - None - -**/ -// TODO: This - add argument and description to function comment -// TODO: Attributes - add argument and description to function comment -// TODO: BarIndex - add argument and description to function comment -// TODO: Offset - add argument and description to function comment -// TODO: Length - add argument and description to function comment -// TODO: EFI_INVALID_PARAMETER - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; PCI_IO_DEVICE *PciIoDevice; @@ -1899,27 +1797,27 @@ Returns: return EFI_SUCCESS; } +/** + Program parent bridge's attribute recurrently. + + @param PciIoDevice Child Pci device 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. + + @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. + +**/ EFI_STATUS UpStreamBridgesAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation, IN UINT64 Attributes ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: Operation - add argument and description to function comment -// TODO: Attributes - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *Parent; EFI_PCI_IO_PROTOCOL *PciIo; @@ -1941,24 +1839,19 @@ Returns: return EFI_SUCCESS; } +/** + Test whether two Pci device has same parent bridge. + + @param PciDevice1 the frist pci device for testing + @param PciDevice2 the second pci device for testing + + @return whether two Pci device has same parent bridge. +**/ BOOLEAN PciDevicesOnTheSamePath ( IN PCI_IO_DEVICE *PciDevice1, IN PCI_IO_DEVICE *PciDevice2 ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDevice1 - add argument and description to function comment -// TODO: PciDevice2 - add argument and description to function comment { BOOLEAN Existed1; BOOLEAN Existed2; @@ -1972,3 +1865,4 @@ Returns: return (BOOLEAN) (Existed1 || Existed2); } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.h index 6c6d739c62..216ee402fd 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciIo.h @@ -15,27 +15,33 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_PCI_IO_PROTOCOL_H #define _EFI_PCI_IO_PROTOCOL_H +/** + Initializes a PCI I/O Instance + + @param PciIoDevice Pci device instance + + @retval EFI_SUCCESS Success operation +**/ EFI_STATUS InitializePciIoInstance ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Verifies access to a PCI Base Address Register (BAR) + + @param PciIoDevice Pci device instance + @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 Type Operation type could be memory or I/O + @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 Offset The offset within the PCI configuration space for the PCI controller. + + @retval EFI_INVALID_PARAMETER Invalid Width/BarIndex or Bar type. + @retval EFI_SUCCESS Success Operation. +**/ EFI_STATUS PciIoVerifyBarAccess ( PCI_IO_DEVICE *PciIoDevice, @@ -45,28 +51,20 @@ PciIoVerifyBarAccess ( IN UINTN Count, UINT64 *Offset ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - BarIndex - TODO: add argument description - Type - TODO: add argument description - Width - TODO: add argument description - Count - TODO: add argument description - Offset - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Verifies access to a PCI Config Header + + @param PciIoDevice Pci device instance + @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 Offset The offset within the PCI configuration space for the PCI controller. + + @retval EFI_INVALID_PARAMETER Invalid Width + @retval EFI_UNSUPPORTED Offset overflow + @retval EFI_SUCCESS Success operation +**/ EFI_STATUS PciIoVerifyConfigAccess ( PCI_IO_DEVICE *PciIoDevice, @@ -74,26 +72,27 @@ PciIoVerifyConfigAccess ( IN UINTN Count, IN UINT64 *Offset ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - Width - TODO: add argument description - Count - TODO: add argument description - Offset - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is + satisfied or after a defined duration. + + @param This Pointer to protocol instance of EFI_PCI_IO_PROTOCOL + @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 PCI configuration space for the PCI controller. + @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. + + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. + @retval EFI_TIMEOUT Delay expired before a match occurred. + @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. +**/ EFI_STATUS EFIAPI PciIoPollMem ( @@ -106,30 +105,26 @@ PciIoPollMem ( IN UINT64 Delay, OUT UINT64 *Result ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Mask - TODO: add argument description - Value - TODO: add argument description - Delay - TODO: add argument description - Result - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Reads from the I/O space of a PCI Root Bridge. Returns when either the polling exit criteria is + satisfied or after a defined duration. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL. + @param Width Signifies the width of the memory or I/O operations. + @param Address The base address of the memory or I/O operations. + @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. + + @retval EFI_SUCCESS The last data returned from the access matched the poll exit criteria. + @retval EFI_TIMEOUT Delay expired before a match occurred. + @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. + +**/ EFI_STATUS EFIAPI PciIoPollIo ( @@ -142,30 +137,28 @@ PciIoPollIo ( IN UINT64 Delay, OUT UINT64 *Result ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Mask - TODO: add argument description - Value - TODO: add argument description - Delay - TODO: add argument description - Result - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoMemRead ( @@ -176,28 +169,28 @@ PciIoMemRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoMemWrite ( @@ -208,28 +201,28 @@ PciIoMemWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoIoRead ( @@ -240,28 +233,28 @@ PciIoIoRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoIoWrite ( @@ -272,28 +265,26 @@ PciIoIoWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Enable a PCI driver to access PCI controller registers in PCI configuration space. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @param Width Signifies the width of the memory operations. + @param Offset The offset within the PCI configuration space for the PCI controller. + @param Count The number of PCI configuration 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 configuration header of the PCI controller. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. + +**/ EFI_STATUS EFIAPI PciIoConfigRead ( @@ -303,27 +294,26 @@ PciIoConfigRead ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Enable a PCI driver to access PCI controller registers in PCI configuration space. + + @param This A pointer to the EFI_PCI_IO_PROTOCOL instance. + @param Width Signifies the width of the memory operations. + @param Offset The offset within the PCI configuration space for the PCI controller. + @param Count The number of PCI configuration 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 configuration header of the PCI controller. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + @retval EFI_INVALID_PARAMETER Buffer is NULL or Width is invalid. + +**/ EFI_STATUS EFIAPI PciIoConfigWrite ( @@ -333,27 +323,36 @@ PciIoConfigWrite ( IN UINTN Count, IN OUT VOID *Buffer ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - Offset - TODO: add argument description - Count - TODO: add argument description - Buffer - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + + @retval EFI_SUCCESS The data was copied from one memory region to another memory region. + @retval EFI_UNSUPPORTED DestBarIndex not valid for this PCI controller. + @retval EFI_UNSUPPORTED SrcBarIndex not valid for this PCI controller. + @retval EFI_UNSUPPORTED The address range specified by DestOffset, Width, and Count + is not valid for the PCI BAR specified by DestBarIndex. + @retval EFI_UNSUPPORTED The address range specified by SrcOffset, Width, and Count is + not valid for the PCI BAR specified by SrcBarIndex. + @retval EFI_INVALID_PARAMETER Width is invalid. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. + +**/ EFI_STATUS EFIAPI PciIoCopyMem ( @@ -365,29 +364,27 @@ PciIoCopyMem ( IN UINT64 SrcOffset, IN UINTN Count ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Width - TODO: add argument description - DestBarIndex - TODO: add argument description - DestOffset - TODO: add argument description - SrcBarIndex - TODO: add argument description - SrcOffset - TODO: add argument description - Count - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Provides the PCI controller-Cspecific 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. + +**/ EFI_STATUS EFIAPI PciIoMap ( @@ -398,52 +395,46 @@ PciIoMap ( OUT EFI_PHYSICAL_ADDRESS *DeviceAddress, OUT VOID **Mapping ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Operation - TODO: add argument description - HostAddress - TODO: add argument description - NumberOfBytes - TODO: add argument description - DeviceAddress - TODO: add argument description - Mapping - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. + +**/ EFI_STATUS EFIAPI PciIoUnmap ( IN EFI_PCI_IO_PROTOCOL *This, IN VOID *Mapping ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Mapping - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Allocates pages that are suitable for an EfiPciIoOperationBusMasterCommonBuffer + mapping. + + @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. + +**/ EFI_STATUS EFIAPI PciIoAllocateBuffer ( @@ -454,28 +445,20 @@ PciIoAllocateBuffer ( OUT VOID **HostAddress, IN UINT64 Attributes ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Type - TODO: add argument description - MemoryType - TODO: add argument description - Pages - TODO: add argument description - HostAddress - TODO: add argument description - Attributes - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Frees memory that was allocated with AllocateBuffer(). + + @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 EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages + was not allocated with AllocateBuffer(). + +**/ EFI_STATUS EFIAPI PciIoFreeBuffer ( @@ -483,47 +466,39 @@ PciIoFreeBuffer ( IN UINTN Pages, IN VOID *HostAddress ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Pages - TODO: add argument description - HostAddress - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + + @retval EFI_SUCCESS The PCI posted write transactions were flushed from the PCI host + bridge to system memory. + @retval EFI_DEVICE_ERROR The PCI posted write transactions were not flushed from the PCI + host bridge due to a hardware error. + +**/ EFI_STATUS EFIAPI PciIoFlush ( IN EFI_PCI_IO_PROTOCOL *This ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoGetLocation ( @@ -533,100 +508,79 @@ PciIoGetLocation ( OUT UINTN *Device, OUT UINTN *Function ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Segment - TODO: add argument description - Bus - TODO: add argument description - Device - TODO: add argument description - Function - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Check BAR type for PCI resource. + + @param PciIoDevice PCI device instance + @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 BarType Memory or I/O + + @return whether Pci device's bar type is same with input BarType. +**/ BOOLEAN CheckBarType ( IN PCI_IO_DEVICE *PciIoDevice, UINT8 BarIndex, PCI_BAR_TYPE BarType ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - BarIndex - TODO: add argument description - BarType - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Set/Disable new attributes to a Root Bridge + + @param PciIoDevice Pci device instance + @param Attributes New attribute want to be set + @param Operation Set or Disable + + @retval EFI_UNSUPPORTED If root bridge does not support change attribute + @retval EFI_SUCCESS Success operation. +**/ EFI_STATUS ModifyRootBridgeAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN UINT64 Attributes, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - Attributes - TODO: add argument description - Operation - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Check whether this device can be enable/disable to snoop + + @param PciIoDevice Pci device instance + @param Operation Enable/Disable + + @retval EFI_UNSUPPORTED Pci device is not GFX device or not support snoop + @retval EFI_SUCCESS Snoop can be supported. +**/ EFI_STATUS SupportPaletteSnoopAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - Operation - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoAttributes ( @@ -635,26 +589,30 @@ PciIoAttributes ( IN UINT64 Attributes, OUT UINT64 *Result OPTIONAL ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Operation - TODO: add argument description - Attributes - TODO: add argument description - Result - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + +**/ EFI_STATUS EFIAPI PciIoGetBarAttributes ( @@ -663,26 +621,32 @@ PciIoGetBarAttributes ( OUT UINT64 *Supports, OPTIONAL OUT VOID **Resources OPTIONAL ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - BarIndex - TODO: add argument description - Supports - TODO: add argument description - Resources - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + 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. + + @retval EFI_SUCCESS The set of attributes specified by Attributes for the resource + range specified by BarIndex, Offset, and Length were + set on the PCI controller, and the actual resource range is returned + in Offset and Length. + @retval EFI_INVALID_PARAMETER Offset or Length is NULL. + @retval EFI_UNSUPPORTED BarIndex not valid for this PCI controller. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the attributes on the + resource range specified by BarIndex, Offset, and + Length. + +**/ EFI_STATUS EFIAPI PciIoSetBarAttributes ( @@ -692,73 +656,44 @@ PciIoSetBarAttributes ( IN OUT UINT64 *Offset, IN OUT UINT64 *Length ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - Attributes - TODO: add argument description - BarIndex - TODO: add argument description - Offset - TODO: add argument description - Length - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Program parent bridge's attribute recurrently. + + @param PciIoDevice Child Pci device 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. + + @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. + +**/ EFI_STATUS UpStreamBridgesAttributes ( IN PCI_IO_DEVICE *PciIoDevice, IN EFI_PCI_IO_PROTOCOL_ATTRIBUTE_OPERATION Operation, IN UINT64 Attributes ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - Operation - TODO: add argument description - Attributes - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether two Pci device has same parent bridge. + + @param PciDevice1 the frist pci device for testing + @param PciDevice2 the second pci device for testing + + @return whether two Pci device has same parent bridge. +**/ BOOLEAN PciDevicesOnTheSamePath ( IN PCI_IO_DEVICE *PciDevice1, IN PCI_IO_DEVICE *PciDevice2 ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDevice1 - TODO: add argument description - PciDevice2 - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; #endif diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c index 658992b1ac..587f1767d7 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.c @@ -21,23 +21,14 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_PCI_HOTPLUG_REQUEST_PROTOCOL gPciHotPlugReques PciHotPlugRequestNotify }; - +/** + Install protocol gEfiPciHotPlugRequestProtocolGuid + @param Status return status of protocol installation. +**/ VOID InstallHotPlugRequestProtocol ( IN EFI_STATUS *Status ) -/** - -Routine Description: - -Arguments: - Status - A pointer to the status. - -Returns: - - None - -**/ { EFI_HANDLE Handle; @@ -54,23 +45,17 @@ Returns: ); } +/** + Install protocol gEfiPciHotplugDeviceGuid into hotplug device + instance + + @param PciIoDevice hotplug device instance + +**/ VOID InstallPciHotplugGuid ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - - PciIoDevice - A pointer to the PCI_IO_DEVICE. - -Returns: - - None - -**/ { EFI_STATUS Status; @@ -90,23 +75,17 @@ Returns: } } +/** + UnInstall protocol gEfiPciHotplugDeviceGuid into hotplug device + instance + + @param PciIoDevice hotplug device instance + +**/ VOID UninstallPciHotplugGuid ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - - PciIoDevice - A pointer to the PCI_IO_DEVICE. - -Returns: - - None - -**/ { EFI_STATUS Status; @@ -136,24 +115,15 @@ Returns: } } +/** + Retrieve the BAR information via PciIo interface + + @param PciIoDevice Pci device instance +**/ VOID GetBackPcCardBar ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - -Arguments: - - PciIoDevice - A pointer to the PCI_IO_DEVICE. - -Returns: - - None - -**/ { UINT32 Address; @@ -222,27 +192,20 @@ Returns: } } +/** + Remove rejected pci device from specific root bridge + handle. + + @param RootBridgeHandle specific parent root bridge handle + @param Bridge Bridge device instance + + @retval EFI_SUCCESS Success operation. +**/ EFI_STATUS RemoveRejectedPciDevices ( EFI_HANDLE RootBridgeHandle, IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - - -Arguments: - - RootBridgeHandle - An efi handle. - Bridge - An pointer to the PCI_IO_DEVICE. - -Returns: - - None - -**/ -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *Temp; LIST_ENTRY *CurrentLink; @@ -295,6 +258,12 @@ Returns: return EFI_SUCCESS; } +/** + Wrapper function for allocating resource for pci host bridge. + + @param PciResAlloc Point to protocol instance EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + +**/ EFI_STATUS PciHostBridgeResourceAllocator ( IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc @@ -311,27 +280,17 @@ PciHostBridgeResourceAllocator ( } } +/** + Submits the I/O and memory resource requirements for the specified PCI Root Bridge + @param PciResAlloc Point to protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + + @retval EFI_SUCCESS Success +**/ EFI_STATUS PciHostBridgeResourceAllocator_WithoutHotPlugDeviceSupport ( IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciResAlloc - add argument and description to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *RootBridgeDev; EFI_HANDLE RootBridgeHandle; @@ -684,30 +643,18 @@ Returns: return EFI_SUCCESS; } +/** + Submits the I/O and memory resource requirements for the specified PCI Root Bridge + + @param PciResAlloc Point to protocol instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + + @retval EFI_SUCCESS Success +**/ EFI_STATUS PciHostBridgeResourceAllocator_WithHotPlugDeviceSupport ( IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) -/** - -Routine Description: - - Host brige resource allocator. - -Arguments: - - PciResAlloc - A pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL. - -Returns: - - EFI Status. - -**/ -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *RootBridgeDev; EFI_HANDLE RootBridgeHandle; @@ -1190,7 +1137,18 @@ Returns: return EFI_SUCCESS; } - +/** + Wapper function of scanning pci bus and assign bus number to the given PCI bus system + Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug + + @param Bridge Bridge device instance + @param StartBusNumber start point + @param SubBusNumber Point to sub bus number + @param PaddedBusRange Customized bus number + + @retval EFI_SUCCESS Success + @retval EFI_DEVICE_ERROR Fail to scan bus +**/ EFI_STATUS PciScanBus ( IN PCI_IO_DEVICE *Bridge, @@ -1216,7 +1174,18 @@ PciScanBus ( } } - +/** + Wapper function of scanning pci bus and assign bus number to the given PCI bus system + Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug + + @param Bridge Bridge device instance + @param StartBusNumber start point + @param SubBusNumber Point to sub bus number + @param PaddedBusRange Customized bus number + + @retval EFI_SUCCESS Success + @retval EFI_DEVICE_ERROR Fail to scan bus +**/ EFI_STATUS PciScanBus_WithoutHotPlugDeviceSupport ( IN PCI_IO_DEVICE *Bridge, @@ -1224,25 +1193,6 @@ PciScanBus_WithoutHotPlugDeviceSupport ( OUT UINT8 *SubBusNumber, OUT UINT8 *PaddedBusRange ) -/** - -Routine Description: - - This routine is used to assign bus number to the given PCI bus system - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: StartBusNumber - add argument and description to function comment -// TODO: SubBusNumber - add argument and description to function comment -// TODO: PaddedBusRange - add argument and description to function comment -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; PCI_TYPE00 Pci; @@ -1402,6 +1352,18 @@ Returns: return EFI_SUCCESS; } +/** + Wapper function of scanning pci bus and assign bus number to the given PCI bus system + Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug + + @param Bridge Bridge device instance + @param StartBusNumber start point + @param SubBusNumber Point to sub bus number + @param PaddedBusRange Customized bus number + + @retval EFI_SUCCESS Success + @retval EFI_DEVICE_ERROR Fail to scan bus +**/ EFI_STATUS PciScanBus_WithHotPlugDeviceSupport ( IN PCI_IO_DEVICE *Bridge, @@ -1409,26 +1371,6 @@ PciScanBus_WithHotPlugDeviceSupport ( OUT UINT8 *SubBusNumber, OUT UINT8 *PaddedBusRange ) -/** - -Routine Description: - - This routine is used to assign bus number to the given PCI bus system - -Arguments: - - Bridge - A pointer to the PCI_IO_DEVICE structure. - StartBusNumber - The start bus number. - SubBusNumber - A pointer to the sub bus number. - PaddedBusRange - A pointer to the padded bus range. - -Returns: - - None - -**/ -// TODO: EFI_DEVICE_ERROR - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; PCI_TYPE00 Pci; @@ -1700,25 +1642,17 @@ Returns: return EFI_SUCCESS; } +/** + Process Option Rom on this host bridge + + @param Bridge Pci bridge device instance + + @retval EFI_SUCCESS Success +**/ EFI_STATUS PciRootBridgeP2CProcess ( IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - - Process Option Rom on this host bridge - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { LIST_ENTRY *CurrentLink; PCI_IO_DEVICE *Temp; @@ -1823,30 +1757,20 @@ PciHostBridgeP2CProcess ( return EFI_SUCCESS; } +/** + This function is used to enumerate the entire host bridge + in a given platform + + @param PciResAlloc A pointer to the resource allocate protocol. + + @retval EFI_OUT_OF_RESOURCES no enough resource + @retval EFI_SUCCESS Success + +**/ EFI_STATUS PciHostBridgeEnumerator ( EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) -/** - -Routine Description: - - This function is used to enumerate the entire host bridge - in a given platform - -Arguments: - - PciResAlloc - A pointer to the resource allocate protocol. - -Returns: - - None - -**/ -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_HANDLE RootBridgeHandle; PCI_IO_DEVICE *RootBridgeDev; @@ -2933,3 +2857,4 @@ PciIoWrite ( ); } } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.h index b8dc2a61f3..639da70be8 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciLib.h @@ -49,132 +49,79 @@ typedef struct { UINT8 *AllocRes; } EFI_RESOURCE_ALLOC_FAILURE_ERROR_DATA_PAYLOAD; +/** + Install protocol gEfiPciHotPlugRequestProtocolGuid + @param Status return status of protocol installation. +**/ void InstallHotPlugRequestProtocol ( IN EFI_STATUS *Status ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Status - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Install protocol gEfiPciHotplugDeviceGuid into hotplug device + instance + + @param PciIoDevice hotplug device instance + +**/ VOID InstallPciHotplugGuid ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + UnInstall protocol gEfiPciHotplugDeviceGuid into hotplug device + instance + + @param PciIoDevice hotplug device instance + +**/ VOID UninstallPciHotplugGuid ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Retrieve the BAR information via PciIo interface + + @param PciIoDevice Pci device instance +**/ VOID GetBackPcCardBar ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Remove rejected pci device from specific root bridge + handle. + + @param RootBridgeHandle specific parent root bridge handle + @param Bridge Bridge device instance + + @retval EFI_SUCCESS Success operation. +**/ EFI_STATUS RemoveRejectedPciDevices ( EFI_HANDLE RootBridgeHandle, IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - RootBridgeHandle - TODO: add argument description - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Wrapper function for allocating resource for pci host bridge. + + @param PciResAlloc Point to protocol instance EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + +**/ EFI_STATUS PciHostBridgeResourceAllocator ( IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciResAlloc - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; EFI_STATUS @@ -189,6 +136,18 @@ PciHostBridgeResourceAllocator_WithHotPlugDeviceSupport ( ) ; +/** + Wapper function of scanning pci bus and assign bus number to the given PCI bus system + Feature flag PcdPciBusHotplugDeviceSupport determine whether need support hotplug + + @param Bridge Bridge device instance + @param StartBusNumber start point + @param SubBusNumber Point to sub bus number + @param PaddedBusRange Customized bus number + + @retval EFI_SUCCESS Success + @retval EFI_DEVICE_ERROR Fail to scan bus +**/ EFI_STATUS PciScanBus ( IN PCI_IO_DEVICE *Bridge, @@ -196,24 +155,6 @@ PciScanBus ( OUT UINT8 *SubBusNumber, OUT UINT8 *PaddedBusRange ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - StartBusNumber - TODO: add argument description - SubBusNumber - TODO: add argument description - PaddedBusRange - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; EFI_STATUS @@ -234,67 +175,49 @@ PciScanBus_WithoutHotPlugDeviceSupport ( ) ; +/** + Process Option Rom on this host bridge + + @param Bridge Pci bridge device instance + + @retval EFI_SUCCESS Success +**/ + EFI_STATUS PciRootBridgeP2CProcess ( IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Process Option Rom on this host bridge + + @param PciResAlloc Pointer to instance of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL + + @retval EFI_NOT_FOUND Can not find the root bridge instance + @retval EFI_SUCCESS Success process +**/ EFI_STATUS PciHostBridgeP2CProcess ( IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) +; + /** + This function is used to enumerate the entire host bridge + in a given platform -Routine Description: + @param PciResAlloc A pointer to the resource allocate protocol. - TODO: Add function description - -Arguments: - - PciResAlloc - TODO: add argument description - -Returns: - - TODO: add return values + @retval EFI_OUT_OF_RESOURCES no enough resource + @retval EFI_SUCCESS Success **/ -; EFI_STATUS PciHostBridgeEnumerator ( EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *PciResAlloc ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciResAlloc - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; /** diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.c index bf087821c5..980282f63d 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.c @@ -30,22 +30,16 @@ MEMMAP_DEVICE_PATH mPciOptionRomImageDevicePathNodeTemplate = { 0 }; +/** + Get Pci device's oprom infor bits. + + @retval EFI_NOT_FOUND Pci device has not oprom + @retval EFI_SUCCESS Pci device has oprom +**/ EFI_STATUS GetOpRomInfo ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - -Returns: - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT8 RomBarIndex; UINT32 AllOnes; @@ -125,27 +119,20 @@ Returns: return EFI_SUCCESS; } +/** + Load option rom image for specified PCI device + + @param PciDevice Pci device instance + @param RomBase Base address of oprom. + + @retval EFI_OUT_OF_RESOURCES not enough memory to hold image + @retval EFI_SUCESS Success +**/ EFI_STATUS LoadOpRomImage ( IN PCI_IO_DEVICE *PciDevice, IN UINT64 RomBase ) -/** - -Routine Description: - - Load option rom image for specified PCI device - -Arguments: - -Returns: - -**/ -// TODO: PciDevice - add argument and description to function comment -// TODO: RomBase - add argument and description to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment { UINT8 RomBarIndex; UINT8 Indicator; @@ -307,6 +294,17 @@ Returns: return retStatus; } +/** + enable/disable oprom decode + + @param PciDevice pci device instance + @param RomBarIndex 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 RomBar Base address of rom + @param Enable Flag for enable/disable decode. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS RomDecode ( IN PCI_IO_DEVICE *PciDevice, @@ -314,20 +312,6 @@ RomDecode ( IN UINT32 RomBar, IN BOOLEAN Enable ) -/** - -Routine Description: - -Arguments: - -Returns: - -**/ -// TODO: PciDevice - add argument and description to function comment -// TODO: RomBarIndex - add argument and description to function comment -// TODO: RomBar - add argument and description to function comment -// TODO: Enable - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT32 Value32; UINT32 Offset; @@ -395,24 +379,15 @@ Returns: } +/** + Process the oprom image. + + @param PciDevice Pci device instance +**/ EFI_STATUS ProcessOpRomImage ( PCI_IO_DEVICE *PciDevice ) -/** - -Routine Description: - - Process the oprom image. - -Arguments: - PciDevice A pointer to a pci device. - -Returns: - - EFI Status. - -**/ { UINT8 Indicator; UINT32 ImageSize; @@ -580,3 +555,4 @@ Returns: return retStatus; } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.h index e06edd4c17..c2ed590b67 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciOptionRomSupport.h @@ -14,50 +14,45 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_PCI_OP_ROM_SUPPORT_H #define _EFI_PCI_OP_ROM_SUPPORT_H +/** + Get Pci device's oprom infor bits. + + @retval EFI_NOT_FOUND Pci device has not oprom + @retval EFI_SUCCESS Pci device has oprom +**/ EFI_STATUS GetOpRomInfo ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Load option rom image for specified PCI device + + @param PciDevice Pci device instance + @param RomBase Base address of oprom. + + @retval EFI_OUT_OF_RESOURCES not enough memory to hold image + @retval EFI_SUCESS Success +**/ EFI_STATUS LoadOpRomImage ( IN PCI_IO_DEVICE *PciDevice, IN UINT64 RomBase ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDevice - TODO: add argument description - RomBase - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + enable/disable oprom decode + + @param PciDevice pci device instance + @param RomBarIndex 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 RomBar Base address of rom + @param Enable Flag for enable/disable decode. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS RomDecode ( IN PCI_IO_DEVICE *PciDevice, @@ -65,45 +60,17 @@ RomDecode ( IN UINT32 RomBar, IN BOOLEAN Enable ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDevice - TODO: add argument description - RomBarIndex - TODO: add argument description - RomBar - TODO: add argument description - Enable - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Process the oprom image. + + @param PciDevice Pci device instance +**/ EFI_STATUS ProcessOpRomImage ( PCI_IO_DEVICE *PciDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; #endif diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.c index 0cbbb36880..eb77e517ad 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.c @@ -13,28 +13,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include "pcibus.h" -EFI_STATUS -ResetPowerManagementFeature ( - IN PCI_IO_DEVICE *PciIoDevice - ) /** - -Routine Description: - This function is intended to turn off PWE assertion and put the device to D0 state if the device supports PCI Power Management. -Arguments: - -Returns: - - None + @param PciIoDevice Pci device instance + @retval EFI_UNSUPPORTED Device do not support power management + @retval EFI_SUCCESS Success **/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_UNSUPPORTED - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment +EFI_STATUS +ResetPowerManagementFeature ( + IN PCI_IO_DEVICE *PciIoDevice + ) { EFI_STATUS Status; UINT8 PowerManagementRegBlock; @@ -71,3 +63,4 @@ Returns: return EFI_SUCCESS; } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.h index 1239eed2ec..c7dff8c91b 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciPowerManagement.h @@ -14,25 +14,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_PCI_POWER_MANAGEMENT_H #define _EFI_PCI_POWER_MANAGEMENT_H +/** + This function is intended to turn off PWE assertion and + put the device to D0 state if the device supports + PCI Power Management. + + @param PciIoDevice Pci device instance + + @retval EFI_UNSUPPORTED Device do not support power management + @retval EFI_SUCCESS Success +**/ EFI_STATUS ResetPowerManagementFeature ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; #endif diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.c index 1521065780..563f229c7f 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.c @@ -15,27 +15,19 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include "PciResourceSupport.h" #include "PciCommand.h" +/** + The function is used to skip VGA range + + @param Start address including VGA range + @param Length length of VGA range. + + @retval EFI_SUCCESS success +**/ EFI_STATUS SkipVGAAperture ( OUT UINT64 *Start, IN UINT64 Length ) -/** - -Routine Description: - - The function is used to skip VGA range - -Arguments: - -Returns: - - None - -**/ -// TODO: Start - add argument and description to function comment -// TODO: Length - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Original; UINT64 Mask; @@ -57,27 +49,19 @@ Returns: return EFI_SUCCESS; } +/** + This function is used to skip ISA aliasing aperture + + @param Start address including ISA aliasing aperture + @param Length length of ISA aliasing aperture + + @retval EFI_SUCCESS success +**/ EFI_STATUS SkipIsaAliasAperture ( OUT UINT64 *Start, IN UINT64 Length ) -/** - -Routine Description: - - This function is used to skip ISA aliasing aperture - -Arguments: - -Returns: - - None - -**/ -// TODO: Start - add argument and description to function comment -// TODO: Length - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Original; @@ -101,28 +85,20 @@ Returns: return EFI_SUCCESS; } +/** + This function inserts a resource node into the resource list. + The resource list is sorted in descend order. + + @param Bridge PCI resource node for bridge + @param ResNode Resource node want to be inserted + + @retval EFI_SUCCESS Success +**/ EFI_STATUS InsertResourceNode ( PCI_RESOURCE_NODE *Bridge, PCI_RESOURCE_NODE *ResNode ) -/** - -Routine Description: - - This function inserts a resource node into the resource list. - The resource list is sorted in descend order. - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: ResNode - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { LIST_ENTRY *CurrentLink; PCI_RESOURCE_NODE *Temp; @@ -153,12 +129,6 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -MergeResourceTree ( - PCI_RESOURCE_NODE *Dst, - PCI_RESOURCE_NODE *Res, - BOOLEAN TypeMerge - ) /** Routine Description: @@ -171,17 +141,20 @@ Routine Description: If the TypeMerge is TRUE, Res resource type is changed to the type of destination resource type. -Arguments: - -Returns: - - None - + @param Dst Point to destination resource tree + @param Res Point to source resource tree + @param TypeMerge If the TypeMerge is TRUE, Res resource type is changed to the type of + destination resource type. + + + @retval EFI_SUCCESS Success **/ -// TODO: Dst - add argument and description to function comment -// TODO: Res - add argument and description to function comment -// TODO: TypeMerge - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment +EFI_STATUS +MergeResourceTree ( + PCI_RESOURCE_NODE *Dst, + PCI_RESOURCE_NODE *Res, + BOOLEAN TypeMerge + ) { LIST_ENTRY *CurrentLink; @@ -204,27 +177,18 @@ Returns: return EFI_SUCCESS; } +/** + This function is used to calculate the IO16 aperture + for a bridge. + + @param Bridge PCI resource node for bridge. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CalculateApertureIo16 ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - This function is used to calculate the IO16 aperture - for a bridge. - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Aperture; @@ -345,27 +309,18 @@ Returns: return EFI_SUCCESS; } +/** + This function is used to calculate the resource aperture + for a given bridge device + + @param Bridge Give bridge device + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CalculateResourceAperture ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - This function is used to calculate the resource aperture - for a given bridge device - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT64 Aperture; LIST_ENTRY *CurrentLink; @@ -455,6 +410,18 @@ Returns: return EFI_SUCCESS; } +/** + Get IO/Memory resource infor for given PCI device + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS GetResourceFromDevice ( PCI_IO_DEVICE *PciDev, @@ -464,24 +431,6 @@ GetResourceFromDevice ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDev - add argument and description to function comment -// TODO: IoNode - add argument and description to function comment -// TODO: Mem32Node - add argument and description to function comment -// TODO: PMem32Node - add argument and description to function comment -// TODO: Mem64Node - add argument and description to function comment -// TODO: PMem64Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { UINT8 Index; @@ -608,6 +557,16 @@ Returns: return EFI_SUCCESS; } +/** + This function is used to create a resource node + + @param PciDev Pci device instance + @param Length Length of Io/Memory resource + @param Alignment Alignment of resource + @param Bar Bar index + @param ResType Type of resource: IO/Memory + @param ResUage Resource usage +**/ PCI_RESOURCE_NODE * CreateResourceNode ( IN PCI_IO_DEVICE *PciDev, @@ -617,25 +576,6 @@ CreateResourceNode ( IN PCI_BAR_TYPE ResType, IN PCI_RESOURCE_USAGE ResUsage ) -/** - -Routine Description: - - This function is used to create a resource node - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDev - add argument and description to function comment -// TODO: Length - add argument and description to function comment -// TODO: Alignment - add argument and description to function comment -// TODO: Bar - add argument and description to function comment -// TODO: ResType - add argument and description to function comment -// TODO: ResUsage - add argument and description to function comment { PCI_RESOURCE_NODE *Node; @@ -668,6 +608,19 @@ Returns: return Node; } +/** + This routine is used to extract resource request from + device node list. + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CreateResourceMap ( IN PCI_IO_DEVICE *Bridge, @@ -677,27 +630,6 @@ CreateResourceMap ( IN PCI_RESOURCE_NODE *Mem64Node, IN PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - This routine is used to extract resource request from - device node list. - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: IoNode - add argument and description to function comment -// TODO: Mem32Node - add argument and description to function comment -// TODO: PMem32Node - add argument and description to function comment -// TODO: Mem64Node - add argument and description to function comment -// TODO: PMem64Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *Temp; PCI_RESOURCE_NODE *IoBridge; @@ -923,6 +855,18 @@ Returns: } +/** + This function is used to do the resource padding for a specific platform + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ResourcePaddingPolicy ( PCI_IO_DEVICE *PciDev, @@ -932,28 +876,6 @@ ResourcePaddingPolicy ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - This function is used to do the resource padding for a specific platform - -Arguments: - - PciDev - A pointer to the PCI_IO_DEVICE structrue. - IoNode - A pointer to the PCI_RESOURCE_NODE structrue. - Mem32Node - A pointer to the PCI_RESOURCE_NODE structrue. - PMem32Node - A pointer to the PCI_RESOURCE_NODE structrue. - Mem64Node - A pointer to the PCI_RESOURCE_NODE structrue. - PMem64Node - A pointer to the PCI_RESOURCE_NODE structrue. - -Returns: - Status code - - None - -**/ -// TODO: EFI_SUCCESS - add return value to function comment { // // Create padding resource node @@ -973,6 +895,22 @@ Returns: } +/** + This function is used to degrade resource if the upstream bridge + doesn't support certain resource. Degradation path is + PMEM64 -> MEM64 -> MEM32 + PMEM64 -> PMEM32 -> MEM32 + IO32 -> IO16 + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS DegradeResource ( IN PCI_IO_DEVICE *Bridge, @@ -981,29 +919,6 @@ DegradeResource ( IN PCI_RESOURCE_NODE *Mem64Node, IN PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - This function is used to degrade resource if the upstream bridge - doesn't support certain resource. Degradation path is - PMEM64 -> MEM64 -> MEM32 - PMEM64 -> PMEM32 -> MEM32 - IO32 -> IO16 - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: Mem32Node - add argument and description to function comment -// TODO: PMem32Node - add argument and description to function comment -// TODO: Mem64Node - add argument and description to function comment -// TODO: PMem64Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { // @@ -1078,39 +993,22 @@ Returns: return EFI_SUCCESS; } +/** + Test whether bridge device support decode resource + + @param Bridge Bridge device instance + @param Decode Decode type according to resource type + + @return whether bridge device support decode resource + +**/ BOOLEAN BridgeSupportResourceDecode ( IN PCI_IO_DEVICE *Bridge, IN UINT32 Decode ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - Decode - TODO: add argument description - -Returns: - - TODO: add return values - -**/ { - /** -Routine Description: - -Arguments: - -Returns: - - None - -**/ if ((Bridge->Decodes) & Decode) { return TRUE; } @@ -1118,29 +1016,21 @@ Returns: return FALSE; } +/** + This function is used to program the resource allocated + for each resource node + + + @param Base Base address of resource + @param Bridge Bridge device instance + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramResource ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - This function is used to program the resource allocated - for each resource node - -Arguments: - -Returns: - - None - -**/ -// TODO: Base - add argument and description to function comment -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { LIST_ENTRY *CurrentLink; PCI_RESOURCE_NODE *Node; @@ -1179,25 +1069,19 @@ Returns: return EFI_SUCCESS; } +/** + Program Bar register. + + @param Base Base address for resource + @param Node Point to resoure node structure + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramBar ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Base - add argument and description to function comment -// TODO: Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_PCI_IO_PROTOCOL *PciIo; UINT64 Address; @@ -1269,26 +1153,19 @@ Returns: return EFI_SUCCESS; } +/** + Program PPB apperture + + @param Base Base address for resource + @param Node Point to resoure node structure + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramPpbApperture ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Base - add argument and description to function comment -// TODO: Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_PCI_IO_PROTOCOL *PciIo; UINT64 Address; @@ -1450,25 +1327,21 @@ Returns: return EFI_SUCCESS; } +/** + Program parent bridge for oprom + + @param PciDevice Pci deivce instance + @param OptionRomBase Base address for oprom + @param Enable Enable/Disable + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgrameUpstreamBridgeForRom ( IN PCI_IO_DEVICE *PciDevice, IN UINT32 OptionRomBase, IN BOOLEAN Enable ) -/** - -Routine Description: - -Arguments: - -Returns: - -**/ -// TODO: PciDevice - add argument and description to function comment -// TODO: OptionRomBase - add argument and description to function comment -// TODO: Enable - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_IO_DEVICE *Parent; PCI_RESOURCE_NODE Node; @@ -1506,23 +1379,17 @@ Returns: return EFI_SUCCESS; } +/** + Test whether resource exists for a bridge + + @param Bridge Point to resource node for a bridge + + @return whether resource exists +**/ BOOLEAN ResourceRequestExisted ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - -Arguments: - - Bridge - A pointer to the PCI_RESOURCE_NODE. - -Returns: - - None - -**/ { if (Bridge != NULL) { if (!IsListEmpty (&Bridge->ChildList) || Bridge->Length != 0) { @@ -1533,25 +1400,17 @@ Returns: return FALSE; } +/** + Initialize resource pool structure. + + @param ResourcePool Point to resource pool structure + @param ResourceType Type of resource +**/ EFI_STATUS InitializeResourcePool ( PCI_RESOURCE_NODE *ResourcePool, PCI_BAR_TYPE ResourceType ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: ResourcePool - add argument and description to function comment -// TODO: ResourceType - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { ZeroMem (ResourcePool, sizeof (PCI_RESOURCE_NODE)); @@ -1562,6 +1421,23 @@ Returns: return EFI_SUCCESS; } +/** + Get all resource information for given Pci device + + @param PciDev Pci device instance + @param IoBridge Io resource node + @param Mem32Bridge 32-bit memory node + @param PMem32Bridge 32-bit Pmemory node + @param Mem64Bridge 64-bit memory node + @param PMem64Bridge 64-bit PMemory node + @param IoPool Link list header for Io resource + @param Mem32Pool Link list header for 32-bit memory + @param PMem32Pool Link list header for 32-bit Pmemory + @param Mem64Pool Link list header for 64-bit memory + @param PMem64Pool Link list header for 64-bit Pmemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS GetResourceMap ( PCI_IO_DEVICE *PciDev, @@ -1576,29 +1452,6 @@ GetResourceMap ( PCI_RESOURCE_NODE *Mem64Pool, PCI_RESOURCE_NODE *PMem64Pool ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDev - add argument and description to function comment -// TODO: IoBridge - add argument and description to function comment -// TODO: Mem32Bridge - add argument and description to function comment -// TODO: PMem32Bridge - add argument and description to function comment -// TODO: Mem64Bridge - add argument and description to function comment -// TODO: PMem64Bridge - add argument and description to function comment -// TODO: IoPool - add argument and description to function comment -// TODO: Mem32Pool - add argument and description to function comment -// TODO: PMem32Pool - add argument and description to function comment -// TODO: Mem64Pool - add argument and description to function comment -// TODO: PMem64Pool - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_RESOURCE_NODE *Temp; @@ -1687,23 +1540,17 @@ Returns: return EFI_SUCCESS; } +/** + Destory given resource tree + + @param Bridge root node of resource tree + + @retval EFI_SUCCESS Success +**/ EFI_STATUS DestroyResourceTree ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_RESOURCE_NODE *Temp; LIST_ENTRY *CurrentLink; @@ -1726,6 +1573,14 @@ Returns: return EFI_SUCCESS; } +/** + Record the reserved resource and insert to reserved list. + + @param Base Base address of reserved resourse + @param Length Length of reserved resource + @param ResType Resource type + @param Bridge Pci device instance +**/ EFI_STATUS RecordReservedResource ( IN UINT64 Base, @@ -1733,23 +1588,6 @@ RecordReservedResource ( IN PCI_BAR_TYPE ResType, IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Base - add argument and description to function comment -// TODO: Length - add argument and description to function comment -// TODO: ResType - add argument and description to function comment -// TODO: Bridge - add argument and description to function comment -// TODO: EFI_OUT_OF_RESOURCES - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_RESERVED_RESOURCE_LIST *ReservedNode; @@ -1768,6 +1606,18 @@ Returns: return EFI_SUCCESS; } +/** + Insert resource padding for P2C + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ResourcePaddingForCardBusBridge ( PCI_IO_DEVICE *PciDev, @@ -1777,24 +1627,6 @@ ResourcePaddingForCardBusBridge ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDev - add argument and description to function comment -// TODO: IoNode - add argument and description to function comment -// TODO: Mem32Node - add argument and description to function comment -// TODO: PMem32Node - add argument and description to function comment -// TODO: Mem64Node - add argument and description to function comment -// TODO: PMem64Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { PCI_RESOURCE_NODE *Node; @@ -1875,25 +1707,19 @@ Returns: return EFI_SUCCESS; } +/** + Program P2C register for given resource node + + @param Base Base address of P2C device + @param Node Given resource node. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramP2C ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: Base - add argument and description to function comment -// TODO: Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_PCI_IO_PROTOCOL *PciIo; UINT64 Address; @@ -2118,6 +1944,19 @@ Returns: return EFI_SUCCESS; } +/** + Create padding resource node. + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success + +**/ EFI_STATUS ApplyResourcePadding ( PCI_IO_DEVICE *PciDev, @@ -2127,24 +1966,6 @@ ApplyResourcePadding ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - -Arguments: - -Returns: - - None - -**/ -// TODO: PciDev - add argument and description to function comment -// TODO: IoNode - add argument and description to function comment -// TODO: Mem32Node - add argument and description to function comment -// TODO: PMem32Node - add argument and description to function comment -// TODO: Mem64Node - add argument and description to function comment -// TODO: PMem64Node - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_ACPI_ADDRESS_SPACE_DESCRIPTOR *Ptr; PCI_RESOURCE_NODE *Node; @@ -2283,29 +2104,17 @@ Returns: return EFI_SUCCESS; } -// -// Light PCI bus driver woundn't support hotplug root device -// So no need to pad resource for them -// +/** + Get padding resource for PPB + Light PCI bus driver woundn't support hotplug root device + So no need to pad resource for them + + @param PciIoDevice Pci device instance +**/ VOID GetResourcePaddingPpb ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - Get resource. - -Arguments: - - PciIoDevice A pointer to a pci device. - -Returns: - - None - -**/ { if (gPciHotPlugInit) { if (PciIoDevice->ResourcePaddingDescriptors == NULL) { @@ -2313,3 +2122,4 @@ Returns: } } } + diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.h index 87d0b9146e..b255dc9ca9 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciResourceSupport.h @@ -59,142 +59,120 @@ typedef struct { #define RESOURCE_NODE_FROM_LINK(a) \ CR (a, PCI_RESOURCE_NODE, Link, PCI_RESOURCE_SIGNATURE) +/** + The function is used to skip VGA range + + @param Start address including VGA range + @param Length length of VGA range. + + @retval EFI_SUCCESS success +**/ EFI_STATUS SkipVGAAperture ( OUT UINT64 *Start, IN UINT64 Length ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Start - TODO: add argument description - Length - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to skip ISA aliasing aperture + + @param Start address including ISA aliasing aperture + @param Length length of ISA aliasing aperture + + @retval EFI_SUCCESS success +**/ EFI_STATUS SkipIsaAliasAperture ( OUT UINT64 *Start, IN UINT64 Length ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Start - TODO: add argument description - Length - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function inserts a resource node into the resource list. + The resource list is sorted in descend order. + + @param Bridge PCI resource node for bridge + @param ResNode Resource node want to be inserted + + @retval EFI_SUCCESS Success +**/ EFI_STATUS InsertResourceNode ( PCI_RESOURCE_NODE *Bridge, PCI_RESOURCE_NODE *ResNode ) +; + /** Routine Description: - TODO: Add function description + This routine is used to merge two different resource tree in need of + resoure degradation. For example, if a upstream PPB doesn't support, + prefetchable memory decoding, the PCI bus driver will choose to call this function + to merge prefectchable memory resource list into normal memory list. -Arguments: - - Bridge - TODO: add argument description - ResNode - TODO: add argument description - -Returns: - - TODO: add return values + If the TypeMerge is TRUE, Res resource type is changed to the type of destination resource + type. + @param Dst Point to destination resource tree + @param Res Point to source resource tree + @param TypeMerge If the TypeMerge is TRUE, Res resource type is changed to the type of + destination resource type. + + + @retval EFI_SUCCESS Success **/ -; - EFI_STATUS MergeResourceTree ( PCI_RESOURCE_NODE *Dst, PCI_RESOURCE_NODE *Res, BOOLEAN TypeMerge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Dst - TODO: add argument description - Res - TODO: add argument description - TypeMerge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to calculate the IO16 aperture + for a bridge. + + @param Bridge PCI resource node for bridge. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CalculateApertureIo16 ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to calculate the resource aperture + for a given bridge device + + @param Bridge Give bridge device + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CalculateResourceAperture ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Get IO/Memory resource infor for given PCI device + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS GetResourceFromDevice ( PCI_IO_DEVICE *PciDev, @@ -204,28 +182,18 @@ GetResourceFromDevice ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - IoNode - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to create a resource node + + @param PciDev Pci device instance + @param Length Length of Io/Memory resource + @param Alignment Alignment of resource + @param Bar Bar index + @param ResType Type of resource: IO/Memory + @param ResUage Resource usage +**/ PCI_RESOURCE_NODE * CreateResourceNode ( IN PCI_IO_DEVICE *PciDev, @@ -235,28 +203,21 @@ CreateResourceNode ( IN PCI_BAR_TYPE ResType, IN PCI_RESOURCE_USAGE ResUsage ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - Length - TODO: add argument description - Alignment - TODO: add argument description - Bar - TODO: add argument description - ResType - TODO: add argument description - ResUsage - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This routine is used to extract resource request from + device node list. + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS CreateResourceMap ( IN PCI_IO_DEVICE *Bridge, @@ -266,28 +227,20 @@ CreateResourceMap ( IN PCI_RESOURCE_NODE *Mem64Node, IN PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - IoNode - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to do the resource padding for a specific platform + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ResourcePaddingPolicy ( PCI_IO_DEVICE *PciDev, @@ -297,28 +250,24 @@ ResourcePaddingPolicy ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - IoNode - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to degrade resource if the upstream bridge + doesn't support certain resource. Degradation path is + PMEM64 -> MEM64 -> MEM32 + PMEM64 -> PMEM32 -> MEM32 + IO32 -> IO16 + + @param Bridge Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS DegradeResource ( IN PCI_IO_DEVICE *Bridge, @@ -327,188 +276,131 @@ DegradeResource ( IN PCI_RESOURCE_NODE *Mem64Node, IN PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether bridge device support decode resource + + @param Bridge Bridge device instance + @param Decode Decode type according to resource type + + @return whether bridge device support decode resource + +**/ BOOLEAN BridgeSupportResourceDecode ( IN PCI_IO_DEVICE *Bridge, IN UINT32 Decode ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - Decode - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + This function is used to program the resource allocated + for each resource node + + + @param Base Base address of resource + @param Bridge Bridge device instance + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramResource ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Base - TODO: add argument description - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Program Bar register. + + @param Base Base address for resource + @param Node Point to resoure node structure + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramBar ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Base - TODO: add argument description - Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Program PPB apperture + + @param Base Base address for resource + @param Node Point to resoure node structure + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramPpbApperture ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Base - TODO: add argument description - Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Program parent bridge for oprom + + @param PciDevice Pci deivce instance + @param OptionRomBase Base address for oprom + @param Enable Enable/Disable + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgrameUpstreamBridgeForRom ( IN PCI_IO_DEVICE *PciDevice, IN UINT32 OptionRomBase, IN BOOLEAN Enable ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDevice - TODO: add argument description - OptionRomBase - TODO: add argument description - Enable - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Test whether resource exists for a bridge + + @param Bridge Point to resource node for a bridge + + @return whether resource exists +**/ BOOLEAN ResourceRequestExisted ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Initialize resource pool structure. + + @param ResourcePool Point to resource pool structure + @param ResourceType Type of resource +**/ EFI_STATUS InitializeResourcePool ( PCI_RESOURCE_NODE *ResourcePool, PCI_BAR_TYPE ResourceType ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - ResourcePool - TODO: add argument description - ResourceType - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Get all resource information for given Pci device + + @param PciDev Pci device instance + @param IoBridge Io resource node + @param Mem32Bridge 32-bit memory node + @param PMem32Bridge 32-bit Pmemory node + @param Mem64Bridge 64-bit memory node + @param PMem64Bridge 64-bit PMemory node + @param IoPool Link list header for Io resource + @param Mem32Pool Link list header for 32-bit memory + @param PMem32Pool Link list header for 32-bit Pmemory + @param Mem64Pool Link list header for 64-bit memory + @param PMem64Pool Link list header for 64-bit Pmemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS GetResourceMap ( PCI_IO_DEVICE *PciDev, @@ -523,54 +415,29 @@ GetResourceMap ( PCI_RESOURCE_NODE *Mem64Pool, PCI_RESOURCE_NODE *PMem64Pool ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - IoBridge - TODO: add argument description - Mem32Bridge - TODO: add argument description - PMem32Bridge - TODO: add argument description - Mem64Bridge - TODO: add argument description - PMem64Bridge - TODO: add argument description - IoPool - TODO: add argument description - Mem32Pool - TODO: add argument description - PMem32Pool - TODO: add argument description - Mem64Pool - TODO: add argument description - PMem64Pool - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Destory given resource tree + + @param Bridge root node of resource tree + + @retval EFI_SUCCESS Success +**/ EFI_STATUS DestroyResourceTree ( IN PCI_RESOURCE_NODE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Record the reserved resource and insert to reserved list. + + @param Base Base address of reserved resourse + @param Length Length of reserved resource + @param ResType Resource type + @param Bridge Pci device instance +**/ EFI_STATUS RecordReservedResource ( IN UINT64 Base, @@ -578,26 +445,20 @@ RecordReservedResource ( IN PCI_BAR_TYPE ResType, IN PCI_IO_DEVICE *Bridge ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Base - TODO: add argument description - Length - TODO: add argument description - ResType - TODO: add argument description - Bridge - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Insert resource padding for P2C + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ResourcePaddingForCardBusBridge ( PCI_IO_DEVICE *PciDev, @@ -607,51 +468,36 @@ ResourcePaddingForCardBusBridge ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - IoNode - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Program P2C register for given resource node + + @param Base Base address of P2C device + @param Node Given resource node. + + @retval EFI_SUCCESS Success +**/ EFI_STATUS ProgramP2C ( IN UINT64 Base, IN PCI_RESOURCE_NODE *Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - Base - TODO: add argument description - Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Create padding resource node. + + @param PciDev Pci device instance + @param IoNode Resource info node for IO + @param Mem32Node Resource info node for 32-bit memory + @param PMem32Node Resource info node for 32-bit PMemory + @param Mem64Node Resource info node for 64-bit memory + @param PMem64Node Resource info node for 64-bit PMemory + + @retval EFI_SUCCESS Success + +**/ EFI_STATUS ApplyResourcePadding ( PCI_IO_DEVICE *PciDev, @@ -661,70 +507,32 @@ ApplyResourcePadding ( PCI_RESOURCE_NODE *Mem64Node, PCI_RESOURCE_NODE *PMem64Node ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciDev - TODO: add argument description - IoNode - TODO: add argument description - Mem32Node - TODO: add argument description - PMem32Node - TODO: add argument description - Mem64Node - TODO: add argument description - PMem64Node - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Get padding resource for PPB + Light PCI bus driver woundn't support hotplug root device + So no need to pad resource for them + + @param PciIoDevice Pci device instance +**/ VOID GetResourcePaddingPpb ( IN PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Reset and all bus number from specific bridge. + + @param Bridge Parent specific bridge + @param StartBusNumber start bus number +**/ EFI_STATUS ResetAllPpbBusNumber ( IN PCI_IO_DEVICE *Bridge, IN UINT8 StartBusNumber ) -/** - -Routine Description: - - Reset bus register - -Arguments: - - Bridge - a pointer to the PCI_IO_DEVICE - StartBusNumber - the number of bus - -Returns: - - None - -**/ ; #endif diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.c b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.c index 18ee0a89fa..bacd2ebd5d 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.c +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.c @@ -29,6 +29,17 @@ static UINTN mNumberOfPciRomImages = 0; static UINTN mMaxNumberOfPciRomImages = 0; static EFI_PCI_ROM_IMAGE_MAPPING *mRomImageTable = NULL; +/** + Add the Rom Image to internal database for later PCI light enumeration + + @param ImageHandle Option Rom image handle + @param Seg Segment of PCI space + @param Bus Bus NO of PCI space + @param Dev Dev NO of PCI space + @param Func Func NO of PCI space + @param RomAddress Base address of OptionRom + @param RomLength Length of rom image. +**/ VOID PciRomAddImageMapping ( IN EFI_HANDLE ImageHandle, @@ -39,27 +50,6 @@ PciRomAddImageMapping ( IN UINT64 RomAddress, IN UINT64 RomLength ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - ImageHandle - TODO: add argument description - Seg - TODO: add argument description - Bus - TODO: add argument description - Dev - TODO: add argument description - Func - TODO: add argument description - RomAddress - TODO: add argument description - RomLength - TODO: add argument description - -Returns: - - TODO: add return values - -**/ { EFI_PCI_ROM_IMAGE_MAPPING *TempMapping; @@ -92,26 +82,19 @@ Returns: mNumberOfPciRomImages++; } +/** + Load all option rom image to PCI driver list. + + @param This Pointer to protocol instance EFI_DRIVER_BINDING_PROTOCOL + @param PciRootBridgeIo Root bridge Io instance + @param PciIoDevice device instance +**/ EFI_STATUS PciRomGetRomResourceFromPciOptionRomTable ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo, PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - -Returns: - -**/ -// TODO: This - add argument and description to function comment -// TODO: PciRootBridgeIo - add argument and description to function comment -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_NOT_FOUND - add return value to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; EFI_PCI_OPTION_ROM_TABLE *PciOptionRomTable; @@ -148,21 +131,16 @@ Returns: return EFI_SUCCESS; } +/** + Get Option rom driver's mapping for PCI device. + + @param PciIoDevice Device instance. + +**/ EFI_STATUS PciRomGetImageMapping ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - -Arguments: - -Returns: - -**/ -// TODO: PciIoDevice - add argument and description to function comment -// TODO: EFI_SUCCESS - add return value to function comment { EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo; UINTN Index; diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.h index 9cb9966c85..59bff9279f 100644 --- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.h +++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciRomTable.h @@ -15,6 +15,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #ifndef _EFI_PCI_ROM_TABLE_H #define _EFI_PCI_ROM_TABLE_H +/** + Add the Rom Image to internal database for later PCI light enumeration + + @param ImageHandle Option Rom image handle + @param Seg Segment of PCI space + @param Bus Bus NO of PCI space + @param Dev Dev NO of PCI space + @param Func Func NO of PCI space + @param RomAddress Base address of OptionRom + @param RomLength Length of rom image. +**/ VOID PciRomAddImageMapping ( IN EFI_HANDLE ImageHandle, @@ -25,74 +36,32 @@ PciRomAddImageMapping ( IN UINT64 RomAddress, IN UINT64 RomLength ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - ImageHandle - TODO: add argument description - Seg - TODO: add argument description - Bus - TODO: add argument description - Dev - TODO: add argument description - Func - TODO: add argument description - RomAddress - TODO: add argument description - RomLength - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; - - +/** + Load all option rom image to PCI driver list. + + @param This Pointer to protocol instance EFI_DRIVER_BINDING_PROTOCOL + @param PciRootBridgeIo Root bridge Io instance + @param PciIoDevice device instance +**/ EFI_STATUS PciRomGetRomResourceFromPciOptionRomTable ( IN EFI_DRIVER_BINDING_PROTOCOL *This, IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo, PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - This - TODO: add argument description - PciRootBridgeIo - TODO: add argument description - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; +/** + Get Option rom driver's mapping for PCI device. + + @param PciIoDevice Device instance. + +**/ EFI_STATUS PciRomGetImageMapping ( PCI_IO_DEVICE *PciIoDevice ) -/** - -Routine Description: - - TODO: Add function description - -Arguments: - - PciIoDevice - TODO: add argument description - -Returns: - - TODO: add return values - -**/ ; #endif