lib/librte_power/rte_power.h

   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