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