Documentation/power/powercap/dtpm.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==========================================
   4 Dynamic Thermal Power Management framework
   5 ==========================================
   6
   7 On the embedded world, the complexity of the SoC leads to an
   8 increasing number of hotspots which need to be monitored and mitigated
   9 as a whole in order to prevent the temperature to go above the
  10 normative and legally stated 'skin temperature'.
  11
  12 Another aspect is to sustain the performance for a given power budget,
  13 for example virtual reality where the user can feel dizziness if the
  14 performance is capped while a big CPU is processing something else. Or
  15 reduce the battery charging because the dissipated power is too high
  16 compared with the power consumed by other devices.
  17
  18 The user space is the most adequate place to dynamically act on the
  19 different devices by limiting their power given an application
  20 profile: it has the knowledge of the platform.
  21
  22 The Dynamic Thermal Power Management (DTPM) is a technique acting on
  23 the device power by limiting and/or balancing a power budget among
  24 different devices.
  25
  26 The DTPM framework provides an unified interface to act on the
  27 device power.
  28
  29 Overview
  30 ========
  31
  32 The DTPM framework relies on the powercap framework to create the
  33 powercap entries in the sysfs directory and implement the backend
  34 driver to do the connection with the power manageable device.
  35
  36 The DTPM is a tree representation describing the power constraints
  37 shared between devices, not their physical positions.
  38
  39 The nodes of the tree are a virtual description aggregating the power
  40 characteristics of the children nodes and their power limitations.
  41
  42 The leaves of the tree are the real power manageable devices.
  43
  44 For instance::
  45
  46   SoC
  47    |
  48    `-- pkg
  49         |
  50         |-- pd0 (cpu0-3)
  51         |
  52         `-- pd1 (cpu4-5)
  53
  54 The pkg power will be the sum of pd0 and pd1 power numbers::
  55
  56   SoC (400mW - 3100mW)
  57    |
  58    `-- pkg (400mW - 3100mW)
  59         |
  60         |-- pd0 (100mW - 700mW)
  61         |
  62         `-- pd1 (300mW - 2400mW)
  63
  64 When the nodes are inserted in the tree, their power characteristics are propagated to the parents::
  65
  66   SoC (600mW - 5900mW)
  67    |
  68    |-- pkg (400mW - 3100mW)
  69    |    |
  70    |    |-- pd0 (100mW - 700mW)
  71    |    |
  72    |    `-- pd1 (300mW - 2400mW)
  73    |
  74    `-- pd2 (200mW - 2800mW)
  75
  76 Each node have a weight on a 2^10 basis reflecting the percentage of power consumption along the siblings::
  77
  78   SoC (w=1024)
  79    |
  80    |-- pkg (w=538)
  81    |    |
  82    |    |-- pd0 (w=231)
  83    |    |
  84    |    `-- pd1 (w=794)
  85    |
  86    `-- pd2 (w=486)
  87
  88    Note the sum of weights at the same level are equal to 1024.
  89
  90 When a power limitation is applied to a node, then it is distributed along the children given their weights. For example, if we set a power limitation of 3200mW at the 'SoC' root node, the resulting tree will be::
  91
  92   SoC (w=1024) <--- power_limit = 3200mW
  93    |
  94    |-- pkg (w=538) --> power_limit = 1681mW
  95    |    |
  96    |    |-- pd0 (w=231) --> power_limit = 378mW
  97    |    |
  98    |    `-- pd1 (w=794) --> power_limit = 1303mW
  99    |
 100    `-- pd2 (w=486) --> power_limit = 1519mW
 101
 102
 103 Flat description
 104 ----------------
 105
 106 A root node is created and it is the parent of all the nodes. This
 107 description is the simplest one and it is supposed to give to user
 108 space a flat representation of all the devices supporting the power
 109 limitation without any power limitation distribution.
 110
 111 Hierarchical description
 112 ------------------------
 113
 114 The different devices supporting the power limitation are represented
 115 hierarchically. There is one root node, all intermediate nodes are
 116 grouping the child nodes which can be intermediate nodes also or real
 117 devices.
 118
 119 The intermediate nodes aggregate the power information and allows to
 120 set the power limit given the weight of the nodes.
 121
 122 User space API
 123 ==============
 124
 125 As stated in the overview, the DTPM framework is built on top of the
 126 powercap framework. Thus the sysfs interface is the same, please refer
 127 to the powercap documentation for further details.
 128
 129  * power_uw: Instantaneous power consumption. If the node is an
 130    intermediate node, then the power consumption will be the sum of all
 131    children power consumption.
 132
 133  * max_power_range_uw: The power range resulting of the maximum power
 134    minus the minimum power.
 135
 136  * name: The name of the node. This is implementation dependent. Even
 137    if it is not recommended for the user space, several nodes can have
 138    the same name.
 139
 140  * constraint_X_name: The name of the constraint.
 141
 142  * constraint_X_max_power_uw: The maximum power limit to be applicable
 143    to the node.
 144
 145  * constraint_X_power_limit_uw: The power limit to be applied to the
 146    node. If the value contained in constraint_X_max_power_uw is set,
 147    the constraint will be removed.
 148
 149  * constraint_X_time_window_us: The meaning of this file will depend
 150    on the constraint number.
 151
 152 Constraints
 153 -----------
 154
 155  * Constraint 0: The power limitation is immediately applied, without
 156    limitation in time.
 157
 158 Kernel API
 159 ==========
 160
 161 Overview
 162 --------
 163
 164 The DTPM framework has no power limiting backend support. It is
 165 generic and provides a set of API to let the different drivers to
 166 implement the backend part for the power limitation and create the
 167 power constraints tree.
 168
 169 It is up to the platform to provide the initialization function to
 170 allocate and link the different nodes of the tree.
 171
 172 A special macro has the role of declaring a node and the corresponding
 173 initialization function via a description structure. This one contains
 174 an optional parent field allowing to hook different devices to an
 175 already existing tree at boot time.
 176
 177 For instance::
 178
 179         struct dtpm_descr my_descr = {
 180                 .name = "my_name",
 181                 .init = my_init_func,
 182         };
 183
 184         DTPM_DECLARE(my_descr);
 185
 186 The nodes of the DTPM tree are described with dtpm structure. The
 187 steps to add a new power limitable device is done in three steps:
 188
 189  * Allocate the dtpm node
 190  * Set the power number of the dtpm node
 191  * Register the dtpm node
 192
 193 The registration of the dtpm node is done with the powercap
 194 ops. Basically, it must implements the callbacks to get and set the
 195 power and the limit.
 196
 197 Alternatively, if the node to be inserted is an intermediate one, then
 198 a simple function to insert it as a future parent is available.
 199
 200 If a device has its power characteristics changing, then the tree must
 201 be updated with the new power numbers and weights.
 202
 203 Nomenclature
 204 ------------
 205
 206  * dtpm_alloc() : Allocate and initialize a dtpm structure
 207
 208  * dtpm_register() : Add the dtpm node to the tree
 209
 210  * dtpm_unregister() : Remove the dtpm node from the tree
 211
 212  * dtpm_update_power() : Update the power characteristics of the dtpm node