lib/power/power_cppc_cpufreq.h

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