devtools: standardize script arguments
[dpdk.git] / lib / librte_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