[mirror_edk2.git] / DynamicTablesPkg / Library / Acpi / Arm / AcpiPpttLibArm / PpttGenerator.h

/** @file\r
  Header file for the dynamic PPTT generator\r
\r
  Copyright (c) 2019, ARM Limited. All rights reserved.\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Reference(s):\r
  - ACPI 6.3 Specification, January 2019\r
  - ARM Architecture Reference Manual ARMv8 (D.a)\r
\r
  @par Glossary:\r
    - Cm or CM   - Configuration Manager\r
    - Obj or OBJ - Object\r
**/\r
\r
#ifndef PPTT_GENERATOR_H_\r
#define PPTT_GENERATOR_H_\r
\r
#pragma pack(1)\r
\r
/// Cache parameters allowed by the architecture with\r
/// ARMv8.3-CCIDX (Cache extended number of sets)\r
/// Derived from CCSIDR_EL1 when ID_AA64MMFR2_EL1.CCIDX==0001\r
#define PPTT_ARM_CCIDX_CACHE_NUMBER_OF_SETS_MAX  (1 << 24)\r
#define PPTT_ARM_CCIDX_CACHE_ASSOCIATIVITY_MAX   (1 << 21)\r
\r
/// Cache parameters allowed by the architecture without\r
/// ARMv8.3-CCIDX (Cache extended number of sets)\r
/// Derived from CCSIDR_EL1 when ID_AA64MMFR2_EL1.CCIDX==0000\r
#define PPTT_ARM_CACHE_NUMBER_OF_SETS_MAX  (1 << 15)\r
#define PPTT_ARM_CACHE_ASSOCIATIVITY_MAX   (1 << 10)\r
\r
/// Common cache parameters\r
/// Derived from CCSIDR_EL1\r
/// The LineSize is represented by bits 2:0\r
/// (Log2(Number of bytes in cache line)) - 4 is used to represent\r
/// the LineSize bits.\r
#define PPTT_ARM_CACHE_LINE_SIZE_MAX  (1 << 11)\r
#define PPTT_ARM_CACHE_LINE_SIZE_MIN  (1 << 4)\r
\r
/// Test if the given Processor Hierarchy Info object has the 'Node is a Leaf'\r
/// flag set\r
#define IS_PROC_NODE_LEAF(Node)  ((Node->Flags & BIT3) != 0)\r
\r
/// Test if the given Processor Hierarchy Info object has the 'ACPI Processor\r
/// ID valid' flag set\r
#define IS_ACPI_PROC_ID_VALID(Node)  ((Node->Flags & BIT1) != 0)\r
\r
/**\r
  The GET_SIZE_OF_PPTT_STRUCTS macro expands to a function that is used to\r
  calculate the total memory requirement for the PPTT structures represented\r
  by the given list of Configuration Manager Objects of the same type. This\r
  function also indexes the input CM objects so that various other CM objects\r
  (possibly of different type) can reference them.\r
\r
  The size of memory needed for the specified type of PPTT structures is based\r
  on the number and type of CM objects provided. The macro assumes that the\r
  ACPI object PpttObjName has fixed size.\r
\r
  The macro expands to a function which has the following prototype:\r
\r
  STATIC\r
  UINT32\r
  EFIAPI\r
  GetSizeof<PpttObjName> (\r
    IN      CONST UINT32                      StartOffset,\r
    IN      CONST CmObjectType       *        Nodes,\r
    IN            UINT32                      NodeCount,\r
    IN OUT        PPTT_NODE_INDEXER ** CONST  NodeIndexer\r
  )\r
\r
  Generated function parameters:\r
  @param [in]       StartOffset     Offset from the start of PPTT to where\r
                                    the PPTT structures will be placed.\r
  @param [in]       NodesToIndex    Pointer to the list of CM objects to be\r
                                    indexed and size-estimated.\r
  @param [out]      NodeCount       Number of CM objects in NodesToIndex.\r
  @param [in, out]  NodeIndexer     Pointer to the list of Node Indexer\r
                                    elements to populate.\r
  @retval           Size            Total memory requirement for the PPTT\r
                                    structures described in NodesToIndex.\r
\r
  Macro Parameters:\r
  @param [in]       PpttObjName     Name for the type of PPTT structures which\r
                                    size is estimated.\r
  @param [in]       PpttObjSize     Expression to use to calculate the size of\r
                                    of a single instance of the PPTT structure\r
                                    which corresponds to the CM object being\r
                                    indexed.\r
  @param [in]       CmObjectType    Data type of the CM nodes in NodesToIndex.\r
**/\r
#define GET_SIZE_OF_PPTT_STRUCTS(                                             \\r
                                                                              PpttObjName,                                                                \\r
                                                                              PpttObjSize,                                                                \\r
                                                                              CmObjectType                                                                \\r
                                                                              )                                                                             \\r
