DoxygenFspIntegrationGuide.h

Go to the documentation of this file.

/** @file
  This file contains doxygen KabylakeFspIntegration Guide

@copyright
  Copyright (c) 2015 - 2018 Intel Corporation. All rights reserved
  This software and associated documentation (if any) is furnished
  under a license and may only be used or copied in accordance
  with the terms of the license. Except as permitted by such
  license, no part of this software or documentation may be
  reproduced, stored in a retrieval system, or transmitted in any
  form or by any means without the express written consent of
  Intel Corporation.
  This file contains an 'Intel Peripheral Driver' and uniquely
  identified as "Intel Reference Module" and is
  licensed for Intel CPUs and chipsets under the terms of your
  license agreement with Intel or your vendor.  This file may
  be modified by the user, subject to additional terms of the
  license agreement
**/

/** @mainpage INTRODUCTION

# 1 Introduction

## 1.1 Purpose
  The purpose of this document is to describe the steps required to integrate the Intel® Firmware
  Support Package (FSP) into a boot loader solution. It supports Kabylake platforms with Kabylake/Skylake
  processor and Sunrise point Platform Controller Hub (PCH).</P>

## 1.2 Intended Audience
  This document is targeted at all platform and system developers who need to consume FSP binaries
  in their boot loader solutions. This includes, but is not limited to: system BIOS developers, boot
  loader developers, system integrators, as well as end users.</P>

## 1.3 Related Documents
  - *Platform Initialization (PI) Specification v1.4* located at http://www.uefi.org/specifications
  - *UEFI Specification v2.5* located at http://www.uefi.org/specifications
  - *Intel&reg; Firmware Support Package: External Architecture Specification (EAS) v2.0* located at 
  http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v2.pdf
  - *Boot Setting File Specification (BSF) v1.0* https://firmware.intel.com/sites/default/files/BSF_1_0.pdf
  - *Binary Configuration Tool for Intel&reg; Firmware Support Package* available at http://www.intel.com/fsp

## 1.4 Acronyms and Terminology

Acronym | Definition
--------|-----------
BCT     | Binary Configuration Tool
BSF     | Boot Setting File
BSP     | Boot Strap Processor
BWG     | BIOS Writer&apos;s Guide
CAR     | Cache As Ram
CRB     | Customer Reference Board
FIT     | Firmware Interface Table
FSP     | Firmware Support Package
FSP API | Firmware Support Package Interface
FW      | Firmware
PCH     | Platform Controller Hub
PMC     | Power Management Controller
SBSP    | System BSP
SMI     | System Management Interrupt
SMM     | System Management Mode
SPI     | Serial Peripheral Interface
TSEG    | Memory Reserved at the Top of Memory to be used as SMRAM
UPD     | Updatable Product Data

**/

/** @page  fsp_overview FSP OVERVIEW
# FSP Overview
## 2.1 Technical Overview
  The *Intel&reg; Firmware Support Package (FSP)* provides chipset and processor initialization in a
  format that can easily be incorporated into many existing boot loaders.

  The FSP will perform the necessary initialization steps as documented in the BWG including
  initialization of the CPU, memory controller, chipset and certain bus interfaces, if necessary.

  FSP is not a stand-alone boot loader; therefore it needs to be integrated into a host boot loader
  to carry out other boot loader functions, such as: initializing non-Intel components, conducting
  bus enumeration, and discovering devices in the system and all industry standard initialization.

  The FSP binary can be integrated easily into many different boot loaders, such as Coreboot, EDKII etc.
  and also into the embedded OS directly.

  Below are some required steps for the integration:

    - **Customizing**
        The static FSP configuration parameters are part of the FSP binary and can be customized by external
        tools that will be provided by Intel.

    - **Rebasing**
        The FSP is not Position Independent Code (PIC) and the whole FSP has to be rebased if it is placed
        at a location which is different from the preferred address during build process.

    - **Placing**
        Once the FSP binary is ready for integration, the boot loader build process needs to be modified to
        place this FSP binary at the specific rebasing location identified above.

    - **Interfacing**
        The boot loader needs to add code to setup the operating environment for the FSP, call the FSP with
        correct parameters and parse the FSP output to retrieve the necessary information returned by the FSP.

## 2.2 FSP Distribution Package
  - The FSP distribution package contains the following:
    - FSP Binary
    - FSP Integration Guide
    - BSF Configuration File
    - Data Structure Header File

  - The FSP configuration utility called BCT is available as a separate package.
    It can be downloaded from link mentioned in Section 1.3.

### 2.2.1 Package Layout
  - **Docs (Auto generated)**
      - Kabylake_FSP_Integration_Guide.pdf (this doc)
      - Kabylake_FSP_Integration_Guide.chm

  - **Include**
      - FsptUpd.h, FspmUpd.h and FspsUpd.h (FSP UPD structure and related definitions)
      - GpioSampleDef.h (Sample enum definitions for Gpio table)
  - KabylakeFspBinPkg.dec (EDKII declaration file for package)
  - Fsp.bsf (BSF file for configuring the data using BCT tool)
  - Fsp.fd (FSP Binary)
**/

