1 /* 2 * Arm SCP/MCP Software 3 * Copyright (c) 2022, Arm Limited and Contributors. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef MOD_THERMAL_MGMT_H 9 #define MOD_THERMAL_MGMT_H 10 11 #include <fwk_element.h> 12 #include <fwk_id.h> 13 #include <fwk_module_idx.h> 14 15 #include <stdint.h> 16 17 /*! 18 * \ingroup GroupModules 19 * \defgroup GroupThermal Thermal Management 20 * 21 * \details Module for controlling/limiting the Performance of a platform based 22 * on thermal input. 23 * 24 * \{ 25 */ 26 27 /*! 28 * \brief Number of defined APIs for Thermal Management Module. 29 */ 30 enum mod_thermal_api_idx { 31 /*! 32 * \brief Performance Update API index. 33 * 34 * \note This API implements the ::perf_plugins_api interface. 35 */ 36 MOD_THERMAL_API_PERF_UPDATE_IDX, 37 38 MOD_THERMAL_API_COUNT, 39 }; 40 41 /*! 42 * \brief Thermal Mgmt activity factor configuration. 43 * 44 * \details Configuration structure for activity factor. 45 */ 46 struct mod_thermal_mgmt_activity_factor_config { 47 /*! Activity factor driver identifier */ 48 fwk_id_t driver_id; 49 50 /*! Activity factor driver API identifier */ 51 fwk_id_t driver_api_id; 52 }; 53 54 /*! 55 * \brief Thermal Mgmt actors configuration. 56 * 57 * \details Configuration structure for individual thermal actors. 58 * Please refer to the doc section for further details. 59 */ 60 struct mod_thermal_mgmt_actor_config { 61 /*! Element identifier of the corresponding power model */ 62 fwk_id_t driver_id; 63 64 /*! Corresponding DVFS Element identifier for this device */ 65 fwk_id_t dvfs_domain_id; 66 67 /*! 68 * \brief Weight coefficient for power distribution. 69 * 70 * \details Its value can be any. It expresses the relative weight to other 71 * devices. 72 */ 73 uint16_t weight; 74 75 /*! Activity factor configuration */ 76 struct mod_thermal_mgmt_activity_factor_config *activity_factor; 77 }; 78 79 /*! 80 * \brief Thermal Mgmt protection configuration. 81 * 82 * \details Configuration structure for thermal protection. 83 */ 84 struct mod_thermal_mgmt_protection_config { 85 /*! Thermal protection driver identifier */ 86 fwk_id_t driver_id; 87 88 /*! Thermal protection driver API identifier*/ 89 fwk_id_t driver_api_id; 90 91 /*! 92 * \brief Warning temperature value threshold. 93 * 94 * \details Warning temperature threshold value that activates the thermal 95 * protection. The corresponding callback is invoked when the 96 * temperature is above the threshold. 97 */ 98 uint32_t warn_temp_threshold; 99 100 /*! 101 * \brief Critical temperature threshold value. 102 * 103 * \details Critical temperature threshold value that activates the thermal 104 * protection. It is expected that `warn_temp_threshold` > 105 * `crit_temp_threshold`. The corresponding callback is invoked when 106 * the temperature is above the threshold. 107 */ 108 uint32_t crit_temp_threshold; 109 }; 110 111 /*! 112 * \brief Thermal Mgmt device configuration. 113 * 114 * \details Configuration structure for individual thermal devices. 115 * Please refer to the doc section for further details. 116 */ 117 struct mod_thermal_mgmt_dev_config { 118 /*! 119 * \brief Slow loop multiplier. 120 * 121 * \details The slow loop time interval is derived as follow: 122 * slow_loop_period = slow_loop_mult * perf_update_period. 123 */ 124 unsigned int slow_loop_mult; 125 126 /*! The thermal design power (TDP) for all the devices being controlled */ 127 uint16_t tdp; 128 129 /*! 130 * \brief Switch-on temperature threshold. 131 * 132 * \details The temperature above which the PI loop runs. Below this 133 * threshold the power is allocated only on bias coefficients. 134 */ 135 struct { 136 /*! 137 * \brief Switch-on temperature threshold. 138 * 139 * \details The temperature above which the PI loop runs. Below this 140 * threshold the power is allocated only on bias coefficients. 141 */ 142 uint32_t switch_on_temperature; 143 144 /*! 145 * \brief Control temperature 146 * 147 * \details The temperature that the system will achive once stabilised. 148 * Due to the PI nature of the controller, some 149 * overshoot/undershoot may occur. Note that the controller can 150 * only limit the temperature by placing a limit to the power to 151 * the heat source. It has no direct control on the heat source 152 * itself and therefore only the upper limit can be controlled. 153 */ 154 uint32_t control_temperature; 155 156 /*! 157 * \brief Integral cut-off threshold. 158 * 159 * \details Below this value the errors are accumulated. This is useful 160 * to avoid accumulating errors when the temperature is below the 161 * target. 162 */ 163 int32_t integral_cutoff; 164 165 /*! 166 * \brief Integral maximum. 167 * 168 * \details This is the upper limit the accumulated errors. 169 */ 170 int32_t integral_max; 171 172 /*! Proportional term when undershooting (PI loop)*/ 173 int32_t k_p_undershoot; 174 175 /*! Proportional term when overhooting (PI loop) */ 176 int32_t k_p_overshoot; 177 178 /*! Integral term (PI loop) */ 179 int32_t k_integral; 180 } pi_controller; 181 182 /*! Temperature sensor identifier */ 183 fwk_id_t sensor_id; 184 185 /*! 186 * \brief Thermal protection configuration. 187 * 188 * \details It is an optional feature. If it is left NULL it will not 189 * operate. 190 */ 191 struct mod_thermal_mgmt_protection_config *temp_protection; 192 193 /*! Power Model API identifier */ 194 fwk_id_t driver_api_id; 195 196 /*! Thermal actors lookup table */ 197 struct mod_thermal_mgmt_actor_config *thermal_actors_table; 198 199 /*! 200 * \brief The number of actors in the thermal actors lookup table. 201 * 202 * \details If it is left zero it will not the PI controller and power 203 * distribution will not take place. 204 */ 205 uint32_t thermal_actors_count; 206 }; 207 208 /*! 209 * \brief Power Model API. 210 * 211 * \details This API must be implemented by the platform. 212 */ 213 struct mod_thermal_mgmt_driver_api { 214 /*! 215 * \brief Performance Level to Power conversion. 216 * 217 * \details Convert a performance level into its corresponding power usage. 218 * 219 * \param domain_id Specific power model device id. 220 * \param level Performance level 221 * 222 * \retval power The corresponding power for a given performance level. 223 */ 224 uint32_t (*level_to_power)(fwk_id_t domain_id, const uint32_t level); 225 226 /*! 227 * \brief Power to Performance Level conversion. 228 * 229 * \details Convert a power usage into its corresponding performance level. 230 * 231 * \param domain_id Specific power model device id. 232 * \param power Power 233 * 234 * \retval level The corresponding performance level for a given power. 235 */ 236 uint32_t (*power_to_level)(fwk_id_t domain_id, const uint32_t power); 237 }; 238 239 /*! 240 * \brief Thermal management temperature protection API. 241 * 242 * \ details This API must be implemented by the platform. 243 */ 244 struct mod_thermal_mgmt_protection_api { 245 /*! 246 * \brief Thermal protection warning alarm callback. 247 * 248 * \details Informs once every time the temperature exceeds 249 * `warn_temp_threshold` value. The periodicity of this callback 250 * is not more often than `slow_loop_mult`. 251 * 252 * \param driver_id Specific driver identifier. 253 * \param thermal_id Specific thermal management controller device 254 * identifier. 255 */ 256 void (*warning)(fwk_id_t driver_id, fwk_id_t thermal_id); 257 258 /*! 259 * \brief Thermal protection critical alarm callback. 260 * 261 * \details Informs once every time the temperature exceeds 262 * `crit_temp_threshold` value. The periodicity of this callback 263 * is not more often than `slow_loop_mult`. 264 * 265 * \param driver_id Specific driver identifier. 266 * \param thermal_id Specific thermal management controller device 267 * identifier. 268 */ 269 void (*critical)(fwk_id_t driver_id, fwk_id_t thermal_id); 270 }; 271 272 /*! 273 * \brief Activity counter API. 274 * 275 * \details This API must be implemented by the platform. 276 */ 277 struct mod_thermal_mgmt_activity_factor_api { 278 /*! 279 * \brief Gets activity factor from the specified domain. 280 * 281 * \details Activity factor is referred to the corresponding actor and 282 * implemented by the platform. It must return a 10 bits 283 * resolution value (0-1023) where 0 corresponds to a complete 284 * inactivity and 1023 to 100% activity. 285 * 286 * \param domain_id Specific device id. 287 * \param[out] activity activity factor normalized to 10 bits. 288 * 289 * \retval ::FWK_E_PARAM One or more parameters were invalid. 290 * \retval ::FWK_SUCCESS The operation succeeded. 291 * 292 * \return Status code representing the result of the operation. 293 */ 294 int (*get_activity_factor)(fwk_id_t domain_id, uint16_t *activity); 295 }; 296 297 /*! 298 * \} 299 */ 300 301 #endif /* MOD_THERMAL_MGMT_H */ 302