IntelFrameworkPkg/Include/Framework/SmmCis.h

   1 /** @file
   2   Include file for definitions in the Intel Platform Innovation Framework for EFI
   3   System Management Mode Core Interface Specification (SMM CIS) version 0.91.
   4
   5   Copyright (c) 2007 - 2010, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _SMM_CIS_H_
  17 #define _SMM_CIS_H_
  18
  19 //
  20 // Share some common definitions with PI SMM
  21 //
  22 #include <Pi/PiSmmCis.h>
  23 #include <Protocol/SmmCpuIo.h>
  24
  25 typedef struct _EFI_SMM_SYSTEM_TABLE      EFI_SMM_SYSTEM_TABLE;
  26
  27 //
  28 // SMM Base specification constant and types
  29 //
  30 #define EFI_SMM_SYSTEM_TABLE_REVISION (0 << 16) | (0x09)
  31
  32 /**
  33   Allocates pool memory from SMRAM for IA-32 or runtime memory for
  34   the Itanium processor family.
  35
  36   @param  PoolType         The type of pool to allocate. The only supported type is EfiRuntimeServicesData
  37   @param  Size             The number of bytes to allocate from the pool.
  38   @param  Buffer           A pointer to a pointer to the allocated buffer if the call
  39                            succeeds; undefined otherwise.
  40
  41   @retval EFI_SUCCESS           The requested number of bytes was allocated.
  42   @retval EFI_OUT_OF_RESOURCES  The pool requested could not be allocated.
  43   @retval EFI_UNSUPPORTED       In runtime.
  44   @note  Inconsistent with specification here:
  45          In Framework Spec, this definition is named EFI_SMM_ALLOCATE_POOL.
  46          To avoid a naming conflict, the definition is renamed.
  47 **/
  48 typedef
  49 EFI_STATUS
  50 (EFIAPI *EFI_SMMCORE_ALLOCATE_POOL)(
  51   IN EFI_MEMORY_TYPE                PoolType,
  52   IN UINTN                          Size,
  53   OUT VOID                          **Buffer
  54   );
  55
  56 /**
  57   Returns pool memory to the system.
  58
  59   @param  Buffer           Pointer to the buffer to free.
  60
  61   @retval EFI_SUCCESS           The memory was returned to the system.
  62   @retval EFI_INVALID_PARAMETER Buffer was invalid.
  63   @retval EFI_UNSUPPORTED       In runtime.
  64   @note  Inconsistent with specification here:
  65          In Framework Spec, this definition is named EFI_SMM_FREE_POOL.
  66          To avoid a naming conflict, the definition is renamed.
  67 **/
  68 typedef
  69 EFI_STATUS
  70 (EFIAPI *EFI_SMMCORE_FREE_POOL)(
  71   IN VOID                   *Buffer
  72   );
  73
  74 /**
  75   Allocates memory pages from the system.
  76
  77   @param  Type             The type of allocation to perform.
  78   @param  MemoryType       The only supported type is EfiRuntimeServicesData
  79   @param  NumberofPages    The number of contiguous 4 KB pages to allocate
  80   @param  Memory           Pointer to a physical address. On input, the way in which
  81                            the address is used depends on the value of Type. On output, the address
  82                            is set to the base of the page range that was allocated.
  83
  84   @retval EFI_SUCCESS           The requested pages were allocated.
  85   @retval EFI_OUT_OF_RESOURCES  The pages requested could not be allocated.
  86   @retval EFI_NOT_FOUND         The requested pages could not be found.
  87   @retval EFI_INVALID_PARAMETER Type is not AllocateAnyPages or AllocateMaxAddress
  88                                 or AllocateAddress. Or MemoryType is in the range EfiMaxMemoryType..0x7FFFFFFF.
  89   @note  Inconsistent with specification here:
  90          In the Framework Spec, this definition is named EFI_SMM_ALLOCATE_PAGES.
  91          To avoid a naming conflict, the definition here is renamed.
  92 **/
  93 typedef
  94 EFI_STATUS
  95 (EFIAPI *EFI_SMMCORE_ALLOCATE_PAGES)(
  96   IN EFI_ALLOCATE_TYPE      Type,
  97   IN EFI_MEMORY_TYPE        MemoryType,
  98   IN UINTN                  NumberOfPages,
  99   OUT EFI_PHYSICAL_ADDRESS  *Memory
 100   );
 101
 102 /**
 103   Frees memory pages for the system.
 104
 105   @param  Memory           The base physical address of the pages to be freed
 106   @param  NumberOfPages    The number of contiguous 4 KB pages to free.
 107
 108   @retval EFI_SUCCESS           The requested memory pages were freed.
 109   @retval EFI_INVALID_PARAMETER Memory is not a page-aligned address or NumberOfPages is invalid.
 110   @retval EFI_NOT_FOUND         The requested memory pages were not allocated with SmmAllocatePages().
 111
 112   @note  Inconsistent with specification here:
 113          In the Framework Spec, this definition is named EFI_SMM_FREE_PAGES.
 114          To avoid a naming conflict, the definition here is renamed.
 115 **/
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *EFI_SMMCORE_FREE_PAGES)(
 119   IN EFI_PHYSICAL_ADDRESS   Memory,
 120   IN UINTN                  NumberOfPages
 121   );
 122
 123 ///
 124 /// The processor save-state information for IA-32 processors. This information is important in that the
 125 /// SMM drivers may need to ascertain the state of the processor before invoking the SMI.
 126 ///
 127 typedef struct {
 128   ///
 129   /// Reserved for future processors. As such, software should not attempt to interpret or
 130   /// write to this region.
 131   ///
 132   UINT8                 Reserved1[248];
 133   ///
 134   /// The location of the processor SMBASE, which is the location where the processor
 135   /// will pass control upon receipt of an SMI.
 136   ///
 137   UINT32                SMBASE;
 138   ///
 139   /// The revision of the SMM save state. This value is set by the processor.
 140   ///
 141   UINT32                SMMRevId;
 142   ///
 143   /// The value of the I/O restart field. Allows for restarting an in-process I/O instruction.
 144   ///
 145   UINT16                IORestart;
 146   ///
 147   /// Describes behavior that should be commenced in response to a halt instruction.
 148   ///
 149   UINT16                AutoHALTRestart;
 150   ///
 151   /// Reserved for future processors. As such, software should not attempt to interpret or
 152   /// write to this region.
 153   ///
 154   UINT8                 Reserved2[164];
 155
 156   //
 157   // Registers in IA-32 processors.
 158   //
 159   UINT32                ES;
 160   UINT32                CS;
 161   UINT32                SS;
 162   UINT32                DS;
 163   UINT32                FS;
 164   UINT32                GS;
 165   UINT32                LDTBase;
 166   UINT32                TR;
 167   UINT32                DR7;
 168   UINT32                DR6;
 169   UINT32                EAX;
 170   UINT32                ECX;
 171   UINT32                EDX;
 172   UINT32                EBX;
 173   UINT32                ESP;
 174   UINT32                EBP;
 175   UINT32                ESI;
 176   UINT32                EDI;
 177   UINT32                EIP;
 178   UINT32                EFLAGS;
 179   UINT32                CR3;
 180   UINT32                CR0;
 181 } EFI_SMI_CPU_SAVE_STATE;
 182
 183 ///
 184 /// The processor save-state information for the Itanium processor family. This information is
 185 /// important in that the SMM drivers may need to ascertain the state of the processor before invoking
 186 /// the PMI. This structure is mandatory and must be 512 byte aligned.
 187 ///
 188 typedef struct {
 189   UINT64   reserved;
 190   UINT64   r1;
 191   UINT64   r2;
 192   UINT64   r3;
 193   UINT64   r4;
 194   UINT64   r5;
 195   UINT64   r6;
 196   UINT64   r7;
 197   UINT64   r8;
 198   UINT64   r9;
 199   UINT64   r10;
 200   UINT64   r11;
 201   UINT64   r12;
 202   UINT64   r13;
 203   UINT64   r14;
 204   UINT64   r15;
 205   UINT64   r16;
 206   UINT64   r17;
 207   UINT64   r18;
 208   UINT64   r19;
 209   UINT64   r20;
 210   UINT64   r21;
 211   UINT64   r22;
 212   UINT64   r23;
 213   UINT64   r24;
 214   UINT64   r25;
 215   UINT64   r26;
 216   UINT64   r27;
 217   UINT64   r28;
 218   UINT64   r29;
 219   UINT64   r30;
 220   UINT64   r31;
 221
 222   UINT64   pr;
 223
 224   UINT64   b0;
 225   UINT64   b1;
 226   UINT64   b2;
 227   UINT64   b3;
 228   UINT64   b4;
 229   UINT64   b5;
 230   UINT64   b6;
 231   UINT64   b7;
 232
 233   // application registers
 234   UINT64   ar_rsc;
 235   UINT64   ar_bsp;
 236   UINT64   ar_bspstore;
 237   UINT64   ar_rnat;
 238
 239   UINT64   ar_fcr;
 240
 241   UINT64   ar_eflag;
 242   UINT64   ar_csd;
 243   UINT64   ar_ssd;
 244   UINT64   ar_cflg;
 245   UINT64   ar_fsr;
 246   UINT64   ar_fir;
 247   UINT64   ar_fdr;
 248
 249   UINT64   ar_ccv;
 250
 251   UINT64   ar_unat;
 252
 253   UINT64   ar_fpsr;
 254
 255   UINT64   ar_pfs;
 256   UINT64   ar_lc;
 257   UINT64   ar_ec;
 258
 259   // control registers
 260   UINT64   cr_dcr;
 261   UINT64   cr_itm;
 262   UINT64   cr_iva;
 263   UINT64   cr_pta;
 264   UINT64   cr_ipsr;
 265   UINT64   cr_isr;
 266   UINT64   cr_iip;
 267   UINT64   cr_ifa;
 268   UINT64   cr_itir;
 269   UINT64   cr_iipa;
 270   UINT64   cr_ifs;
 271   UINT64   cr_iim;
 272   UINT64   cr_iha;
 273
 274   // debug registers
 275   UINT64   dbr0;
 276   UINT64   dbr1;
 277   UINT64   dbr2;
 278   UINT64   dbr3;
 279   UINT64   dbr4;
 280   UINT64   dbr5;
 281   UINT64   dbr6;
 282   UINT64   dbr7;
 283
 284   UINT64   ibr0;
 285   UINT64   ibr1;
 286   UINT64   ibr2;
 287   UINT64   ibr3;
 288   UINT64   ibr4;
 289   UINT64   ibr5;
 290   UINT64   ibr6;
 291   UINT64   ibr7;
 292
 293   // virtual registers
 294   UINT64   int_nat;         // nat bits for R1-R31
 295
 296 } EFI_PMI_SYSTEM_CONTEXT;
 297
 298 ///
 299 /// The processor save-state information for IA-32 and Itanium processors. This information is
 300 /// important in that the SMM drivers may need to ascertain the state of the processor before invoking
 301 /// the SMI or PMI.
 302 ///
 303 typedef union {
 304   ///
 305   /// The processor save-state information for IA-32 processors.
 306   ///
 307   EFI_SMI_CPU_SAVE_STATE     Ia32SaveState;
 308   ///
 309   /// The processor save-state information for Itanium processors.
 310   ///
 311   EFI_PMI_SYSTEM_CONTEXT     ItaniumSaveState;
 312 } EFI_SMM_CPU_SAVE_STATE;
 313
 314 ///
 315 /// The optional floating point save-state information for IA-32 processors. If the optional floating
 316 /// point save is indicated for any handler, the following data structure must be preserved.
 317 ///
 318 typedef struct {
 319   UINT16                Fcw;
 320   UINT16                Fsw;
 321   UINT16                Ftw;
 322   UINT16                Opcode;
 323   UINT32                Eip;
 324   UINT16                Cs;
 325   UINT16                Rsvd1;
 326   UINT32                DataOffset;
 327   UINT16                Ds;
 328   UINT8                 Rsvd2[10];
 329   UINT8                 St0Mm0[10], Rsvd3[6];
 330   UINT8                 St0Mm1[10], Rsvd4[6];
 331   UINT8                 St0Mm2[10], Rsvd5[6];
 332   UINT8                 St0Mm3[10], Rsvd6[6];
 333   UINT8                 St0Mm4[10], Rsvd7[6];
 334   UINT8                 St0Mm5[10], Rsvd8[6];
 335   UINT8                 St0Mm6[10], Rsvd9[6];
 336   UINT8                 St0Mm7[10], Rsvd10[6];
 337   UINT8                 Rsvd11[22*16];
 338 } EFI_SMI_OPTIONAL_FPSAVE_STATE;
 339
 340 ///
 341 /// The optional floating point save-state information for the Itanium processor family. If the optional
 342 /// floating point save is indicated for any handler, then this data structure must be preserved.
 343 ///
 344 typedef struct {
 345   UINT64   f2[2];
 346   UINT64   f3[2];
 347   UINT64   f4[2];
 348   UINT64   f5[2];
 349   UINT64   f6[2];
 350   UINT64   f7[2];
 351   UINT64   f8[2];
 352   UINT64   f9[2];
 353   UINT64   f10[2];
 354   UINT64   f11[2];
 355   UINT64   f12[2];
 356   UINT64   f13[2];
 357   UINT64   f14[2];
 358   UINT64   f15[2];
 359   UINT64   f16[2];
 360   UINT64   f17[2];
 361   UINT64   f18[2];
 362   UINT64   f19[2];
 363   UINT64   f20[2];
 364   UINT64   f21[2];
 365   UINT64   f22[2];
 366   UINT64   f23[2];
 367   UINT64   f24[2];
 368   UINT64   f25[2];
 369   UINT64   f26[2];
 370   UINT64   f27[2];
 371   UINT64   f28[2];
 372   UINT64   f29[2];
 373   UINT64   f30[2];
 374   UINT64   f31[2];
 375 } EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT;
 376
 377 ///
 378 /// The processor save-state information for IA-32 and Itanium processors. If the optional floating
 379 /// point save is indicated for any handler, then this data structure must be preserved.
 380 ///
 381 typedef union {
 382   ///
 383   /// The optional floating point save-state information for IA-32 processors.
 384   ///
 385   EFI_SMI_OPTIONAL_FPSAVE_STATE             Ia32FpSave;
 386   ///
 387   /// The optional floating point save-state information for Itanium processors.
 388   ///
 389   EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT   ItaniumFpSave;
 390 } EFI_SMM_FLOATING_POINT_SAVE_STATE;
 391
 392 /**
 393   This function is the main entry point for an SMM handler dispatch
 394   or communicate-based callback.
 395
 396   @param  SmmImageHandle   A unique value returned by the SMM infrastructure
 397                            in response to registration for a communicate-based callback or dispatch.
 398   @param  CommunicationBuffer
 399                            An optional buffer that will be populated
 400                            by the SMM infrastructure in response to a non-SMM agent (preboot or runtime)
 401                            invoking the EFI_SMM_BASE_PROTOCOL.Communicate() service.
 402   @param  SourceSize       If CommunicationBuffer is non-NULL, this field
 403                            indicates the size of the data payload in this buffer.
 404
 405   @return Status Code
 406
 407 **/
 408 typedef
 409 EFI_STATUS
 410 (EFIAPI *EFI_SMM_HANDLER_ENTRY_POINT)(
 411   IN EFI_HANDLE             SmmImageHandle,
 412   IN OUT VOID               *CommunicationBuffer OPTIONAL,
 413   IN OUT UINTN              *SourceSize OPTIONAL
 414   );
 415
 416 /**
 417   The SmmInstallConfigurationTable() function is used to maintain the list
 418   of configuration tables that are stored in the System Management System
 419   Table.  The list is stored as an array of (GUID, Pointer) pairs.  The list
 420   must be allocated from pool memory with PoolType set to EfiRuntimeServicesData.
 421
 422   @param  SystemTable      A pointer to the SMM System Table.
 423   @param  Guid             A pointer to the GUID for the entry to add, update, or remove.
 424   @param  Table            A pointer to the buffer of the table to add.
 425   @param  TableSize        The size of the table to install.
 426
 427   @retval EFI_SUCCESS           The (Guid, Table) pair was added, updated, or removed.
 428   @retval EFI_INVALID_PARAMETER Guid is not valid.
 429   @retval EFI_NOT_FOUND         An attempt was made to delete a non-existent entry.
 430   @retval EFI_OUT_OF_RESOURCES  There is not enough memory available to complete the operation.
 431
 432 **/
 433 typedef
 434 EFI_STATUS
 435 (EFIAPI *EFI_SMM_INSTALL_CONFIGURATION_TABLE)(
 436   IN EFI_SMM_SYSTEM_TABLE         *SystemTable,
 437   IN EFI_GUID                     *Guid,
 438   IN VOID                         *Table,
 439   IN UINTN                        TableSize
 440   );
 441
 442 //
 443 // System Management System Table (SMST)
 444 //
 445 struct _EFI_SMM_SYSTEM_TABLE {
 446   ///
 447   /// The table header for the System Management System Table (SMST).
 448   ///
 449   EFI_TABLE_HEADER                    Hdr;
 450
 451   ///
 452   /// A pointer to a NULL-terminated Unicode string containing the vendor name. It is
 453   /// permissible for this pointer to be NULL.
 454   ///
 455   CHAR16                              *SmmFirmwareVendor;
 456   ///
 457   /// The particular revision of the firmware.
 458   ///
 459   UINT32                              SmmFirmwareRevision;
 460
 461   ///
 462   /// Adds, updates, or removes a configuration table entry from the SMST.
 463   ///
 464   EFI_SMM_INSTALL_CONFIGURATION_TABLE SmmInstallConfigurationTable;
 465
 466   //
 467   // I/O Services
 468   //
 469   ///
 470   /// A GUID that designates the particular CPU I/O services.
 471   ///
 472   EFI_GUID                            EfiSmmCpuIoGuid;
 473   ///
 474   /// Provides the basic memory and I/O interfaces that are used to abstract accesses to
 475   /// devices.
 476   ///
 477   EFI_SMM_CPU_IO_INTERFACE            SmmIo;
 478
 479   //
 480   // Runtime memory service
 481   //
 482   ///
 483   ///
 484   /// Allocates pool memory from SMRAM for IA-32 or runtime memory for the
 485   /// Itanium processor family.
 486   ///
 487   EFI_SMMCORE_ALLOCATE_POOL           SmmAllocatePool;
 488   ///
 489   /// Returns pool memory to the system.
 490   ///
 491   EFI_SMMCORE_FREE_POOL               SmmFreePool;
 492   ///
 493   /// Allocates memory pages from the system.
 494   ///
 495   EFI_SMMCORE_ALLOCATE_PAGES          SmmAllocatePages;
 496   ///
 497   /// Frees memory pages for the system.
 498   ///
 499   EFI_SMMCORE_FREE_PAGES              SmmFreePages;
 500
 501   //
 502   // MP service
 503   //
 504
 505   ///Inconsistent with specification here:
 506   ///  In Framework Spec, this definition does not exist. This method is introduced in PI1.1 spec for
 507   ///  implementation needed.
 508   EFI_SMM_STARTUP_THIS_AP             SmmStartupThisAp;
 509
 510   //
 511   // CPU information records
 512   //
 513   ///
 514   /// A 1-relative number between 1 and the NumberOfCpus field. This field designates
 515   /// which processor is executing the SMM infrastructure. This number also serves as an
 516   /// index into the CpuSaveState and CpuOptionalFloatingPointState
 517   /// fields.
 518   ///
 519   UINTN                               CurrentlyExecutingCpu;
 520   ///
 521   /// The number of EFI Configuration Tables in the buffer
 522   /// SmmConfigurationTable.
 523   ///
 524   UINTN                               NumberOfCpus;
 525   ///
 526   /// A pointer to the EFI Configuration Tables. The number of entries in the table is
 527   /// NumberOfTableEntries.
 528   ///
 529   EFI_SMM_CPU_SAVE_STATE              *CpuSaveState;
 530   ///
 531   /// A pointer to a catenation of the EFI_SMM_FLOATING_POINT_SAVE_STATE.
 532   /// The size of this entire table is NumberOfCpus* size of the
 533   /// EFI_SMM_FLOATING_POINT_SAVE_STATE. These fields are populated only if
 534   /// there is at least one SMM driver that has registered for a callback with the
 535   /// FloatingPointSave field in EFI_SMM_BASE_PROTOCOL.RegisterCallback() set to TRUE.
 536   ///
 537   EFI_SMM_FLOATING_POINT_SAVE_STATE   *CpuOptionalFloatingPointState;
 538
 539   //
 540   // Extensibility table
 541   //
 542   ///
 543   /// The number of EFI Configuration Tables in the buffer
 544   /// SmmConfigurationTable.
 545   ///
 546   UINTN                               NumberOfTableEntries;
 547   ///
 548   /// A pointer to the EFI Configuration Tables. The number of entries in the table is
 549   /// NumberOfTableEntries.
 550   ///
 551   EFI_CONFIGURATION_TABLE             *SmmConfigurationTable;
 552 };
 553
 554 #endif