/* $NoKeywords:$ */
/**
 * @file
 *
 * AMD CPU Reset API, and related functions and structures.
 *
 * Contains code that initialized the CPU after early reset.
 *
 * @xrefitem bom "File Content Label" "Release Content"
 * @e project:      AGESA
 * @e sub-project:  CPU
 * @e \$Revision: 63425 $   @e \$Date: 2011-12-22 11:24:10 -0600 (Thu, 22 Dec 2011) $
 *
 */
/*
 ******************************************************************************
 *
 * Copyright 2008 - 2012 ADVANCED MICRO DEVICES, INC.  All Rights Reserved.
 *
 * AMD is granting you permission to use this software (the Materials)
 * pursuant to the terms and conditions of your Software License Agreement
 * with AMD.  This header does *NOT* give you permission to use the Materials
 * or any rights under AMD's intellectual property.  Your use of any portion
 * of these Materials shall constitute your acceptance of those terms and
 * conditions.  If you do not agree to the terms and conditions of the Software
 * License Agreement, please do not use any portion of these Materials.
 *
 * CONFIDENTIALITY:  The Materials and all other information, identified as
 * confidential and provided to you by AMD shall be kept confidential in
 * accordance with the terms and conditions of the Software License Agreement.
 *
 * LIMITATION OF LIABILITY: THE MATERIALS AND ANY OTHER RELATED INFORMATION
 * PROVIDED TO YOU BY AMD ARE PROVIDED "AS IS" WITHOUT ANY EXPRESS OR IMPLIED
 * WARRANTY OF ANY KIND, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
 * MERCHANTABILITY, NONINFRINGEMENT, TITLE, FITNESS FOR ANY PARTICULAR PURPOSE,
 * OR WARRANTIES ARISING FROM CONDUCT, COURSE OF DEALING, OR USAGE OF TRADE.
 * IN NO EVENT SHALL AMD OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES WHATSOEVER
 * (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS
 * INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF AMD'S NEGLIGENCE,
 * GROSS NEGLIGENCE, THE USE OF OR INABILITY TO USE THE MATERIALS OR ANY OTHER
 * RELATED INFORMATION PROVIDED TO YOU BY AMD, EVEN IF AMD HAS BEEN ADVISED OF
 * THE POSSIBILITY OF SUCH DAMAGES.  BECAUSE SOME JURISDICTIONS PROHIBIT THE
 * EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES,
 * THE ABOVE LIMITATION MAY NOT APPLY TO YOU.
 *
 * AMD does not assume any responsibility for any errors which may appear in
 * the Materials or any other related information provided to you by AMD, or
 * result from use of the Materials or any related information.
 *
 * You agree that you will not reverse engineer or decompile the Materials.
 *
 * NO SUPPORT OBLIGATION: AMD is not obligated to furnish, support, or make any
 * further information, software, technical information, know-how, or show-how
 * available to you.  Additionally, AMD retains the right to modify the
 * Materials at any time, without notice, and is not obligated to provide such
 * modified Materials to you.
 *
 * U.S. GOVERNMENT RESTRICTED RIGHTS: The Materials are provided with
 * "RESTRICTED RIGHTS." Use, duplication, or disclosure by the Government is
 * subject to the restrictions as set forth in FAR 52.227-14 and
 * DFAR252.227-7013, et seq., or its successor.  Use of the Materials by the
 * Government constitutes acknowledgement of AMD's proprietary rights in them.
 *
 * EXPORT ASSURANCE:  You agree and certify that neither the Materials, nor any
 * direct product thereof will be exported directly or indirectly, into any
 * country prohibited by the United States Export Administration Act and the
 * regulations thereunder, without the required authorization from the U.S.
 * government nor will be used for any purpose prohibited by the same.
 ******************************************************************************
 */

#ifndef _CPU_EARLY_INIT_H_
#define _CPU_EARLY_INIT_H_


/*---------------------------------------------------------------------------------------
 *          M I X E D   (Definitions And Macros / Typedefs, Structures, Enums)
 *---------------------------------------------------------------------------------------
 */
