UefiCpuPkg/Include/Library/MicrocodeLib.h

   1 /** @file
   2   Public include file for Microcode library.
   3
   4   Copyright (c) 2021, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef MICROCODE_LIB_H_
  10 #define MICROCODE_LIB_H_
  11
  12 #include <Register/Intel/Microcode.h>
  13 #include <Ppi/ShadowMicrocode.h>
  14
  15 /**
  16   Get microcode update signature of currently loaded microcode update.
  17
  18   @return  Microcode signature.
  19 **/
  20 UINT32
  21 EFIAPI
  22 GetProcessorMicrocodeSignature (
  23   VOID
  24   );
  25
  26 /**
  27   Get the processor signature and platform ID for current processor.
  28
  29   @param MicrocodeCpuId  Return the processor signature and platform ID.
  30 **/
  31 VOID
  32 EFIAPI
  33 GetProcessorMicrocodeCpuId (
  34   EDKII_PEI_MICROCODE_CPU_ID  *MicrocodeCpuId
  35   );
  36
  37 /**
  38   Return the total size of the microcode entry.
  39
  40   Logic follows pseudo code in SDM as below:
  41
  42      N = 512
  43      If (Update.DataSize != 00000000H)
  44        N = Update.TotalSize / 4
  45
  46   If Microcode is NULL, then ASSERT.
  47
  48   @param Microcode  Pointer to the microcode entry.
  49
  50   @return The microcode total size.
  51 **/
  52 UINT32
  53 EFIAPI
  54 GetMicrocodeLength (
  55   IN CPU_MICROCODE_HEADER  *Microcode
  56   );
  57
  58 /**
  59   Load the microcode to the processor.
  60
  61   If Microcode is NULL, then ASSERT.
  62
  63   @param Microcode  Pointer to the microcode entry.
  64 **/
  65 VOID
  66 EFIAPI
  67 LoadMicrocode (
  68   IN CPU_MICROCODE_HEADER  *Microcode
  69   );
  70
  71 /**
  72   Detect whether specified processor can find matching microcode patch and load it.
  73
  74   Microcode format is as below:
  75   +----------------------------------------+-------------------------------------------------+
  76   |          CPU_MICROCODE_HEADER          |                                                 |
  77   +----------------------------------------+                                                 V
  78   |              Update Data               |                                               CPU_MICROCODE_HEADER.Checksum
  79   +----------------------------------------+-------+                                         ^
  80   |  CPU_MICROCODE_EXTENDED_TABLE_HEADER   |       |                                         |
  81   +----------------------------------------+       V                                         |
  82   |      CPU_MICROCODE_EXTENDED_TABLE[0]   |  CPU_MICROCODE_EXTENDED_TABLE_HEADER.Checksum   |
  83   |      CPU_MICROCODE_EXTENDED_TABLE[1]   |       ^                                         |
  84   |                   ...                  |       |                                         |
  85   +----------------------------------------+-------+-----------------------------------------+
  86
  87   There may by multiple CPU_MICROCODE_EXTENDED_TABLE in this format.
  88   The count of CPU_MICROCODE_EXTENDED_TABLE is indicated by ExtendedSignatureCount
  89   of CPU_MICROCODE_EXTENDED_TABLE_HEADER structure.
  90
  91   If Microcode is NULL, then ASSERT.
  92
  93   @param Microcode            Pointer to a microcode entry.
  94   @param MicrocodeLength      The total length of the microcode entry.
  95   @param MinimumRevision      The microcode whose revision <= MinimumRevision is treated as invalid.
  96                               Caller can supply value get from GetProcessorMicrocodeSignature() to check
  97                               whether the microcode is newer than loaded one.
  98                               Caller can supply 0 to treat any revision (except 0) microcode as valid.
  99   @param MicrocodeCpuIds      Pointer to an array of processor signature and platform ID that represents
 100                               a set of processors.
 101                               Caller can supply zero-element array to skip the processor signature and
 102                               platform ID check.
 103   @param MicrocodeCpuIdCount  The number of elements in MicrocodeCpuIds.
 104   @param VerifyChecksum       FALSE to skip all the checksum verifications.
 105
 106   @retval TRUE  The microcode is valid.
 107   @retval FALSE The microcode is invalid.
 108 **/
 109 BOOLEAN
 110 EFIAPI
 111 IsValidMicrocode (
 112   IN CPU_MICROCODE_HEADER        *Microcode,
 113   IN UINTN                       MicrocodeLength,
 114   IN UINT32                      MinimumRevision,
 115   IN EDKII_PEI_MICROCODE_CPU_ID  *MicrocodeCpuIds,
 116   IN UINTN                       MicrocodeCpuIdCount,
 117   IN BOOLEAN                     VerifyChecksum
 118   );
 119
 120 #endif