2 Intel FSP API definition from Intel Firmware Support Package External
3 Architecture Specification v2.0 - v2.2
5 Copyright (c) 2014 - 2022, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #include <Pi/PiStatusCode.h>
16 /// FSP Reset Status code
17 /// These are defined in FSP EAS v2.0 section 11.2.2 - OEM Status Code
19 #define FSP_STATUS_RESET_REQUIRED_COLD 0x40000001
20 #define FSP_STATUS_RESET_REQUIRED_WARM 0x40000002
21 #define FSP_STATUS_RESET_REQUIRED_3 0x40000003
22 #define FSP_STATUS_RESET_REQUIRED_4 0x40000004
23 #define FSP_STATUS_RESET_REQUIRED_5 0x40000005
24 #define FSP_STATUS_RESET_REQUIRED_6 0x40000006
25 #define FSP_STATUS_RESET_REQUIRED_7 0x40000007
26 #define FSP_STATUS_RESET_REQUIRED_8 0x40000008
30 /// FSP Event related definition.
32 #define FSP_EVENT_CODE 0xF5000000
33 #define FSP_POST_CODE (FSP_EVENT_CODE | 0x00F80000)
36 FSP may optionally include the capability of generating events messages to aid in the debugging of firmware issues.
37 These events fall under three catagories: Error, Progress, and Debug. The event reporting mechanism follows the
38 status code services described in section 6 and 7 of the PI Specification v1.7 Volume 3.
40 @param[in] Type Indicates the type of event being reported.
41 See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_TYPE.
42 @param[in] Value Describes the current status of a hardware or software entity.
43 This includes information about the class and subclass that is used to classify the entity as well as an operation.
44 For progress events, the operation is the current activity. For error events, it is the exception.
45 For debug events, it is not defined at this time.
46 See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_VALUE.
47 @param[in] Instance The enumeration of a hardware or software entity within the system.
48 A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them.
49 An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant.
50 Valid instance numbers start with 1.
51 @param[in] *CallerId This parameter can be used to identify the sub-module within the FSP generating the event.
52 This parameter may be NULL.
53 @param[in] *Data This optional parameter may be used to pass additional data. The contents can have event-specific data.
54 For example, the FSP provides a EFI_STATUS_CODE_STRING_DATA instance to this parameter when sending debug messages.
55 This parameter is NULL when no additional data is provided.
57 @retval EFI_SUCCESS The event was handled successfully.
58 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
59 @retval EFI_DEVICE_ERROR The event handler failed.
63 (EFIAPI
*FSP_EVENT_HANDLER
)(
64 IN EFI_STATUS_CODE_TYPE Type
,
65 IN EFI_STATUS_CODE_VALUE Value
,
67 IN OPTIONAL EFI_GUID
*CallerId
,
68 IN OPTIONAL EFI_STATUS_CODE_DATA
*Data
72 Handler for FSP-T debug log messages, provided by the bootloader.
74 @param[in] DebugMessage A pointer to the debug message to be written to the log.
75 @param[in] MessageLength Number of bytes to written to the debug log.
77 @retval UINT32 The return value indicates the number of bytes actually written to
78 the debug log. If the return value is less than MessageLength,
83 (EFIAPI
*FSP_DEBUG_HANDLER
)(
84 IN CHAR8
*DebugMessage
,
85 IN UINT32 MessageLength
90 /// FSP_UPD_HEADER Configuration.
94 /// UPD Region Signature. This signature will be
95 /// "XXXXXX_T" for FSP-T
96 /// "XXXXXX_M" for FSP-M
97 /// "XXXXXX_S" for FSP-S
98 /// Where XXXXXX is an unique signature
102 /// Revision of the Data structure.
103 /// For FSP spec 2.0/2.1 value is 1.
104 /// For FSP spec 2.2 value is 2.
111 /// FSPT_ARCH_UPD Configuration.
115 /// Revision of the structure is 1 for this version of the specification.
120 /// Length of the structure in bytes. The current value for this field is 32.
124 /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages
125 /// occurring during FSP execution.
127 FSP_DEBUG_HANDLER FspDebugHandler
;
132 /// FSPT_ARCH2_UPD Configuration.
136 /// Revision of the structure is 2 for this version of the specification.
141 /// Length of the structure in bytes. The current value for this field is 32.
145 /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages
146 /// occurring during FSP execution.
148 EFI_PHYSICAL_ADDRESS FspDebugHandler
;
153 /// FSPM_ARCH_UPD Configuration.
157 /// Revision of the structure. For FSP v2.0 value is 1.
162 /// Pointer to the non-volatile storage (NVS) data buffer.
163 /// If it is NULL it indicates the NVS data is not available.
167 /// Pointer to the temporary stack base address to be
168 /// consumed inside FspMemoryInit() API.
172 /// Temporary stack size to be consumed inside
173 /// FspMemoryInit() API.
177 /// Size of memory to be reserved by FSP below "top
178 /// of low usable memory" for bootloader usage.
180 UINT32 BootLoaderTolumSize
;
182 /// Current boot mode.
186 /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.
187 /// This value is only valid if Revision is >= 2.
189 FSP_EVENT_HANDLER
*FspEventHandler
;
194 /// FSPM_ARCH2_UPD Configuration.
198 /// Revision of the structure is 3 for this version of the specification.
203 /// Length of the structure in bytes. The current value for this field is 64.
207 /// Pointer to the temporary stack base address to be
208 /// consumed inside FspMemoryInit() API.
210 EFI_PHYSICAL_ADDRESS StackBase
;
212 /// Temporary stack size to be consumed inside
213 /// FspMemoryInit() API.
217 /// Size of memory to be reserved by FSP below "top
218 /// of low usable memory" for bootloader usage.
220 UINT32 BootLoaderTolumSize
;
222 /// Current boot mode.
226 /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.
227 /// This value is only valid if Revision is >= 2.
229 EFI_PHYSICAL_ADDRESS FspEventHandler
;
234 /// FSPS_ARCH_UPD Configuration.
238 /// Revision of the structure is 1 for this version of the specification.
243 /// Length of the structure in bytes. The current value for this field is 32.
247 /// FspEventHandler Optional event handler for the bootloader to be informed of events
248 /// occurring during FSP execution.
250 FSP_EVENT_HANDLER FspEventHandler
;
252 /// A FSP binary may optionally implement multi-phase silicon initialization,
253 /// This is only supported if the FspMultiPhaseSiInitEntryOffset field in FSP_INFO_HEADER
255 /// To enable multi-phase silicon initialization, the bootloader must set
256 /// EnableMultiPhaseSiliconInit to a non-zero value.
258 UINT8 EnableMultiPhaseSiliconInit
;
263 /// FSPS_ARCH2_UPD Configuration.
267 /// Revision of the structure is 2 for this version of the specification.
272 /// Length of the structure in bytes. The current value for this field is 32.
276 /// FspEventHandler Optional event handler for the bootloader to be informed of events
277 /// occurring during FSP execution.
279 EFI_PHYSICAL_ADDRESS FspEventHandler
;
284 /// FSPT_UPD_COMMON Configuration.
288 /// FSP_UPD_HEADER Configuration.
290 FSP_UPD_HEADER FspUpdHeader
;
294 /// FSPT_UPD_COMMON Configuration for FSP spec. 2.2 and above.
298 /// FSP_UPD_HEADER Configuration.
300 FSP_UPD_HEADER FspUpdHeader
;
303 /// FSPT_ARCH_UPD Configuration.
305 FSPT_ARCH_UPD FsptArchUpd
;
306 } FSPT_UPD_COMMON_FSP22
;
309 /// FSPT_UPD_COMMON Configuration for FSP spec. 2.4 and above.
313 /// FSP_UPD_HEADER Configuration.
315 FSP_UPD_HEADER FspUpdHeader
;
318 /// FSPT_ARCH2_UPD Configuration.
320 FSPT_ARCH2_UPD FsptArchUpd
;
321 } FSPT_UPD_COMMON_FSP24
;
324 /// FSPM_UPD_COMMON Configuration.
328 /// FSP_UPD_HEADER Configuration.
330 FSP_UPD_HEADER FspUpdHeader
;
332 /// FSPM_ARCH_UPD Configuration.
334 FSPM_ARCH_UPD FspmArchUpd
;
338 /// FSPM_UPD_COMMON Configuration for FSP spec. 2.4 and above.
342 /// FSP_UPD_HEADER Configuration.
344 FSP_UPD_HEADER FspUpdHeader
;
346 /// FSPM_ARCH2_UPD Configuration.
348 FSPM_ARCH2_UPD FspmArchUpd
;
349 } FSPM_UPD_COMMON_FSP24
;
352 /// FSPS_UPD_COMMON Configuration.
356 /// FSP_UPD_HEADER Configuration.
358 FSP_UPD_HEADER FspUpdHeader
;
362 /// FSPS_UPD_COMMON Configuration for FSP spec. 2.2 and above.
366 /// FSP_UPD_HEADER Configuration.
368 FSP_UPD_HEADER FspUpdHeader
;
371 /// FSPS_ARCH_UPD Configuration.
373 FSPS_ARCH_UPD FspsArchUpd
;
374 } FSPS_UPD_COMMON_FSP22
;
377 /// FSPS_UPD_COMMON Configuration for FSP spec. 2.4 and above.
381 /// FSP_UPD_HEADER Configuration.
383 FSP_UPD_HEADER FspUpdHeader
;
386 /// FSPS_ARCH2_UPD Configuration.
388 FSPS_ARCH2_UPD FspsArchUpd
;
389 } FSPS_UPD_COMMON_FSP24
;
392 /// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE.
396 /// This stage is notified when the bootloader completes the
397 /// PCI enumeration and the resource allocation for the
398 /// PCI devices is complete.
400 EnumInitPhaseAfterPciEnumeration
= 0x20,
402 /// This stage is notified just before the bootloader hand-off
403 /// to the OS loader.
405 EnumInitPhaseReadyToBoot
= 0x40,
407 /// This stage is notified just before the firmware/Preboot
408 /// environment transfers management of all system resources
409 /// to the OS or next level execution environment.
411 EnumInitPhaseEndOfFirmware
= 0xF0
415 /// Definition of NOTIFY_PHASE_PARAMS.
419 /// Notification phase used for NotifyPhase API
421 FSP_INIT_PHASE Phase
;
422 } NOTIFY_PHASE_PARAMS
;
425 /// Action definition for FspMultiPhaseSiInit API
428 EnumMultiPhaseGetNumberOfPhases
= 0x0,
429 EnumMultiPhaseExecutePhase
= 0x1
430 } FSP_MULTI_PHASE_ACTION
;
433 /// Data structure returned by FSP when bootloader calling
434 /// FspMultiPhaseSiInit API with action 0 (EnumMultiPhaseGetNumberOfPhases)
437 UINT32 NumberOfPhases
;
438 UINT32 PhasesExecuted
;
439 } FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS
;
442 /// FspMultiPhaseSiInit function parameter.
444 /// For action 0 (EnumMultiPhaseGetNumberOfPhases):
445 /// - PhaseIndex must be 0.
446 /// - MultiPhaseParamPtr should point to an instance of FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS.
448 /// For action 1 (EnumMultiPhaseExecutePhase):
449 /// - PhaseIndex will be the phase that will be executed by FSP.
450 /// - MultiPhaseParamPtr shall be NULL.
453 IN FSP_MULTI_PHASE_ACTION MultiPhaseAction
;
454 IN UINT32 PhaseIndex
;
455 IN OUT VOID
*MultiPhaseParamPtr
;
456 } FSP_MULTI_PHASE_PARAMS
;
461 This FSP API is called soon after coming out of reset and before memory and stack is
462 available. This FSP API will load the microcode update, enable code caching for the
463 region specified by the boot loader and also setup a temporary stack to be used until
464 main memory is initialized.
466 A hardcoded stack can be set up with the following values, and the "esp" register
467 initialized to point to this hardcoded stack.
468 1. The return address where the FSP will return control after setting up a temporary
470 2. A pointer to the input parameter structure
472 However, since the stack is in ROM and not writeable, this FSP API cannot be called
473 using the "call" instruction, but needs to be jumped to.
475 @param[in] FsptUpdDataPtr Pointer to the FSPT_UPD data structure.
477 @retval EFI_SUCCESS Temporary RAM was initialized successfully.
478 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
479 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
480 @retval EFI_DEVICE_ERROR Temp RAM initialization failed.
482 If this function is successful, the FSP initializes the ECX and EDX registers to point to
483 a temporary but writeable memory range available to the boot loader and returns with
484 FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
485 memory range and EDX points to the end of the range. Boot loader is free to use the
486 whole range described. Typically the boot loader can reload the ESP register to point
487 to the end of this returned range so that it can be used as a standard stack.
491 (EFIAPI
*FSP_TEMP_RAM_INIT
)(
492 IN VOID
*FsptUpdDataPtr
496 This FSP API is used to notify the FSP about the different phases in the boot process.
497 This allows the FSP to take appropriate actions as needed during different initialization
498 phases. The phases will be platform dependent and will be documented with the FSP
499 release. The current FSP supports two notify phases:
503 @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
505 @retval EFI_SUCCESS The notification was handled successfully.
506 @retval EFI_UNSUPPORTED The notification was not called in the proper order.
507 @retval EFI_INVALID_PARAMETER The notification code is invalid.
511 (EFIAPI
*FSP_NOTIFY_PHASE
)(
512 IN NOTIFY_PHASE_PARAMS
*NotifyPhaseParamPtr
516 This FSP API is called after TempRamInit and initializes the memory.
517 This FSP API accepts a pointer to a data structure that will be platform dependent
518 and defined for each FSP binary. This will be documented in Integration guide with
520 After FspMemInit completes its execution, it passes the pointer to the HobList and
521 returns to the boot loader from where it was called. BootLoader is responsible to
522 migrate its stack and data to Memory.
523 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
524 complete the silicon initialization and provides bootloader an opportunity to get
525 control after system memory is available and before the temporary RAM is torn down.
527 @param[in] FspmUpdDataPtr Pointer to the FSPM_UPD data structure.
528 @param[out] HobListPtr Pointer to receive the address of the HOB list.
530 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
531 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
532 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
533 @retval EFI_DEVICE_ERROR FSP initialization failed.
534 @retval EFI_OUT_OF_RESOURCES Stack range requested by FSP is not met.
535 @retval FSP_STATUS_RESET_REQUIREDx A reset is reuired. These status codes will not be returned during S3.
539 (EFIAPI
*FSP_MEMORY_INIT
)(
540 IN VOID
*FspmUpdDataPtr
,
541 OUT VOID
**HobListPtr
545 This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
546 memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
547 that will be platform dependent and defined for each FSP binary. This will be
548 documented in Integration Guide.
549 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
550 complete the silicon initialization and provides bootloader an opportunity to get
551 control after system memory is available and before the temporary RAM is torn down.
553 @param[in] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
554 This structure is normally defined in the Integration Guide.
555 And if it is not defined in the Integration Guide, pass NULL.
557 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
558 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
559 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
560 @retval EFI_DEVICE_ERROR FSP initialization failed.
564 (EFIAPI
*FSP_TEMP_RAM_EXIT
)(
565 IN VOID
*TempRamExitParamPtr
569 This FSP API is called after TempRamExit API.
570 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
571 silicon initialization.
573 @param[in] FspsUpdDataPtr Pointer to the FSPS_UPD data structure.
574 If NULL, FSP will use the default parameters.
576 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
577 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
578 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
579 @retval EFI_DEVICE_ERROR FSP initialization failed.
580 @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.
584 (EFIAPI
*FSP_SILICON_INIT
)(
585 IN VOID
*FspsUpdDataPtr
589 This FSP API is expected to be called after FspSiliconInit but before FspNotifyPhase.
590 This FSP API provides multi-phase silicon initialization; which brings greater modularity
591 beyond the existing FspSiliconInit() API. Increased modularity is achieved by adding an
592 extra API to FSP-S. This allows the bootloader to add board specific initialization steps
593 throughout the SiliconInit flow as needed.
595 @param[in,out] FSP_MULTI_PHASE_PARAMS For action - EnumMultiPhaseGetNumberOfPhases:
596 FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr will contain
597 how many phases supported by FSP.
598 For action - EnumMultiPhaseExecutePhase:
599 FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr shall be NULL.
600 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
601 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
602 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
603 @retval EFI_DEVICE_ERROR FSP initialization failed.
604 @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.
608 (EFIAPI
*FSP_MULTI_PHASE_SI_INIT
)(
609 IN FSP_MULTI_PHASE_PARAMS
*MultiPhaseSiInitParamPtr