1/** @file 2 Provides library functions for all PEI Services. 3 4Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 5This program and the accompanying materials 6are licensed and made available under the terms and conditions of the BSD License 7which accompanies this distribution. The full text of the license may be found at 8http://opensource.org/licenses/bsd-license.php 9 10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13**/ 14 15#ifndef __PEI_SERVICES_LIB_H__ 16#define __PEI_SERVICES_LIB_H__ 17 18/** 19 This service enables a given PEIM to register an interface into the PEI Foundation. 20 21 @param PpiList A pointer to the list of interfaces that the caller shall install. 22 23 @retval EFI_SUCCESS The interface was successfully installed. 24 @retval EFI_INVALID_PARAMETER The PpiList pointer is NULL. 25 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the 26 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field. 27 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 28 29**/ 30EFI_STATUS 31EFIAPI 32PeiServicesInstallPpi ( 33 IN CONST EFI_PEI_PPI_DESCRIPTOR *PpiList 34 ); 35 36/** 37 This service enables PEIMs to replace an entry in the PPI database with an alternate entry. 38 39 @param OldPpi Pointer to the old PEI PPI Descriptors. 40 @param NewPpi Pointer to the new PEI PPI Descriptors. 41 42 @retval EFI_SUCCESS The interface was successfully installed. 43 @retval EFI_INVALID_PARAMETER The OldPpi or NewPpi is NULL. 44 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the 45 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field. 46 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 47 @retval EFI_NOT_FOUND The PPI for which the reinstallation was requested has not been 48 installed. 49 50**/ 51EFI_STATUS 52EFIAPI 53PeiServicesReInstallPpi ( 54 IN CONST EFI_PEI_PPI_DESCRIPTOR *OldPpi, 55 IN CONST EFI_PEI_PPI_DESCRIPTOR *NewPpi 56 ); 57 58/** 59 This service enables PEIMs to discover a given instance of an interface. 60 61 @param Guid A pointer to the GUID whose corresponding interface needs to be 62 found. 63 @param Instance The N-th instance of the interface that is required. 64 @param PpiDescriptor A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR. 65 @param Ppi A pointer to the instance of the interface. 66 67 @retval EFI_SUCCESS The interface was successfully returned. 68 @retval EFI_NOT_FOUND The PPI descriptor is not found in the database. 69 70**/ 71EFI_STATUS 72EFIAPI 73PeiServicesLocatePpi ( 74 IN CONST EFI_GUID *Guid, 75 IN UINTN Instance, 76 IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor, 77 IN OUT VOID **Ppi 78 ); 79 80/** 81 This service enables PEIMs to register a given service to be invoked when another service is 82 installed or reinstalled. 83 84 @param NotifyList A pointer to the list of notification interfaces that the caller 85 shall install. 86 87 @retval EFI_SUCCESS The interface was successfully installed. 88 @retval EFI_INVALID_PARAMETER The NotifyList pointer is NULL. 89 @retval EFI_INVALID_PARAMETER Any of the PEI notify descriptors in the list do not have the 90 EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field. 91 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 92 93**/ 94EFI_STATUS 95EFIAPI 96PeiServicesNotifyPpi ( 97 IN CONST EFI_PEI_NOTIFY_DESCRIPTOR *NotifyList 98 ); 99 100/** 101 This service enables PEIMs to ascertain the present value of the boot mode. 102 103 @param BootMode A pointer to contain the value of the boot mode. 104 105 @retval EFI_SUCCESS The boot mode was returned successfully. 106 @retval EFI_INVALID_PARAMETER BootMode is NULL. 107 108**/ 109EFI_STATUS 110EFIAPI 111PeiServicesGetBootMode ( 112 OUT EFI_BOOT_MODE *BootMode 113 ); 114 115/** 116 This service enables PEIMs to update the boot mode variable. 117 118 @param BootMode The value of the boot mode to set. 119 120 @retval EFI_SUCCESS The value was successfully updated 121 122**/ 123EFI_STATUS 124EFIAPI 125PeiServicesSetBootMode ( 126 IN EFI_BOOT_MODE BootMode 127 ); 128 129/** 130 This service enables a PEIM to ascertain the address of the list of HOBs in memory. 131 132 @param HobList A pointer to the list of HOBs that the PEI Foundation will initialize. 133 134 @retval EFI_SUCCESS The list was successfully returned. 135 @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published. 136 137**/ 138EFI_STATUS 139EFIAPI 140PeiServicesGetHobList ( 141 OUT VOID **HobList 142 ); 143 144/** 145 This service enables PEIMs to create various types of HOBs. 146 147 @param Type The type of HOB to be installed. 148 @param Length The length of the HOB to be added. 149 @param Hob The address of a pointer that will contain the HOB header. 150 151 @retval EFI_SUCCESS The HOB was successfully created. 152 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation. 153 154**/ 155EFI_STATUS 156EFIAPI 157PeiServicesCreateHob ( 158 IN UINT16 Type, 159 IN UINT16 Length, 160 OUT VOID **Hob 161 ); 162 163/** 164 This service enables PEIMs to discover additional firmware volumes. 165 166 @param Instance This instance of the firmware volume to find. The value 0 is the 167 Boot Firmware Volume (BFV). 168 @param VolumeHandle Handle of the firmware volume header of the volume to return. 169 170 @retval EFI_SUCCESS The volume was found. 171 @retval EFI_NOT_FOUND The volume was not found. 172 @retval EFI_INVALID_PARAMETER FwVolHeader is NULL. 173 174**/ 175EFI_STATUS 176EFIAPI 177PeiServicesFfsFindNextVolume ( 178 IN UINTN Instance, 179 IN OUT EFI_PEI_FV_HANDLE *VolumeHandle 180 ); 181 182/** 183 This service enables PEIMs to discover additional firmware files. 184 185 @param SearchType A filter to find files only of this type. 186 @param VolumeHandle Pointer to the firmware volume header of the volume to search. 187 This parameter must point to a valid FFS volume. 188 @param FileHandle Handle of the current file from which to begin searching. 189 190 @retval EFI_SUCCESS The file was found. 191 @retval EFI_NOT_FOUND The file was not found. 192 @retval EFI_NOT_FOUND The header checksum was not zero. 193 194**/ 195EFI_STATUS 196EFIAPI 197PeiServicesFfsFindNextFile ( 198 IN EFI_FV_FILETYPE SearchType, 199 IN EFI_PEI_FV_HANDLE VolumeHandle, 200 IN OUT EFI_PEI_FILE_HANDLE *FileHandle 201 ); 202 203/** 204 This service enables PEIMs to discover sections of a given type within a valid FFS file. 205 206 @param SectionType The value of the section type to find. 207 @param FileHandle A pointer to the file header that contains the set of sections to 208 be searched. 209 @param SectionData A pointer to the discovered section, if successful. 210 211 @retval EFI_SUCCESS The section was found. 212 @retval EFI_NOT_FOUND The section was not found. 213 214**/ 215EFI_STATUS 216EFIAPI 217PeiServicesFfsFindSectionData ( 218 IN EFI_SECTION_TYPE SectionType, 219 IN EFI_PEI_FILE_HANDLE FileHandle, 220 OUT VOID **SectionData 221 ); 222 223/** 224 This service enables PEIMs to discover sections of a given instance and type within a valid FFS file. 225 226 @param SectionType The value of the section type to find. 227 @param SectionInstance Section instance to find. 228 @param FileHandle A pointer to the file header that contains the set 229 of sections to be searched. 230 @param SectionData A pointer to the discovered section, if successful. 231 @param AuthenticationStatus A pointer to the authentication status for this section. 232 233 @retval EFI_SUCCESS The section was found. 234 @retval EFI_NOT_FOUND The section was not found. 235 236**/ 237EFI_STATUS 238EFIAPI 239PeiServicesFfsFindSectionData3 ( 240 IN EFI_SECTION_TYPE SectionType, 241 IN UINTN SectionInstance, 242 IN EFI_PEI_FILE_HANDLE FileHandle, 243 OUT VOID **SectionData, 244 OUT UINT32 *AuthenticationStatus 245 ); 246 247/** 248 This service enables PEIMs to register the permanent memory configuration 249 that has been initialized with the PEI Foundation. 250 251 @param MemoryBegin The value of a region of installed memory. 252 @param MemoryLength The corresponding length of a region of installed memory. 253 254 @retval EFI_SUCCESS The region was successfully installed in a HOB. 255 @retval EFI_INVALID_PARAMETER MemoryBegin and MemoryLength are illegal for this system. 256 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation. 257 258**/ 259EFI_STATUS 260EFIAPI 261PeiServicesInstallPeiMemory ( 262 IN EFI_PHYSICAL_ADDRESS MemoryBegin, 263 IN UINT64 MemoryLength 264 ); 265 266/** 267 This service enables PEIMs to allocate memory after the permanent memory has been installed by a 268 PEIM. 269 270 @param MemoryType Type of memory to allocate. 271 @param Pages Number of pages to allocate. 272 @param Memory Pointer of memory allocated. 273 274 @retval EFI_SUCCESS The memory range was successfully allocated. 275 @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages. 276 @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available. 277 @retval EFI_OUT_OF_RESOURCES The pages could not be allocated. 278 279**/ 280EFI_STATUS 281EFIAPI 282PeiServicesAllocatePages ( 283 IN EFI_MEMORY_TYPE MemoryType, 284 IN UINTN Pages, 285 OUT EFI_PHYSICAL_ADDRESS *Memory 286 ); 287 288/** 289 This service allocates memory from the Hand-Off Block (HOB) heap. 290 291 @param Size The number of bytes to allocate from the pool. 292 @param Buffer If the call succeeds, a pointer to a pointer to the allocate 293 buffer; undefined otherwise. 294 295 @retval EFI_SUCCESS The allocation was successful 296 @retval EFI_OUT_OF_RESOURCES There is not enough heap to allocate the requested size. 297 298**/ 299EFI_STATUS 300EFIAPI 301PeiServicesAllocatePool ( 302 IN UINTN Size, 303 OUT VOID **Buffer 304 ); 305 306/** 307 Resets the entire platform. 308 309 @retval EFI_SUCCESS The function completed successfully. 310 @retval EFI_NOT_AVAILABLE_YET The service has not been installed yet. 311 312**/ 313EFI_STATUS 314EFIAPI 315PeiServicesResetSystem ( 316 VOID 317 ); 318 319 320/** 321 This service is a wrapper for the PEI Service FfsFindByName(), except the pointer to the PEI Services 322 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 323 Specification for details. 324 325 @param FileName A pointer to the name of the file to 326 find within the firmware volume. 327 328 @param VolumeHandle The firmware volume to search FileHandle 329 Upon exit, points to the found file's 330 handle or NULL if it could not be found. 331 @param FileHandle Pointer to found file handle 332 333 @retval EFI_SUCCESS File was found. 334 335 @retval EFI_NOT_FOUND File was not found. 336 337 @retval EFI_INVALID_PARAMETER VolumeHandle or FileHandle or 338 FileName was NULL. 339 340**/ 341EFI_STATUS 342EFIAPI 343PeiServicesFfsFindFileByName ( 344 IN CONST EFI_GUID *FileName, 345 IN CONST EFI_PEI_FV_HANDLE VolumeHandle, 346 OUT EFI_PEI_FILE_HANDLE *FileHandle 347 ); 348 349 350/** 351 This service is a wrapper for the PEI Service FfsGetFileInfo(), except the pointer to the PEI Services 352 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 353 Specification for details. 354 355 @param FileHandle Handle of the file. 356 357 @param FileInfo Upon exit, points to the file's 358 information. 359 360 @retval EFI_SUCCESS File information returned. 361 362 @retval EFI_INVALID_PARAMETER If FileHandle does not 363 represent a valid file. 364 365 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 366 367**/ 368EFI_STATUS 369EFIAPI 370PeiServicesFfsGetFileInfo ( 371 IN CONST EFI_PEI_FILE_HANDLE FileHandle, 372 OUT EFI_FV_FILE_INFO *FileInfo 373 ); 374 375/** 376 This service is a wrapper for the PEI Service FfsGetFileInfo2(), except the pointer to the PEI Services 377 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 378 Specification for details. 379 380 @param FileHandle Handle of the file. 381 382 @param FileInfo Upon exit, points to the file's 383 information. 384 385 @retval EFI_SUCCESS File information returned. 386 387 @retval EFI_INVALID_PARAMETER If FileHandle does not 388 represent a valid file. 389 390 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 391 392**/ 393EFI_STATUS 394EFIAPI 395PeiServicesFfsGetFileInfo2 ( 396 IN CONST EFI_PEI_FILE_HANDLE FileHandle, 397 OUT EFI_FV_FILE_INFO2 *FileInfo 398 ); 399 400/** 401 This service is a wrapper for the PEI Service FfsGetVolumeInfo(), except the pointer to the PEI Services 402 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 403 Specification for details. 404 405 @param VolumeHandle Handle of the volume. 406 407 @param VolumeInfo Upon exit, points to the volume's 408 information. 409 410 @retval EFI_SUCCESS File information returned. 411 412 @retval EFI_INVALID_PARAMETER If FileHandle does not 413 represent a valid file. 414 415 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 416 417**/ 418EFI_STATUS 419EFIAPI 420PeiServicesFfsGetVolumeInfo ( 421 IN EFI_PEI_FV_HANDLE VolumeHandle, 422 OUT EFI_FV_INFO *VolumeInfo 423 ); 424 425 426/** 427 This service is a wrapper for the PEI Service RegisterForShadow(), except the pointer to the PEI Services 428 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 429 Specification for details. 430 431 @param FileHandle PEIM's file handle. Must be the currently 432 executing PEIM. 433 434 @retval EFI_SUCCESS The PEIM was successfully registered for 435 shadowing. 436 437 @retval EFI_ALREADY_STARTED The PEIM was previously 438 registered for shadowing. 439 440 @retval EFI_NOT_FOUND The FileHandle does not refer to a 441 valid file handle. 442**/ 443EFI_STATUS 444EFIAPI 445PeiServicesRegisterForShadow ( 446 IN EFI_PEI_FILE_HANDLE FileHandle 447 ); 448 449/** 450 Install a EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance so the PEI Core will be notified about a new firmware volume. 451 452 This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO_PPI using 453 the parameters passed in to initialize the fields of the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance. 454 If the resources can not be allocated for EFI_PEI_FIRMWARE_VOLUME_INFO_PPI, then ASSERT(). 455 If the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI can not be installed, then ASSERT(). 456 457 458 @param FvFormat Unique identifier of the format of the memory-mapped firmware volume. 459 This parameter is optional and may be NULL. 460 If NULL is specified, the EFI_FIRMWARE_FILE_SYSTEM2_GUID format is assumed. 461 @param FvInfo Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. 462 The format of this buffer is specific to the FvFormat. For memory-mapped firmware volumes, 463 this typically points to the first byte of the firmware volume. 464 @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped firmware volumes, 465 this is typically the size of the firmware volume. 466 @param ParentFvName If the new firmware volume originated from a file in a different firmware volume, 467 then this parameter specifies the GUID name of the originating firmware volume. 468 Otherwise, this parameter must be NULL. 469 @param ParentFileName If the new firmware volume originated from a file in a different firmware volume, 470 then this parameter specifies the GUID file name of the originating firmware file. 471 Otherwise, this parameter must be NULL. 472**/ 473VOID 474EFIAPI 475PeiServicesInstallFvInfoPpi ( 476 IN CONST EFI_GUID *FvFormat, OPTIONAL 477 IN CONST VOID *FvInfo, 478 IN UINT32 FvInfoSize, 479 IN CONST EFI_GUID *ParentFvName, OPTIONAL 480 IN CONST EFI_GUID *ParentFileName OPTIONAL 481 ); 482 483/** 484 Install a EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI instance so the PEI Core will be notified about a new firmware volume. 485 486 This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI using 487 the parameters passed in to initialize the fields of the EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI instance. 488 If the resources can not be allocated for EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI, then ASSERT(). 489 If the EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI can not be installed, then ASSERT(). 490 491 @param FvFormat Unique identifier of the format of the memory-mapped 492 firmware volume. This parameter is optional and 493 may be NULL. If NULL is specified, the 494 EFI_FIRMWARE_FILE_SYSTEM2_GUID format is assumed. 495 @param FvInfo Points to a buffer which allows the 496 EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. 497 The format of this buffer is specific to the FvFormat. 498 For memory-mapped firmware volumes, this typically 499 points to the first byte of the firmware volume. 500 @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped 501 firmware volumes, this is typically the size of 502 the firmware volume. 503 @param ParentFvName If the new firmware volume originated from a file 504 in a different firmware volume, then this parameter 505 specifies the GUID name of the originating firmware 506 volume. Otherwise, this parameter must be NULL. 507 @param ParentFileName If the new firmware volume originated from a file 508 in a different firmware volume, then this parameter 509 specifies the GUID file name of the originating 510 firmware file. Otherwise, this parameter must be NULL. 511 @param AuthenticationStatus Authentication Status 512**/ 513VOID 514EFIAPI 515PeiServicesInstallFvInfo2Ppi ( 516 IN CONST EFI_GUID *FvFormat, OPTIONAL 517 IN CONST VOID *FvInfo, 518 IN UINT32 FvInfoSize, 519 IN CONST EFI_GUID *ParentFvName, OPTIONAL 520 IN CONST EFI_GUID *ParentFileName, OPTIONAL 521 IN UINT32 AuthenticationStatus 522 ); 523 524#endif 525