X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fvm_power_management.rst;h=855570d6b53c4c98d5cee125b570b773ceba9e04;hb=e3386f9a512332718b3715ba71436235c589589b;hp=16f44c4bac4aa42ee669db7a1caa0a5b55588233;hpb=c75f4e6a7a2b5a7b4136ddd6dcb977eb48aae1f6;p=dpdk.git diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index 16f44c4bac..855570d6b5 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. VM Power Management Application =============================== @@ -47,7 +20,7 @@ running on Virtual Machines(VMs). The Virtual Machine Power Management solution shows an example of how a DPDK application can indicate its processing requirements using VM local -only information(vCPU/lcore) to a Host based Monitor which is responsible +only information(vCPU/lcore, etc.) to a Host based Monitor which is responsible for accepting requests for frequency changes for a vCPU, translating the vCPU to a pCPU via libvirt and affecting the change in frequency. @@ -65,6 +38,26 @@ The solution is comprised of two high-level components: to the librte_power ACPI cpufreq sysfs based library. The Host Application relies on both qemu-kvm and libvirt to function. + This monitoring application is responsible for: + + - Accepting requests from client applications: Client applications can + request frequency changes for a vCPU, translating + the vCPU to a pCPU via libvirt and affecting the change in frequency. + + - Accepting policies from client applications: Client application can + send a policy to the host application. The + host application will then apply the rules of the policy independent + of the application. For example, the policy can contain time-of-day + information for busy/quiet periods, and the host application can scale + up/down the relevant cores when required. See the details of the guest + application below for more information on setting the policy values. + + - Out-of-band monitoring of workloads via cores hardware event counters: + The host application can manage power for an application in a virtualised + OR non-virtualised environment by looking at the event counters of the + cores and taking action based on the branch hit/miss ratio. See the host + application '--core-list' command line parameter below. + #. librte_power for Virtual Machines Using an alternate implementation for the librte_power API, requests for @@ -72,13 +65,14 @@ The solution is comprised of two high-level components: the APCI cpufreq sysfs interface used on the host. The l3fwd-power application will use this implementation when deployed on a VM - (see Chapter 11 "L3 Forwarding with Power Management Application"). + (see :doc:`l3_forward_power_man`). -.. _figure_24: +.. _figure_vm_power_mgr_highlevel: -**Figure 24. Highlevel Solution** +.. figure:: img/vm_power_mgr_highlevel.* + + Highlevel Solution -|vm_power_mgr_highlevel| Overview -------- @@ -105,11 +99,12 @@ at runtime based on the environment. Upon receiving a request, the host translates the vCPU to a pCPU via the libvirt API before forwarding to the host librte_power. -.. _figure_25: +.. _figure_vm_power_mgr_vm_request_seq: + +.. figure:: img/vm_power_mgr_vm_request_seq.* -**Figure 25. VM request to scale frequency** + VM request to scale frequency -|vm_power_mgr_vm_request_seq| Performance Considerations ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -139,7 +134,7 @@ Host Operating System The Host OS must also have the *apci_cpufreq* module installed, in some cases the *intel_pstate* driver may be the default Power Management environment. To enable *acpi_cpufreq* and disable *intel_pstate*, add the following -to the grub linux command line: +to the grub Linux command line: .. code-block:: console @@ -165,7 +160,7 @@ Virtio-Serial channels are configured via libvirt XML: -
@@ -199,9 +194,19 @@ Compiling and Running the Host Application Compiling ~~~~~~~~~ -#. export RTE_SDK=/path/to/rte_sdk -#. cd ${RTE_SDK}/examples/vm_power_manager -#. make +For information on compiling DPDK and the sample applications +see :doc:`compiling`. + +The application is located in the ``vm_power_manager`` sub-directory. + +To build just the ``vm_power_manager`` application: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + export RTE_TARGET=build + cd ${RTE_SDK}/examples/vm_power_manager/ + make Running ~~~~~~~ @@ -218,9 +223,9 @@ on cores 0 & 1 on a system with 4 memory channels: .. code-block:: console - ./build/vm_power_mgr -c 0x3 -n 4 + ./build/vm_power_mgr -l 0-1 -n 4 -After successful initialisation the user is presented with VM Power Manager CLI: +After successful initialization the user is presented with VM Power Manager CLI: .. code-block:: console @@ -309,41 +314,132 @@ Manual control and inspection can also be carried in relation CPU frequency scal set_cpu_freq {core_num} up|down|min|max +There are also some command line parameters for enabling the out-of-band +monitoring of branch ratio on cores doing busy polling via PMDs. + + .. code-block:: console + + --core-list {list of cores} + + When this parameter is used, the list of cores specified will monitor the ratio + between branch hits and branch misses. A tightly polling PMD thread will have a + very low branch ratio, so the core frequency will be scaled down to the minimim + allowed value. When packets are received, the code path will alter, causing the + branch ratio to increase. When the ratio goes above the ratio threshold, the + core frequency will be scaled up to the maximum allowed value. + + .. code-block:: console + + --branch-ratio {ratio} + + The branch ratio is a floating point number that specifies the threshold at which + to scale up or down for the given workload. The default branch ratio is 0.01, + and will need to be adjusted for different workloads. + + Compiling and Running the Guest Applications -------------------------------------------- -For compiling and running l3fwd-power, see Chapter 11 "L3 Forwarding with Power Management Application". +l3fwd-power is one sample application that can be used with vm_power_manager. A guest CLI is also provided for validating the setup. For both l3fwd-power and guest CLI, the channels for the VM must be monitored by the -host application using the *add_channels* command on the host. +host application using the *add_channels* command on the host. This typically uses +the following commands in the host application: + +.. code-block:: console + + vm_power> add_vm vmname + vm_power> add_channels vmname all + vm_power> set_channel_status vmname all enabled + vm_power> show_vm vmname + Compiling ~~~~~~~~~ -#. export RTE_SDK=/path/to/rte_sdk -#. cd ${RTE_SDK}/examples/vm_power_manager/guest_cli -#. make +For information on compiling DPDK and the sample applications +see :doc:`compiling`. + +For compiling and running l3fwd-power, see :doc:`l3_forward_power_man`. + +The application is located in the ``guest_cli`` sub-directory under ``vm_power_manager``. + +To build just the ``guest_vm_power_manager`` application: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + export RTE_TARGET=build + cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/ + make Running ~~~~~~~ -The application does not have any specific command line options other than *EAL*: +The standard *EAL* command line parameters are required: .. code-block:: console - ./build/vm_power_mgr [EAL options] + ./build/guest_vm_power_mgr [EAL options] -- [guest options] -The application for example purposes uses a channel for each lcore enabled, -for example to run on cores 0,1,2,3 on a system with 4 memory channels: +The guest example uses a channel for each lcore enabled. For example, +to run on cores 0,1,2,3: .. code-block:: console - ./build/guest_vm_power_mgr -c 0xf -n 4 + ./build/guest_vm_power_mgr -l 0-3 + +Optionally, there is a list of command line parameter should the user wish to send a power +policy down to the host application. These parameters are as follows: + + .. code-block:: console + + --vm-name {name of guest vm} + + This parameter allows the user to change the Virtual Machine name passed down to the + host application via the power policy. The default is "ubuntu2" + + .. code-block:: console + + --vcpu-list {list vm cores} + + A comma-separated list of cores in the VM that the user wants the host application to + monitor. The list of cores in any vm starts at zero, and these are mapped to the + physical cores by the host application once the policy is passed down. + Valid syntax includes individial cores '2,3,4', or a range of cores '2-4', or a + combination of both '1,3,5-7' + + .. code-block:: console + + --busy-hours {list of busy hours} + A comma-separated list of hours within which to set the core frequency to maximum. + Valid syntax includes individial hours '2,3,4', or a range of hours '2-4', or a + combination of both '1,3,5-7'. Valid hours are 0 to 23. + + .. code-block:: console -After successful initialisation the user is presented with VM Power Manager Guest CLI: + --quiet-hours {list of quiet hours} + + A comma-separated list of hours within which to set the core frequency to minimum. + Valid syntax includes individial hours '2,3,4', or a range of hours '2-4', or a + combination of both '1,3,5-7'. Valid hours are 0 to 23. + + .. code-block:: console + + --policy {policy type} + + The type of policy. This can be one of the following values: + TRAFFIC - based on incoming traffic rates on the NIC. + TIME - busy/quiet hours policy. + BRANCH_RATIO - uses branch ratio counters to determine core busyness. + Not all parameters are needed for all policy types. For example, BRANCH_RATIO + only needs the vcpu-list parameter, not any of the hours. + + +After successful initialization the user is presented with VM Power Manager Guest CLI: .. code-block:: console @@ -356,6 +452,19 @@ Where {core_num} is the lcore and channel to change frequency by scaling up/down set_cpu_freq {core_num} up|down|min|max -.. |vm_power_mgr_highlevel| image:: img/vm_power_mgr_highlevel.svg +To start the application and configure the power policy, and send it to the host: + +.. code-block:: console + + ./build/guest_vm_power_mgr -l 0-3 -n 4 -- --vm-name=ubuntu --policy=BRANCH_RATIO --vcpu-list=2-4 + +Once the VM Power Manager Guest CLI appears, issuing the 'send_policy now' command +will send the policy to the host: + +.. code-block:: console + + send_policy now + +Once the policy is sent to the host, the host application takes over the power monitoring +of the specified cores in the policy. -.. |vm_power_mgr_vm_request_seq| image:: img/vm_power_mgr_vm_request_seq.svg