Orange Pi5 kernel

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