sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget6/translations/zh_CN/driver-api/thermal/power_allocatormodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/zh_TW/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/it_IT/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/ja_JP/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/ko_KR/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/pt_BR/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/sp_SP/driver-api/thermal/power_allocatormodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h!Power allocator governor tunablesh]h!Power allocator governor tunables}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhP/var/lib/git/docbuild/linux/Documentation/driver-api/thermal/power_allocator.rsthKubh)}(hhh](h)}(h Trip pointsh]h Trip points}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hHThe governor works optimally with the following two passive trip points:h]hHThe governor works optimally with the following two passive trip points:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhenumerated_list)}(hhh](h list_item)}(h"switch on" trip point: temperature above which the governor control loop starts operating. This is the first passive trip point of the thermal zone. h]h)}(h"switch on" trip point: temperature above which the governor control loop starts operating. This is the first passive trip point of the thermal zone.h]h“switch on” trip point: temperature above which the governor control loop starts operating. This is the first passive trip point of the thermal zone.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(h"desired temperature" trip point: it should be higher than the "switch on" trip point. This the target temperature the governor is controlling for. This is the last passive trip point of the thermal zone. h]h)}(h"desired temperature" trip point: it should be higher than the "switch on" trip point. This the target temperature the governor is controlling for. This is the last passive trip point of the thermal zone.h]h“desired temperature” trip point: it should be higher than the “switch on” trip point. This the target temperature the governor is controlling for. This is the last passive trip point of the thermal zone.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1hhhhhhhhK ubeh}(h] trip-pointsah ]h"] trip pointsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hPID Controllerh]hPID Controller}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhKubh)}(hThe power allocator governor implements a Proportional-Integral-Derivative controller (PID controller) with temperature as the control input and power as the controlled output:h]hThe power allocator governor implements a Proportional-Integral-Derivative controller (PID controller) with temperature as the control input and power as the controlled output:}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj6hhubh block_quote)}(hJP_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power h]h)}(hIP_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_powerh]hIP_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWubah}(h]h ]h"]h$]h&]uh1jUhhhKhj6hhubhdefinition_list)}(hhh]hdefinition_list_item)}(hwhere - e = desired_temperature - current_temperature - err_integral is the sum of previous errors - diff_err = e - previous_error h](hterm)}(hwhereh]hwhere}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjvubh definition)}(hhh]h bullet_list)}(hhh](h)}(h-e = desired_temperature - current_temperatureh]h)}(hjh]h-e = desired_temperature - current_temperature}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h*err_integral is the sum of previous errorsh]h)}(hjh]h*err_integral is the sum of previous errors}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hdiff_err = e - previous_error h]h)}(hdiff_err = e - previous_errorh]hdiff_err = e - previous_error}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjvubeh}(h]h ]h"]h$]h&]uh1jthhhKhjqubah}(h]h ]h"]h$]h&]uh1johj6hhhNhNubh)}(h)It is similar to the one depicted below::h]h(It is similar to the one depicted below:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hj6hhubh literal_block)}(hXF k_d | current_temp | | v | +----------+ +---+ | +----->| diff_err |-->| X |------+ | | +----------+ +---+ | | | | tdp actor | | k_i | | get_requested_power() | | | | | | | | | | | | | | ... v | v v v v v +---+ | +-------+ +---+ +---+ +---+ +----------+ | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power | +---+ | +-------+ +---+ +---+ +---+ |allocation| ^ | ^ +----------+ | | | | | | | +---+ | | | | +------->| X |-------------------+ v v | +---+ granted performance desired_temperature ^ | | k_po/k_puh]hXF k_d | current_temp | | v | +----------+ +---+ | +----->| diff_err |-->| X |------+ | | +----------+ +---+ | | | | tdp actor | | k_i | | get_requested_power() | | | | | | | | | | | | | | ... v | v v v v v +---+ | +-------+ +---+ +---+ +---+ +----------+ | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power | +---+ | +-------+ +---+ +---+ +---+ |allocation| ^ | ^ +----------+ | | | | | | | +---+ | | | | +------->| X |-------------------+ v v | +---+ granted performance desired_temperature ^ | | k_po/k_pu}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhK#hj6hhubeh}(h]pid-controllerah ]h"]pid controllerah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hSustainable powerh]hSustainable power}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK=ubh)}(hXAn estimate of the sustainable dissipatable power (in mW) should be provided while registering the thermal zone. This estimates the sustained power that can be dissipated at the desired control temperature. This is the maximum sustained power for allocation at the desired maximum temperature. The actual sustained power can vary for a number of reasons. The closed loop controller will take care of variations such as environmental conditions, and some factors related to the speed-grade of the silicon. `sustainable_power` is therefore simply an estimate, and may be tuned to affect the aggressiveness of the thermal ramp. For reference, the sustainable power of a 4" phone is typically 2000mW, while on a 10" tablet is around 4500mW (may vary depending on screen size). It is possible to have the power value expressed in an abstract scale. The sustained power should be aligned to the scale used by the related cooling devices.h](hXAn estimate of the sustainable dissipatable power (in mW) should be provided while registering the thermal zone. This estimates the sustained power that can be dissipated at the desired control temperature. This is the maximum sustained power for allocation at the desired maximum temperature. The actual sustained power can vary for a number of reasons. The closed loop controller will take care of variations such as environmental conditions, and some factors related to the speed-grade of the silicon. }(hj-hhhNhNubhtitle_reference)}(h`sustainable_power`h]hsustainable_power}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj-ubhX is therefore simply an estimate, and may be tuned to affect the aggressiveness of the thermal ramp. For reference, the sustainable power of a 4” phone is typically 2000mW, while on a 10” tablet is around 4500mW (may vary depending on screen size). It is possible to have the power value expressed in an abstract scale. The sustained power should be aligned to the scale used by the related cooling devices.}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hjhhubh)}(hYIf you are using device tree, do add it as a property of the thermal-zone. For example::h]hXIf you are using device tree, do add it as a property of the thermal-zone. For example:}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjhhubj)}(hthermal-zones { soc_thermal { polling-delay = <1000>; polling-delay-passive = <100>; sustainable-power = <2500>; ...h]hthermal-zones { soc_thermal { polling-delay = <1000>; polling-delay-passive = <100>; sustainable-power = <2500>; ...}hj]sbah}(h]h ]h"]h$]h&]jjuh1jhhhKQhjhhubh)}(hInstead, if the thermal zone is registered from the platform code, pass a `thermal_zone_params` that has a `sustainable_power`. If no `thermal_zone_params` were being passed, then something like below will suffice::h](hJInstead, if the thermal zone is registered from the platform code, pass a }(hjkhhhNhNubj6)}(h`thermal_zone_params`h]hthermal_zone_params}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjkubh that has a }(hjkhhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjkubh . If no }(hjkhhhNhNubj6)}(h`thermal_zone_params`h]hthermal_zone_params}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjkubh; were being passed, then something like below will suffice:}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubj)}(h[static const struct thermal_zone_params tz_params = { .sustainable_power = 3500, };h]h[static const struct thermal_zone_params tz_params = { .sustainable_power = 3500, };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhK]hjhhubh)}(hRand then pass `tz_params` as the 5th parameter to `thermal_zone_device_register()`h](hand then pass }(hjhhhNhNubj6)}(h `tz_params`h]h tz_params}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh as the 5th parameter to }(hjhhhNhNubj6)}(h `thermal_zone_device_register()`h]hthermal_zone_device_register()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1hhhhKahjhhubeh}(h]sustainable-powerah ]h"]sustainable powerah$]h&]uh1hhhhhhhhK=ubh)}(hhh](h)}(h k_po and k_puh]h k_po and k_pu}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKeubh)}(hXThe implementation of the PID controller in the power allocator thermal governor allows the configuration of two proportional term constants: `k_po` and `k_pu`. `k_po` is the proportional term constant during temperature overshoot periods (current temperature is above "desired temperature" trip point). Conversely, `k_pu` is the proportional term constant during temperature undershoot periods (current temperature below "desired temperature" trip point).h](hThe implementation of the PID controller in the power allocator thermal governor allows the configuration of two proportional term constants: }(hjhhhNhNubj6)}(h`k_po`h]hk_po}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh and }(hjhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. }(hjhhhNhNubj6)}(h`k_po`h]hk_po}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh is the proportional term constant during temperature overshoot periods (current temperature is above “desired temperature” trip point). Conversely, }(hjhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh is the proportional term constant during temperature undershoot periods (current temperature below “desired temperature” trip point).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKghjhhubh)}(hXThese controls are intended as the primary mechanism for configuring the permitted thermal "ramp" of the system. For instance, a lower `k_pu` value will provide a slower ramp, at the cost of capping available capacity at a low temperature. On the other hand, a high value of `k_pu` will result in the governor granting very high power while temperature is low, and may lead to temperature overshooting.h](hThese controls are intended as the primary mechanism for configuring the permitted thermal “ramp” of the system. For instance, a lower }(hjZhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjZubh value will provide a slower ramp, at the cost of capping available capacity at a low temperature. On the other hand, a high value of }(hjZhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjZubhy will result in the governor granting very high power while temperature is low, and may lead to temperature overshooting.}(hjZhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKohjhhubh)}(h!The default value for `k_pu` is::h](hThe default value for }(hjhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh is:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKvhjhhubj)}(h>2 * sustainable_power / (desired_temperature - switch_on_temp)h]h>2 * sustainable_power / (desired_temperature - switch_on_temp)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKxhjhhubh)}(hThis means that at `switch_on_temp` the output of the controller's proportional term will be 2 * `sustainable_power`. The default value for `k_po` is::h](hThis means that at }(hjhhhNhNubj6)}(h`switch_on_temp`h]hswitch_on_temp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh@ the output of the controller’s proportional term will be 2 * }(hjhhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. The default value for }(hjhhhNhNubj6)}(h`k_po`h]hk_po}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh is:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhjhhubj)}(h:sustainable_power / (desired_temperature - switch_on_temp)h]h:sustainable_power / (desired_temperature - switch_on_temp)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhK~hjhhubh)}(h]Focusing on the proportional and feed forward values of the PID controller equation we have::h]h\Focusing on the proportional and feed forward values of the PID controller equation we have:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h#P_max = k_p * e + sustainable_powerh]h#P_max = k_p * e + sustainable_power}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hXThe proportional term is proportional to the difference between the desired temperature and the current one. When the current temperature is the desired one, then the proportional component is zero and `P_max` = `sustainable_power`. That is, the system should operate in thermal equilibrium under constant load. `sustainable_power` is only an estimate, which is the reason for closed-loop control such as this.h](hThe proportional term is proportional to the difference between the desired temperature and the current one. When the current temperature is the desired one, then the proportional component is zero and }(hj(hhhNhNubj6)}(h`P_max`h]hP_max}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj(ubh = }(hj(hhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj(ubhS. That is, the system should operate in thermal equilibrium under constant load. }(hj(hhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj(ubhO is only an estimate, which is the reason for closed-loop control such as this.}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hExpanding `k_pu` we get::h](h Expanding }(hjlhhhNhNubj6)}(h`k_pu`h]hk_pu}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjlubh we get:}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hTP_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) + sustainable_powerh]hTP_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) + sustainable_power}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hwhere:h]hwhere:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjV)}(hf- T_set is the desired temperature - T is the current temperature - T_on is the switch on temperature h]j)}(hhh](h)}(h T_set is the desired temperatureh]h)}(hjh]h T_set is the desired temperature}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hT is the current temperatureh]h)}(hjh]hT is the current temperature}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h"T_on is the switch on temperature h]h)}(h!T_on is the switch on temperatureh]h!T_on is the switch on temperature}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jUhhhKhjhhubh)}(hVWhen the current temperature is the switch_on temperature, the above formula becomes::h]hUWhen the current temperature is the switch_on temperature, the above formula becomes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hP_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) + sustainable_power = 2 * sustainable_power + sustainable_power = 3 * sustainable_powerh]hP_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) + sustainable_power = 2 * sustainable_power + sustainable_power = 3 * sustainable_power}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hTherefore, the proportional term alone linearly decreases power from 3 * `sustainable_power` to `sustainable_power` as the temperature rises from the switch on temperature to the desired temperature.h](hITherefore, the proportional term alone linearly decreases power from 3 * }(hjhhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh to }(hjhhhNhNubj6)}(h`sustainable_power`h]hsustainable_power}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubhT as the temperature rises from the switch on temperature to the desired temperature.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] k-po-and-k-puah ]h"] k_po and k_puah$]h&]uh1hhhhhhhhKeubh)}(hhh](h)}(hk_i and integral_cutoffh]hk_i and integral_cutoff}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWhhhhhKubh)}(hX`k_i` configures the PID loop's integral term constant. This term allows the PID controller to compensate for long term drift and for the quantized nature of the output control: cooling devices can't set the exact power that the governor requests. When the temperature error is below `integral_cutoff`, errors are accumulated in the integral term. This term is then multiplied by `k_i` and the result added to the output of the controller. Typically `k_i` is set low (1 or 2) and `integral_cutoff` is 0.h](j6)}(h`k_i`h]hk_i}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhubhX configures the PID loop’s integral term constant. This term allows the PID controller to compensate for long term drift and for the quantized nature of the output control: cooling devices can’t set the exact power that the governor requests. When the temperature error is below }(hjhhhhNhNubj6)}(h`integral_cutoff`h]hintegral_cutoff}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhubhP, errors are accumulated in the integral term. This term is then multiplied by }(hjhhhhNhNubj6)}(h`k_i`h]hk_i}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhubhB and the result added to the output of the controller. Typically }(hjhhhhNhNubj6)}(h`k_i`h]hk_i}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhubh is set low (1 or 2) and }(hjhhhhNhNubj6)}(h`integral_cutoff`h]hintegral_cutoff}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhubh is 0.}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubeh}(h]k-i-and-integral-cutoffah ]h"]k_i and integral_cutoffah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hk_dh]hk_d}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hj`k_d` configures the PID loop's derivative term constant. It's recommended to leave it as the default: 0.h](j6)}(h`k_d`h]hk_d}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubhi configures the PID loop’s derivative term constant. It’s recommended to leave it as the default: 0.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(hCooling device power APIh]hCooling device power API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hCooling devices controlled by this governor must supply the additional "power" API in their `cooling_device_ops`. It consists on three ops:h](h`Cooling devices controlled by this governor must supply the additional “power” API in their }(hjhhhNhNubj6)}(h`cooling_device_ops`h]hcooling_device_ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. It consists on three ops:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh]h)}(h:: int get_requested_power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, u32 *power); h]j)}(hint get_requested_power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, u32 *power);h]hint get_requested_power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, u32 *power);}hj9sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhj5ubah}(h]h ]h"]h$]h&]uh1hhj2hhhhhNubah}(h]h ]h"]h$]h&]j)j*j+hj,j-uh1hhjhhhhhKubjp)}(hhh](ju)}(h2@cdev: The `struct thermal_cooling_device` pointerh](j{)}(h@cdev:h]h@cdev:}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjVubj)}(hhh]h)}(h+The `struct thermal_cooling_device` pointerh](hThe }(hjkhhhNhNubj6)}(h`struct thermal_cooling_device`h]hstruct thermal_cooling_device}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjkubh pointer}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhubah}(h]h ]h"]h$]h&]uh1jhjVubeh}(h]h ]h"]h$]h&]uh1jthhhKhjSubju)}(h5@tz: thermal zone in which we are currently operatingh](j{)}(h@tz:h]h@tz:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(h0thermal zone in which we are currently operatingh]h0thermal zone in which we are currently operating}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhjShhubju)}(h7@power: pointer in which to store the calculated power h](j{)}(h@power:h]h@power:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(h.pointer in which to store the calculated powerh]h.pointer in which to store the calculated power}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhjShhubeh}(h]h ]h"]h$]h&]uh1johjhhhhhNubh)}(hX`get_requested_power()` calculates the power requested by the device in milliwatts and stores it in @power . It should return 0 on success, -E* on failure. This is currently used by the power allocator governor to calculate how much power to give to each cooling device.h](j6)}(h`get_requested_power()`h]hget_requested_power()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh calculates the power requested by the device in milliwatts and stores it in @power . It should return 0 on success, -E* on failure. This is currently used by the power allocator governor to calculate how much power to give to each cooling device.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh]h)}(h:: int state2power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, unsigned long state, u32 *power); h]j)}(hint state2power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, unsigned long state, u32 *power);h]hint state2power(struct thermal_cooling_device *cdev, struct thermal_zone_device *tz, unsigned long state, u32 *power);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubah}(h]h ]h"]h$]h&]j)j*j+hj,j-startKuh1hhjhhhhhKubjp)}(hhh](ju)}(h2@cdev: The `struct thermal_cooling_device` pointerh](j{)}(h@cdev:h]h@cdev:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhj<ubj)}(hhh]h)}(h+The `struct thermal_cooling_device` pointerh](hThe }(hjQhhhNhNubj6)}(h`struct thermal_cooling_device`h]hstruct thermal_cooling_device}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjQubh pointer}(hjQhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjNubah}(h]h ]h"]h$]h&]uh1jhj<ubeh}(h]h ]h"]h$]h&]uh1jthhhKhj9ubju)}(h5@tz: thermal zone in which we are currently operatingh](j{)}(h@tz:h]h@tz:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhj}ubj)}(hhh]h)}(h0thermal zone in which we are currently operatingh]h0thermal zone in which we are currently operating}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj}ubeh}(h]h ]h"]h$]h&]uh1jthhhKhj9hhubju)}(h@state: A cooling device stateh](j{)}(h@state:h]h@state:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(hA cooling device stateh]hA cooling device state}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhj9hhubju)}(h7@power: pointer in which to store the equivalent power h](j{)}(h@power:h]h@power:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(h.pointer in which to store the equivalent powerh]h.pointer in which to store the equivalent power}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhj9hhubeh}(h]h ]h"]h$]h&]uh1johjhhhhhNubh)}(hConvert cooling device state @state into power consumption in milliwatts and store it in @power. It should return 0 on success, -E* on failure. This is currently used by thermal core to calculate the maximum power that an actor can consume.h]hConvert cooling device state @state into power consumption in milliwatts and store it in @power. It should return 0 on success, -E* on failure. This is currently used by thermal core to calculate the maximum power that an actor can consume.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh]h)}(hu:: int power2state(struct thermal_cooling_device *cdev, u32 power, unsigned long *state); h]j)}(hfint power2state(struct thermal_cooling_device *cdev, u32 power, unsigned long *state);h]hfint power2state(struct thermal_cooling_device *cdev, u32 power, unsigned long *state);}hj%sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhj!ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubah}(h]h ]h"]h$]h&]j)j*j+hj,j-j8Kuh1hhjhhhhhKubjp)}(hhh](ju)}(h2@cdev: The `struct thermal_cooling_device` pointerh](j{)}(h@cdev:h]h@cdev:}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjBubj)}(hhh]h)}(h+The `struct thermal_cooling_device` pointerh](hThe }(hjWhhhNhNubj6)}(h`struct thermal_cooling_device`h]hstruct thermal_cooling_device}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjWubh pointer}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjTubah}(h]h ]h"]h$]h&]uh1jhjBubeh}(h]h ]h"]h$]h&]uh1jthhhKhj?ubju)}(h@power: power in milliwattsh](j{)}(h@power:h]h@power:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(hpower in milliwattsh]hpower in milliwatts}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhj?hhubju)}(h6@state: pointer in which to store the resulting state h](j{)}(h@state:h]h@state:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jzhhhKhjubj)}(hhh]h)}(h-pointer in which to store the resulting stateh]h-pointer in which to store the resulting state}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jthhhKhj?hhubeh}(h]h ]h"]h$]h&]uh1johjhhhhhNubh)}(hXCalculate a cooling device state that would make the device consume at most @power mW and store it in @state. It should return 0 on success, -E* on failure. This is currently used by the thermal core to convert a given power set by the power allocator governor to a state that the cooling device can set. It is a function because this conversion may depend on external factors that may change so this function should the best conversion given "current circumstances".h]hXCalculate a cooling device state that would make the device consume at most @power mW and store it in @state. It should return 0 on success, -E* on failure. This is currently used by the thermal core to convert a given power set by the power allocator governor to a state that the cooling device can set. It is a function because this conversion may depend on external factors that may change so this function should the best conversion given “current circumstances”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]cooling-device-power-apiah ]h"]cooling device power apiah$]h&]uh1hhjhhhhhKubeh}(h]k-dah ]h"]k_dah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hCooling device weightsh]hCooling device weights}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hX Weights are a mechanism to bias the allocation among cooling devices. They express the relative power efficiency of different cooling devices. Higher weight can be used to express higher power efficiency. Weighting is relative such that if each cooling device has a weight of one they are considered equal. This is particularly useful in heterogeneous systems where two cooling devices may perform the same kind of compute, but with different efficiency. For example, a system with two different types of processors.h]hX Weights are a mechanism to bias the allocation among cooling devices. They express the relative power efficiency of different cooling devices. Higher weight can be used to express higher power efficiency. Weighting is relative such that if each cooling device has a weight of one they are considered equal. This is particularly useful in heterogeneous systems where two cooling devices may perform the same kind of compute, but with different efficiency. For example, a system with two different types of processors.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX=If the thermal zone is registered using `thermal_zone_device_register()` (i.e., platform code), then weights are passed as part of the thermal zone's `thermal_bind_parameters`. If the platform is registered using device tree, then they are passed as the `contribution` property of each map in the `cooling-maps` node.h](h(If the thermal zone is registered using }(hj$ hhhNhNubj6)}(h `thermal_zone_device_register()`h]hthermal_zone_device_register()}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj$ ubhP (i.e., platform code), then weights are passed as part of the thermal zone’s }(hj$ hhhNhNubj6)}(h`thermal_bind_parameters`h]hthermal_bind_parameters}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj$ ubhO. If the platform is registered using device tree, then they are passed as the }(hj$ hhhNhNubj6)}(h`contribution`h]h contribution}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj$ ubh property of each map in the }(hj$ hhhNhNubj6)}(h`cooling-maps`h]h cooling-maps}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj$ ubh node.}(hj$ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hhh](h)}(h+Limitations of the power allocator governorh]h+Limitations of the power allocator governor}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjz hhhhhMubh)}(hXThe power allocator governor's PID controller works best if there is a periodic tick. If you have a driver that calls `thermal_zone_device_update()` (or anything that ends up calling the governor's `throttle()` function) repetitively, the governor response won't be very good. Note that this is not particular to this governor, step-wise will also misbehave if you call its throttle() faster than the normal thermal framework tick (due to interrupts for example) as it will overreact.h](hyThe power allocator governor’s PID controller works best if there is a periodic tick. If you have a driver that calls }(hj hhhNhNubj6)}(h`thermal_zone_device_update()`h]hthermal_zone_device_update()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj ubh4 (or anything that ends up calling the governor’s }(hj hhhNhNubj6)}(h `throttle()`h]h throttle()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj ubhX function) repetitively, the governor response won’t be very good. Note that this is not particular to this governor, step-wise will also misbehave if you call its throttle() faster than the normal thermal framework tick (due to interrupts for example) as it will overreact.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjz hhubeh}(h]+limitations-of-the-power-allocator-governorah ]h"]+limitations of the power allocator governorah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(hEnergy Model requirementsh]hEnergy Model requirements}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hAnother important thing is the consistent scale of the power values provided by the cooling devices. All of the cooling devices in a single thermal zone should have power values reported either in milli-Watts or scaled to the same 'abstract scale'.h]hAnother important thing is the consistent scale of the power values provided by the cooling devices. All of the cooling devices in a single thermal zone should have power values reported either in milli-Watts or scaled to the same ‘abstract scale’.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]energy-model-requirementsah ]h"]energy model requirementsah$]h&]uh1hhj hhhhhMubeh}(h]cooling-device-weightsah ]h"]cooling device weightsah$]h&]uh1hhhhhhhhKubeh}(h]!power-allocator-governor-tunablesah ]h"]!power allocator governor tunablesah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j j3j0jjjjjTjQjjj jjjj j j j j j u nametypes}(j j3jjjTjj jj j j uh}(j hj0hjj6jjjQjjjWjjjjj j j jz j j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages](hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehʌlineKuh1j hjhhhhhKubj )}(hhh]h)}(h:Enumerated list start value not ordinal-1: "3" (ordinal 3)h]h>Enumerated list start value not ordinal-1: “3” (ordinal 3)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j hjhhhhhKubetransform_messages] transformerN include_log] decorationNhhub.