MdePkg/Library/PeiHobLib/HobLib.c

   1 /** @file
   2   HOB Library.
   3
   4   Copyright (c) 2006 - 2007, 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   Get the Boot Mode from the HOB list.
 172
 173   This function returns the system boot mode information from the
 174   PHIT HOB in HOB list.
 175
 176   @param  VOID
 177
 178   @return The Boot Mode.
 179
 180 **/
 181 EFI_BOOT_MODE
 182 EFIAPI
 183 GetBootModeHob (
 184   VOID
 185   )
 186 {
 187   EFI_STATUS             Status;
 188   EFI_BOOT_MODE          BootMode;
 189
 190   Status = PeiServicesGetBootMode (&BootMode);
 191   ASSERT_EFI_ERROR (Status);
 192
 193   return BootMode;
 194 }
 195
 196 /**
 197   Adds a new HOB to the HOB List.
 198
 199   This internal function enables PEIMs to create various types of HOBs.
 200
 201   @param  Type          Type of the new HOB.
 202   @param  Length        Length of the new HOB to allocate.
 203
 204   @return The address of new HOB.
 205
 206 **/
 207 STATIC
 208 VOID *
 209 InternalPeiCreateHob (
 210   IN UINT16                      Type,
 211   IN UINT16                      Length
 212   )
 213 {
 214   EFI_STATUS        Status;
 215   VOID              *Hob;
 216
 217   Status = PeiServicesCreateHob (Type, Length, &Hob);
 218   //
 219   // Assume the process of HOB building is always successful.
 220   //
 221   ASSERT_EFI_ERROR (Status);
 222   return Hob;
 223 }
 224
 225 /**
 226   Builds a HOB for a loaded PE32 module.
 227
 228   This function builds a HOB for a loaded PE32 module.
 229   It can only be invoked during PEI phase;
 230   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 231   If ModuleName is NULL, then ASSERT().
 232   If there is no additional space for HOB creation, then ASSERT().
 233
 234   @param  ModuleName              The GUID File Name of the module.
 235   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 236   @param  ModuleLength            The length of the module in bytes.
 237   @param  EntryPoint              The 64 bit physical address of the module's entry point.
 238
 239 **/
 240 VOID
 241 EFIAPI
 242 BuildModuleHob (
 243   IN CONST EFI_GUID         *ModuleName,
 244   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 245   IN UINT64                 ModuleLength,
 246   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 247   )
 248 {
 249   EFI_HOB_MEMORY_ALLOCATION_MODULE  *Hob;
 250
 251   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_MODULE));
 252
 253   CopyGuid (&(Hob->MemoryAllocationHeader.Name), &gEfiHobMemoryAllocModuleGuid);
 254   Hob->MemoryAllocationHeader.MemoryBaseAddress = MemoryAllocationModule;
 255   Hob->MemoryAllocationHeader.MemoryLength      = ModuleLength;
 256   Hob->MemoryAllocationHeader.MemoryType        = EfiBootServicesCode;
 257
 258   //
 259   // Zero the reserved space to match HOB spec
 260   //
 261   ZeroMem (Hob->MemoryAllocationHeader.Reserved, sizeof (Hob->MemoryAllocationHeader.Reserved));
 262
 263   CopyGuid (&Hob->ModuleName, ModuleName);
 264   Hob->EntryPoint = EntryPoint;
 265 }
 266
 267 /**
 268   Builds a HOB that describes a chunk of system memory.
 269
 270   This function builds a HOB that describes a chunk of system memory.
 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  ResourceType        The type of resource described by this HOB.
 276   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 277   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 278   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 279
 280 **/
 281 VOID
 282 EFIAPI
 283 BuildResourceDescriptorHob (
 284   IN EFI_RESOURCE_TYPE            ResourceType,
 285   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 286   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 287   IN UINT64                       NumberOfBytes
 288   )
 289 {
 290   EFI_HOB_RESOURCE_DESCRIPTOR  *Hob;
 291
 292   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_RESOURCE_DESCRIPTOR, sizeof (EFI_HOB_RESOURCE_DESCRIPTOR));
 293
 294   Hob->ResourceType      = ResourceType;
 295   Hob->ResourceAttribute = ResourceAttribute;
 296   Hob->PhysicalStart     = PhysicalStart;
 297   Hob->ResourceLength    = NumberOfBytes;
 298 }
 299
 300 /**
 301   Builds a GUID HOB with a certain data length.
 302
 303   This function builds a customized HOB tagged with a GUID for identification
 304   and returns the start address of GUID HOB data so that caller can fill the customized data.
 305   The HOB Header and Name field is already stripped.
 306   It can only be invoked during PEI phase;
 307   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 308   If Guid is NULL, then ASSERT().
 309   If there is no additional space for HOB creation, then ASSERT().
 310   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 311
 312   @param  Guid          The GUID to tag the customized HOB.
 313   @param  DataLength    The size of the data payload for the GUID HOB.
 314
 315   @return The start address of GUID HOB data.
 316
 317 **/
 318 VOID *
 319 EFIAPI
 320 BuildGuidHob (
 321   IN CONST EFI_GUID              *Guid,
 322   IN UINTN                       DataLength
 323   )
 324 {
 325   EFI_HOB_GUID_TYPE *Hob;
 326
 327   //
 328   // Make sure that data length is not too long.
 329   //
 330   ASSERT (DataLength <= (0xffff - sizeof (EFI_HOB_GUID_TYPE)));
 331
 332   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_GUID_EXTENSION, (UINT16) (sizeof (EFI_HOB_GUID_TYPE) + DataLength));
 333   CopyGuid (&Hob->Name, Guid);
 334   return Hob + 1;
 335 }
 336
 337 /**
 338   Copies a data buffer to a newly-built HOB.
 339
 340   This function builds a customized HOB tagged with a GUID for identification,
 341   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 342   The HOB Header and Name field is already stripped.
 343   It can only be invoked during PEI phase;
 344   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 345   If Guid is NULL, then ASSERT().
 346   If Data is NULL and DataLength > 0, then ASSERT().
 347   If there is no additional space for HOB creation, then ASSERT().
 348   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 349
 350   @param  Guid          The GUID to tag the customized HOB.
 351   @param  Data          The data to be copied into the data field of the GUID HOB.
 352   @param  DataLength    The size of the data payload for the GUID HOB.
 353
 354   @return The start address of GUID HOB data.
 355
 356 **/
 357 VOID *
 358 EFIAPI
 359 BuildGuidDataHob (
 360   IN CONST EFI_GUID              *Guid,
 361   IN VOID                        *Data,
 362   IN UINTN                       DataLength
 363   )
 364 {
 365   VOID  *HobData;
 366
 367   ASSERT (Data != NULL || DataLength == 0);
 368
 369   HobData = BuildGuidHob (Guid, DataLength);
 370
 371   return CopyMem (HobData, Data, DataLength);
 372 }
 373
 374 /**
 375   Builds a Firmware Volume HOB.
 376
 377   This function builds a Firmware Volume HOB.
 378   It can only be invoked during PEI phase;
 379   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 380   If there is no additional space for HOB creation, then ASSERT().
 381
 382   @param  BaseAddress   The base address of the Firmware Volume.
 383   @param  Length        The size of the Firmware Volume in bytes.
 384
 385 **/
 386 VOID
 387 EFIAPI
 388 BuildFvHob (
 389   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 390   IN UINT64                      Length
 391   )
 392 {
 393   EFI_HOB_FIRMWARE_VOLUME  *Hob;
 394
 395   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_FV, sizeof (EFI_HOB_FIRMWARE_VOLUME));
 396
 397   Hob->BaseAddress = BaseAddress;
 398   Hob->Length      = Length;
 399 }
 400
 401 /**
 402   Builds a Capsule Volume HOB.
 403
 404   This function builds a Capsule Volume HOB.
 405   It can only be invoked during PEI phase;
 406   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 407   If there is no additional space for HOB creation, then ASSERT().
 408
 409   @param  BaseAddress   The base address of the Capsule Volume.
 410   @param  Length        The size of the Capsule Volume in bytes.
 411
 412 **/
 413 VOID
 414 EFIAPI
 415 BuildCvHob (
 416   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 417   IN UINT64                      Length
 418   )
 419 {
 420   EFI_HOB_CAPSULE_VOLUME  *Hob;
 421
 422   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CV, sizeof (EFI_HOB_CAPSULE_VOLUME));
 423
 424   Hob->BaseAddress  = BaseAddress;
 425   Hob->Length       = Length;
 426 }
 427
 428 /**
 429   Builds a HOB for the CPU.
 430
 431   This function builds a HOB for the CPU.
 432   It can only be invoked during PEI phase;
 433   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 434   If there is no additional space for HOB creation, then ASSERT().
 435
 436   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 437   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 438
 439 **/
 440 VOID
 441 EFIAPI
 442 BuildCpuHob (
 443   IN UINT8                       SizeOfMemorySpace,
 444   IN UINT8                       SizeOfIoSpace
 445   )
 446 {
 447   EFI_HOB_CPU  *Hob;
 448
 449   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CPU, sizeof (EFI_HOB_CPU));
 450
 451   Hob->SizeOfMemorySpace = SizeOfMemorySpace;
 452   Hob->SizeOfIoSpace     = SizeOfIoSpace;
 453
 454   //
 455   // Zero the reserved space to match HOB spec
 456   //
 457   ZeroMem (Hob->Reserved, sizeof (Hob->Reserved));
 458 }
 459
 460 /**
 461   Builds a HOB for the Stack.
 462
 463   This function builds a HOB for the stack.
 464   It can only be invoked during PEI phase;
 465   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 466   If there is no additional space for HOB creation, then ASSERT().
 467
 468   @param  BaseAddress   The 64 bit physical address of the Stack.
 469   @param  Length        The length of the stack in bytes.
 470
 471 **/
 472 VOID
 473 EFIAPI
 474 BuildStackHob (
 475   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 476   IN UINT64                      Length
 477   )
 478 {
 479   EFI_HOB_MEMORY_ALLOCATION_STACK  *Hob;
 480
 481   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_STACK));
 482
 483   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocStackGuid);
 484   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 485   Hob->AllocDescriptor.MemoryLength      = Length;
 486   Hob->AllocDescriptor.MemoryType        = EfiConventionalMemory;
 487
 488   //
 489   // Zero the reserved space to match HOB spec
 490   //
 491   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 492 }
 493
 494 /**
 495   Builds a HOB for the BSP store.
 496
 497   This function builds a HOB for BSP store.
 498   It can only be invoked during PEI phase;
 499   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 500   If there is no additional space for HOB creation, then ASSERT().
 501
 502   @param  BaseAddress   The 64 bit physical address of the BSP.
 503   @param  Length        The length of the BSP store in bytes.
 504   @param  MemoryType    Type of memory allocated by this HOB.
 505
 506 **/
 507 VOID
 508 EFIAPI
 509 BuildBspStoreHob (
 510   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 511   IN UINT64                      Length,
 512   IN EFI_MEMORY_TYPE             MemoryType
 513   )
 514 {
 515   EFI_HOB_MEMORY_ALLOCATION_BSP_STORE  *Hob;
 516
 517   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_BSP_STORE));
 518
 519   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocBspStoreGuid);
 520   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 521   Hob->AllocDescriptor.MemoryLength      = Length;
 522   Hob->AllocDescriptor.MemoryType        = MemoryType;
 523
 524   //
 525   // Zero the reserved space to match HOB spec
 526   //
 527   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 528 }
 529
 530 /**
 531   Builds a HOB for the memory allocation.
 532
 533   This function builds a HOB for the memory allocation.
 534   It can only be invoked during PEI phase;
 535   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 536   If there is no additional space for HOB creation, then ASSERT().
 537
 538   @param  BaseAddress   The 64 bit physical address of the memory.
 539   @param  Length        The length of the memory allocation in bytes.
 540   @param  MemoryType    Type of memory allocated by this HOB.
 541
 542 **/
 543 VOID
 544 EFIAPI
 545 BuildMemoryAllocationHob (
 546   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 547   IN UINT64                      Length,
 548   IN EFI_MEMORY_TYPE             MemoryType
 549   )
 550 {
 551   EFI_HOB_MEMORY_ALLOCATION  *Hob;
 552
 553   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION));
 554
 555   ZeroMem (&(Hob->AllocDescriptor.Name), sizeof (EFI_GUID));
 556   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 557   Hob->AllocDescriptor.MemoryLength      = Length;
 558   Hob->AllocDescriptor.MemoryType        = MemoryType;
 559   //
 560   // Zero the reserved space to match HOB spec
 561   //
 562   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 563 }