Initial import.

[mirror_edk2.git] / Tools / Source / TianoTools / Common / PeiLib / PeiLib.h

/*++\r
\r
Copyright (c) 2004, Intel Corporation                                                         \r
All rights reserved. This program and the accompanying materials                          \r
are licensed and made available under the terms and conditions of the BSD License         \r
which accompanies this distribution.  The full text of the license may be found at        \r
http://opensource.org/licenses/bsd-license.php                                            \r
                                                                                          \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
Module Name:\r
\r
  PeiLib.h\r
\r
Abstract:\r
\r
  PEI Library Functions\r
 \r
--*/\r
\r
#ifndef _PEI_LIB_H_\r
#define _PEI_LIB_H_\r
\r
#include "Tiano.h"\r
#include "Pei.h"\r
#include "peiHobLib.h"\r
#include EFI_PROTOCOL_DEFINITION (Decompress)\r
#include EFI_PROTOCOL_DEFINITION (TianoDecompress)\r
#include EFI_GUID_DEFINITION (PeiPeCoffLoader)\r
\r
VOID\r
PeiCopyMem (\r
  IN VOID   *Destination,\r
  IN VOID   *Source,\r
  IN UINTN  Length\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Copy Length bytes from Source to Destination.\r
\r
Arguments:\r
\r
  Destination - Target of copy\r
\r
  Source      - Place to copy from\r
\r
  Length      - Number of bytes to copy\r
\r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
VOID\r
ZeroMem (\r
  IN VOID   *Buffer,\r
  IN UINTN  Size\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Set Buffer to zero for Size bytes.\r
\r
Arguments:\r
\r
  Buffer  - Memory to set.\r
\r
  Size    - Number of bytes to set\r
\r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
VOID\r
CopyMem (\r
  IN VOID   *Destination,\r
  IN VOID   *Source,\r
  IN UINTN  Length\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Copy Length bytes from Source to Destination.\r
\r
Arguments:\r
\r
  Destination - Target of copy\r
\r
  Source      - Place to copy from\r
\r
  Length      - Number of bytes to copy\r
\r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
BOOLEAN\r
CompareGuid (\r
  IN EFI_GUID     *Guid1,\r
  IN EFI_GUID     *Guid2\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Compares two GUIDs\r
\r
Arguments:\r
\r
  Guid1 - guid to compare\r
  Guid2 - guid to compare\r
\r
Returns:\r
  = TRUE  if Guid1 == Guid2\r
  = FALSE if Guid1 != Guid2 \r
\r
--*/\r
;\r
\r
EFI_STATUS\r
InstallEfiPeiPeCoffLoader (\r
  IN EFI_PEI_SERVICES                     **PeiServices,\r
  IN EFI_PEI_PE_COFF_LOADER_PROTOCOL      **This,\r
  IN EFI_PEI_PPI_DESCRIPTOR               *ThisPpi\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Install EFI Pei PE coff loader protocol.\r
  \r
Arguments:\r
\r
  PeiServices - The PEI core services table.\r
  \r
  This        - Pointer to get Pei PE coff loader protocol as output\r
  \r
  ThisPpi     - Passed in as EFI_NT_LOAD_AS_DLL_PPI on NT_EMULATOR platform\r
\r
Returns:\r
\r
  EFI_SUCCESS\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
InstallEfiDecompress (\r
  EFI_DECOMPRESS_PROTOCOL  **This\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Install EFI decompress protocol.\r
\r
Arguments:\r
\r
  This  - Pointer to get decompress protocol as output\r
\r
Returns:\r
\r
  EFI_SUCCESS - EFI decompress protocol successfully installed.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
InstallTianoDecompress (\r
  EFI_TIANO_DECOMPRESS_PROTOCOL  **This\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Install Tiano decompress protocol.\r
\r
Arguments:\r
\r
  This  - Pointer to get decompress protocol as output\r
\r
Returns:\r
\r
  EFI_SUCCESS - Tiano decompress protocol successfully installed.\r
\r
--*/\r
;\r
\r
VOID\r
PeiPerfMeasure (\r
  EFI_PEI_SERVICES              **PeiServices,\r
  IN UINT16                     *Token,\r
  IN EFI_FFS_FILE_HEADER        *FileHeader,\r
  IN BOOLEAN                    EntryExit,\r
  IN UINT64                     Value\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Log a timestamp count.\r
\r
Arguments:\r
\r
  PeiServices - Pointer to the PEI Core Services table\r
  \r
  Token       - Pointer to Token Name\r
  \r
  FileHeader  - Pointer to the file header\r
\r
  EntryExit   - Indicates start or stop measurement\r
\r
  Value       - The start time or the stop time\r
\r
Returns:\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
GetTimerValue (\r
  OUT UINT64    *TimerValue\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Get timer value.\r
\r
Arguments:\r
\r
  TimerValue  - Pointer to the returned timer value\r
\r
Returns:\r
\r
  EFI_SUCCESS - Successfully got timer value\r
\r
--*/\r
;\r
\r
#ifdef EFI_PEI_PERFORMANCE\r
#define PEI_PERF_START(Ps, Token, FileHeader, Value)  PeiPerfMeasure (Ps, Token, FileHeader, FALSE, Value)\r
#define PEI_PERF_END(Ps, Token, FileHeader, Value)    PeiPerfMeasure (Ps, Token, FileHeader, TRUE, Value)\r
#else\r
#define PEI_PERF_START(Ps, Token, FileHeader, Value)\r
#define PEI_PERF_END(Ps, Token, FileHeader, Value)\r
#endif\r
\r
#ifdef EFI_NT_EMULATOR\r
EFI_STATUS\r
PeCoffLoaderWinNtLoadAsDll (\r
  IN  CHAR8  *PdbFileName,\r
  IN  VOID   **ImageEntryPoint,\r
  OUT VOID   **ModHandle\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Loads the .DLL file is present when a PE/COFF file is loaded.  This provides source level\r
  debugging for drivers that have cooresponding .DLL files on the local system.\r
\r
Arguments:\r
\r
  PdbFileName     - The name of the .PDB file.  This was found from the PE/COFF\r
                    file's debug directory entry.\r
\r
  ImageEntryPoint - A pointer to the DLL entry point of the .DLL file was loaded.\r
\r
  ModHandle       - Pointer to loaded library.\r
\r
Returns:\r
\r
  EFI_SUCCESS     - The .DLL file was loaded, and the DLL entry point is returned in ImageEntryPoint\r
\r
  EFI_NOT_FOUND   - The .DLL file could not be found\r
\r
  EFI_UNSUPPORTED - The .DLL file was loaded, but the entry point to the .DLL file could not\r
                    determined.\r
\r
--*/\r
;\r
\r
#endif\r
//\r
// hob.c\r
//\r
EFI_STATUS\r
PeiBuildHobModule (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_GUID                    *ModuleName,\r
  IN EFI_PHYSICAL_ADDRESS        Module,\r
  IN UINT64                      ModuleLength,\r
  IN EFI_PHYSICAL_ADDRESS        EntryPoint\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB for a loaded PE32 module\r
\r
Arguments:\r
\r
  PeiServices               - The PEI core services table.\r
  ModuleName                - The GUID File Name of the module\r
  Memory                    - The 64 bit physical address of the module\r
  ModuleLength              - The length of the module in bytes\r
  EntryPoint                - The 64 bit physical address of the entry point\r
                              to the module\r
\r
Returns:\r
\r
  EFI_SUCCESS               - Hob is successfully built.\r
  Others                    - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobResourceDescriptor (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_RESOURCE_TYPE           ResourceType,\r
  IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute,\r
  IN EFI_PHYSICAL_ADDRESS        PhysicalStart,\r
  IN UINT64                      NumberOfBytes\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB that describes a chunck of system memory\r
\r
Arguments:\r
\r
  PeiServices        - The PEI core services table.\r
 \r
  ResourceType       - The type of resource described by this HOB\r
\r
  ResourceAttribute  - The resource attributes of the memory described by this HOB\r
\r
  PhysicalStart      - The 64 bit physical address of memory described by this HOB\r
\r
  NumberOfBytes      - The length of the memoty described by this HOB in bytes\r
\r
Returns:\r
\r
  EFI_SUCCESS     - Hob is successfully built.\r
  Others          - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobGuid (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_GUID                    *Guid,\r
  IN UINTN                       DataLength,\r
  IN OUT VOID                    **Hob\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a custom HOB that is tagged with a GUID for identification\r
\r
Arguments:\r
\r
  PeiServices - The PEI core services table.\r
\r
  Guid        - The GUID of the custome HOB type\r
\r
  DataLength  - The size of the data payload for the GUIDed HOB\r
\r
  Hob         - Pointer to the Hob\r
\r
Returns:\r
\r
  EFI_SUCCESS   - Hob is successfully built.\r
  Others        - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobGuidData (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_GUID                    *Guid,\r
  IN VOID                        *Data,\r
  IN UINTN                       DataLength\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a custom HOB that is tagged with a GUID for identification\r
\r
Arguments:\r
\r
  PeiServices - The PEI core services table.\r
\r
  Guid        - The GUID of the custome HOB type\r
\r
  Data        - The data to be copied into the GUIDed HOB data field.\r
\r
  DataLength  - The data field length.\r
\r
Returns:\r
\r
  EFI_SUCCESS   - Hob is successfully built.\r
  Others        - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobFv (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_PHYSICAL_ADDRESS        BaseAddress,\r
  IN UINT64                      Length\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a Firmware Volume HOB\r
\r
Arguments:\r
\r
  PeiServices - The PEI core services table.\r
\r
  BaseAddress - The base address of the Firmware Volume\r
\r
  Length      - The size of the Firmware Volume in bytes\r
\r
Returns:\r
\r
  EFI_SUCCESS   - Hob is successfully built.\r
  Others        - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobCpu (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN UINT8                       SizeOfMemorySpace,\r
  IN UINT8                       SizeOfIoSpace\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB for the CPU\r
\r
Arguments:\r
\r
  PeiServices               - The PEI core services table.\r
\r
  SizeOfMemorySpace         - Identifies the maximum \r
                              physical memory addressibility of the processor.\r
\r
  SizeOfIoSpace             - Identifies the maximum physical I/O addressibility \r
                              of the processor.\r
\r
Returns:\r
\r
  EFI_SUCCESS               - Hob is successfully built.\r
  Others                    - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobStack (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_PHYSICAL_ADDRESS        BaseAddress,\r
  IN UINT64                      Length\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB for the Stack\r
\r
Arguments:\r
\r
  PeiServices               - The PEI core services table.\r
\r
  BaseAddress               - The 64 bit physical address of the Stack\r
\r
  Length                    - The length of the stack in bytes\r
\r
Returns:\r
\r
  EFI_SUCCESS               - Hob is successfully built.\r
  Others                    - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobBspStore (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_PHYSICAL_ADDRESS        BaseAddress,\r
  IN UINT64                      Length,\r
  IN EFI_MEMORY_TYPE             MemoryType\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB for the bsp store\r
\r
Arguments:\r
\r
  PeiServices               - The PEI core services table.\r
\r
  BaseAddress               - The 64 bit physical address of the bsp store\r
\r
  Length                    - The length of the bsp store in bytes\r
\r
  MemoryType                - Memory type\r
\r
Returns:\r
\r
  EFI_SUCCESS               - Hob is successfully built.\r
  Others                    - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
PeiBuildHobMemoryAllocation (\r
  IN EFI_PEI_SERVICES            **PeiServices,\r
  IN EFI_PHYSICAL_ADDRESS        BaseAddress,\r
  IN UINT64                      Length,\r
  IN EFI_GUID                    *Name,\r
  IN EFI_MEMORY_TYPE             MemoryType\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Builds a HOB for the memory allocation\r
\r
Arguments:\r
\r
  PeiServices               - The PEI core services table.\r
\r
  BaseAddress               - The 64 bit physical address of the memory\r
\r
  Length                    - The length of the memory allocation in bytes\r
\r
  Name                      - Name for Hob\r
\r
  MemoryType                - Memory type\r
\r
Returns:\r
\r
  EFI_SUCCESS               - Hob is successfully built.\r
  Others                    - Errors occur while creating new Hob\r
\r
--*/\r
;\r
\r
//\r
// print.c\r
//\r
UINTN\r
AvSPrint (\r
  OUT CHAR8       *StartOfBuffer,\r
  IN  UINTN       StrSize,\r
  IN  CONST CHAR8 *Format,\r
  IN  VA_LIST     Marker\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  AvSPrint function to process format and place the results in Buffer. Since a \r
  VA_LIST is used this rountine allows the nesting of Vararg routines. Thus \r
  this is the main print working routine\r
\r
Arguments:\r
\r
  StartOfBuffer - Ascii buffer to print the results of the parsing of Format into.\r
\r
  StrSize       - Maximum number of characters to put into buffer. Zero means \r
                  no limit.\r
\r
  FormatString  - Ascii format string see file header for more details.\r
\r
  Marker        - Vararg list consumed by processing Format.\r
\r
Returns: \r
\r
  Number of characters printed.\r
\r
--*/\r
;\r
\r
UINTN\r
ASPrint (\r
  OUT CHAR8       *Buffer,\r
  IN UINTN        BufferSize,\r
  IN CONST CHAR8  *Format,\r
  ...\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  ASPrint function to process format and place the results in Buffer.\r
\r
Arguments:\r
\r
  Buffer     - Ascii buffer to print the results of the parsing of Format into.\r
\r
  BufferSize - Maximum number of characters to put into buffer. Zero means no \r
               limit.\r
\r
  Format - Ascii format string see file header for more details.\r
\r
  ...    - Vararg list consumed by processing Format.\r
\r
Returns: \r
\r
  Number of characters printed.\r
\r
--*/\r
;\r
\r
//\r
// math.c\r
//\r
UINT64\r
MultU64x32 (\r
  IN  UINT64  Multiplicand,\r
  IN  UINTN   Multiplier\r
  )\r
/*++  \r
  \r
Routine Description:\r
\r
  This routine allows a 64 bit value to be multiplied with a 32 bit \r
  value returns 64bit result.\r
  No checking if the result is greater than 64bits\r
\r
Arguments:\r
\r
  Multiplicand  - multiplicand\r
  Multiplier    - multiplier\r
\r
Returns:\r
\r
  Multiplicand * Multiplier\r
  \r
--*/\r
;\r
\r
UINT64\r
DivU64x32 (\r
  IN  UINT64  Dividend,\r
  IN  UINTN   Divisor,\r
  OUT UINTN   *Remainder OPTIONAL\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  This routine allows a 64 bit value to be divided with a 32 bit value returns \r
  64bit result and the Remainder.\r
  N.B. only works for 31bit divisors!!\r
\r
Arguments:\r
\r
  Dividend  - dividend\r
  Divisor   - divisor\r
  Remainder - buffer for remainder\r
 \r
Returns:\r
\r
  Dividend  / Divisor\r
  Remainder = Dividend mod Divisor\r
\r
--*/\r
;\r
\r
UINT64\r
RShiftU64 (\r
  IN  UINT64  Operand,\r
  IN  UINTN   Count\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  This routine allows a 64 bit value to be right shifted by 32 bits and returns the \r
  shifted value.\r
  Count is valid up 63. (Only Bits 0-5 is valid for Count)\r
\r
Arguments:\r
\r
  Operand - Value to be shifted\r
  Count   - Number of times to shift right.\r
 \r
Returns:\r
\r
  Value shifted right identified by the Count.\r
\r
--*/\r
;\r
\r
UINT64\r
LShiftU64 (\r
  IN  UINT64  Operand,\r
  IN  UINTN   Count\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  This routine allows a 64 bit value to be left shifted by 32 bits and \r
  returns the shifted value.\r
  Count is valid up 63. (Only Bits 0-5 is valid for Count)\r
\r
Arguments:\r
\r
  Operand - Value to be shifted\r
  Count   - Number of times to shift left.\r
\r
Returns:\r
\r
  Value shifted left identified by the Count.\r
\r
--*/\r
;\r
\r
VOID\r
RegisterNativeCpuIo (\r
  IN EFI_PEI_SERVICES         **PeiServices,\r
  IN VOID                     *CpuIo\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Register a native Cpu IO\r
\r
Arguments:\r
\r
  PeiServices - Calling context\r
  CpuIo       - CpuIo instance to register\r
\r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
VOID\r
GetNativeCpuIo (\r
  IN EFI_PEI_SERVICES         **PeiServices,\r
  OUT VOID                    **CpuIo\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Get registered Cpu IO.\r
\r
Arguments:\r
\r
  PeiServices - Calling context\r
  CpuIo       - CpuIo instance registered before\r
\r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
#endif\r