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
32 //Build private HOB to PEI core to transfer old NEM-range data to new NEM-range
34 #define EFI_PEI_CORE_PRIVATE_GUID \
35 {0xd641a0f5, 0xcb7c, 0x4846, { 0xa3, 0x80, 0x1d, 0x01, 0xb4, 0xd9, 0xe3, 0xb9 } }
38 // Pei Core private data structures
41 EFI_PEI_PPI_DESCRIPTOR
*Ppi
;
42 EFI_PEI_NOTIFY_DESCRIPTOR
*Notify
;
44 } PEI_PPI_LIST_POINTERS
;
46 #define PEI_STACK_SIZE 0x20000
48 #define MAX_PPI_DESCRIPTORS 64
54 INTN LastDispatchedInstall
;
55 INTN LastDispatchedNotify
;
56 PEI_PPI_LIST_POINTERS PpiListPtrs
[MAX_PPI_DESCRIPTORS
];
62 UINT32 DispatchedPeimBitMap
;
63 UINT32 PreviousPeimBitMap
;
64 EFI_FFS_FILE_HEADER
*CurrentPeimAddress
;
65 EFI_FIRMWARE_VOLUME_HEADER
*CurrentFvAddress
;
66 EFI_FIRMWARE_VOLUME_HEADER
*BootFvAddress
;
67 EFI_PEI_FIND_FV_PPI
*FindFv
;
68 } PEI_CORE_DISPATCH_DATA
;
72 // Pei Core private data structure instance
75 #define PEI_CORE_HANDLE_SIGNATURE EFI_SIGNATURE_32('P','e','i','C')
79 EFI_PEI_SERVICES
*PS
; // Point to ServiceTableShadow
80 PEI_PPI_DATABASE PpiData
;
81 PEI_CORE_DISPATCH_DATA DispatchData
;
82 EFI_PEI_HOB_POINTERS HobList
;
83 BOOLEAN SwitchStackSignal
;
84 BOOLEAN PeiMemoryInstalled
;
85 EFI_PHYSICAL_ADDRESS StackBase
;
87 VOID
*BottomOfCarHeap
;
90 EFI_PEI_SECURITY_PPI
*PrivateSecurityPpi
;
91 EFI_PEI_SERVICES ServiceTableShadow
;
92 UINTN SizeOfCacheAsRam
;
93 VOID
*MaxTopOfCarHeap
;
97 // Pei Core Instance Data Macros
100 #define PEI_CORE_INSTANCE_FROM_PS_THIS(a) \
101 CR(a, PEI_CORE_INSTANCE, PS, PEI_CORE_HANDLE_SIGNATURE)
104 // BUGBUG: Where does this go really?
108 (EFIAPI
*PEI_CORE_ENTRY_POINT
)(
109 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
110 IN PEI_CORE_INSTANCE
*OldCoreData
114 // Union of temporarily used function pointers (to save stack space)
117 PEI_CORE_ENTRY_POINT PeiCore
;
118 EFI_PEIM_ENTRY_POINT PeimEntry
;
119 EFI_PEIM_NOTIFY_ENTRY_POINT PeimNotifyEntry
;
120 EFI_DXE_IPL_PPI
*DxeIpl
;
121 EFI_PEI_PPI_DESCRIPTOR
*PpiDescriptor
;
122 EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyDescriptor
;
124 } PEI_CORE_TEMP_POINTERS
;
134 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
135 IN PEI_CORE_INSTANCE
*OldCoreData
141 Main entry point to Pei Core. After switching stack in the PEI core,
142 it will restart with the old core data.
146 PeiStartupDescriptor - Information and services provided by SEC phase.
147 OldCoreData - Pointer to old core data that is used to initialize the
152 This function never returns
159 // Dispatcher support functions
163 PeimDispatchReadiness (
164 IN EFI_PEI_SERVICES
**PeiServices
,
165 IN VOID
*DependencyExpression
,
166 IN OUT BOOLEAN
*Runnable
172 This is the POSTFIX version of the dependency evaluator. When a
173 PUSH [PPI GUID] is encountered, a pointer to the GUID is stored on
174 the evaluation stack. When that entry is poped from the evaluation
175 stack, the PPI is checked if it is installed. This method allows
176 some time savings as not all PPIs must be checked for certain
177 operation types (AND, OR).
181 PeiServices - Calling context.
183 DependencyExpression - Pointer to a dependency expression. The Grammar adheres to
184 the BNF described above and is stored in postfix notation.
185 Runnable - is True if the driver can be scheduled and False if the driver
186 cannot be scheduled. This is the value that the schedulers
187 should use for deciding the state of the driver.
191 Status = EFI_SUCCESS if it is a well-formed Grammar
192 EFI_INVALID_PARAMETER if the dependency expression overflows
194 EFI_INVALID_PARAMETER if the dependency expression underflows
196 EFI_INVALID_PARAMETER if the dependency expression is not a
204 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
205 IN PEI_CORE_INSTANCE
*PrivateData
,
206 IN PEI_CORE_DISPATCH_DATA
*DispatchData
213 Conduct PEIM dispatch.
217 PeiStartupDescriptor - Pointer to IN EFI_PEI_STARTUP_DESCRIPTOR
218 PrivateData - Pointer to the private data passed in from caller
219 DispatchData - Pointer to PEI_CORE_DISPATCH_DATA data.
223 EFI_SUCCESS - Successfully dispatched PEIM.
224 EFI_NOT_FOUND - The dispatch failed.
231 InitializeDispatcherData (
232 IN EFI_PEI_SERVICES
**PeiServices
,
233 IN PEI_CORE_INSTANCE
*OldCoreData
,
234 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
240 Initialize the Dispatcher's data members
244 PeiServices - The PEI core services table.
245 OldCoreData - Pointer to old core data (before switching stack).
246 NULL if being run in non-permament memory mode.
247 PeiStartupDescriptor - Information and services provided by SEC phase.
260 IN EFI_PEI_SERVICES
**PeiServices
,
261 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
262 IN OUT EFI_FFS_FILE_HEADER
**PeimFileHeader
267 Given the input file pointer, search for the next matching file in the
268 FFS volume. The search starts from FileHeader inside
269 the Firmware Volume defined by FwVolHeader.
272 PeiServices - Pointer to the PEI Core Services Table.
274 FwVolHeader - Pointer to the FV header of the volume to search.
275 This parameter must point to a valid FFS volume.
277 PeimFileHeader - Pointer to the current file from which to begin searching.
278 This pointer will be updated upon return to reflect the file found.
281 EFI_NOT_FOUND - No files matching the search criteria were found
289 IN UINT8 CurrentPeim
,
290 IN UINT32 DispatchedPeimBitMap
296 This routine checks to see if a particular PEIM has been dispatched during
297 the PEI core dispatch.
300 CurrentPeim - The PEIM/FV in the bit array to check.
301 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
304 TRUE if PEIM already dispatched
312 IN EFI_PEI_SERVICES
**PeiServices
,
313 IN UINT8 CurrentPeim
,
314 OUT UINT32
*DispatchedPeimBitMap
320 This routine sets a PEIM as having been dispatched once its entry
321 point has been invoked.
325 PeiServices - The PEI core services table.
326 CurrentPeim - The PEIM/FV in the bit array to check.
327 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
337 IN EFI_PEI_SERVICES
**PeiServices
,
338 IN VOID
*CurrentPeimAddress
344 This routine parses the Dependency Expression, if available, and
345 decides if the module can be executed.
348 PeiServices - The PEI Service Table
349 CurrentPeimAddress - Address of the PEIM Firmware File under investigation
352 TRUE - Can be dispatched
353 FALSE - Cannot be dispatched
360 // In Ipf we should make special changes for the PHIT pointers to support
361 // recovery boot in cache mode.
363 #define SWITCH_TO_CACHE_MODE(CoreData) SwitchToCacheMode(CoreData)
364 #define CACHE_MODE_ADDRESS_MASK 0x7FFFFFFFFFFFFFFFULL
367 IN PEI_CORE_INSTANCE
*CoreData
373 Switch the PHIT pointers to cache mode after InstallPeiMemory in CAR.
377 CoreData - The PEI core Private Data
386 #define SWITCH_TO_CACHE_MODE(CoreData)
391 // PPI support functions
394 InitializePpiServices (
395 IN EFI_PEI_SERVICES
**PeiServices
,
396 IN PEI_CORE_INSTANCE
*OldCoreData
402 Initialize PPI services.
406 PeiServices - The PEI core services table.
407 OldCoreData - Pointer to the PEI Core data.
408 NULL if being run in non-permament memory mode.
418 IN EFI_PEI_SERVICES
**PeiServices
,
419 IN EFI_HOB_HANDOFF_INFO_TABLE
*OldHandOffHob
,
420 IN EFI_HOB_HANDOFF_INFO_TABLE
*NewHandOffHob
426 Migrate the Hob list from the CAR stack to PEI installed memory.
430 PeiServices - The PEI core services table.
431 OldHandOffHob - The old handoff HOB list.
432 NewHandOffHob - The new handoff HOB list.
442 IN EFI_PEI_SERVICES
**PeiServices
,
443 IN EFI_PEI_PPI_DESCRIPTOR
*PpiList
449 Install PPI services.
453 PeiServices - Pointer to the PEI Service Table
454 PpiList - Pointer to a list of PEI PPI Descriptors.
458 EFI_SUCCESS - if all PPIs in PpiList are successfully installed.
459 EFI_INVALID_PARAMETER - if PpiList is NULL pointer
460 EFI_INVALID_PARAMETER - if any PPI in PpiList is not valid
461 EFI_OUT_OF_RESOURCES - if there is no more memory resource to install PPI
469 IN EFI_PEI_SERVICES
**PeiServices
,
470 IN EFI_PEI_PPI_DESCRIPTOR
*OldPpi
,
471 IN EFI_PEI_PPI_DESCRIPTOR
*NewPpi
477 Re-Install PPI services.
481 PeiServices - Pointer to the PEI Service Table
482 OldPpi - Pointer to the old PEI PPI Descriptors.
483 NewPpi - Pointer to the new PEI PPI Descriptors.
487 EFI_SUCCESS - if the operation was successful
488 EFI_INVALID_PARAMETER - if OldPpi or NewPpi is NULL
489 EFI_INVALID_PARAMETER - if NewPpi is not valid
490 EFI_NOT_FOUND - if the PPI was not in the database
498 IN EFI_PEI_SERVICES
**PeiServices
,
501 IN OUT EFI_PEI_PPI_DESCRIPTOR
**PpiDescriptor
,
508 Locate a given named PPI.
512 PeiServices - Pointer to the PEI Service Table
513 Guid - Pointer to GUID of the PPI.
514 Instance - Instance Number to discover.
515 PpiDescriptor - Pointer to reference the found descriptor. If not NULL,
516 returns a pointer to the descriptor (includes flags, etc)
517 Ppi - Pointer to reference the found PPI
521 Status - EFI_SUCCESS if the PPI is in the database
522 EFI_NOT_FOUND if the PPI is not in the database
529 IN EFI_PEI_SERVICES
**PeiServices
,
530 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyList
536 Install a notification for a given PPI.
540 PeiServices - Pointer to the PEI Service Table
541 NotifyList - Pointer to list of Descriptors to notify upon.
545 Status - EFI_SUCCESS if successful
546 EFI_OUT_OF_RESOURCES if no space in the database
547 EFI_INVALID_PARAMETER if not a good decriptor
554 IN EFI_PEI_SERVICES
**PeiServices
560 Process the Notify List at dispatch level.
564 PeiServices - Pointer to the PEI Service Table
573 IN EFI_PEI_SERVICES
**PeiServices
,
575 IN INTN InstallStartIndex
,
576 IN INTN InstallStopIndex
,
577 IN INTN NotifyStartIndex
,
578 IN INTN NotifyStopIndex
584 Dispatch notifications.
588 PeiServices - Pointer to the PEI Service Table
589 NotifyType - Type of notify to fire.
590 InstallStartIndex - Install Beginning index.
591 InstallStopIndex - Install Ending index.
592 NotifyStartIndex - Notify Beginning index.
593 NotifyStopIndex - Notify Ending index.
601 // Boot mode support functions
606 IN EFI_PEI_SERVICES
**PeiServices
,
607 IN OUT EFI_BOOT_MODE
*BootMode
613 This service enables PEIMs to ascertain the present value of the boot mode.
617 PeiServices - The PEI core services table.
618 BootMode - A pointer to contain the value of the boot mode.
622 EFI_SUCCESS - The boot mode was returned successfully.
623 EFI_INVALID_PARAMETER - BootMode is NULL.
631 IN EFI_PEI_SERVICES
**PeiServices
,
632 IN EFI_BOOT_MODE BootMode
638 This service enables PEIMs to update the boot mode variable.
642 PeiServices - The PEI core services table.
643 BootMode - The value of the boot mode to set.
647 EFI_SUCCESS - The value was successfully updated
653 // Security support functions
656 InitializeSecurityServices (
657 IN EFI_PEI_SERVICES
**PeiServices
,
658 IN PEI_CORE_INSTANCE
*OldCoreData
664 Initialize the security services.
668 PeiServices - The PEI core services table.
669 OldCoreData - Pointer to the old core data.
670 NULL if being run in non-permament memory mode.
680 IN EFI_FIRMWARE_VOLUME_HEADER
*CurrentFvAddress
686 Provide a callout to the OEM FV verification service.
690 CurrentFvAddress - Pointer to the FV under investigation.
702 IN EFI_PEI_SERVICES
**PeiServices
,
703 IN EFI_FFS_FILE_HEADER
*CurrentPeimAddress
709 Provide a callout to the security verification service.
713 PeiServices - The PEI core services table.
714 CurrentPeimAddress - Pointer to the Firmware File under investigation.
718 EFI_SUCCESS - Image is OK
719 EFI_SECURITY_VIOLATION - Image is illegal
728 IN EFI_PEI_SERVICES
**PeiServices
,
729 IN OUT VOID
**HobList
735 Gets the pointer to the HOB List.
739 PeiServices - The PEI core services table.
740 HobList - Pointer to the HOB List.
744 EFI_SUCCESS - Get the pointer of HOB List
745 EFI_NOT_AVAILABLE_YET - the HOB List is not yet published
746 EFI_INVALID_PARAMETER - HobList is NULL (in debug mode)
754 IN EFI_PEI_SERVICES
**PeiServices
,
763 Add a new HOB to the HOB List.
767 PeiServices - The PEI core services table.
768 Type - Type of the new HOB.
769 Length - Length of the new HOB to allocate.
770 Hob - Pointer to the new HOB.
775 - EFI_INVALID_PARAMETER if Hob is NULL
776 - EFI_NOT_AVAILABLE_YET if HobList is still not available.
777 - EFI_OUT_OF_RESOURCES if there is no more memory to grow the Hoblist.
783 PeiCoreBuildHobHandoffInfoTable (
784 IN EFI_BOOT_MODE BootMode
,
785 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
786 IN UINT64 MemoryLength
792 Builds a Handoff Information Table HOB
796 BootMode - Current Bootmode
797 MemoryBegin - Start Memory Address.
798 MemoryLength - Length of Memory.
809 // FFS Fw Volume support functions
814 IN EFI_PEI_SERVICES
**PeiServices
,
816 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
817 IN OUT EFI_FFS_FILE_HEADER
**FileHeader
822 Given the input file pointer, search for the next matching file in the
823 FFS volume as defined by SearchType. The search starts from FileHeader inside
824 the Firmware Volume defined by FwVolHeader.
827 PeiServices - Pointer to the PEI Core Services Table.
829 SearchType - Filter to find only files of this type.
830 Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
832 FwVolHeader - Pointer to the FV header of the volume to search.
833 This parameter must point to a valid FFS volume.
835 FileHeader - Pointer to the current file from which to begin searching.
836 This pointer will be updated upon return to reflect the file found.
839 EFI_NOT_FOUND - No files matching the search criteria were found
847 PeiFfsFindSectionData (
848 IN EFI_PEI_SERVICES
**PeiServices
,
849 IN EFI_SECTION_TYPE SectionType
,
850 IN EFI_FFS_FILE_HEADER
*FfsFileHeader
,
851 IN OUT VOID
**SectionData
856 Given the input file pointer, search for the next matching section in the
860 PeiServices - Pointer to the PEI Core Services Table.
861 SearchType - Filter to find only sections of this type.
862 FfsFileHeader - Pointer to the current file to search.
863 SectionData - Pointer to the Section matching SectionType in FfsFileHeader.
864 - NULL if section not found
867 EFI_NOT_FOUND - No files matching the search criteria were found
875 PeiFvFindNextVolume (
876 IN EFI_PEI_SERVICES
**PeiServices
,
878 IN OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
884 Return the BFV location
886 BugBug -- Move this to the location of this code to where the
887 other FV and FFS support code lives.
888 Also, update to use FindFV for instances #'s >= 1.
892 PeiServices - The PEI core services table.
893 Instance - Instance of FV to find
894 FwVolHeader - Pointer to contain the data to return
897 Pointer to the Firmware Volume instance requested
899 EFI_INVALID_PARAMETER - FwVolHeader is NULL
901 EFI_SUCCESS - Firmware volume instance successfully found.
907 // Memory support functions
910 InitializeMemoryServices (
911 IN EFI_PEI_SERVICES
**PeiServices
,
912 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
913 IN PEI_CORE_INSTANCE
*OldCoreData
919 Initialize the memory services.
923 PeiServices - The PEI core services table.
924 PeiStartupDescriptor - Information and services provided by SEC phase.
925 OldCoreData - Pointer to the PEI Core data.
926 NULL if being run in non-permament memory mode.
937 PeiInstallPeiMemory (
938 IN EFI_PEI_SERVICES
**PeiServices
,
939 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
940 IN UINT64 MemoryLength
946 Install the permanent memory is now available.
947 Creates HOB (PHIT and Stack).
951 PeiServices - The PEI core services table.
952 MemoryBegin - Start of memory address.
953 MemoryLength - Length of memory.
965 IN EFI_PEI_SERVICES
**PeiServices
,
966 IN EFI_MEMORY_TYPE MemoryType
,
968 OUT EFI_PHYSICAL_ADDRESS
*Memory
974 Memory allocation service on permanent memory,
975 not usable prior to the memory installation.
979 PeiServices - The PEI core services table.
980 Type - Type of allocation.
981 MemoryType - Type of memory to allocate.
982 Pages - Number of pages to allocate.
983 Memory - Pointer of memory allocated.
987 Status - EFI_SUCCESS The allocation was successful
988 EFI_INVALID_PARAMETER Only AllocateAnyAddress is supported.
989 EFI_NOT_AVAILABLE_YET Called with permanent memory not available
990 EFI_OUT_OF_RESOURCES There is not enough HOB heap to satisfy the requirement
991 to allocate the number of pages.
999 IN EFI_PEI_SERVICES
**PeiServices
,
1005 Routine Description:
1007 Memory allocation service on the CAR.
1011 PeiServices - The PEI core services table.
1013 Size - Amount of memory required
1015 Buffer - Address of pointer to the buffer
1019 Status - EFI_SUCCESS The allocation was successful
1020 EFI_OUT_OF_RESOURCES There is not enough heap to satisfy the requirement
1021 to allocate the requested size.
1028 IN EFI_PEI_SERVICES
**PeiServices
,
1029 IN EFI_FFS_FILE_HEADER
*PeimFileHeader
,
1030 OUT VOID
**EntryPoint
1034 Routine Description:
1036 Get entry point of a Peim file.
1040 PeiServices - Calling context.
1042 PeimFileHeader - Peim file's header.
1044 EntryPoint - Entry point of that Peim file.
1056 PeiReportStatusCode (
1057 IN EFI_PEI_SERVICES
**PeiServices
,
1058 IN EFI_STATUS_CODE_TYPE CodeType
,
1059 IN EFI_STATUS_CODE_VALUE Value
,
1061 IN EFI_GUID
*CallerId
,
1062 IN EFI_STATUS_CODE_DATA
*Data OPTIONAL
1066 Routine Description:
1068 Core version of the Status Code reporter
1072 PeiServices - The PEI core services table.
1074 CodeType - Type of Status Code.
1076 Value - Value to output for Status Code.
1078 Instance - Instance Number of this status code.
1080 CallerId - ID of the caller of this status code.
1082 Data - Optional data associated with this status code.
1086 Status - EFI_SUCCESS if status code is successfully reported
1087 - EFI_NOT_AVAILABLE_YET if StatusCodePpi has not been installed
1096 IN EFI_PEI_SERVICES
**PeiServices
1100 Routine Description:
1102 Core version of the Reset System
1106 PeiServices - The PEI core services table.
1110 Status - EFI_NOT_AVAILABLE_YET. PPI not available yet.
1111 - EFI_DEVICE_ERROR. Did not reset system.
1113 Otherwise, resets the system.
1119 Transfers control to a function starting with a new stack.
1121 Transfers control to the function specified by EntryPoint using the new stack
1122 specified by NewStack and passing in the parameters specified by Context1 and
1123 Context2. Context1 and Context2 are optional and may be NULL. The function
1124 EntryPoint must never return.
1126 If EntryPoint is NULL, then ASSERT().
1127 If NewStack is NULL, then ASSERT().
1129 @param EntryPoint A pointer to function to call with the new stack.
1130 @param Context1 A pointer to the context to pass into the EntryPoint
1132 @param Context2 A pointer to the context to pass into the EntryPoint
1134 @param NewStack A pointer to the new stack to use for the EntryPoint
1136 @param NewBsp A pointer to the new BSP for the EntryPoint on IPF. It's
1137 Reserved on other architectures.
1143 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
1144 IN VOID
*Context1
, OPTIONAL
1145 IN VOID
*Context2
, OPTIONAL