From: qhuang8 Date: Thu, 11 May 2006 07:19:55 +0000 (+0000) Subject: *BaseSmbusLib: (new version) X-Git-Tag: edk2-stable201903~25525 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=5f10fa0140f7100aa04c12f87d63a66755d20d58;ds=sidebyside *BaseSmbusLib: (new version) Complete function header, detailed description, ASSERT()s & pass smoke test in MRC of Lakeport package by replacing Smbus PPI. *Device Patch Lib Fix a bug in AppendDevicePathNode() (Solve Track #44 in Remodel PVCS). The original logic failed if the first device path was NULL. *Performance Lib Add PeiPerformanceHob & Performance protocol in spd file in EdkModule Package (Solve Tracker #41, #42 in Remodel PVCS). *Hob Lib Add detailed description for each Hob function. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@126 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/EdkModulePkg/EdkModulePkg.spd b/EdkModulePkg/EdkModulePkg.spd index f2bdfa0401..40c20d47c3 100644 --- a/EdkModulePkg/EdkModulePkg.spd +++ b/EdkModulePkg/EdkModulePkg.spd @@ -469,6 +469,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. gEfiCompatibleMemoryTestedGuid 0x64c475ef, 0x344b, 0x492c, 0x93, 0xad, 0xab, 0x9e, 0xb4, 0x39, 0x50, 0x4 + + gPeiPerformanceHobGuid + 0xec4df5af, 0x4395, 0x4cc9, 0x94, 0xde, 0x77, 0x50, 0x6d, 0x12, 0xc7, 0xb8 + @@ -571,6 +575,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. gEfiIsaAcpiProtocolGuid 0x64a892dc, 0x5561, 0x4536, 0x92, 0xc7, 0x79, 0x9b, 0xfc, 0x18, 0x33, 0x55 + + gPerformanceProtocolGuid + 0x76b6bdfa, 0x2acd, 0x4462, 0x9E, 0x3F, 0xcb, 0x58, 0xC9, 0x69, 0xd9, 0x37 + diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h index bedbd1c0d4..b42a8fecfd 100644 --- a/MdePkg/Include/Library/DevicePathLib.h +++ b/MdePkg/Include/Library/DevicePathLib.h @@ -74,24 +74,23 @@ AppendDevicePath ( ; /** - This function appends the device path node SecondDevicePath - to every device path instance in FirstDevicePath. + This function appends the device path node SecondDevicePath + to every device path instance in FirstDevicePath. - @param FirstDevicePath A pointer to a device path data structure. - - @param SecondDevicePath A pointer to a single device path node. + @param DevicePath A pointer to a device path data structure. + + @param DevicePathNode A pointer to a single device path node. - @return - A pointer to the new device path. - If there is not enough temporary pool memory available to complete this function, - then NULL is returned. + @return A pointer to the new device path. + If there is not enough temporary pool memory available to complete this function, + then NULL is returned. **/ EFI_DEVICE_PATH_PROTOCOL * EFIAPI AppendDevicePathNode ( - IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath, - IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode ) ; diff --git a/MdePkg/Include/Library/HobLib.h b/MdePkg/Include/Library/HobLib.h index cac9c4fa09..9789c693e7 100644 --- a/MdePkg/Include/Library/HobLib.h +++ b/MdePkg/Include/Library/HobLib.h @@ -18,9 +18,11 @@ #define __HOB_LIB_H__ /** - Returns the pointer to the HOB list. + Returns the pointer to the HOB list. - @return The pointer to the HOB list. + This function returns the pointer to first HOB in the list. + + @return The pointer to the HOB list. **/ VOID * @@ -31,13 +33,19 @@ GetHobList ( ; /** - This function searches the first instance of a HOB type from the starting HOB pointer. - If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + Returns the next instance of a HOB type from the starting HOB. + + This function searches the first instance of a HOB type from the starting HOB pointer. + If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). - @param Type The HOB type to return. - @param HobStart The starting HOB pointer to search from. + @param Type The HOB type to return. + @param HobStart The starting HOB pointer to search from. - @return The next instance of a HOB type from the starting HOB. + @return The next instance of a HOB type from the starting HOB. **/ VOID * @@ -49,12 +57,14 @@ GetNextHob ( ; /** - This function searches the first instance of a HOB type among the whole HOB list. - If there does not exist such HOB type in the HOB list, it will return NULL. + Returns the first instance of a HOB type among the whole HOB list. - @param Type The HOB type to return. + This function searches the first instance of a HOB type among the whole HOB list. + If there does not exist such HOB type in the HOB list, it will return NULL. - @return The next instance of a HOB type from the starting HOB. + @param Type The HOB type to return. + + @return The next instance of a HOB type from the starting HOB. **/ VOID * @@ -65,15 +75,22 @@ GetFirstHob ( ; /** - This function searches the first instance of a HOB from the starting HOB pointer. - Such HOB should satisfy two conditions: - its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. - If there does not exist such HOB from the starting HOB pointer, it will return NULL. - - @param Guid The GUID to match with in the HOB list. - @param HobStart A pointer to a Guid. - - @return The next instance of the matched GUID HOB from the starting HOB. + This function searches the first instance of a HOB from the starting HOB pointer. + Such HOB should satisfy two conditions: + its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. + If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). + If HobStart is NULL, then ASSERT(). + + @param Guid The GUID to match with in the HOB list. + @param HobStart A pointer to a Guid. + + @return The next instance of the matched GUID HOB from the starting HOB. **/ VOID * @@ -85,14 +102,17 @@ GetNextGuidHob ( ; /** - This function searches the first instance of a HOB among the whole HOB list. - Such HOB should satisfy two conditions: - its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. - If there does not exist such HOB from the starting HOB pointer, it will return NULL. + This function searches the first instance of a HOB among the whole HOB list. + Such HOB should satisfy two conditions: + its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. + If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + If Guid is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. + @param Guid The GUID to match with in the HOB list. - @return The first instance of the matched GUID HOB among the whole HOB list. + @return The first instance of the matched GUID HOB among the whole HOB list. **/ VOID * @@ -103,12 +123,18 @@ GetFirstGuidHob ( ; /** - This function builds a HOB for a loaded PE32 module. + Builds a HOB for a loaded PE32 module. + + This function builds a HOB for a loaded PE32 module. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). - @param ModuleName The GUID File Name of the module. - @param MemoryAllocationModule The 64 bit physical address of the module. - @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module’s entry point. + @param ModuleName The GUID File Name of the module. + @param MemoryAllocationModule The 64 bit physical address of the module. + @param ModuleLength The length of the module in bytes. + @param EntryPoint The 64 bit physical address of the module’s entry point. **/ VOID @@ -122,12 +148,17 @@ BuildModuleHob ( ; /** - Builds a HOB that describes a chunk of system memory. + Builds a HOB that describes a chunk of system memory. - @param ResourceType The type of resource described by this HOB. - @param ResourceAttribute The resource attributes of the memory described by this HOB. - @param PhysicalStart The 64 bit physical address of memory described by this HOB. - @param NumberOfBytes The length of the memory described by this HOB in bytes. + This function builds a HOB that describes a chunk of system memory. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param ResourceType The type of resource described by this HOB. + @param ResourceAttribute The resource attributes of the memory described by this HOB. + @param PhysicalStart The 64 bit physical address of memory described by this HOB. + @param NumberOfBytes The length of the memory described by this HOB in bytes. **/ VOID @@ -141,13 +172,21 @@ BuildResourceDescriptorHob ( ; /** - This function builds a customized HOB tagged with a GUID for identification - and returns the start address of GUID HOB data so that caller can fill the customized data. + Builds a GUID HOB with a certain data length. + + This function builds a customized HOB tagged with a GUID for identification + and returns the start address of GUID HOB data so that caller can fill the customized data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @param Guid The GUID to tag the customized HOB. - @param DataLength The size of the data payload for the GUID HOB. + @param Guid The GUID to tag the customized HOB. + @param DataLength The size of the data payload for the GUID HOB. - @return The start address of GUID HOB data. + @return The start address of GUID HOB data. **/ VOID * @@ -159,14 +198,23 @@ BuildGuidHob ( ; /** - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field, and returns the start address of GUID HOB data. + Copies a data buffer to a newly-built HOB. - @param Guid The GUID to tag the customized HOB. - @param Data The data to be copied into the data field of the GUID HOB. - @param DataLength The size of the data payload for the GUID HOB. + This function builds a customized HOB tagged with a GUID for identification, + copies the input data to the HOB data field and returns the start address of the GUID HOB data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If Data is NULL and DataLength > 0, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @return The start address of GUID HOB data. + @param Guid The GUID to tag the customized HOB. + @param Data The data to be copied into the data field of the GUID HOB. + @param DataLength The size of the data payload for the GUID HOB. + + @return The start address of GUID HOB data. **/ VOID * @@ -179,10 +227,15 @@ BuildGuidDataHob ( ; /** - Builds a Firmware Volume HOB. + Builds a Firmware Volume HOB. + + This function builds a Firmware Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). - @param BaseAddress The base address of the Firmware Volume. - @param Length The size of the Firmware Volume in bytes. + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. **/ VOID @@ -194,10 +247,15 @@ BuildFvHob ( ; /** - Builds a Capsule Volume HOB. + Builds a Capsule Volume HOB. - @param BaseAddress The base address of the Capsule Volume. - @param Length The size of the Capsule Volume in bytes. + This function builds a Capsule Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Capsule Volume. + @param Length The size of the Capsule Volume in bytes. **/ VOID @@ -209,10 +267,15 @@ BuildCvHob ( ; /** - Builds a HOB for the CPU. + Builds a HOB for the CPU. + + This function builds a HOB for the CPU. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). - @param SizeOfMemorySpace The maximum physical memory addressability of the processor. - @param SizeOfIoSpace The maximum physical I/O addressability of the processor. + @param SizeOfMemorySpace The maximum physical memory addressability of the processor. + @param SizeOfIoSpace The maximum physical I/O addressability of the processor. **/ VOID @@ -224,10 +287,15 @@ BuildCpuHob ( ; /** - Builds a HOB for the Stack. + Builds a HOB for the Stack. - @param BaseAddress The 64 bit physical address of the Stack. - @param Length The length of the stack in bytes. + This function builds a HOB for the stack. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the Stack. + @param Length The length of the stack in bytes. **/ VOID @@ -239,11 +307,16 @@ BuildStackHob ( ; /** - Builds a HOB for the BSP store. + Builds a HOB for the BSP store. + + This function builds a HOB for BSP store. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). - @param BaseAddress The 64 bit physical address of the BSP. - @param Length The length of the BSP store in bytes. - @param MemoryType Type of memory allocated by this HOB. + @param BaseAddress The 64 bit physical address of the BSP. + @param Length The length of the BSP store in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID @@ -256,11 +329,16 @@ BuildBspStoreHob ( ; /** - Builds a HOB for the memory allocation. + Builds a HOB for the memory allocation. + + This function builds a HOB for the memory allocation. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). - @param BaseAddress The 64 bit physical address of the memory. - @param Length The length of the memory allocation in bytes. - @param MemoryType Type of memory allocated by this HOB. + @param BaseAddress The 64 bit physical address of the memory. + @param Length The length of the memory allocation in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID diff --git a/MdePkg/Library/BaseSmbusLib/BaseSmbusLib.msa b/MdePkg/Library/BaseSmbusLib/BaseSmbusLib.msa index 00c2aa4a03..25b8f51400 100644 --- a/MdePkg/Library/BaseSmbusLib/BaseSmbusLib.msa +++ b/MdePkg/Library/BaseSmbusLib/BaseSmbusLib.msa @@ -32,7 +32,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 2006-03-19 15:17 - SmBusLib + SmbusLib BaseLib IoLib PciLib diff --git a/MdePkg/Library/BaseSmbusLib/SmbusLib.c b/MdePkg/Library/BaseSmbusLib/SmbusLib.c index 5aad978836..29c09e730e 100644 --- a/MdePkg/Library/BaseSmbusLib/SmbusLib.c +++ b/MdePkg/Library/BaseSmbusLib/SmbusLib.c @@ -10,548 +10,852 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - Module Name: SmbusLib.h + Module Name: SmbusLib.c **/ -RETURN_STATUS -EFIAPI -BaseSmBusLibConstructor ( - IN VOID *Param1, - IN VOID *Param2 - ) -{ - return RETURN_SUCCESS; -} +#include "SmbusLibRegisters.h" -// -// BUGBUG: use PCD to retrieve BUS, DEV, FUNC & OFFSET for SMBUS host BAR -// -#define SMBUS_HOST_BUS 0 -#define SMBUS_HOST_DEV 31 -#define SMBUS_HOST_FUNC 3 -#define SMBUS_HOST_SMB_BASE 0x20 - -// -// Offsets of registers for SMBUS controller -// -#define R_HST_STS 0 -#define R_HST_CNT 2 -#define R_HST_CMD 3 -#define R_XMIT_SLVA 4 -#define R_HST_D0 5 -#define R_HST_D1 6 -#define R_HOST_BLOCK_DB 7 -#define R_PEC 8 -#define R_RCV_SLVA 9 -#define R_SLV_DATA 0x0a -#define R_AUX_STS 0x0c -#define R_AUX_CTL 0x0d -#define R_SMLINK_PIN_CTL 0x0e -#define R_SMBUS_PIN_CTL 0x0f -#define R_SLV_STS 0x10 -#define R_SLV_CMD 0x11 -#define R_NOTIFY_DADDR 0x14 -#define R_NOTIFY_DLOW 0x16 -#define R_NOTIFY_DHIGH 0x17 +#define SMBUS_LIB_SLAVE_ADDRESS(SmBusAddress) (((SmBusAddress) >> 1) & 0x7f) +#define SMBUS_LIB_COMMAND(SmBusAddress) (((SmBusAddress) >> 8) & 0xff) +#define SMBUS_LIB_LENGTH(SmBusAddress) (((SmBusAddress) >> 16) & 0x1f) +#define SMBUS_LIB_PEC(SmBusAddress) ((BOOLEAN) (((SmBusAddress) & SMBUS_LIB_PEC_BIT) != 0)) +#define SMBUS_LIB_RESEARVED(SmBusAddress) ((SmBusAddress) & ~(((1 << 21) - 2) | SMBUS_LIB_PEC_BIT)) // -// Bits in HST_STS +// Replaced by PCD // -#define B_HST_STS_DS 0x80 -#define B_HST_STS_INUSE 0x40 -#define B_HST_STS_SMBALERT 0x20 -#define B_HST_STS_FAILED 0x10 -#define B_HST_STS_BUS_ERR 0x08 -#define B_HST_STS_DEV_ERR 0x04 -#define B_HST_STS_INTR 0x02 -#define B_HST_STS_BUSY 0x01 -#define B_HST_STS_ERR ( B_HST_STS_BUS_ERR | \ - B_HST_STS_DEV_ERR | \ - B_HST_STS_FAILED ) -#define B_HST_STS_ALL ( B_HST_STS_DS | \ - B_HST_STS_INUSE | \ - B_HST_STS_SMBALERT | \ - B_HST_STS_ERR | \ - B_HST_STS_INTR ) +#define ICH_SMBUS_BASE_ADDRESS 0xEFA0 -// -// Bits in HST_CNT -// -#define B_HST_CNT_PEC 0x80 -#define B_HST_CNT_START 0x40 -#define B_HST_CNT_LAST_BYTE 0x20 -#define B_HST_CNT_SMB_CMD 0x1c -#define B_HST_CNT_KILL 0x02 -#define B_HST_CNT_INTREN 0x01 +/** + Reads an 8-bit SMBUS register on ICH. -// -// SMBUS Protocols -// -#define B_SMB_CMD_QUICK 0 -#define B_SMB_CMD_BYTE 1 -#define B_SMB_CMD_BYTE_DATA 2 -#define B_SMB_CMD_WORD_DATA 3 -#define B_SMB_CMD_PROCESS_CALL 4 -#define B_SMB_CMD_BLOCK 5 -#define B_SMB_CMD_I2C 6 -#define B_SMB_CMD_BLOCK_PROCESS 7 + This internal function reads an SMBUS register specified by Offset. -// -// Bits in AUX_CTL -// -#define B_AUX_CTL_E32B 0x02 -#define B_AUX_CTL_AAC 0x01 + @param Offset The offset of SMBUS register. -// -// SMBUS Rd/Wr control -// -#define B_SMBUS_READ 1 -#define B_SMBUS_WRITE 0 + @return The value read. -static -UINT16 -EFIAPI -GetSmBusIOBaseAddress ( - VOID +**/ +UINT8 +InternalSmBusIoRead8 ( + IN UINTN Offset ) { - UINT32 SmbusBar; - - SmbusBar = PciRead32 ( - PCI_LIB_ADDRESS ( - SMBUS_HOST_BUS, - SMBUS_HOST_DEV, - SMBUS_HOST_FUNC, - SMBUS_HOST_SMB_BASE - ) - ); - ASSERT ((SmbusBar & 0xffff001f) == 1); - return (UINT16)(SmbusBar & ~1); + return IoRead8 (ICH_SMBUS_BASE_ADDRESS + Offset); } -static -BOOLEAN -EFIAPI -SmBusAcquire ( - IN UINT16 SmBusBase - ) -{ - UINT8 HstSts; +/** + Writes an 8-bit SMBUS register on ICH. - HstSts = IoRead8 (SmBusBase + R_HST_STS); - if (HstSts & B_HST_STS_INUSE) { - return FALSE; - } + This internal function writes an SMBUS register specified by Offset. - // - // BUGBUG: Dead loop may occur here - // - while (HstSts & B_HST_STS_BUSY) { - ASSERT (HstSts & B_HST_STS_INUSE); - HstSts = IoRead8 (SmBusBase + R_HST_STS); - } - return TRUE; -} + @param Offset The offset of SMBUS register. + @param Value The value to write to SMBUS register. -static -VOID -EFIAPI -SmBusStart ( - IN UINT16 SmBusBase, - IN UINT8 SmBusProtocol, - IN UINT8 SlaveAddress + @return The value written the SMBUS register. + +**/ +UINT8 +InternalSmBusIoWrite8 ( + IN UINTN Offset, + IN UINT8 Value ) { - IoWrite8 (SmBusBase + R_XMIT_SLVA, SlaveAddress); - IoWrite8 ( - SmBusBase + R_HST_CNT, - IoBitFieldWrite8 (SmBusBase + R_HST_CNT, 2, 4, SmBusProtocol) | - B_HST_CNT_START - ); + return IoWrite8 (ICH_SMBUS_BASE_ADDRESS + Offset, Value); } -static -UINT8 -EFIAPI -SmBusWait ( - IN UINT16 SmBusBase +/** + Acquires the ownership of SMBUS. + + This internal function reads the host state register. + If the SMBUS is not available, RETURN_TIMEOUT is returned; + Otherwise, it performs some basic initializations and returns + RETURN_SUCCESS. + + @retval RETURN_SUCCESS The SMBUS command was executed successfully. + @retval RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + +**/ +RETURN_STATUS +InternalSmBusAcquire ( + VOID ) { - UINT8 HstSts; + UINT8 HostStatus; - while (((HstSts = IoRead8 (SmBusBase + R_HST_STS)) & B_HST_STS_INTR) == 0); - return HstSts; + HostStatus = InternalSmBusIoRead8 (SMBUS_R_HST_STS); + if ((HostStatus & SMBUS_B_INUSE_STS) != 0) { + return RETURN_TIMEOUT; + } else if ((HostStatus & SMBUS_B_HOST_BUSY) != 0) { + // + // Clear Status Register and exit + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_HSTS_ALL); + return RETURN_TIMEOUT; + } + // + // Clear byte pointer of 32-byte buffer. + // + InternalSmBusIoRead8 (SMBUS_R_HST_CTL); + // + // Clear BYTE_DONE status + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_BYTE_DONE_STS); + + return RETURN_SUCCESS; } -static -VOID -EFIAPI -SmBusCleanup ( - IN UINT16 SmBusBase +/** + Waits until the completion of SMBUS transaction. + + This internal function waits until the transaction of SMBUS is over + by polling the INTR bit of Host status register. + If the SMBUS is not available, RETURN_TIMEOUT is returned; + Otherwise, it performs some basic initializations and returns + RETURN_SUCCESS. + + @retval RETURN_SUCCESS The SMBUS command was executed successfully. + @retval RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + @retval RETURN_DEVICE_ERROR The request was not completed because a failure reflected + in the Host Status Register bit. Device errors are + a result of a transaction collision, illegal command field, + unclaimed cycle (host initiated), or bus errors (collisions). + +**/ +RETURN_STATUS +InternalSmBusWait ( + VOID ) { - IoWrite8 (SmBusBase + R_HST_STS, B_HST_STS_ALL); + UINT8 HostStatus; + UINT8 AuxiliaryStatus; + BOOLEAN First; + First = TRUE; + + do { + // + // Poll INTR bit of host status register. + // + HostStatus = InternalSmBusIoRead8 (SMBUS_R_HST_STS); + } while ((HostStatus & (SMBUS_B_INTR | SMBUS_B_ERROR | SMBUS_B_BYTE_DONE_STS)) == 0); + + if ((HostStatus & SMBUS_B_ERROR) == 0) { + return RETURN_SUCCESS; + } + // + // Clear error bits of host status register + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_ERROR); + // + // Read auxiliary status register to judge CRC error. + // + AuxiliaryStatus = InternalSmBusIoRead8 (SMBUS_R_AUX_STS); + if ((AuxiliaryStatus & SMBUS_B_CRCE) != 0) { + return RETURN_CRC_ERROR; + } + + return RETURN_DEVICE_ERROR; } -static -RETURN_STATUS +/** + Executes an SMBUS quick read/write command. + + This internal function executes an SMBUS quick read/write command + on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + +**/ +VOID EFIAPI -SmBusQuick ( - IN UINT8 SmBusAddress +InternalSmBusQuick ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - RETURN_STATUS Status; - UINT16 SmBusBase; + RETURN_STATUS ReturnStatus; - SmBusBase = GetSmBusIOBaseAddress (); - if (!SmBusAcquire (SmBusBase)) { - return RETURN_TIMEOUT; + ReturnStatus = InternalSmBusAcquire (); + if (RETURN_ERROR (ReturnStatus)) { + goto Done; } + + // + // Set Command register + // + InternalSmBusIoWrite8 (SMBUS_R_HST_CMD, 0); + // + // Set Auxiliary Control register + // + InternalSmBusIoWrite8 (SMBUS_R_AUX_CTL, 0); + // + // Set SMBus slave address for the device to send/receive from + // + InternalSmBusIoWrite8 (SMBUS_R_XMIT_SLVA, (UINT8) SmBusAddress); + // + // Set Control Register (Initiate Operation, Interrupt disabled) + // + InternalSmBusIoWrite8 (SMBUS_R_HST_CTL, SMBUS_V_SMB_CMD_QUICK + SMBUS_B_START); - SmBusStart (SmBusAddress, B_SMB_CMD_QUICK, SmBusAddress); - if (SmBusWait (SmBusAddress) & B_HST_STS_ERR) { - Status = RETURN_DEVICE_ERROR; - } else { - Status = RETURN_SUCCESS; - } + // + // Wait for the end + // + ReturnStatus = InternalSmBusWait (); - SmBusCleanup (SmBusAddress); - return Status; + // + // Clear status register and exit + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_HSTS_ALL);; + +Done: + if (Status != NULL) { + *Status = ReturnStatus; + } } +/** + Executes an SMBUS quick read command. + + Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + If PEC is set in SmBusAddress, then ASSERT(). + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + +**/ VOID EFIAPI SmBusQuickRead ( - IN UINTN SmBusAddress, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - RETURN_STATUS RetStatus; + ASSERT (!SMBUS_LIB_PEC (SmBusAddress)); + ASSERT (SMBUS_LIB_COMMAND (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); - ASSERT ((SmBusAddress & ~0xfe) == 0); - RetStatus = SmBusQuick ((UINT8)SmBusAddress | B_SMBUS_READ); - if (Status) { - *Status = RetStatus; - } + InternalSmBusQuick (SmBusAddress | SMBUS_B_READ, Status); } -BOOLEAN +/** + Executes an SMBUS quick write command. + + Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + If PEC is set in SmBusAddress, then ASSERT(). + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + +**/ +VOID EFIAPI SmBusQuickWrite ( - IN UINTN SmBusAddress, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - RETURN_STATUS RetStatus; + ASSERT (!SMBUS_LIB_PEC (SmBusAddress)); + ASSERT (SMBUS_LIB_COMMAND (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); - ASSERT ((SmBusAddress & ~0xfe) == 0); - RetStatus = SmBusQuick ((UINT8)SmBusAddress | B_SMBUS_WRITE); - if (Status) { - *Status = RetStatus; - } - return (BOOLEAN)!RETURN_ERROR (RetStatus); + InternalSmBusQuick (SmBusAddress | SMBUS_B_WRITE, Status); } -static +/** + Executes an SMBUS byte or word command. + + This internal function executes an . + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + + @param HostControl The value of Host Control Register to set. + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Value The byte/word write to the SMBUS. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The byte/word read from the SMBUS. + +**/ UINT16 -EFIAPI -SmBusByteWord ( - IN UINTN SmBusAddress, - IN UINT16 Value, - IN UINT8 SmBusProtocol, - OUT RETURN_STATUS *Status +InternalSmBusByteWord ( + IN UINT8 HostControl, + IN UINTN SmBusAddress, + IN UINT16 Value, + OUT RETURN_STATUS *Status ) { - RETURN_STATUS RetStatus; - UINT16 SmBusBase; + RETURN_STATUS ReturnStatus; + UINT8 AuxiliaryControl; - if (Status == NULL) { - Status = &RetStatus; + ReturnStatus = InternalSmBusAcquire (); + if (RETURN_ERROR (ReturnStatus)) { + goto Done; } - SmBusBase = GetSmBusIOBaseAddress (); - if (!SmBusAcquire (SmBusBase)) { - *Status = RETURN_TIMEOUT; - return Value; + AuxiliaryControl = 0; + if (SMBUS_LIB_PEC (SmBusAddress)) { + AuxiliaryControl |= SMBUS_B_AAC; + HostControl |= SMBUS_B_PEC_EN; } + + // + // Set commond register + // + InternalSmBusIoWrite8 (SMBUS_R_HST_CMD, (UINT8) SMBUS_LIB_COMMAND (SmBusAddress)); - IoWrite8 (SmBusBase + R_HST_CMD, (UINT8)(SmBusAddress >> 8)); - IoWrite8 (SmBusBase + R_HST_D0, (UINT8)Value); - IoWrite8 (SmBusBase + R_HST_D1, (UINT8)(Value >> 8)); - if ((INTN)SmBusAddress < 0) { - IoOr8 (SmBusBase + R_HST_CNT, B_HST_CNT_PEC); - IoOr8 (SmBusBase + R_AUX_CTL, B_AUX_CTL_AAC); - } else { - IoAnd8 (SmBusBase + R_HST_CNT, (UINT8)~B_HST_CNT_PEC); - IoAnd8 (SmBusBase + R_AUX_CTL, (UINT8)~B_AUX_CTL_AAC); - } + InternalSmBusIoWrite8 (SMBUS_R_HST_D0, (UINT8) Value); + InternalSmBusIoWrite8 (SMBUS_R_HST_D1, (UINT8) (Value >> 8)); + + // + // Set Auxiliary Control Regiester. + // + InternalSmBusIoWrite8 (SMBUS_R_AUX_CTL, AuxiliaryControl); + // + // Set SMBus slave address for the device to send/receive from. + // + InternalSmBusIoWrite8 (SMBUS_R_XMIT_SLVA, (UINT8) SmBusAddress); + // + // Set Control Register (Initiate Operation, Interrupt disabled) + // + InternalSmBusIoWrite8 (SMBUS_R_HST_CTL, HostControl + SMBUS_B_START); + + // + // Wait for the end + // + ReturnStatus = InternalSmBusWait (); + + Value = InternalSmBusIoRead8 (SMBUS_R_HST_D1) << 8; + Value |= InternalSmBusIoRead8 (SMBUS_R_HST_D0); - SmBusStart (SmBusBase, SmBusProtocol, (UINT8)SmBusAddress); + // + // Clear status register and exit + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_HSTS_ALL);; - if (SmBusWait (SmBusBase) & B_HST_STS_ERR) { - *Status = RETURN_DEVICE_ERROR; - } else { - *Status = RETURN_SUCCESS; - Value = IoRead8 (SmBusBase + R_HST_D0); - Value |= (UINT16)IoRead8 (SmBusBase + R_HST_D1) << 8; +Done: + if (Status != NULL) { + *Status = ReturnStatus; } - SmBusCleanup (SmBusBase); return Value; } +/** + Executes an SMBUS receive byte command. + + Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + The byte received from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The byte received from the SMBUS. + +**/ UINT8 EFIAPI SmBusReceiveByte ( - IN UINTN SmBusAddress, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfe | MAX_BIT)) == 0); - return (UINT8)SmBusByteWord ( - SmBusAddress | B_SMBUS_READ, - 0, - B_SMB_CMD_BYTE, - Status - ); + ASSERT (SMBUS_LIB_COMMAND (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return (UINT8) InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_BYTE, + SmBusAddress | SMBUS_B_READ, + 0, + Status + ); } +/** + Executes an SMBUS send byte command. + + Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress. + The byte specified by Value is sent. + Only the SMBUS slave address field of SmBusAddress is required. Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Value The 8-bit value to send. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The parameter of Value. + +**/ UINT8 EFIAPI SmBusSendByte ( - IN UINTN SmBusAddress, - IN UINT8 Value, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + IN UINT8 Value, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfe | MAX_BIT)) == 0); - return (UINT8)SmBusByteWord ( - SmBusAddress | B_SMBUS_WRITE, - Value, - B_SMB_CMD_BYTE, - Status - ); + ASSERT (SMBUS_LIB_COMMAND (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return (UINT8) InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_BYTE, + SmBusAddress | SMBUS_B_WRITE, + Value, + Status + ); } +/** + Executes an SMBUS read data byte command. + + Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 8-bit value read from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The byte read from the SMBUS. + +**/ UINT8 EFIAPI SmBusReadDataByte ( - IN UINTN SmBusAddress, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffe | MAX_BIT)) == 0); - return (UINT8)SmBusByteWord ( - SmBusAddress | B_SMBUS_READ, - 0, - B_SMB_CMD_BYTE_DATA, - Status - ); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return (UINT8) InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_BYTE_DATA, + SmBusAddress | SMBUS_B_READ, + 0, + Status + ); } +/** + Executes an SMBUS write data byte command. + + Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress. + The 8-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Value The 8-bit value to write. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The parameter of Value. + +**/ UINT8 EFIAPI SmBusWriteDataByte ( - IN UINTN SmBusAddress, - IN UINT8 Value, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + IN UINT8 Value, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT (((UINT32)SmBusAddress & ~(0xfffe | MAX_BIT)) == 0); - return (UINT8)SmBusByteWord ( - SmBusAddress | B_SMBUS_WRITE, - Value, - B_SMB_CMD_BYTE_DATA, - Status - ); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return (UINT8) InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_BYTE_DATA, + SmBusAddress | SMBUS_B_WRITE, + Value, + Status + ); } +/** + Executes an SMBUS read data word command. + + Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 16-bit value read from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The byte read from the SMBUS. + +**/ UINT16 EFIAPI SmBusReadDataWord ( - IN UINTN SmBusAddress, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffe | MAX_BIT)) == 0); - return SmBusByteWord ( - SmBusAddress | B_SMBUS_READ, + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_WORD_DATA, + SmBusAddress | SMBUS_B_READ, 0, - B_SMB_CMD_WORD_DATA, Status ); } +/** + Executes an SMBUS write data word command. + + Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress. + The 16-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Value The 16-bit value to write. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The parameter of Value. + +**/ UINT16 EFIAPI SmBusWriteDataWord ( - IN UINTN SmBusAddress, - IN UINT16 Value, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + IN UINT16 Value, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffe | MAX_BIT)) == 0); - return SmBusByteWord ( - SmBusAddress | B_SMBUS_WRITE, + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_WORD_DATA, + SmBusAddress | SMBUS_B_WRITE, Value, - B_SMB_CMD_WORD_DATA, Status ); } +/** + Executes an SMBUS process call command. + + Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress. + The 16-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 16-bit value returned by the process call command is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Value The 16-bit value to write. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The 16-bit value returned by the process call command. + +**/ UINT16 EFIAPI SmBusProcessCall ( - IN UINTN SmBusAddress, - IN UINT16 Value, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + IN UINT16 Value, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffe | MAX_BIT)) == 0); - return SmBusByteWord ( - SmBusAddress | B_SMBUS_WRITE, + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusByteWord ( + SMBUS_V_SMB_CMD_PROCESS_CALL, + SmBusAddress | SMBUS_B_WRITE, Value, - B_SMB_CMD_PROCESS_CALL, Status ); } -static +/** + Executes an SMBUS block command. + + Executes an SMBUS block read, block write and block write-block read command + on the SMBUS device specified by SmBusAddress. + Bytes are read from the SMBUS and stored in Buffer. + The number of bytes read is returned, and will never return a value larger than 32-bytes. + If Status is not NULL, then the status of the executed command is returned in Status. + It is the caller¡¯s responsibility to make sure Buffer is large enough for the total number of bytes read. + SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. + + @param HostControl The value of Host Control Register to set. + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param OutBuffer Pointer to the buffer of bytes to write to the SMBUS. + @param InBuffer Pointer to the buffer of bytes to read from the SMBUS. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The number of bytes read from the SMBUS. + +**/ UINTN -EFIAPI -SmBusBlock ( - IN UINTN SmBusAddress, - IN UINT8 SmBusProtocol, - IN VOID *InBuffer, - OUT VOID *OutBuffer, - OUT RETURN_STATUS *Status +InternalSmBusBlock ( + IN UINT8 HostControl, + IN UINTN SmBusAddress, + IN UINT8 *OutBuffer, + OUT UINT8 *InBuffer, + OUT RETURN_STATUS *Status ) { - RETURN_STATUS RetStatus; - UINT16 SmBusBase; - UINTN Index; - UINTN BytesCount; + RETURN_STATUS ReturnStatus; + UINTN Index; + UINTN BytesCount; + UINT8 AuxiliaryControl; - BytesCount = (UINT8)(SmBusAddress >> 16); - ASSERT (BytesCount <= 32); + BytesCount = SMBUS_LIB_LENGTH (SmBusAddress) + 1; - if (Status == NULL) { - Status = &RetStatus; + ReturnStatus = InternalSmBusAcquire (); + if (RETURN_ERROR (ReturnStatus)) { + goto Done; } - - SmBusBase = GetSmBusIOBaseAddress (); - if (!SmBusAcquire (SmBusBase)) { - *Status = RETURN_TIMEOUT; - return 0; + + AuxiliaryControl = SMBUS_B_E32B; + if (SMBUS_LIB_PEC (SmBusAddress)) { + AuxiliaryControl |= SMBUS_B_AAC; + HostControl |= SMBUS_B_PEC_EN; } - IoWrite8 (SmBusBase + R_HST_CMD, (UINT8)(SmBusAddress >> 8)); - IoWrite8 (SmBusBase + R_HST_D0, (UINT8)BytesCount); - if ((INTN)SmBusAddress < 0) { - IoOr8 (SmBusBase + R_HST_CNT, B_HST_CNT_PEC); - IoOr8 (SmBusBase + R_AUX_CTL, B_AUX_CTL_AAC); - } else { - IoAnd8 (SmBusBase + R_HST_CNT, (UINT8)~B_HST_CNT_PEC); - IoAnd8 (SmBusBase + R_AUX_CTL, (UINT8)~B_AUX_CTL_AAC); + InternalSmBusIoWrite8 (SMBUS_R_HST_CMD, (UINT8) SMBUS_LIB_COMMAND (SmBusAddress)); + + InternalSmBusIoWrite8 (SMBUS_R_HST_D0, (UINT8) BytesCount); + + if (OutBuffer != NULL) { + for (Index = 0; Index < BytesCount; Index++) { + InternalSmBusIoWrite8 (SMBUS_R_HOST_BLOCK_DB, OutBuffer[Index]); + } } + // + // Set Auxiliary Control Regiester. + // + InternalSmBusIoWrite8 (SMBUS_R_AUX_CTL, AuxiliaryControl); + // + // Set SMBus slave address for the device to send/receive from + // + InternalSmBusIoWrite8 (SMBUS_R_XMIT_SLVA, (UINT8) SmBusAddress); + // + // Set Control Register (Initiate Operation, Interrupt disabled) + // + InternalSmBusIoWrite8 (SMBUS_R_HST_CTL, HostControl + SMBUS_B_START); // - // BUGBUG: E32B bit does not exist in ICH3 or earlier + // Wait for the end // - IoOr8 (SmBusBase + R_AUX_CTL, B_AUX_CTL_E32B); - ASSERT (IoRead8 (SmBusBase + R_AUX_CTL) & B_AUX_CTL_E32B); - for (Index = 0; InBuffer != NULL && Index < BytesCount; Index++) { - IoWrite8 (SmBusBase + R_HOST_BLOCK_DB, ((UINT8*)InBuffer)[Index]); + ReturnStatus = InternalSmBusWait (); + if (RETURN_ERROR (ReturnStatus)) { + goto Done; } - SmBusStart (SmBusBase, SmBusProtocol, (UINT8)SmBusAddress); - - if (SmBusWait (SmBusBase) & B_HST_STS_ERR) { - *Status = RETURN_DEVICE_ERROR; - } else { - *Status = RETURN_SUCCESS; - BytesCount = IoRead8 (SmBusBase + R_HST_D0); - for (Index = 0; OutBuffer != NULL && Index < BytesCount; Index++) { - ((UINT8*)OutBuffer)[Index] = IoRead8 (SmBusBase + R_HOST_BLOCK_DB); + BytesCount = InternalSmBusIoRead8 (SMBUS_R_HST_D0); + if (InBuffer != NULL) { + for (Index = 0; Index < BytesCount; Index++) { + InBuffer[Index] = InternalSmBusIoRead8 (SMBUS_R_HOST_BLOCK_DB); } } - SmBusCleanup (SmBusBase); + // + // Clear status register and exit + // + InternalSmBusIoWrite8 (SMBUS_R_HST_STS, SMBUS_B_HSTS_ALL); + +Done: + if (Status != NULL) { + *Status = ReturnStatus; + } + return BytesCount; } +/** + Executes an SMBUS read block command. + + Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Bytes are read from the SMBUS and stored in Buffer. + The number of bytes read is returned, and will never return a value larger than 32-bytes. + If Status is not NULL, then the status of the executed command is returned in Status. + It is the caller¡¯s responsibility to make sure Buffer is large enough for the total number of bytes read. + SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. + If Length in SmBusAddress is not zero, then ASSERT(). + If Buffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The number of bytes read. + +**/ UINTN EFIAPI SmBusReadBlock ( - IN UINTN SmBusAddress, - OUT VOID *Buffer, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT VOID *Buffer, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffffe | MAX_BIT)) == 0); - return SmBusBlock ( - SmBusAddress | B_SMBUS_READ, - B_SMB_CMD_BLOCK, + ASSERT (Buffer != NULL); + ASSERT (SMBUS_LIB_LENGTH (SmBusAddress) == 0); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusBlock ( + SMBUS_V_SMB_CMD_BLOCK, + SmBusAddress | SMBUS_B_READ, NULL, Buffer, Status ); } +/** + Executes an SMBUS write block command. + + Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress. + The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. + Bytes are written to the SMBUS from Buffer. + The number of bytes written is returned, and will never return a value larger than 32-bytes. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is zero or greater than 32, then ASSERT(). + If Buffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The number of bytes written. + +**/ UINTN EFIAPI SmBusWriteBlock ( - IN UINTN SmBusAddress, - OUT VOID *Buffer, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + OUT VOID *Buffer, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffffe | MAX_BIT)) == 0); - return SmBusBlock ( - SmBusAddress | B_SMBUS_WRITE, - B_SMB_CMD_BLOCK, + ASSERT (Buffer != NULL); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusBlock ( + SMBUS_V_SMB_CMD_BLOCK, + SmBusAddress | SMBUS_B_WRITE, Buffer, NULL, Status ); } +/** + Executes an SMBUS block process call command. + + Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress. + The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. + Bytes are written to the SMBUS from OutBuffer. Bytes are then read from the SMBUS into InBuffer. + If Status is not NULL, then the status of the executed command is returned in Status. + It is the caller¡¯s responsibility to make sure InBuffer is large enough for the total number of bytes read. + SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. + If OutBuffer is NULL, then ASSERT(). + If InBuffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param SmBusAddress Address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param OutBuffer Pointer to the buffer of bytes to write to the SMBUS. + @param InBuffer Pointer to the buffer of bytes to read from the SMBUS. + @param Status Return status for the executed command. + This is an optional parameter and may be NULL. + + @return The number of bytes written. + +**/ UINTN EFIAPI SmBusBlockProcessCall ( - IN UINTN SmBusAddress, - IN VOID *OutBuffer, - OUT VOID *InBuffer, - OUT RETURN_STATUS *Status + IN UINTN SmBusAddress, + IN VOID *OutBuffer, + OUT VOID *InBuffer, + OUT RETURN_STATUS *Status OPTIONAL ) { - ASSERT ((SmBusAddress & ~(0xfffffe | MAX_BIT)) == 0); - return SmBusBlock ( - SmBusAddress | B_SMBUS_WRITE, - B_SMB_CMD_BLOCK_PROCESS, + ASSERT (InBuffer != NULL); + ASSERT (OutBuffer != NULL); + ASSERT (SMBUS_LIB_RESEARVED (SmBusAddress) == 0); + + return InternalSmBusBlock ( + SMBUS_V_SMB_CMD_BLOCK_PROCESS, + SmBusAddress | SMBUS_B_WRITE, OutBuffer, InBuffer, Status ); } - -RETURN_STATUS -EFIAPI -SmBusArpAll ( - IN UINTN SmBusAddress - ); - -RETURN_STATUS -EFIAPI -SmBusArpDevice ( - IN UINTN SmBusAddress, - IN CONST GUID *Uuid - ); - -RETURN_STATUS -EFIAPI -SmBusGetUuid ( - IN UINTN SmBusAddress, - OUT GUID *Uuid - ); diff --git a/MdePkg/Library/BaseSmbusLib/SmbusLibRegisters.h b/MdePkg/Library/BaseSmbusLib/SmbusLibRegisters.h new file mode 100644 index 0000000000..6eb14faefb --- /dev/null +++ b/MdePkg/Library/BaseSmbusLib/SmbusLibRegisters.h @@ -0,0 +1,120 @@ +/** @file + Base SMBUS library implementation built upon I/O library. + + 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 + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + Module Name: SmbusLib.h + +**/ + +#ifndef __SMBUS_LIB_REGISTER_H +#define __SMBUS_LIB_REGISTER_H + +#define SMBUS_R_HST_STS 0x00 // Host Status Register +#define SMBUS_B_HOST_BUSY 0x01 // RO +#define SMBUS_B_INTR 0x02 // R/WC +#define SMBUS_B_DEV_ERR 0x04 // R/WC +#define SMBUS_B_BUS_ERR 0x08 // R/WC +#define SMBUS_B_FAILED 0x10 // R/WC +#define SMBUS_B_SMBALERT_STS 0x20 // R/WC +#define SMBUS_B_INUSE_STS 0x40 // R/WC +#define SMBUS_B_BYTE_DONE_STS 0x80 // R/WC +#define SMBUS_B_ERROR (SMBUS_B_DEV_ERR | SMBUS_B_BUS_ERR | SMBUS_B_FAILED) +#define SMBUS_B_HSTS_ALL 0xFF // R/WC + + +#define SMBUS_R_HST_CTL 0x02 // Host Control Register R/W +#define SMBUS_B_INTREN 0x01 // RW +#define SMBUS_B_KILL 0x02 // RW +#define SMBUS_B_CMD (7 << 2) // RW +#define SMBUS_V_SMB_CMD_QUICK (0 << 2) +#define SMBUS_V_SMB_CMD_BYTE (1 << 2) +#define SMBUS_V_SMB_CMD_BYTE_DATA (2 << 2) +#define SMBUS_V_SMB_CMD_WORD_DATA (3 << 2) +#define SMBUS_V_SMB_CMD_PROCESS_CALL (4 << 2) +#define SMBUS_V_SMB_CMD_BLOCK (5 << 2) +#define SMBUS_V_SMB_CMD_IIC_READ (6 << 2) +#define SMBUS_V_SMB_CMD_BLOCK_PROCESS (7 << 2) +#define SMBUS_B_LAST_BYTE 0x20 // WO +#define SMBUS_B_START 0x40 // WO +#define SMBUS_B_PEC_EN 0x80 // RW + + +#define SMBUS_R_HST_CMD 0x03 // Host Command Register R/W + + +#define SMBUS_R_XMIT_SLVA 0x04 // Transmit Slave Address Register R/W +#define SMBUS_B_RW 0x01 // RW +#define SMBUS_B_READ 0x01 // RW +#define SMBUS_B_WRITE 0x00 // RW +#define SMBUS_B_ADDRESS 0xFE // RW + + +#define SMBUS_R_HST_D0 0x05 // Data 0 Register R/W + + +#define SMBUS_R_HST_D1 0x06 // Data 1 Register R/W + + +#define SMBUS_R_HOST_BLOCK_DB 0x07 // Host Block Data Register R/W + + +#define SMBUS_R_PEC 0x08 // Packet Error Check Data Register R/W + + +#define SMBUS_R_RCV_SLVA 0x09 // Receive Slave Address Register R/W +#define SMBUS_B_SLAVE_ADDR 0x7F // RW + + +#define SMBUS_R_SLV_DATA 0x0A // Receive Slave Data Register R/W + + +#define SMBUS_R_AUX_STS 0x0C // Auxiliary Status Register R/WC +#define SMBUS_B_CRCE 0x01 // R/WC + + +#define SMBUS_R_AUX_CTL 0x0D // Auxiliary Control Register R/W +#define SMBUS_B_AAC 0x01 // R/W +#define SMBUS_B_E32B 0x02 // R/W + + +#define SMBUS_R_SMLINK_PIN_CTL 0x0E // SMLINK Pin Control Register R/W +#define SMBUS_B_SMLINK0_CUR_STS 0x01 // RO +#define SMBUS_B_SMLINK1_CUR_STS 0x02 // RO +#define SMBUS_B_SMLINK_CLK_CTL 0x04 // RW + + +#define SMBUS_R_SMBUS_PIN_CTL 0x0F // SMBus Pin Control Register R/W +#define SMBUS_B_SMBCLK_CUR_STS 0x01 // RO +#define SMBUS_B_SMBDATA_CUR_STS 0x02 // RO +#define SMBUS_B_SMBCLK_CTL 0x04 // RW + + +#define SMBUS_R_SLV_STS 0x10 // Slave Status Register R/WC +#define SMBUS_B_HOST_NOTIFY_STS 0x01 // R/WC + + +#define SMBUS_R_SLV_CMD 0x11 // Slave Command Register R/W +#define SMBUS_B_HOST_NOTIFY_INTREN 0x01 // R/W +#define SMBUS_B_HOST_NOTIFY_WKEN 0x02 // R/W +#define SMBUS_B_SMBALERT_DIS 0x04 // R/W + + +#define SMBUS_R_NOTIFY_DADDR 0x14 // Notify Device Address Register RO +#define SMBUS_B_DEVICE_ADDRESS 0xFE // RO + + +#define SMBUS_R_NOTIFY_DLOW 0x16 // Notify Data Low Byte Register RO + + +#define SMBUS_R_NOTIFY_DHIGH 0x17 // Notify Data High Byte Register RO + + +#endif diff --git a/MdePkg/Library/DxeCoreHobLib/HobLib.c b/MdePkg/Library/DxeCoreHobLib/HobLib.c index febd1e45b9..45336c5e54 100644 --- a/MdePkg/Library/DxeCoreHobLib/HobLib.c +++ b/MdePkg/Library/DxeCoreHobLib/HobLib.c @@ -18,9 +18,12 @@ extern VOID *gHobList; + /** Returns the pointer to the HOB list. + This function returns the pointer to first HOB in the list. + @return The pointer to the HOB list. **/ @@ -34,11 +37,17 @@ GetHobList ( } /** + Returns the next instance of a HOB type from the starting HOB. + This function searches the first instance of a HOB type from the starting HOB pointer. - If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). - @param Type The HOB type to return. - @param HobStart The starting HOB pointer to search from. + @param Type The HOB type to return. + @param HobStart The starting HOB pointer to search from. @return The next instance of a HOB type from the starting HOB. @@ -56,7 +65,7 @@ GetNextHob ( Hob.Raw = (UINT8 *) HobStart; // - // Parse the HOB list, stop if end of list or matching type found. + // Parse the HOB list until end of list or matching type is found. // while (!END_OF_HOB_LIST (Hob)) { if (Hob.Header->HobType == Type) { @@ -68,10 +77,12 @@ GetNextHob ( } /** + Returns the first instance of a HOB type among the whole HOB list. + This function searches the first instance of a HOB type among the whole HOB list. If there does not exist such HOB type in the HOB list, it will return NULL. - @param Type The HOB type to return. + @param Type The HOB type to return. @return The next instance of a HOB type from the starting HOB. @@ -93,9 +104,16 @@ GetFirstHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). + If HobStart is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. - @param HobStart A pointer to a Guid. + @param Guid The GUID to match with in the HOB list. + @param HobStart A pointer to a Guid. @return The next instance of the matched GUID HOB from the starting HOB. @@ -124,8 +142,11 @@ GetNextGuidHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + If Guid is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. + @param Guid The GUID to match with in the HOB list. @return The first instance of the matched GUID HOB among the whole HOB list. @@ -143,12 +164,18 @@ GetFirstGuidHob ( } /** + Builds a HOB for a loaded PE32 module. + This function builds a HOB for a loaded PE32 module. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). - @param ModuleName The GUID File Name of the module. - @param MemoryAllocationModule The 64 bit physical address of the module. - @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module’s entry point. + @param ModuleName The GUID File Name of the module. + @param MemoryAllocationModule The 64 bit physical address of the module. + @param ModuleLength The length of the module in bytes. + @param EntryPoint The 64 bit physical address of the module’s entry point. **/ VOID @@ -169,10 +196,15 @@ BuildModuleHob ( /** Builds a HOB that describes a chunk of system memory. - @param ResourceType The type of resource described by this HOB. - @param ResourceAttribute The resource attributes of the memory described by this HOB. - @param PhysicalStart The 64 bit physical address of memory described by this HOB. - @param NumberOfBytes The length of the memory described by this HOB in bytes. + This function builds a HOB that describes a chunk of system memory. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param ResourceType The type of resource described by this HOB. + @param ResourceAttribute The resource attributes of the memory described by this HOB. + @param PhysicalStart The 64 bit physical address of memory described by this HOB. + @param NumberOfBytes The length of the memory described by this HOB in bytes. **/ VOID @@ -191,11 +223,19 @@ BuildResourceDescriptorHob ( } /** + Builds a GUID HOB with a certain data length. + This function builds a customized HOB tagged with a GUID for identification and returns the start address of GUID HOB data so that caller can fill the customized data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @param Guid The GUID to tag the customized HOB. - @param DataLength The size of the data payload for the GUID HOB. + @param Guid The GUID to tag the customized HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -215,12 +255,21 @@ BuildGuidHob ( } /** - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field, and returns the start address of GUID HOB data. - - @param Guid The GUID to tag the customized HOB. - @param Data The data to be copied into the data field of the GUID HOB. - @param DataLength The size of the data payload for the GUID HOB. + Copies a data buffer to a newly-built HOB. + + This function builds a customized HOB tagged with a GUID for identification, + copies the input data to the HOB data field and returns the start address of the GUID HOB data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If Data is NULL and DataLength > 0, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). + + @param Guid The GUID to tag the customized HOB. + @param Data The data to be copied into the data field of the GUID HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -243,8 +292,13 @@ BuildGuidDataHob ( /** Builds a Firmware Volume HOB. - @param BaseAddress The base address of the Firmware Volume. - @param Length The size of the Firmware Volume in bytes. + This function builds a Firmware Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. **/ VOID @@ -263,8 +317,13 @@ BuildFvHob ( /** Builds a Capsule Volume HOB. - @param BaseAddress The base address of the Capsule Volume. - @param Length The size of the Capsule Volume in bytes. + This function builds a Capsule Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Capsule Volume. + @param Length The size of the Capsule Volume in bytes. **/ VOID @@ -283,8 +342,13 @@ BuildCvHob ( /** Builds a HOB for the CPU. - @param SizeOfMemorySpace The maximum physical memory addressability of the processor. - @param SizeOfIoSpace The maximum physical I/O addressability of the processor. + This function builds a HOB for the CPU. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param SizeOfMemorySpace The maximum physical memory addressability of the processor. + @param SizeOfIoSpace The maximum physical I/O addressability of the processor. **/ VOID @@ -303,8 +367,13 @@ BuildCpuHob ( /** Builds a HOB for the Stack. - @param BaseAddress The 64 bit physical address of the Stack. - @param Length The length of the stack in bytes. + This function builds a HOB for the stack. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the Stack. + @param Length The length of the stack in bytes. **/ VOID @@ -323,9 +392,14 @@ BuildStackHob ( /** Builds a HOB for the BSP store. - @param BaseAddress The 64 bit physical address of the BSP. - @param Length The length of the BSP store in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for BSP store. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the BSP. + @param Length The length of the BSP store in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID @@ -345,9 +419,14 @@ BuildBspStoreHob ( /** Builds a HOB for the memory allocation. - @param BaseAddress The 64 bit physical address of the memory. - @param Length The length of the memory allocation in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for the memory allocation. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the memory. + @param Length The length of the memory allocation in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID diff --git a/MdePkg/Library/DxeHobLib/HobLib.c b/MdePkg/Library/DxeHobLib/HobLib.c index a914dd7ba2..41baba2847 100644 --- a/MdePkg/Library/DxeHobLib/HobLib.c +++ b/MdePkg/Library/DxeHobLib/HobLib.c @@ -48,9 +48,9 @@ HobLibConstructor ( /** Returns the pointer to the HOB list. - None. + This function returns the pointer to first HOB in the list. - The pointer to the HOB list. + @return The pointer to the HOB list. **/ VOID * @@ -63,11 +63,17 @@ GetHobList ( } /** + Returns the next instance of a HOB type from the starting HOB. + This function searches the first instance of a HOB type from the starting HOB pointer. - If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). - @param Type The HOB type to return. - @param HobStart The starting HOB pointer to search from. + @param Type The HOB type to return. + @param HobStart The starting HOB pointer to search from. @return The next instance of a HOB type from the starting HOB. @@ -85,7 +91,7 @@ GetNextHob ( Hob.Raw = (UINT8 *) HobStart; // - // Parse the HOB list, stop if end of list or matching type found. + // Parse the HOB list until end of list or matching type is found. // while (!END_OF_HOB_LIST (Hob)) { if (Hob.Header->HobType == Type) { @@ -97,10 +103,12 @@ GetNextHob ( } /** + Returns the first instance of a HOB type among the whole HOB list. + This function searches the first instance of a HOB type among the whole HOB list. If there does not exist such HOB type in the HOB list, it will return NULL. - @param Type The HOB type to return. + @param Type The HOB type to return. @return The next instance of a HOB type from the starting HOB. @@ -122,9 +130,16 @@ GetFirstHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). + If HobStart is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. - @param HobStart A pointer to a Guid. + @param Guid The GUID to match with in the HOB list. + @param HobStart A pointer to a Guid. @return The next instance of the matched GUID HOB from the starting HOB. @@ -153,8 +168,11 @@ GetNextGuidHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + If Guid is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. + @param Guid The GUID to match with in the HOB list. @return The first instance of the matched GUID HOB among the whole HOB list. @@ -172,12 +190,18 @@ GetFirstGuidHob ( } /** + Builds a HOB for a loaded PE32 module. + This function builds a HOB for a loaded PE32 module. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). - @param ModuleName The GUID File Name of the module. - @param MemoryAllocationModule The 64 bit physical address of the module. - @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module’s entry point. + @param ModuleName The GUID File Name of the module. + @param MemoryAllocationModule The 64 bit physical address of the module. + @param ModuleLength The length of the module in bytes. + @param EntryPoint The 64 bit physical address of the module’s entry point. **/ VOID @@ -198,10 +222,15 @@ BuildModuleHob ( /** Builds a HOB that describes a chunk of system memory. - @param ResourceType The type of resource described by this HOB. - @param ResourceAttribute The resource attributes of the memory described by this HOB. - @param PhysicalStart The 64 bit physical address of memory described by this HOB. - @param NumberOfBytes The length of the memory described by this HOB in bytes. + This function builds a HOB that describes a chunk of system memory. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param ResourceType The type of resource described by this HOB. + @param ResourceAttribute The resource attributes of the memory described by this HOB. + @param PhysicalStart The 64 bit physical address of memory described by this HOB. + @param NumberOfBytes The length of the memory described by this HOB in bytes. **/ VOID @@ -220,11 +249,19 @@ BuildResourceDescriptorHob ( } /** + Builds a GUID HOB with a certain data length. + This function builds a customized HOB tagged with a GUID for identification and returns the start address of GUID HOB data so that caller can fill the customized data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @param Guid The GUID to tag the customized HOB. - @param DataLength The size of the data payload for the GUID HOB. + @param Guid The GUID to tag the customized HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -244,12 +281,21 @@ BuildGuidHob ( } /** - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field, and returns the start address of GUID HOB data. - - @param Guid The GUID to tag the customized HOB. - @param Data The data to be copied into the data field of the GUID HOB. - @param DataLength The size of the data payload for the GUID HOB. + Copies a data buffer to a newly-built HOB. + + This function builds a customized HOB tagged with a GUID for identification, + copies the input data to the HOB data field and returns the start address of the GUID HOB data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If Data is NULL and DataLength > 0, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). + + @param Guid The GUID to tag the customized HOB. + @param Data The data to be copied into the data field of the GUID HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -272,8 +318,13 @@ BuildGuidDataHob ( /** Builds a Firmware Volume HOB. - @param BaseAddress The base address of the Firmware Volume. - @param Length The size of the Firmware Volume in bytes. + This function builds a Firmware Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. **/ VOID @@ -292,8 +343,13 @@ BuildFvHob ( /** Builds a Capsule Volume HOB. - @param BaseAddress The base address of the Capsule Volume. - @param Length The size of the Capsule Volume in bytes. + This function builds a Capsule Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Capsule Volume. + @param Length The size of the Capsule Volume in bytes. **/ VOID @@ -312,8 +368,13 @@ BuildCvHob ( /** Builds a HOB for the CPU. - @param SizeOfMemorySpace The maximum physical memory addressability of the processor. - @param SizeOfIoSpace The maximum physical I/O addressability of the processor. + This function builds a HOB for the CPU. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param SizeOfMemorySpace The maximum physical memory addressability of the processor. + @param SizeOfIoSpace The maximum physical I/O addressability of the processor. **/ VOID @@ -332,8 +393,13 @@ BuildCpuHob ( /** Builds a HOB for the Stack. - @param BaseAddress The 64 bit physical address of the Stack. - @param Length The length of the stack in bytes. + This function builds a HOB for the stack. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the Stack. + @param Length The length of the stack in bytes. **/ VOID @@ -352,9 +418,14 @@ BuildStackHob ( /** Builds a HOB for the BSP store. - @param BaseAddress The 64 bit physical address of the BSP. - @param Length The length of the BSP store in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for BSP store. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the BSP. + @param Length The length of the BSP store in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID @@ -374,9 +445,14 @@ BuildBspStoreHob ( /** Builds a HOB for the memory allocation. - @param BaseAddress The 64 bit physical address of the memory. - @param Length The length of the memory allocation in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for the memory allocation. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the memory. + @param Length The length of the memory allocation in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID diff --git a/MdePkg/Library/PeiHobLib/HobLib.c b/MdePkg/Library/PeiHobLib/HobLib.c index a06f1690bf..380a735b99 100644 --- a/MdePkg/Library/PeiHobLib/HobLib.c +++ b/MdePkg/Library/PeiHobLib/HobLib.c @@ -19,9 +19,9 @@ /** Returns the pointer to the HOB list. - None. + This function returns the pointer to first HOB in the list. - The pointer to the HOB list. + @return The pointer to the HOB list. **/ VOID * @@ -41,11 +41,17 @@ GetHobList ( } /** + Returns the next instance of a HOB type from the starting HOB. + This function searches the first instance of a HOB type from the starting HOB pointer. - If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + If there does not exist such HOB type from the starting HOB pointer, it will return NULL. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If HobStart is NULL, then ASSERT(). - @param Type The HOB type to return. - @param HobStart The starting HOB pointer to search from. + @param Type The HOB type to return. + @param HobStart The starting HOB pointer to search from. @return The next instance of a HOB type from the starting HOB. @@ -63,7 +69,7 @@ GetNextHob ( Hob.Raw = (UINT8 *) HobStart; // - // Parse the HOB list, stop if end of list or matching type found. + // Parse the HOB list until end of list or matching type is found. // while (!END_OF_HOB_LIST (Hob)) { if (Hob.Header->HobType == Type) { @@ -75,10 +81,12 @@ GetNextHob ( } /** + Returns the first instance of a HOB type among the whole HOB list. + This function searches the first instance of a HOB type among the whole HOB list. If there does not exist such HOB type in the HOB list, it will return NULL. - @param Type The HOB type to return. + @param Type The HOB type to return. @return The next instance of a HOB type from the starting HOB. @@ -100,9 +108,16 @@ GetFirstHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer + unconditionally: it returns HobStart back if HobStart itself meets the requirement; + caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart. + If Guid is NULL, then ASSERT(). + If HobStart is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. - @param HobStart A pointer to a Guid. + @param Guid The GUID to match with in the HOB list. + @param HobStart A pointer to a Guid. @return The next instance of the matched GUID HOB from the starting HOB. @@ -131,8 +146,11 @@ GetNextGuidHob ( Such HOB should satisfy two conditions: its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid. If there does not exist such HOB from the starting HOB pointer, it will return NULL. + Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () + to extract the data section and its size info respectively. + If Guid is NULL, then ASSERT(). - @param Guid The GUID to match with in the HOB list. + @param Guid The GUID to match with in the HOB list. @return The first instance of the matched GUID HOB among the whole HOB list. @@ -150,10 +168,12 @@ GetFirstGuidHob ( } /** - Add a new HOB to the HOB List. + Adds a new HOB to the HOB List. - @param Type Type of the new HOB. - @param Length Length of the new HOB to allocate. + This internal function enables PEIMs to create various types of HOBs. + + @param Type Type of the new HOB. + @param Length Length of the new HOB to allocate. @return The address of new HOB. @@ -176,12 +196,18 @@ InternalPeiCreateHob ( } /** + Builds a HOB for a loaded PE32 module. + This function builds a HOB for a loaded PE32 module. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If ModuleName is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). - @param ModuleName The GUID File Name of the module. - @param MemoryAllocationModule The 64 bit physical address of the module. - @param ModuleLength The length of the module in bytes. - @param EntryPoint The 64 bit physical address of the module’s entry point. + @param ModuleName The GUID File Name of the module. + @param MemoryAllocationModule The 64 bit physical address of the module. + @param ModuleLength The length of the module in bytes. + @param EntryPoint The 64 bit physical address of the module’s entry point. **/ VOID @@ -209,10 +235,15 @@ BuildModuleHob ( /** Builds a HOB that describes a chunk of system memory. - @param ResourceType The type of resource described by this HOB. - @param ResourceAttribute The resource attributes of the memory described by this HOB. - @param PhysicalStart The 64 bit physical address of memory described by this HOB. - @param NumberOfBytes The length of the memory described by this HOB in bytes. + This function builds a HOB that describes a chunk of system memory. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param ResourceType The type of resource described by this HOB. + @param ResourceAttribute The resource attributes of the memory described by this HOB. + @param PhysicalStart The 64 bit physical address of memory described by this HOB. + @param NumberOfBytes The length of the memory described by this HOB in bytes. **/ VOID @@ -235,11 +266,19 @@ BuildResourceDescriptorHob ( } /** - This function builds a customized HOB tagged with a GUID for identification - and returns the start address of GUID HOB data so that caller can fill the customized data. + Builds a GUID HOB with a certain data length. + + This function builds a customized HOB tagged with a GUID for identification + and returns the start address of GUID HOB data so that caller can fill the customized data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). - @param Guid The GUID to tag the customized HOB. - @param DataLength The size of the data payload for the GUID HOB. + @param Guid The GUID to tag the customized HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -264,12 +303,21 @@ BuildGuidHob ( } /** - This function builds a customized HOB tagged with a GUID for identification, - copies the input data to the HOB data field, and returns the start address of GUID HOB data. + Copies a data buffer to a newly-built HOB. - @param Guid The GUID to tag the customized HOB. - @param Data The data to be copied into the data field of the GUID HOB. - @param DataLength The size of the data payload for the GUID HOB. + This function builds a customized HOB tagged with a GUID for identification, + copies the input data to the HOB data field and returns the start address of the GUID HOB data. + The HOB Header and Name field is already stripped. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If Guid is NULL, then ASSERT(). + If Data is NULL and DataLength > 0, then ASSERT(). + If there is no additional space for HOB creation, then ASSERT(). + If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT(). + + @param Guid The GUID to tag the customized HOB. + @param Data The data to be copied into the data field of the GUID HOB. + @param DataLength The size of the data payload for the GUID HOB. @return The start address of GUID HOB data. @@ -292,8 +340,13 @@ BuildGuidDataHob ( /** Builds a Firmware Volume HOB. - @param BaseAddress The base address of the Firmware Volume. - @param Length The size of the Firmware Volume in bytes. + This function builds a Firmware Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. **/ VOID @@ -314,8 +367,13 @@ BuildFvHob ( /** Builds a Capsule Volume HOB. - @param BaseAddress The base address of the Capsule Volume. - @param Length The size of the Capsule Volume in bytes. + This function builds a Capsule Volume HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The base address of the Capsule Volume. + @param Length The size of the Capsule Volume in bytes. **/ VOID @@ -336,8 +394,13 @@ BuildCvHob ( /** Builds a HOB for the CPU. - @param SizeOfMemorySpace The maximum physical memory addressability of the processor. - @param SizeOfIoSpace The maximum physical I/O addressability of the processor. + This function builds a HOB for the CPU. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param SizeOfMemorySpace The maximum physical memory addressability of the processor. + @param SizeOfIoSpace The maximum physical I/O addressability of the processor. **/ VOID @@ -358,8 +421,13 @@ BuildCpuHob ( /** Builds a HOB for the Stack. - @param BaseAddress The 64 bit physical address of the Stack. - @param Length The length of the stack in bytes. + This function builds a HOB for the stack. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the Stack. + @param Length The length of the stack in bytes. **/ VOID @@ -382,9 +450,14 @@ BuildStackHob ( /** Builds a HOB for the BSP store. - @param BaseAddress The 64 bit physical address of the BSP. - @param Length The length of the BSP store in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for BSP store. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the BSP. + @param Length The length of the BSP store in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID @@ -408,9 +481,14 @@ BuildBspStoreHob ( /** Builds a HOB for the memory allocation. - @param BaseAddress The 64 bit physical address of the memory. - @param Length The length of the memory allocation in bytes. - @param MemoryType Type of memory allocated by this HOB. + This function builds a HOB for the memory allocation. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + If there is no additional space for HOB creation, then ASSERT(). + + @param BaseAddress The 64 bit physical address of the memory. + @param Length The length of the memory allocation in bytes. + @param MemoryType Type of memory allocated by this HOB. **/ VOID diff --git a/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c b/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c index 8dc84f48b7..1b1376e2cf 100644 --- a/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c +++ b/MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.c @@ -155,9 +155,9 @@ AppendDevicePath ( This function appends the device path node SecondDevicePath to every device path instance in FirstDevicePath. - @param FirstDevicePath A pointer to a device path data structure. + @param DevicePath A pointer to a device path data structure. - @param SecondDevicePath A pointer to a single device path node. + @param DevicePathNode A pointer to a single device path node. @return A pointer to the new device path. If there is not enough temporary pool memory available to complete this function, @@ -167,40 +167,37 @@ AppendDevicePath ( EFI_DEVICE_PATH_PROTOCOL * EFIAPI AppendDevicePathNode ( - IN CONST EFI_DEVICE_PATH_PROTOCOL *FirstDevicePath, - IN CONST EFI_DEVICE_PATH_PROTOCOL *SecondDevicePath + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePathNode ) { + EFI_DEVICE_PATH_PROTOCOL *TempDevicePath; EFI_DEVICE_PATH_PROTOCOL *NextNode; EFI_DEVICE_PATH_PROTOCOL *NewDevicePath; UINTN NodeLength; - UINTN Size1; // // Build a Node that has a terminator on it // - NodeLength = DevicePathNodeLength (SecondDevicePath); - Size1 = GetDevicePathSize (FirstDevicePath); - - NewDevicePath = AllocatePool (NodeLength + Size1); - if (NewDevicePath != NULL) { - // - // Copy the first device path to the new device path - // - NewDevicePath = CopyMem (NewDevicePath, FirstDevicePath, Size1); - - // - // Copy the device path node to the new device path - // - NextNode = (EFI_DEVICE_PATH_PROTOCOL *) ((CHAR8 *) NewDevicePath + (Size1 - sizeof (EFI_DEVICE_PATH_PROTOCOL))); - NextNode = CopyMem (NextNode, SecondDevicePath, NodeLength); + NodeLength = DevicePathNodeLength (DevicePathNode); - // - // Terminate the whole device path - // - NextNode = NextDevicePathNode (NextNode); - SetDevicePathEndNode (NextNode); + TempDevicePath = AllocatePool (NodeLength + sizeof (EFI_DEVICE_PATH_PROTOCOL)); + if (TempDevicePath == NULL) { + return NULL; } + TempDevicePath = CopyMem (TempDevicePath, DevicePathNode, NodeLength); + // + // Add and end device path node to convert Node to device path + // + NextNode = NextDevicePathNode (TempDevicePath); + SetDevicePathEndNode (NextNode); + // + // Append device paths + // + NewDevicePath = AppendDevicePath (DevicePath, TempDevicePath); + + FreePool (TempDevicePath); + return NewDevicePath; }