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