STATIC                                                                        \\r
UINT32                                                                        \\r
GetSizeof##PpttObjName (                                                      \\r
  IN      CONST UINT32                      StartOffset,                      \\r
  IN      CONST CmObjectType      *         NodesToIndex,                     \\r
  IN            UINT32                      NodeCount,                        \\r
  IN OUT        PPTT_NODE_INDEXER ** CONST  NodeIndexer                       \\r
  )                                                                           \\r
{                                                                             \\r
  UINT32  Size;                                                               \\r
                                                                              \\r
  ASSERT (                                                                    \\r
    (NodesToIndex != NULL) &&                                                 \\r
    (NodeIndexer != NULL)                                                     \\r
    );                                                                        \\r
                                                                              \\r
  Size = 0;                                                                   \\r
  while (NodeCount-- != 0) {                                                  \\r
    (*NodeIndexer)->Token = NodesToIndex->Token;                              \\r
    (*NodeIndexer)->Object = (VOID*)NodesToIndex;                             \\r
    (*NodeIndexer)->Offset = Size + StartOffset;                              \\r
    (*NodeIndexer)->CycleDetectionStamp = 0;                                  \\r
    (*NodeIndexer)->TopologyParent = NULL;                                    \\r
    DEBUG ((                                                                  \\r
      DEBUG_INFO,                                                             \\r
      "PPTT: Node Indexer = %p, Token = %p, Object = %p, Offset = 0x%x\n",    \\r
      *NodeIndexer,                                                           \\r
      (*NodeIndexer)->Token,                                                  \\r
      (*NodeIndexer)->Object,                                                 \\r
      (*NodeIndexer)->Offset                                                  \\r
      ));                                                                     \\r
                                                                              \\r
    Size += PpttObjSize;                                                      \\r
    (*NodeIndexer)++;                                                         \\r
    NodesToIndex++;                                                           \\r
  }                                                                           \\r
  return Size;                                                                \\r
}\r
\r
/**\r
  A structure for indexing CM objects (nodes) used in PPTT generation.\r
\r
  PPTT_NODE_INDEXER is a wrapper around CM objects which augments these objects\r
  with additional information that enables generating PPTT structures with\r
  correct cross-references.\r
\r
  PPTT_NODE_INDEXER keeps track of each structure's offset from the base\r
  address of the generated table. It also caches certain information and makes\r
  PPTT cyclic reference detection possible.\r
*/\r
typedef struct PpttNodeIndexer {\r
  /// Unique identifier for the node\r
  CM_OBJECT_TOKEN           Token;\r
  /// Pointer to the CM object being indexed\r
  VOID                      *Object;\r
  /// Offset from the start of the PPTT table to the PPTT structure which is\r
  /// represented by Object\r
  UINT32                    Offset;\r
  /// Field used to mark nodes as 'visited' when detecting cycles in processor\r
  /// and cache topology\r
  UINT32                    CycleDetectionStamp;\r
  /// Reference to a Node Indexer element which is the parent of this Node\r
  /// Indexer element in the processor and cache topology\r
  /// e.g For a hardware thread the TopologyParent would point to a CPU node\r
  ///     For a L1 cache the TopologyParent would point to a L2 cache\r
  struct PpttNodeIndexer    *TopologyParent;\r
} PPTT_NODE_INDEXER;\r
\r
typedef struct AcpiPpttGenerator {\r
  /// ACPI Table generator header\r
  ACPI_TABLE_GENERATOR    Header;\r
  /// PPTT structure count\r
  UINT32                  ProcTopologyStructCount;\r
  /// Count of Processor Hierarchy Nodes\r
  UINT32                  ProcHierarchyNodeCount;\r
  /// Count of Cache Structures\r
  UINT32                  CacheStructCount;\r
  /// List of indexed CM objects for PPTT generation\r
  PPTT_NODE_INDEXER       *NodeIndexer;\r
  /// Pointer to the start of Processor Hierarchy nodes in\r
  /// the Node Indexer array\r
  PPTT_NODE_INDEXER       *ProcHierarchyNodeIndexedList;\r
  /// Pointer to the start of Cache Structures in the Node Indexer array\r
  PPTT_NODE_INDEXER       *CacheStructIndexedList;\r
} ACPI_PPTT_GENERATOR;\r
\r
#pragma pack()\r
\r
#endif // PPTT_GENERATOR_H_\r
Commit	Line	Data
77db1156 KK	1	/** @file\r
	2	Header file for the dynamic PPTT generator\r
	3	\r
	4	Copyright (c) 2019, ARM Limited. All rights reserved.\r
	5	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	6	\r
	7	@par Reference(s):\r
	8	- ACPI 6.3 Specification, January 2019\r
	9	- ARM Architecture Reference Manual ARMv8 (D.a)\r
	10	\r
	11	@par Glossary:\r
	12	- Cm or CM - Configuration Manager\r
	13	- Obj or OBJ - Object\r
	14	**/\r
	15	\r
	16	#ifndef PPTT_GENERATOR_H_\r
	17	#define PPTT_GENERATOR_H_\r
	18	\r
	19	#pragma pack(1)\r
	20	\r
	21	/// Cache parameters allowed by the architecture with\r
	22	/// ARMv8.3-CCIDX (Cache extended number of sets)\r
	23	/// Derived from CCSIDR_EL1 when ID_AA64MMFR2_EL1.CCIDX==0001\r
