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