OldMdePkg/Include/Library/HobLib.h

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