731c67e1 MK	24	#define PPTT_ARM_CCIDX_CACHE_NUMBER_OF_SETS_MAX (1 << 24)\r
731c67e1 MK	25	#define PPTT_ARM_CCIDX_CACHE_ASSOCIATIVITY_MAX (1 << 21)\r
77db1156 KK	26	\r
	27	/// Cache parameters allowed by the architecture without\r
	28	/// ARMv8.3-CCIDX (Cache extended number of sets)\r
	29	/// Derived from CCSIDR_EL1 when ID_AA64MMFR2_EL1.CCIDX==0000\r
731c67e1 MK	30	#define PPTT_ARM_CACHE_NUMBER_OF_SETS_MAX (1 << 15)\r
731c67e1 MK	31	#define PPTT_ARM_CACHE_ASSOCIATIVITY_MAX (1 << 10)\r
77db1156 KK	32	\r
	33	/// Common cache parameters\r
	34	/// Derived from CCSIDR_EL1\r
	35	/// The LineSize is represented by bits 2:0\r
	36	/// (Log2(Number of bytes in cache line)) - 4 is used to represent\r
	37	/// the LineSize bits.\r
731c67e1 MK	38	#define PPTT_ARM_CACHE_LINE_SIZE_MAX (1 << 11)\r
731c67e1 MK	39	#define PPTT_ARM_CACHE_LINE_SIZE_MIN (1 << 4)\r
77db1156 KK	40	\r
	41	/// Test if the given Processor Hierarchy Info object has the 'Node is a Leaf'\r
	42	/// flag set\r
