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