Synchronize code with specs.

[mirror_edk2.git] / IntelFrameworkPkg / Include / Framework / SmmCis.h

diff --git a/IntelFrameworkPkg/Include/Framework/SmmCis.h b/IntelFrameworkPkg/Include/Framework/SmmCis.h
index c246b8366b01192269fe0606e386032b1b95785e..03d4c7547cdcfaff858e5e5833d20e9b8b9d8098 100644 (file)
--- a/IntelFrameworkPkg/Include/Framework/SmmCis.h
+++ b/IntelFrameworkPkg/Include/Framework/SmmCis.h
@@ -77,12 +77,22 @@ EFI_STATUS
   );\r
 \r
 typedef struct {\r
   );\r
 \r
 typedef struct {\r

-  EFI_SMM_CPU_IO  Read;\r
-  EFI_SMM_CPU_IO  Write;\r
+  EFI_SMM_CPU_IO  Read;  ///> This service provides the various modalities of memory and I/O read.\r
+  EFI_SMM_CPU_IO  Write; ///> This service provides the various modalities of memory and I/O write.\r

 } EFI_SMM_IO_ACCESS;\r
 \r
 } EFI_SMM_IO_ACCESS;\r
 \r

+///\r
+/// The EFI_SMM_CPU_IO_INTERFACE service provides the basic memory, I/O, and PCI\r
+/// interfaces that are used to abstract accesses to devices.\r
+///\r

 struct _EFI_SMM_CPU_IO_INTERFACE {\r
 struct _EFI_SMM_CPU_IO_INTERFACE {\r

+  ///\r
+  /// Allows reads and writes to memory-mapped I/O space. \r
+  ///\r

   EFI_SMM_IO_ACCESS Mem;\r
   EFI_SMM_IO_ACCESS Mem;\r

+  ///\r
+  /// Allows reads and writes to I/O space. \r
+  ///\r

   EFI_SMM_IO_ACCESS Io;\r
 };\r
 \r
   EFI_SMM_IO_ACCESS Io;\r
 };\r
 \r


@@ -176,13 +186,42 @@ EFI_STATUS
   IN  OUT VOID                            *ProcArguments OPTIONAL\r
   );\r
 \r
   IN  OUT VOID                            *ProcArguments OPTIONAL\r
   );\r
 \r

