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 S
8 increasing number of hotspots which need to be
9 as a whole in order to prevent the temperature
10 normative and legally stated 'skin temperature
11
12 Another aspect is to sustain the performance f
13 for example virtual reality where the user can
14 performance is capped while a big CPU is proce
15 reduce the battery charging because the dissip
16 compared with the power consumed by other devi
17
18 The user space is the most adequate place to d
19 different devices by limiting their power give
20 profile: it has the knowledge of the platform.
21
22 The Dynamic Thermal Power Management (DTPM) is
23 the device power by limiting and/or balancing
24 different devices.
25
26 The DTPM framework provides an unified interfa
27 device power.
28
29 Overview
30 ========
31
32 The DTPM framework relies on the powercap fram
33 powercap entries in the sysfs directory and im
34 driver to do the connection with the power man
35
36 The DTPM is a tree representation describing t
37 shared between devices, not their physical pos
38
39 The nodes of the tree are a virtual descriptio
40 characteristics of the children nodes and thei
41
42 The leaves of the tree are the real power mana
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 p
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
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 reflec
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 a
89
90 When a power limitation is applied to a node,
91
92 SoC (w=1024) <--- power_limit = 3200mW
93 |
94 |-- pkg (w=538) --> power_limit = 1681mW
95 | |
96 | |-- pd0 (w=231) --> power_limit = 378m
97 | |
98 | `-- pd1 (w=794) --> power_limit = 1303
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
107 description is the simplest one and it is supp
108 space a flat representation of all the devices
109 limitation without any power limitation distri
110
111 Hierarchical description
112 ------------------------
113
114 The different devices supporting the power lim
115 hierarchically. There is one root node, all in
116 grouping the child nodes which can be intermed
117 devices.
118
119 The intermediate nodes aggregate the power inf
120 set the power limit given the weight of the no
121
122 User space API
123 ==============
124
125 As stated in the overview, the DTPM framework
126 powercap framework. Thus the sysfs interface i
127 to the powercap documentation for further deta
128
129 * power_uw: Instantaneous power consumption.
130 intermediate node, then the power consumpti
131 children power consumption.
132
133 * max_power_range_uw: The power range resulti
134 minus the minimum power.
135
136 * name: The name of the node. This is impleme
137 if it is not recommended for the user space
138 the same name.
139
140 * constraint_X_name: The name of the constrai
141
142 * constraint_X_max_power_uw: The maximum powe
143 to the node.
144
145 * constraint_X_power_limit_uw: The power limi
146 node. If the value contained in constraint_
147 the constraint will be removed.
148
149 * constraint_X_time_window_us: The meaning of
150 on the constraint number.
151
152 Constraints
153 -----------
154
155 * Constraint 0: The power limitation is immed
156 limitation in time.
157
158 Kernel API
159 ==========
160
161 Overview
162 --------
163
164 The DTPM framework has no power limiting backe
165 generic and provides a set of API to let the d
166 implement the backend part for the power limit
167 power constraints tree.
168
169 It is up to the platform to provide the initia
170 allocate and link the different nodes of the t
171
172 A special macro has the role of declaring a no
173 initialization function via a description stru
174 an optional parent field allowing to hook diff
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
187 steps to add a new power limitable device is d
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
194 ops. Basically, it must implements the callbac
195 power and the limit.
196
197 Alternatively, if the node to be inserted is a
198 a simple function to insert it as a future par
199
200 If a device has its power characteristics chan
201 be updated with the new power numbers and weig
202
203 Nomenclature
204 ------------
205
206 * dtpm_alloc() : Allocate and initialize a dt
207
208 * dtpm_register() : Add the dtpm node to the
209
210 * dtpm_unregister() : Remove the dtpm node fr
211
212 * dtpm_update_power() : Update the power char
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.