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