731c67e1	43	#define IS_PROC_NODE_LEAF(Node) ((Node->Flags & BIT3) != 0)\r
77db1156 KK	44	\r
	45	/// Test if the given Processor Hierarchy Info object has the 'ACPI Processor\r
	46	/// ID valid' flag set\r
731c67e1	47	#define IS_ACPI_PROC_ID_VALID(Node) ((Node->Flags & BIT1) != 0)\r
77db1156 KK	48	\r
	49	/**\r
	50	The GET_SIZE_OF_PPTT_STRUCTS macro expands to a function that is used to\r
	51	calculate the total memory requirement for the PPTT structures represented\r
	52	by the given list of Configuration Manager Objects of the same type. This\r
	53	function also indexes the input CM objects so that various other CM objects\r
	54	(possibly of different type) can reference them.\r
	55	\r
	56	The size of memory needed for the specified type of PPTT structures is based\r
	57	on the number and type of CM objects provided. The macro assumes that the\r
	58	ACPI object PpttObjName has fixed size.\r
	59	\r
	60	The macro expands to a function which has the following prototype:\r
	61	\r
	62	STATIC\r
	63	UINT32\r
	64	EFIAPI\r
	65	GetSizeof<PpttObjName> (\r
	66	IN CONST UINT32 StartOffset,\r
	67	IN CONST CmObjectType * Nodes,\r
	68	IN UINT32 NodeCount,\r
	69	IN OUT PPTT_NODE_INDEXER ** CONST NodeIndexer\r
	70	)\r
	71	\r
	72	Generated function parameters:\r
	73	@param [in] StartOffset Offset from the start of PPTT to where\r
	74	the PPTT structures will be placed.\r
	75	@param [in] NodesToIndex Pointer to the list of CM objects to be\r
	76	indexed and size-estimated.\r
	77	@param [out] NodeCount Number of CM objects in NodesToIndex.\r
	78	@param [in, out] NodeIndexer Pointer to the list of Node Indexer\r
	79	elements to populate.\r
	80	@retval Size Total memory requirement for the PPTT\r
	81	structures described in NodesToIndex.\r
	82	\r
	83	Macro Parameters:\r
	84	@param [in] PpttObjName Name for the type of PPTT structures which\r
	85	size is estimated.\r
	86	@param [in] PpttObjSize Expression to use to calculate the size of\r
	87	of a single instance of the PPTT structure\r
	88	which corresponds to the CM object being\r
	89	indexed.\r
	90	@param [in] CmObjectType Data type of the CM nodes in NodesToIndex.\r
	91	**/\r
	92	#define GET_SIZE_OF_PPTT_STRUCTS( \\r
731c67e1 MK	93	PpttObjName, \\r
	94	PpttObjSize, \\r
	95	CmObjectType \\r
	96	) \\r
