1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
4 Virtual Machine Power Management Application
5 ============================================
7 Applications running in virtual environments have an abstract view of
8 the underlying hardware on the host. Specifically, applications cannot
9 see the binding of virtual components to physical hardware. When looking
10 at 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
12 may change over time. In addition, operating systems on Virtual Machines
13 (VMs) do not have the ability to govern their own power policy. The
14 Machine Specific Registers (MSRs) for enabling P-state transitions are
15 not exposed to the operating systems running on the VMs.
17 The solution demonstrated in this sample application shows an example of
18 how a DPDK application can indicate its processing requirements using
19 VM-local only information (vCPU/lcore, and so on) to a host resident VM
20 Power Manager. The VM Power Manager is responsible for:
22 - **Accepting requests for frequency changes for a vCPU**
23 - **Translating the vCPU to a pCPU using libvirt**
24 - **Performing the change in frequency**
26 This application demonstrates the following features:
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.
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.
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`.
49 **Note**: This functionality also applies in non-virtualised environments.
51 In addition to the ``librte_power`` library used on the host, the
52 application uses a special version of ``librte_power`` on each VM, which
53 directs frequency changes and policies to the host monitor rather than
54 the APCI ``cpufreq`` ``sysfs`` interface used on the host in non-virtualised
57 .. _figure_vm_power_mgr_highlevel:
59 .. figure:: img/vm_power_mgr_highlevel.*
63 In the above diagram, the DPDK Applications are shown running in
64 virtual machines, and the VM Power Monitor application is shown running
67 **DPDK VM Application**
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
77 - Accepts VM commands over ``virtio-serial`` endpoints, monitored
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
87 Sample Application Architecture Overview
88 ----------------------------------------
90 The VM power management solution employs ``qemu-kvm`` to provide
91 communications channels between the host and VMs in the form of a
92 ``virtio-serial`` connection that appears as a para-virtualised serial
93 device on a VM and can be configured to use various backends on the
94 host. For this example, the configuration of each ``virtio-serial`` endpoint
95 on the host as an ``AF_UNIX`` file socket, supporting poll/select and
96 ``epoll`` for event notification. In this example, each channel endpoint on
97 the host is monitored for ``EPOLLIN`` events using ``epoll``. Each channel
98 is specified as ``qemu-kvm`` arguments or as ``libvirt`` XML for each VM,
99 where each VM can have several channels up to a maximum of 64 per VM. In this
100 example, each DPDK lcore on a VM has exclusive access to a channel.
102 To enable frequency changes from within a VM, the VM forwards a
103 ``librte_power`` request over the ``virtio-serial`` channel to the host. Each
104 request contains the vCPU and power command (scale up/down/min/max). The
105 API for the host ``librte_power`` and guest ``librte_power`` is consistent
106 across environments, with the selection of VM or host implementation
107 determined automatically at runtime based on the environment. On
108 receiving a request, the host translates the vCPU to a pCPU using the
109 libvirt API before forwarding it to the host ``librte_power``.
112 .. _figure_vm_power_mgr_vm_request_seq:
114 .. figure:: img/vm_power_mgr_vm_request_seq.*
116 In addition to the ability to send power management requests to the
117 host, a VM can send a power management policy to the host. In some
118 cases, using a power management policy is a preferred option because it
119 can eliminate possible latency issues that can occur when sending power
120 management requests. Once the VM sends the policy to the host, the VM no
121 longer needs to worry about power management, because the host now
122 manages the power for the VM based on the policy. The policy can specify
123 power behavior that is based on incoming traffic rates or time-of-day
124 power adjustment (busy/quiet hour power adjustment for example). See
125 :ref:`sending_policy` for more information.
127 One method of power management is to sense how busy a core is when
128 processing packets and adjusting power accordingly. One technique for
129 doing this is to monitor the ratio of the branch miss to branch hits
130 counters and scale the core power accordingly. This technique is based
131 on the premise that when a core is not processing packets, the ratio of
132 branch misses to branch hits is very low, but when the core is
133 processing packets, it is measurably higher. The implementation of this
134 capability is as a policy of type ``BRANCH_RATIO``.
135 See :ref:`sending_policy` for more information on using the
136 BRANCH_RATIO policy option.
138 A JSON interface enables the specification of power management requests
139 and policies in JSON format. The JSON interfaces provide a more
140 convenient and more easily interpreted interface for the specification
141 of requests and policies. See :ref:`power_man_requests` for more information.
143 Performance Considerations
144 ~~~~~~~~~~~~~~~~~~~~~~~~~~
146 While the Haswell microarchitecture allows for independent power control
147 for each core, earlier microarchitectures do not offer such fine-grained
148 control. When deploying on pre-Haswell platforms, greater care must be
149 taken when selecting which cores are assigned to a VM, for example, a
150 core does not scale down in frequency until all of its siblings are
151 similarly scaled down.
159 To use the power management features of the DPDK, you must enable
160 Enhanced Intel SpeedStep® Technology in the platform BIOS. Otherwise,
161 the ``sys`` file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` does not
162 exist, and you cannot use CPU frequency-based power management. Refer to the
163 relevant BIOS documentation to determine how to access these settings.
165 Host Operating System
166 ~~~~~~~~~~~~~~~~~~~~~
168 The DPDK Power Management library can use either the ``acpi_cpufreq`` or
169 the ``intel_pstate`` kernel driver for the management of core frequencies. In
170 many cases, the ``intel_pstate`` driver is the default power management
173 Should the ``acpi-cpufreq driver`` be required, the ``intel_pstate``
174 module must be disabled, and the ``acpi-cpufreq`` module loaded in its place.
176 To disable the ``intel_pstate`` driver, add the following to the ``grub``
179 ``intel_pstate=disable``
181 On reboot, load the ``acpi_cpufreq`` module:
183 ``modprobe acpi_cpufreq``
185 Hypervisor Channel Configuration
186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188 Configure ``virtio-serial`` channels using ``libvirt`` XML.
189 The XML structure is as follows:
193 <name>{vm_name}</name>
194 <controller type='virtio-serial' index='0'>
195 <address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x0'/>
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}'/>
203 Where a single controller of type ``virtio-serial`` is created, up to 32
204 channels can be associated with a single controller, and multiple
205 controllers can be specified. The convention is to use the name of the
206 VM in the host path ``{vm_name}`` and to increment ``{channel_num}`` for each
207 channel. Likewise, the port value ``{N}`` must be incremented for each
210 On the host, for each channel to appear in the path, ensure the creation
211 of the ``/tmp/powermonitor/`` directory and the assignment of ``qemu``
214 .. code-block:: console
216 mkdir /tmp/powermonitor/
217 chown qemu:qemu /tmp/powermonitor
219 Note that files and directories in ``/tmp`` are generally removed when
220 rebooting the host and you may need to perform the previous steps after
223 The serial device as it appears on a VM is configured with the target
224 element 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
227 DPDK VM applications.
229 Each channel on a VM is present at:
231 ``/dev/virtio-ports/virtio.serial.port.poweragent.{vm_channel_num}``
233 Compiling and Running the Host Application
234 ------------------------------------------
236 Compiling the Host Application
237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
239 For information on compiling the DPDK and sample applications, see
240 see :doc:`compiling`.
242 The application is located in the ``vm_power_manager`` subdirectory.
244 To build just the ``vm_power_manager`` application using ``make``:
246 .. code-block:: console
248 export RTE_SDK=/path/to/rte_sdk
249 export RTE_TARGET=build
250 cd ${RTE_SDK}/examples/vm_power_manager/
253 The resulting binary is ``${RTE_SDK}/build/examples/vm_power_manager``.
255 To build just the ``vm_power_manager`` application using ``meson``/``ninja``:
257 .. code-block:: console
259 export RTE_SDK=/path/to/rte_sdk
264 meson configure -Dexamples=vm_power_manager
267 The resulting binary is ``${RTE_SDK}/build/examples/dpdk-vm_power_manager``.
269 Running the Host Application
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272 The application does not have any specific command line options other
273 than the EAL options:
275 .. code-block:: console
277 ./build/vm_power_mgr [EAL options]
279 The application requires exactly two cores to run. One core for the CLI
280 and the other for the channel endpoint monitor. For example, to run on
281 cores 0 and 1 on a system with four memory channels, issue the command:
283 .. code-block:: console
285 ./build/vm_power_mgr -l 0-1 -n 4
287 After successful initialization, the VM Power Manager CLI prompt appears:
289 .. code-block:: console
293 Now, it is possible to add virtual machines to the VM Power Manager:
295 .. code-block:: console
297 vm_power> add_vm {vm_name}
299 When a ``{vm_name}`` is specified with the ``add_vm`` command, a lookup is
300 performed with ``libvirt`` to ensure that the VM exists. ``{vm_name}`` is a
301 unique identifier to associate channels with a particular VM and for
302 executing operations on a VM within the CLI. VMs do not have to be
305 It is possible to issue several commands from the CLI to manage VMs.
307 Remove the virtual machine identified by ``{vm_name}`` from the VM Power
308 Manager using the command:
310 .. code-block:: console
314 Add communication channels for the specified VM using the following
315 command. The ``virtio`` channels must be enabled in the VM configuration
316 (``qemu/libvirt``) and the associated VM must be active. ``{list}`` is a
317 comma-separated list of channel numbers to add. Specifying the keyword
318 ``all`` attempts to add all channels for the VM:
320 .. code-block:: console
322 set_pcpu {vm_name} {vcpu} {pcpu}
324 Enable query of physical core information from a VM:
326 .. code-block:: console
328 set_query {vm_name} enable|disable
330 Manual control and inspection can also be carried in relation CPU frequency scaling:
332 Get the current frequency for each core specified in the mask:
334 .. code-block:: console
336 show_cpu_freq_mask {mask}
338 Set the current frequency for the cores specified in {core_mask} by scaling each up/down/min/max:
340 .. code-block:: console
342 add_channels {vm_name} {list}|all
344 Enable or disable the communication channels in ``{list}`` (comma-separated)
345 for the specified VM. Alternatively, replace ``list`` with the keyword
346 ``all``. Disabled channels receive packets on the host. However, the commands
347 they specify are ignored. Set the status to enabled to begin processing
350 .. code-block:: console
352 set_channel_status {vm_name} {list}|all enabled|disabled
354 Print to the CLI information on the specified VM. The information lists
355 the number of vCPUs, the pinning to pCPU(s) as a bit mask, along with
356 any communication channels associated with each VM, and the status of
359 .. code-block:: console
363 Set the binding of a virtual CPU on a VM with name ``{vm_name}`` to the
366 .. code-block:: console
368 set_pcpu_mask {vm_name} {vcpu} {pcpu}
370 Set the binding of the virtual CPU on the VM to the physical CPU:
372 .. code-block:: console
374 set_pcpu {vm_name} {vcpu} {pcpu}
376 It is also possible to perform manual control and inspection in relation
377 to CPU frequency scaling.
379 Get the current frequency for each core specified in the mask:
381 .. code-block:: console
383 show_cpu_freq_mask {mask}
385 Set the current frequency for the cores specified in ``{core_mask}`` by
386 scaling each up/down/min/max:
388 .. code-block:: console
390 set_cpu_freq {core_mask} up|down|min|max
392 Get the current frequency for the specified core:
394 .. code-block:: console
396 show_cpu_freq {core_num}
398 Set the current frequency for the specified core by scaling up/down/min/max:
400 .. code-block:: console
402 set_cpu_freq {core_num} up|down|min|max
404 .. _enabling_out_of_band:
406 Command Line Options for Enabling Out-of-band Branch Ratio Monitoring
407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
409 There are a couple of command line parameters for enabling the out-of-band
410 monitoring of branch ratios on cores doing busy polling using PMDs as
413 ``--core-branch-ratio {list of cores}:{branch ratio for listed cores}``
414 Specify the list of cores to monitor the ratio of branch misses
415 to branch hits. A tightly-polling PMD thread has a very low
416 branch ratio, therefore the core frequency scales down to the
417 minimum allowed value. On receiving packets, the code path changes,
418 causing the branch ratio to increase. When the ratio goes above
419 the ratio threshold, the core frequency scales up to the maximum
420 allowed value. The specified branch-ratio is a floating point number
421 that identifies the threshold at which to scale up or down for the
422 elements of the core-list. If not included the default branch ratio of
423 0.01 but will need adjustment for different workloads
425 This parameter can be used multiple times for different sets of cores.
426 The branch ratio mechanism can also be useful for non-PMD cores and
427 hyper-threaded environments where C-States are disabled.
430 Compiling and Running the Guest Applications
431 --------------------------------------------
433 It is possible to use the ``l3fwd-power`` application (for example) with the
434 ``vm_power_manager``.
436 The distribution also provides a guest CLI for validating the setup.
438 For both ``l3fwd-power`` and the guest CLI, the host application must use
439 the ``add_channels`` command to monitor the channels for the VM. To do this,
440 issue the following commands in the host application:
442 .. code-block:: console
444 vm_power> add_vm vmname
445 vm_power> add_channels vmname all
446 vm_power> set_channel_status vmname all enabled
447 vm_power> show_vm vmname
449 Compiling the Guest Application
450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452 For information on compiling DPDK and the sample applications in general,
453 see :doc:`compiling`.
455 For compiling and running the ``l3fwd-power`` sample application, see
456 :doc:`l3_forward_power_man`.
458 The application is in the ``guest_cli`` subdirectory under ``vm_power_manager``.
460 To build just the ``guest_vm_power_manager`` application using ``make``, issue
461 the following commands:
463 .. code-block:: console
465 export RTE_SDK=/path/to/rte_sdk
466 export RTE_TARGET=build
467 cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/
470 The resulting binary is ``${RTE_SDK}/build/examples/guest_cli``.
472 **Note**: This sample application conditionally links in the Jansson JSON
473 library. Consequently, if you are using a multilib or cross-compile
474 environment, you may need to set the ``PKG_CONFIG_LIBDIR`` environmental
475 variable to point to the relevant ``pkgconfig`` folder so that the correct
476 library is linked in.
478 For example, if you are building for a 32-bit target, you could find the
479 correct directory using the following find command:
481 .. code-block:: console
483 # find /usr -type d -name pkgconfig
484 /usr/lib/i386-linux-gnu/pkgconfig
485 /usr/lib/x86_64-linux-gnu/pkgconfig
489 .. code-block:: console
491 export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig
493 You then use the ``make`` command as normal, which should find the 32-bit
494 version of the library, if it installed. If not, the application builds
495 without the JSON interface functionality.
497 To build just the ``vm_power_manager`` application using ``meson``/``ninja``:
499 .. code-block:: console
501 export RTE_SDK=/path/to/rte_sdk
506 meson configure -Dexamples=vm_power_manager/guest_cli
509 The resulting binary is ``${RTE_SDK}/build/examples/guest_cli``.
511 Running the Guest Application
512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
514 The standard EAL command line parameters are necessary:
516 .. code-block:: console
518 ./build/vm_power_mgr [EAL options] -- [guest options]
520 The guest example uses a channel for each lcore enabled. For example, to
521 run on cores 0, 1, 2 and 3:
523 .. code-block:: console
525 ./build/guest_vm_power_mgr -l 0-3
529 Command Line Options Available When Sending a Policy to the Host
530 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
532 Optionally, there are several command line options for a user who needs
533 to send a power policy to the host application:
535 ``--vm-name {name of guest vm}``
536 Allows the user to change the virtual machine name
537 passed down to the host application using the power policy.
538 The default is ubuntu2.
540 ``--vcpu-list {list vm cores}``
541 A comma-separated list of cores in the VM that the user
542 wants the host application to monitor.
543 The list of cores in any VM starts at zero,
544 and the host application maps these to the physical cores
545 once the policy passes down to the host.
546 Valid syntax includes individual cores 2,3,4,
547 a range of cores 2-4, or a combination of both 1,3,5-7.
549 ``--busy-hours {list of busy hours}``
550 A comma-separated list of hours in which to set the core
551 frequency to the maximum.
552 Valid syntax includes individual hours 2,3,4,
553 a range of hours 2-4, or a combination of both 1,3,5-7.
554 Valid hour values are 0 to 23.
556 ``--quiet-hours {list of quiet hours}``
557 A comma-separated list of hours in which to set the core frequency
558 to minimum. Valid syntax includes individual hours 2,3,4,
559 a range of hours 2-4, or a combination of both 1,3,5-7.
560 Valid hour values are 0 to 23.
562 ``--policy {policy type}``
563 The type of policy. This can be one of the following values:
565 - TRAFFIC - Based on incoming traffic rates on the NIC.
566 - TIME - Uses a busy/quiet hours policy.
567 - BRANCH_RATIO - Uses branch ratio counters to determine core busyness.
568 - WORKLOAD - Sets the frequency to low, medium or high
569 based on the received policy setting.
571 **Note**: Not all policy types need all parameters.
572 For example, BRANCH_RATIO only needs the vcpu-list parameter.
574 After successful initialization, the VM Power Manager Guest CLI prompt
577 .. code-block:: console
581 To change the frequency of an lcore, use a ``set_cpu_freq`` command similar
584 .. code-block:: console
586 set_cpu_freq {core_num} up|down|min|max
588 where, ``{core_num}`` is the lcore and channel to change frequency by
589 scaling up/down/min/max.
591 To start an application, configure the power policy, and send it to the
592 host, use a command like the following:
594 .. code-block:: console
596 ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4
598 Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command
599 will send the policy to the host:
601 .. code-block:: console
605 Once the policy is sent to the host, the host application takes over the power monitoring
606 of the specified cores in the policy.
608 .. _power_man_requests:
610 JSON Interface for Power Management Requests and Policies
611 ---------------------------------------------------------
613 In addition to the command line interface for the host command, and a
614 ``virtio-serial`` interface for VM power policies, there is also a JSON
615 interface through which power commands and policies can be sent.
617 **Note**: This functionality adds a dependency on the Jansson library.
618 Install the Jansson development package on the system to avail of the
619 JSON parsing functionality in the app. Issue the ``apt-get install
620 libjansson-dev`` command to install the development package. The command
621 and package name may be different depending on your operating system. It
622 is worth noting that the app builds successfully if this package is not
623 present, but a warning displays during compilation, and the JSON parsing
624 functionality is not present in the app.
626 Send a request or policy to the VM Power Manager by simply opening a
627 fifo file at ``/tmp/powermonitor/fifo``, writing a JSON string to that file,
628 and closing the file.
630 The JSON string can be a power management request or a policy, and takes
631 the following format:
633 .. code-block:: javascript
640 The ``packet_type`` header can contain one of two values, depending on
641 whether a power management request or policy is being sent. The two
642 possible values are ``instruction`` and ``policy`` and the expected name-value
643 pairs are different depending on which type is sent.
645 The pairs are in the format of standard JSON name-value pairs. The value
646 type varies between the different name-value pairs, and may be integers,
647 strings, arrays, and so on. See :ref:`json_interface_ex`
648 for examples of policies and instructions and
649 :ref:`json_name_value_pair` for the supported names and value types.
651 .. _json_interface_ex:
653 JSON Interface Examples
654 ~~~~~~~~~~~~~~~~~~~~~~~
656 The following is an example JSON string that creates a time-profile
664 "policy_type": "TIME",
665 "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ],
666 "quiet_hours":[ 2, 3, 4, 5, 6 ],
670 The following is an example JSON string that removes the named policy.
676 "command": "destroy",
679 The following is an example JSON string for a power management request.
690 To query the available frequences of an lcore, use the query_cpu_freq command.
691 Where {core_num} is the lcore to query.
692 Before using this command, please enable responses via the set_query command on the host.
694 .. code-block:: console
696 query_cpu_freq {core_num}|all
698 To query the capabilities of an lcore, use the query_cpu_caps command.
699 Where {core_num} is the lcore to query.
700 Before using this command, please enable responses via the set_query command on the host.
702 .. code-block:: console
704 query_cpu_caps {core_num}|all
706 To start the application and configure the power policy, and send it to the host:
708 .. code-block:: console
710 ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4
712 Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command
713 will send the policy to the host:
715 .. code-block:: console
719 Once the policy is sent to the host, the host application takes over the power monitoring
720 of the specified cores in the policy.
722 .. _json_name_value_pair:
724 JSON Name-value Pairs
725 ~~~~~~~~~~~~~~~~~~~~~
727 The following are the name-value pairs supported by the JSON interface:
729 - `avg_packet_thresh`_
734 - `max_packet_thresh`_
746 The threshold below which the frequency is set to the minimum value
747 for the TRAFFIC policy.
748 If the traffic rate is above this value and below the maximum value,
749 the frequency is set to medium.
753 The number of packets below which the TRAFFIC policy applies
754 the minimum frequency, or the medium frequency
755 if between the average and maximum thresholds.
759 ``"avg_packet_thresh": 100000``
765 The hours of the day in which we scale up the cores for busy times.
769 An array with a list of hour values (0-23).
771 For the TIME policy only.
773 ``"busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ]``
779 The type of packet to send to the VM Power Manager.
780 It is possible to create or destroy a policy or send a direct command
781 to adjust the frequency of a core,
782 as is possible on the command line interface.
787 - CREATE: Create a new policy.
788 - DESTROY: Remove an existing policy.
789 - POWER: Send an immediate command, max, min, and so on.
793 ``"command": "CREATE"``
799 The cores to which to apply a policy.
803 An array with a list of virtual CPUs.
805 For CREATE/DESTROY policy requests only.
807 ``"core_list":[ 10, 11 ]``
813 When the policy is of type TRAFFIC,
814 it is necessary to specify the MAC addresses that the host must monitor.
818 An array with a list of MAC address strings.
820 For TRAFFIC policy types only.
822 ``"mac_list":[ "de:ad:be:ef:01:01","de:ad:be:ef:01:02" ]``
828 In a policy of type TRAFFIC,
829 the threshold value above which the frequency is set to a maximum.
833 The number of packets per interval above which
834 the TRAFFIC policy applies the maximum frequency.
836 For the TRAFFIC policy only.
838 ``"max_packet_thresh": 500000``
844 The name of the VM or host.
845 Allows the parser to associate the policy with the relevant VM or host OS.
853 ``"name": "ubuntu2"``
859 The type of policy to apply.
860 See the ``--policy`` option description for more information.
866 - TIME: Time-of-day policy.
867 Scale the frequencies of the relevant cores up/down
868 depending on busy and quiet hours.
869 - TRAFFIC: Use statistics from the NIC and scale up and down accordingly.
870 - WORKLOAD: Determine how heavily loaded the cores are
871 and scale up and down accordingly.
872 - BRANCH_RATIO: An out-of-band policy that looks at the ratio
873 between branch hits and misses on a core
874 and uses that information to determine how much packet processing
878 For ``CREATE`` and ``DESTROY`` policy requests only.
880 ``"policy_type": "TIME"``
886 The hours of the day to scale down the cores for quiet times.
890 An array with a list of hour numbers with values in the range 0 to 23.
892 For the TIME policy only.
894 ``"quiet_hours":[ 2, 3, 4, 5, 6 ]``
900 The core to which to apply a power command.
904 A valid core ID for the VM or host OS.
906 For the ``POWER`` instruction only.
908 ``"resource_id": 10``
914 The type of power operation to apply in the command.
918 - SCALE_MAX: Scale the frequency of this core to the maximum.
919 - SCALE_MIN: Scale the frequency of this core to the minimum.
920 - SCALE_UP: Scale up the frequency of this core.
921 - SCALE_DOWN: Scale down the frequency of this core.
922 - ENABLE_TURBO: Enable Intel® Turbo Boost Technology for this core.
923 - DISABLE_TURBO: Disable Intel® Turbo Boost Technology for this core.
925 For the ``POWER`` instruction only.
927 ``"unit": "SCALE_MAX"``
933 In a policy of type WORKLOAD,
934 it is necessary to specify how heavy the workload is.
938 - HIGH: Scale the frequency of this core to maximum.
939 - MEDIUM: Scale the frequency of this core to minimum.
940 - LOW: Scale up the frequency of this core.
942 For the ``WORKLOAD`` policy only.
944 ``"workload": "MEDIUM"``