1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Virtual Machine Power Management Application 5============================================ 6 7Applications running in virtual environments have an abstract view of 8the underlying hardware on the host. Specifically, applications cannot 9see the binding of virtual components to physical hardware. When looking 10at CPU resourcing, the pinning of Virtual CPUs (vCPUs) to Physical CPUs 11(pCPUs) on the host is not apparent to an application and this pinning 12may change over time. In addition, operating systems on Virtual Machines 13(VMs) do not have the ability to govern their own power policy. The 14Machine Specific Registers (MSRs) for enabling P-state transitions are 15not exposed to the operating systems running on the VMs. 16 17The solution demonstrated in this sample application shows an example of 18how a DPDK application can indicate its processing requirements using 19VM-local only information (vCPU/lcore, and so on) to a host resident VM 20Power Manager. The VM Power Manager is responsible for: 21 22- **Accepting requests for frequency changes for a vCPU** 23- **Translating the vCPU to a pCPU using libvirt** 24- **Performing the change in frequency** 25 26This application demonstrates the following features: 27 28- **The handling of VM application requests to change frequency.** 29 VM applications can request frequency changes for a vCPU. The VM 30 Power Management Application uses libvirt to translate that 31 virtual CPU (vCPU) request to a physical CPU (pCPU) request and 32 performs the frequency change. 33 34- **The acceptance of power management policies from VM applications.** 35 A VM application can send a policy to the host application. The 36 policy contains rules that define the power management behaviour 37 of the VM. The host application then applies the rules of the 38 policy independent of the VM application. For example, the 39 policy can contain time-of-day information for busy/quiet 40 periods, and the host application can scale up/down the relevant 41 cores when required. See :ref:`sending_policy` for information on 42 setting policy values. 43 44- **Out-of-band monitoring of workloads using core hardware event counters.** 45 The host application can manage power for an application by looking 46 at the event counters of the cores and taking action based on the 47 branch miss/hit ratio. See :ref:`enabling_out_of_band`. 48 49 **Note**: This functionality also applies in non-virtualised environments. 50 51In addition to the ``librte_power`` library used on the host, the 52application uses a special version of ``librte_power`` on each VM, which 53directs frequency changes and policies to the host monitor rather than 54the APCI ``cpufreq`` ``sysfs`` interface used on the host in non-virtualised 55environments. 56 57.. _figure_vm_power_mgr_highlevel: 58 59.. figure:: img/vm_power_mgr_highlevel.* 60 61 Highlevel Solution 62 63In the above diagram, the DPDK Applications are shown running in 64virtual machines, and the VM Power Monitor application is shown running 65in the host. 66 67**DPDK VM Application** 68 69- Reuse ``librte_power`` interface, but uses an implementation that 70 forwards frequency requests to the host using a ``virtio-serial`` channel 71- Each lcore has exclusive access to a single channel 72- Sample application reuses ``l3fwd_power`` 73- A CLI for changing frequency from within a VM is also included 74 75**VM Power Monitor** 76 77- Accepts VM commands over ``virtio-serial`` endpoints, monitored 78 using ``epoll`` 79- Commands include the virtual core to be modified, using ``libvirt`` to get 80 the physical core mapping 81- Uses ``librte_power`` to affect frequency changes using Linux userspace 82 power governor (``acpi_cpufreq`` OR ``intel_pstate`` driver) 83- CLI: For adding VM channels to monitor, inspecting and changing channel 84 state, manually altering CPU frequency. Also allows for the changings 85 of vCPU to pCPU pinning 86 87Sample Application Architecture Overview 88---------------------------------------- 89 90The VM power management solution employs ``qemu-kvm`` to provide 91communications channels between the host and VMs in the form of a 92``virtio-serial`` connection that appears as a para-virtualised serial 93device on a VM and can be configured to use various backends on the 94host. For this example, the configuration of each ``virtio-serial`` endpoint 95on the host as an ``AF_UNIX`` file socket, supporting poll/select and 96``epoll`` for event notification. In this example, each channel endpoint on 97the host is monitored for ``EPOLLIN`` events using ``epoll``. Each channel 98is specified as ``qemu-kvm`` arguments or as ``libvirt`` XML for each VM, 99where each VM can have several channels up to a maximum of 64 per VM. In this 100example, each DPDK lcore on a VM has exclusive access to a channel. 101 102To enable frequency changes from within a VM, the VM forwards a 103``librte_power`` request over the ``virtio-serial`` channel to the host. Each 104request contains the vCPU and power command (scale up/down/min/max). The 105API for the host ``librte_power`` and guest ``librte_power`` is consistent 106across environments, with the selection of VM or host implementation 107determined automatically at runtime based on the environment. On 108receiving a request, the host translates the vCPU to a pCPU using the 109libvirt API before forwarding it to the host ``librte_power``. 110 111 112.. _figure_vm_power_mgr_vm_request_seq: 113 114.. figure:: img/vm_power_mgr_vm_request_seq.* 115 116In addition to the ability to send power management requests to the 117host, a VM can send a power management policy to the host. In some 118cases, using a power management policy is a preferred option because it 119can eliminate possible latency issues that can occur when sending power 120management requests. Once the VM sends the policy to the host, the VM no 121longer needs to worry about power management, because the host now 122manages the power for the VM based on the policy. The policy can specify 123power behavior that is based on incoming traffic rates or time-of-day 124power adjustment (busy/quiet hour power adjustment for example). See 125:ref:`sending_policy` for more information. 126 127One method of power management is to sense how busy a core is when 128processing packets and adjusting power accordingly. One technique for 129doing this is to monitor the ratio of the branch miss to branch hits 130counters and scale the core power accordingly. This technique is based 131on the premise that when a core is not processing packets, the ratio of 132branch misses to branch hits is very low, but when the core is 133processing packets, it is measurably higher. The implementation of this 134capability is as a policy of type ``BRANCH_RATIO``. 135See :ref:`sending_policy` for more information on using the 136BRANCH_RATIO policy option. 137 138A JSON interface enables the specification of power management requests 139and policies in JSON format. The JSON interfaces provide a more 140convenient and more easily interpreted interface for the specification 141of requests and policies. See :ref:`power_man_requests` for more information. 142 143Performance Considerations 144~~~~~~~~~~~~~~~~~~~~~~~~~~ 145 146While the Haswell microarchitecture allows for independent power control 147for each core, earlier microarchitectures do not offer such fine-grained 148control. When deploying on pre-Haswell platforms, greater care must be 149taken when selecting which cores are assigned to a VM, for example, a 150core does not scale down in frequency until all of its siblings are 151similarly scaled down. 152 153Configuration 154------------- 155 156BIOS 157~~~~ 158 159To use the power management features of the DPDK, you must enable 160Enhanced Intel SpeedStep® Technology in the platform BIOS. Otherwise, 161the ``sys`` file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` does not 162exist, and you cannot use CPU frequency-based power management. Refer to the 163relevant BIOS documentation to determine how to access these settings. 164 165Host Operating System 166~~~~~~~~~~~~~~~~~~~~~ 167 168The DPDK Power Management library can use either the ``acpi_cpufreq`` or 169the ``intel_pstate`` kernel driver for the management of core frequencies. In 170many cases, the ``intel_pstate`` driver is the default power management 171environment. 172 173Should the ``acpi-cpufreq driver`` be required, the ``intel_pstate`` 174module must be disabled, and the ``acpi-cpufreq`` module loaded in its place. 175 176To disable the ``intel_pstate`` driver, add the following to the ``grub`` 177Linux command line: 178 179 ``intel_pstate=disable`` 180 181On reboot, load the ``acpi_cpufreq`` module: 182 183 ``modprobe acpi_cpufreq`` 184 185Hypervisor Channel Configuration 186~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 187 188Configure ``virtio-serial`` channels using ``libvirt`` XML. 189The XML structure is as follows: 190 191.. code-block:: XML 192 193 <name>{vm_name}</name> 194 <controller type='virtio-serial' index='0'> 195 <address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x0'/> 196 </controller> 197 <channel type='unix'> 198 <source mode='bind' path='/tmp/powermonitor/{vm_name}.{channel_num}'/> 199 <target type='virtio' name='virtio.serial.port.poweragent.{vm_channel_num}'/> 200 <address type='virtio-serial' controller='0' bus='0' port='{N}'/> 201 </channel> 202 203Where a single controller of type ``virtio-serial`` is created, up to 32 204channels can be associated with a single controller, and multiple 205controllers can be specified. The convention is to use the name of the 206VM in the host path ``{vm_name}`` and to increment ``{channel_num}`` for each 207channel. Likewise, the port value ``{N}`` must be incremented for each 208channel. 209 210On the host, for each channel to appear in the path, ensure the creation 211of the ``/tmp/powermonitor/`` directory and the assignment of ``qemu`` 212permissions: 213 214.. code-block:: console 215 216 mkdir /tmp/powermonitor/ 217 chown qemu:qemu /tmp/powermonitor 218 219Note that files and directories in ``/tmp`` are generally removed when 220rebooting the host and you may need to perform the previous steps after 221each reboot. 222 223The serial device as it appears on a VM is configured with the target 224element attribute name and must be in the form: 225``virtio.serial.port.poweragent.{vm_channel_num}``, where 226``vm_channel_num`` is typically the lcore channel to be used in 227DPDK VM applications. 228 229Each channel on a VM is present at: 230 231``/dev/virtio-ports/virtio.serial.port.poweragent.{vm_channel_num}`` 232 233Compiling and Running the Host Application 234------------------------------------------ 235 236Compiling the Host Application 237~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 238 239For information on compiling the DPDK and sample applications, see 240see :doc:`compiling`. 241 242The application is located in the ``vm_power_manager`` subdirectory. 243 244To build just the ``vm_power_manager`` application using ``make``: 245 246.. code-block:: console 247 248 export RTE_SDK=/path/to/rte_sdk 249 export RTE_TARGET=build 250 cd ${RTE_SDK}/examples/vm_power_manager/ 251 make 252 253The resulting binary is ``${RTE_SDK}/build/examples/vm_power_manager``. 254 255To build just the ``vm_power_manager`` application using ``meson``/``ninja``: 256 257.. code-block:: console 258 259 export RTE_SDK=/path/to/rte_sdk 260 cd ${RTE_SDK} 261 meson build 262 cd build 263 ninja 264 meson configure -Dexamples=vm_power_manager 265 ninja 266 267The resulting binary is ``${RTE_SDK}/build/examples/dpdk-vm_power_manager``. 268 269Running the Host Application 270~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 271 272The application does not have any specific command line options other 273than the EAL options: 274 275.. code-block:: console 276 277 ./build/vm_power_mgr [EAL options] 278 279The application requires exactly two cores to run. One core for the CLI 280and the other for the channel endpoint monitor. For example, to run on 281cores 0 and 1 on a system with four memory channels, issue the command: 282 283.. code-block:: console 284 285 ./build/vm_power_mgr -l 0-1 -n 4 286 287After successful initialization, the VM Power Manager CLI prompt appears: 288 289.. code-block:: console 290 291 vm_power> 292 293Now, it is possible to add virtual machines to the VM Power Manager: 294 295.. code-block:: console 296 297 vm_power> add_vm {vm_name} 298 299When a ``{vm_name}`` is specified with the ``add_vm`` command, a lookup is 300performed with ``libvirt`` to ensure that the VM exists. ``{vm_name}`` is a 301unique identifier to associate channels with a particular VM and for 302executing operations on a VM within the CLI. VMs do not have to be 303running to add them. 304 305It is possible to issue several commands from the CLI to manage VMs. 306 307Remove the virtual machine identified by ``{vm_name}`` from the VM Power 308Manager using the command: 309 310.. code-block:: console 311 312 rm_vm {vm_name} 313 314Add communication channels for the specified VM using the following 315command. The ``virtio`` channels must be enabled in the VM configuration 316(``qemu/libvirt``) and the associated VM must be active. ``{list}`` is a 317comma-separated list of channel numbers to add. Specifying the keyword 318``all`` attempts to add all channels for the VM: 319 320.. code-block:: console 321 322 set_pcpu {vm_name} {vcpu} {pcpu} 323 324 Enable query of physical core information from a VM: 325 326.. code-block:: console 327 328 set_query {vm_name} enable|disable 329 330Manual control and inspection can also be carried in relation CPU frequency scaling: 331 332 Get the current frequency for each core specified in the mask: 333 334.. code-block:: console 335 336 show_cpu_freq_mask {mask} 337 338 Set the current frequency for the cores specified in {core_mask} by scaling each up/down/min/max: 339 340.. code-block:: console 341 342 add_channels {vm_name} {list}|all 343 344Enable or disable the communication channels in ``{list}`` (comma-separated) 345for the specified VM. Alternatively, replace ``list`` with the keyword 346``all``. Disabled channels receive packets on the host. However, the commands 347they specify are ignored. Set the status to enabled to begin processing 348requests again: 349 350.. code-block:: console 351 352 set_channel_status {vm_name} {list}|all enabled|disabled 353 354Print to the CLI information on the specified VM. The information lists 355the number of vCPUs, the pinning to pCPU(s) as a bit mask, along with 356any communication channels associated with each VM, and the status of 357each channel: 358 359.. code-block:: console 360 361 show_vm {vm_name} 362 363Set the binding of a virtual CPU on a VM with name ``{vm_name}`` to the 364physical CPU mask: 365 366.. code-block:: console 367 368 set_pcpu_mask {vm_name} {vcpu} {pcpu} 369 370Set the binding of the virtual CPU on the VM to the physical CPU: 371 372 .. code-block:: console 373 374 set_pcpu {vm_name} {vcpu} {pcpu} 375 376It is also possible to perform manual control and inspection in relation 377to CPU frequency scaling. 378 379Get the current frequency for each core specified in the mask: 380 381.. code-block:: console 382 383 show_cpu_freq_mask {mask} 384 385Set the current frequency for the cores specified in ``{core_mask}`` by 386scaling each up/down/min/max: 387 388.. code-block:: console 389 390 set_cpu_freq {core_mask} up|down|min|max 391 392Get the current frequency for the specified core: 393 394.. code-block:: console 395 396 show_cpu_freq {core_num} 397 398Set the current frequency for the specified core by scaling up/down/min/max: 399 400.. code-block:: console 401 402 set_cpu_freq {core_num} up|down|min|max 403 404.. _enabling_out_of_band: 405 406Command Line Options for Enabling Out-of-band Branch Ratio Monitoring 407~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 408 409There are a couple of command line parameters for enabling the out-of-band 410monitoring of branch ratios on cores doing busy polling using PMDs as 411described in the following table. 412 413Table 1 – Command Line Options for Enabling Out-of-band Monitoring of 414Branch Ratios 415 416=============================== ============================================== 417**Command Line Option** **Description** 418=============================== ============================================== 419``--core-list {list of cores}`` | Specify the list of cores to monitor the ratio of branch misses 420 | to branch hits. A tightly-polling PMD thread has a very low 421 | branch ratio, therefore the core frequency scales down to the 422 | minimum allowed value. On receiving packets, the code path changes, 423 | causing the branch ratio to increase. When the ratio goes above 424 | the ratio threshold, the core frequency scales up to the maximum 425 | allowed value. 426``--branch-ratio {ratio}`` | Specify a floating-point number that identifies the threshold at which 427 | to scale up or down for the given workload. The default branch ratio 428 | is 0.01 and needs adjustment for different workloads. 429=============================== ============================================== 430 431 432 433Compiling and Running the Guest Applications 434-------------------------------------------- 435 436It is possible to use the ``l3fwd-power`` application (for example) with the 437``vm_power_manager``. 438 439The distribution also provides a guest CLI for validating the setup. 440 441For both ``l3fwd-power`` and the guest CLI, the host application must use 442the ``add_channels`` command to monitor the channels for the VM. To do this, 443issue the following commands in the host application: 444 445.. code-block:: console 446 447 vm_power> add_vm vmname 448 vm_power> add_channels vmname all 449 vm_power> set_channel_status vmname all enabled 450 vm_power> show_vm vmname 451 452Compiling the Guest Application 453~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 454 455For information on compiling DPDK and the sample applications in general, 456see :doc:`compiling`. 457 458For compiling and running the ``l3fwd-power`` sample application, see 459:doc:`l3_forward_power_man`. 460 461The application is in the ``guest_cli`` subdirectory under ``vm_power_manager``. 462 463To build just the ``guest_vm_power_manager`` application using ``make``, issue 464the following commands: 465 466.. code-block:: console 467 468 export RTE_SDK=/path/to/rte_sdk 469 export RTE_TARGET=build 470 cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/ 471 make 472 473The resulting binary is ``${RTE_SDK}/build/examples/guest_cli``. 474 475**Note**: This sample application conditionally links in the Jansson JSON 476library. Consequently, if you are using a multilib or cross-compile 477environment, you may need to set the ``PKG_CONFIG_LIBDIR`` environmental 478variable to point to the relevant ``pkgconfig`` folder so that the correct 479library is linked in. 480 481For example, if you are building for a 32-bit target, you could find the 482correct directory using the following find command: 483 484.. code-block:: console 485 486 # find /usr -type d -name pkgconfig 487 /usr/lib/i386-linux-gnu/pkgconfig 488 /usr/lib/x86_64-linux-gnu/pkgconfig 489 490Then use: 491 492.. code-block:: console 493 494 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig 495 496You then use the ``make`` command as normal, which should find the 32-bit 497version of the library, if it installed. If not, the application builds 498without the JSON interface functionality. 499 500To build just the ``vm_power_manager`` application using ``meson``/``ninja``: 501 502.. code-block:: console 503 504 export RTE_SDK=/path/to/rte_sdk 505 cd ${RTE_SDK} 506 meson build 507 cd build 508 ninja 509 meson configure -Dexamples=vm_power_manager/guest_cli 510 ninja 511 512The resulting binary is ``${RTE_SDK}/build/examples/guest_cli``. 513 514Running the Guest Application 515~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 516 517The standard EAL command line parameters are necessary: 518 519.. code-block:: console 520 521 ./build/vm_power_mgr [EAL options] -- [guest options] 522 523The guest example uses a channel for each lcore enabled. For example, to 524run on cores 0, 1, 2 and 3: 525 526.. code-block:: console 527 528 ./build/guest_vm_power_mgr -l 0-3 529 530.. _sending_policy: 531 532Command Line Options Available When Sending a Policy to the Host 533~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 534 535Optionally, there are several command line options for a user who needs 536to send a power policy to the host application. The following table 537describes these options. 538 539Table 1 – Command Line Options Available When Sending a Policy to the Host 540 541======================================= ====================================== 542**Command Line Option** **Description** 543======================================= ====================================== 544``--vm-name {name of guest vm}`` | Allows the user to change the virtual machine name passed 545 | down to the host application using the power policy. The 546 | default is ubuntu2. 547``--vcpu-list {list vm cores}`` | A comma-separated list of cores in the VM that the user 548 | wants the host application to monitor. The list of cores 549 | in any vm starts at zero, and the host application maps 550 | these to the physical cores once the policy passes down 551 | to the host. Valid syntax includes individual cores 552 | 2,3,4, a range of cores 2-4, or a combination of both 553 | 1,3,5-7. 554``--busy-hours {list of busy hours}`` | A comma-separated list of hours in which to set the core 555 | frequency to the maximum. Valid syntax includes 556 | individual hours 2,3,4, a range of hours 2-4, or a 557 | combination of both 1,3,5-7. Valid hour values are 0 to 23. 558``--quiet-hours {list of quiet hours}`` | A comma-separated list of hours in which to set the core 559 | frequency to minimum. Valid syntax includes individual 560 | hours 2,3,4, a range of hours 2-4, or a combination of 561 | both 1,3,5-7. Valid hour values are 0 to 23. 562``--policy {policy type}`` | The type of policy. This can be one of the following values: 563 564 - | TRAFFIC Based on incoming traffic rates on the NIC. 565 566 - | TIME - Uses a busy/quiet hours policy. 567 568 - | BRANCH_RATIO - Uses branch ratio counters to determine 569 | core busyness. 570 571 - | WORKLOAD - Sets the frequency to low, medium or high 572 | based on the received policy setting. 573 574 | **Note**: Not all policy types need all parameters. For 575 | example, BRANCH_RATIO only needs the vcpu-list 576 | parameter. 577======================================= ====================================== 578 579After successful initialization, the VM Power Manager Guest CLI prompt 580appears: 581 582.. code-block:: console 583 584 vm_power(guest)> 585 586To change the frequency of an lcore, use a ``set_cpu_freq`` command similar 587to the following: 588 589.. code-block:: console 590 591 set_cpu_freq {core_num} up|down|min|max 592 593where, ``{core_num}`` is the lcore and channel to change frequency by 594scaling up/down/min/max. 595 596To start an application, configure the power policy, and send it to the 597host, use a command like the following: 598 599.. code-block:: console 600 601 ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4 602 603Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command 604will send the policy to the host: 605 606.. code-block:: console 607 608 send_policy now 609 610Once the policy is sent to the host, the host application takes over the power monitoring 611of the specified cores in the policy. 612 613.. _power_man_requests: 614 615JSON Interface for Power Management Requests and Policies 616--------------------------------------------------------- 617 618In addition to the command line interface for the host command, and a 619``virtio-serial`` interface for VM power policies, there is also a JSON 620interface through which power commands and policies can be sent. 621 622**Note**: This functionality adds a dependency on the Jansson library. 623Install the Jansson development package on the system to avail of the 624JSON parsing functionality in the app. Issue the ``apt-get install 625libjansson-dev`` command to install the development package. The command 626and package name may be different depending on your operating system. It 627is worth noting that the app builds successfully if this package is not 628present, but a warning displays during compilation, and the JSON parsing 629functionality is not present in the app. 630 631Send a request or policy to the VM Power Manager by simply opening a 632fifo file at ``/tmp/powermonitor/fifo``, writing a JSON string to that file, 633and closing the file. 634 635The JSON string can be a power management request or a policy, and takes 636the following format: 637 638.. code-block:: javascript 639 640 {"packet_type": { 641 "pair_1": value, 642 "pair_2": value 643 }} 644 645The ``packet_type`` header can contain one of two values, depending on 646whether a power management request or policy is being sent. The two 647possible values are ``instruction`` and ``policy`` and the expected name-value 648pairs are different depending on which type is sent. 649 650The pairs are in the format of standard JSON name-value pairs. The value 651type varies between the different name-value pairs, and may be integers, 652strings, arrays, and so on. See :ref:`json_interface_ex` 653for examples of policies and instructions and 654:ref:`json_name_value_pair` for the supported names and value types. 655 656.. _json_interface_ex: 657 658JSON Interface Examples 659~~~~~~~~~~~~~~~~~~~~~~~ 660 661The following is an example JSON string that creates a time-profile 662policy. 663 664.. code-block:: JSON 665 666 {"policy": { 667 "name": "ubuntu", 668 "command": "create", 669 "policy_type": "TIME", 670 "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ], 671 "quiet_hours":[ 2, 3, 4, 5, 6 ], 672 "core_list":[ 11 ] 673 }} 674 675The following is an example JSON string that removes the named policy. 676 677.. code-block:: JSON 678 679 {"policy": { 680 "name": "ubuntu", 681 "command": "destroy", 682 }} 683 684The following is an example JSON string for a power management request. 685 686.. code-block:: JSON 687 688 {"instruction": { 689 "name": "ubuntu", 690 "command": "power", 691 "unit": "SCALE_MAX", 692 "resource_id": 10 693 }} 694 695To query the available frequences of an lcore, use the query_cpu_freq command. 696Where {core_num} is the lcore to query. 697Before using this command, please enable responses via the set_query command on the host. 698 699.. code-block:: console 700 701 query_cpu_freq {core_num}|all 702 703To query the capabilities of an lcore, use the query_cpu_caps command. 704Where {core_num} is the lcore to query. 705Before using this command, please enable responses via the set_query command on the host. 706 707.. code-block:: console 708 709 query_cpu_caps {core_num}|all 710 711To start the application and configure the power policy, and send it to the host: 712 713.. code-block:: console 714 715 ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4 716 717Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command 718will send the policy to the host: 719 720.. code-block:: console 721 722 send_policy now 723 724Once the policy is sent to the host, the host application takes over the power monitoring 725of the specified cores in the policy. 726 727.. _json_name_value_pair: 728 729JSON Name-value Pairs 730~~~~~~~~~~~~~~~~~~~~~ 731 732The following are the name-value pairs supported by the JSON interface: 733 734- `avg_packet_thresh`_ 735- `busy_hours`_ 736- `command`_ 737- `core_list`_ 738- `mac_list`_ 739- `max_packet_thresh`_ 740- `name`_ 741- `policy_type`_ 742- `quiet_hours`_ 743- `resource_id`_ 744- `unit`_ 745- `workload`_ 746 747avg_packet_thresh 748^^^^^^^^^^^^^^^^^ 749 750================== =========================================================== 751 **Pair Name:** "avg_packet_thresh" 752================== =========================================================== 753 **Description:** | The threshold below which the frequency is set to the minimum value for the 754 | TRAFFIC policy. If the traffic rate is above this value and below the 755 | maximum value, the frequency is set to medium. 756 **Type:** integer 757 **Values:** | The number of packets below which the TRAFFIC policy applies the minimum 758 | frequency, or the medium frequency if between the average and maximum 759 | thresholds. 760 **Required:** Yes 761 **Example:** ``"avg_packet_thresh": 100000`` 762================== =========================================================== 763 764busy_hours 765^^^^^^^^^^ 766 767================== =========================================================== 768 **Pair Name:** "busy_hours" 769================== =========================================================== 770 **Description:** The hours of the day in which we scale up the cores for busy times. 771 **Type:** array of integers 772 **Values:** An array with a list of hour values (0-23). 773 **Required:** For the TIME policy only. 774 **Example:** ``"busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ]`` 775================== =========================================================== 776 777command 778^^^^^^^ 779 780================== =========================================================== 781 **Pair Name:** "command" 782================== =========================================================== 783 **Description:** | The type of packet to send to the VM Power Manager. It is possible to create 784 | or destroy a policy or send a direct command to adjust the frequency of a core, 785 | as is possible on the command line interface. 786 **Type:** | string 787 **Values:** Possible values are: 788 789 - CREATE: Create a new policy. 790 - DESTROY: Remove an existing policy. 791 - POWER: Send an immediate command, max, min, and so on. 792 793 **Required:** Yes 794 **Example:** ``"command": "CREATE"`` 795================== =========================================================== 796 797core_list 798^^^^^^^^^ 799 800================== =========================================================== 801 **Pair Name:** "core_list" 802================== =========================================================== 803 **Description:** The cores to which to apply a policy. 804 **Type:** array of integers 805 **Values:** An array with a list of virtual CPUs. 806 **Required:** For CREATE/DESTROY policy requests only. 807 **Example:** ``"core_list":[ 10, 11 ]`` 808================== =========================================================== 809 810mac_list 811^^^^^^^^ 812 813================== =========================================================== 814 **Pair Name:** "mac_list" 815================== =========================================================== 816 **Description:** | When the policy is of type TRAFFIC, it is necessary to specify the MAC addresses 817 | that the host must monitor. 818 **Type:** | array of strings 819 **Values:** An array with a list of mac address strings. 820 **Required:** For TRAFFIC policy types only. 821 **Example:** ``"mac_list":[ "de:ad:be:ef:01:01","de:ad:be:ef:01:02" ]`` 822================== =========================================================== 823 824 825max_packet_thresh 826^^^^^^^^^^^^^^^^^ 827 828================== =========================================================== 829 **Pair Name:** "max_packet_thresh" 830================== =========================================================== 831 **Description:** | In a policy of type TRAFFIC, the threshold value above which the frequency is set 832 | to a maximum. 833 **Type:** | integer 834 **Values:** | The number of packets per interval above which the TRAFFIC 835 | policy applies the maximum frequency. 836 **Required:** For the TRAFFIC policy only. 837 **Example:** ``"max_packet_thresh": 500000`` 838================== =========================================================== 839 840name 841^^^^ 842 843================== =========================================================== 844 **Pair Name:** "name" 845================== =========================================================== 846 **Description:** | The name of the VM or host. Allows the parser to associate the policy with the 847 | relevant VM or host OS. 848 **Type:** | string 849 **Values:** Any valid string. 850 **Required:** Yes 851 **Example:** ``"name": "ubuntu2"`` 852================== =========================================================== 853 854policy_type 855^^^^^^^^^^^ 856 857================== =========================================================== 858 **Pair Name:** "policy_type" 859================== =========================================================== 860 **Description:** | The type of policy to apply. See the ``--policy`` option description for more 861 | information. 862 **Type:** string 863 **Values:** Possible values are: 864 865 - | TIME: Time-of-day policy. Scale the frequencies of the relevant cores up/down 866 | depending on busy and quiet hours. 867 - | TRAFFIC: Use statistics from the NIC and scale up and down accordingly. 868 - | WORKLOAD: Determine how heavily loaded the cores are and scale up and down 869 | accordingly. 870 - | BRANCH_RATIO: An out-of-band policy that looks at the ratio between branch 871 | hits and misses on a core and uses that information to determine how much 872 | packet processing a core is doing. 873 874 **Required:** For ``CREATE`` and ``DESTROY`` policy requests only. 875 **Example:** ``"policy_type": "TIME"`` 876================== =========================================================== 877 878quiet_hours 879^^^^^^^^^^^ 880 881================== =========================================================== 882 **Pair Name:** "quiet_hours" 883================== =========================================================== 884 **Description:** | The hours of the day to scale down the cores for quiet times. 885 **Type:** array of integers 886 **Values:** | An array with a list of hour numbers with values in the range 0 to 23. 887 **Required:** For the TIME policy only. 888 **Example:** ``"quiet_hours":[ 2, 3, 4, 5, 6 ]`` 889================== =========================================================== 890 891resource_id 892^^^^^^^^^^^ 893 894================== =========================================================== 895 **Pair Name:** "resource_id" 896================== =========================================================== 897 **Description:** The core to which to apply a power command. 898 **Type:** integer 899 **Values:** A valid core ID for the VM or host OS. 900 **Required:** For the ``POWER`` instruction only. 901 **Example:** ``"resource_id": 10`` 902================== =========================================================== 903 904unit 905^^^^ 906 907================== =========================================================== 908 **Pair Name:** "unit" 909================== =========================================================== 910 **Description:** The type of power operation to apply in the command. 911 **Type:** string 912 **Values:** - SCALE_MAX: Scale the frequency of this core to the maximum. 913 - SCALE_MIN: Scale the frequency of this core to the minimum. 914 - SCALE_UP: Scale up the frequency of this core. 915 - SCALE_DOWN: Scale down the frequency of this core. 916 - ENABLE_TURBO: Enable Intel® Turbo Boost Technology for this core. 917 - DISABLE_TURBO: Disable Intel® Turbo Boost Technology for this core. 918 **Required:** For the ``POWER`` instruction only. 919 **Example:** ``"unit": "SCALE_MAX"`` 920================== =========================================================== 921 922workload 923^^^^^^^^ 924 925================== =========================================================== 926 **Pair Name:** "workload" 927================== =========================================================== 928 **Description:** In a policy of type WORKLOAD, it is necessary to specify 929 how heavy the workload is. 930 **Type:** string 931 **Values:** - HIGH: Scale the frequency of this core to maximum. 932 - MEDIUM: Scale the frequency of this core to minimum. 933 - LOW: Scale up the frequency of this core. 934 **Required:** For the ``WORKLOAD`` policy only. 935 **Example:** ``"workload": "MEDIUM"`` 936================== =========================================================== 937 938