DynamicTablesPkg/Library/Acpi/Arm/AcpiPpttLibArm/PpttGenerator.h

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