IntelFrameworkPkg/Include/Framework/SmmCis.h

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