MdeModulePkg/Core/Pei/PeiMain.h

   1 /** @file
   2
   3 Copyright (c) 2006 - 2007, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   PeiMain.h
  15
  16 Abstract:
  17
  18   Definition of Pei Core Structures and Services
  19
  20 Revision History
  21
  22 **/
  23
  24 #ifndef _PEI_MAIN_H_
  25 #define _PEI_MAIN_H_
  26
  27 #include <PiPei.h>
  28 #include <Ppi/DxeIpl.h>
  29 #include <Ppi/MemoryDiscovered.h>
  30 #include <Ppi/StatusCode.h>
  31 #include <Ppi/Reset.h>
  32 #include <Ppi/FirmwareVolume.h>
  33 #include <Ppi/FirmwareVolumeInfo.h>
  34 #include <Ppi/Decompress.h>
  35 #include <Ppi/GuidedSectionExtraction.h>
  36 #include <Ppi/LoadFile.h>
  37 #include <Ppi/Security2.h>
  38 #include <Ppi/TemporaryRamSupport.h>
  39 #include <Library/DebugLib.h>
  40 #include <Library/PeiCoreEntryPoint.h>
  41 #include <Library/BaseLib.h>
  42 #include <Library/HobLib.h>
  43 #include <Library/PerformanceLib.h>
  44 #include <Library/PeiServicesLib.h>
  45 #include <Library/ReportStatusCodeLib.h>
  46 #include <Library/PeCoffLib.h>
  47 #include <Library/PeCoffGetEntryPointLib.h>
  48 #include <Library/BaseMemoryLib.h>
  49 #include <Library/CacheMaintenanceLib.h>
  50 #include <Library/TimerLib.h>
  51 #include <Library/PcdLib.h>
  52 #include <IndustryStandard/PeImage.h>
  53 #include <Library/PeiServicesTablePointerLib.h>
  54 #include <Library/MemoryAllocationLib.h>
  55 #include <Library/PeiPiLib.h>
  56 #include <Guid/FirmwareFileSystem2.h>
  57 #include <Guid/AprioriFileName.h>
  58
  59 #define PEI_CORE_INTERNAL_FFS_FILE_DISPATCH_TYPE   0xff
  60
  61 //
  62 // Pei Core private data structures
  63 //
  64 typedef union {
  65   EFI_PEI_PPI_DESCRIPTOR      *Ppi;
  66   EFI_PEI_NOTIFY_DESCRIPTOR   *Notify;
  67   VOID                        *Raw;
  68 } PEI_PPI_LIST_POINTERS;
  69
  70 #define MAX_PPI_DESCRIPTORS 64
  71
  72 typedef struct {
  73   INTN                    PpiListEnd;
  74   INTN                    NotifyListEnd;
  75   INTN                    DispatchListEnd;
  76   INTN                    LastDispatchedInstall;
  77   INTN                    LastDispatchedNotify;
  78   PEI_PPI_LIST_POINTERS   PpiListPtrs[MAX_PPI_DESCRIPTORS];
  79 } PEI_PPI_DATABASE;
  80
  81
  82 //
  83 // PEI_CORE_FV_HANDE.PeimState
  84 // Do not change these values as there is code doing math to change states.
  85 // Look for Private->Fv[FvCount].PeimState[PeimCount]++;
  86 //
  87 #define PEIM_STATE_NOT_DISPATCHED         0x00
  88 #define PEIM_STATE_DISPATCHED             0x01
  89 #define PEIM_STATE_REGISITER_FOR_SHADOW   0x02
  90 #define PEIM_STATE_DONE                   0x03
  91
  92 typedef struct {
  93   EFI_FIRMWARE_VOLUME_HEADER          *FvHeader;
  94   UINT8                               PeimState[FixedPcdGet32 (PcdPeiCoreMaxPeimPerFv)];
  95   EFI_PEI_FILE_HANDLE                 FvFileHandles[FixedPcdGet32 (PcdPeiCoreMaxPeimPerFv)];
  96   BOOLEAN                             ScanFv;
  97 } PEI_CORE_FV_HANDLE;
  98
  99 #define CACHE_SETION_MAX_NUMBER       0x10
 100 typedef struct {
 101   EFI_COMMON_SECTION_HEADER*          Section[CACHE_SETION_MAX_NUMBER];
 102   VOID*                               SectionData[CACHE_SETION_MAX_NUMBER];
 103   UINTN                               SectionSize[CACHE_SETION_MAX_NUMBER];
 104   UINTN                               AllSectionCount;
 105   UINTN                               SectionIndex;
 106 } CACHE_SECTION_DATA;
 107
 108 //
 109 // Pei Core private data structure instance
 110 //
 111
 112 #define PEI_CORE_HANDLE_SIGNATURE  EFI_SIGNATURE_32('P','e','i','C')
 113
 114 typedef struct{
 115   UINTN                              Signature;
 116   EFI_PEI_SERVICES                   *PS;     // Point to ServiceTableShadow
 117   PEI_PPI_DATABASE                   PpiData;
 118   UINTN                              FvCount;
 119   PEI_CORE_FV_HANDLE                 Fv[FixedPcdGet32 (PcdPeiCoreMaxFvSupported)];
 120   EFI_PEI_FILE_HANDLE                CurrentFvFileHandles[FixedPcdGet32 (PcdPeiCoreMaxPeimPerFv)];
 121   UINTN                              AprioriCount;
 122   UINTN                              CurrentPeimFvCount;
 123   UINTN                              CurrentPeimCount;
 124   EFI_PEI_FILE_HANDLE                CurrentFileHandle;
 125   UINTN                              AllFvCount;
 126   EFI_PEI_FV_HANDLE                  AllFv[FixedPcdGet32 (PcdPeiCoreMaxFvSupported)];
 127   EFI_PEI_HOB_POINTERS               HobList;
 128   BOOLEAN                            SwitchStackSignal;
 129   BOOLEAN                            PeiMemoryInstalled;
 130   EFI_PHYSICAL_ADDRESS               StackBase;
 131   UINT64                             StackSize;
 132   VOID                               *BottomOfCarHeap;
 133   VOID                               *TopOfCarHeap;
 134   VOID                               *CpuIo;
 135   EFI_PEI_SECURITY2_PPI              *PrivateSecurityPpi;
 136   EFI_PEI_SERVICES                   ServiceTableShadow;
 137   UINTN                              SizeOfTemporaryMemory;
 138   UINTN                              SizeOfCacheAsRam;
 139   VOID                               *MaxTopOfCarHeap;
 140   EFI_PEI_PPI_DESCRIPTOR             *XipLoadFile;
 141   EFI_PHYSICAL_ADDRESS               PhysicalMemoryBegin;
 142   UINT64                             PhysicalMemoryLength;
 143   EFI_PHYSICAL_ADDRESS               FreePhysicalMemoryTop;
 144   VOID*                              ShadowedPeiCore;
 145   CACHE_SECTION_DATA                 CacheSection;
 146 } PEI_CORE_INSTANCE;
 147
 148 //
 149 // Pei Core Instance Data Macros
 150 //
 151
 152 #define PEI_CORE_INSTANCE_FROM_PS_THIS(a) \
 153   CR(a, PEI_CORE_INSTANCE, PS, PEI_CORE_HANDLE_SIGNATURE)
 154
 155 //
 156 // BUGBUG: Where does this go really?
 157 //
 158 typedef
 159 EFI_STATUS
 160 (EFIAPI *PEI_CORE_ENTRY_POINT)(
 161   IN CONST  EFI_SEC_PEI_HAND_OFF    *SecCoreData,
 162   IN CONST  EFI_PEI_PPI_DESCRIPTOR  *PpiList,
 163   IN PEI_CORE_INSTANCE              *OldCoreData
 164   );
 165
 166 //
 167 // Union of temporarily used function pointers (to save stack space)
 168 //
 169 typedef union {
 170   PEI_CORE_ENTRY_POINT         PeiCore;
 171   EFI_PEIM_ENTRY_POINT2        PeimEntry;
 172   EFI_PEIM_NOTIFY_ENTRY_POINT  PeimNotifyEntry;
 173   EFI_DXE_IPL_PPI              *DxeIpl;
 174   EFI_PEI_PPI_DESCRIPTOR       *PpiDescriptor;
 175   EFI_PEI_NOTIFY_DESCRIPTOR    *NotifyDescriptor;
 176   VOID                         *Raw;
 177 } PEI_CORE_TEMP_POINTERS;
 178
 179
 180
 181 typedef struct {
 182   CONST EFI_SEC_PEI_HAND_OFF    *SecCoreData;
 183   EFI_PEI_PPI_DESCRIPTOR        *PpiList;
 184   VOID                          *Data;
 185 } PEI_CORE_PARAMETERS;
 186
 187 //
 188 // PeiCore function
 189 //
 190 EFI_STATUS
 191 EFIAPI
 192 PeiCore (
 193   IN CONST EFI_SEC_PEI_HAND_OFF        *SecCoreData,
 194   IN CONST EFI_PEI_PPI_DESCRIPTOR      *PpList,
 195   IN VOID                              *Data
 196   )
 197 /*++
 198
 199 Routine Description:
 200
 201   The entry routine to Pei Core, invoked by PeiMain during transition
 202   from SEC to PEI. After switching stack in the PEI core, it will restart
 203   with the old core data.
 204
 205 Arguments:
 206
 207   PeiStartupDescriptor - Information and services provided by SEC phase.
 208   OldCoreData          - Pointer to old core data that is used to initialize the
 209                          core's data areas.
 210
 211 Returns:
 212
 213   This function never returns
 214   EFI_NOT_FOUND        - Never reach
 215
 216 --*/
 217 ;
 218
 219 //
 220 // Dispatcher support functions
 221 //
 222
 223 BOOLEAN
 224 PeimDispatchReadiness (
 225   IN EFI_PEI_SERVICES   **PeiServices,
 226   IN VOID               *DependencyExpression
 227   )
 228 /*++
 229
 230 Routine Description:
 231
 232   This is the POSTFIX version of the dependency evaluator.  When a
 233   PUSH [PPI GUID] is encountered, a pointer to the GUID is stored on
 234   the evaluation stack.  When that entry is poped from the evaluation
 235   stack, the PPI is checked if it is installed.  This method allows
 236   some time savings as not all PPIs must be checked for certain
 237   operation types (AND, OR).
 238
 239 Arguments:
 240
 241   PeiServices               - Calling context.
 242
 243   DependencyExpression      - Pointer to a dependency expression.  The Grammar adheres to
 244                               the BNF described above and is stored in postfix notation.
 245
 246 Returns:
 247
 248   Status = EFI_SUCCESS            if it is a well-formed Grammar
 249            EFI_INVALID_PARAMETER  if the dependency expression overflows
 250                                   the evaluation stack
 251            EFI_INVALID_PARAMETER  if the dependency expression underflows
 252                                   the evaluation stack
 253            EFI_INVALID_PARAMETER  if the dependency expression is not a
 254                                   well-formed Grammar.
 255 --*/
 256 ;
 257
 258
 259 VOID
 260 PeiDispatcher (
 261   IN CONST EFI_SEC_PEI_HAND_OFF  *SecCoreData,
 262   IN PEI_CORE_INSTANCE           *PrivateData
 263   )
 264
 265 /*++
 266
 267 Routine Description:
 268
 269   Conduct PEIM dispatch.
 270
 271 Arguments:
 272
 273   PeiStartupDescriptor - Pointer to IN EFI_PEI_STARTUP_DESCRIPTOR
 274   PrivateData          - Pointer to the private data passed in from caller
 275   DispatchData         - Pointer to PEI_CORE_DISPATCH_DATA data.
 276
 277 Returns:
 278
 279   EFI_SUCCESS   - Successfully dispatched PEIM.
 280   EFI_NOT_FOUND - The dispatch failed.
 281
 282 --*/
 283 ;
 284
 285
 286 VOID
 287 InitializeDispatcherData (
 288   IN PEI_CORE_INSTANCE            *PrivateData,
 289   IN PEI_CORE_INSTANCE            *OldCoreData,
 290   IN CONST EFI_SEC_PEI_HAND_OFF   *SecCoreData
 291   )
 292 /*++
 293
 294 Routine Description:
 295
 296   Initialize the Dispatcher's data members
 297
 298 Arguments:
 299
 300   PeiServices          - The PEI core services table.
 301   OldCoreData          - Pointer to old core data (before switching stack).
 302                          NULL if being run in non-permament memory mode.
 303   PeiStartupDescriptor - Information and services provided by SEC phase.
 304
 305
 306 Returns:
 307
 308   None
 309
 310 --*/
 311 ;
 312
 313
 314 EFI_STATUS
 315 FindNextPeim (
 316   IN EFI_PEI_SERVICES            **PeiServices,
 317   IN EFI_FIRMWARE_VOLUME_HEADER  *FwVolHeader,
 318   IN OUT EFI_FFS_FILE_HEADER     **PeimFileHeader
 319   )
 320 /*++
 321
 322 Routine Description:
 323     Given the input file pointer, search for the next matching file in the
 324     FFS volume. The search starts from FileHeader inside
 325     the Firmware Volume defined by FwVolHeader.
 326
 327 Arguments:
 328     PeiServices - Pointer to the PEI Core Services Table.
 329
 330     FwVolHeader - Pointer to the FV header of the volume to search.
 331                      This parameter must point to a valid FFS volume.
 332
 333     PeimFileHeader  - Pointer to the current file from which to begin searching.
 334                   This pointer will be updated upon return to reflect the file found.
 335
 336 Returns:
 337     EFI_NOT_FOUND - No files matching the search criteria were found
 338     EFI_SUCCESS
 339
 340 --*/
 341 ;
 342
 343 BOOLEAN
 344 Dispatched (
 345   IN UINT8  CurrentPeim,
 346   IN UINT32 DispatchedPeimBitMap
 347   )
 348 /*++
 349
 350 Routine Description:
 351
 352   This routine checks to see if a particular PEIM has been dispatched during
 353   the PEI core dispatch.
 354
 355 Arguments:
 356   CurrentPeim - The PEIM/FV in the bit array to check.
 357   DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
 358
 359 Returns:
 360   TRUE if PEIM already dispatched
 361   FALSE if not
 362
 363 --*/
 364 ;
 365
 366 VOID
 367 SetDispatched (
 368   IN EFI_PEI_SERVICES   **PeiServices,
 369   IN UINT8              CurrentPeim,
 370   OUT UINT32            *DispatchedPeimBitMap
 371   )
 372 /*++
 373
 374 Routine Description:
 375
 376   This routine sets a PEIM as having been dispatched once its entry
 377   point has been invoked.
 378
 379 Arguments:
 380
 381   PeiServices          - The PEI core services table.
 382   CurrentPeim          - The PEIM/FV in the bit array to check.
 383   DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
 384
 385 Returns:
 386   None
 387
 388 --*/
 389 ;
 390
 391 BOOLEAN
 392 DepexSatisfied (
 393   IN PEI_CORE_INSTANCE          *Private,
 394   IN EFI_PEI_FILE_HANDLE        FileHandle,
 395   IN UINTN                      PeimCount
 396   )
 397 /*++
 398
 399 Routine Description:
 400
 401   This routine parses the Dependency Expression, if available, and
 402   decides if the module can be executed.
 403
 404 Arguments:
 405   PeiServices - The PEI Service Table
 406   CurrentPeimAddress - Address of the PEIM Firmware File under investigation
 407
 408 Returns:
 409   TRUE  - Can be dispatched
 410   FALSE - Cannot be dispatched
 411
 412 --*/
 413 ;
 414
 415 //
 416 // PPI support functions
 417 //
 418 VOID
 419 InitializePpiServices (
 420   IN PEI_CORE_INSTANCE   *PrivateData,
 421   IN PEI_CORE_INSTANCE   *OldCoreData
 422   )
 423 /*++
 424
 425 Routine Description:
 426
 427   Initialize PPI services.
 428
 429 Arguments:
 430
 431   PeiServices - The PEI core services table.
 432   OldCoreData - Pointer to the PEI Core data.
 433                 NULL if being run in non-permament memory mode.
 434
 435 Returns:
 436   Nothing
 437
 438 --*/
 439 ;
 440
 441 VOID
 442 ConvertPpiPointers (
 443   IN CONST EFI_PEI_SERVICES                     **PeiServices,
 444   IN UINTN                         OldCheckingBottom,
 445   IN UINTN                         OldCheckingTop,
 446   IN EFI_HOB_HANDOFF_INFO_TABLE    *NewHandOffHob
 447   )
 448 /*++
 449
 450 Routine Description:
 451
 452   Migrate the Hob list from the CAR stack to PEI installed memory.
 453
 454 Arguments:
 455
 456   PeiServices       - The PEI core services table.
 457   OldCheckingBottom - The old checking bottom.
 458   OldCheckingTop    - The old checking top.
 459   NewHandOffHob     - The new handoff HOB list.
 460
 461 Returns:
 462
 463 --*/
 464 ;
 465
 466 EFI_STATUS
 467 EFIAPI
 468 PeiInstallPpi (
 469   IN CONST EFI_PEI_SERVICES        **PeiServices,
 470   IN CONST EFI_PEI_PPI_DESCRIPTOR  *PpiList
 471   )
 472 /*++
 473
 474 Routine Description:
 475
 476   Install PPI services.
 477
 478 Arguments:
 479
 480   PeiServices - Pointer to the PEI Service Table
 481   PpiList     - Pointer to a list of PEI PPI Descriptors.
 482
 483 Returns:
 484
 485     EFI_SUCCESS             - if all PPIs in PpiList are successfully installed.
 486     EFI_INVALID_PARAMETER   - if PpiList is NULL pointer
 487     EFI_INVALID_PARAMETER   - if any PPI in PpiList is not valid
 488     EFI_OUT_OF_RESOURCES    - if there is no more memory resource to install PPI
 489
 490 --*/
 491 ;
 492
 493 EFI_STATUS
 494 EFIAPI
 495 PeiReInstallPpi (
 496   IN CONST EFI_PEI_SERVICES        **PeiServices,
 497   IN CONST EFI_PEI_PPI_DESCRIPTOR  *OldPpi,
 498   IN CONST EFI_PEI_PPI_DESCRIPTOR  *NewPpi
 499   )
 500 /*++
 501
 502 Routine Description:
 503
 504   Re-Install PPI services.
 505
 506 Arguments:
 507
 508   PeiServices - Pointer to the PEI Service Table
 509   OldPpi      - Pointer to the old PEI PPI Descriptors.
 510   NewPpi      - Pointer to the new PEI PPI Descriptors.
 511
 512 Returns:
 513
 514   EFI_SUCCESS           - if the operation was successful
 515   EFI_INVALID_PARAMETER - if OldPpi or NewPpi is NULL
 516   EFI_INVALID_PARAMETER - if NewPpi is not valid
 517   EFI_NOT_FOUND         - if the PPI was not in the database
 518
 519 --*/
 520 ;
 521
 522 EFI_STATUS
 523 EFIAPI
 524 PeiLocatePpi (
 525   IN CONST EFI_PEI_SERVICES            **PeiServices,
 526   IN CONST EFI_GUID                    *Guid,
 527   IN UINTN                       Instance,
 528   IN OUT EFI_PEI_PPI_DESCRIPTOR  **PpiDescriptor,
 529   IN OUT VOID                    **Ppi
 530   )
 531 /*++
 532
 533 Routine Description:
 534
 535   Locate a given named PPI.
 536
 537 Arguments:
 538
 539   PeiServices   - Pointer to the PEI Service Table
 540   Guid          - Pointer to GUID of the PPI.
 541   Instance      - Instance Number to discover.
 542   PpiDescriptor - Pointer to reference the found descriptor. If not NULL,
 543                 returns a pointer to the descriptor (includes flags, etc)
 544   Ppi           - Pointer to reference the found PPI
 545
 546 Returns:
 547
 548   Status -  EFI_SUCCESS   if the PPI is in the database
 549             EFI_NOT_FOUND if the PPI is not in the database
 550 --*/
 551 ;
 552
 553 EFI_STATUS
 554 EFIAPI
 555 PeiNotifyPpi (
 556   IN CONST EFI_PEI_SERVICES           **PeiServices,
 557   IN CONST EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyList
 558   )
 559 /*++
 560
 561 Routine Description:
 562
 563   Install a notification for a given PPI.
 564
 565 Arguments:
 566
 567   PeiServices - Pointer to the PEI Service Table
 568   NotifyList  - Pointer to list of Descriptors to notify upon.
 569
 570 Returns:
 571
 572   Status - EFI_SUCCESS          if successful
 573            EFI_OUT_OF_RESOURCES if no space in the database
 574            EFI_INVALID_PARAMETER if not a good decriptor
 575
 576 --*/
 577 ;
 578
 579 VOID
 580 ProcessNotifyList (
 581   IN PEI_CORE_INSTANCE  *PrivateData
 582   )
 583 /*++
 584
 585 Routine Description:
 586
 587   Process the Notify List at dispatch level.
 588
 589 Arguments:
 590
 591   PeiServices - Pointer to the PEI Service Table
 592
 593 Returns:
 594
 595 --*/
 596 ;
 597
 598 VOID
 599 DispatchNotify (
 600   IN PEI_CORE_INSTANCE  *PrivateData,
 601   IN UINTN               NotifyType,
 602   IN INTN                InstallStartIndex,
 603   IN INTN                InstallStopIndex,
 604   IN INTN                NotifyStartIndex,
 605   IN INTN                NotifyStopIndex
 606   )
 607 /*++
 608
 609 Routine Description:
 610
 611   Dispatch notifications.
 612
 613 Arguments:
 614
 615   PeiServices         - Pointer to the PEI Service Table
 616   NotifyType          - Type of notify to fire.
 617   InstallStartIndex   - Install Beginning index.
 618   InstallStopIndex    - Install Ending index.
 619   NotifyStartIndex    - Notify Beginning index.
 620   NotifyStopIndex    - Notify Ending index.
 621
 622 Returns:  None
 623
 624 --*/
 625 ;
 626
 627 //
 628 // Boot mode support functions
 629 //
 630 EFI_STATUS
 631 EFIAPI
 632 PeiGetBootMode (
 633   IN CONST EFI_PEI_SERVICES  **PeiServices,
 634   IN OUT EFI_BOOT_MODE *BootMode
 635   )
 636 /*++
 637
 638 Routine Description:
 639
 640   This service enables PEIMs to ascertain the present value of the boot mode.
 641
 642 Arguments:
 643
 644   PeiServices    - The PEI core services table.
 645   BootMode       - A pointer to contain the value of the boot mode.
 646
 647 Returns:
 648
 649   EFI_SUCCESS           - The boot mode was returned successfully.
 650   EFI_INVALID_PARAMETER - BootMode is NULL.
 651
 652 --*/
 653 ;
 654
 655 EFI_STATUS
 656 EFIAPI
 657 PeiSetBootMode (
 658   IN CONST EFI_PEI_SERVICES  **PeiServices,
 659   IN EFI_BOOT_MODE     BootMode
 660   )
 661 /*++
 662
 663 Routine Description:
 664
 665   This service enables PEIMs to update the boot mode variable.
 666
 667 Arguments:
 668
 669   PeiServices    - The PEI core services table.
 670   BootMode       - The value of the boot mode to set.
 671
 672 Returns:
 673
 674   EFI_SUCCESS    - The value was successfully updated
 675
 676 --*/
 677 ;
 678
 679 //
 680 // Security support functions
 681 //
 682 VOID
 683 InitializeSecurityServices (
 684   IN EFI_PEI_SERVICES  **PeiServices,
 685   IN PEI_CORE_INSTANCE *OldCoreData
 686   )
 687 /*++
 688
 689 Routine Description:
 690
 691   Initialize the security services.
 692
 693 Arguments:
 694
 695   PeiServices - The PEI core services table.
 696   OldCoreData - Pointer to the old core data.
 697                 NULL if being run in non-permament memory mode.
 698 Returns:
 699
 700   None
 701
 702 --*/
 703 ;
 704
 705 EFI_STATUS
 706 VerifyFv (
 707   IN EFI_FIRMWARE_VOLUME_HEADER  *CurrentFvAddress
 708   )
 709 /*++
 710
 711 Routine Description:
 712
 713   Provide a callout to the OEM FV verification service.
 714
 715 Arguments:
 716
 717   CurrentFvAddress       - Pointer to the FV under investigation.
 718
 719 Returns:
 720
 721   Status - EFI_SUCCESS
 722
 723 --*/
 724 ;
 725
 726
 727 EFI_STATUS
 728 VerifyPeim (
 729   IN PEI_CORE_INSTANCE      *PrivateData,
 730   IN EFI_PEI_FV_HANDLE      VolumeHandle,
 731   IN EFI_PEI_FILE_HANDLE    FileHandle
 732   )
 733 /*++
 734
 735 Routine Description:
 736
 737   Provide a callout to the security verification service.
 738
 739 Arguments:
 740
 741   PeiServices          - The PEI core services table.
 742   CurrentPeimAddress   - Pointer to the Firmware File under investigation.
 743
 744 Returns:
 745
 746   EFI_SUCCESS             - Image is OK
 747   EFI_SECURITY_VIOLATION  - Image is illegal
 748
 749 --*/
 750 ;
 751
 752
 753 EFI_STATUS
 754 EFIAPI
 755 PeiGetHobList (
 756   IN CONST EFI_PEI_SERVICES  **PeiServices,
 757   IN OUT VOID          **HobList
 758   )
 759 /*++
 760
 761 Routine Description:
 762
 763   Gets the pointer to the HOB List.
 764
 765 Arguments:
 766
 767   PeiServices - The PEI core services table.
 768   HobList     - Pointer to the HOB List.
 769
 770 Returns:
 771
 772   EFI_SUCCESS                 - Get the pointer of HOB List
 773   EFI_NOT_AVAILABLE_YET       - the HOB List is not yet published
 774   EFI_INVALID_PARAMETER       - HobList is NULL (in debug mode)
 775
 776 --*/
 777 ;
 778
 779 EFI_STATUS
 780 EFIAPI
 781 PeiCreateHob (
 782   IN CONST EFI_PEI_SERVICES  **PeiServices,
 783   IN UINT16            Type,
 784   IN UINT16            Length,
 785   IN OUT VOID          **Hob
 786   )
 787 /*++
 788
 789 Routine Description:
 790
 791   Add a new HOB to the HOB List.
 792
 793 Arguments:
 794
 795   PeiServices - The PEI core services table.
 796   Type        - Type of the new HOB.
 797   Length      - Length of the new HOB to allocate.
 798   Hob         - Pointer to the new HOB.
 799
 800 Returns:
 801
 802   Status  - EFI_SUCCESS
 803           - EFI_INVALID_PARAMETER if Hob is NULL
 804           - EFI_NOT_AVAILABLE_YET if HobList is still not available.
 805           - EFI_OUT_OF_RESOURCES if there is no more memory to grow the Hoblist.
 806
 807 --*/
 808 ;
 809
 810 EFI_STATUS
 811 PeiCoreBuildHobHandoffInfoTable (
 812   IN EFI_BOOT_MODE         BootMode,
 813   IN EFI_PHYSICAL_ADDRESS  MemoryBegin,
 814   IN UINT64                MemoryLength
 815   )
 816 /*++
 817
 818 Routine Description:
 819
 820   Builds a Handoff Information Table HOB
 821
 822 Arguments:
 823
 824   BootMode      - Current Bootmode
 825   MemoryBegin   - Start Memory Address.
 826   MemoryLength  - Length of Memory.
 827
 828 Returns:
 829
 830   EFI_SUCCESS
 831
 832 --*/
 833 ;
 834
 835
 836 //
 837 // FFS Fw Volume support functions
 838 //
 839 EFI_STATUS
 840 EFIAPI
 841 PeiFfsFindNextFile (
 842   IN CONST EFI_PEI_SERVICES      **PeiServices,
 843   IN UINT8                       SearchType,
 844   IN EFI_PEI_FV_HANDLE           FwVolHeader,
 845   IN OUT EFI_PEI_FILE_HANDLE     *FileHeader
 846   )
 847 /*++
 848
 849 Routine Description:
 850     Given the input file pointer, search for the next matching file in the
 851     FFS volume as defined by SearchType. The search starts from FileHeader inside
 852     the Firmware Volume defined by FwVolHeader.
 853
 854 Arguments:
 855     PeiServices - Pointer to the PEI Core Services Table.
 856
 857     SearchType - Filter to find only files of this type.
 858       Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
 859
 860     FwVolHeader - Pointer to the FV header of the volume to search.
 861       This parameter must point to a valid FFS volume.
 862
 863     FileHeader  - Pointer to the current file from which to begin searching.
 864       This pointer will be updated upon return to reflect the file found.
 865
 866 Returns:
 867     EFI_NOT_FOUND - No files matching the search criteria were found
 868     EFI_SUCCESS
 869
 870 --*/
 871 ;
 872
 873 EFI_STATUS
 874 EFIAPI
 875 PeiFfsFindSectionData (
 876   IN CONST EFI_PEI_SERVICES      **PeiServices,
 877   IN EFI_SECTION_TYPE            SectionType,
 878   IN EFI_PEI_FILE_HANDLE         FfsFileHeader,
 879   IN OUT VOID                    **SectionData
 880   )
 881 /*++
 882
 883 Routine Description:
 884     Given the input file pointer, search for the next matching section in the
 885     FFS volume.
 886
 887 Arguments:
 888     PeiServices - Pointer to the PEI Core Services Table.
 889     SearchType - Filter to find only sections of this type.
 890     FfsFileHeader  - Pointer to the current file to search.
 891     SectionData - Pointer to the Section matching SectionType in FfsFileHeader.
 892                 - NULL if section not found
 893
 894 Returns:
 895     EFI_NOT_FOUND - No files matching the search criteria were found
 896     EFI_SUCCESS
 897
 898 --*/
 899 ;
 900
 901 EFI_STATUS
 902 EFIAPI
 903 PeiFvFindNextVolume (
 904   IN CONST EFI_PEI_SERVICES                **PeiServices,
 905   IN UINTN                           Instance,
 906   IN OUT EFI_PEI_FV_HANDLE           *FwVolHeader
 907   )
 908 /*++
 909
 910 Routine Description:
 911
 912   Return the BFV location
 913
 914   BugBug -- Move this to the location of this code to where the
 915   other FV and FFS support code lives.
 916   Also, update to use FindFV for instances #'s >= 1.
 917
 918 Arguments:
 919
 920   PeiServices - The PEI core services table.
 921   Instance    - Instance of FV to find
 922   FwVolHeader - Pointer to contain the data to return
 923
 924 Returns:
 925   Pointer to the Firmware Volume instance requested
 926
 927   EFI_INVALID_PARAMETER     - FwVolHeader is NULL
 928
 929   EFI_SUCCESS               - Firmware volume instance successfully found.
 930
 931 --*/
 932 ;
 933
 934 //
 935 // Memory support functions
 936 //
 937 VOID
 938 InitializeMemoryServices (
 939   IN PEI_CORE_INSTANCE           *PrivateData,
 940   IN CONST EFI_SEC_PEI_HAND_OFF  *SecCoreData,
 941   IN PEI_CORE_INSTANCE           *OldCoreData
 942   )
 943 /*++
 944
 945 Routine Description:
 946
 947   Initialize the memory services.
 948
 949 Arguments:
 950
 951   PeiServices          - The PEI core services table.
 952   PeiStartupDescriptor - Information and services provided by SEC phase.
 953   OldCoreData          - Pointer to the PEI Core data.
 954                          NULL if being run in non-permament memory mode.
 955
 956 Returns:
 957
 958   None
 959
 960 --*/
 961 ;
 962
 963 EFI_STATUS
 964 EFIAPI
 965 PeiInstallPeiMemory (
 966   IN CONST EFI_PEI_SERVICES      **PeiServices,
 967   IN EFI_PHYSICAL_ADDRESS  MemoryBegin,
 968   IN UINT64                MemoryLength
 969   )
 970 /*++
 971
 972 Routine Description:
 973
 974   Install the permanent memory is now available.
 975   Creates HOB (PHIT and Stack).
 976
 977 Arguments:
 978
 979   PeiServices   - The PEI core services table.
 980   MemoryBegin   - Start of memory address.
 981   MemoryLength  - Length of memory.
 982
 983 Returns:
 984
 985   Status  - EFI_SUCCESS
 986
 987 --*/
 988 ;
 989
 990 EFI_STATUS
 991 EFIAPI
 992 PeiAllocatePages (
 993   IN CONST EFI_PEI_SERVICES           **PeiServices,
 994   IN EFI_MEMORY_TYPE            MemoryType,
 995   IN UINTN                      Pages,
 996   OUT EFI_PHYSICAL_ADDRESS      *Memory
 997   )
 998 /*++
 999
1000 Routine Description:
1001
1002   Memory allocation service on permanent memory,
1003   not usable prior to the memory installation.
1004
1005 Arguments:
1006
1007   PeiServices - The PEI core services table.
1008   Type        - Type of allocation.
1009   MemoryType  - Type of memory to allocate.
1010   Pages       - Number of pages to allocate.
1011   Memory      - Pointer of memory allocated.
1012
1013 Returns:
1014
1015   Status - EFI_SUCCESS              The allocation was successful
1016            EFI_INVALID_PARAMETER    Only AllocateAnyAddress is supported.
1017            EFI_NOT_AVAILABLE_YET    Called with permanent memory not available
1018            EFI_OUT_OF_RESOURCES     There is not enough HOB heap to satisfy the requirement
1019                                     to allocate the number of pages.
1020
1021 --*/
1022 ;
1023
1024 EFI_STATUS
1025 EFIAPI
1026 PeiAllocatePool (
1027   IN CONST EFI_PEI_SERVICES           **PeiServices,
1028   IN UINTN                      Size,
1029   OUT VOID                      **Buffer
1030   )
1031 /*++
1032
1033 Routine Description:
1034
1035   Memory allocation service on the CAR.
1036
1037 Arguments:
1038
1039   PeiServices - The PEI core services table.
1040
1041   Size        - Amount of memory required
1042
1043   Buffer      - Address of pointer to the buffer
1044
1045 Returns:
1046
1047   Status - EFI_SUCCESS              The allocation was successful
1048            EFI_OUT_OF_RESOURCES     There is not enough heap to satisfy the requirement
1049                                     to allocate the requested size.
1050
1051 --*/
1052 ;
1053
1054 EFI_STATUS
1055 PeiLoadImage (
1056   IN  EFI_PEI_SERVICES            **PeiServices,
1057   IN  EFI_PEI_FILE_HANDLE         FileHandle,
1058   OUT    EFI_PHYSICAL_ADDRESS     *EntryPoint,
1059   OUT    UINT32                   *AuthenticationState
1060   )
1061 /*++
1062
1063 Routine Description:
1064
1065   Get entry point of a Peim file.
1066
1067 Arguments:
1068
1069   PeiServices                 - Calling context.
1070
1071   PeimFileHeader              - Peim file's header.
1072
1073   EntryPoint                  - Entry point of that Peim file.
1074
1075 Returns:
1076
1077   Status code.
1078
1079 --*/
1080 ;
1081
1082
1083 EFI_STATUS
1084 EFIAPI
1085 PeiReportStatusCode (
1086   IN CONST EFI_PEI_SERVICES         **PeiServices,
1087   IN EFI_STATUS_CODE_TYPE     CodeType,
1088   IN EFI_STATUS_CODE_VALUE    Value,
1089   IN UINT32                   Instance,
1090   IN CONST EFI_GUID                 *CallerId,
1091   IN CONST EFI_STATUS_CODE_DATA     *Data OPTIONAL
1092   )
1093 /*++
1094
1095 Routine Description:
1096
1097   Core version of the Status Code reporter
1098
1099 Arguments:
1100
1101   PeiServices - The PEI core services table.
1102
1103   CodeType    - Type of Status Code.
1104
1105   Value       - Value to output for Status Code.
1106
1107   Instance    - Instance Number of this status code.
1108
1109   CallerId    - ID of the caller of this status code.
1110
1111   Data        - Optional data associated with this status code.
1112
1113 Returns:
1114
1115   Status  - EFI_SUCCESS             if status code is successfully reported
1116           - EFI_NOT_AVAILABLE_YET   if StatusCodePpi has not been installed
1117
1118 --*/
1119 ;
1120
1121
1122 EFI_STATUS
1123 EFIAPI
1124 PeiResetSystem (
1125   IN CONST EFI_PEI_SERVICES   **PeiServices
1126   )
1127 /*++
1128
1129 Routine Description:
1130
1131   Core version of the Reset System
1132
1133 Arguments:
1134
1135   PeiServices - The PEI core services table.
1136
1137 Returns:
1138
1139   Status  - EFI_NOT_AVAILABLE_YET. PPI not available yet.
1140           - EFI_DEVICE_ERROR.   Did not reset system.
1141
1142   Otherwise, resets the system.
1143
1144 --*/
1145 ;
1146
1147 VOID
1148 PeiInitializeFv (
1149   IN  PEI_CORE_INSTANCE           *PrivateData,
1150   IN CONST EFI_SEC_PEI_HAND_OFF   *SecCoreData
1151   )
1152 /*++
1153
1154 Routine Description:
1155
1156   Initialize PeiCore Fv List.
1157
1158 Arguments:
1159   PrivateData     - Pointer to PEI_CORE_INSTANCE.
1160   SecCoreData     - Pointer to EFI_SEC_PEI_HAND_OFF.
1161
1162 Returns:
1163   NONE
1164
1165 --*/
1166 ;
1167
1168 EFI_STATUS
1169 EFIAPI
1170 FirmwareVolmeInfoPpiNotifyCallback (
1171   IN EFI_PEI_SERVICES              **PeiServices,
1172   IN EFI_PEI_NOTIFY_DESCRIPTOR     *NotifyDescriptor,
1173   IN VOID                          *Ppi
1174   )
1175 /*++
1176
1177 Routine Description:
1178
1179   Process Firmware Volum Information once FvInfoPPI install.
1180
1181 Arguments:
1182
1183   PeiServices - General purpose services available to every PEIM.
1184
1185 Returns:
1186
1187   Status -  EFI_SUCCESS if the interface could be successfully
1188             installed
1189
1190 --*/
1191 ;
1192
1193
1194 EFI_STATUS
1195 EFIAPI
1196 PeiFfsFindFileByName (
1197   IN  CONST EFI_GUID        *FileName,
1198   IN  EFI_PEI_FV_HANDLE     VolumeHandle,
1199   OUT EFI_PEI_FILE_HANDLE   *FileHandle
1200   )
1201 /*++
1202
1203 Routine Description:
1204
1205   Given the input VolumeHandle, search for the next matching name file.
1206
1207 Arguments:
1208
1209   FileName      - File name to search.
1210   VolumeHandle  - The current FV to search.
1211   FileHandle    - Pointer to the file matching name in VolumeHandle.
1212                 - NULL if file not found
1213 Returns:
1214   EFI_STATUS
1215
1216 --*/
1217 ;
1218
1219
1220 EFI_STATUS
1221 EFIAPI
1222 PeiFfsGetFileInfo (
1223   IN EFI_PEI_FILE_HANDLE  FileHandle,
1224   OUT EFI_FV_FILE_INFO    *FileInfo
1225   )
1226 /*++
1227
1228 Routine Description:
1229
1230   Collect information of given file.
1231
1232 Arguments:
1233   FileHandle   - The handle to file.
1234   FileInfo     - Pointer to the file information.
1235
1236 Returns:
1237   EFI_STATUS
1238
1239 --*/
1240 ;
1241
1242 EFI_STATUS
1243 EFIAPI
1244 PeiFfsGetVolumeInfo (
1245   IN EFI_PEI_FV_HANDLE  VolumeHandle,
1246   OUT EFI_FV_INFO       *VolumeInfo
1247   )
1248 /*++
1249
1250 Routine Description:
1251
1252   Collect information of given Fv Volume.
1253
1254 Arguments:
1255   VolumeHandle    - The handle to Fv Volume.
1256   VolumeInfo      - The pointer to volume information.
1257
1258 Returns:
1259   EFI_STATUS
1260
1261 --*/
1262 ;
1263
1264
1265 EFI_STATUS
1266 EFIAPI
1267 PeiRegisterForShadow (
1268   IN EFI_PEI_FILE_HANDLE       FileHandle
1269   )
1270 /*++
1271
1272 Routine Description:
1273
1274   This routine enable a PEIM to register itself to shadow when PEI Foundation
1275   discovery permanent memory.
1276
1277 Arguments:
1278   FileHandle  - File handle of a PEIM.
1279
1280 Returns:
1281   EFI_NOT_FOUND        - The file handle doesn't point to PEIM itself.
1282   EFI_ALREADY_STARTED  - Indicate that the PEIM has been registered itself.
1283   EFI_SUCCESS          - Successfully to register itself.
1284
1285 --*/
1286 ;
1287
1288
1289 /**
1290   This routine enable a PEIM to register itself to shadow when PEI Foundation
1291   discovery permanent memory.
1292
1293         @param FileHandle       File handle of a PEIM.
1294
1295   @retval EFI_NOT_FOUND                                 The file handle doesn't point to PEIM itself.
1296   @retval EFI_ALREADY_STARTED           Indicate that the PEIM has been registered itself.
1297   @retval EFI_SUCCESS                                           Successfully to register itself.
1298
1299 **/
1300 EFI_STATUS
1301 EFIAPI
1302 PeiRegisterForShadow (
1303   IN EFI_PEI_FILE_HANDLE       FileHandle
1304   )
1305 ;
1306
1307 EFI_STATUS
1308 PeiFindFileEx (
1309   IN  CONST EFI_PEI_FV_HANDLE        FvHandle,
1310   IN  CONST EFI_GUID                 *FileName,   OPTIONAL
1311   IN        EFI_FV_FILETYPE          SearchType,
1312   IN OUT    EFI_PEI_FILE_HANDLE      *FileHandle,
1313   IN OUT    EFI_PEI_FV_HANDLE        *AprioriFile  OPTIONAL
1314   )
1315 /*++
1316
1317 Routine Description:
1318     Given the input file pointer, search for the next matching file in the
1319     FFS volume as defined by SearchType. The search starts from FileHeader inside
1320     the Firmware Volume defined by FwVolHeader.
1321
1322 Arguments:
1323     PeiServices - Pointer to the PEI Core Services Table.
1324     SearchType - Filter to find only files of this type.
1325       Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
1326     FwVolHeader - Pointer to the FV header of the volume to search.
1327       This parameter must point to a valid FFS volume.
1328     FileHeader  - Pointer to the current file from which to begin searching.
1329       This pointer will be updated upon return to reflect the file found.
1330     Flag        - Indicator for if this is for PEI Dispath search
1331
1332 Returns:
1333     EFI_NOT_FOUND - No files matching the search criteria were found
1334     EFI_SUCCESS
1335
1336 --*/
1337 ;
1338
1339 VOID
1340 InitializeImageServices (
1341   IN  PEI_CORE_INSTANCE   *PrivateData,
1342   IN  PEI_CORE_INSTANCE   *OldCoreData
1343   )
1344 /*++
1345
1346 Routine Description:
1347
1348   Install Pei Load File PPI.
1349
1350 Arguments:
1351
1352   PrivateData    - Pointer to PEI_CORE_INSTANCE.
1353   OldCoreData    - Pointer to PEI_CORE_INSTANCE.
1354
1355 Returns:
1356
1357   NONE.
1358
1359 --*/
1360 ;
1361
1362 /**
1363   Get Fv image from the FV type file, then install FV INFO ppi, Build FV hob.
1364
1365         @param PeiServices          Pointer to the PEI Core Services Table.
1366         @param FileHandle               File handle of a Fv type file.
1367   @param AuthenticationState  Pointer to attestation authentication state of image.
1368
1369
1370   @retval EFI_NOT_FOUND                                 FV image can't be found.
1371   @retval EFI_SUCCESS                                           Successfully to process it.
1372
1373 **/
1374 EFI_STATUS
1375 ProcessFvFile (
1376   IN  EFI_PEI_SERVICES      **PeiServices,
1377   IN  EFI_PEI_FILE_HANDLE   FvFileHandle,
1378   OUT UINT32                *AuthenticationState
1379   );
1380
1381 #endif