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