MdePkg/Library/PeiHobLib/HobLib.c

   1 /** @file
   2   HOB Library.
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   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.c
  14
  15 **/
  16
  17
  18
  19 /**
  20   Returns the pointer to the HOB list.
  21
  22   This function returns the pointer to first HOB in the list.
  23
  24   @return The pointer to the HOB list.
  25
  26 **/
  27 VOID *
  28 EFIAPI
  29 GetHobList (
  30   VOID
  31   )
  32 {
  33   EFI_STATUS            Status;
  34   VOID                  *HobList;
  35
  36   Status = PeiServicesGetHobList (&HobList);
  37   ASSERT_EFI_ERROR (Status);
  38   ASSERT (HobList != NULL);
  39
  40   return HobList;
  41 }
  42
  43 /**
  44   Returns the next instance of a HOB type from the starting HOB.
  45
  46   This function searches the first instance of a HOB type from the starting HOB pointer.
  47   If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  48   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  49   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  50   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  51   If HobStart is NULL, then ASSERT().
  52
  53   @param  Type          The HOB type to return.
  54   @param  HobStart      The starting HOB pointer to search from.
  55
  56   @return The next instance of a HOB type from the starting HOB.
  57
  58 **/
  59 VOID *
  60 EFIAPI
  61 GetNextHob (
  62   IN UINT16                 Type,
  63   IN CONST VOID             *HobStart
  64   )
  65 {
  66   EFI_PEI_HOB_POINTERS  Hob;
  67
  68   ASSERT (HobStart != NULL);
  69
  70   Hob.Raw = (UINT8 *) HobStart;
  71   //
  72   // Parse the HOB list until end of list or matching type is found.
  73   //
  74   while (!END_OF_HOB_LIST (Hob)) {
  75     if (Hob.Header->HobType == Type) {
  76       return Hob.Raw;
  77     }
  78     Hob.Raw = GET_NEXT_HOB (Hob);
  79   }
  80   return NULL;
  81 }
  82
  83 /**
  84   Returns the first instance of a HOB type among the whole HOB list.
  85
  86   This function searches the first instance of a HOB type among the whole HOB list.
  87   If there does not exist such HOB type in the HOB list, it will return NULL.
  88
  89   @param  Type          The HOB type to return.
  90
  91   @return The next instance of a HOB type from the starting HOB.
  92
  93 **/
  94 VOID *
  95 EFIAPI
  96 GetFirstHob (
  97   IN UINT16                 Type
  98   )
  99 {
 100   VOID      *HobList;
 101
 102   HobList = GetHobList ();
 103   return GetNextHob (Type, HobList);
 104 }
 105
 106 /**
 107   This function searches the first instance of a HOB from the starting HOB pointer.
 108   Such HOB should satisfy two conditions:
 109   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 110   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 111   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 112   to extract the data section and its size info respectively.
 113   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
 114   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
 115   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
 116   If Guid is NULL, then ASSERT().
 117   If HobStart is NULL, then ASSERT().
 118
 119   @param  Guid          The GUID to match with in the HOB list.
 120   @param  HobStart      A pointer to a Guid.
 121
 122   @return The next instance of the matched GUID HOB from the starting HOB.
 123
 124 **/
 125 VOID *
 126 EFIAPI
 127 GetNextGuidHob (
 128   IN CONST EFI_GUID         *Guid,
 129   IN CONST VOID             *HobStart
 130   )
 131 {
 132   EFI_PEI_HOB_POINTERS  GuidHob;
 133
 134   GuidHob.Raw = (UINT8 *) HobStart;
 135   while ((GuidHob.Raw = GetNextHob (EFI_HOB_TYPE_GUID_EXTENSION, GuidHob.Raw)) != NULL) {
 136     if (CompareGuid (Guid, &GuidHob.Guid->Name)) {
 137       break;
 138     }
 139     GuidHob.Raw = GET_NEXT_HOB (GuidHob);
 140   }
 141   return GuidHob.Raw;
 142 }
 143
 144 /**
 145   This function searches the first instance of a HOB among the whole HOB list.
 146   Such HOB should satisfy two conditions:
 147   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 148   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 149   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 150   to extract the data section and its size info respectively.
 151   If Guid is NULL, then ASSERT().
 152
 153   @param  Guid          The GUID to match with in the HOB list.
 154
 155   @return The first instance of the matched GUID HOB among the whole HOB list.
 156
 157 **/
 158 VOID *
 159 EFIAPI
 160 GetFirstGuidHob (
 161   IN CONST EFI_GUID         *Guid
 162   )
 163 {
 164   VOID      *HobList;
 165
 166   HobList = GetHobList ();
 167   return GetNextGuidHob (Guid, HobList);
 168 }
 169
 170 /**
 171   Adds a new HOB to the HOB List.
 172
 173   This internal function enables PEIMs to create various types of HOBs.
 174
 175   @param  Type          Type of the new HOB.
 176   @param  Length        Length of the new HOB to allocate.
 177
 178   @return The address of new HOB.
 179
 180 **/
 181 STATIC
 182 VOID *
 183 InternalPeiCreateHob (
 184   IN UINT16                      Type,
 185   IN UINT16                      Length
 186   )
 187 {
 188   EFI_STATUS        Status;
 189   VOID              *Hob;
 190
 191   Status = PeiServicesCreateHob (Type, Length, &Hob);
 192   //
 193   // Assume the process of HOB building is always successful.
 194   //
 195   ASSERT_EFI_ERROR (Status);
 196   return Hob;
 197 }
 198
 199 /**
 200   Builds a HOB for a loaded PE32 module.
 201
 202   This function builds a HOB for a loaded PE32 module.
 203   It can only be invoked during PEI phase;
 204   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 205   If ModuleName is NULL, then ASSERT().
 206   If there is no additional space for HOB creation, then ASSERT().
 207
 208   @param  ModuleName              The GUID File Name of the module.
 209   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 210   @param  ModuleLength            The length of the module in bytes.
 211   @param  EntryPoint              The 64 bit physical address of the module's entry point.
 212
 213 **/
 214 VOID
 215 EFIAPI
 216 BuildModuleHob (
 217   IN CONST EFI_GUID         *ModuleName,
 218   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 219   IN UINT64                 ModuleLength,
 220   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 221   )
 222 {
 223   EFI_HOB_MEMORY_ALLOCATION_MODULE  *Hob;
 224
 225   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_MODULE));
 226
 227   CopyGuid (&(Hob->MemoryAllocationHeader.Name), &gEfiHobMemoryAllocModuleGuid);
 228   Hob->MemoryAllocationHeader.MemoryBaseAddress = MemoryAllocationModule;
 229   Hob->MemoryAllocationHeader.MemoryLength      = ModuleLength;
 230   Hob->MemoryAllocationHeader.MemoryType        = EfiBootServicesCode;
 231
 232   //
 233   // Zero the reserved space to match HOB spec
 234   //
 235   ZeroMem (Hob->MemoryAllocationHeader.Reserved, sizeof (Hob->MemoryAllocationHeader.Reserved));
 236
 237   CopyGuid (&Hob->ModuleName, ModuleName);
 238   Hob->EntryPoint = EntryPoint;
 239 }
 240
 241 /**
 242   Builds a HOB that describes a chunk of system memory.
 243
 244   This function builds a HOB that describes a chunk of system memory.
 245   It can only be invoked during PEI phase;
 246   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 247   If there is no additional space for HOB creation, then ASSERT().
 248
 249   @param  ResourceType        The type of resource described by this HOB.
 250   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 251   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 252   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 253
 254 **/
 255 VOID
 256 EFIAPI
 257 BuildResourceDescriptorHob (
 258   IN EFI_RESOURCE_TYPE            ResourceType,
 259   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 260   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 261   IN UINT64                       NumberOfBytes
 262   )
 263 {
 264   EFI_HOB_RESOURCE_DESCRIPTOR  *Hob;
 265
 266   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_RESOURCE_DESCRIPTOR, sizeof (EFI_HOB_RESOURCE_DESCRIPTOR));
 267
 268   Hob->ResourceType      = ResourceType;
 269   Hob->ResourceAttribute = ResourceAttribute;
 270   Hob->PhysicalStart     = PhysicalStart;
 271   Hob->ResourceLength    = NumberOfBytes;
 272 }
 273
 274 /**
 275   Builds a GUID HOB with a certain data length.
 276
 277   This function builds a customized HOB tagged with a GUID for identification
 278   and returns the start address of GUID HOB data so that caller can fill the customized data.
 279   The HOB Header and Name field is already stripped.
 280   It can only be invoked during PEI phase;
 281   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 282   If Guid is NULL, then ASSERT().
 283   If there is no additional space for HOB creation, then ASSERT().
 284   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 285
 286   @param  Guid          The GUID to tag the customized HOB.
 287   @param  DataLength    The size of the data payload for the GUID HOB.
 288
 289   @return The start address of GUID HOB data.
 290
 291 **/
 292 VOID *
 293 EFIAPI
 294 BuildGuidHob (
 295   IN CONST EFI_GUID              *Guid,
 296   IN UINTN                       DataLength
 297   )
 298 {
 299   EFI_HOB_GUID_TYPE *Hob;
 300
 301   //
 302   // Make sure that data length is not too long.
 303   //
 304   ASSERT (DataLength <= (0xffff - sizeof (EFI_HOB_GUID_TYPE)));
 305
 306   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_GUID_EXTENSION, (UINT16) (sizeof (EFI_HOB_GUID_TYPE) + DataLength));
 307   CopyGuid (&Hob->Name, Guid);
 308   return Hob + 1;
 309 }
 310
 311 /**
 312   Copies a data buffer to a newly-built HOB.
 313
 314   This function builds a customized HOB tagged with a GUID for identification,
 315   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 316   The HOB Header and Name field is already stripped.
 317   It can only be invoked during PEI phase;
 318   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 319   If Guid is NULL, then ASSERT().
 320   If Data is NULL and DataLength > 0, then ASSERT().
 321   If there is no additional space for HOB creation, then ASSERT().
 322   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 323
 324   @param  Guid          The GUID to tag the customized HOB.
 325   @param  Data          The data to be copied into the data field of the GUID HOB.
 326   @param  DataLength    The size of the data payload for the GUID HOB.
 327
 328   @return The start address of GUID HOB data.
 329
 330 **/
 331 VOID *
 332 EFIAPI
 333 BuildGuidDataHob (
 334   IN CONST EFI_GUID              *Guid,
 335   IN VOID                        *Data,
 336   IN UINTN                       DataLength
 337   )
 338 {
 339   VOID  *HobData;
 340
 341   ASSERT (Data != NULL || DataLength == 0);
 342
 343   HobData = BuildGuidHob (Guid, DataLength);
 344
 345   return CopyMem (HobData, Data, DataLength);
 346 }
 347
 348 /**
 349   Builds a Firmware Volume HOB.
 350
 351   This function builds a Firmware Volume HOB.
 352   It can only be invoked during PEI phase;
 353   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 354   If there is no additional space for HOB creation, then ASSERT().
 355
 356   @param  BaseAddress   The base address of the Firmware Volume.
 357   @param  Length        The size of the Firmware Volume in bytes.
 358
 359 **/
 360 VOID
 361 EFIAPI
 362 BuildFvHob (
 363   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 364   IN UINT64                      Length
 365   )
 366 {
 367   EFI_HOB_FIRMWARE_VOLUME  *Hob;
 368
 369   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_FV, sizeof (EFI_HOB_FIRMWARE_VOLUME));
 370
 371   Hob->BaseAddress = BaseAddress;
 372   Hob->Length      = Length;
 373 }
 374
 375 /**
 376   Builds a Capsule Volume HOB.
 377
 378   This function builds a Capsule Volume HOB.
 379   It can only be invoked during PEI phase;
 380   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 381   If there is no additional space for HOB creation, then ASSERT().
 382
 383   @param  BaseAddress   The base address of the Capsule Volume.
 384   @param  Length        The size of the Capsule Volume in bytes.
 385
 386 **/
 387 VOID
 388 EFIAPI
 389 BuildCvHob (
 390   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 391   IN UINT64                      Length
 392   )
 393 {
 394   EFI_HOB_CAPSULE_VOLUME  *Hob;
 395
 396   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CV, sizeof (EFI_HOB_CAPSULE_VOLUME));
 397
 398   Hob->BaseAddress  = BaseAddress;
 399   Hob->Length       = Length;
 400 }
 401
 402 /**
 403   Builds a HOB for the CPU.
 404
 405   This function builds a HOB for the CPU.
 406   It can only be invoked during PEI phase;
 407   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 408   If there is no additional space for HOB creation, then ASSERT().
 409
 410   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 411   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 412
 413 **/
 414 VOID
 415 EFIAPI
 416 BuildCpuHob (
 417   IN UINT8                       SizeOfMemorySpace,
 418   IN UINT8                       SizeOfIoSpace
 419   )
 420 {
 421   EFI_HOB_CPU  *Hob;
 422
 423   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CPU, sizeof (EFI_HOB_CPU));
 424
 425   Hob->SizeOfMemorySpace = SizeOfMemorySpace;
 426   Hob->SizeOfIoSpace     = SizeOfIoSpace;
 427
 428   //
 429   // Zero the reserved space to match HOB spec
 430   //
 431   ZeroMem (Hob->Reserved, sizeof (Hob->Reserved));
 432 }
 433
 434 /**
 435   Builds a HOB for the Stack.
 436
 437   This function builds a HOB for the stack.
 438   It can only be invoked during PEI phase;
 439   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 440   If there is no additional space for HOB creation, then ASSERT().
 441
 442   @param  BaseAddress   The 64 bit physical address of the Stack.
 443   @param  Length        The length of the stack in bytes.
 444
 445 **/
 446 VOID
 447 EFIAPI
 448 BuildStackHob (
 449   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 450   IN UINT64                      Length
 451   )
 452 {
 453   EFI_HOB_MEMORY_ALLOCATION_STACK  *Hob;
 454
 455   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_STACK));
 456
 457   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocStackGuid);
 458   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 459   Hob->AllocDescriptor.MemoryLength      = Length;
 460   Hob->AllocDescriptor.MemoryType        = EfiConventionalMemory;
 461
 462   //
 463   // Zero the reserved space to match HOB spec
 464   //
 465   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 466 }
 467
 468 /**
 469   Builds a HOB for the BSP store.
 470
 471   This function builds a HOB for BSP store.
 472   It can only be invoked during PEI phase;
 473   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 474   If there is no additional space for HOB creation, then ASSERT().
 475
 476   @param  BaseAddress   The 64 bit physical address of the BSP.
 477   @param  Length        The length of the BSP store in bytes.
 478   @param  MemoryType    Type of memory allocated by this HOB.
 479
 480 **/
 481 VOID
 482 EFIAPI
 483 BuildBspStoreHob (
 484   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 485   IN UINT64                      Length,
 486   IN EFI_MEMORY_TYPE             MemoryType
 487   )
 488 {
 489   EFI_HOB_MEMORY_ALLOCATION_BSP_STORE  *Hob;
 490
 491   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_BSP_STORE));
 492
 493   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocBspStoreGuid);
 494   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 495   Hob->AllocDescriptor.MemoryLength      = Length;
 496   Hob->AllocDescriptor.MemoryType        = MemoryType;
 497
 498   //
 499   // Zero the reserved space to match HOB spec
 500   //
 501   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 502 }
 503
 504 /**
 505   Builds a HOB for the memory allocation.
 506
 507   This function builds a HOB for the memory allocation.
 508   It can only be invoked during PEI phase;
 509   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 510   If there is no additional space for HOB creation, then ASSERT().
 511
 512   @param  BaseAddress   The 64 bit physical address of the memory.
 513   @param  Length        The length of the memory allocation in bytes.
 514   @param  MemoryType    Type of memory allocated by this HOB.
 515
 516 **/
 517 VOID
 518 EFIAPI
 519 BuildMemoryAllocationHob (
 520   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 521   IN UINT64                      Length,
 522   IN EFI_MEMORY_TYPE             MemoryType
 523   )
 524 {
 525   EFI_HOB_MEMORY_ALLOCATION  *Hob;
 526
 527   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION));
 528
 529   ZeroMem (&(Hob->AllocDescriptor.Name), sizeof (EFI_GUID));
 530   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 531   Hob->AllocDescriptor.MemoryLength      = Length;
 532   Hob->AllocDescriptor.MemoryType        = MemoryType;
 533   //
 534   // Zero the reserved space to match HOB spec
 535   //
 536   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 537 }