AGESA_FORWARD_DECLARATION (CPU_CORE_LEVELING_FAMILY_SERVICES);

/*---------------------------------------------------------------------------------------
 *                 D E F I N I T I O N S     A N D     M A C R O S
 *---------------------------------------------------------------------------------------
 */
//----------------------------------------------------------------------------
//                         CPU BRAND ID TYPEDEFS, STRUCTURES, ENUMS
//
//----------------------------------------------------------------------------
#define CPU_BRAND_ID_LENGTH     48            // Total number of characters supported
#define LOW_NODE_DEVICEID       24
#define NB_CAPABILITIES         0xE8          //Function 3 Registers
//----------------------------------------------------------------------------
//                         CPU MICROCODE PATCH TYPEDEFS, STRUCTURES, ENUMS
//
//----------------------------------------------------------------------------
/* All lengths are in bytes */
#define MICROCODE_TRIADE_SIZE           28
#define MICROCODE_HEADER_LENGTH         64

/**
 * @page ucodeflag Microcode Patches Signature Guide
 *
 * We mark patches in the ROM with a signature so that they can be easily found
 *
 *   @anchor Microcode Patch Signature
 *   @li @e  Microcode Patch Signature @n
 *         Microcode patches are marked by adding a signature before patches in the ROM image to
 *         help identify where they are located.
 *         There're two kind of signatures. One is '$UCODE2K', it indicates there's a following patch with 2K size.
 *         The other is '$UCODE4K', it indicates there's a following patch with 4K size.
 *         If you want to know the patch level / equivalent ID, please consult the BKDG for patch header format.
 *
 *
 */
/// Microcode patch flag for replacement
typedef struct {
  IN       UINT8   MicrocodePatchesFlag[8];  ///< a flag followed by microcode
} MICROCODE_PATCHES_FLAG;

#define UCODE_2K_FLAG(x) STATIC CONST MICROCODE_PATCHES_FLAG ROMDATA UcodeFlag##x = {{'$', 'U', 'C', 'O', 'D', 'E', '2', 'K'}};
#define UCODE_4K_FLAG(x) STATIC CONST MICROCODE_PATCHES_FLAG ROMDATA UcodeFlag##x = {{'$', 'U', 'C', 'O', 'D', 'E', '4', 'K'}};
#define UCODE_VS_FLAG(x) STATIC CONST MICROCODE_PATCHES_FLAG ROMDATA UcodeFlag##x = {{'$', 'U', 'C', 'O', 'D', 'E', 'V', 'S'}};

/* Offsets in UCODE PATCH Header */
/* Note: Header is 64 bytes      */
#define DATE_CODE_OFFSET                0   // 4 bytes
#define PATCH_ID                        4   // 4 bytes
#define MICROCODE_PATH_DATA_ID          8   // 2 bytes
#define MICROCODE_PATCH_DATA_LENGTH     10  // 1 byte
#define MICROCODE_PATCH_DATA_CHECKSUM   12  // 4 bytes
#define CHIPSET_1_DEVICE_ID             16  // 4 bytes
#define CHIPSET_2_DEVICE_ID             20  // 4 bytes
#define PROCESSOR_REV_ID                24  // 2 bytes
#define CHIPSET_1_REV_ID                26  // 1 byte
#define CHIPSET_2_REV_ID                27  // 1 byte

#define MICROCODE_PATCH_2K_SIZE    2048
#define MICROCODE_PATCH_4K_SIZE    4096
/*---------------------------------------------------------------------------------------
 *               T Y P E D E F S,   S T R U C T U R E S,    E N U M S
 *---------------------------------------------------------------------------------------
 */
