]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2010-2014 Intel Corporation. | |
7c673cae FG |
3 | |
4 | VM Power Management Application | |
5 | =============================== | |
6 | ||
7 | Introduction | |
8 | ------------ | |
9 | ||
10 | Applications running in Virtual Environments have an abstract view of | |
11 | the underlying hardware on the Host, in particular applications cannot see | |
12 | the binding of virtual to physical hardware. | |
13 | When looking at CPU resourcing, the pinning of Virtual CPUs(vCPUs) to | |
14 | Host Physical CPUs(pCPUS) is not apparent to an application | |
15 | and this pinning may change over time. | |
16 | Furthermore, Operating Systems on virtual machines do not have the ability | |
17 | to govern their own power policy; the Machine Specific Registers (MSRs) | |
18 | for enabling P-State transitions are not exposed to Operating Systems | |
19 | running on Virtual Machines(VMs). | |
20 | ||
21 | The Virtual Machine Power Management solution shows an example of | |
22 | how a DPDK application can indicate its processing requirements using VM local | |
11fdf7f2 | 23 | only information(vCPU/lcore, etc.) to a Host based Monitor which is responsible |
7c673cae FG |
24 | for accepting requests for frequency changes for a vCPU, translating the vCPU |
25 | to a pCPU via libvirt and affecting the change in frequency. | |
26 | ||
27 | The solution is comprised of two high-level components: | |
28 | ||
29 | #. Example Host Application | |
30 | ||
31 | Using a Command Line Interface(CLI) for VM->Host communication channel management | |
32 | allows adding channels to the Monitor, setting and querying the vCPU to pCPU pinning, | |
33 | inspecting and manually changing the frequency for each CPU. | |
34 | The CLI runs on a single lcore while the thread responsible for managing | |
35 | VM requests runs on a second lcore. | |
36 | ||
37 | VM requests arriving on a channel for frequency changes are passed | |
38 | to the librte_power ACPI cpufreq sysfs based library. | |
39 | The Host Application relies on both qemu-kvm and libvirt to function. | |
40 | ||
11fdf7f2 TL |
41 | This monitoring application is responsible for: |
42 | ||
43 | - Accepting requests from client applications: Client applications can | |
44 | request frequency changes for a vCPU, translating | |
45 | the vCPU to a pCPU via libvirt and affecting the change in frequency. | |
46 | ||
47 | - Accepting policies from client applications: Client application can | |
48 | send a policy to the host application. The | |
49 | host application will then apply the rules of the policy independent | |
50 | of the application. For example, the policy can contain time-of-day | |
51 | information for busy/quiet periods, and the host application can scale | |
52 | up/down the relevant cores when required. See the details of the guest | |
53 | application below for more information on setting the policy values. | |
54 | ||
55 | - Out-of-band monitoring of workloads via cores hardware event counters: | |
56 | The host application can manage power for an application in a virtualised | |
57 | OR non-virtualised environment by looking at the event counters of the | |
58 | cores and taking action based on the branch hit/miss ratio. See the host | |
59 | application '--core-list' command line parameter below. | |
60 | ||
7c673cae FG |
61 | #. librte_power for Virtual Machines |
62 | ||
63 | Using an alternate implementation for the librte_power API, requests for | |
64 | frequency changes are forwarded to the host monitor rather than | |
65 | the APCI cpufreq sysfs interface used on the host. | |
66 | ||
67 | The l3fwd-power application will use this implementation when deployed on a VM | |
68 | (see :doc:`l3_forward_power_man`). | |
69 | ||
70 | .. _figure_vm_power_mgr_highlevel: | |
71 | ||
72 | .. figure:: img/vm_power_mgr_highlevel.* | |
73 | ||
74 | Highlevel Solution | |
75 | ||
76 | ||
77 | Overview | |
78 | -------- | |
79 | ||
80 | VM Power Management employs qemu-kvm to provide communications channels | |
81 | between the host and VMs in the form of Virtio-Serial which appears as | |
82 | a paravirtualized serial device on a VM and can be configured to use | |
83 | various backends on the host. For this example each Virtio-Serial endpoint | |
84 | on the host is configured as AF_UNIX file socket, supporting poll/select | |
85 | and epoll for event notification. | |
86 | In this example each channel endpoint on the host is monitored via | |
87 | epoll for EPOLLIN events. | |
88 | Each channel is specified as qemu-kvm arguments or as libvirt XML for each VM, | |
89 | where each VM can have a number of channels up to a maximum of 64 per VM, | |
90 | in this example each DPDK lcore on a VM has exclusive access to a channel. | |
91 | ||
92 | To enable frequency changes from within a VM, a request via the librte_power interface | |
93 | is forwarded via Virtio-Serial to the host, each request contains the vCPU | |
94 | and power command(scale up/down/min/max). | |
95 | The API for host and guest librte_power is consistent across environments, | |
96 | with the selection of VM or Host Implementation determined at automatically | |
97 | at runtime based on the environment. | |
98 | ||
99 | Upon receiving a request, the host translates the vCPU to a pCPU via | |
100 | the libvirt API before forwarding to the host librte_power. | |
101 | ||
102 | .. _figure_vm_power_mgr_vm_request_seq: | |
103 | ||
104 | .. figure:: img/vm_power_mgr_vm_request_seq.* | |
105 | ||
106 | VM request to scale frequency | |
107 | ||
108 | ||
109 | Performance Considerations | |
110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
111 | ||
112 | While Haswell Microarchitecture allows for independent power control for each core, | |
113 | earlier Microarchtectures do not offer such fine grained control. | |
114 | When deployed on pre-Haswell platforms greater care must be taken in selecting | |
115 | which cores are assigned to a VM, for instance a core will not scale down | |
116 | until its sibling is similarly scaled. | |
117 | ||
118 | Configuration | |
119 | ------------- | |
120 | ||
121 | BIOS | |
122 | ~~~~ | |
123 | ||
124 | Enhanced Intel SpeedStep® Technology must be enabled in the platform BIOS | |
125 | if the power management feature of DPDK is to be used. | |
126 | Otherwise, the sys file folder /sys/devices/system/cpu/cpu0/cpufreq will not exist, | |
127 | and the CPU frequency-based power management cannot be used. | |
128 | Consult the relevant BIOS documentation to determine how these settings | |
129 | can be accessed. | |
130 | ||
131 | Host Operating System | |
132 | ~~~~~~~~~~~~~~~~~~~~~ | |
133 | ||
9f95a23c TL |
134 | The DPDK Power Library can use either the *acpi_cpufreq* or *intel_pstate* |
135 | kernel driver for the management of core frequencies. In many cases | |
136 | the *intel_pstate* driver is the default Power Management environment. | |
137 | ||
138 | Should the *acpi-cpufreq* driver be required, the *intel_pstate* module must | |
139 | be disabled, and *apci_cpufreq* module loaded in its place. | |
140 | ||
141 | To disable *intel_pstate* driver, add the following to the grub Linux | |
142 | command line: | |
7c673cae FG |
143 | |
144 | .. code-block:: console | |
145 | ||
146 | intel_pstate=disable | |
147 | ||
148 | Upon rebooting, load the *acpi_cpufreq* module: | |
149 | ||
150 | .. code-block:: console | |
151 | ||
152 | modprobe acpi_cpufreq | |
153 | ||
154 | Hypervisor Channel Configuration | |
155 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
156 | ||
157 | Virtio-Serial channels are configured via libvirt XML: | |
158 | ||
159 | ||
160 | .. code-block:: xml | |
161 | ||
162 | <name>{vm_name}</name> | |
163 | <controller type='virtio-serial' index='0'> | |
164 | <address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x0'/> | |
165 | </controller> | |
166 | <channel type='unix'> | |
167 | <source mode='bind' path='/tmp/powermonitor/{vm_name}.{channel_num}'/> | |
168 | <target type='virtio' name='virtio.serial.port.poweragent.{vm_channel_num}'/> | |
169 | <address type='virtio-serial' controller='0' bus='0' port='{N}'/> | |
170 | </channel> | |
171 | ||
172 | ||
173 | Where a single controller of type *virtio-serial* is created and up to 32 channels | |
174 | can be associated with a single controller and multiple controllers can be specified. | |
175 | The convention is to use the name of the VM in the host path *{vm_name}* and | |
176 | to increment *{channel_num}* for each channel, likewise the port value *{N}* | |
177 | must be incremented for each channel. | |
178 | ||
179 | Each channel on the host will appear in *path*, the directory */tmp/powermonitor/* | |
180 | must first be created and given qemu permissions | |
181 | ||
182 | .. code-block:: console | |
183 | ||
184 | mkdir /tmp/powermonitor/ | |
185 | chown qemu:qemu /tmp/powermonitor | |
186 | ||
187 | Note that files and directories within /tmp are generally removed upon | |
188 | rebooting the host and the above steps may need to be carried out after each reboot. | |
189 | ||
190 | The serial device as it appears on a VM is configured with the *target* element attribute *name* | |
191 | and must be in the form of *virtio.serial.port.poweragent.{vm_channel_num}*, | |
192 | where *vm_channel_num* is typically the lcore channel to be used in DPDK VM applications. | |
193 | ||
194 | Each channel on a VM will be present at */dev/virtio-ports/virtio.serial.port.poweragent.{vm_channel_num}* | |
195 | ||
196 | Compiling and Running the Host Application | |
197 | ------------------------------------------ | |
198 | ||
199 | Compiling | |
200 | ~~~~~~~~~ | |
201 | ||
11fdf7f2 TL |
202 | For information on compiling DPDK and the sample applications |
203 | see :doc:`compiling`. | |
204 | ||
205 | The application is located in the ``vm_power_manager`` sub-directory. | |
206 | ||
9f95a23c | 207 | To build just the ``vm_power_manager`` application using ``make``: |
11fdf7f2 TL |
208 | |
209 | .. code-block:: console | |
210 | ||
211 | export RTE_SDK=/path/to/rte_sdk | |
212 | export RTE_TARGET=build | |
213 | cd ${RTE_SDK}/examples/vm_power_manager/ | |
214 | make | |
7c673cae | 215 | |
9f95a23c TL |
216 | The resulting binary will be ${RTE_SDK}/build/examples/vm_power_manager |
217 | ||
218 | To build just the ``vm_power_manager`` application using ``meson/ninja``: | |
219 | ||
220 | .. code-block:: console | |
221 | ||
222 | export RTE_SDK=/path/to/rte_sdk | |
223 | cd ${RTE_SDK} | |
224 | meson build | |
225 | cd build | |
226 | ninja | |
227 | meson configure -Dexamples=vm_power_manager | |
228 | ninja | |
229 | ||
230 | The resulting binary will be ${RTE_SDK}/build/examples/dpdk-vm_power_manager | |
231 | ||
7c673cae FG |
232 | Running |
233 | ~~~~~~~ | |
234 | ||
235 | The application does not have any specific command line options other than *EAL*: | |
236 | ||
237 | .. code-block:: console | |
238 | ||
239 | ./build/vm_power_mgr [EAL options] | |
240 | ||
241 | The application requires exactly two cores to run, one core is dedicated to the CLI, | |
242 | while the other is dedicated to the channel endpoint monitor, for example to run | |
243 | on cores 0 & 1 on a system with 4 memory channels: | |
244 | ||
245 | .. code-block:: console | |
246 | ||
11fdf7f2 | 247 | ./build/vm_power_mgr -l 0-1 -n 4 |
7c673cae FG |
248 | |
249 | After successful initialization the user is presented with VM Power Manager CLI: | |
250 | ||
251 | .. code-block:: console | |
252 | ||
253 | vm_power> | |
254 | ||
255 | Virtual Machines can now be added to the VM Power Manager: | |
256 | ||
257 | .. code-block:: console | |
258 | ||
259 | vm_power> add_vm {vm_name} | |
260 | ||
261 | When a {vm_name} is specified with the *add_vm* command a lookup is performed | |
262 | with libvirt to ensure that the VM exists, {vm_name} is used as an unique identifier | |
263 | to associate channels with a particular VM and for executing operations on a VM within the CLI. | |
264 | VMs do not have to be running in order to add them. | |
265 | ||
266 | A number of commands can be issued via the CLI in relation to VMs: | |
267 | ||
268 | Remove a Virtual Machine identified by {vm_name} from the VM Power Manager. | |
269 | ||
270 | .. code-block:: console | |
271 | ||
272 | rm_vm {vm_name} | |
273 | ||
274 | Add communication channels for the specified VM, the virtio channels must be enabled | |
275 | in the VM configuration(qemu/libvirt) and the associated VM must be active. | |
276 | {list} is a comma-separated list of channel numbers to add, using the keyword 'all' | |
277 | will attempt to add all channels for the VM: | |
278 | ||
279 | .. code-block:: console | |
280 | ||
281 | add_channels {vm_name} {list}|all | |
282 | ||
283 | Enable or disable the communication channels in {list}(comma-separated) | |
284 | for the specified VM, alternatively list can be replaced with keyword 'all'. | |
285 | Disabled channels will still receive packets on the host, however the commands | |
286 | they specify will be ignored. Set status to 'enabled' to begin processing requests again: | |
287 | ||
288 | .. code-block:: console | |
289 | ||
290 | set_channel_status {vm_name} {list}|all enabled|disabled | |
291 | ||
292 | Print to the CLI the information on the specified VM, the information | |
293 | lists the number of vCPUS, the pinning to pCPU(s) as a bit mask, along with | |
294 | any communication channels associated with each VM, along with the status of each channel: | |
295 | ||
296 | .. code-block:: console | |
297 | ||
298 | show_vm {vm_name} | |
299 | ||
300 | Set the binding of Virtual CPU on VM with name {vm_name} to the Physical CPU mask: | |
301 | ||
302 | .. code-block:: console | |
303 | ||
304 | set_pcpu_mask {vm_name} {vcpu} {pcpu} | |
305 | ||
306 | Set the binding of Virtual CPU on VM to the Physical CPU: | |
307 | ||
308 | .. code-block:: console | |
309 | ||
310 | set_pcpu {vm_name} {vcpu} {pcpu} | |
311 | ||
312 | Manual control and inspection can also be carried in relation CPU frequency scaling: | |
313 | ||
314 | Get the current frequency for each core specified in the mask: | |
315 | ||
316 | .. code-block:: console | |
317 | ||
318 | show_cpu_freq_mask {mask} | |
319 | ||
320 | Set the current frequency for the cores specified in {core_mask} by scaling each up/down/min/max: | |
321 | ||
322 | .. code-block:: console | |
323 | ||
324 | set_cpu_freq {core_mask} up|down|min|max | |
325 | ||
326 | Get the current frequency for the specified core: | |
327 | ||
328 | .. code-block:: console | |
329 | ||
330 | show_cpu_freq {core_num} | |
331 | ||
332 | Set the current frequency for the specified core by scaling up/down/min/max: | |
333 | ||
334 | .. code-block:: console | |
335 | ||
336 | set_cpu_freq {core_num} up|down|min|max | |
337 | ||
11fdf7f2 TL |
338 | There are also some command line parameters for enabling the out-of-band |
339 | monitoring of branch ratio on cores doing busy polling via PMDs. | |
340 | ||
341 | .. code-block:: console | |
342 | ||
343 | --core-list {list of cores} | |
344 | ||
345 | When this parameter is used, the list of cores specified will monitor the ratio | |
346 | between branch hits and branch misses. A tightly polling PMD thread will have a | |
9f95a23c | 347 | very low branch ratio, so the core frequency will be scaled down to the minimum |
11fdf7f2 TL |
348 | allowed value. When packets are received, the code path will alter, causing the |
349 | branch ratio to increase. When the ratio goes above the ratio threshold, the | |
350 | core frequency will be scaled up to the maximum allowed value. | |
351 | ||
352 | .. code-block:: console | |
353 | ||
354 | --branch-ratio {ratio} | |
355 | ||
356 | The branch ratio is a floating point number that specifies the threshold at which | |
357 | to scale up or down for the given workload. The default branch ratio is 0.01, | |
358 | and will need to be adjusted for different workloads. | |
359 | ||
360 | ||
9f95a23c TL |
361 | |
362 | JSON API | |
363 | ~~~~~~~~ | |
364 | ||
365 | In addition to the command line interface for host command and a virtio-serial | |
366 | interface for VM power policies, there is also a JSON interface through which | |
367 | power commands and policies can be sent. This functionality adds a dependency | |
368 | on the Jansson library, and the Jansson development package must be installed | |
369 | on the system before the JSON parsing functionality is included in the app. | |
370 | This is achieved by: | |
371 | ||
372 | .. code-block:: javascript | |
373 | ||
374 | apt-get install libjansson-dev | |
375 | ||
376 | The command and package name may be different depending on your operating | |
377 | system. It's worth noting that the app will successfully build without this | |
378 | package present, but a warning is shown during compilation, and the JSON | |
379 | parsing functionality will not be present in the app. | |
380 | ||
381 | Sending a command or policy to the power manager application is achieved by | |
382 | simply opening a fifo file, writing a JSON string to that fifo, and closing | |
383 | the file. | |
384 | ||
385 | The fifo is at /tmp/powermonitor/fifo | |
386 | ||
387 | The JSON string can be a policy or instruction, and takes the following | |
388 | format: | |
389 | ||
390 | .. code-block:: javascript | |
391 | ||
392 | {"packet_type": { | |
393 | "pair_1": value, | |
394 | "pair_2": value | |
395 | }} | |
396 | ||
397 | The 'packet_type' header can contain one of two values, depending on | |
398 | whether a policy or power command is being sent. The two possible values are | |
399 | "policy" and "instruction", and the expected name-value pairs is different | |
400 | depending on which type is being sent. | |
401 | ||
402 | The pairs are the format of standard JSON name-value pairs. The value type | |
403 | varies between the different name/value pairs, and may be integers, strings, | |
404 | arrays, etc. Examples of policies follow later in this document. The allowed | |
405 | names and value types are as follows: | |
406 | ||
407 | ||
408 | :Pair Name: "name" | |
409 | :Description: Name of the VM or Host. Allows the parser to associate the | |
410 | policy with the relevant VM or Host OS. | |
411 | :Type: string | |
412 | :Values: any valid string | |
413 | :Required: yes | |
414 | :Example: | |
415 | ||
416 | .. code-block:: javascript | |
417 | ||
418 | "name", "ubuntu2" | |
419 | ||
420 | ||
421 | :Pair Name: "command" | |
422 | :Description: The type of packet we're sending to the power manager. We can be | |
423 | creating or destroying a policy, or sending a direct command to adjust | |
424 | the frequency of a core, similar to the command line interface. | |
425 | :Type: string | |
426 | :Values: | |
427 | ||
428 | :CREATE: used when creating a new policy, | |
429 | :DESTROY: used when removing a policy, | |
430 | :POWER: used when sending an immediate command, max, min, etc. | |
431 | :Required: yes | |
432 | :Example: | |
433 | ||
434 | .. code-block:: javascript | |
435 | ||
436 | "command", "CREATE" | |
437 | ||
438 | ||
439 | :Pair Name: "policy_type" | |
440 | :Description: Type of policy to apply. Please see vm_power_manager documentation | |
441 | for more information on the types of policies that may be used. | |
442 | :Type: string | |
443 | :Values: | |
444 | ||
445 | :TIME: Time-of-day policy. Frequencies of the relevant cores are | |
446 | scaled up/down depending on busy and quiet hours. | |
447 | :TRAFFIC: This policy takes statistics from the NIC and scales up | |
448 | and down accordingly. | |
449 | :WORKLOAD: This policy looks at how heavily loaded the cores are, | |
450 | and scales up and down accordingly. | |
451 | :BRANCH_RATIO: This out-of-band policy can look at the ratio between | |
452 | branch hits and misses on a core, and is useful for detecting | |
453 | how much packet processing a core is doing. | |
454 | :Required: only for CREATE/DESTROY command | |
455 | :Example: | |
456 | ||
457 | .. code-block:: javascript | |
458 | ||
459 | "policy_type", "TIME" | |
460 | ||
461 | :Pair Name: "busy_hours" | |
462 | :Description: The hours of the day in which we scale up the cores for busy | |
463 | times. | |
464 | :Type: array of integers | |
465 | :Values: array with list of hour numbers, (0-23) | |
466 | :Required: only for TIME policy | |
467 | :Example: | |
468 | ||
469 | .. code-block:: javascript | |
470 | ||
471 | "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ] | |
472 | ||
473 | :Pair Name: "quiet_hours" | |
474 | :Description: The hours of the day in which we scale down the cores for quiet | |
475 | times. | |
476 | :Type: array of integers | |
477 | :Values: array with list of hour numbers, (0-23) | |
478 | :Required: only for TIME policy | |
479 | :Example: | |
480 | ||
481 | .. code-block:: javascript | |
482 | ||
483 | "quiet_hours":[ 2, 3, 4, 5, 6 ] | |
484 | ||
485 | :Pair Name: "avg_packet_thresh" | |
486 | :Description: Threshold below which the frequency will be set to min for | |
487 | the TRAFFIC policy. If the traffic rate is above this and below max, the | |
488 | frequency will be set to medium. | |
489 | :Type: integer | |
490 | :Values: The number of packets below which the TRAFFIC policy applies the | |
491 | minimum frequency, or medium frequency if between avg and max thresholds. | |
492 | :Required: only for TRAFFIC policy | |
493 | :Example: | |
494 | ||
495 | .. code-block:: javascript | |
496 | ||
497 | "avg_packet_thresh": 100000 | |
498 | ||
499 | :Pair Name: "max_packet_thresh" | |
500 | :Description: Threshold above which the frequency will be set to max for | |
501 | the TRAFFIC policy | |
502 | :Type: integer | |
503 | :Values: The number of packets per interval above which the TRAFFIC policy | |
504 | applies the maximum frequency | |
505 | :Required: only for TRAFFIC policy | |
506 | :Example: | |
507 | ||
508 | .. code-block:: javascript | |
509 | ||
510 | "max_packet_thresh": 500000 | |
511 | ||
512 | :Pair Name: "core_list" | |
513 | :Description: The cores to which to apply the policy. | |
514 | :Type: array of integers | |
515 | :Values: array with list of virtual CPUs. | |
516 | :Required: only policy CREATE/DESTROY | |
517 | :Example: | |
518 | ||
519 | .. code-block:: javascript | |
520 | ||
521 | "core_list":[ 10, 11 ] | |
522 | ||
523 | :Pair Name: "workload" | |
524 | :Description: When our policy is of type WORKLOAD, we need to specify how | |
525 | heavy our workload is. | |
526 | :Type: string | |
527 | :Values: | |
528 | ||
529 | :HIGH: For cores running workloads that require high frequencies | |
530 | :MEDIUM: For cores running workloads that require medium frequencies | |
531 | :LOW: For cores running workloads that require low frequencies | |
532 | :Required: only for WORKLOAD policy types | |
533 | :Example: | |
534 | ||
535 | .. code-block:: javascript | |
536 | ||
537 | "workload", "MEDIUM" | |
538 | ||
539 | :Pair Name: "mac_list" | |
540 | :Description: When our policy is of type TRAFFIC, we need to specify the | |
541 | MAC addresses that the host needs to monitor | |
542 | :Type: string | |
543 | :Values: array with a list of mac address strings. | |
544 | :Required: only for TRAFFIC policy types | |
545 | :Example: | |
546 | ||
547 | .. code-block:: javascript | |
548 | ||
549 | "mac_list":[ "de:ad:be:ef:01:01", "de:ad:be:ef:01:02" ] | |
550 | ||
551 | :Pair Name: "unit" | |
552 | :Description: the type of power operation to apply in the command | |
553 | :Type: string | |
554 | :Values: | |
555 | ||
556 | :SCALE_MAX: Scale frequency of this core to maximum | |
557 | :SCALE_MIN: Scale frequency of this core to minimum | |
558 | :SCALE_UP: Scale up frequency of this core | |
559 | :SCALE_DOWN: Scale down frequency of this core | |
560 | :ENABLE_TURBO: Enable Turbo Boost for this core | |
561 | :DISABLE_TURBO: Disable Turbo Boost for this core | |
562 | :Required: only for POWER instruction | |
563 | :Example: | |
564 | ||
565 | .. code-block:: javascript | |
566 | ||
567 | "unit", "SCALE_MAX" | |
568 | ||
569 | :Pair Name: "resource_id" | |
570 | :Description: The core to which to apply the power command. | |
571 | :Type: integer | |
572 | :Values: valid core id for VM or host OS. | |
573 | :Required: only POWER instruction | |
574 | :Example: | |
575 | ||
576 | .. code-block:: javascript | |
577 | ||
578 | "resource_id": 10 | |
579 | ||
580 | JSON API Examples | |
581 | ~~~~~~~~~~~~~~~~~ | |
582 | ||
583 | Profile create example: | |
584 | ||
585 | .. code-block:: javascript | |
586 | ||
587 | {"policy": { | |
588 | "name": "ubuntu", | |
589 | "command": "create", | |
590 | "policy_type": "TIME", | |
591 | "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ], | |
592 | "quiet_hours":[ 2, 3, 4, 5, 6 ], | |
593 | "core_list":[ 11 ] | |
594 | }} | |
595 | ||
596 | Profile destroy example: | |
597 | ||
598 | .. code-block:: javascript | |
599 | ||
600 | {"policy": { | |
601 | "name": "ubuntu", | |
602 | "command": "destroy", | |
603 | }} | |
604 | ||
605 | Power command example: | |
606 | ||
607 | .. code-block:: javascript | |
608 | ||
609 | {"instruction": { | |
610 | "name": "ubuntu", | |
611 | "command": "power", | |
612 | "unit": "SCALE_MAX", | |
613 | "resource_id": 10 | |
614 | }} | |
615 | ||
616 | To send a JSON string to the Power Manager application, simply paste the | |
617 | example JSON string into a text file and cat it into the fifo: | |
618 | ||
619 | .. code-block:: console | |
620 | ||
621 | cat file.json >/tmp/powermonitor/fifo | |
622 | ||
623 | The console of the Power Manager application should indicate the command that | |
624 | was just received via the fifo. | |
625 | ||
7c673cae FG |
626 | Compiling and Running the Guest Applications |
627 | -------------------------------------------- | |
628 | ||
11fdf7f2 | 629 | l3fwd-power is one sample application that can be used with vm_power_manager. |
7c673cae FG |
630 | |
631 | A guest CLI is also provided for validating the setup. | |
632 | ||
633 | For both l3fwd-power and guest CLI, the channels for the VM must be monitored by the | |
11fdf7f2 TL |
634 | host application using the *add_channels* command on the host. This typically uses |
635 | the following commands in the host application: | |
636 | ||
637 | .. code-block:: console | |
638 | ||
639 | vm_power> add_vm vmname | |
640 | vm_power> add_channels vmname all | |
641 | vm_power> set_channel_status vmname all enabled | |
642 | vm_power> show_vm vmname | |
643 | ||
7c673cae FG |
644 | |
645 | Compiling | |
646 | ~~~~~~~~~ | |
647 | ||
11fdf7f2 TL |
648 | For information on compiling DPDK and the sample applications |
649 | see :doc:`compiling`. | |
650 | ||
651 | For compiling and running l3fwd-power, see :doc:`l3_forward_power_man`. | |
652 | ||
653 | The application is located in the ``guest_cli`` sub-directory under ``vm_power_manager``. | |
654 | ||
9f95a23c | 655 | To build just the ``guest_vm_power_manager`` application using ``make``: |
11fdf7f2 TL |
656 | |
657 | .. code-block:: console | |
658 | ||
659 | export RTE_SDK=/path/to/rte_sdk | |
660 | export RTE_TARGET=build | |
661 | cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/ | |
662 | make | |
7c673cae | 663 | |
9f95a23c TL |
664 | The resulting binary will be ${RTE_SDK}/build/examples/guest_cli |
665 | ||
666 | .. Note:: | |
667 | This sample application conditionally links in the Jansson JSON | |
668 | library, so if you are using a multilib or cross compile environment you | |
669 | may need to set the ``PKG_CONFIG_LIBDIR`` environmental variable to point to | |
670 | the relevant pkgconfig folder so that the correct library is linked in. | |
671 | ||
672 | For example, if you are building for a 32-bit target, you could find the | |
673 | correct directory using the following ``find`` command: | |
674 | ||
675 | .. code-block:: console | |
676 | ||
677 | # find /usr -type d -name pkgconfig | |
678 | /usr/lib/i386-linux-gnu/pkgconfig | |
679 | /usr/lib/x86_64-linux-gnu/pkgconfig | |
680 | ||
681 | Then use: | |
682 | ||
683 | .. code-block:: console | |
684 | ||
685 | export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig | |
686 | ||
687 | You then use the make command as normal, which should find the 32-bit | |
688 | version of the library, if it installed. If not, the application will | |
689 | be built without the JSON interface functionality. | |
690 | ||
691 | To build just the ``vm_power_manager`` application using ``meson/ninja``: | |
692 | ||
693 | .. code-block:: console | |
694 | ||
695 | export RTE_SDK=/path/to/rte_sdk | |
696 | cd ${RTE_SDK} | |
697 | meson build | |
698 | cd build | |
699 | ninja | |
700 | meson configure -Dexamples=vm_power_manager/guest_cli | |
701 | ninja | |
702 | ||
703 | The resulting binary will be ${RTE_SDK}/build/examples/guest_cli | |
704 | ||
7c673cae FG |
705 | Running |
706 | ~~~~~~~ | |
707 | ||
11fdf7f2 | 708 | The standard *EAL* command line parameters are required: |
7c673cae FG |
709 | |
710 | .. code-block:: console | |
711 | ||
11fdf7f2 | 712 | ./build/guest_vm_power_mgr [EAL options] -- [guest options] |
7c673cae | 713 | |
11fdf7f2 TL |
714 | The guest example uses a channel for each lcore enabled. For example, |
715 | to run on cores 0,1,2,3: | |
7c673cae FG |
716 | |
717 | .. code-block:: console | |
718 | ||
11fdf7f2 TL |
719 | ./build/guest_vm_power_mgr -l 0-3 |
720 | ||
721 | Optionally, there is a list of command line parameter should the user wish to send a power | |
722 | policy down to the host application. These parameters are as follows: | |
723 | ||
724 | .. code-block:: console | |
725 | ||
726 | --vm-name {name of guest vm} | |
727 | ||
728 | This parameter allows the user to change the Virtual Machine name passed down to the | |
729 | host application via the power policy. The default is "ubuntu2" | |
730 | ||
731 | .. code-block:: console | |
732 | ||
733 | --vcpu-list {list vm cores} | |
734 | ||
735 | A comma-separated list of cores in the VM that the user wants the host application to | |
736 | monitor. The list of cores in any vm starts at zero, and these are mapped to the | |
737 | physical cores by the host application once the policy is passed down. | |
9f95a23c | 738 | Valid syntax includes individual cores '2,3,4', or a range of cores '2-4', or a |
11fdf7f2 TL |
739 | combination of both '1,3,5-7' |
740 | ||
741 | .. code-block:: console | |
742 | ||
743 | --busy-hours {list of busy hours} | |
744 | ||
745 | A comma-separated list of hours within which to set the core frequency to maximum. | |
9f95a23c | 746 | Valid syntax includes individual hours '2,3,4', or a range of hours '2-4', or a |
11fdf7f2 TL |
747 | combination of both '1,3,5-7'. Valid hours are 0 to 23. |
748 | ||
749 | .. code-block:: console | |
750 | ||
751 | --quiet-hours {list of quiet hours} | |
752 | ||
753 | A comma-separated list of hours within which to set the core frequency to minimum. | |
9f95a23c | 754 | Valid syntax includes individual hours '2,3,4', or a range of hours '2-4', or a |
11fdf7f2 TL |
755 | combination of both '1,3,5-7'. Valid hours are 0 to 23. |
756 | ||
757 | .. code-block:: console | |
758 | ||
759 | --policy {policy type} | |
760 | ||
761 | The type of policy. This can be one of the following values: | |
762 | TRAFFIC - based on incoming traffic rates on the NIC. | |
763 | TIME - busy/quiet hours policy. | |
764 | BRANCH_RATIO - uses branch ratio counters to determine core busyness. | |
765 | Not all parameters are needed for all policy types. For example, BRANCH_RATIO | |
766 | only needs the vcpu-list parameter, not any of the hours. | |
7c673cae FG |
767 | |
768 | ||
769 | After successful initialization the user is presented with VM Power Manager Guest CLI: | |
770 | ||
771 | .. code-block:: console | |
772 | ||
773 | vm_power(guest)> | |
774 | ||
775 | To change the frequency of a lcore, use the set_cpu_freq command. | |
776 | Where {core_num} is the lcore and channel to change frequency by scaling up/down/min/max. | |
777 | ||
778 | .. code-block:: console | |
779 | ||
780 | set_cpu_freq {core_num} up|down|min|max | |
11fdf7f2 TL |
781 | |
782 | To start the application and configure the power policy, and send it to the host: | |
783 | ||
784 | .. code-block:: console | |
785 | ||
786 | ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4 | |
787 | ||
788 | Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command | |
789 | will send the policy to the host: | |
790 | ||
791 | .. code-block:: console | |
792 | ||
793 | send_policy now | |
794 | ||
795 | Once the policy is sent to the host, the host application takes over the power monitoring | |
796 | of the specified cores in the policy. | |
797 |