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>
17 /// FSP Reset Status code
18 /// These are defined in FSP EAS v2.4 section 13.2.2 - OEM Status Code
21 #define ENCODE_RESET_REQUEST(ResetType) \
22 ((EFI_STATUS)((MAX_BIT >> 1) | (ResetType)))
23 #define FSP_STATUS_RESET_REQUIRED_COLD ENCODE_RESET_REQUEST(1)
24 #define FSP_STATUS_RESET_REQUIRED_WARM ENCODE_RESET_REQUEST(2)
25 #define FSP_STATUS_RESET_REQUIRED_3 ENCODE_RESET_REQUEST(3)
26 #define FSP_STATUS_RESET_REQUIRED_4 ENCODE_RESET_REQUEST(4)
27 #define FSP_STATUS_RESET_REQUIRED_5 ENCODE_RESET_REQUEST(5)
28 #define FSP_STATUS_RESET_REQUIRED_6 ENCODE_RESET_REQUEST(6)
29 #define FSP_STATUS_RESET_REQUIRED_7 ENCODE_RESET_REQUEST(7)
30 #define FSP_STATUS_RESET_REQUIRED_8 ENCODE_RESET_REQUEST(8)
31 #define FSP_STATUS_VARIABLE_REQUEST ENCODE_RESET_REQUEST(10)
35 /// FSP Event related definition.
37 #define FSP_EVENT_CODE 0xF5000000
38 #define FSP_POST_CODE (FSP_EVENT_CODE | 0x00F80000)
41 FSP may optionally include the capability of generating events messages to aid in the debugging of firmware issues.
42 These events fall under three catagories: Error, Progress, and Debug. The event reporting mechanism follows the
43 status code services described in section 6 and 7 of the PI Specification v1.7 Volume 3.
45 @param[in] Type Indicates the type of event being reported.
46 See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_TYPE.
47 @param[in] Value Describes the current status of a hardware or software entity.
48 This includes information about the class and subclass that is used to classify the entity as well as an operation.
49 For progress events, the operation is the current activity. For error events, it is the exception.
50 For debug events, it is not defined at this time.
51 See MdePkg/Include/Pi/PiStatusCode.h for the definition of EFI_STATUS_CODE_VALUE.
52 @param[in] Instance The enumeration of a hardware or software entity within the system.
53 A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them.
54 An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant.
55 Valid instance numbers start with 1.
56 @param[in] *CallerId This parameter can be used to identify the sub-module within the FSP generating the event.
57 This parameter may be NULL.
58 @param[in] *Data This optional parameter may be used to pass additional data. The contents can have event-specific data.
59 For example, the FSP provides a EFI_STATUS_CODE_STRING_DATA instance to this parameter when sending debug messages.
60 This parameter is NULL when no additional data is provided.
62 @retval EFI_SUCCESS The event was handled successfully.
63 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
64 @retval EFI_DEVICE_ERROR The event handler failed.
68 (EFIAPI
*FSP_EVENT_HANDLER
)(
69 IN EFI_STATUS_CODE_TYPE Type
,
70 IN EFI_STATUS_CODE_VALUE Value
,
72 IN OPTIONAL EFI_GUID
*CallerId
,
73 IN OPTIONAL EFI_STATUS_CODE_DATA
*Data
77 Handler for FSP-T debug log messages, provided by the bootloader.
79 @param[in] DebugMessage A pointer to the debug message to be written to the log.
80 @param[in] MessageLength Number of bytes to written to the debug log.
82 @retval UINT32 The return value indicates the number of bytes actually written to
83 the debug log. If the return value is less than MessageLength,
88 (EFIAPI
*FSP_DEBUG_HANDLER
)(
89 IN CHAR8
*DebugMessage
,
90 IN UINT32 MessageLength
95 /// FSP_UPD_HEADER Configuration.
99 /// UPD Region Signature. This signature will be
100 /// "XXXXXX_T" for FSP-T
101 /// "XXXXXX_M" for FSP-M
102 /// "XXXXXX_S" for FSP-S
103 /// Where XXXXXX is an unique signature
107 /// Revision of the Data structure.
108 /// For FSP spec 2.0/2.1 value is 1.
109 /// For FSP spec 2.2 value is 2.
116 /// FSPT_ARCH_UPD Configuration.
120 /// Revision of the structure is 1 for this version of the specification.
125 /// Length of the structure in bytes. The current value for this field is 32.
129 /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages
130 /// occurring during FSP execution.
132 FSP_DEBUG_HANDLER FspDebugHandler
;
137 /// FSPT_ARCH2_UPD Configuration.
141 /// Revision of the structure is 2 for this version of the specification.
146 /// Length of the structure in bytes. The current value for this field is 32.
150 /// FspDebugHandler Optional debug handler for the bootloader to receive debug messages
151 /// occurring during FSP execution.
153 EFI_PHYSICAL_ADDRESS FspDebugHandler
;
158 /// FSPM_ARCH_UPD Configuration.
162 /// Revision of the structure. For FSP v2.0 value is 1.
167 /// Pointer to the non-volatile storage (NVS) data buffer.
168 /// If it is NULL it indicates the NVS data is not available.
172 /// Pointer to the temporary stack base address to be
173 /// consumed inside FspMemoryInit() API.
177 /// Temporary stack size to be consumed inside
178 /// FspMemoryInit() API.
182 /// Size of memory to be reserved by FSP below "top
183 /// of low usable memory" for bootloader usage.
185 UINT32 BootLoaderTolumSize
;
187 /// Current boot mode.
191 /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.
192 /// This value is only valid if Revision is >= 2.
194 FSP_EVENT_HANDLER
*FspEventHandler
;
199 /// FSPM_ARCH2_UPD Configuration.
203 /// Revision of the structure is 3 for this version of the specification.
208 /// Length of the structure in bytes. The current value for this field is 64.
212 /// Pointer to the temporary stack base address to be
213 /// consumed inside FspMemoryInit() API.
215 EFI_PHYSICAL_ADDRESS StackBase
;
217 /// Temporary stack size to be consumed inside
218 /// FspMemoryInit() API.
222 /// Size of memory to be reserved by FSP below "top
223 /// of low usable memory" for bootloader usage.
225 UINT32 BootLoaderTolumSize
;
227 /// Current boot mode.
231 /// Optional event handler for the bootloader to be informed of events occurring during FSP execution.
232 /// This value is only valid if Revision is >= 2.
234 EFI_PHYSICAL_ADDRESS FspEventHandler
;
239 /// FSPS_ARCH_UPD Configuration.
243 /// Revision of the structure is 1 for this version of the specification.
248 /// Length of the structure in bytes. The current value for this field is 32.
252 /// FspEventHandler Optional event handler for the bootloader to be informed of events
253 /// occurring during FSP execution.
255 FSP_EVENT_HANDLER FspEventHandler
;
257 /// A FSP binary may optionally implement multi-phase silicon initialization,
258 /// This is only supported if the FspMultiPhaseSiInitEntryOffset field in FSP_INFO_HEADER
260 /// To enable multi-phase silicon initialization, the bootloader must set
261 /// EnableMultiPhaseSiliconInit to a non-zero value.
263 UINT8 EnableMultiPhaseSiliconInit
;
268 /// FSPS_ARCH2_UPD Configuration.
272 /// Revision of the structure is 2 for this version of the specification.
277 /// Length of the structure in bytes. The current value for this field is 32.
281 /// FspEventHandler Optional event handler for the bootloader to be informed of events
282 /// occurring during FSP execution.
284 EFI_PHYSICAL_ADDRESS FspEventHandler
;
289 /// FSPT_UPD_COMMON Configuration.
293 /// FSP_UPD_HEADER Configuration.
295 FSP_UPD_HEADER FspUpdHeader
;
299 /// FSPT_UPD_COMMON Configuration for FSP spec. 2.2 and above.
303 /// FSP_UPD_HEADER Configuration.
305 FSP_UPD_HEADER FspUpdHeader
;
308 /// FSPT_ARCH_UPD Configuration.
310 FSPT_ARCH_UPD FsptArchUpd
;
311 } FSPT_UPD_COMMON_FSP22
;
314 /// FSPT_UPD_COMMON Configuration for FSP spec. 2.4 and above.
318 /// FSP_UPD_HEADER Configuration.
320 FSP_UPD_HEADER FspUpdHeader
;
323 /// FSPT_ARCH2_UPD Configuration.
325 FSPT_ARCH2_UPD FsptArchUpd
;
326 } FSPT_UPD_COMMON_FSP24
;
329 /// FSPM_UPD_COMMON Configuration.
333 /// FSP_UPD_HEADER Configuration.
335 FSP_UPD_HEADER FspUpdHeader
;
337 /// FSPM_ARCH_UPD Configuration.
339 FSPM_ARCH_UPD FspmArchUpd
;
343 /// FSPM_UPD_COMMON Configuration for FSP spec. 2.4 and above.
347 /// FSP_UPD_HEADER Configuration.
349 FSP_UPD_HEADER FspUpdHeader
;
351 /// FSPM_ARCH2_UPD Configuration.
353 FSPM_ARCH2_UPD FspmArchUpd
;
354 } FSPM_UPD_COMMON_FSP24
;
357 /// FSPS_UPD_COMMON Configuration.
361 /// FSP_UPD_HEADER Configuration.
363 FSP_UPD_HEADER FspUpdHeader
;
367 /// FSPS_UPD_COMMON Configuration for FSP spec. 2.2 and above.
371 /// FSP_UPD_HEADER Configuration.
373 FSP_UPD_HEADER FspUpdHeader
;
376 /// FSPS_ARCH_UPD Configuration.
378 FSPS_ARCH_UPD FspsArchUpd
;
379 } FSPS_UPD_COMMON_FSP22
;
382 /// FSPS_UPD_COMMON Configuration for FSP spec. 2.4 and above.
386 /// FSP_UPD_HEADER Configuration.
388 FSP_UPD_HEADER FspUpdHeader
;
391 /// FSPS_ARCH2_UPD Configuration.
393 FSPS_ARCH2_UPD FspsArchUpd
;
394 } FSPS_UPD_COMMON_FSP24
;
397 /// Enumeration of FSP_INIT_PHASE for NOTIFY_PHASE.
401 /// This stage is notified when the bootloader completes the
402 /// PCI enumeration and the resource allocation for the
403 /// PCI devices is complete.
405 EnumInitPhaseAfterPciEnumeration
= 0x20,
407 /// This stage is notified just before the bootloader hand-off
408 /// to the OS loader.
410 EnumInitPhaseReadyToBoot
= 0x40,
412 /// This stage is notified just before the firmware/Preboot
413 /// environment transfers management of all system resources
414 /// to the OS or next level execution environment.
416 EnumInitPhaseEndOfFirmware
= 0xF0
420 /// Definition of NOTIFY_PHASE_PARAMS.
424 /// Notification phase used for NotifyPhase API
426 FSP_INIT_PHASE Phase
;
427 } NOTIFY_PHASE_PARAMS
;
430 /// Action definition for FspMultiPhaseSiInit API
433 EnumMultiPhaseGetNumberOfPhases
= 0x0,
434 EnumMultiPhaseExecutePhase
= 0x1
435 } FSP_MULTI_PHASE_ACTION
;
438 /// Data structure returned by FSP when bootloader calling
439 /// FspMultiPhaseSiInit API with action 0 (EnumMultiPhaseGetNumberOfPhases)
442 UINT32 NumberOfPhases
;
443 UINT32 PhasesExecuted
;
444 } FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS
;
447 /// FspMultiPhaseSiInit function parameter.
449 /// For action 0 (EnumMultiPhaseGetNumberOfPhases):
450 /// - PhaseIndex must be 0.
451 /// - MultiPhaseParamPtr should point to an instance of FSP_MULTI_PHASE_GET_NUMBER_OF_PHASES_PARAMS.
453 /// For action 1 (EnumMultiPhaseExecutePhase):
454 /// - PhaseIndex will be the phase that will be executed by FSP.
455 /// - MultiPhaseParamPtr shall be NULL.
458 IN FSP_MULTI_PHASE_ACTION MultiPhaseAction
;
459 IN UINT32 PhaseIndex
;
460 IN OUT VOID
*MultiPhaseParamPtr
;
461 } FSP_MULTI_PHASE_PARAMS
;
466 This FSP API is called soon after coming out of reset and before memory and stack is
467 available. This FSP API will load the microcode update, enable code caching for the
468 region specified by the boot loader and also setup a temporary stack to be used until
469 main memory is initialized.
471 A hardcoded stack can be set up with the following values, and the "esp" register
472 initialized to point to this hardcoded stack.
473 1. The return address where the FSP will return control after setting up a temporary
475 2. A pointer to the input parameter structure
477 However, since the stack is in ROM and not writeable, this FSP API cannot be called
478 using the "call" instruction, but needs to be jumped to.
480 @param[in] FsptUpdDataPtr Pointer to the FSPT_UPD data structure.
482 @retval EFI_SUCCESS Temporary RAM was initialized successfully.
483 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
484 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
485 @retval EFI_DEVICE_ERROR Temp RAM initialization failed.
487 If this function is successful, the FSP initializes the ECX and EDX registers to point to
488 a temporary but writeable memory range available to the boot loader and returns with
489 FSP_SUCCESS in register EAX. Register ECX points to the start of this temporary
490 memory range and EDX points to the end of the range. Boot loader is free to use the
491 whole range described. Typically the boot loader can reload the ESP register to point
492 to the end of this returned range so that it can be used as a standard stack.
496 (EFIAPI
*FSP_TEMP_RAM_INIT
)(
497 IN VOID
*FsptUpdDataPtr
501 This FSP API is used to notify the FSP about the different phases in the boot process.
502 This allows the FSP to take appropriate actions as needed during different initialization
503 phases. The phases will be platform dependent and will be documented with the FSP
504 release. The current FSP supports two notify phases:
508 @param[in] NotifyPhaseParamPtr Address pointer to the NOTIFY_PHASE_PRAMS
510 @retval EFI_SUCCESS The notification was handled successfully.
511 @retval EFI_UNSUPPORTED The notification was not called in the proper order.
512 @retval EFI_INVALID_PARAMETER The notification code is invalid.
516 (EFIAPI
*FSP_NOTIFY_PHASE
)(
517 IN NOTIFY_PHASE_PARAMS
*NotifyPhaseParamPtr
521 This FSP API is called after TempRamInit and initializes the memory.
522 This FSP API accepts a pointer to a data structure that will be platform dependent
523 and defined for each FSP binary. This will be documented in Integration guide with
525 After FspMemInit completes its execution, it passes the pointer to the HobList and
526 returns to the boot loader from where it was called. BootLoader is responsible to
527 migrate its stack and data to Memory.
528 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
529 complete the silicon initialization and provides bootloader an opportunity to get
530 control after system memory is available and before the temporary RAM is torn down.
532 @param[in] FspmUpdDataPtr Pointer to the FSPM_UPD data structure.
533 @param[out] HobListPtr Pointer to receive the address of the HOB list.
535 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
536 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
537 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
538 @retval EFI_DEVICE_ERROR FSP initialization failed.
539 @retval EFI_OUT_OF_RESOURCES Stack range requested by FSP is not met.
540 @retval FSP_STATUS_RESET_REQUIREDx A reset is reuired. These status codes will not be returned during S3.
544 (EFIAPI
*FSP_MEMORY_INIT
)(
545 IN VOID
*FspmUpdDataPtr
,
546 OUT VOID
**HobListPtr
550 This FSP API is called after FspMemoryInit API. This FSP API tears down the temporary
551 memory setup by TempRamInit API. This FSP API accepts a pointer to a data structure
552 that will be platform dependent and defined for each FSP binary. This will be
553 documented in Integration Guide.
554 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to
555 complete the silicon initialization and provides bootloader an opportunity to get
556 control after system memory is available and before the temporary RAM is torn down.
558 @param[in] TempRamExitParamPtr Pointer to the Temp Ram Exit parameters structure.
559 This structure is normally defined in the Integration Guide.
560 And if it is not defined in the Integration Guide, pass NULL.
562 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
563 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
564 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
565 @retval EFI_DEVICE_ERROR FSP initialization failed.
569 (EFIAPI
*FSP_TEMP_RAM_EXIT
)(
570 IN VOID
*TempRamExitParamPtr
574 This FSP API is called after TempRamExit API.
575 FspMemoryInit, TempRamExit and FspSiliconInit APIs provide an alternate method to complete the
576 silicon initialization.
578 @param[in] FspsUpdDataPtr Pointer to the FSPS_UPD data structure.
579 If NULL, FSP will use the default parameters.
581 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
582 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
583 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
584 @retval EFI_DEVICE_ERROR FSP initialization failed.
585 @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.
589 (EFIAPI
*FSP_SILICON_INIT
)(
590 IN VOID
*FspsUpdDataPtr
594 This FSP API is expected to be called after FspSiliconInit but before FspNotifyPhase.
595 This FSP API provides multi-phase silicon initialization; which brings greater modularity
596 beyond the existing FspSiliconInit() API. Increased modularity is achieved by adding an
597 extra API to FSP-S. This allows the bootloader to add board specific initialization steps
598 throughout the SiliconInit flow as needed.
600 @param[in,out] FSP_MULTI_PHASE_PARAMS For action - EnumMultiPhaseGetNumberOfPhases:
601 FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr will contain
602 how many phases supported by FSP.
603 For action - EnumMultiPhaseExecutePhase:
604 FSP_MULTI_PHASE_PARAMS->MultiPhaseParamPtr shall be NULL.
605 @retval EFI_SUCCESS FSP execution environment was initialized successfully.
606 @retval EFI_INVALID_PARAMETER Input parameters are invalid.
607 @retval EFI_UNSUPPORTED The FSP calling conditions were not met.
608 @retval EFI_DEVICE_ERROR FSP initialization failed.
609 @retval FSP_STATUS_RESET_REQUIREDx A reset is required. These status codes will not be returned during S3.
613 (EFIAPI
*FSP_MULTI_PHASE_SI_INIT
)(
614 IN FSP_MULTI_PHASE_PARAMS
*MultiPhaseSiInitParamPtr