1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
7 The DPDK Power Management feature allows users space applications to save power
8 by dynamically adjusting CPU frequency or entering into different C-States.
10 * Adjusting the CPU frequency dynamically according to the utilization of RX queue.
12 * Entering into different deeper C-States according to the adaptive algorithms to speculate
13 brief periods of time suspending the application if no packets are received.
15 The interfaces for adjusting the operating CPU frequency are in the power management library.
16 C-State control is implemented in applications according to the different use cases.
21 The Linux kernel provides a cpufreq module for CPU frequency scaling for each lcore.
22 For example, for cpuX, /sys/devices/system/cpu/cpuX/cpufreq/ has the following sys files for frequency scaling:
34 * cpuinfo_transition_latency
38 * scaling_available_frequencies
40 * scaling_available_governors
54 In the DPDK, scaling_governor is configured in user space.
55 Then, a user space application can prompt the kernel by writing scaling_setspeed to adjust the CPU frequency
56 according to the strategies defined by the user space application.
58 Core-load Throttling through C-States
59 -------------------------------------
61 Core state can be altered by speculative sleeps whenever the specified lcore has nothing to do.
62 In the DPDK, if no packet is received after polling,
63 speculative sleeps can be triggered according the strategies defined by the user space application.
68 Individual cores can be allowed to enter a Turbo Boost state on a per-core
69 basis. This is achieved by enabling Turbo Boost Technology in the BIOS, then
70 looping through the relevant cores and enabling/disabling Turbo Boost on each
73 Use of Power Library in a Hyper-Threaded Environment
74 ----------------------------------------------------
76 In the case where the power library is in use on a system with Hyper-Threading enabled,
77 the frequency on the physical core is set to the highest frequency of the Hyper-Thread siblings.
78 So even though an application may request a scale down, the core frequency will
79 remain at the highest frequency until all Hyper-Threads on that core request a scale down.
81 API Overview of the Power Library
82 ---------------------------------
84 The main methods exported by power library are for CPU frequency scaling and include the following:
86 * **Freq up**: Prompt the kernel to scale up the frequency of the specific lcore.
88 * **Freq down**: Prompt the kernel to scale down the frequency of the specific lcore.
90 * **Freq max**: Prompt the kernel to scale up the frequency of the specific lcore to the maximum.
92 * **Freq min**: Prompt the kernel to scale down the frequency of the specific lcore to the minimum.
94 * **Get available freqs**: Read the available frequencies of the specific lcore from the sys file.
96 * **Freq get**: Get the current frequency of the specific lcore.
98 * **Freq set**: Prompt the kernel to set the frequency for the specific lcore.
100 * **Enable turbo**: Prompt the kernel to enable Turbo Boost for the specific lcore.
102 * **Disable turbo**: Prompt the kernel to disable Turbo Boost for the specific lcore.
107 The power management mechanism is used to save power when performing L3 forwarding.
116 For packet processing workloads such as DPDK polling is continuous.
117 This means CPU cores always show 100% busy independent of how much work
118 those cores are doing. It is critical to accurately determine how busy
119 a core is hugely important for the following reasons:
121 * No indication of overload conditions
122 * User does not know how much real load is on a system, resulting
123 in wasted energy as no power management is utilized
125 Compared to the original l3fwd-power design, instead of going to sleep
126 after detecting an empty poll, the new mechanism just lowers the core frequency.
127 As a result, the application does not stop polling the device, which leads
128 to improved handling of bursts of traffic.
130 When the system become busy, the empty poll mechanism can also increase the core
131 frequency (including turbo) to do best effort for intensive traffic. This gives
132 us more flexible and balanced traffic awareness over the standard l3fwd-power
138 The proposed solution focuses on how many times empty polls are executed.
139 The less the number of empty polls, means current core is busy with processing
140 workload, therefore, the higher frequency is needed. The high empty poll number
141 indicates the current core not doing any real work therefore, we can lower the
142 frequency to safe power.
144 In the current implementation, each core has 1 empty-poll counter which assume
145 1 core is dedicated to 1 queue. This will need to be expanded in the future to
146 support multiple queues per core.
148 Power state definition:
149 ^^^^^^^^^^^^^^^^^^^^^^^
151 * LOW: Not currently used, reserved for future use.
153 * MED: the frequency is used to process modest traffic workload.
155 * HIGH: the frequency is used to process busy traffic workload.
157 There are two phases to establish the power management system:
158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
159 * Training phase. This phase is used to measure the optimal frequency
160 change thresholds for a given system. The thresholds will differ from
161 system to system due to differences in processor micro-architecture,
162 cache and device configurations.
163 In this phase, the user must ensure that no traffic can enter the
164 system so that counts can be measured for empty polls at low, medium
165 and high frequencies. Each frequency is measured for two seconds.
166 Once the training phase is complete, the threshold numbers are
167 displayed, and normal mode resumes, and traffic can be allowed into
168 the system. These threshold number can be used on the command line
169 when starting the application in normal mode to avoid re-training
172 * Normal phase. Every 10ms the run-time counters are compared
173 to the supplied threshold values, and the decision will be made
174 whether to move to a different power state (by adjusting the
177 API Overview for Empty Poll Power Management
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179 * **State Init**: initialize the power management system.
181 * **State Free**: free the resource hold by power management system.
183 * **Update Empty Poll Counter**: update the empty poll counter.
185 * **Update Valid Poll Counter**: update the valid poll counter.
187 * **Set the Frequency Index**: update the power state/frequency mapping.
189 * **Detect empty poll state change**: empty poll state change detection algorithm then take action.
193 The mechanism can applied to any device which is based on polling. e.g. NIC, FPGA.
195 Ethernet PMD Power Management API
196 ---------------------------------
201 Existing power management mechanisms require developers to change application
202 design or change code to make use of it. The PMD power management API provides a
203 convenient alternative by utilizing Ethernet PMD RX callbacks, and triggering
204 power saving whenever empty poll count reaches a certain number.
207 This power saving scheme will put the CPU into optimized power state and
208 monitor the Ethernet PMD RX descriptor address, waking the CPU up whenever
209 there's new traffic. Support for this scheme may not be available on all
210 platforms, and further limitations may apply (see below).
213 This power saving scheme will avoid busy polling by either entering
214 power-optimized sleep state with ``rte_power_pause()`` function, or, if it's
215 not supported by the underlying platform, use ``rte_pause()``.
218 This power saving scheme will use ``librte_power`` library functionality to
219 scale the core frequency up/down depending on traffic volume.
220 The reaction time of the frequency scaling mode is longer
221 than the pause and monitor mode.
223 The "monitor" mode is only supported in the following configurations and scenarios:
225 * On Linux* x86_64, `rte_power_monitor()` requires WAITPKG instruction set being
226 supported by the CPU, while `rte_power_monitor_multi()` requires WAITPKG and
227 RTM instruction sets being supported by the CPU. RTM instruction set may also
228 require booting the Linux with `tsx=on` command line parameter. Please refer
229 to your platform documentation for further information.
231 * If ``rte_cpu_get_intrinsics_support()`` function indicates that
232 ``rte_power_monitor_multi()`` function is supported by the platform, then
233 monitoring multiple Ethernet Rx queues for traffic will be supported.
235 * If ``rte_cpu_get_intrinsics_support()`` function indicates that only
236 ``rte_power_monitor()`` is supported by the platform, then monitoring will be
237 limited to a mapping of 1 core 1 queue (thus, each Rx queue will have to be
238 monitored from a different lcore).
240 * If ``rte_cpu_get_intrinsics_support()`` function indicates that neither of the
241 two monitoring functions are supported, then monitor mode will not be supported.
243 * Not all Ethernet drivers support monitoring, even if the underlying
244 platform may support the necessary CPU instructions. Please refer to
245 :doc:`../nics/overview` for more information.
248 API Overview for Ethernet PMD Power Management
249 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
251 * **Queue Enable**: Enable specific power scheme for certain queue/port/core.
253 * **Queue Disable**: Disable power scheme for certain queue/port/core.
255 * **Get Emptypoll Max**: Get the configured number of empty polls to wait before
256 entering sleep state.
258 * **Set Emptypoll Max**: Set the number of empty polls to wait before entering
261 * **Get Pause Duration**: Get the configured duration (microseconds) to be used
262 in the Pause callback.
264 * **Set Pause Duration**: Set the duration of the pause (microseconds) used in
265 the Pause mode callback.
270 * The :doc:`../sample_app_ug/l3_forward_power_man`
271 chapter in the :doc:`../sample_app_ug/index` section.
273 * The :doc:`../sample_app_ug/vm_power_management`
274 chapter in the :doc:`../sample_app_ug/index` section.
276 * The :doc:`../nics/overview` chapter in the :doc:`../nics/index` section