MdePkg/Include/Library/HobLib.h

   1 /** @file
   2         Public include file for the HOB Library
   3
   4         Copyright (c) 2006, 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   Builds a HOB for a loaded PE32 module.
 127
 128   This function builds a HOB for a loaded PE32 module.
 129   It can only be invoked during PEI phase;
 130   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 131   If ModuleName is NULL, then ASSERT().
 132   If there is no additional space for HOB creation, then ASSERT().
 133
 134   @param  ModuleName              The GUID File Name of the module.
 135   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 136   @param  ModuleLength            The length of the module in bytes.
 137   @param  EntryPoint              The 64 bit physical address of the module\92s entry point.
 138
 139 **/
 140 VOID
 141 EFIAPI
 142 BuildModuleHob (
 143   IN CONST EFI_GUID         *ModuleName,
 144   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 145   IN UINT64                 ModuleLength,
 146   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 147   )
 148 ;
 149
 150 /**
 151   Builds a HOB that describes a chunk of system memory.
 152
 153   This function builds a HOB that describes a chunk of system memory.
 154   It can only be invoked during PEI phase;
 155   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 156   If there is no additional space for HOB creation, then ASSERT().
 157
 158   @param  ResourceType        The type of resource described by this HOB.
 159   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 160   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 161   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 162
 163 **/
 164 VOID
 165 EFIAPI
 166 BuildResourceDescriptorHob (
 167   IN EFI_RESOURCE_TYPE            ResourceType,
 168   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 169   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 170   IN UINT64                       NumberOfBytes
 171   )
 172 ;
 173
 174 /**
 175   Builds a GUID HOB with a certain data length.
 176
 177   This function builds a customized HOB tagged with a GUID for identification
 178   and returns the start address of GUID HOB data so that caller can fill the customized data.
 179   The HOB Header and Name field is already stripped.
 180   It can only be invoked during PEI phase;
 181   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 182   If Guid is NULL, then ASSERT().
 183   If there is no additional space for HOB creation, then ASSERT().
 184   If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT().
 185
 186   @param  Guid          The GUID to tag the customized HOB.
 187   @param  DataLength    The size of the data payload for the GUID HOB.
 188
 189   @return The start address of GUID HOB data.
 190
 191 **/
 192 VOID *
 193 EFIAPI
 194 BuildGuidHob (
 195   IN CONST EFI_GUID              *Guid,
 196   IN UINTN                       DataLength
 197   )
 198 ;
 199
 200 /**
 201   Copies a data buffer to a newly-built HOB.
 202
 203   This function builds a customized HOB tagged with a GUID for identification,
 204   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 205   The HOB Header and Name field is already stripped.
 206   It can only be invoked during PEI phase;
 207   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 208   If Guid is NULL, then ASSERT().
 209   If Data is NULL and DataLength > 0, then ASSERT().
 210   If there is no additional space for HOB creation, then ASSERT().
 211   If DataLength > (0x10000 - sizeof (EFI_HOB_TYPE_GUID)), then ASSERT().
 212
 213   @param  Guid          The GUID to tag the customized HOB.
 214   @param  Data          The data to be copied into the data field of the GUID HOB.
 215   @param  DataLength    The size of the data payload for the GUID HOB.
 216
 217   @return The start address of GUID HOB data.
 218
 219 **/
 220 VOID *
 221 EFIAPI
 222 BuildGuidDataHob (
 223   IN CONST EFI_GUID              *Guid,
 224   IN VOID                        *Data,
 225   IN UINTN                       DataLength
 226   )
 227 ;
 228
 229 /**
 230   Builds a Firmware Volume HOB.
 231
 232   This function builds a Firmware Volume HOB.
 233   It can only be invoked during PEI phase;
 234   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 235   If there is no additional space for HOB creation, then ASSERT().
 236
 237   @param  BaseAddress   The base address of the Firmware Volume.
 238   @param  Length        The size of the Firmware Volume in bytes.
 239
 240 **/
 241 VOID
 242 EFIAPI
 243 BuildFvHob (
 244   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 245   IN UINT64                      Length
 246   )
 247 ;
 248
 249 /**
 250   Builds a Capsule Volume HOB.
 251
 252   This function builds a Capsule Volume HOB.
 253   It can only be invoked during PEI phase;
 254   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 255   If there is no additional space for HOB creation, then ASSERT().
 256
 257   @param  BaseAddress   The base address of the Capsule Volume.
 258   @param  Length        The size of the Capsule Volume in bytes.
 259
 260 **/
 261 VOID
 262 EFIAPI
 263 BuildCvHob (
 264   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 265   IN UINT64                      Length
 266   )
 267 ;
 268
 269 /**
 270   Builds a HOB for the CPU.
 271
 272   This function builds a HOB for the CPU.
 273   It can only be invoked during PEI phase;
 274   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 275   If there is no additional space for HOB creation, then ASSERT().
 276
 277   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 278   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 279
 280 **/
 281 VOID
 282 EFIAPI
 283 BuildCpuHob (
 284   IN UINT8                       SizeOfMemorySpace,
 285   IN UINT8                       SizeOfIoSpace
 286   )
 287 ;
 288
 289 /**
 290   Builds a HOB for the Stack.
 291
 292   This function builds a HOB for the stack.
 293   It can only be invoked during PEI phase;
 294   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 295   If there is no additional space for HOB creation, then ASSERT().
 296
 297   @param  BaseAddress   The 64 bit physical address of the Stack.
 298   @param  Length        The length of the stack in bytes.
 299
 300 **/
 301 VOID
 302 EFIAPI
 303 BuildStackHob (
 304   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 305   IN UINT64                      Length
 306   )
 307 ;
 308
 309 /**
 310   Builds a HOB for the BSP store.
 311
 312   This function builds a HOB for BSP store.
 313   It can only be invoked during PEI phase;
 314   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 315   If there is no additional space for HOB creation, then ASSERT().
 316
 317   @param  BaseAddress   The 64 bit physical address of the BSP.
 318   @param  Length        The length of the BSP store in bytes.
 319   @param  MemoryType    Type of memory allocated by this HOB.
 320
 321 **/
 322 VOID
 323 EFIAPI
 324 BuildBspStoreHob (
 325   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 326   IN UINT64                      Length,
 327   IN EFI_MEMORY_TYPE             MemoryType
 328   )
 329 ;
 330
 331 /**
 332   Builds a HOB for the memory allocation.
 333
 334   This function builds a HOB for the memory allocation.
 335   It can only be invoked during PEI phase;
 336   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 337   If there is no additional space for HOB creation, then ASSERT().
 338
 339   @param  BaseAddress   The 64 bit physical address of the memory.
 340   @param  Length        The length of the memory allocation in bytes.
 341   @param  MemoryType    Type of memory allocated by this HOB.
 342
 343 **/
 344 VOID
 345 EFIAPI
 346 BuildMemoryAllocationHob (
 347   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 348   IN UINT64                      Length,
 349   IN EFI_MEMORY_TYPE             MemoryType
 350   )
 351 ;
 352
 353 #endif