MdePkg/Include/Protocol/SmmCpu.h

   1 /** @file
   2   EFI SMM CPU Protocol as defined in the PI 1.2 specification.
   3
   4   This protocol allows SMM 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) 2009, Intel Corporation
  10   All rights reserved. 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 _SMM_CPU_H_
  21 #define _SMM_CPU_H_
  22
  23 #include <Pi/PiSmmCis.h>
  24
  25 #define EFI_SMM_CPU_PROTOCOL_GUID \
  26   { \
  27     0xeb346b97, 0x975f, 0x4a9f, { 0x8b, 0x22, 0xf8, 0xe9, 0x2b, 0xb3, 0xd5, 0x69 } \
  28   }
  29
  30 ///
  31 /// Save State register index
  32 ///
  33 typedef enum {
  34   ///
  35   /// x86/X64 standard registers
  36   ///
  37   EFI_SMM_SAVE_STATE_REGISTER_GDTBASE       = 4,
  38   EFI_SMM_SAVE_STATE_REGISTER_IDTBASE       = 5,
  39   EFI_SMM_SAVE_STATE_REGISTER_LDTBASE       = 6,
  40   EFI_SMM_SAVE_STATE_REGISTER_GDTLIMIT      = 7,
  41   EFI_SMM_SAVE_STATE_REGISTER_IDTLIMIT      = 8,
  42   EFI_SMM_SAVE_STATE_REGISTER_LDTLIMIT      = 9,
  43   EFI_SMM_SAVE_STATE_REGISTER_LDTINFO       = 10,
  44   EFI_SMM_SAVE_STATE_REGISTER_ES            = 20,
  45   EFI_SMM_SAVE_STATE_REGISTER_CS            = 21,
  46   EFI_SMM_SAVE_STATE_REGISTER_SS            = 22,
  47   EFI_SMM_SAVE_STATE_REGISTER_DS            = 23,
  48   EFI_SMM_SAVE_STATE_REGISTER_FS            = 24,
  49   EFI_SMM_SAVE_STATE_REGISTER_GS            = 25,
  50   EFI_SMM_SAVE_STATE_REGISTER_LDTR_SEL      = 26,
  51   EFI_SMM_SAVE_STATE_REGISTER_TR_SEL        = 27,
  52   EFI_SMM_SAVE_STATE_REGISTER_DR7           = 28,
  53   EFI_SMM_SAVE_STATE_REGISTER_DR6           = 29,
  54   EFI_SMM_SAVE_STATE_REGISTER_R8            = 30,
  55   EFI_SMM_SAVE_STATE_REGISTER_R9            = 31,
  56   EFI_SMM_SAVE_STATE_REGISTER_R10           = 32,
  57   EFI_SMM_SAVE_STATE_REGISTER_R11           = 33,
  58   EFI_SMM_SAVE_STATE_REGISTER_R12           = 34,
  59   EFI_SMM_SAVE_STATE_REGISTER_R13           = 35,
  60   EFI_SMM_SAVE_STATE_REGISTER_R14           = 36,
  61   EFI_SMM_SAVE_STATE_REGISTER_R15           = 37,
  62   EFI_SMM_SAVE_STATE_REGISTER_RAX           = 38,
  63   EFI_SMM_SAVE_STATE_REGISTER_RBX           = 39,
  64   EFI_SMM_SAVE_STATE_REGISTER_RCX           = 40,
  65   EFI_SMM_SAVE_STATE_REGISTER_RDX           = 41,
  66   EFI_SMM_SAVE_STATE_REGISTER_RSP           = 42,
  67   EFI_SMM_SAVE_STATE_REGISTER_RBP           = 43,
  68   EFI_SMM_SAVE_STATE_REGISTER_RSI           = 44,
  69   EFI_SMM_SAVE_STATE_REGISTER_RDI           = 45,
  70   EFI_SMM_SAVE_STATE_REGISTER_RIP           = 46,
  71   EFI_SMM_SAVE_STATE_REGISTER_RFLAGS        = 51,
  72   EFI_SMM_SAVE_STATE_REGISTER_CR0           = 52,
  73   EFI_SMM_SAVE_STATE_REGISTER_CR3           = 53,
  74   EFI_SMM_SAVE_STATE_REGISTER_CR4           = 54,
  75   EFI_SMM_SAVE_STATE_REGISTER_FCW           = 256,
  76   EFI_SMM_SAVE_STATE_REGISTER_FSW           = 257,
  77   EFI_SMM_SAVE_STATE_REGISTER_FTW           = 258,
  78   EFI_SMM_SAVE_STATE_REGISTER_OPCODE        = 259,
  79   EFI_SMM_SAVE_STATE_REGISTER_FP_EIP        = 260,
  80   EFI_SMM_SAVE_STATE_REGISTER_FP_CS         = 261,
  81   EFI_SMM_SAVE_STATE_REGISTER_DATAOFFSET    = 262,
  82   EFI_SMM_SAVE_STATE_REGISTER_FP_DS         = 263,
  83   EFI_SMM_SAVE_STATE_REGISTER_MM0           = 264,
  84   EFI_SMM_SAVE_STATE_REGISTER_MM1           = 265,
  85   EFI_SMM_SAVE_STATE_REGISTER_MM2           = 266,
  86   EFI_SMM_SAVE_STATE_REGISTER_MM3           = 267,
  87   EFI_SMM_SAVE_STATE_REGISTER_MM4           = 268,
  88   EFI_SMM_SAVE_STATE_REGISTER_MM5           = 269,
  89   EFI_SMM_SAVE_STATE_REGISTER_MM6           = 270,
  90   EFI_SMM_SAVE_STATE_REGISTER_MM7           = 271,
  91   EFI_SMM_SAVE_STATE_REGISTER_XMM0          = 272,
  92   EFI_SMM_SAVE_STATE_REGISTER_XMM1          = 273,
  93   EFI_SMM_SAVE_STATE_REGISTER_XMM2          = 274,
  94   EFI_SMM_SAVE_STATE_REGISTER_XMM3          = 275,
  95   EFI_SMM_SAVE_STATE_REGISTER_XMM4          = 276,
  96   EFI_SMM_SAVE_STATE_REGISTER_XMM5          = 277,
  97   EFI_SMM_SAVE_STATE_REGISTER_XMM6          = 278,
  98   EFI_SMM_SAVE_STATE_REGISTER_XMM7          = 279,
  99   EFI_SMM_SAVE_STATE_REGISTER_XMM8          = 280,
 100   EFI_SMM_SAVE_STATE_REGISTER_XMM9          = 281,
 101   EFI_SMM_SAVE_STATE_REGISTER_XMM10         = 282,
 102   EFI_SMM_SAVE_STATE_REGISTER_XMM11         = 283,
 103   EFI_SMM_SAVE_STATE_REGISTER_XMM12         = 284,
 104   EFI_SMM_SAVE_STATE_REGISTER_XMM13         = 285,
 105   EFI_SMM_SAVE_STATE_REGISTER_XMM14         = 286,
 106   EFI_SMM_SAVE_STATE_REGISTER_XMM15         = 287,
 107   ///
 108   /// Pseudo-Registers
 109   ///
 110   EFI_SMM_SAVE_STATE_REGISTER_IO            = 512,
 111   EFI_SMM_SAVE_STATE_REGISTER_LMA           = 513
 112 } EFI_SMM_SAVE_STATE_REGISTER;
 113
 114 ///
 115 /// The EFI_SMM_SAVE_STATE_REGISTER_LMA pseudo-register values
 116 /// If the processor acts in 32-bit mode at the time the SMI occurred, the pseudo register value
 117 /// EFI_SMM_SAVE_STATE_REGISTER_LMA_32BIT is returned in Buffer. Otherwise,
 118 /// EFI_SMM_SAVE_STATE_REGISTER_LMA_64BIT is returned in Buffer.
 119 ///
 120 #define EFI_SMM_SAVE_STATE_REGISTER_LMA_32BIT  32
 121 #define EFI_SMM_SAVE_STATE_REGISTER_LMA_64BIT  64
 122
 123 ///
 124 /// Size width of I/O instruction
 125 ///
 126 typedef enum {
 127   EFI_SMM_SAVE_STATE_IO_WIDTH_UINT8      = 0,
 128   EFI_SMM_SAVE_STATE_IO_WIDTH_UINT16     = 1,
 129   EFI_SMM_SAVE_STATE_IO_WIDTH_UINT32     = 2,
 130   EFI_SMM_SAVE_STATE_IO_WIDTH_UINT64     = 3
 131 } EFI_SMM_SAVE_STATE_IO_WIDTH;
 132
 133 ///
 134 /// Types of I/O instruction
 135 ///
 136 typedef enum {
 137   EFI_SMM_SAVE_STATE_IO_TYPE_INPUT       = 1,
 138   EFI_SMM_SAVE_STATE_IO_TYPE_OUTPUT      = 2,
 139   EFI_SMM_SAVE_STATE_IO_TYPE_STRING      = 4,
 140   EFI_SMM_SAVE_STATE_IO_TYPE_REP_PREFIX  = 8
 141 } EFI_SMM_SAVE_STATE_IO_TYPE;
 142
 143 ///
 144 /// Structure of the data which is returned when ReadSaveState() is called with
 145 /// EFI_SMM_SAVE_STATE_REGISTER_IO. If there was no I/O then ReadSaveState() will
 146 /// return EFI_NOT_FOUND.
 147 ///
 148 /// This structure describes the I/O operation which was in process when the SMI was generated.
 149 ///
 150 typedef struct _EFI_SMM_SAVE_STATE_IO_INFO {
 151   ///
 152   /// For input instruction (IN, INS), this is data read before the SMI occurred. For output
 153   /// instructions (OUT, OUTS) this is data that was written before the SMI occurred. The
 154   /// width of the data is specified by IoWidth.
 155   ///
 156   /// Note: inconsistency with PI 1.2 spec here. wait for spec update.
 157   ///
 158   UINTN                         IoData;
 159   ///
 160   /// The I/O port that was being accessed when the SMI was triggered.
 161   ///
 162   UINT16                        IoPort;
 163   ///
 164   /// Defines the size width (UINT8, UINT16, UINT32, UINT64) for IoData.
 165   ///
 166   EFI_SMM_SAVE_STATE_IO_WIDTH   IoWidth;
 167   ///
 168   /// Defines type of I/O instruction.
 169   ///
 170   EFI_SMM_SAVE_STATE_IO_TYPE    IoType;
 171 } EFI_SMM_SAVE_STATE_IO_INFO;
 172
 173 typedef struct _EFI_SMM_CPU_PROTOCOL  EFI_SMM_CPU_PROTOCOL;
 174
 175 /**
 176   Read data from the CPU save state.
 177
 178   This function is used to read the specified number of bytes of the specified register from the CPU
 179   save state of the specified CPU and place the value into the buffer. If the CPU does not support the
 180   specified register Register, then EFI_NOT_FOUND  should be returned. If the CPU does not
 181   support the specified register width Width, then EFI_INVALID_PARAMETER is returned.
 182
 183   @param[in]  This               The EFI_SMM_CPU_PROTOCOL instance.
 184   @param[in]  Width              The number of bytes to read from the CPU save state.
 185   @param[in]  Register           Specifies the CPU register to read form the save state.
 186   @param[in]  CpuIndex           Specifies the zero-based index of the CPU save state.
 187   @param[out] Buffer             Upon return, this holds the CPU register value read from the save state.
 188
 189   @retval EFI_SUCCESS            The register was read from Save State.
 190   @retval EFI_NOT_FOUND          The register is not defined for the Save State of Processor.
 191   @retval EFI_INVALID_PARAMETER  Input parameters are not valid, for example, Processor No or register width
 192                                  is not correct.This or Buffer is NULL.
 193 **/
 194 typedef
 195 EFI_STATUS
 196 (EFIAPI *EFI_SMM_READ_SAVE_STATE)(
 197   IN CONST EFI_SMM_CPU_PROTOCOL   *This,
 198   IN UINTN                        Width,
 199   IN EFI_SMM_SAVE_STATE_REGISTER  Register,
 200   IN UINTN                        CpuIndex,
 201   OUT VOID                        *Buffer
 202   );
 203
 204
 205 /**
 206   Write data to the CPU save state.
 207
 208   This function is used to write the specified number of bytes of the specified register to the CPU save
 209   state of the specified CPU and place the value into the buffer. If the CPU does not support the
 210   specified register Register, then EFI_UNSUPPORTED should be returned. If the CPU does not
 211   support the specified register width Width, then EFI_INVALID_PARAMETER is returned.
 212
 213   @param[in]  This               The EFI_SMM_CPU_PROTOCOL instance.
 214   @param[in]  Width              The number of bytes to write to the CPU save state.
 215   @param[in]  Register           Specifies the CPU register to write to the save state.
 216   @param[in]  CpuIndex           Specifies the zero-based index of the CPU save state.
 217   @param[in]  Buffer             Upon entry, this holds the new CPU register value.
 218
 219   @retval EFI_SUCCESS            The register was written to Save State.
 220   @retval EFI_NOT_FOUND          The register is not defined for the Save State of Processor.
 221   @retval EFI_INVALID_PARAMETER  Input parameters are not valid. For example:
 222                                  ProcessorIndex or Width is not correct.
 223 **/
 224 typedef
 225 EFI_STATUS
 226 (EFIAPI *EFI_SMM_WRITE_SAVE_STATE)(
 227   IN CONST EFI_SMM_CPU_PROTOCOL   *This,
 228   IN UINTN                        Width,
 229   IN EFI_SMM_SAVE_STATE_REGISTER  Register,
 230   IN UINTN                        CpuIndex,
 231   IN CONST VOID                   *Buffer
 232   );
 233
 234 ///
 235 /// EFI SMM CPU Protocol provides access to CPU-related information while in SMM.
 236 ///
 237 /// This protocol allows SMM drivers to access architecture-standard registers from any of the CPU
 238 /// save state areas. In some cases, difference processors provide the same information in the save state,
 239 /// but not in the same format. These so-called pseudo-registers provide this information in a standard
 240 /// format.
 241 ///
 242 struct _EFI_SMM_CPU_PROTOCOL {
 243   EFI_SMM_READ_SAVE_STATE   ReadSaveState;
 244   EFI_SMM_WRITE_SAVE_STATE  WriteSaveState;
 245 };
 246
 247 extern EFI_GUID gEfiSmmCpuProtocolGuid;
 248
 249 #endif
 250