+///\r
+/// The processor save-state information for IA-32 processors. This information is important in that the\r
+/// SMM drivers may need to ascertain the state of the processor before invoking the SMI.\r
+///\r

 typedef struct {\r
 typedef struct {\r

+  ///\r
+  /// Reserved for future processors. As such, software should not attempt to interpret or\r
+  /// write to this region.\r
+  ///\r

   UINT8                 Reserved1[248];\r
   UINT8                 Reserved1[248];\r

+  ///\r
+  /// The location of the processor SMBASE, which is the location where the processor\r
+  /// will pass control upon receipt of an SMI.\r
+  ///\r

   UINT32                SMBASE;\r
   UINT32                SMBASE;\r

+  ///\r
+  /// The revision of the SMM save state. This value is set by the processor.\r
+  ///\r

   UINT32                SMMRevId;\r
   UINT32                SMMRevId;\r

+  ///\r
+  /// The value of the I/O restart field. Allows for restarting an in-process I/O instruction.\r
+  ///\r

   UINT16                IORestart;\r
   UINT16                IORestart;\r

+  ///\r
+  /// Describes behavior that should be commenced in response to a halt instruction.\r
+  ///\r

   UINT16                AutoHALTRestart;\r
   UINT16                AutoHALTRestart;\r

+  ///\r
+  /// Reserved for future processors. As such, software should not attempt to interpret or\r
+  /// write to this region.\r
+  ///\r

   UINT8                 Reserved2[164];\r
   UINT8                 Reserved2[164];\r

+\r
+  //\r
+  // Registers in IA-32 processors. \r
+  //\r

   UINT32                ES;\r
   UINT32                CS;\r
   UINT32                SS;\r
   UINT32                ES;\r
   UINT32                CS;\r
   UINT32                SS;\r


@@ -207,6 +246,11 @@ typedef struct {
   UINT32                CR0;\r
 } EFI_SMI_CPU_SAVE_STATE;\r
 \r
   UINT32                CR0;\r
 } EFI_SMI_CPU_SAVE_STATE;\r
 \r

+///\r
+/// The processor save-state information for the Itanium processor family. This information is\r
+/// important in that the SMM drivers may need to ascertain the state of the processor before invoking\r
+/// the PMI. This structure is mandatory and must be 512 byte aligned.\r
+/// \r

 typedef struct {\r
   UINT64   reserved;\r
   UINT64   r1;\r
 typedef struct {\r
   UINT64   reserved;\r
   UINT64   r1;\r


@@ -317,11 +361,26 @@ typedef struct {
 \r
 } EFI_PMI_SYSTEM_CONTEXT;\r
 \r
 \r
 } EFI_PMI_SYSTEM_CONTEXT;\r
 \r

+///\r
+/// The processor save-state information for IA-32 and Itanium processors. This information is\r
+/// important in that the SMM drivers may need to ascertain the state of the processor before invoking\r
+/// the SMI or PMI.\r
+///\r

 typedef union {\r
 typedef union {\r

+  ///\r
+  /// The processor save-state information for IA-32 processors. \r
+  ///\r

   EFI_SMI_CPU_SAVE_STATE     Ia32SaveState;\r
   EFI_SMI_CPU_SAVE_STATE     Ia32SaveState;\r

+  ///\r
+  /// The processor save-state information for Itanium processors.\r
+  ///\r

   EFI_PMI_SYSTEM_CONTEXT     ItaniumSaveState;\r
 } EFI_SMM_CPU_SAVE_STATE;\r
 \r
   EFI_PMI_SYSTEM_CONTEXT     ItaniumSaveState;\r
 } EFI_SMM_CPU_SAVE_STATE;\r
 \r

+///\r
+/// The optional floating point save-state information for IA-32 processors. If the optional floating\r
+/// point save is indicated for any handler, the following data structure must be preserved.\r
+///\r

 typedef struct {\r
   UINT16                Fcw;\r
   UINT16                Fsw;\r
 typedef struct {\r
   UINT16                Fcw;\r
   UINT16                Fsw;\r


@@ -344,6 +403,10 @@ typedef struct {
   UINT8                 Rsvd11[22*16];\r
 } EFI_SMI_OPTIONAL_FPSAVE_STATE;\r
 \r
   UINT8                 Rsvd11[22*16];\r
 } EFI_SMI_OPTIONAL_FPSAVE_STATE;\r
 \r

+///\r
+/// The optional floating point save-state information for the Itanium processor family. If the optional\r
+/// floating point save is indicated for any handler, then this data structure must be preserved. \r
+/// \r

 typedef struct {\r
   UINT64   f2[2];\r
   UINT64   f3[2];\r
 typedef struct {\r
   UINT64   f2[2];\r
   UINT64   f3[2];\r


@@ -377,8 +440,18 @@ typedef struct {
   UINT64   f31[2];\r
 } EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT;\r
 \r
   UINT64   f31[2];\r
 } EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT;\r
 \r

+///\r
+/// The processor save-state information for IA-32 and Itanium processors. If the optional floating\r
+/// point save is indicated for any handler, then this data structure must be preserved.\r
+///\r

 typedef union {\r
 typedef union {\r

+  /// \r
+  /// The optional floating point save-state information for IA-32 processors. \r
+  ///\r

   EFI_SMI_OPTIONAL_FPSAVE_STATE             Ia32FpSave;\r
   EFI_SMI_OPTIONAL_FPSAVE_STATE             Ia32FpSave;\r

+  ///\r
+  /// The optional floating point save-state information for Itanium processors. \r
+  ///\r

   EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT   ItaniumFpSave;\r
 } EFI_SMM_FLOATING_POINT_SAVE_STATE;\r
 \r
   EFI_PMI_OPTIONAL_FLOATING_POINT_CONTEXT   ItaniumFpSave;\r
 } EFI_SMM_FLOATING_POINT_SAVE_STATE;\r
 \r


@@ -436,25 +509,58 @@ EFI_STATUS
 // System Management System Table (SMST)\r
 //\r
 struct _EFI_SMM_SYSTEM_TABLE {\r
 // System Management System Table (SMST)\r
 //\r
 struct _EFI_SMM_SYSTEM_TABLE {\r

+  ///\r
+  /// The table header for the System Management System Table (SMST). \r
+  ///\r

   EFI_TABLE_HEADER                    Hdr;\r
 \r
   EFI_TABLE_HEADER                    Hdr;\r
 \r

+  ///\r
+  /// A pointer to a NULL-terminated Unicode string containing the vendor name. It is\r
+  /// permissible for this pointer to be NULL.\r
+  ///\r

   CHAR16                              *SmmFirmwareVendor;\r
   CHAR16                              *SmmFirmwareVendor;\r

+  ///\r
+  /// The particular revision of the firmware.\r
+  ///\r

   UINT32                              SmmFirmwareRevision;\r
 \r
   UINT32                              SmmFirmwareRevision;\r
 \r

+  ///\r
+  /// Adds, updates, or removes a configuration table entry from the SMST. \r
+  ///\r

   EFI_SMM_INSTALL_CONFIGURATION_TABLE SmmInstallConfigurationTable;\r
 \r
   //\r
   // I/O Services\r
   //\r
   EFI_SMM_INSTALL_CONFIGURATION_TABLE SmmInstallConfigurationTable;\r
 \r
   //\r
   // I/O Services\r
   //\r

+  ///\r
+  /// A GUID that designates the particular CPU I/O services. \r
+  ///\r

   EFI_GUID                            EfiSmmCpuIoGuid;\r
   EFI_GUID                            EfiSmmCpuIoGuid;\r

+  ///\r
+  /// Provides the basic memory and I/O interfaces that are used to abstract accesses to\r
+  /// devices.\r
+  ///\r

   EFI_SMM_CPU_IO_INTERFACE            SmmIo;\r
 \r
   //\r
   // Runtime memory service\r
   //\r
   EFI_SMM_CPU_IO_INTERFACE            SmmIo;\r
 \r
   //\r
   // Runtime memory service\r
   //\r

+  ///\r
+  /// Allocates pool memory from SMRAM for IA-32 or runtime memory for the\r
+  /// Itanium processor family.\r
+  ///\r

   EFI_SMMCORE_ALLOCATE_POOL           SmmAllocatePool;\r
   EFI_SMMCORE_ALLOCATE_POOL           SmmAllocatePool;\r

+  ///\r
+  /// Returns pool memory to the system. \r
+  ///\r

   EFI_SMMCORE_FREE_POOL               SmmFreePool;\r
   EFI_SMMCORE_FREE_POOL               SmmFreePool;\r

+  ///\r
+  /// Allocates memory pages from the system. \r
+  ///\r

   EFI_SMMCORE_ALLOCATE_PAGES          SmmAllocatePages;\r
   EFI_SMMCORE_ALLOCATE_PAGES          SmmAllocatePages;\r

+  ///\r
+  /// Frees memory pages for the system.\r
+  ///\r

   EFI_SMMCORE_FREE_PAGES              SmmFreePages;\r
 \r
   //\r
   EFI_SMMCORE_FREE_PAGES              SmmFreePages;\r
 \r
   //\r


@@ -465,15 +571,44 @@ struct _EFI_SMM_SYSTEM_TABLE {
   //\r
   // CPU information records\r
   //\r
   //\r
   // CPU information records\r
   //\r

+  ///\r
+  /// A 1-relative number between 1 and the NumberOfCpus field. This field designates\r
+  /// which processor is executing the SMM infrastructure. This number also serves as an\r
+  /// index into the CpuSaveState and CpuOptionalFloatingPointState\r
+  /// fields.\r
+  ///\r

   UINTN                               CurrentlyExecutingCpu;\r
   UINTN                               CurrentlyExecutingCpu;\r

+  ///\r
+  /// The number of EFI Configuration Tables in the buffer\r
+  /// SmmConfigurationTable.\r
+  ///\r

   UINTN                               NumberOfCpus;\r
   UINTN                               NumberOfCpus;\r

+  ///\r
+  /// A pointer to the EFI Configuration Tables. The number of entries in the table is\r
+  /// NumberOfTableEntries.\r
+  ///\r

   EFI_SMM_CPU_SAVE_STATE              *CpuSaveState;\r
   EFI_SMM_CPU_SAVE_STATE              *CpuSaveState;\r

+  ///\r
+  /// A pointer to a catenation of the EFI_SMM_FLOATING_POINT_SAVE_STATE.\r
+  /// The size of this entire table is NumberOfCpus* size of the\r
+  /// EFI_SMM_FLOATING_POINT_SAVE_STATE. These fields are populated only if\r
+  /// there is at least one SMM driver that has registered for a callback with the\r
+  /// FloatingPointSave field in EFI_SMM_BASE_PROTOCOL.RegisterCallback() set to TRUE.\r
+  ///\r

   EFI_SMM_FLOATING_POINT_SAVE_STATE   *CpuOptionalFloatingPointState;\r
 \r
   //\r
   // Extensibility table\r
   //\r
   EFI_SMM_FLOATING_POINT_SAVE_STATE   *CpuOptionalFloatingPointState;\r
 \r
   //\r
   // Extensibility table\r
   //\r

+  ///\r
+  /// The number of EFI Configuration Tables in the buffer\r
+  /// SmmConfigurationTable.\r
+  ///\r

   UINTN                               NumberOfTableEntries;\r
   UINTN                               NumberOfTableEntries;\r

+  ///\r
+  /// A pointer to the EFI Configuration Tables. The number of entries in the table is\r
+  /// NumberOfTableEntries.\r
+  ///\r

   EFI_CONFIGURATION_TABLE             *SmmConfigurationTable;\r
 };\r
 \r
   EFI_CONFIGURATION_TABLE             *SmmConfigurationTable;\r
 };\r
 \r