UefiCpuPkg/Include: Expand description of AcpiCpuData.h structures

Provide a more detailed description of each field of the
ACPI_CPU_DATA and CPU_REGISTER_TABLE structures.

Cc: Laszlo Ersek <lersek@redhat.com>
Cc: "Yao, Jiewen" <jiewen.yao@intel.com>
Cc: "Fan, Jeff" <jeff.fan@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Tested-by: Laszlo Ersek <lersek@redhat.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@18950 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/UefiCpuPkg/Include/AcpiCpuData.h b/UefiCpuPkg/Include/AcpiCpuData.h
index a36725711cd8ed9d3e2760356b6d15e6b3d3aab8..12e9692c5cf80b5294ef14c61c43a1788b9e844a 100644 (file)
--- a/UefiCpuPkg/Include/AcpiCpuData.h
+++ b/UefiCpuPkg/Include/AcpiCpuData.h
@@ -18,7 +18,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //\r
 // Register types in register table\r
 //\r
-typedef enum _REGISTER_TYPE {\r
+typedef enum {\r
   Msr,\r
   ControlRegister,\r
   MemoryMapped,\r
@@ -29,11 +29,11 @@ typedef enum _REGISTER_TYPE {
 // Element of register table entry\r
 //\r
 typedef struct {\r
-  REGISTER_TYPE RegisterType;\r
-  UINT32        Index;\r
-  UINT8         ValidBitStart;\r
-  UINT8         ValidBitLength;\r
-  UINT64        Value;\r
+  REGISTER_TYPE  RegisterType;\r
+  UINT32         Index;\r
+  UINT8          ValidBitStart;\r
+  UINT8          ValidBitLength;\r
+  UINT64         Value;\r
 } CPU_REGISTER_TABLE_ENTRY;\r
 \r
 //\r
@@ -41,30 +41,119 @@ typedef struct {
 // allocated size of this table, and pointer to the list of table entries.\r
 //\r
 typedef struct {\r
-  UINT32                   TableLength;\r
-  UINT32                   NumberBeforeReset;\r
-  UINT32                   AllocatedSize;\r
-  UINT32                   InitialApicId;\r
-  CPU_REGISTER_TABLE_ENTRY *RegisterTableEntry;\r
+  //\r
+  // The number of valid entries in the RegisterTableEntry buffer\r
+  //\r
+  UINT32                    TableLength;\r
+  UINT32                    NumberBeforeReset;\r
+  //\r
+  // The size, in bytes, of the RegisterTableEntry buffer\r
+  //\r
+  UINT32                    AllocatedSize;\r
+  //\r
+  // The initial APIC ID of the CPU this register table applies to\r
+  //\r
+  UINT32                    InitialApicId;\r
+  //\r
+  // Buffer of CPU_REGISTER_TABLE_ENTRY structures.  This buffer must be\r
+  // allocated below 4GB from memory of type EfiACPIMemoryNVS.\r
+  //\r
+  CPU_REGISTER_TABLE_ENTRY  *RegisterTableEntry;\r
 } CPU_REGISTER_TABLE;\r
 \r
+//\r
+// Data structure that is required for ACPI S3 resume.  This structure must be\r
+// allocated below 4GB from memory of type EfiACPIMemoryNVS.  The PCD\r
+// PcdCpuS3DataAddress must be set to the physical address where this structure\r
+// is allocated\r
+//\r
 typedef struct {\r
+  //\r
+  // Physical address of 4KB buffer allocated below 1MB from memory of type\r
+  // EfiReservedMemoryType.  The buffer is not required to be initialized, but\r
+  // it is recommended that the buffer be zero-filled.  This buffer is used to\r
+  // wake APs during an ACPI S3 resume.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  StartupVector;\r
+  //\r
+  // Physical address of structure of type IA32_DESCRIPTOR.  This structure must\r
+  // be allocated below 4GB from memory of type EfiACPIMemoryNVS.  The\r
+  // IA32_DESCRIPTOR structure provides the base address and length of a GDT\r
+  // The buffer for GDT must also be allocated below 4GB from memory of type\r
+  // EfiACPIMemoryNVS.  The GDT must be filled in with the GDT contents that are\r
+  // used during an ACPI S3 resume.  This is typically the contents of the GDT\r
+  // used by the boot processor when the platform is booted.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  GdtrProfile;\r
+  //\r
+  // Physical address of structure of type IA32_DESCRIPTOR.  This structure must\r
+  // be allocated below 4GB from memory of type EfiACPIMemoryNVS.  The\r
+  // IA32_DESCRIPTOR structure provides the base address and length of an IDT.\r
+  // The buffer for IDT must also be allocated below 4GB from memory of type\r
+  // EfiACPIMemoryNVS.  The IDT must be filled in with the IDT contents that are\r
+  // used during an ACPI S3 resume.  This is typically the contents of the IDT\r
+  // used by the boot processor when the platform is booted.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  IdtrProfile;\r
+  //\r
+  // Physical address of a buffer that is used as stacks during ACPI S3 resume.\r
+  // The total size of this buffer, in bytes, is NumberOfCpus * StackSize.  This\r
+  // structure must be allocated below 4GB from memory of type EfiACPIMemoryNVS.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  StackAddress;\r
+  //\r
+  // The size, in bytes, of the stack provided to each CPU during ACPI S3 resume.\r
+  //\r
   UINT32                StackSize;\r
+  //\r
+  // The number of CPUs.  If a platform does not support hot plug CPUs, then\r
+  // this is the number of CPUs detected when the platform is booted, regardless\r
+  // of being enabled or disabled.  If a platform does support hot plug CPUs,\r
+  // then this is the maximum number of CPUs that the platform supports.\r
+  //\r
   UINT32                NumberOfCpus;\r
+  //\r
+  // Physical address of structure of type MTRR_SETTINGS that contains a copy\r
+  // of the MTRR settings that are compatible with the MTRR settings used by\r
+  // the boot processor when the platform was booted.  These MTRR settings are\r
+  // used during an ACPI S3 resume.  This structure must be allocated below 4GB\r
+  // from memory of type EfiACPIMemoryNVS.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  MtrrTable;\r
   //\r
-  // Physical address of a CPU_REGISTER_TABLE structure\r
+  // Physical address of an array of CPU_REGISTER_TABLE structures, with\r
+  // NumberOfCpus entries.  This array must be allocated below 4GB from memory\r
+  // of type EfiACPIMemoryNVS.  If a register table is not required, then the\r
+  // TableLength and AllocatedSize fields of CPU_REGISTER_TABLE are set to 0.\r
+  // If TableLength is > 0, then elements of RegisterTableEntry are used to\r
+  // initialize the CPU that matches InitialApicId, during an ACPI S3 resume,\r
+  // before SMBASE relocation is performed.\r
   //\r
   EFI_PHYSICAL_ADDRESS  PreSmmInitRegisterTable;\r
   //\r
-  // Physical address of a CPU_REGISTER_TABLE structure\r
+  // Physical address of an array of CPU_REGISTER_TABLE structures, with\r
+  // NumberOfCpus entries.  This array must be allocated below 4GB from memory\r
+  // of type EfiACPIMemoryNVS.  If a register table is not required, then the\r
+  // TableLength and AllocatedSize fields of CPU_REGISTER_TABLE are set to 0.\r
+  // If TableLength is > 0, then elements of RegisterTableEntry are used to\r
+  // initialize the CPU that matches InitialApicId, during an ACPI S3 resume,\r
+  // after SMBASE relocation is performed.\r
   //\r
   EFI_PHYSICAL_ADDRESS  RegisterTable;\r
+  //\r
+  // Physical address of a buffer that contains the machine check handler that\r
+  // is used during an ACPI S3 Resume.  This buffer must be allocated below 4GB\r
+  // from memory of type EfiACPIMemoryNVS.  In order for this machine check\r
+  // handler to be active on an AP during an ACPI S3 resume, the machine check\r
+  // vector in the IDT provided by IdtrProfile must be initialized to transfer\r
+  // control to this physical address.\r
+  //\r
   EFI_PHYSICAL_ADDRESS  ApMachineCheckHandlerBase;\r
+  //\r
+  // The size, in bytes, of the machine check handler that is used during an\r
+  // ACPI S3 Resume.  If this field is 0, then a machine check handler is not\r
+  // provided.\r
+  //\r
   UINT32                ApMachineCheckHandlerSize;\r
 } ACPI_CPU_DATA;\r
 \r