EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGlueHobLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2006, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12
  13 Module Name:
  14
  15   EdkIIGlueHobLib.h
  16
  17 Abstract:
  18
  19   Public header file for Hob Lib
  20
  21 --*/
  22
  23 #ifndef __EDKII_GLUE_HOB_LIB_H__
  24 #define __EDKII_GLUE_HOB_LIB_H__
  25
  26
  27 #define GetFirstGuidHob(_GUID)                                                                                                                                                          GlueGetFirstGuidHob(_GUID)
  28 #define GetNextGuidHob(_GUID, _HobStart)                                                                                                        GlueGetNextGuidHob(_GUID, _HobStart)
  29 #define BuildModuleHob(_MODULENAME, _MEMORYALLOCATIONMODULE, _MODULELENGTH, _ENTRYPOINT)                GlueBuildModuleHob(_MODULENAME, _MEMORYALLOCATIONMODULE, _MODULELENGTH, _ENTRYPOINT)
  30 #define BuildMemoryAllocationHob(_BASEADDRESS, _LENGTH, _MEMORYTYPE)    GlueBuildMemoryAllocationHob(_BASEADDRESS, _LENGTH, _MEMORYTYPE)
  31
  32
  33 /**
  34   Returns the pointer to the HOB list.
  35
  36   This function returns the pointer to first HOB in the list.
  37
  38   @return The pointer to the HOB list.
  39
  40 **/
  41 VOID *
  42 EFIAPI
  43 GetHobList (
  44   VOID
  45   )
  46 ;
  47
  48 /**
  49   Returns the next instance of a HOB type from the starting HOB.
  50
  51   This function searches the first instance of a HOB type from the starting HOB pointer.
  52   If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  53   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  54   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  55   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  56   If HobStart is NULL, then ASSERT().
  57
  58   @param  Type          The HOB type to return.
  59   @param  HobStart      The starting HOB pointer to search from.
  60
  61   @return The next instance of a HOB type from the starting HOB.
  62
  63 **/
  64 VOID *
  65 EFIAPI
  66 GetNextHob (
  67   IN UINT16                 Type,
  68   IN CONST VOID             *HobStart
  69   )
  70 ;
  71
  72 /**
  73   Returns the first instance of a HOB type among the whole HOB list.
  74
  75   This function searches the first instance of a HOB type among the whole HOB list.
  76   If there does not exist such HOB type in the HOB list, it will return NULL.
  77
  78   @param  Type          The HOB type to return.
  79
  80   @return The next instance of a HOB type from the starting HOB.
  81
  82 **/
  83 VOID *
  84 EFIAPI
  85 GetFirstHob (
  86   IN UINT16                 Type
  87   )
  88 ;
  89
  90 /**
  91   This function searches the first instance of a HOB from the starting HOB pointer.
  92   Such HOB should satisfy two conditions:
  93   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
  94   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
  95   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
  96   to extract the data section and its size info respectively.
  97   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  98   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  99   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
 100   If Guid is NULL, then ASSERT().
 101   If HobStart is NULL, then ASSERT().
 102
 103   @param  Guid          The GUID to match with in the HOB list.
 104   @param  HobStart      A pointer to a Guid.
 105
 106   @return The next instance of the matched GUID HOB from the starting HOB.
 107
 108 **/
 109 VOID *
 110 EFIAPI
 111 GlueGetNextGuidHob (
 112   IN CONST EFI_GUID         *Guid,
 113   IN CONST VOID             *HobStart
 114   )
 115 ;
 116
 117 /**
 118   This function searches the first instance of a HOB among the whole HOB list.
 119   Such HOB should satisfy two conditions:
 120   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 121   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 122   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 123   to extract the data section and its size info respectively.
 124   If Guid is NULL, then ASSERT().
 125
 126   @param  Guid          The GUID to match with in the HOB list.
 127
 128   @return The first instance of the matched GUID HOB among the whole HOB list.
 129
 130 **/
 131 VOID *
 132 EFIAPI
 133 GlueGetFirstGuidHob (
 134   IN CONST EFI_GUID         *Guid
 135   )
 136 ;
 137
 138 /**
 139   Get the Boot Mode from the HOB list.
 140
 141   This function returns the system boot mode information from the
 142   PHIT HOB in HOB list.
 143
 144   @param  VOID
 145
 146   @return The Boot Mode.
 147
 148 **/
 149 EFI_BOOT_MODE
 150 EFIAPI
 151 GetBootModeHob (
 152   VOID
 153   )
 154 ;
 155
 156 /**
 157   Builds a HOB for a loaded PE32 module.
 158
 159   This function builds a HOB for a loaded PE32 module.
 160   It can only be invoked during PEI phase;
 161   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 162   If ModuleName is NULL, then ASSERT().
 163   If there is no additional space for HOB creation, then ASSERT().
 164
 165   @param  ModuleName              The GUID File Name of the module.
 166   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 167   @param  ModuleLength            The length of the module in bytes.
 168   @param  EntryPoint              The 64 bit physical address of the module entry point.
 169
 170 **/
 171 VOID
 172 EFIAPI
 173 GlueBuildModuleHob (
 174   IN CONST EFI_GUID         *ModuleName,
 175   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 176   IN UINT64                 ModuleLength,
 177   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 178   )
 179 ;
 180
 181 /**
 182   Builds a HOB that describes a chunk of system memory.
 183
 184   This function builds a HOB that describes a chunk of system memory.
 185   It can only be invoked during PEI phase;
 186   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 187   If there is no additional space for HOB creation, then ASSERT().
 188
 189   @param  ResourceType        The type of resource described by this HOB.
 190   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 191   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 192   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 193
 194 **/
 195 VOID
 196 EFIAPI
 197 BuildResourceDescriptorHob (
 198   IN EFI_RESOURCE_TYPE            ResourceType,
 199   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 200   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 201   IN UINT64                       NumberOfBytes
 202   )
 203 ;
 204
 205 /**
 206   Builds a GUID HOB with a certain data length.
 207
 208   This function builds a customized HOB tagged with a GUID for identification
 209   and returns the start address of GUID HOB data so that caller can fill the customized data.
 210   The HOB Header and Name field is already stripped.
 211   It can only be invoked during PEI phase;
 212   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 213   If Guid is NULL, then ASSERT().
 214   If there is no additional space for HOB creation, then ASSERT().
 215   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 216
 217   @param  Guid          The GUID to tag the customized HOB.
 218   @param  DataLength    The size of the data payload for the GUID HOB.
 219
 220   @return The start address of GUID HOB data.
 221
 222 **/
 223 VOID *
 224 EFIAPI
 225 BuildGuidHob (
 226   IN CONST EFI_GUID              *Guid,
 227   IN UINTN                       DataLength
 228   )
 229 ;
 230
 231 /**
 232   Copies a data buffer to a newly-built HOB.
 233
 234   This function builds a customized HOB tagged with a GUID for identification,
 235   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 236   The HOB Header and Name field is already stripped.
 237   It can only be invoked during PEI phase;
 238   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 239   If Guid is NULL, then ASSERT().
 240   If Data is NULL and DataLength > 0, then ASSERT().
 241   If there is no additional space for HOB creation, then ASSERT().
 242   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 243
 244   @param  Guid          The GUID to tag the customized HOB.
 245   @param  Data          The data to be copied into the data field of the GUID HOB.
 246   @param  DataLength    The size of the data payload for the GUID HOB.
 247
 248   @return The start address of GUID HOB data.
 249
 250 **/
 251 VOID *
 252 EFIAPI
 253 BuildGuidDataHob (
 254   IN CONST EFI_GUID              *Guid,
 255   IN VOID                        *Data,
 256   IN UINTN                       DataLength
 257   )
 258 ;
 259
 260 /**
 261   Builds a Firmware Volume HOB.
 262
 263   This function builds a Firmware Volume HOB.
 264   It can only be invoked during PEI phase;
 265   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 266   If there is no additional space for HOB creation, then ASSERT().
 267
 268   @param  BaseAddress   The base address of the Firmware Volume.
 269   @param  Length        The size of the Firmware Volume in bytes.
 270
 271 **/
 272 VOID
 273 EFIAPI
 274 BuildFvHob (
 275   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 276   IN UINT64                      Length
 277   )
 278 ;
 279
 280 /**
 281   Builds a Capsule Volume HOB.
 282
 283   This function builds a Capsule Volume HOB.
 284   It can only be invoked during PEI phase;
 285   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 286   If there is no additional space for HOB creation, then ASSERT().
 287
 288   @param  BaseAddress   The base address of the Capsule Volume.
 289   @param  Length        The size of the Capsule Volume in bytes.
 290
 291 **/
 292 VOID
 293 EFIAPI
 294 BuildCvHob (
 295   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 296   IN UINT64                      Length
 297   )
 298 ;
 299
 300 /**
 301   Builds a HOB for the CPU.
 302
 303   This function builds a HOB for the CPU.
 304   It can only be invoked during PEI phase;
 305   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 306   If there is no additional space for HOB creation, then ASSERT().
 307
 308   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 309   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 310
 311 **/
 312 VOID
 313 EFIAPI
 314 BuildCpuHob (
 315   IN UINT8                       SizeOfMemorySpace,
 316   IN UINT8                       SizeOfIoSpace
 317   )
 318 ;
 319
 320 /**
 321   Builds a HOB for the Stack.
 322
 323   This function builds a HOB for the stack.
 324   It can only be invoked during PEI phase;
 325   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 326   If there is no additional space for HOB creation, then ASSERT().
 327
 328   @param  BaseAddress   The 64 bit physical address of the Stack.
 329   @param  Length        The length of the stack in bytes.
 330
 331 **/
 332 VOID
 333 EFIAPI
 334 BuildStackHob (
 335   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 336   IN UINT64                      Length
 337   )
 338 ;
 339
 340 /**
 341   Builds a HOB for the BSP store.
 342
 343   This function builds a HOB for BSP store.
 344   It can only be invoked during PEI phase;
 345   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 346   If there is no additional space for HOB creation, then ASSERT().
 347
 348   @param  BaseAddress   The 64 bit physical address of the BSP.
 349   @param  Length        The length of the BSP store in bytes.
 350   @param  MemoryType    Type of memory allocated by this HOB.
 351
 352 **/
 353 VOID
 354 EFIAPI
 355 BuildBspStoreHob (
 356   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 357   IN UINT64                      Length,
 358   IN EFI_MEMORY_TYPE             MemoryType
 359   )
 360 ;
 361
 362 /**
 363   Builds a HOB for the memory allocation.
 364
 365   This function builds a HOB for the memory allocation.
 366   It can only be invoked during PEI phase;
 367   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 368   If there is no additional space for HOB creation, then ASSERT().
 369
 370   @param  BaseAddress   The 64 bit physical address of the memory.
 371   @param  Length        The length of the memory allocation in bytes.
 372   @param  MemoryType    Type of memory allocated by this HOB.
 373
 374 **/
 375 VOID
 376 EFIAPI
 377 GlueBuildMemoryAllocationHob (
 378   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 379   IN UINT64                      Length,
 380   IN EFI_MEMORY_TYPE             MemoryType
 381   )
 382 ;
 383
 384 #endif