1.. SPDX-License-Identifier: GPL-2.0 2 3========================================== 4Dynamic Thermal Power Management framework 5========================================== 6 7On the embedded world, the complexity of the SoC leads to an 8increasing number of hotspots which need to be monitored and mitigated 9as a whole in order to prevent the temperature to go above the 10normative and legally stated 'skin temperature'. 11 12Another aspect is to sustain the performance for a given power budget, 13for example virtual reality where the user can feel dizziness if the 14performance is capped while a big CPU is processing something else. Or 15reduce the battery charging because the dissipated power is too high 16compared with the power consumed by other devices. 17 18The user space is the most adequate place to dynamically act on the 19different devices by limiting their power given an application 20profile: it has the knowledge of the platform. 21 22The Dynamic Thermal Power Management (DTPM) is a technique acting on 23the device power by limiting and/or balancing a power budget among 24different devices. 25 26The DTPM framework provides an unified interface to act on the 27device power. 28 29Overview 30======== 31 32The DTPM framework relies on the powercap framework to create the 33powercap entries in the sysfs directory and implement the backend 34driver to do the connection with the power manageable device. 35 36The DTPM is a tree representation describing the power constraints 37shared between devices, not their physical positions. 38 39The nodes of the tree are a virtual description aggregating the power 40characteristics of the children nodes and their power limitations. 41 42The leaves of the tree are the real power manageable devices. 43 44For instance:: 45 46 SoC 47 | 48 `-- pkg 49 | 50 |-- pd0 (cpu0-3) 51 | 52 `-- pd1 (cpu4-5) 53 54The 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 64When 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 76Each 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 90When 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 103Flat description 104---------------- 105 106A root node is created and it is the parent of all the nodes. This 107description is the simplest one and it is supposed to give to user 108space a flat representation of all the devices supporting the power 109limitation without any power limitation distribution. 110 111Hierarchical description 112------------------------ 113 114The different devices supporting the power limitation are represented 115hierarchically. There is one root node, all intermediate nodes are 116grouping the child nodes which can be intermediate nodes also or real 117devices. 118 119The intermediate nodes aggregate the power information and allows to 120set the power limit given the weight of the nodes. 121 122User space API 123============== 124 125As stated in the overview, the DTPM framework is built on top of the 126powercap framework. Thus the sysfs interface is the same, please refer 127to 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 152Constraints 153----------- 154 155 * Constraint 0: The power limitation is immediately applied, without 156 limitation in time. 157 158Kernel API 159========== 160 161Overview 162-------- 163 164The DTPM framework has no power limiting backend support. It is 165generic and provides a set of API to let the different drivers to 166implement the backend part for the power limitation and create the 167power constraints tree. 168 169It is up to the platform to provide the initialization function to 170allocate and link the different nodes of the tree. 171 172A special macro has the role of declaring a node and the corresponding 173initialization function via a description structure. This one contains 174an optional parent field allowing to hook different devices to an 175already existing tree at boot time. 176 177For 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 186The nodes of the DTPM tree are described with dtpm structure. The 187steps 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 193The registration of the dtpm node is done with the powercap 194ops. Basically, it must implements the callbacks to get and set the 195power and the limit. 196 197Alternatively, if the node to be inserted is an intermediate one, then 198a simple function to insert it as a future parent is available. 199 200If a device has its power characteristics changing, then the tree must 201be updated with the new power numbers and weights. 202 203Nomenclature 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 213