3 Copyright (c) 2006, 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
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.
18 Definition of Pei Core Structures and Services
28 //Build private HOB to PEI core to transfer old NEM-range data to new NEM-range
30 #define EFI_PEI_CORE_PRIVATE_GUID \
31 {0xd641a0f5, 0xcb7c, 0x4846, { 0xa3, 0x80, 0x1d, 0x01, 0xb4, 0xd9, 0xe3, 0xb9 } }
34 // Pei Core private data structures
37 EFI_PEI_PPI_DESCRIPTOR
*Ppi
;
38 EFI_PEI_NOTIFY_DESCRIPTOR
*Notify
;
40 } PEI_PPI_LIST_POINTERS
;
42 #define PEI_STACK_SIZE 0x20000
44 #define MAX_PPI_DESCRIPTORS 64
50 INTN LastDispatchedInstall
;
51 INTN LastDispatchedNotify
;
52 PEI_PPI_LIST_POINTERS PpiListPtrs
[MAX_PPI_DESCRIPTORS
];
58 UINT32 DispatchedPeimBitMap
;
59 UINT32 PreviousPeimBitMap
;
60 EFI_FFS_FILE_HEADER
*CurrentPeimAddress
;
61 EFI_FIRMWARE_VOLUME_HEADER
*CurrentFvAddress
;
62 EFI_FIRMWARE_VOLUME_HEADER
*BootFvAddress
;
63 EFI_PEI_FIND_FV_PPI
*FindFv
;
64 } PEI_CORE_DISPATCH_DATA
;
68 // Pei Core private data structure instance
71 #define PEI_CORE_HANDLE_SIGNATURE EFI_SIGNATURE_32('P','e','i','C')
75 EFI_PEI_SERVICES
*PS
; // Point to ServiceTableShadow
76 PEI_PPI_DATABASE PpiData
;
77 PEI_CORE_DISPATCH_DATA DispatchData
;
78 EFI_PEI_HOB_POINTERS HobList
;
79 BOOLEAN SwitchStackSignal
;
80 BOOLEAN PeiMemoryInstalled
;
81 EFI_PHYSICAL_ADDRESS StackBase
;
83 VOID
*BottomOfCarHeap
;
86 EFI_PEI_SECURITY_PPI
*PrivateSecurityPpi
;
87 EFI_PEI_SERVICES ServiceTableShadow
;
88 UINTN SizeOfCacheAsRam
;
89 VOID
*MaxTopOfCarHeap
;
93 // Pei Core Instance Data Macros
96 #define PEI_CORE_INSTANCE_FROM_PS_THIS(a) \
97 CR(a, PEI_CORE_INSTANCE, PS, PEI_CORE_HANDLE_SIGNATURE)
100 // BUGBUG: Where does this go really?
104 (EFIAPI
*PEI_CORE_ENTRY_POINT
)(
105 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
106 IN PEI_CORE_INSTANCE
*OldCoreData
110 // Union of temporarily used function pointers (to save stack space)
113 PEI_CORE_ENTRY_POINT PeiCore
;
114 EFI_PEIM_ENTRY_POINT PeimEntry
;
115 EFI_PEIM_NOTIFY_ENTRY_POINT PeimNotifyEntry
;
116 EFI_DXE_IPL_PPI
*DxeIpl
;
117 EFI_PEI_PPI_DESCRIPTOR
*PpiDescriptor
;
118 EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyDescriptor
;
120 } PEI_CORE_TEMP_POINTERS
;
129 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
136 The entry routine to Pei Core, invoked by PeiMain during transition
137 from SEC to PEI. After switching stack in the PEI core, it will restart
138 with the old core data.
142 PeiStartupDescriptor - Information and services provided by SEC phase.
143 OldCoreData - Pointer to old core data that is used to initialize the
148 This function never returns
149 EFI_NOT_FOUND - Never reach
155 // Dispatcher support functions
159 PeimDispatchReadiness (
160 IN EFI_PEI_SERVICES
**PeiServices
,
161 IN VOID
*DependencyExpression
,
162 IN OUT BOOLEAN
*Runnable
168 This is the POSTFIX version of the dependency evaluator. When a
169 PUSH [PPI GUID] is encountered, a pointer to the GUID is stored on
170 the evaluation stack. When that entry is poped from the evaluation
171 stack, the PPI is checked if it is installed. This method allows
172 some time savings as not all PPIs must be checked for certain
173 operation types (AND, OR).
177 PeiServices - Calling context.
179 DependencyExpression - Pointer to a dependency expression. The Grammar adheres to
180 the BNF described above and is stored in postfix notation.
181 Runnable - is True if the driver can be scheduled and False if the driver
182 cannot be scheduled. This is the value that the schedulers
183 should use for deciding the state of the driver.
187 Status = EFI_SUCCESS if it is a well-formed Grammar
188 EFI_INVALID_PARAMETER if the dependency expression overflows
190 EFI_INVALID_PARAMETER if the dependency expression underflows
192 EFI_INVALID_PARAMETER if the dependency expression is not a
200 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
201 IN PEI_CORE_INSTANCE
*PrivateData
,
202 IN PEI_CORE_DISPATCH_DATA
*DispatchData
209 Conduct PEIM dispatch.
213 PeiStartupDescriptor - Pointer to IN EFI_PEI_STARTUP_DESCRIPTOR
214 PrivateData - Pointer to the private data passed in from caller
215 DispatchData - Pointer to PEI_CORE_DISPATCH_DATA data.
219 EFI_SUCCESS - Successfully dispatched PEIM.
220 EFI_NOT_FOUND - The dispatch failed.
227 InitializeDispatcherData (
228 IN EFI_PEI_SERVICES
**PeiServices
,
229 IN PEI_CORE_INSTANCE
*OldCoreData
,
230 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
236 Initialize the Dispatcher's data members
240 PeiServices - The PEI core services table.
241 OldCoreData - Pointer to old core data (before switching stack).
242 NULL if being run in non-permament memory mode.
243 PeiStartupDescriptor - Information and services provided by SEC phase.
256 IN EFI_PEI_SERVICES
**PeiServices
,
257 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
258 IN OUT EFI_FFS_FILE_HEADER
**PeimFileHeader
263 Given the input file pointer, search for the next matching file in the
264 FFS volume. The search starts from FileHeader inside
265 the Firmware Volume defined by FwVolHeader.
268 PeiServices - Pointer to the PEI Core Services Table.
270 FwVolHeader - Pointer to the FV header of the volume to search.
271 This parameter must point to a valid FFS volume.
273 PeimFileHeader - Pointer to the current file from which to begin searching.
274 This pointer will be updated upon return to reflect the file found.
277 EFI_NOT_FOUND - No files matching the search criteria were found
285 IN UINT8 CurrentPeim
,
286 IN UINT32 DispatchedPeimBitMap
292 This routine checks to see if a particular PEIM has been dispatched during
293 the PEI core dispatch.
296 CurrentPeim - The PEIM/FV in the bit array to check.
297 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
300 TRUE if PEIM already dispatched
308 IN EFI_PEI_SERVICES
**PeiServices
,
309 IN UINT8 CurrentPeim
,
310 OUT UINT32
*DispatchedPeimBitMap
316 This routine sets a PEIM as having been dispatched once its entry
317 point has been invoked.
321 PeiServices - The PEI core services table.
322 CurrentPeim - The PEIM/FV in the bit array to check.
323 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
333 IN EFI_PEI_SERVICES
**PeiServices
,
334 IN VOID
*CurrentPeimAddress
340 This routine parses the Dependency Expression, if available, and
341 decides if the module can be executed.
344 PeiServices - The PEI Service Table
345 CurrentPeimAddress - Address of the PEIM Firmware File under investigation
348 TRUE - Can be dispatched
349 FALSE - Cannot be dispatched
356 // In Ipf we should make special changes for the PHIT pointers to support
357 // recovery boot in cache mode.
359 #define SWITCH_TO_CACHE_MODE(CoreData) SwitchToCacheMode(CoreData)
360 #define CACHE_MODE_ADDRESS_MASK 0x7FFFFFFFFFFFFFFFULL
363 IN PEI_CORE_INSTANCE
*CoreData
369 Switch the PHIT pointers to cache mode after InstallPeiMemory in CAR.
373 CoreData - The PEI core Private Data
382 #define SWITCH_TO_CACHE_MODE(CoreData)
387 // PPI support functions
390 InitializePpiServices (
391 IN EFI_PEI_SERVICES
**PeiServices
,
392 IN PEI_CORE_INSTANCE
*OldCoreData
398 Initialize PPI services.
402 PeiServices - The PEI core services table.
403 OldCoreData - Pointer to the PEI Core data.
404 NULL if being run in non-permament memory mode.
414 IN EFI_PEI_SERVICES
**PeiServices
,
415 IN EFI_HOB_HANDOFF_INFO_TABLE
*OldHandOffHob
,
416 IN EFI_HOB_HANDOFF_INFO_TABLE
*NewHandOffHob
422 Migrate the Hob list from the CAR stack to PEI installed memory.
426 PeiServices - The PEI core services table.
427 OldHandOffHob - The old handoff HOB list.
428 NewHandOffHob - The new handoff HOB list.
438 IN EFI_PEI_SERVICES
**PeiServices
,
439 IN EFI_PEI_PPI_DESCRIPTOR
*PpiList
445 Install PPI services.
449 PeiServices - Pointer to the PEI Service Table
450 PpiList - Pointer to a list of PEI PPI Descriptors.
454 EFI_SUCCESS - if all PPIs in PpiList are successfully installed.
455 EFI_INVALID_PARAMETER - if PpiList is NULL pointer
456 EFI_INVALID_PARAMETER - if any PPI in PpiList is not valid
457 EFI_OUT_OF_RESOURCES - if there is no more memory resource to install PPI
465 IN EFI_PEI_SERVICES
**PeiServices
,
466 IN EFI_PEI_PPI_DESCRIPTOR
*OldPpi
,
467 IN EFI_PEI_PPI_DESCRIPTOR
*NewPpi
473 Re-Install PPI services.
477 PeiServices - Pointer to the PEI Service Table
478 OldPpi - Pointer to the old PEI PPI Descriptors.
479 NewPpi - Pointer to the new PEI PPI Descriptors.
483 EFI_SUCCESS - if the operation was successful
484 EFI_INVALID_PARAMETER - if OldPpi or NewPpi is NULL
485 EFI_INVALID_PARAMETER - if NewPpi is not valid
486 EFI_NOT_FOUND - if the PPI was not in the database
494 IN EFI_PEI_SERVICES
**PeiServices
,
497 IN OUT EFI_PEI_PPI_DESCRIPTOR
**PpiDescriptor
,
504 Locate a given named PPI.
508 PeiServices - Pointer to the PEI Service Table
509 Guid - Pointer to GUID of the PPI.
510 Instance - Instance Number to discover.
511 PpiDescriptor - Pointer to reference the found descriptor. If not NULL,
512 returns a pointer to the descriptor (includes flags, etc)
513 Ppi - Pointer to reference the found PPI
517 Status - EFI_SUCCESS if the PPI is in the database
518 EFI_NOT_FOUND if the PPI is not in the database
525 IN EFI_PEI_SERVICES
**PeiServices
,
526 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyList
532 Install a notification for a given PPI.
536 PeiServices - Pointer to the PEI Service Table
537 NotifyList - Pointer to list of Descriptors to notify upon.
541 Status - EFI_SUCCESS if successful
542 EFI_OUT_OF_RESOURCES if no space in the database
543 EFI_INVALID_PARAMETER if not a good decriptor
550 IN EFI_PEI_SERVICES
**PeiServices
556 Process the Notify List at dispatch level.
560 PeiServices - Pointer to the PEI Service Table
569 IN EFI_PEI_SERVICES
**PeiServices
,
571 IN INTN InstallStartIndex
,
572 IN INTN InstallStopIndex
,
573 IN INTN NotifyStartIndex
,
574 IN INTN NotifyStopIndex
580 Dispatch notifications.
584 PeiServices - Pointer to the PEI Service Table
585 NotifyType - Type of notify to fire.
586 InstallStartIndex - Install Beginning index.
587 InstallStopIndex - Install Ending index.
588 NotifyStartIndex - Notify Beginning index.
589 NotifyStopIndex - Notify Ending index.
597 // Boot mode support functions
602 IN EFI_PEI_SERVICES
**PeiServices
,
603 IN OUT EFI_BOOT_MODE
*BootMode
609 This service enables PEIMs to ascertain the present value of the boot mode.
613 PeiServices - The PEI core services table.
614 BootMode - A pointer to contain the value of the boot mode.
618 EFI_SUCCESS - The boot mode was returned successfully.
619 EFI_INVALID_PARAMETER - BootMode is NULL.
627 IN EFI_PEI_SERVICES
**PeiServices
,
628 IN EFI_BOOT_MODE BootMode
634 This service enables PEIMs to update the boot mode variable.
638 PeiServices - The PEI core services table.
639 BootMode - The value of the boot mode to set.
643 EFI_SUCCESS - The value was successfully updated
649 // Security support functions
652 InitializeSecurityServices (
653 IN EFI_PEI_SERVICES
**PeiServices
,
654 IN PEI_CORE_INSTANCE
*OldCoreData
660 Initialize the security services.
664 PeiServices - The PEI core services table.
665 OldCoreData - Pointer to the old core data.
666 NULL if being run in non-permament memory mode.
676 IN EFI_FIRMWARE_VOLUME_HEADER
*CurrentFvAddress
682 Provide a callout to the OEM FV verification service.
686 CurrentFvAddress - Pointer to the FV under investigation.
698 IN EFI_PEI_SERVICES
**PeiServices
,
699 IN EFI_FFS_FILE_HEADER
*CurrentPeimAddress
705 Provide a callout to the security verification service.
709 PeiServices - The PEI core services table.
710 CurrentPeimAddress - Pointer to the Firmware File under investigation.
714 EFI_SUCCESS - Image is OK
715 EFI_SECURITY_VIOLATION - Image is illegal
724 IN EFI_PEI_SERVICES
**PeiServices
,
725 IN OUT VOID
**HobList
731 Gets the pointer to the HOB List.
735 PeiServices - The PEI core services table.
736 HobList - Pointer to the HOB List.
740 EFI_SUCCESS - Get the pointer of HOB List
741 EFI_NOT_AVAILABLE_YET - the HOB List is not yet published
742 EFI_INVALID_PARAMETER - HobList is NULL (in debug mode)
750 IN EFI_PEI_SERVICES
**PeiServices
,
759 Add a new HOB to the HOB List.
763 PeiServices - The PEI core services table.
764 Type - Type of the new HOB.
765 Length - Length of the new HOB to allocate.
766 Hob - Pointer to the new HOB.
771 - EFI_INVALID_PARAMETER if Hob is NULL
772 - EFI_NOT_AVAILABLE_YET if HobList is still not available.
773 - EFI_OUT_OF_RESOURCES if there is no more memory to grow the Hoblist.
779 PeiCoreBuildHobHandoffInfoTable (
780 IN EFI_BOOT_MODE BootMode
,
781 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
782 IN UINT64 MemoryLength
788 Builds a Handoff Information Table HOB
792 BootMode - Current Bootmode
793 MemoryBegin - Start Memory Address.
794 MemoryLength - Length of Memory.
805 // FFS Fw Volume support functions
810 IN EFI_PEI_SERVICES
**PeiServices
,
812 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
813 IN OUT EFI_FFS_FILE_HEADER
**FileHeader
818 Given the input file pointer, search for the next matching file in the
819 FFS volume as defined by SearchType. The search starts from FileHeader inside
820 the Firmware Volume defined by FwVolHeader.
823 PeiServices - Pointer to the PEI Core Services Table.
825 SearchType - Filter to find only files of this type.
826 Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
828 FwVolHeader - Pointer to the FV header of the volume to search.
829 This parameter must point to a valid FFS volume.
831 FileHeader - Pointer to the current file from which to begin searching.
832 This pointer will be updated upon return to reflect the file found.
835 EFI_NOT_FOUND - No files matching the search criteria were found
843 PeiFfsFindSectionData (
844 IN EFI_PEI_SERVICES
**PeiServices
,
845 IN EFI_SECTION_TYPE SectionType
,
846 IN EFI_FFS_FILE_HEADER
*FfsFileHeader
,
847 IN OUT VOID
**SectionData
852 Given the input file pointer, search for the next matching section in the
856 PeiServices - Pointer to the PEI Core Services Table.
857 SearchType - Filter to find only sections of this type.
858 FfsFileHeader - Pointer to the current file to search.
859 SectionData - Pointer to the Section matching SectionType in FfsFileHeader.
860 - NULL if section not found
863 EFI_NOT_FOUND - No files matching the search criteria were found
871 PeiFvFindNextVolume (
872 IN EFI_PEI_SERVICES
**PeiServices
,
874 IN OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
880 Return the BFV location
882 BugBug -- Move this to the location of this code to where the
883 other FV and FFS support code lives.
884 Also, update to use FindFV for instances #'s >= 1.
888 PeiServices - The PEI core services table.
889 Instance - Instance of FV to find
890 FwVolHeader - Pointer to contain the data to return
893 Pointer to the Firmware Volume instance requested
895 EFI_INVALID_PARAMETER - FwVolHeader is NULL
897 EFI_SUCCESS - Firmware volume instance successfully found.
903 // Memory support functions
906 InitializeMemoryServices (
907 IN EFI_PEI_SERVICES
**PeiServices
,
908 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
909 IN PEI_CORE_INSTANCE
*OldCoreData
915 Initialize the memory services.
919 PeiServices - The PEI core services table.
920 PeiStartupDescriptor - Information and services provided by SEC phase.
921 OldCoreData - Pointer to the PEI Core data.
922 NULL if being run in non-permament memory mode.
933 PeiInstallPeiMemory (
934 IN EFI_PEI_SERVICES
**PeiServices
,
935 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
936 IN UINT64 MemoryLength
942 Install the permanent memory is now available.
943 Creates HOB (PHIT and Stack).
947 PeiServices - The PEI core services table.
948 MemoryBegin - Start of memory address.
949 MemoryLength - Length of memory.
961 IN EFI_PEI_SERVICES
**PeiServices
,
962 IN EFI_MEMORY_TYPE MemoryType
,
964 OUT EFI_PHYSICAL_ADDRESS
*Memory
970 Memory allocation service on permanent memory,
971 not usable prior to the memory installation.
975 PeiServices - The PEI core services table.
976 Type - Type of allocation.
977 MemoryType - Type of memory to allocate.
978 Pages - Number of pages to allocate.
979 Memory - Pointer of memory allocated.
983 Status - EFI_SUCCESS The allocation was successful
984 EFI_INVALID_PARAMETER Only AllocateAnyAddress is supported.
985 EFI_NOT_AVAILABLE_YET Called with permanent memory not available
986 EFI_OUT_OF_RESOURCES There is not enough HOB heap to satisfy the requirement
987 to allocate the number of pages.
995 IN EFI_PEI_SERVICES
**PeiServices
,
1001 Routine Description:
1003 Memory allocation service on the CAR.
1007 PeiServices - The PEI core services table.
1009 Size - Amount of memory required
1011 Buffer - Address of pointer to the buffer
1015 Status - EFI_SUCCESS The allocation was successful
1016 EFI_OUT_OF_RESOURCES There is not enough heap to satisfy the requirement
1017 to allocate the requested size.
1024 IN EFI_PEI_SERVICES
**PeiServices
,
1025 IN EFI_FFS_FILE_HEADER
*PeimFileHeader
,
1026 OUT VOID
**EntryPoint
1030 Routine Description:
1032 Get entry point of a Peim file.
1036 PeiServices - Calling context.
1038 PeimFileHeader - Peim file's header.
1040 EntryPoint - Entry point of that Peim file.
1052 PeiReportStatusCode (
1053 IN EFI_PEI_SERVICES
**PeiServices
,
1054 IN EFI_STATUS_CODE_TYPE CodeType
,
1055 IN EFI_STATUS_CODE_VALUE Value
,
1057 IN EFI_GUID
*CallerId
,
1058 IN EFI_STATUS_CODE_DATA
*Data OPTIONAL
1062 Routine Description:
1064 Core version of the Status Code reporter
1068 PeiServices - The PEI core services table.
1070 CodeType - Type of Status Code.
1072 Value - Value to output for Status Code.
1074 Instance - Instance Number of this status code.
1076 CallerId - ID of the caller of this status code.
1078 Data - Optional data associated with this status code.
1082 Status - EFI_SUCCESS if status code is successfully reported
1083 - EFI_NOT_AVAILABLE_YET if StatusCodePpi has not been installed
1092 IN EFI_PEI_SERVICES
**PeiServices
1096 Routine Description:
1098 Core version of the Reset System
1102 PeiServices - The PEI core services table.
1106 Status - EFI_NOT_AVAILABLE_YET. PPI not available yet.
1107 - EFI_DEVICE_ERROR. Did not reset system.
1109 Otherwise, resets the system.
1115 Transfers control to a function starting with a new stack.
1117 Transfers control to the function specified by EntryPoint using the new stack
1118 specified by NewStack and passing in the parameters specified by Context1 and
1119 Context2. Context1 and Context2 are optional and may be NULL. The function
1120 EntryPoint must never return.
1122 If EntryPoint is NULL, then ASSERT().
1123 If NewStack is NULL, then ASSERT().
1125 @param EntryPoint A pointer to function to call with the new stack.
1126 @param Context1 A pointer to the context to pass into the EntryPoint
1128 @param Context2 A pointer to the context to pass into the EntryPoint
1130 @param NewStack A pointer to the new stack to use for the EntryPoint
1132 @param NewBsp A pointer to the new BSP for the EntryPoint on IPF. It's
1133 Reserved on other architectures.
1139 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
1140 IN VOID
*Context1
, OPTIONAL
1141 IN VOID
*Context2
, OPTIONAL