UefiCpuPkg/AcpiCpuData: update comments on register table fields

[mirror_edk2.git] / UefiCpuPkg / Include / AcpiCpuData.h

/** @file\r
Definitions for CPU S3 data.\r
\r
Copyright (c) 2013 - 2020, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _ACPI_CPU_DATA_H_\r
#define _ACPI_CPU_DATA_H_\r
\r
//\r
// Register types in register table\r
//\r
typedef enum {\r
  Msr,\r
  ControlRegister,\r
  MemoryMapped,\r
  CacheControl,\r
\r
  //\r
  // Semaphore type used to control the execute sequence of the Msr.\r
  // It will be insert between two Msr which has execute dependence.\r
  //\r
  Semaphore,\r
  InvalidReg\r
} REGISTER_TYPE;\r
\r
//\r
// Describe the dependency type for different features.\r
// The value set to CPU_REGISTER_TABLE_ENTRY.Value when the REGISTER_TYPE is Semaphore.\r
//\r
typedef enum {\r
  NoneDepType,\r
  ThreadDepType,\r
  CoreDepType,\r
  PackageDepType,\r
  InvalidDepType\r
} CPU_FEATURE_DEPENDENCE_TYPE;\r
\r
//\r
// CPU information.\r
//\r
typedef struct {\r
  //\r
  // Record the package count in this CPU.\r
  //\r
  UINT32                      PackageCount;\r
  //\r
  // Record the max core count in this CPU.\r
  // Different packages may have different core count, this value\r
  // save the max core count in all the packages.\r
  //\r
  UINT32                      MaxCoreCount;\r
  //\r
  // Record the max thread count in this CPU.\r
  // Different cores may have different thread count, this value\r
  // save the max thread count in all the cores.\r
  //\r
  UINT32                      MaxThreadCount;\r
  //\r
  // This field points to an array.\r
  // This array saves thread count (type UINT32) of each package.\r
  // The array has PackageCount elements.\r
  //\r
  // If the platform does not support MSR setting at S3 resume, and\r
  // therefore it doesn't need the dependency semaphores, it should set\r
  // this field to 0.\r
  //\r
  EFI_PHYSICAL_ADDRESS        ThreadCountPerPackage;\r
  //\r
  // This field points to an array.\r
  // This array saves thread count (type UINT8) of each core.\r
  // The array has PackageCount * MaxCoreCount elements.\r
  //\r
  // If the platform does not support MSR setting at S3 resume, and\r
  // therefore it doesn't need the dependency semaphores, it should set\r
  // this field to 0.\r
  //\r
  EFI_PHYSICAL_ADDRESS        ThreadCountPerCore;\r
} CPU_STATUS_INFORMATION;\r
\r
//\r
// Element of register table entry\r
//\r
typedef struct {\r
  REGISTER_TYPE  RegisterType;          // offset 0 - 3\r
  UINT32         Index;                 // offset 4 - 7\r
  UINT8          ValidBitStart;         // offset 8\r
  UINT8          ValidBitLength;        // offset 9\r
  BOOLEAN        TestThenWrite;         // offset 10\r
  UINT8          Reserved1;             // offset 11\r
  UINT32         HighIndex;             // offset 12-15, only valid for MemoryMapped\r
  UINT64         Value;                 // offset 16-23\r
} CPU_REGISTER_TABLE_ENTRY;\r
\r
//\r
// Register table definition, including current table length,\r
// allocated size of this table, and pointer to the list of table entries.\r
//\r
typedef struct {\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
  // Physical address of CPU_REGISTER_TABLE_ENTRY structures.\r
  //\r
  EFI_PHYSICAL_ADDRESS      RegisterTableEntry;\r
} CPU_REGISTER_TABLE;\r
\r
//\r
// Data structure that is required for ACPI S3 resume. 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. The\r
  // IA32_DESCRIPTOR structure provides the base address and length of a GDT\r
  // 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.  The\r
  // IA32_DESCRIPTOR structure provides the base address and length of an IDT.\r
  // 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 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.\r
  //\r
  EFI_PHYSICAL_ADDRESS  MtrrTable;\r
  //\r
  // Physical address of an array of CPU_REGISTER_TABLE structures, with\r
  // NumberOfCpus entries.  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
  // If a register table is not required for any one of the CPUs, then\r
  // PreSmmInitRegisterTable may be set to 0.\r
  //\r
  EFI_PHYSICAL_ADDRESS  PreSmmInitRegisterTable;\r
  //\r
  // Physical address of an array of CPU_REGISTER_TABLE structures, with\r
  // NumberOfCpus entries.  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
  // If a register table is not required for any one of the CPUs, then\r
  // RegisterTable may be set to 0.\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.  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
  //\r
  // CPU information which is required when set the register table.\r
  //\r
  CPU_STATUS_INFORMATION     CpuStatus;\r
  //\r
  // Location info for each AP.\r
  // It points to an array which saves all APs location info.\r
  // The array count is the AP count in this CPU.\r
  //\r
  // If the platform does not support MSR setting at S3 resume, and\r
  // therefore it doesn't need the dependency semaphores, it should set\r
  // this field to 0.\r
  //\r
  EFI_PHYSICAL_ADDRESS  ApLocation;\r
} ACPI_CPU_DATA;\r
\r
#endif\r