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
(cherry picked from commit af381fda9b63f548a1b9f71bac3d4721f1fd8db4)

1 files changed, 102 insertions, 13 deletions

diff --git a/UefiCpuPkg/Include/AcpiCpuData.h b/UefiCpuPkg/Include/AcpiCpuData.h
index a36725711c..12e9692c5c 100644
--- 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.
 //

 // Register types in register table

 //

-typedef enum _REGISTER_TYPE {

+typedef enum {

   Msr,

   ControlRegister,

   MemoryMapped,

@@ -29,11 +29,11 @@ typedef enum _REGISTER_TYPE {
 // Element of register table entry

 //

 typedef struct {

-  REGISTER_TYPE RegisterType;

-  UINT32        Index;

-  UINT8         ValidBitStart;

-  UINT8         ValidBitLength;

-  UINT64        Value;

+  REGISTER_TYPE  RegisterType;

+  UINT32         Index;

+  UINT8          ValidBitStart;

+  UINT8          ValidBitLength;

+  UINT64         Value;

 } CPU_REGISTER_TABLE_ENTRY;

 

 //

@@ -41,30 +41,119 @@ typedef struct {
 // allocated size of this table, and pointer to the list of table entries.

 //

 typedef struct {

-  UINT32                   TableLength;

-  UINT32                   NumberBeforeReset;

-  UINT32                   AllocatedSize;

-  UINT32                   InitialApicId;

-  CPU_REGISTER_TABLE_ENTRY *RegisterTableEntry;

+  //

+  // The number of valid entries in the RegisterTableEntry buffer

+  //

+  UINT32                    TableLength;

+  UINT32                    NumberBeforeReset;

+  //

+  // The size, in bytes, of the RegisterTableEntry buffer

+  //

+  UINT32                    AllocatedSize;

+  //

+  // The initial APIC ID of the CPU this register table applies to

+  //

+  UINT32                    InitialApicId;

+  //

+  // Buffer of CPU_REGISTER_TABLE_ENTRY structures.  This buffer must be

+  // allocated below 4GB from memory of type EfiACPIMemoryNVS.

+  //

+  CPU_REGISTER_TABLE_ENTRY  *RegisterTableEntry;

 } CPU_REGISTER_TABLE;

 

+//

+// Data structure that is required for ACPI S3 resume.  This structure must be

+// allocated below 4GB from memory of type EfiACPIMemoryNVS.  The PCD

+// PcdCpuS3DataAddress must be set to the physical address where this structure

+// is allocated

+//

 typedef struct {

+  //

+  // Physical address of 4KB buffer allocated below 1MB from memory of type

+  // EfiReservedMemoryType.  The buffer is not required to be initialized, but

+  // it is recommended that the buffer be zero-filled.  This buffer is used to

+  // wake APs during an ACPI S3 resume.

+  //

   EFI_PHYSICAL_ADDRESS  StartupVector;

+  //

+  // Physical address of structure of type IA32_DESCRIPTOR.  This structure must

+  // be allocated below 4GB from memory of type EfiACPIMemoryNVS.  The

+  // IA32_DESCRIPTOR structure provides the base address and length of a GDT

+  // The buffer for GDT must also be allocated below 4GB from memory of type

+  // EfiACPIMemoryNVS.  The GDT must be filled in with the GDT contents that are

+  // used during an ACPI S3 resume.  This is typically the contents of the GDT

+  // used by the boot processor when the platform is booted.

+  //

   EFI_PHYSICAL_ADDRESS  GdtrProfile;

+  //

+  // Physical address of structure of type IA32_DESCRIPTOR.  This structure must

+  // be allocated below 4GB from memory of type EfiACPIMemoryNVS.  The

+  // IA32_DESCRIPTOR structure provides the base address and length of an IDT.

+  // The buffer for IDT must also be allocated below 4GB from memory of type

+  // EfiACPIMemoryNVS.  The IDT must be filled in with the IDT contents that are

+  // used during an ACPI S3 resume.  This is typically the contents of the IDT

+  // used by the boot processor when the platform is booted.

+  //

   EFI_PHYSICAL_ADDRESS  IdtrProfile;

+  //

+  // Physical address of a buffer that is used as stacks during ACPI S3 resume.

+  // The total size of this buffer, in bytes, is NumberOfCpus * StackSize.  This

+  // structure must be allocated below 4GB from memory of type EfiACPIMemoryNVS.

+  //

   EFI_PHYSICAL_ADDRESS  StackAddress;

+  //

+  // The size, in bytes, of the stack provided to each CPU during ACPI S3 resume.

+  //

   UINT32                StackSize;

+  //

+  // The number of CPUs.  If a platform does not support hot plug CPUs, then

+  // this is the number of CPUs detected when the platform is booted, regardless

+  // of being enabled or disabled.  If a platform does support hot plug CPUs,

+  // then this is the maximum number of CPUs that the platform supports.

+  //

   UINT32                NumberOfCpus;

+  //

+  // Physical address of structure of type MTRR_SETTINGS that contains a copy

+  // of the MTRR settings that are compatible with the MTRR settings used by

+  // the boot processor when the platform was booted.  These MTRR settings are

+  // used during an ACPI S3 resume.  This structure must be allocated below 4GB

+  // from memory of type EfiACPIMemoryNVS.

+  //

   EFI_PHYSICAL_ADDRESS  MtrrTable;

   //

-  // Physical address of a CPU_REGISTER_TABLE structure

+  // Physical address of an array of CPU_REGISTER_TABLE structures, with

+  // NumberOfCpus entries.  This array must be allocated below 4GB from memory

+  // of type EfiACPIMemoryNVS.  If a register table is not required, then the

+  // TableLength and AllocatedSize fields of CPU_REGISTER_TABLE are set to 0.

+  // If TableLength is > 0, then elements of RegisterTableEntry are used to

+  // initialize the CPU that matches InitialApicId, during an ACPI S3 resume,

+  // before SMBASE relocation is performed.

   //

   EFI_PHYSICAL_ADDRESS  PreSmmInitRegisterTable;

   //

-  // Physical address of a CPU_REGISTER_TABLE structure

+  // Physical address of an array of CPU_REGISTER_TABLE structures, with

+  // NumberOfCpus entries.  This array must be allocated below 4GB from memory

+  // of type EfiACPIMemoryNVS.  If a register table is not required, then the

+  // TableLength and AllocatedSize fields of CPU_REGISTER_TABLE are set to 0.

+  // If TableLength is > 0, then elements of RegisterTableEntry are used to

+  // initialize the CPU that matches InitialApicId, during an ACPI S3 resume,

+  // after SMBASE relocation is performed.

   //

   EFI_PHYSICAL_ADDRESS  RegisterTable;

+  //

+  // Physical address of a buffer that contains the machine check handler that

+  // is used during an ACPI S3 Resume.  This buffer must be allocated below 4GB

+  // from memory of type EfiACPIMemoryNVS.  In order for this machine check

+  // handler to be active on an AP during an ACPI S3 resume, the machine check

+  // vector in the IDT provided by IdtrProfile must be initialized to transfer

+  // control to this physical address.

+  //

   EFI_PHYSICAL_ADDRESS  ApMachineCheckHandlerBase;

+  //

+  // The size, in bytes, of the machine check handler that is used during an

+  // ACPI S3 Resume.  If this field is 0, then a machine check handler is not

+  // provided.

+  //

   UINT32                ApMachineCheckHandlerSize;

 } ACPI_CPU_DATA;