/** @page fsp_integration FSP INTEGRATION
# 3 FSP Integration

## 3.1 Assumptions Used in this Document
  The FSP for the Kabylake platform is built with a preferred base address of 0xFFF40000 and so the
  reference code provided in the document assumes that the FSP is placed at this base address during
  the final boot loader build. Users may rebase the FSP binary at a different location with
  Intel&apos;s Binary Configuration Tool (BCT) before integrating to the boot loader.

  For other assumptions and conventions, please refer section 8 in the FSP External Architecture
  Specification version 2.0.

## 3.2 Boot Flow
  Please refer Chapter 7 in the FSP External Architecture Specification version 2.0 for Boot flow chart.

## 3.3 FSP INFO Header
  The FSP has an Information Header that provides critical information that is required by the
  bootloader to successfully interface with the FSP. The structure of the FSP Information Header
  is documented in the FSP External Architecture Specification version 2.0 with a HeaderRevision of 3.

## 3.4 FSP Image ID and Revision
  FSP information header contains an Image ID field and an Image Revision field that provide the
  identification and revision information of the FSP binary. It is important to verify these fields
  while integrating the FSP as API parameters could change over different FSP IDs and revisions. 
  All the FSP FV segments(FSP-T, FSP-M and FSP-S) must have same FSP Image ID and revision number,
  using FV segments with different revision numbers in a single FSP image is not valid. The FSP 
  API parameters documented in this integration guide are applicable for the Image ID and
  Revision specified as below. 

  The current FSP ImageId string in the FSP information header is <strong>$KBLFSP$</strong> and the
  ImageRevision field is **0x03060000.(3.6.0.0)**.

## 3.5 FSP Global Data
  FSP uses some amount of TempRam area to store FSP global data which contains some critical data like
  pointers to FSP information headers and UPD configuration regions, FSP/Bootloader stack pointers 
  required for stack switching etc. HPET Timer register(2) 0xFED00148 is reserved to store address 
  of this global data, and hence boot loader should not use this register for any other purpose. 
  If TempRAM initialization is done by boot loader, then HPET has to be initialized to the base so 
  that access to this register will work fine. 
 
## 3.6 FSP APIs
  This release of the Kabylake FSP supports the all APIs required by the FSP External
  Architecture Specification version 2.0.
  The FSP information header contains the address offset for these APIs. Register usage is
  described in the FSP External Architecture Specification version 2.0. Any usage not described
  by the specification is described in the individual sections below.

  The below sections will highlight any changes that are specific to this FSP release.

### 3.6.1 TempRamInit API
  Please refer Chapter 8.5 in the FSP External Architecture Specification version 2.0 for complete
  details including the prototype, parameters and return value details for this API.

  TempRamInit does basic early initialization primarily setting up temporary RAM using cache. It
  returns ECX pointing to beginning of temporary memory and EDX pointing to end of temporary memory + 1.
  The total temporary ram currently available is from 0xFEF0_0000 to 0xFEF4_0000 out of which  
  0xFEF0_0000(ECX) to 0xFEF3_FF00(EDX) is usable area for both bootloader and FSP binary, remaining
  0x100 bytes of space reserved by FSP for TempRamInit if temporary RAM initialization is done by FSP.

  **TempRamInit** also sets up the code caching of the region passed CodeCacheBase and CodeCacheLength,
  which are input parameters to TempRamInitApi. if 0 is passed in for CodeCacheBase, the base used will
  be 4 GB - 1 - length to be code cached instead of starting from CodeCacheBase.
  @note: when programming MTRR CodeCacheLength will be reduced, if SKU LLC size is smaller than the requested.

  It is a requirement for Firmware to have Firmware Interface Table (FIT), which contains pointers to
  each microcode update. The microcode update is loaded for all logical processors before reset
  vector. If more than microcode update for the CPU is present, the microcode update with the
  latest revision is loaded.

  **FSPT_UPD.MicrocodeRegionBase** and **FSPT_UPD.MicrocodeRegionLength** are input parameters to TempRamInit API. 
  If these values are 0, FSP will not attempt to update microcode. If a region is passed, then if a newer
  microcode update revision is in the region, it will be loaded by the FSP.
 
  MTRRs are programmed to the default values to have the following memory map:

  Memory range                           | Cache Attribute
  ---------------------------------------|-----------------
  0xFEF00000    - 0x00040000             | Write back
  CodeCacheBase - CodeCacheLength        | Write protect

### 3.6.2 FspMemoryInit API
  Please refer to Chapter 8.6 in the FSP external Architecture Specification version 2.0 for the
  prototype, parameters and return value details for this API.

  The **FspmUpdPtr** is pointer to **FSPM_UPD** structure which is described in header file FspmUpd.h.

  Boot Loader must pass valid CAR region for FSP stack use through **FSPM_UPD.FspmArchUpd.StackBase**
  and **FSPM_UPD.FspmArchUpd.StackSize** UPDs.
 
  The minimum FSP stack size required for this revision of FSP is 160KB, stack base is 0xFEF17F00 by default. 

  The base address of HECI device (Bus 0, Device 22, Function 0) is required to be initialized prior
  to perform FspMemoryInit flow. The default address is programmed to 0xFED1A000.

  Calculate memory map determining memory regions TSEG, IED, GTT, BDSM, ME stolen, Uncore PMRR, IOT,
  MOT, DPR, REMAP, TOLUD, TOUUD. Programming will be done at a different time.

#### 3.6.3 TempRamExit API
  Please refer to Chapter 8.7 in the FSP external Architecture Specification version 2.0 for the
  prototype, parameters and return value details for this API.

  If Boot Loader initializes the Temporary RAM (CAR) and skip calling **TempRamInit API**, it is expected that
  bootloader must skip calling this API and bootloader will tear down the temporary memory area setup in the
  cache and bring the cache to normal mode of operation.

  This revision of FSP doesn't have any fields/structure to pass as parameter for this API.
  Pass Null for *TempRamExitParamPtr*.

  At the end of *TempRamExit* the original code and data caching are disabled.  FSP will reconfigure all MTRRs
  as described in the table below for performance optimization.

  Memory range                           | Cache Attribute
  ---------------------------------------|-----------------
  0x00000000 - 0x0009FFFF                | Write back
  0x000C0000 - Top of Low Memory         | Write back
  0xFF800000 - 0xFFFFFFFF (Flash region) | Write protect
  0x1000000000 - Top of High Memory      | Write back

  If the boot loader wish to reconfigure the MTRRs differently, it can be overridden immediately after this API call.

### 3.6.4 FspSiliconInit API
  Please refer to Chapter 8.8 in the FSP external Architecture Specification version 2.0 for the
  prototype, parameters and return value details for this API.

  The *FspsUpdPtr* is pointer to **FSPS_UPD** structure which is described in header file FspsUpd.h.

  It is expected that boot loader will program MTRRs for SBSP as needed after **TempRamExit** but before
  entering **FspSiliconInit**. If MTRRs are not programmed properly, the boot performance
  might be impacted.

  The region of 0x5_8000 - 0x5_8FFF is used by FspSilicionInit for starting APs. If this data
  is important to bootloader, then bootloader needs to preserve it before calling FspSilicionInit.

  It is a requirement for bootloader to have Firmware Interface Table (FIT), which contains pointers
  to each microcode. The microcode is loaded for all cores before reset vector. If more than one
  microcode update for the CPU is present, the latest revision is loaded.

  MicrocodeRegionBase and MicrocodeRegionLength are both input parameters to TempRamInit
  and UPD for SiliconInit API. UPD has priority and will be searched for a later revision
  than TempRamInit. If MicrocodeRegionBase and MicrocodeRegionLength values are 0, FSP will
  not attempt to update the microcode. If a microcode region is passed, and if a later
  revision of microcode is present in this region, FSP will load it.

  FSP initializes PCH audio including selecting HD Audio verb table and initializes Codec.

  PCH required initialization is done for the following HECI, USB, HSIO, Integrated Sensor Hub,
  Display, Sky Cam, Camera, PCI Express, Vt-d, straps (cores, hyper-threading, BIST, ..)

  FSP initializes CPU features: XD, VMX, AES, IED, HDC, x(2)Apic, Intel&reg; Processor Trace,
  Three strike counter, Machine check, Cache pre-fetchers, Core PMRR, Power management.

  Initializes HECI, DMI, Internal Graphics. Publish EFI_PEI_GRAPHICS_INFO_HOB during normal boot
  but this HOB will not be published during S3 resume as FSP will not launch the PEI Graphics PEIM
  during S3 resume.

  Programs SA Bars: MchBar, DmiBar, EpBar, GdxcBar, EDRAM (if supported). Please refer to section
  2.8 (MemoryMap)  for the corresponding Bar values. GttMmadr (0xDF000000) and GmAdr(0xC0000000)
  are temporarily programmed and cleared after use in FSP.

  On normal boot CPU S3 Resume Data HOB is produced in this phase. This CPU S3 Resume Data HOB is described
  in section 4.4. Unless UPD SkipMpInit is enabled, on S3 resume, this data (not the entire HOB) must be passed through
  UPD CpuS3ResumeData, and optionally final S3 boot MTRRs is passed through UPD CpuS3ResumeMtrrData. During S3
  resume unless SkipMpInit is enabled, GDT base and length and IDT base and length on APs are programmed
  to that of the BSP.

### 3.6.5 NotifyPhase API
  Please refer Chapter 8.9 in the FSP External Architecture Specification version 2.0 for the
  prototype, parameters and return value details for this API.

#### 3.6.5.1 PostPciEnumeration Notification
  This phase *EnumInitPhaseAfterPciEnumeration* is to be called after PCI enumeration but before
  execution of third party code such as option ROMs. Currently, nothing is done in this phase,
  but in the future updates, programming may be done in this phase.

#### 3.6.5.2 ReadyToBoot Notification
  This phase *EnumInitPhaseReadyToBoot* is to be called before giving control to boot. It includes some
  final initialization steps recommended by the BWG, including power management settings, Send ME Message
  EOP (End of Post).

#### 3.6.5.3 EndOfFirmware Notification
  This phase *EnumInitEndOfFirmware* is to be called before the firmware/preboot environment transfers
  management of all system resources to the OS or next level execution environment. It includes final locking
  of chipset registers  
 
## 3.7 Memory Map
  Below diagram represents the memory map allocated by FSP including the FSP specific regions.
![System Memory Map](KabylakeMemoryMap.jpg)

## 3.8 Porting recommendation
  Here listed some notes or recommendation when porting with FSP.

### 3.8.1 Locking PAM register
  FSP 2.0 introduced EndOfFirmware Notify phase callback which is a recommended place for locking PAM registers
  so FSP by default implemented this way. If it is still too early to lock PAM registers then the PAM locking code
  inside FSP can be disabled by UPD -> FSP_S_TEST_CONFIG -> SkipPamLock or SA policy -> _SI_PREMEM_POLICY_STRUCT 
  -> SA_MISC_PEI_CONFIG -> SkipPamLock, and platform or wrapper code should do the PAM locking right before booting
  OS (so do it outside FSP instead) by programming one PCI config space register as below.
 
  This PAM locking step has to been applied in all boot paths including S3 resume.To lock PAM regsiter: 

~~~
    MmioOr32 (B0: D0: F0: Register 0x80, BIT0)
~~~

### 3.8.2 Locking SMRAM register
  Since SMRAM locking is recommended to be locked before any 3rd party OpROM execution and highly depending on platform code implementation, the FSP code by default will not lock it.
  The platform or FSP Wrapper code should lock SMRAM by below programming step before any 3rd partiy OpRom execution (and should be locked in S3 resume right before OS waking vector).
~~~
    PciOr8 (B0: D0: F0: Register 0x88, BIT4); Note: it must be programmed by CF8/CFC Standard PCI access mechanism. (MMIO access will not work)
~~~

### 3.8.3 Locking SMI register
  Global SMI bit is recommended to be locked before any 3rd party OpROM execution and highly depending on platform code implementation after SMM configuration. FSP by default will not lock it.
  Boot loader is responsible for locking below regsiters after SMM configuration.
      Set AcpiBase + 0x30[0] to 1b to enable global SMI.
      Set PMC PCI offset A0h[4] = 1b to lock SMI.

### 3.8.4 Verify below settings are correct for your platforms

  Settings               | Values
  ---------------------------------|------------------------
  PCIEXBAR_BASE_ADDRESS            | 0xE0000000  -> PciExBar
  MCH_BASE_ADDRESS                 | 0xFED10000  -> MchBar
  DMI_BASE_ADDRESS                 | 0xFED18000  -> DmiBar
  EP_BASE_ADDRESS                  | 0xFED19000  -> EpBar
  EDRAM_BASE_ADDRESS               | 0xFED80000  -> EdramBar
  DEFAULT_OPTION_ROM_TEMP_BAR      | 0x80000000  -> OpRomScanTempMmioBar
  DEFAULT_OPTION_ROM_TEMP_MEM_LIMIT| 0xC0000000  -> OpRomScanTempMmioLimit
  @note:\n
    - It is recommended that you do not change these settings as it may require significant changes to the System Agent reference code.\n
    - Those memory regions should be reserved from any memory service functions in platform code so it will not cause any conflict when other modules or drivers allocating memory resource.
    - Boot Loader can use different value for PCIEXBAR_BASE_ADDRESS either by modifying the UPD (under FSP-T) or by overriding the PCIEXBAR (B0:D0:F0:R60h) before calling FspMemoryInit Api.
    - Boot Loader should avoid using conflicting address when reprogramming PCIEXBAR_BASE_ADDRESS than the recommended one.

### 3.8.5 FSP_STATUS_RESET_REQUIRED
  As per FSP External Architecture Specification version 2.0, Any reset required in the FSP flow will
  be reported as return status FSP_STATUS_RESET_REQUIREDx by the API.It is the bootloader responsibility to reset the system according to the reset type requested.

  Below table specifies the return status returned by FSP API and the requested reset type.

FSP_STATUS_RESET_REQUIRED Code | Reset Type requested
-------------------------------|----------------------
0x40000001 | Cold Reset
0x40000002 | Warm Reset
0x40000003 | Global Reset - Puts the system to Global reset through Heci or Full Reset through PCH
0x40000004 | Reserved
0x40000005 | Reserved
0x40000006 | Reserved
0x40000007 | Reserved
0x40000008 | Reserved
**/
/** @page fsp_output FSP OUTPUT
# 4 FSP Output
  The FSP builds a series of data structures called the Hand-Off-Blocks (HOBs) as it progresses
  through initializing the silicon. 
  Please refer to the Platform Initialization (PI) Specification - Volume 3: Shared Architectural
  Elements specification for PI Architectural HOBs.Please refer Chapter 9 in the FSP External Architecture 
  Specification version 2.0 for details about FSP Architectural HOBs.

  Below section describe the HOBs not covered in the above two specifications.

## 4.1 SMRAM Resource Descriptor HOB
  The FSP will report the system SMRAM T-SEG range through a generic resource HOB if T-SEG is
  enabled. The owner field of the HOB identifies the owner as T-SEG.

~~~
#define FSP_HOB_RESOURCE_OWNER_TSEG_GUID  \
{ 0xd038747c, 0xd00c, 0x4980, { 0xb3, 0x19, 0x49, 0x01, 0x99, 0xa4, 0x7d, 0x55 } }
~~~

## 4.2 SMBIOS INFO HOB
  The FSP will report the SMBIOS through a HOB with below GUID. This information can be consumed
  by the bootloader to produce the SMBIOS tables. These structures are included as part of MemInfoHob.h , SmbiosCacheInfoHob.h & SmbiosProcessorInfoHob.h.
  Note: The Smbios Cache Info Hob & Smbios Processor Info Hob won't be published on S3 boot.
~~~
#define SI_MEMORY_INFO_DATA_HOB_GUID \ 
{ 0x9b2071d4, 0xb054, 0x4e0c, { 0x8d, 0x09, 0x11, 0xcf, 0x8b, 0x9f, 0x03, 0x23 } };

typedef struct {
  MrcDimmStatus Status;                     ///< See MrcDimmStatus for the definition of this field.
  UINT8         DimmId;
  UINT32        DimmCapacity;               ///< DIMM size in MBytes.
  UINT16        MfgId;
  UINT8         ModulePartNum[20];          ///< Module part number for DDR3 is 18 bytes however for DRR4 20 bytes as per JEDEC Spec, so reserving 20 bytes
  UINT8         RankInDimm;                 ///< The number of ranks in this DIMM.
  UINT8         SpdDramDeviceType;          ///< Save SPD DramDeviceType information needed for SMBIOS structure creation.
  UINT8         SpdModuleType;              ///< Save SPD ModuleType information needed for SMBIOS structure creation.
  UINT8         SpdModuleMemoryBusWidth;    ///< Save SPD ModuleMemoryBusWidth information needed for SMBIOS structure creation.
  UINT8         SpdSave[MAX_SPD_SAVE_DATA]; ///< Save SPD Manufacturing information needed for SMBIOS structure creation.
} DIMM_INFO;

typedef struct {
  UINT8         Status;                     ///< Indicates whether this channel should be used.
  UINT8         ChannelId;
  UINT8         DimmCount;                  ///< Number of valid DIMMs that exist in the channel.
  MRC_CH_TIMING Timing[MAX_PROFILE];        ///< The channel timing values.
  DIMM_INFO     Dimm[MAX_DIMM];             ///< Save the DIMM output characteristics.
} CHANNEL_INFO;

typedef struct {
  UINT8            Status;                  ///< Indicates whether this controller should be used.
  UINT16           DeviceId;                ///< The PCI device id of this memory controller.
  UINT8            RevisionId;              ///< The PCI revision id of this memory controller.
  UINT8            ChannelCount;            ///< Number of valid channels that exist on the controller.
  CHANNEL_INFO     Channel[MAX_CH];         ///< The following are channel level definitions.
} CONTROLLER_INFO;

typedef struct {
  EFI_HOB_GUID_TYPE EfiHobGuidType;
  UINT8             Revision;
  UINT16            DataWidth;
  /// As defined in SMBIOS 3.0 spec
  /// Section 7.18.2 and Table 75
  UINT8             DdrType;                ///< DDR type: DDR3, DDR4, or LPDDR3
  UINT32            Frequency;              ///< The system's common memory controller frequency in MT/s.
  /// As defined in SMBIOS 3.0 spec
  /// Section 7.17.3 and Table 72
  UINT8             ErrorCorrectionType;

  SiMrcVersion      Version;
  UINT32            FreqMax;
  BOOLEAN           EccSupport;
  UINT8             MemoryProfile;
  UINT32            TotalPhysicalMemorySize;
  BOOLEAN           XmpProfileEnable;
  UINT8             Ratio;
  UINT8             RefClk;
  UINT32            VddVoltage[MAX_PROFILE];
  CONTROLLER_INFO   Controller[MAX_NODE];
} MEMORY_INFO_DATA_HOB;

#define  SI_MEMORY_PLATFORM_DATA_HOB \
  { 0x6210d62f, 0x418d, 0x4999, { 0xa2, 0x45, 0x22, 0x10, 0x0a, 0x5d, 0xea, 0x44 } }

typedef struct {
  UINT8             Revision;
  UINT8             Reserved[3];
  UINT32            BootMode;
  UINT32            TsegSize;
  UINT32            TsegBase;
  UINT32            PrmrrSize;
  UINT32            PrmrrBase;
  UINT32            GttBase;
  UINT32            MmioSize;
  UINT32            PciEBaseAddress;
} MEMORY_PLATFORM_DATA;

typedef struct {
  EFI_HOB_GUID_TYPE    EfiHobGuidType;
  MEMORY_PLATFORM_DATA Data;
  UINT8                *Buffer;
} MEMORY_PLATFORM_DATA_HOB;

#define SMBIOS_CACHE_INFO_HOB_GUID \ 
 { 0xd805b74e, 0x1460, 0x4755, {0xbb, 0x36, 0x1e, 0x8c, 0x8a, 0xd6, 0x78, 0xd7} }

///
/// SMBIOS Cache Info HOB Structure
///
typedef struct {
  UINT16     ProcessorSocketNumber;
  UINT16     NumberOfCacheLevels;         ///< Based on Number of Cache Types L1/L2/L3
  UINT8      SocketDesignationStrIndex;   ///< String Index in the string Buffer. Example "L1-CACHE"
  UINT16     CacheConfiguration;          ///< Format defined in SMBIOS Spec v3.0 Section7.8 Table36
  UINT16     MaxCacheSize;                ///< Format defined in SMBIOS Spec v3.0 Section7.8.1
  UINT16     InstalledSize;               ///< Format defined in SMBIOS Spec v3.0 Section7.8.1
  UINT16     SupportedSramType;           ///< Format defined in SMBIOS Spec v3.0 Section7.8.2
  UINT16     CurrentSramType;             ///< Format defined in SMBIOS Spec v3.0 Section7.8.2
  UINT8      CacheSpeed;                  ///< Cache Speed in nanoseconds. 0 if speed is unknown.
  UINT8      ErrorCorrectionType;         ///< ENUM Format defined in SMBIOS Spec v3.0 Section 7.8.3
  UINT8      SystemCacheType;             ///< ENUM Format defined in SMBIOS Spec v3.0 Section 7.8.4
  UINT8      Associativity;               ///< ENUM Format defined in SMBIOS Spec v3.0 Section 7.8.5
  ///String Buffer - each string terminated by NULL "0x00"
  ///String buffer terminated by double NULL "0x0000"
} SMBIOS_CACHE_INFO;

#define SMBIOS_PROCESSOR_INFO_HOB_GUID \ 
  { 0xe6d73d92, 0xff56, 0x4146, {0xaf, 0xac, 0x1c, 0x18, 0x81, 0x7d, 0x68, 0x71} }
///
/// SMBIOS Processor Info HOB Structure
///
typedef struct {
  UINT16     TotalNumberOfSockets;
  UINT16     CurrentSocketNumber;
  UINT8      ProcessorType;                 ///< ENUM defined in SMBIOS Spec v3.0 Section 7.5.1
  ///This info is used for both ProcessorFamily and ProcessorFamily2 fields
  ///See ENUM defined in SMBIOS Spec v3.0 Section 7.5.2
  UINT16     ProcessorFamily;
  UINT8      ProcessorManufacturerStrIndex; ///< Index of the String in the String Buffer
  UINT64     ProcessorId;                   ///< ENUM defined in SMBIOS Spec v3.0 Section 7.5.3
  UINT8      ProcessorVersionStrIndex;      ///< Index of the String in the String Buffer
  UINT8      Voltage;                       ///< Format defined in SMBIOS Spec v3.0 Section 7.5.4
  UINT16     ExternalClockInMHz;            ///< External Clock Frequency. Set to 0 if unknown.
  UINT16     CurrentSpeedInMHz;             ///< Snapshot of current processor speed during boot
  UINT8      Status;                        ///< Format defined in the SMBIOS Spec v3.0 Table 21
  UINT8      ProcessorUpgrade;              ///< ENUM defined in SMBIOS Spec v3.0 Section 7.5.5
  ///This info is used for both CoreCount & CoreCount2 fields
  /// See detailed description in SMBIOS Spec v3.0 Section 7.5.6
  UINT16     CoreCount;
  ///This info is used for both CoreEnabled & CoreEnabled2 fields
  ///See detailed description in SMBIOS Spec v3.0 Section 7.5.7
  UINT16     EnabledCoreCount;
  ///This info is used for both ThreadCount & ThreadCount2 fields
  /// See detailed description in SMBIOS Spec v3.0 Section 7.5.8
  UINT16     ThreadCount;
  UINT16     ProcessorCharacteristics;      ///< Format defined in SMBIOS Spec v3.0 Section 7.5.9
  /// String Buffer - each string terminated by NULL "0x00"
  /// String buffer terminated by double NULL "0x0000"  
} SMBIOS_PROCESSOR_INFO;
~~~

## 4.3 CHIPSETINIT INFO HOB
  The FSP will report the ChipsetInit CRC through a HOB with below GUID. This information can be consumed
  by the bootloader to check if ChipsetInit CRC is matched between BIOS and ME. These structures are included 
  as part of FspsUpd.h

~~~
#define CHIPSETINIT_INFO_HOB_GUID \
{ 0xc1392859, 0x1f65, 0x446e, { 0xb3, 0xf5, 0x84, 0x35, 0xfc, 0xc7, 0xd1, 0xc4 }}

///
/// The ChipsetInit Info structure provides the information of ME ChipsetInit CRC and BIOS ChipsetInit CRC.
///
typedef struct {
  UINT8             Revision;
  UINT8             Rsvd[3];
  UINT16            MeChipInitCrc;
  UINT16            BiosChipInitCrc;
} CHIPSET_INIT_INFO;

~~~

## 4.4 CPU S3 Resume Data HOB
  The FSP will report the CPU S3 Resume Data through a GUIDED HOB with below GUID. This data (not the entire HOB) must be passed during S3 resume passed
  in UPD CpuS3ResumeData except if UPD SkipMpInit is enabled.

~~~
#define CPU_S3_RESUME_DATA_HOB_GUID \
{ 0x3972d4c1, 0xf206, 0x463f, { 0x80, 0xa4, 0xd9, 0x62, 0x79, 0x0a, 0xe5, 0x49 }}
~~~

**/
/** @page fsp_postcode FSP POSTCODE
# 5 FSP PostCode
  The FSP outputs 16 bit postcode to indicate which API and in which module the execution is happening.

  Bit Range          | Description
  -------------------|------------
  Bit15 - Bit12 (X)  | used to indicate the phase/api under which the code is executing
  Bit11 - Bit8 (Y)   | used to indicate the module
  Bit7 (ZZ bit 7)    | reserved for error
  Bit6 - Bit0 (ZZ)   | individual codes

## 5.1 PostCode Info
  Below diagram represents the 16 bit PostCode usage in FSP.

@dot
digraph structs {
    node [shape=record, width=3, height=1];
    struct1 [style=bold,label="<f0> X|<f1> Y|<f2> ZZ"];
    struct2 [label="<f0> FSP API - 4 BITS (one Digit)\n
F - Tempraminit /SEC \l
E - Reserved \l
D - MemoryInit /Pre-Memory \l
C - Reserved \l
B - Tempramexit \l
A - Reserved \l
9 - SiliconInit /Post Memory \l
8 - Reserved \l
7 - Reserved \l
6 - Notify / Post PCIE Enumeration \l
5 - Reserved \l
4 - Notify / Ready To Boot \l
3 - Reserved \l
2 - Notify / End Of Firmware \l
1-0 - Reserved\l"];
    struct3 [label="<f0> Module -  4 BITS (one digit)\n
7 - Gfx PEIM \l
8 - FSP Common Code \l
9 - Silicon Common Code \l
A - System Agent \l
B - PCH \l
C - CPU \l
D - MRC \l
E - ME-BIOS \l
F - Reserved \l
"];
    struct4 [label="<f0>Individual Codes\n
0x00 - API Entry \l
0x7F - API Exit \l

(Bit7 reserved for error)\l
 "];
    struct1:f0 -> struct2:f0;
    struct1:f1 -> struct3:f0;
    struct1:f2 -> struct4:f0;
}
@enddot


### 5.1.1 TempRamInit API Status Codes (0xFxxx)

PostCode | Module | Description
---------|--------|-----------------
0x0000   | FSP    | TempRamInit API Entry (The change in upper byte is due to not enabling of the Port81 early in the boot)
0x007F   | FSP    | TempRamInit API Exit

### 5.1.2 FspMemoryInit API Status Codes (0xDxxx)

PostCode | Module | Description
---------|--------|-----------------
0xD800   | FSP    | FspMemoryInit API Entry
0xD87F   | FSP    | FSpMemoryInit API Exit
0xDA00   | SA     | Pre-Mem SaInit Entry
0xDA01   | SA     | DeviceConfigurePreMem Start
0xDA02   | SA     | OverrideDev0Did Start
0xDA04   | SA     | OverrideDev2Did Start
0xDA06   | SA     | Programming SA Bars
0xDA08   | SA     | Install SA HOBs
0xDA0A   | SA     | Reporting SA PCIe code version
0xDA0C   | SA     | SaSvInit Start
0xDA10   | SA     | Initializing DMI
0xDA1F   | SA     | Initializing DMI/OPI Max PayLoad Size
0xDA20   | SA     | Initializing SwitchableGraphics
0xDA30   | SA     | Initializing SA PCIe
0xDA3F   | SA     | Programming PEG credit values Start
0xDA40   | SA     | Initializing DMI Tc/Vc mapping
0xDA42   | SA     | CheckOffboardPcieVga
0xDA44   | SA     | CheckAndInitializePegVga
0xDA50   | SA     | Initializing Graphics
0xDA7F   | SA     | Pre-Mem SaInit Exit
0xDB00   | PCH    | PCH API Entry
0xDC00   | CPU    | Pre-Mem Entry
0xDC7F   | CPU    | Pre-Mem Exit

### 5.1.3 TempRamExit API Status Codes (0xBxxx)

PostCode | Module | Description
---------|--------|-----------------
0xB800   | FSP    | TempRamExit API Entry
0xB87F   | FSP    | TempRamExit API Exit

### 5.1.3 FspSiliconInit API Status Codes (0x9xxx)

PostCode | Module | Description
---------|--------|-----------------
0x9800   | FSP    | FspSiliconInit API Entry
0x987F   | FSP    | FspSiliconInit API Exit
0x9A00   | SA     | Post-Mem SaInit Entry
0x9A01   | SA     | DeviceConfigure Start
0x9A02   | SA     | UpdateSaHobPostMem Start 
0x9A03   | SA     | Initializing Pei Display
0x9A04   | SA     | PeiGraphicsNotifyCallback Entry
0x9A05   | SA     | CallPpiAndFillFrameBuffer
0x9A06   | SA     | GraphicsPpiInit
0x9A07   | SA     | GraphicsPpiGetMode
0x9A08   | SA     | FillFrameBufferAndShowLogo
0x9A0F   | SA     | PeiGraphicsNotifyCallback Exit
0x9A10   | SA     | Initializing SA Overclocking
0x9A14   | SA     | Initializing SA SkyCam device
0x9A16   | SA     | Initializing SA GMM device
0x9A18   | SA     | Internal Device and Misc Configurations
0x9A1A   | SA     | SaProgramLlcWays Start
0x9A20   | SA     | Initializing PciExpressInitPostMem
0x9A30   | SA     | Initializing Vtd
0x9A32   | SA     | Initializing Pavp
0x9A34   | SA     | PeiInstallSmmAccessPpi Start
0x9A36   | SA     | EdramWa Start
0x9A4F   | SA     | Post-Mem SaInit Exit
0x9A50   | SA     | SaSecurityLock Start
0x9A5F   | SA     | SaSecurityLock End
0x9A60   | SA     | SaSResetComplete Entry
0x9A61   | SA     | Set BIOS_RESET_CPL to indicate all configurations complete 
0x9A62   | SA     | SaSvInit2 Start
0x9A63   | SA     | GraphicsPmInit Start
0x9A64   | SA     | SaPeiPolicyDump Start
0x9A6F   | SA     | SaSResetComplete Exit
0x9A70   | SA     | SaS3ResumeAtEndOfPei Callback Entry
0x9A7F   | SA     | SaS3ResumeAtEndOfPei Callback Exit
0x9B7F   | PCH    | Post-Mem ScInit Entry
0x9B01   | PCH    | Post-Mem Program HSIO ModPHY settings
0x9B02   | PCH    | Post-Mem SMBus configuration
0x9B03   | PCH    | Post-Mem LPC configuration
0x9B04   | PCH    | Post-Mem SATA initizalization
0x9B05   | PCH    | Post-Mem PCIe initizalization
0x9B06   | PCH    | Post-Mem xHCI initizalization
0x9B07   | PCH    | Post-Mem xDCI initizalization
0x9B08   | PCH    | Post-Mem HD Audio initizalization
0x9B09   | PCH    | Post-Mem GMM configuration
0x9B0A   | PCH    | Post-Mem LPSS initizalization
0x9B0B   | PCH    | Post-Mem SCS initizalization
0x9B0C   | PCH    | Post-Mem ISH initizalization
0x9B0D   | PCH    | Post-Mem ITSS configuration
0x9B40   | PCH    | Post-Mem OnEndOfPEI Entry
0x9B4F   | PCH    | Post-Mem OnEndOfPEI Exit
0x9B7F   | PCH    | Post-Mem ScInit Exit
0x9C00   | CPU    | Post-Mem Entry
0x9C7F   | CPU    | Post-Mem Exit

### 5.1.4 NotifyPhase API Status Codes (0x6xxx)

PostCode | Module | Description
---------|--------|-----------------
0x6800   | FSP    | NotifyPhase API Entry
0x687F   | FSP    | NotifyPhase API Exit

**/