lib/power/power_pstate_cpufreq.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Intel Corporation
   3  */
   4
   5 #ifndef _POWER_PSTATE_CPUFREQ_H
   6 #define _POWER_PSTATE_CPUFREQ_H
   7
   8 /**
   9  * @file
  10  * RTE Power Management via Intel Pstate driver
  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.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /**
  24  * Check if pstate power management is supported.
  25  *
  26  * @return
  27  *   - 1 if supported
  28  *   - 0 if unsupported
  29  *   - -1 if error, with rte_errno indicating reason for error.
  30  */
  31 int power_pstate_cpufreq_check_supported(void);
  32
  33 /**
  34  * Initialize power management for a specific lcore. It will check and set the
  35  * governor to performance for the lcore, get the available frequencies, and
  36  * prepare to set new lcore frequency.
  37  *
  38  * @param lcore_id
  39  *  lcore id.
  40  *
  41  * @return
  42  *  - 0 on success.
  43  *  - Negative on error.
  44  */
  45 int power_pstate_cpufreq_init(unsigned int lcore_id);
  46
  47 /**
  48  * Exit power management on a specific lcore. It will set the governor to which
  49  * is before initialized.
  50  *
  51  * @param lcore_id
  52  *  lcore id.
  53  *
  54  * @return
  55  *  - 0 on success.
  56  *  - Negative on error.
  57  */
  58 int power_pstate_cpufreq_exit(unsigned int lcore_id);
  59
  60 /**
  61  * Get the available frequencies of a specific lcore. The return value will be
  62  * the minimal one of the total number of available frequencies and the number
  63  * of buffer. The index of available frequencies used in other interfaces
  64  * should be in the range of 0 to this return value.
  65  * It should be protected outside of this function for threadsafe.
  66  *
  67  * @param lcore_id
  68  *  lcore id.
  69  * @param freqs
  70  *  The buffer array to save the frequencies.
  71  * @param num
  72  *  The number of frequencies to get.
  73  *
  74  * @return
  75  *  The number of available frequencies.
  76  */
  77 uint32_t power_pstate_cpufreq_freqs(unsigned int lcore_id, uint32_t *freqs,
  78                 uint32_t num);
  79
  80 /**
  81  * Return the current index of available frequencies of a specific lcore.
  82  * It should be protected outside of this function for threadsafe.
  83  *
  84  * @param lcore_id
  85  *  lcore id.
  86  *
  87  * @return
  88  *  The current index of available frequencies.
  89  *  If error, it will return 'RTE_POWER_INVALID_FREQ_INDEX = (~0)'.
  90  */
  91 uint32_t power_pstate_cpufreq_get_freq(unsigned int lcore_id);
  92
  93 /**
  94  * Set the new frequency for a specific lcore by indicating the index of
  95  * available frequencies.
  96  * It should be protected outside of this function for threadsafe.
  97  *
  98  * @param lcore_id
  99  *  lcore id.
 100  * @param index
 101  *  The index of available frequencies.
 102  *
 103  * @return
 104  *  - 1 on success with frequency changed.
 105  *  - 0 on success without frequency changed.
 106  *  - Negative on error.
 107  */
 108 int power_pstate_cpufreq_set_freq(unsigned int lcore_id, uint32_t index);
 109
 110 /**
 111  * Scale up the frequency of a specific lcore according to the available
 112  * frequencies.
 113  * It should be protected outside of this function for threadsafe.
 114  *
 115  * @param lcore_id
 116  *  lcore id.
 117  *
 118  * @return
 119  *  - 1 on success with frequency changed.
 120  *  - 0 on success without frequency changed.
 121  *  - Negative on error.
 122  */
 123 int power_pstate_cpufreq_freq_up(unsigned int lcore_id);
 124
 125 /**
 126  * Scale down the frequency of a specific lcore according to the available
 127  * frequencies.
 128  * It should be protected outside of this function for threadsafe.
 129  *
 130  * @param lcore_id
 131  *  lcore id.
 132  *
 133  * @return
 134  *  - 1 on success with frequency changed.
 135  *  - 0 on success without frequency changed.
 136  *  - Negative on error.
 137  */
 138 int power_pstate_cpufreq_freq_down(unsigned int lcore_id);
 139
 140 /**
 141  * Scale up the frequency of a specific lcore to the highest according to the
 142  * available frequencies.
 143  * It should be protected outside of this function for threadsafe.
 144  *
 145  * @param lcore_id
 146  *  lcore id.
 147  *
 148  * @return
 149  *  - 1 on success with frequency changed.
 150  *  - 0 on success without frequency changed.
 151  *  - Negative on error.
 152  */
 153 int power_pstate_cpufreq_freq_max(unsigned int lcore_id);
 154
 155 /**
 156  * Scale down the frequency of a specific lcore to the lowest according to the
 157  * available frequencies.
 158  * It should be protected outside of this function for threadsafe.
 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  */
 168 int power_pstate_cpufreq_freq_min(unsigned int lcore_id);
 169
 170 /**
 171  * Get the turbo status of a specific lcore.
 172  * It should be protected outside of this function for threadsafe.
 173  *
 174  * @param lcore_id
 175  *  lcore id.
 176  *
 177  * @return
 178  *  - 1 Turbo Boost is enabled on this lcore.
 179  *  - 0 Turbo Boost is disabled on this lcore.
 180  *  - Negative on error.
 181  */
 182 int power_pstate_turbo_status(unsigned int lcore_id);
 183
 184 /**
 185  * Enable Turbo Boost on a specific lcore.
 186  * It should be protected outside of this function for threadsafe.
 187  *
 188  * @param lcore_id
 189  *  lcore id.
 190  *
 191  * @return
 192  *  - 0 Turbo Boost is enabled successfully on this lcore.
 193  *  - Negative on error.
 194  */
 195 int power_pstate_enable_turbo(unsigned int lcore_id);
 196
 197 /**
 198  * Disable Turbo Boost on a specific lcore.
 199  * It should be protected outside of this function for threadsafe.
 200  *
 201  * @param lcore_id
 202  *  lcore id.
 203  *
 204  * @return
 205  *  - 0 Turbo Boost disabled successfully on this lcore.
 206  *  - Negative on error.
 207  */
 208 int power_pstate_disable_turbo(unsigned int lcore_id);
 209
 210 /**
 211  * Returns power capabilities for a specific lcore.
 212  *
 213  * @param lcore_id
 214  *  lcore id.
 215  * @param caps
 216  *  pointer to rte_power_core_capabilities object.
 217  *
 218  * @return
 219  *  - 0 on success.
 220  *  - Negative on error.
 221  */
 222 int power_pstate_get_capabilities(unsigned int lcore_id,
 223                 struct rte_power_core_capabilities *caps);
 224 #ifdef __cplusplus
 225 }
 226 #endif
 227
 228 #endif