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