1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2014 Intel Corporation 3 */ 4 5 #ifndef _RTE_POWER_H 6 #define _RTE_POWER_H 7 8 /** 9 * @file 10 * RTE Power Management 11 */ 12 13 #include <rte_common.h> 14 #include <rte_log.h> 15 #include <rte_power_guest_channel.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /* Power Management Environment State */ 22 enum power_management_env {PM_ENV_NOT_SET, PM_ENV_ACPI_CPUFREQ, PM_ENV_KVM_VM, 23 PM_ENV_PSTATE_CPUFREQ, PM_ENV_CPPC_CPUFREQ}; 24 25 /** 26 * @warning 27 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 28 * 29 * Check if a specific power management environment type is supported on a 30 * currently running system. 31 * 32 * @param env 33 * The environment type to check support for. 34 * 35 * @return 36 * - 1 if supported 37 * - 0 if unsupported 38 * - -1 if error, with rte_errno indicating reason for error. 39 */ 40 __rte_experimental 41 int rte_power_check_env_supported(enum power_management_env env); 42 43 /** 44 * Set the default power management implementation. If this is not called prior 45 * to rte_power_init(), then auto-detect of the environment will take place. 46 * It is thread safe. New env can be set only in uninitialized state 47 * (thus rte_power_unset_env must be called if different env was already set). 48 * 49 * @param env 50 * env. The environment in which to initialise Power Management for. 51 * 52 * @return 53 * - 0 on success. 54 * - Negative on error. 55 */ 56 int rte_power_set_env(enum power_management_env env); 57 58 /** 59 * Unset the global environment configuration. 60 * This can only be called after all threads have completed. 61 */ 62 void rte_power_unset_env(void); 63 64 /** 65 * Get the default power management implementation. 66 * 67 * @return 68 * power_management_env The configured environment. 69 */ 70 enum power_management_env rte_power_get_env(void); 71 72 /** 73 * Initialize power management for a specific lcore. If rte_power_set_env() has 74 * not been called then an auto-detect of the environment will start and 75 * initialise the corresponding resources. 76 * 77 * @param lcore_id 78 * lcore id. 79 * 80 * @return 81 * - 0 on success. 82 * - Negative on error. 83 */ 84 int rte_power_init(unsigned int lcore_id); 85 86 /** 87 * Exit power management on a specific lcore. This will call the environment 88 * dependent exit function. 89 * 90 * @param lcore_id 91 * lcore id. 92 * 93 * @return 94 * - 0 on success. 95 * - Negative on error. 96 */ 97 int rte_power_exit(unsigned int lcore_id); 98 99 /** 100 * Get the available frequencies of a specific lcore. 101 * Function pointer definition. Review each environments 102 * specific documentation for usage. 103 * 104 * @param lcore_id 105 * lcore id. 106 * @param freqs 107 * The buffer array to save the frequencies. 108 * @param num 109 * The number of frequencies to get. 110 * 111 * @return 112 * The number of available frequencies. 113 */ 114 typedef uint32_t (*rte_power_freqs_t)(unsigned int lcore_id, uint32_t *freqs, 115 uint32_t num); 116 117 extern rte_power_freqs_t rte_power_freqs; 118 119 /** 120 * Return the current index of available frequencies of a specific lcore. 121 * Function pointer definition. Review each environments 122 * specific documentation for usage. 123 * 124 * @param lcore_id 125 * lcore id. 126 * 127 * @return 128 * The current index of available frequencies. 129 */ 130 typedef uint32_t (*rte_power_get_freq_t)(unsigned int lcore_id); 131 132 extern rte_power_get_freq_t rte_power_get_freq; 133 134 /** 135 * Set the new frequency for a specific lcore by indicating the index of 136 * available frequencies. 137 * Function pointer definition. Review each environments 138 * specific documentation for usage. 139 * 140 * @param lcore_id 141 * lcore id. 142 * @param index 143 * The index of available frequencies. 144 * 145 * @return 146 * - 1 on success with frequency changed. 147 * - 0 on success without frequency changed. 148 * - Negative on error. 149 */ 150 typedef int (*rte_power_set_freq_t)(unsigned int lcore_id, uint32_t index); 151 152 extern rte_power_set_freq_t rte_power_set_freq; 153 154 /** 155 * Function pointer definition for generic frequency change functions. Review 156 * each environments specific documentation for usage. 157 * 158 * @param lcore_id 159 * lcore id. 160 * 161 * @return 162 * - 1 on success with frequency changed. 163 * - 0 on success without frequency changed. 164 * - Negative on error. 165 */ 166 typedef int (*rte_power_freq_change_t)(unsigned int lcore_id); 167 168 /** 169 * Scale up the frequency of a specific lcore according to the available 170 * frequencies. 171 * Review each environments specific documentation for usage. 172 * 173 * @param lcore_id 174 * lcore id. 175 * 176 * @return 177 * - 1 on success with frequency changed. 178 * - 0 on success without frequency changed. 179 * - Negative on error. 180 */ 181 extern rte_power_freq_change_t rte_power_freq_up; 182 183 /** 184 * Scale down the frequency of a specific lcore according to the available 185 * frequencies. 186 * Review each environments specific documentation for usage. 187 * 188 * @param lcore_id 189 * lcore id. 190 * 191 * @return 192 * - 1 on success with frequency changed. 193 * - 0 on success without frequency changed. 194 * - Negative on error. 195 */ 196 197 extern rte_power_freq_change_t rte_power_freq_down; 198 199 /** 200 * Scale up the frequency of a specific lcore to the highest according to the 201 * available frequencies. 202 * Review each environments specific documentation for usage. 203 * 204 * @param lcore_id 205 * lcore id. 206 * 207 * @return 208 * - 1 on success with frequency changed. 209 * - 0 on success without frequency changed. 210 * - Negative on error. 211 */ 212 extern rte_power_freq_change_t rte_power_freq_max; 213 214 /** 215 * Scale down the frequency of a specific lcore to the lowest according to the 216 * available frequencies. 217 * Review each environments specific documentation for usage.. 218 * 219 * @param lcore_id 220 * lcore id. 221 * 222 * @return 223 * - 1 on success with frequency changed. 224 * - 0 on success without frequency changed. 225 * - Negative on error. 226 */ 227 extern rte_power_freq_change_t rte_power_freq_min; 228 229 /** 230 * Query the Turbo Boost status of a specific lcore. 231 * Review each environments specific documentation for usage.. 232 * 233 * @param lcore_id 234 * lcore id. 235 * 236 * @return 237 * - 1 Turbo Boost is enabled for this lcore. 238 * - 0 Turbo Boost is disabled for this lcore. 239 * - Negative on error. 240 */ 241 extern rte_power_freq_change_t rte_power_turbo_status; 242 243 /** 244 * Enable Turbo Boost for this lcore. 245 * Review each environments specific documentation for usage.. 246 * 247 * @param lcore_id 248 * lcore id. 249 * 250 * @return 251 * - 0 on success. 252 * - Negative on error. 253 */ 254 extern rte_power_freq_change_t rte_power_freq_enable_turbo; 255 256 /** 257 * Disable Turbo Boost for this lcore. 258 * Review each environments specific documentation for usage.. 259 * 260 * @param lcore_id 261 * lcore id. 262 * 263 * @return 264 * - 0 on success. 265 * - Negative on error. 266 */ 267 extern rte_power_freq_change_t rte_power_freq_disable_turbo; 268 269 /** 270 * Power capabilities summary. 271 */ 272 struct rte_power_core_capabilities { 273 RTE_STD_C11 274 union { 275 uint64_t capabilities; 276 RTE_STD_C11 277 struct { 278 uint64_t turbo:1; /**< Turbo can be enabled. */ 279 uint64_t priority:1; /**< SST-BF high freq core */ 280 }; 281 }; 282 }; 283 284 /** 285 * Returns power capabilities for a specific lcore. 286 * Function pointer definition. Review each environments 287 * specific documentation for usage. 288 * 289 * @param lcore_id 290 * lcore id. 291 * @param caps 292 * pointer to rte_power_core_capabilities object. 293 * 294 * @return 295 * - 0 on success. 296 * - Negative on error. 297 */ 298 typedef int (*rte_power_get_capabilities_t)(unsigned int lcore_id, 299 struct rte_power_core_capabilities *caps); 300 301 extern rte_power_get_capabilities_t rte_power_get_capabilities; 302 303 #ifdef __cplusplus 304 } 305 #endif 306 307 #endif 308