//----------------------------------------------------------------------------
//                         CPU BRAND ID TYPEDEFS, STRUCTURES, ENUMS
//
//----------------------------------------------------------------------------
/// A structure representing BrandId[15:0] from
/// CPUID Fn8000_0001_EBX
typedef struct {
  UINT8           String1:4;   ///< An index to a string value used to create the name string
  UINT8           String2:4;   ///< An index to a string value used to create the name string
  UINT8           Page:1;      ///< An index to the appropriate page for the String1, String2, and Model values
  UINT8           Model:7;     ///< A field used to create the model number in the name string
  UINT8           Socket:4;    ///< Specifies the package type
  UINT8           Cores:4;     ///< Identifies how many physical cores are present
} AMD_CPU_BRAND_DATA;

/// A structure containing string1 and string2 values
/// as well as information pertaining to their usage
typedef struct {
  IN       UINT8  Cores;              ///< Appropriate number of physical cores
  IN       UINT8  Page;               ///< This string's page number
  IN       UINT8  Index;              ///< String index
  IN       UINT8  Socket;             ///< Package type information
  IN       CONST CHAR8 *Stringstart;  ///< The literal string
  IN       UINT8  Stringlength;       ///< Number of characters in the string
} AMD_CPU_BRAND;

/// An entire CPU brand table.
typedef struct {
  UINT8 NumberOfEntries;        ///< The number of entries in the table.
  CONST AMD_CPU_BRAND  *Table;  ///< The table entries.
} CPU_BRAND_TABLE;

//----------------------------------------------------------------------------
//                         CPU MICROCODE PATCH TYPEDEFS, STRUCTURES, ENUMS
//
//----------------------------------------------------------------------------
/// Microcode patch field definitions
typedef struct {
  UINT32   DateCode;                   ///< Date of patch creation
  UINT32   PatchID;                    ///< Patch level
  UINT16   MicrocodePatchDataID;       ///< Internal use only
  UINT8    MicrocodePatchDataLength;   ///< Internal use only
  UINT8    InitializationFlag;         ///< Internal use only
  UINT32   MicrocodePatchDataChecksum; ///< Doubleword sum of data block
  UINT32   Chipset1DeviceID;           ///< Device ID of 1st HT device to match
  UINT32   Chipset2DeviceID;           ///< Device ID of 2nd HT device to match
  UINT16   ProcessorRevisionID;        ///< Equivalent ID
  UINT8    Chipset1RevisionID;         ///< Revision level of 1st HT device to match
  UINT8    Chipset2RevisionID;         ///< Revision level of 2nd HT device to match
  UINT8    BiosApiRevision;            ///< BIOS INT 15 API revision required
  UINT8    Reserved1[3];               ///< Reserved
  UINT32   MatchRegister0;             ///< Internal use only
  UINT32   MatchRegister1;             ///< Internal use only
  UINT32   MatchRegister2;             ///< Internal use only
  UINT32   MatchRegister3;             ///< Internal use only
  UINT32   MatchRegister4;             ///< Internal use only
  UINT32   MatchRegister5;             ///< Internal use only
  UINT32   MatchRegister6;             ///< Internal use only
  UINT32   MatchRegister7;             ///< Internal use only
  UINT8    PatchDataBlock[896];        ///< Raw patch data
  UINT8    Reserved2[896];             ///< Reserved
  UINT8    X86CodePresent;             ///< Boolean to determine if executable code exists
  UINT8    X86CodeEntry[191];          ///< Code to execute if X86CodePresent != 0
} MICROCODE_PATCH;

/// Two kilobyte array containing the raw
/// microcode patch binary data
typedef struct {
  IN       UINT8   MicrocodePatches[MICROCODE_PATCH_2K_SIZE];  ///< 2k UINT8 elements
} MICROCODE_PATCHES;

/// Four kilobyte array containing the raw
/// microcode patch binary data
typedef struct {
  IN       UINT8   MicrocodePatches[MICROCODE_PATCH_4K_SIZE];  ///< 4k UINT8 elements
} MICROCODE_PATCHES_4K;

/**
 *  Set down core register
 *
 *  @CpuServiceInstances
 *
 * @param[in]      FamilySpecificServices  The current Family Specific Services.
 * @param[in]      Socket        Socket ID.
 * @param[in]      Module        Module ID in socket.
 * @param[in]      LeveledCores  Number of core.
 * @param[in]      CoreLevelMode Core level mode.
 * @param[in]      StdHeader     Header for library and services.
 *
 * @retval         TRUE          Down Core register is updated.
 * @retval         FALSE         Down Core register is not updated.
 */
