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
;
123 // Dispatcher support functions
127 PeimDispatchReadiness (
128 IN EFI_PEI_SERVICES
**PeiServices
,
129 IN VOID
*DependencyExpression
,
130 IN OUT BOOLEAN
*Runnable
136 This is the POSTFIX version of the dependency evaluator. When a
137 PUSH [PPI GUID] is encountered, a pointer to the GUID is stored on
138 the evaluation stack. When that entry is poped from the evaluation
139 stack, the PPI is checked if it is installed. This method allows
140 some time savings as not all PPIs must be checked for certain
141 operation types (AND, OR).
145 PeiServices - Calling context.
147 DependencyExpression - Pointer to a dependency expression. The Grammar adheres to
148 the BNF described above and is stored in postfix notation.
149 Runnable - is True if the driver can be scheduled and False if the driver
150 cannot be scheduled. This is the value that the schedulers
151 should use for deciding the state of the driver.
155 Status = EFI_SUCCESS if it is a well-formed Grammar
156 EFI_INVALID_PARAMETER if the dependency expression overflows
158 EFI_INVALID_PARAMETER if the dependency expression underflows
160 EFI_INVALID_PARAMETER if the dependency expression is not a
168 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
169 IN PEI_CORE_INSTANCE
*PrivateData
,
170 IN PEI_CORE_DISPATCH_DATA
*DispatchData
177 Conduct PEIM dispatch.
181 PeiStartupDescriptor - Pointer to IN EFI_PEI_STARTUP_DESCRIPTOR
182 PrivateData - Pointer to the private data passed in from caller
183 DispatchData - Pointer to PEI_CORE_DISPATCH_DATA data.
187 EFI_SUCCESS - Successfully dispatched PEIM.
188 EFI_NOT_FOUND - The dispatch failed.
195 InitializeDispatcherData (
196 IN EFI_PEI_SERVICES
**PeiServices
,
197 IN PEI_CORE_INSTANCE
*OldCoreData
,
198 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
204 Initialize the Dispatcher's data members
208 PeiServices - The PEI core services table.
209 OldCoreData - Pointer to old core data (before switching stack).
210 NULL if being run in non-permament memory mode.
211 PeiStartupDescriptor - Information and services provided by SEC phase.
224 IN EFI_PEI_SERVICES
**PeiServices
,
225 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
226 IN OUT EFI_FFS_FILE_HEADER
**PeimFileHeader
231 Given the input file pointer, search for the next matching file in the
232 FFS volume. The search starts from FileHeader inside
233 the Firmware Volume defined by FwVolHeader.
236 PeiServices - Pointer to the PEI Core Services Table.
238 FwVolHeader - Pointer to the FV header of the volume to search.
239 This parameter must point to a valid FFS volume.
241 PeimFileHeader - Pointer to the current file from which to begin searching.
242 This pointer will be updated upon return to reflect the file found.
245 EFI_NOT_FOUND - No files matching the search criteria were found
253 IN UINT8 CurrentPeim
,
254 IN UINT32 DispatchedPeimBitMap
260 This routine checks to see if a particular PEIM has been dispatched during
261 the PEI core dispatch.
264 CurrentPeim - The PEIM/FV in the bit array to check.
265 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
268 TRUE if PEIM already dispatched
276 IN EFI_PEI_SERVICES
**PeiServices
,
277 IN UINT8 CurrentPeim
,
278 OUT UINT32
*DispatchedPeimBitMap
284 This routine sets a PEIM as having been dispatched once its entry
285 point has been invoked.
289 PeiServices - The PEI core services table.
290 CurrentPeim - The PEIM/FV in the bit array to check.
291 DispatchedPeimBitMap - Bit array, each bit corresponds to a PEIM/FV.
301 IN EFI_PEI_SERVICES
**PeiServices
,
302 IN VOID
*CurrentPeimAddress
308 This routine parses the Dependency Expression, if available, and
309 decides if the module can be executed.
312 PeiServices - The PEI Service Table
313 CurrentPeimAddress - Address of the PEIM Firmware File under investigation
316 TRUE - Can be dispatched
317 FALSE - Cannot be dispatched
324 // In Ipf we should make special changes for the PHIT pointers to support
325 // recovery boot in cache mode.
327 #define SWITCH_TO_CACHE_MODE(CoreData) SwitchToCacheMode(CoreData)
328 #define CACHE_MODE_ADDRESS_MASK 0x7FFFFFFFFFFFFFFFULL
331 IN PEI_CORE_INSTANCE
*CoreData
337 Switch the PHIT pointers to cache mode after InstallPeiMemory in CAR.
341 CoreData - The PEI core Private Data
350 #define SWITCH_TO_CACHE_MODE(CoreData)
355 // PPI support functions
358 InitializePpiServices (
359 IN EFI_PEI_SERVICES
**PeiServices
,
360 IN PEI_CORE_INSTANCE
*OldCoreData
366 Initialize PPI services.
370 PeiServices - The PEI core services table.
371 OldCoreData - Pointer to the PEI Core data.
372 NULL if being run in non-permament memory mode.
382 IN EFI_PEI_SERVICES
**PeiServices
,
383 IN EFI_HOB_HANDOFF_INFO_TABLE
*OldHandOffHob
,
384 IN EFI_HOB_HANDOFF_INFO_TABLE
*NewHandOffHob
390 Migrate the Hob list from the CAR stack to PEI installed memory.
394 PeiServices - The PEI core services table.
395 OldHandOffHob - The old handoff HOB list.
396 NewHandOffHob - The new handoff HOB list.
406 IN EFI_PEI_SERVICES
**PeiServices
,
407 IN EFI_PEI_PPI_DESCRIPTOR
*PpiList
413 Install PPI services.
417 PeiServices - Pointer to the PEI Service Table
418 PpiList - Pointer to a list of PEI PPI Descriptors.
422 EFI_SUCCESS - if all PPIs in PpiList are successfully installed.
423 EFI_INVALID_PARAMETER - if PpiList is NULL pointer
424 EFI_INVALID_PARAMETER - if any PPI in PpiList is not valid
425 EFI_OUT_OF_RESOURCES - if there is no more memory resource to install PPI
433 IN EFI_PEI_SERVICES
**PeiServices
,
434 IN EFI_PEI_PPI_DESCRIPTOR
*OldPpi
,
435 IN EFI_PEI_PPI_DESCRIPTOR
*NewPpi
441 Re-Install PPI services.
445 PeiServices - Pointer to the PEI Service Table
446 OldPpi - Pointer to the old PEI PPI Descriptors.
447 NewPpi - Pointer to the new PEI PPI Descriptors.
451 EFI_SUCCESS - if the operation was successful
452 EFI_INVALID_PARAMETER - if OldPpi or NewPpi is NULL
453 EFI_INVALID_PARAMETER - if NewPpi is not valid
454 EFI_NOT_FOUND - if the PPI was not in the database
462 IN EFI_PEI_SERVICES
**PeiServices
,
465 IN OUT EFI_PEI_PPI_DESCRIPTOR
**PpiDescriptor
,
472 Locate a given named PPI.
476 PeiServices - Pointer to the PEI Service Table
477 Guid - Pointer to GUID of the PPI.
478 Instance - Instance Number to discover.
479 PpiDescriptor - Pointer to reference the found descriptor. If not NULL,
480 returns a pointer to the descriptor (includes flags, etc)
481 Ppi - Pointer to reference the found PPI
485 Status - EFI_SUCCESS if the PPI is in the database
486 EFI_NOT_FOUND if the PPI is not in the database
493 IN EFI_PEI_SERVICES
**PeiServices
,
494 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyList
500 Install a notification for a given PPI.
504 PeiServices - Pointer to the PEI Service Table
505 NotifyList - Pointer to list of Descriptors to notify upon.
509 Status - EFI_SUCCESS if successful
510 EFI_OUT_OF_RESOURCES if no space in the database
511 EFI_INVALID_PARAMETER if not a good decriptor
518 IN EFI_PEI_SERVICES
**PeiServices
524 Process the Notify List at dispatch level.
528 PeiServices - Pointer to the PEI Service Table
537 IN EFI_PEI_SERVICES
**PeiServices
,
539 IN INTN InstallStartIndex
,
540 IN INTN InstallStopIndex
,
541 IN INTN NotifyStartIndex
,
542 IN INTN NotifyStopIndex
548 Dispatch notifications.
552 PeiServices - Pointer to the PEI Service Table
553 NotifyType - Type of notify to fire.
554 InstallStartIndex - Install Beginning index.
555 InstallStopIndex - Install Ending index.
556 NotifyStartIndex - Notify Beginning index.
557 NotifyStopIndex - Notify Ending index.
565 // Boot mode support functions
570 IN EFI_PEI_SERVICES
**PeiServices
,
571 IN OUT EFI_BOOT_MODE
*BootMode
577 This service enables PEIMs to ascertain the present value of the boot mode.
581 PeiServices - The PEI core services table.
582 BootMode - A pointer to contain the value of the boot mode.
586 EFI_SUCCESS - The boot mode was returned successfully.
587 EFI_INVALID_PARAMETER - BootMode is NULL.
595 IN EFI_PEI_SERVICES
**PeiServices
,
596 IN EFI_BOOT_MODE BootMode
602 This service enables PEIMs to update the boot mode variable.
606 PeiServices - The PEI core services table.
607 BootMode - The value of the boot mode to set.
611 EFI_SUCCESS - The value was successfully updated
617 // Security support functions
620 InitializeSecurityServices (
621 IN EFI_PEI_SERVICES
**PeiServices
,
622 IN PEI_CORE_INSTANCE
*OldCoreData
628 Initialize the security services.
632 PeiServices - The PEI core services table.
633 OldCoreData - Pointer to the old core data.
634 NULL if being run in non-permament memory mode.
644 IN EFI_FIRMWARE_VOLUME_HEADER
*CurrentFvAddress
650 Provide a callout to the OEM FV verification service.
654 CurrentFvAddress - Pointer to the FV under investigation.
666 IN EFI_PEI_SERVICES
**PeiServices
,
667 IN EFI_FFS_FILE_HEADER
*CurrentPeimAddress
673 Provide a callout to the security verification service.
677 PeiServices - The PEI core services table.
678 CurrentPeimAddress - Pointer to the Firmware File under investigation.
682 EFI_SUCCESS - Image is OK
683 EFI_SECURITY_VIOLATION - Image is illegal
692 IN EFI_PEI_SERVICES
**PeiServices
,
693 IN OUT VOID
**HobList
699 Gets the pointer to the HOB List.
703 PeiServices - The PEI core services table.
704 HobList - Pointer to the HOB List.
708 EFI_SUCCESS - Get the pointer of HOB List
709 EFI_NOT_AVAILABLE_YET - the HOB List is not yet published
710 EFI_INVALID_PARAMETER - HobList is NULL (in debug mode)
718 IN EFI_PEI_SERVICES
**PeiServices
,
727 Add a new HOB to the HOB List.
731 PeiServices - The PEI core services table.
732 Type - Type of the new HOB.
733 Length - Length of the new HOB to allocate.
734 Hob - Pointer to the new HOB.
739 - EFI_INVALID_PARAMETER if Hob is NULL
740 - EFI_NOT_AVAILABLE_YET if HobList is still not available.
741 - EFI_OUT_OF_RESOURCES if there is no more memory to grow the Hoblist.
747 PeiCoreBuildHobHandoffInfoTable (
748 IN EFI_BOOT_MODE BootMode
,
749 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
750 IN UINT64 MemoryLength
756 Builds a Handoff Information Table HOB
760 BootMode - Current Bootmode
761 MemoryBegin - Start Memory Address.
762 MemoryLength - Length of Memory.
773 // FFS Fw Volume support functions
778 IN EFI_PEI_SERVICES
**PeiServices
,
780 IN EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
,
781 IN OUT EFI_FFS_FILE_HEADER
**FileHeader
786 Given the input file pointer, search for the next matching file in the
787 FFS volume as defined by SearchType. The search starts from FileHeader inside
788 the Firmware Volume defined by FwVolHeader.
791 PeiServices - Pointer to the PEI Core Services Table.
793 SearchType - Filter to find only files of this type.
794 Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
796 FwVolHeader - Pointer to the FV header of the volume to search.
797 This parameter must point to a valid FFS volume.
799 FileHeader - Pointer to the current file from which to begin searching.
800 This pointer will be updated upon return to reflect the file found.
803 EFI_NOT_FOUND - No files matching the search criteria were found
811 PeiFfsFindSectionData (
812 IN EFI_PEI_SERVICES
**PeiServices
,
813 IN EFI_SECTION_TYPE SectionType
,
814 IN EFI_FFS_FILE_HEADER
*FfsFileHeader
,
815 IN OUT VOID
**SectionData
820 Given the input file pointer, search for the next matching section in the
824 PeiServices - Pointer to the PEI Core Services Table.
825 SearchType - Filter to find only sections of this type.
826 FfsFileHeader - Pointer to the current file to search.
827 SectionData - Pointer to the Section matching SectionType in FfsFileHeader.
828 - NULL if section not found
831 EFI_NOT_FOUND - No files matching the search criteria were found
839 PeiFvFindNextVolume (
840 IN EFI_PEI_SERVICES
**PeiServices
,
842 IN OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
848 Return the BFV location
850 BugBug -- Move this to the location of this code to where the
851 other FV and FFS support code lives.
852 Also, update to use FindFV for instances #'s >= 1.
856 PeiServices - The PEI core services table.
857 Instance - Instance of FV to find
858 FwVolHeader - Pointer to contain the data to return
861 Pointer to the Firmware Volume instance requested
863 EFI_INVALID_PARAMETER - FwVolHeader is NULL
865 EFI_SUCCESS - Firmware volume instance successfully found.
871 // Memory support functions
874 InitializeMemoryServices (
875 IN EFI_PEI_SERVICES
**PeiServices
,
876 IN EFI_PEI_STARTUP_DESCRIPTOR
*PeiStartupDescriptor
,
877 IN PEI_CORE_INSTANCE
*OldCoreData
883 Initialize the memory services.
887 PeiServices - The PEI core services table.
888 PeiStartupDescriptor - Information and services provided by SEC phase.
889 OldCoreData - Pointer to the PEI Core data.
890 NULL if being run in non-permament memory mode.
901 PeiInstallPeiMemory (
902 IN EFI_PEI_SERVICES
**PeiServices
,
903 IN EFI_PHYSICAL_ADDRESS MemoryBegin
,
904 IN UINT64 MemoryLength
910 Install the permanent memory is now available.
911 Creates HOB (PHIT and Stack).
915 PeiServices - The PEI core services table.
916 MemoryBegin - Start of memory address.
917 MemoryLength - Length of memory.
929 IN EFI_PEI_SERVICES
**PeiServices
,
930 IN EFI_MEMORY_TYPE MemoryType
,
932 OUT EFI_PHYSICAL_ADDRESS
*Memory
938 Memory allocation service on permanent memory,
939 not usable prior to the memory installation.
943 PeiServices - The PEI core services table.
944 Type - Type of allocation.
945 MemoryType - Type of memory to allocate.
946 Pages - Number of pages to allocate.
947 Memory - Pointer of memory allocated.
951 Status - EFI_SUCCESS The allocation was successful
952 EFI_INVALID_PARAMETER Only AllocateAnyAddress is supported.
953 EFI_NOT_AVAILABLE_YET Called with permanent memory not available
954 EFI_OUT_OF_RESOURCES There is not enough HOB heap to satisfy the requirement
955 to allocate the number of pages.
963 IN EFI_PEI_SERVICES
**PeiServices
,
971 Memory allocation service on the CAR.
975 PeiServices - The PEI core services table.
977 Size - Amount of memory required
979 Buffer - Address of pointer to the buffer
983 Status - EFI_SUCCESS The allocation was successful
984 EFI_OUT_OF_RESOURCES There is not enough heap to satisfy the requirement
985 to allocate the requested size.
992 IN EFI_PEI_SERVICES
**PeiServices
,
993 IN EFI_FFS_FILE_HEADER
*PeimFileHeader
,
994 OUT VOID
**EntryPoint
1000 Get entry point of a Peim file.
1004 PeiServices - Calling context.
1006 PeimFileHeader - Peim file's header.
1008 EntryPoint - Entry point of that Peim file.
1020 PeiReportStatusCode (
1021 IN EFI_PEI_SERVICES
**PeiServices
,
1022 IN EFI_STATUS_CODE_TYPE CodeType
,
1023 IN EFI_STATUS_CODE_VALUE Value
,
1025 IN EFI_GUID
*CallerId
,
1026 IN EFI_STATUS_CODE_DATA
*Data OPTIONAL
1030 Routine Description:
1032 Core version of the Status Code reporter
1036 PeiServices - The PEI core services table.
1038 CodeType - Type of Status Code.
1040 Value - Value to output for Status Code.
1042 Instance - Instance Number of this status code.
1044 CallerId - ID of the caller of this status code.
1046 Data - Optional data associated with this status code.
1050 Status - EFI_SUCCESS if status code is successfully reported
1051 - EFI_NOT_AVAILABLE_YET if StatusCodePpi has not been installed
1060 IN EFI_PEI_SERVICES
**PeiServices
1064 Routine Description:
1066 Core version of the Reset System
1070 PeiServices - The PEI core services table.
1074 Status - EFI_NOT_AVAILABLE_YET. PPI not available yet.
1075 - EFI_DEVICE_ERROR. Did not reset system.
1077 Otherwise, resets the system.
1083 Transfers control to a function starting with a new stack.
1085 Transfers control to the function specified by EntryPoint using the new stack
1086 specified by NewStack and passing in the parameters specified by Context1 and
1087 Context2. Context1 and Context2 are optional and may be NULL. The function
1088 EntryPoint must never return.
1090 If EntryPoint is NULL, then ASSERT().
1091 If NewStack is NULL, then ASSERT().
1093 @param EntryPoint A pointer to function to call with the new stack.
1094 @param Context1 A pointer to the context to pass into the EntryPoint
1096 @param Context2 A pointer to the context to pass into the EntryPoint
1098 @param NewStack A pointer to the new stack to use for the EntryPoint
1100 @param NewBsp A pointer to the new BSP for the EntryPoint on IPF. It's
1101 Reserved on other architectures.
1107 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
1108 IN VOID
*Context1
, OPTIONAL
1109 IN VOID
*Context2
, OPTIONAL