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