~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/power/powercap/dtpm.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/power/powercap/dtpm.rst (Architecture ppc) and /Documentation/power/powercap/dtpm.rst (Architecture m68k)


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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php