Documentation/devicetree/bindings/scheduler/sched-energy-costs.txt

   1 ===========================================================
   2 Energy cost bindings for Energy Aware Scheduling
   3 ===========================================================
   4
   5 ===========================================================
   6 1 - Introduction
   7 ===========================================================
   8
   9 This note specifies bindings required for energy-aware scheduling
  10 (EAS)[1]. Historically, the scheduler's primary objective has been
  11 performance.  EAS aims to provide an alternative objective - energy
  12 efficiency. EAS relies on a simple platform energy cost model to
  13 guide scheduling decisions.  The model only considers the CPU
  14 subsystem.
  15
  16 This note is aligned with the definition of the layout of physical
  17 CPUs in the system as described in the ARM topology binding
  18 description [2]. The concept is applicable to any system so long as
  19 the cost model data is provided for those processing elements in
  20 that system's topology that EAS is required to service.
  21
  22 Processing elements refer to hardware threads, CPUs and clusters of
  23 related CPUs in increasing order of hierarchy.
  24
  25 EAS requires two key cost metrics - busy costs and idle costs. Busy
  26 costs comprise of a list of compute capacities for the processing
  27 element in question and the corresponding power consumption at that
  28 capacity.  Idle costs comprise of a list of power consumption values
  29 for each idle state [C-state] that the processing element supports.
  30 For a detailed description of these metrics, their derivation and
  31 their use see [3].
  32
  33 These cost metrics are required for processing elements in all
  34 scheduling domain levels that EAS is required to service.
  35
  36 ===========================================================
  37 2 - energy-costs node
  38 ===========================================================
  39
  40 Energy costs for the processing elements in scheduling domains that
  41 EAS is required to service are defined in the energy-costs node
  42 which acts as a container for the actual per processing element cost
  43 nodes. A single energy-costs node is required for a given system.
  44
  45 - energy-costs node
  46
  47         Usage: Required
  48
  49         Description: The energy-costs node is a container node and
  50         it's sub-nodes describe costs for each processing element at
  51         all scheduling domain levels that EAS is required to
  52         service.
  53
  54         Node name must be "energy-costs".
  55
  56         The energy-costs node's parent node must be the cpus node.
  57
  58         The energy-costs node's child nodes can be:
  59
  60         - one or more cost nodes.
  61
  62         Any other configuration is considered invalid.
  63
  64 The energy-costs node can only contain a single type of child node
  65 whose bindings are described in paragraph 4.
  66
  67 ===========================================================
  68 3 - energy-costs node child nodes naming convention
  69 ===========================================================
  70
  71 energy-costs child nodes must follow a naming convention where the
  72 node name must be "thread-costN", "core-costN", "cluster-costN"
  73 depending on whether the costs in the node are for a thread, core or
  74 cluster.  N (where N = {0, 1, ...}) is the node number and has no
  75 bearing to the OS' logical thread, core or cluster index.
  76
  77 ===========================================================
  78 4 - cost node bindings
  79 ===========================================================
  80
  81 Bindings for cost nodes are defined as follows:
  82
  83 - cluster-cost node
  84
  85         Description: must be declared within an energy-costs node. A
  86         system can contain multiple clusters and each cluster
  87         serviced by EAS must have a corresponding cluster-costs
  88         node.
  89
  90         The cluster-cost node name must be "cluster-costN" as
  91         described in 3 above.
  92
  93         A cluster-cost node must be a leaf node with no children.
  94
  95         Properties for cluster-cost nodes are described in paragraph
  96         5 below.
  97
  98         Any other configuration is considered invalid.
  99
 100 - core-cost node
 101
 102         Description: must be declared within an energy-costs node. A
 103         system can contain multiple cores and each core serviced by
 104         EAS must have a corresponding core-cost node.
 105
 106         The core-cost node name must be "core-costN" as described in
 107         3 above.
 108
 109         A core-cost node must be a leaf node with no children.
 110
 111         Properties for core-cost nodes are described in paragraph
 112         5 below.
 113
 114         Any other configuration is considered invalid.
 115
 116 - thread-cost node
 117
 118         Description: must be declared within an energy-costs node. A
 119         system can contain cores with multiple hardware threads and
 120         each thread serviced by EAS must have a corresponding
 121         thread-cost node.
 122
 123         The core-cost node name must be "core-costN" as described in
 124         3 above.
 125
 126         A core-cost node must be a leaf node with no children.
 127
 128         Properties for thread-cost nodes are described in paragraph
 129         5 below.
 130
 131         Any other configuration is considered invalid.
 132
 133 ===========================================================
 134 5 - Cost node properties
 135 ==========================================================
 136
 137 All cost node types must have only the following properties:
 138
 139 - busy-cost-data
 140
 141         Usage: required
 142         Value type: An array of 2-item tuples. Each item is of type
 143         u32.
 144         Definition: The first item in the tuple is the capacity
 145         value as described in [3]. The second item in the tuple is
 146         the energy cost value as described in [3].
 147
 148 - idle-cost-data
 149
 150         Usage: required
 151         Value type: An array of 1-item tuples. The item is of type
 152         u32.
 153         Definition: The item in the tuple is the energy cost value
 154         as described in [3].
 155
 156 ===========================================================
 157 4 - Extensions to the cpu node
 158 ===========================================================
 159
 160 The cpu node is extended with a property that establishes the
 161 connection between the processing element represented by the cpu
 162 node and the cost-nodes associated with this processing element.
 163
 164 The connection is expressed in line with the topological hierarchy
 165 that this processing element belongs to starting with the level in
 166 the hierarchy that this processing element itself belongs to through
 167 to the highest level that EAS is required to service.  The
 168 connection cannot be sparse and must be contiguous from the
 169 processing element's level through to the highest desired level. The
 170 highest desired level must be the same for all processing elements.
 171
 172 Example: Given that a cpu node may represent a thread that is a part
 173 of a core, this property may contain multiple elements which
 174 associate the thread with cost nodes describing the costs for the
 175 thread itself, the core the thread belongs to, the cluster the core
 176 belongs to and so on. The elements must be ordered from the lowest
 177 level nodes to the highest desired level that EAS must service. The
 178 highest desired level must be the same for all cpu nodes. The
 179 elements must not be sparse: there must be elements for the current
 180 thread, the next level of hierarchy (core) and so on without any
 181 'holes'.
 182
 183 Example: Given that a cpu node may represent a core that is a part
 184 of a cluster of related cpus this property may contain multiple
 185 elements which associate the core with cost nodes describing the
 186 costs for the core itself, the cluster the core belongs to and so
 187 on. The elements must be ordered from the lowest level nodes to the
 188 highest desired level that EAS must service. The highest desired
 189 level must be the same for all cpu nodes. The elements must not be
 190 sparse: there must be elements for the current thread, the next
 191 level of hierarchy (core) and so on without any 'holes'.
 192
 193 If the system comprises of hierarchical clusters of clusters, this
 194 property will contain multiple associations with the relevant number
 195 of cluster elements in hierarchical order.
 196
 197 Property added to the cpu node:
 198
 199 - sched-energy-costs
 200
 201         Usage: required
 202         Value type: List of phandles
 203         Definition: a list of phandles to specific cost nodes in the
 204         energy-costs parent node that correspond to the processing
 205         element represented by this cpu node in hierarchical order
 206         of topology.
 207
 208         The order of phandles in the list is significant. The first
 209         phandle is to the current processing element's own cost
 210         node.  Subsequent phandles are to higher hierarchical level
 211         cost nodes up until the maximum level that EAS is to
 212         service.
 213
 214         All cpu nodes must have the same highest level cost node.
 215
 216         The phandle list must not be sparsely populated with handles
 217         to non-contiguous hierarchical levels. See commentary above
 218         for clarity.
 219
 220         Any other configuration is invalid.
 221
 222 ===========================================================
 223 5 - Example dts
 224 ===========================================================
 225
 226 Example 1 (ARM 64-bit, 6-cpu system, two clusters of cpus, one
 227 cluster of 2 Cortex-A57 cpus, one cluster of 4 Cortex-A53 cpus):
 228
 229 cpus {
 230         #address-cells = <2>;
 231         #size-cells = <0>;
 232         .
 233         .
 234         .
 235         A57_0: cpu@0 {
 236                 compatible = "arm,cortex-a57","arm,armv8";
 237                 reg = <0x0 0x0>;
 238                 device_type = "cpu";
 239                 enable-method = "psci";
 240                 next-level-cache = <&A57_L2>;
 241                 clocks = <&scpi_dvfs 0>;
 242                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 243                 sched-energy-costs = <&CPU_COST_0 &CLUSTER_COST_0>;
 244         };
 245
 246         A57_1: cpu@1 {
 247                 compatible = "arm,cortex-a57","arm,armv8";
 248                 reg = <0x0 0x1>;
 249                 device_type = "cpu";
 250                 enable-method = "psci";
 251                 next-level-cache = <&A57_L2>;
 252                 clocks = <&scpi_dvfs 0>;
 253                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 254                 sched-energy-costs = <&CPU_COST_0 &CLUSTER_COST_0>;
 255         };
 256
 257         A53_0: cpu@100 {
 258                 compatible = "arm,cortex-a53","arm,armv8";
 259                 reg = <0x0 0x100>;
 260                 device_type = "cpu";
 261                 enable-method = "psci";
 262                 next-level-cache = <&A53_L2>;
 263                 clocks = <&scpi_dvfs 1>;
 264                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 265                 sched-energy-costs = <&CPU_COST_1 &CLUSTER_COST_1>;
 266         };
 267
 268         A53_1: cpu@101 {
 269                 compatible = "arm,cortex-a53","arm,armv8";
 270                 reg = <0x0 0x101>;
 271                 device_type = "cpu";
 272                 enable-method = "psci";
 273                 next-level-cache = <&A53_L2>;
 274                 clocks = <&scpi_dvfs 1>;
 275                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 276                 sched-energy-costs = <&CPU_COST_1 &CLUSTER_COST_1>;
 277         };
 278
 279         A53_2: cpu@102 {
 280                 compatible = "arm,cortex-a53","arm,armv8";
 281                 reg = <0x0 0x102>;
 282                 device_type = "cpu";
 283                 enable-method = "psci";
 284                 next-level-cache = <&A53_L2>;
 285                 clocks = <&scpi_dvfs 1>;
 286                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 287                 sched-energy-costs = <&CPU_COST_1 &CLUSTER_COST_1>;
 288         };
 289
 290         A53_3: cpu@103 {
 291                 compatible = "arm,cortex-a53","arm,armv8";
 292                 reg = <0x0 0x103>;
 293                 device_type = "cpu";
 294                 enable-method = "psci";
 295                 next-level-cache = <&A53_L2>;
 296                 clocks = <&scpi_dvfs 1>;
 297                 cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
 298                 sched-energy-costs = <&CPU_COST_1 &CLUSTER_COST_1>;
 299         };
 300
 301         energy-costs {
 302                 CPU_COST_0: core-cost0 {
 303                         busy-cost-data = <
 304                                 417   168
 305                                 579   251
 306                                 744   359
 307                                 883   479
 308                                 1024  616
 309                         >;
 310                         idle-cost-data = <
 311                                 15
 312                                 0
 313                         >;
 314                 };
 315                 CPU_COST_1: core-cost1 {
 316                         busy-cost-data = <
 317                                 235 33
 318                                 302 46
 319                                 368 61
 320                                 406 76
 321                                 447 93
 322                         >;
 323                         idle-cost-data = <
 324                                 6
 325                                 0
 326                         >;
 327                 };
 328                 CLUSTER_COST_0: cluster-cost0 {
 329                         busy-cost-data = <
 330                                 417   24
 331                                 579   32
 332                                 744   43
 333                                 883   49
 334                                 1024  64
 335                         >;
 336                         idle-cost-data = <
 337                                 65
 338                                 24
 339                         >;
 340                 };
 341                 CLUSTER_COST_1: cluster-cost1 {
 342                         busy-cost-data = <
 343                                 235 26
 344                                 303 30
 345                                 368 39
 346                                 406 47
 347                                 447 57
 348                         >;
 349                         idle-cost-data = <
 350                                 56
 351                                 17
 352                         >;
 353                 };
 354         };
 355 };
 356
 357 ===============================================================================
 358 [1] https://lkml.org/lkml/2015/5/12/728
 359 [2] Documentation/devicetree/bindings/topology.txt
 360 [3] Documentation/scheduler/sched-energy.txt