typedef BOOLEAN (F_CPU_SET_DOWN_CORE_REGISTER) (
  IN       CPU_CORE_LEVELING_FAMILY_SERVICES  *FamilySpecificServices,
  IN       UINT32 *Socket,
  IN       UINT32 *Module,
  IN       UINT32 *LeveledCores,
  IN       CORE_LEVELING_TYPE CoreLevelMode,
  IN       AMD_CONFIG_PARAMS *StdHeader
  );

/// Reference to a method
typedef F_CPU_SET_DOWN_CORE_REGISTER *PF_CPU_SET_DOWN_CORE_REGISTER;

/**
 * Provide the interface to the Core Leveling Family Specific Services.
 *
 * Use the methods or data in this struct to adapt the feature code to a specific cpu family or model (or stepping!).
 * Each supported Family must provide an implementation for all methods in this interface, even if the
 * implementation is a CommonReturn().
 */
struct _CPU_CORE_LEVELING_FAMILY_SERVICES {             // See Forward Declaration above
  UINT16          Revision;                             ///< Interface version
  // Public Methods.
  PF_CPU_SET_DOWN_CORE_REGISTER SetDownCoreRegister;    ///< Method: Set down core register.
};

//----------------------------------------------------------------------------
//                         CPU PERFORM EARLY INIT ON CORE
//
//----------------------------------------------------------------------------
/// Flag definition.
#define PERFORM_EARLY_WARM_RESET    0x1        // bit 0 --- the related function needs to be run if it's warm reset
#define PERFORM_EARLY_COLD_BOOT     0x2        // bit 1 --- the related function needs to be run if it's cold boot

#define PERFORM_EARLY_ANY_CONDITION 0xFFFFFFFFul // the related function always needs to be run
/*---------------------------------------------------------------------------------------
 *                        F U N C T I O N    P R O T O T Y P E
 *---------------------------------------------------------------------------------------
 */

//                   These are   P U B L I C   functions, used by IBVs
AGESA_STATUS
AmdCpuEarly (
  IN       AMD_CONFIG_PARAMS      *StdHeader,
  IN       PLATFORM_CONFIGURATION *PlatformConfig
  );

//                   These are   P U B L I C   functions, used by AGESA
VOID
SetBrandIdRegisters (
  IN OUT   AMD_CONFIG_PARAMS *StdHeader
  );

AGESA_STATUS
PmInitializationAtEarly (
  IN       AMD_CPU_EARLY_PARAMS *CpuEarlyParams,
  IN       AMD_CONFIG_PARAMS    *StdHeader
  );

BOOLEAN
LoadMicrocodePatch (
  IN OUT   AMD_CONFIG_PARAMS *StdHeader
  );

BOOLEAN
GetPatchEquivalentId (
  IN OUT   UINT16             *ProcessorEquivalentId,
  IN OUT   AMD_CONFIG_PARAMS  *StdHeader
  );

BOOLEAN
ValidateMicrocode (
  IN       MICROCODE_PATCH    *MicrocodePatchPtr,
  IN       UINT16             ProcessorEquivalentId,
  IN OUT   AMD_CONFIG_PARAMS  *StdHeader
  );

VOID
GetMicrocodeVersion (
     OUT   UINT32             *pMicrocodeVersion,
  IN OUT   AMD_CONFIG_PARAMS  *StdHeader
  );

VOID
AmdCpuEarlyInitializer (
  IN       AMD_CONFIG_PARAMS      *StdHeader,
  IN       PLATFORM_CONFIGURATION *PlatformConfig,
  IN OUT   AMD_CPU_EARLY_PARAMS   *CpuEarlyParamsPtr
  );

VOID
McaInitialization (
  IN       AMD_CONFIG_PARAMS *StdHeader
  );

#endif  // _CPU_EARLY_INIT_H_