77db1156 KK	97	STATIC \\r
	98	UINT32 \\r
	99	GetSizeof##PpttObjName ( \\r
	100	IN CONST UINT32 StartOffset, \\r
	101	IN CONST CmObjectType * NodesToIndex, \\r
	102	IN UINT32 NodeCount, \\r
	103	IN OUT PPTT_NODE_INDEXER ** CONST NodeIndexer \\r
	104	) \\r
	105	{ \\r
	106	UINT32 Size; \\r
	107	\\r
	108	ASSERT ( \\r
	109	(NodesToIndex != NULL) && \\r
	110	(NodeIndexer != NULL) \\r
	111	); \\r
	112	\\r
	113	Size = 0; \\r
	114	while (NodeCount-- != 0) { \\r
	115	(*NodeIndexer)->Token = NodesToIndex->Token; \\r
	116	(NodeIndexer)->Object = (VOID)NodesToIndex; \\r
	117	(*NodeIndexer)->Offset = Size + StartOffset; \\r
	118	(*NodeIndexer)->CycleDetectionStamp = 0; \\r
	119	(*NodeIndexer)->TopologyParent = NULL; \\r
	120	DEBUG (( \\r
	121	DEBUG_INFO, \\r
	122	"PPTT: Node Indexer = %p, Token = %p, Object = %p, Offset = 0x%x\n", \\r
	123	*NodeIndexer, \\r
	124	(*NodeIndexer)->Token, \\r
	125	(*NodeIndexer)->Object, \\r
	126	(*NodeIndexer)->Offset \\r
	127	)); \\r
	128	\\r
	129	Size += PpttObjSize; \\r
	130	(*NodeIndexer)++; \\r
	131	NodesToIndex++; \\r
	132	} \\r
	133	return Size; \\r
	134	}\r
	135	\r
	136	/**\r
	137	A structure for indexing CM objects (nodes) used in PPTT generation.\r
	138	\r
	139	PPTT_NODE_INDEXER is a wrapper around CM objects which augments these objects\r
	140	with additional information that enables generating PPTT structures with\r
	141	correct cross-references.\r
	142	\r
	143	PPTT_NODE_INDEXER keeps track of each structure's offset from the base\r
	144	address of the generated table. It also caches certain information and makes\r
	145	PPTT cyclic reference detection possible.\r
	146	*/\r
	147	typedef struct PpttNodeIndexer {\r
	148	/// Unique identifier for the node\r
	149	CM_OBJECT_TOKEN Token;\r
	150	/// Pointer to the CM object being indexed\r
731c67e1	151	VOID *Object;\r
77db1156 KK	152	/// Offset from the start of the PPTT table to the PPTT structure which is\r
	153	/// represented by Object\r
	154	UINT32 Offset;\r
	155	/// Field used to mark nodes as 'visited' when detecting cycles in processor\r
	156	/// and cache topology\r
	157	UINT32 CycleDetectionStamp;\r
	158	/// Reference to a Node Indexer element which is the parent of this Node\r
	159	/// Indexer element in the processor and cache topology\r
	160	/// e.g For a hardware thread the TopologyParent would point to a CPU node\r
	161	/// For a L1 cache the TopologyParent would point to a L2 cache\r
731c67e1	162	struct PpttNodeIndexer *TopologyParent;\r
77db1156 KK	163	} PPTT_NODE_INDEXER;\r
	164	\r
	165	typedef struct AcpiPpttGenerator {\r
	166	/// ACPI Table generator header\r
731c67e1	167	ACPI_TABLE_GENERATOR Header;\r
77db1156	168	/// PPTT structure count\r
731c67e1	169	UINT32 ProcTopologyStructCount;\r
d39271f1	170	/// Count of Processor Hierarchy Nodes\r
731c67e1	171	UINT32 ProcHierarchyNodeCount;\r
d39271f1	172	/// Count of Cache Structures\r
731c67e1	173	UINT32 CacheStructCount;\r
77db1156	174	/// List of indexed CM objects for PPTT generation\r
731c67e1	175	PPTT_NODE_INDEXER *NodeIndexer;\r
77db1156 KK	176	/// Pointer to the start of Processor Hierarchy nodes in\r
77db1156 KK	177	/// the Node Indexer array\r
731c67e1	178	PPTT_NODE_INDEXER *ProcHierarchyNodeIndexedList;\r
77db1156	179	/// Pointer to the start of Cache Structures in the Node Indexer array\r
731c67e1	180	PPTT_NODE_INDEXER *CacheStructIndexedList;\r
77db1156 KK	181	} ACPI_PPTT_GENERATOR;\r
	182	\r
	183	#pragma pack()\r
	184	\r
	185	#endif // PPTT_GENERATOR_H_\r