MdePkg/Include/Library/HobLib.h

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