1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2014 Intel Corporation 3 * Copyright(c) 2024 Advanced Micro Devices, Inc. 4 */ 5 6 #ifndef RTE_POWER_CPUFREQ_H 7 #define RTE_POWER_CPUFREQ_H 8 9 /** 10 * @file 11 * CPU Frequency Management 12 */ 13 14 #include <rte_common.h> 15 #include <rte_log.h> 16 #include <rte_power_guest_channel.h> 17 18 #include "power_cpufreq.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /* Power Management Environment State */ 25 enum power_management_env { 26 PM_ENV_NOT_SET = 0, 27 PM_ENV_ACPI_CPUFREQ, 28 PM_ENV_KVM_VM, 29 PM_ENV_PSTATE_CPUFREQ, 30 PM_ENV_CPPC_CPUFREQ, 31 PM_ENV_AMD_PSTATE_CPUFREQ 32 }; 33 34 /** 35 * Check if a specific power management environment type is supported on a 36 * currently running system. 37 * 38 * @param env 39 * The environment type to check support for. 40 * 41 * @return 42 * - 1 if supported 43 * - 0 if unsupported 44 * - -1 if error, with rte_errno indicating reason for error. 45 */ 46 int rte_power_check_env_supported(enum power_management_env env); 47 48 /** 49 * Set the default power management implementation. If this is not called prior 50 * to rte_power_init(), then auto-detect of the environment will take place. 51 * It is thread safe. New env can be set only in uninitialized state 52 * (thus rte_power_unset_env must be called if different env was already set). 53 * 54 * @param env 55 * env. The environment in which to initialise Power Management for. 56 * 57 * @return 58 * - 0 on success. 59 * - Negative on error. 60 */ 61 int rte_power_set_env(enum power_management_env env); 62 63 /** 64 * Unset the global environment configuration. 65 * This can only be called after all threads have completed. 66 */ 67 void rte_power_unset_env(void); 68 69 /** 70 * Get the default power management implementation. 71 * 72 * @return 73 * power_management_env The configured environment. 74 */ 75 enum power_management_env rte_power_get_env(void); 76 77 /** 78 * Initialize power management for a specific lcore. If rte_power_set_env() has 79 * not been called then an auto-detect of the environment will start and 80 * initialise the corresponding resources. 81 * 82 * @param lcore_id 83 * lcore id. 84 * 85 * @return 86 * - 0 on success. 87 * - Negative on error. 88 */ 89 int rte_power_init(unsigned int lcore_id); 90 91 /** 92 * Exit power management on a specific lcore. This will call the environment 93 * dependent exit function. 94 * 95 * @param lcore_id 96 * lcore id. 97 * 98 * @return 99 * - 0 on success. 100 * - Negative on error. 101 */ 102 int rte_power_exit(unsigned int lcore_id); 103 104 /** 105 * Get the available frequencies of a specific lcore. 106 * Function pointer definition. Review each environments 107 * specific documentation for usage. 108 * 109 * @param lcore_id 110 * lcore id. 111 * @param freqs 112 * The buffer array to save the frequencies. 113 * @param num 114 * The number of frequencies to get. 115 * 116 * @return 117 * The number of available frequencies. 118 */ 119 uint32_t rte_power_freqs(unsigned int lcore_id, uint32_t *freqs, uint32_t num); 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 */ 132 uint32_t rte_power_get_freq(unsigned int lcore_id); 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 uint32_t rte_power_set_freq(unsigned int lcore_id, uint32_t index); 151 152 /** 153 * Scale up the frequency of a specific lcore according to the available 154 * frequencies. 155 * Review each environments specific documentation for usage. 156 * 157 * @param lcore_id 158 * lcore id. 159 * 160 * @return 161 * - 1 on success with frequency changed. 162 * - 0 on success without frequency changed. 163 * - Negative on error. 164 */ 165 int rte_power_freq_up(unsigned int lcore_id); 166 167 /** 168 * Scale down the frequency of a specific lcore according to the available 169 * frequencies. 170 * Review each environments specific documentation for usage. 171 * 172 * @param lcore_id 173 * lcore id. 174 * 175 * @return 176 * - 1 on success with frequency changed. 177 * - 0 on success without frequency changed. 178 * - Negative on error. 179 */ 180 int rte_power_freq_down(unsigned int lcore_id); 181 182 /** 183 * Scale up the frequency of a specific lcore to the highest according to the 184 * available frequencies. 185 * Review each environments specific documentation for usage. 186 * 187 * @param lcore_id 188 * lcore id. 189 * 190 * @return 191 * - 1 on success with frequency changed. 192 * - 0 on success without frequency changed. 193 * - Negative on error. 194 */ 195 int rte_power_freq_max(unsigned int lcore_id); 196 197 /** 198 * Scale down the frequency of a specific lcore to the lowest according to the 199 * available frequencies. 200 * Review each environments specific documentation for usage.. 201 * 202 * @param lcore_id 203 * lcore id. 204 * 205 * @return 206 * - 1 on success with frequency changed. 207 * - 0 on success without frequency changed. 208 * - Negative on error. 209 */ 210 int rte_power_freq_min(unsigned int lcore_id); 211 212 /** 213 * Query the Turbo Boost status of a specific lcore. 214 * Review each environments specific documentation for usage.. 215 * 216 * @param lcore_id 217 * lcore id. 218 * 219 * @return 220 * - 1 turbo boost enabled. 221 * - 0 turbo boost disabled. 222 * - Negative on error. 223 */ 224 int rte_power_turbo_status(unsigned int lcore_id); 225 226 /** 227 * Enable Turbo Boost for this lcore. 228 * Review each environments specific documentation for usage.. 229 * 230 * @param lcore_id 231 * lcore id. 232 * 233 * @return 234 * - 0 on success. 235 * - Negative on error. 236 */ 237 int rte_power_freq_enable_turbo(unsigned int lcore_id); 238 239 /** 240 * Disable Turbo Boost for this lcore. 241 * Review each environments specific documentation for usage.. 242 * 243 * @param lcore_id 244 * lcore id. 245 * 246 * @return 247 * - 0 on success. 248 * - Negative on error. 249 */ 250 int rte_power_freq_disable_turbo(unsigned int lcore_id); 251 252 /** 253 * Returns power capabilities for a specific lcore. 254 * Function pointer definition. Review each environments 255 * specific documentation for usage. 256 * 257 * @param lcore_id 258 * lcore id. 259 * @param caps 260 * pointer to rte_power_core_capabilities object. 261 * 262 * @return 263 * - 0 on success. 264 * - Negative on error. 265 */ 266 int rte_power_get_capabilities(unsigned int lcore_id, 267 struct rte_power_core_capabilities *caps); 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif /* RTE_POWER_CPUFREQ_H */ 274