MdePkg/Include/Protocol/MmCpu.h

   1 /** @file
   2   EFI MM CPU Protocol as defined in the PI 1.5 specification.
   3
   4   This protocol allows MM drivers to access architecture-standard registers from any of the CPU
   5   save state areas. In some cases, difference processors provide the same information in the save state,
   6   but not in the same format. These so-called pseudo-registers provide this information in a standard
   7   format.
   8
   9   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
  10   SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12 **/
  13
  14 #ifndef _MM_CPU_H_
  15 #define _MM_CPU_H_
  16
  17 #define EFI_MM_CPU_PROTOCOL_GUID \
  18   { \
  19     0xeb346b97, 0x975f, 0x4a9f, { 0x8b, 0x22, 0xf8, 0xe9, 0x2b, 0xb3, 0xd5, 0x69 } \
  20   }
  21
  22 ///
  23 /// Save State register index
  24 ///
  25 typedef enum {
  26   ///
  27   /// x86/X64 standard registers
  28   ///
  29   EFI_MM_SAVE_STATE_REGISTER_GDTBASE    = 4,
  30   EFI_MM_SAVE_STATE_REGISTER_IDTBASE    = 5,
  31   EFI_MM_SAVE_STATE_REGISTER_LDTBASE    = 6,
  32   EFI_MM_SAVE_STATE_REGISTER_GDTLIMIT   = 7,
  33   EFI_MM_SAVE_STATE_REGISTER_IDTLIMIT   = 8,
  34   EFI_MM_SAVE_STATE_REGISTER_LDTLIMIT   = 9,
  35   EFI_MM_SAVE_STATE_REGISTER_LDTINFO    = 10,
  36   EFI_MM_SAVE_STATE_REGISTER_ES         = 20,
  37   EFI_MM_SAVE_STATE_REGISTER_CS         = 21,
  38   EFI_MM_SAVE_STATE_REGISTER_SS         = 22,
  39   EFI_MM_SAVE_STATE_REGISTER_DS         = 23,
  40   EFI_MM_SAVE_STATE_REGISTER_FS         = 24,
  41   EFI_MM_SAVE_STATE_REGISTER_GS         = 25,
  42   EFI_MM_SAVE_STATE_REGISTER_LDTR_SEL   = 26,
  43   EFI_MM_SAVE_STATE_REGISTER_TR_SEL     = 27,
  44   EFI_MM_SAVE_STATE_REGISTER_DR7        = 28,
  45   EFI_MM_SAVE_STATE_REGISTER_DR6        = 29,
  46   EFI_MM_SAVE_STATE_REGISTER_R8         = 30,
  47   EFI_MM_SAVE_STATE_REGISTER_R9         = 31,
  48   EFI_MM_SAVE_STATE_REGISTER_R10        = 32,
  49   EFI_MM_SAVE_STATE_REGISTER_R11        = 33,
  50   EFI_MM_SAVE_STATE_REGISTER_R12        = 34,
  51   EFI_MM_SAVE_STATE_REGISTER_R13        = 35,
  52   EFI_MM_SAVE_STATE_REGISTER_R14        = 36,
  53   EFI_MM_SAVE_STATE_REGISTER_R15        = 37,
  54   EFI_MM_SAVE_STATE_REGISTER_RAX        = 38,
  55   EFI_MM_SAVE_STATE_REGISTER_RBX        = 39,
  56   EFI_MM_SAVE_STATE_REGISTER_RCX        = 40,
  57   EFI_MM_SAVE_STATE_REGISTER_RDX        = 41,
  58   EFI_MM_SAVE_STATE_REGISTER_RSP        = 42,
  59   EFI_MM_SAVE_STATE_REGISTER_RBP        = 43,
  60   EFI_MM_SAVE_STATE_REGISTER_RSI        = 44,
  61   EFI_MM_SAVE_STATE_REGISTER_RDI        = 45,
  62   EFI_MM_SAVE_STATE_REGISTER_RIP        = 46,
  63   EFI_MM_SAVE_STATE_REGISTER_RFLAGS     = 51,
  64   EFI_MM_SAVE_STATE_REGISTER_CR0        = 52,
  65   EFI_MM_SAVE_STATE_REGISTER_CR3        = 53,
  66   EFI_MM_SAVE_STATE_REGISTER_CR4        = 54,
  67   EFI_MM_SAVE_STATE_REGISTER_FCW        = 256,
  68   EFI_MM_SAVE_STATE_REGISTER_FSW        = 257,
  69   EFI_MM_SAVE_STATE_REGISTER_FTW        = 258,
  70   EFI_MM_SAVE_STATE_REGISTER_OPCODE     = 259,
  71   EFI_MM_SAVE_STATE_REGISTER_FP_EIP     = 260,
  72   EFI_MM_SAVE_STATE_REGISTER_FP_CS      = 261,
  73   EFI_MM_SAVE_STATE_REGISTER_DATAOFFSET = 262,
  74   EFI_MM_SAVE_STATE_REGISTER_FP_DS      = 263,
  75   EFI_MM_SAVE_STATE_REGISTER_MM0        = 264,
  76   EFI_MM_SAVE_STATE_REGISTER_MM1        = 265,
  77   EFI_MM_SAVE_STATE_REGISTER_MM2        = 266,
  78   EFI_MM_SAVE_STATE_REGISTER_MM3        = 267,
  79   EFI_MM_SAVE_STATE_REGISTER_MM4        = 268,
  80   EFI_MM_SAVE_STATE_REGISTER_MM5        = 269,
  81   EFI_MM_SAVE_STATE_REGISTER_MM6        = 270,
  82   EFI_MM_SAVE_STATE_REGISTER_MM7        = 271,
  83   EFI_MM_SAVE_STATE_REGISTER_XMM0       = 272,
  84   EFI_MM_SAVE_STATE_REGISTER_XMM1       = 273,
  85   EFI_MM_SAVE_STATE_REGISTER_XMM2       = 274,
  86   EFI_MM_SAVE_STATE_REGISTER_XMM3       = 275,
  87   EFI_MM_SAVE_STATE_REGISTER_XMM4       = 276,
  88   EFI_MM_SAVE_STATE_REGISTER_XMM5       = 277,
  89   EFI_MM_SAVE_STATE_REGISTER_XMM6       = 278,
  90   EFI_MM_SAVE_STATE_REGISTER_XMM7       = 279,
  91   EFI_MM_SAVE_STATE_REGISTER_XMM8       = 280,
  92   EFI_MM_SAVE_STATE_REGISTER_XMM9       = 281,
  93   EFI_MM_SAVE_STATE_REGISTER_XMM10      = 282,
  94   EFI_MM_SAVE_STATE_REGISTER_XMM11      = 283,
  95   EFI_MM_SAVE_STATE_REGISTER_XMM12      = 284,
  96   EFI_MM_SAVE_STATE_REGISTER_XMM13      = 285,
  97   EFI_MM_SAVE_STATE_REGISTER_XMM14      = 286,
  98   EFI_MM_SAVE_STATE_REGISTER_XMM15      = 287,
  99   ///
 100   /// Pseudo-Registers
 101   ///
 102   EFI_MM_SAVE_STATE_REGISTER_IO           = 512,
 103   EFI_MM_SAVE_STATE_REGISTER_LMA          = 513,
 104   EFI_MM_SAVE_STATE_REGISTER_PROCESSOR_ID = 514
 105 } EFI_MM_SAVE_STATE_REGISTER;
 106
 107 ///
 108 /// The EFI_MM_SAVE_STATE_REGISTER_LMA pseudo-register values
 109 /// If the processor acts in 32-bit mode at the time the MMI occurred, the pseudo register value
 110 /// EFI_MM_SAVE_STATE_REGISTER_LMA_32BIT is returned in Buffer. Otherwise,
 111 /// EFI_MM_SAVE_STATE_REGISTER_LMA_64BIT is returned in Buffer.
 112 ///
 113 #define EFI_MM_SAVE_STATE_REGISTER_LMA_32BIT  32
 114 #define EFI_MM_SAVE_STATE_REGISTER_LMA_64BIT  64
 115
 116 ///
 117 /// Size width of I/O instruction
 118 ///
 119 typedef enum {
 120   EFI_MM_SAVE_STATE_IO_WIDTH_UINT8  = 0,
 121   EFI_MM_SAVE_STATE_IO_WIDTH_UINT16 = 1,
 122   EFI_MM_SAVE_STATE_IO_WIDTH_UINT32 = 2,
 123   EFI_MM_SAVE_STATE_IO_WIDTH_UINT64 = 3
 124 } EFI_MM_SAVE_STATE_IO_WIDTH;
 125
 126 ///
 127 /// Types of I/O instruction
 128 ///
 129 typedef enum {
 130   EFI_MM_SAVE_STATE_IO_TYPE_INPUT      = 1,
 131   EFI_MM_SAVE_STATE_IO_TYPE_OUTPUT     = 2,
 132   EFI_MM_SAVE_STATE_IO_TYPE_STRING     = 4,
 133   EFI_MM_SAVE_STATE_IO_TYPE_REP_PREFIX = 8
 134 } EFI_MM_SAVE_STATE_IO_TYPE;
 135
 136 ///
 137 /// Structure of the data which is returned when ReadSaveState() is called with
 138 /// EFI_MM_SAVE_STATE_REGISTER_IO. If there was no I/O then ReadSaveState() will
 139 /// return EFI_NOT_FOUND.
 140 ///
 141 /// This structure describes the I/O operation which was in process when the MMI was generated.
 142 ///
 143 typedef struct _EFI_MM_SAVE_STATE_IO_INFO {
 144   ///
 145   /// For input instruction (IN, INS), this is data read before the MMI occurred. For output
 146   /// instructions (OUT, OUTS) this is data that was written before the MMI occurred. The
 147   /// width of the data is specified by IoWidth.
 148   ///
 149   UINT64                        IoData;
 150   ///
 151   /// The I/O port that was being accessed when the MMI was triggered.
 152   ///
 153   UINT16                        IoPort;
 154   ///
 155   /// Defines the size width (UINT8, UINT16, UINT32, UINT64) for IoData.
 156   ///
 157   EFI_MM_SAVE_STATE_IO_WIDTH    IoWidth;
 158   ///
 159   /// Defines type of I/O instruction.
 160   ///
 161   EFI_MM_SAVE_STATE_IO_TYPE     IoType;
 162 } EFI_MM_SAVE_STATE_IO_INFO;
 163
 164 typedef struct _EFI_MM_CPU_PROTOCOL EFI_MM_CPU_PROTOCOL;
 165
 166 /**
 167   Read data from the CPU save state.
 168
 169   This function is used to read the specified number of bytes of the specified register from the CPU
 170   save state of the specified CPU and place the value into the buffer. If the CPU does not support the
 171   specified register Register, then EFI_NOT_FOUND  should be returned. If the CPU does not
 172   support the specified register width Width, then EFI_INVALID_PARAMETER is returned.
 173
 174   @param[in]  This               The EFI_MM_CPU_PROTOCOL instance.
 175   @param[in]  Width              The number of bytes to read from the CPU save state.
 176   @param[in]  Register           Specifies the CPU register to read form the save state.
 177   @param[in]  CpuIndex           Specifies the zero-based index of the CPU save state.
 178   @param[out] Buffer             Upon return, this holds the CPU register value read from the save state.
 179
 180   @retval EFI_SUCCESS            The register was read from Save State.
 181   @retval EFI_NOT_FOUND          The register is not defined for the Save State of Processor.
 182   @retval EFI_INVALID_PARAMETER  Input parameters are not valid, for example, Processor No or register width
 183                                  is not correct.This or Buffer is NULL.
 184 **/
 185 typedef
 186 EFI_STATUS
 187 (EFIAPI *EFI_MM_READ_SAVE_STATE)(
 188   IN CONST EFI_MM_CPU_PROTOCOL    *This,
 189   IN UINTN                        Width,
 190   IN EFI_MM_SAVE_STATE_REGISTER   Register,
 191   IN UINTN                        CpuIndex,
 192   OUT VOID                        *Buffer
 193   );
 194
 195 /**
 196   Write data to the CPU save state.
 197
 198   This function is used to write the specified number of bytes of the specified register to the CPU save
 199   state of the specified CPU and place the value into the buffer. If the CPU does not support the
 200   specified register Register, then EFI_UNSUPPORTED should be returned. If the CPU does not
 201   support the specified register width Width, then EFI_INVALID_PARAMETER is returned.
 202
 203   @param[in]  This               The EFI_MM_CPU_PROTOCOL instance.
 204   @param[in]  Width              The number of bytes to write to the CPU save state.
 205   @param[in]  Register           Specifies the CPU register to write to the save state.
 206   @param[in]  CpuIndex           Specifies the zero-based index of the CPU save state.
 207   @param[in]  Buffer             Upon entry, this holds the new CPU register value.
 208
 209   @retval EFI_SUCCESS            The register was written to Save State.
 210   @retval EFI_NOT_FOUND          The register is not defined for the Save State of Processor.
 211   @retval EFI_INVALID_PARAMETER  Input parameters are not valid. For example:
 212                                  ProcessorIndex or Width is not correct.
 213 **/
 214 typedef
 215 EFI_STATUS
 216 (EFIAPI *EFI_MM_WRITE_SAVE_STATE)(
 217   IN CONST EFI_MM_CPU_PROTOCOL    *This,
 218   IN UINTN                        Width,
 219   IN EFI_MM_SAVE_STATE_REGISTER   Register,
 220   IN UINTN                        CpuIndex,
 221   IN CONST VOID                   *Buffer
 222   );
 223
 224 ///
 225 /// EFI MM CPU Protocol provides access to CPU-related information while in MM.
 226 ///
 227 /// This protocol allows MM drivers to access architecture-standard registers from any of the CPU
 228 /// save state areas. In some cases, difference processors provide the same information in the save state,
 229 /// but not in the same format. These so-called pseudo-registers provide this information in a standard
 230 /// format.
 231 ///
 232 struct _EFI_MM_CPU_PROTOCOL {
 233   EFI_MM_READ_SAVE_STATE     ReadSaveState;
 234   EFI_MM_WRITE_SAVE_STATE    WriteSaveState;
 235 };
 236
 237 extern EFI_GUID  gEfiMmCpuProtocolGuid;
 238
 239 #endif