From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 830B931FC for ; Wed, 25 Jul 2018 15:00:20 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 25 Jul 2018 06:00:18 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.51,401,1526367600"; d="scan'208";a="57773116" Received: from silpixa00399952.ir.intel.com (HELO silpixa00399952.ger.corp.intel.com) ([10.237.223.64]) by fmsmga008.fm.intel.com with ESMTP; 25 Jul 2018 06:00:17 -0700 From: David Hunt To: dev@dpdk.org Cc: john.mcnamara@intel.com, david.hunt@intel.com Date: Wed, 25 Jul 2018 14:00:09 +0100 Message-Id: <20180725130009.41756-1-david.hunt@intel.com> X-Mailer: git-send-email 2.17.1 Subject: [dpdk-dev] [PATCH v1] doc/samples: update vm power manager sample docs X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 25 Jul 2018 13:00:23 -0000 Add information on the ability of guest app to sent a policy to the host app. Add information on the branch ratio out-of-band method of workload monitoring and power management. Signed-off-by: David Hunt --- .../sample_app_ug/vm_power_management.rst | 165 ++++++++++++++++-- 1 file changed, 150 insertions(+), 15 deletions(-) diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index cd7c7f341..855570d6b 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -20,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. @@ -38,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 @@ -174,13 +194,20 @@ Compiling and Running the Host Application Compiling ~~~~~~~~~ -Compiling the Application -------------------------- - -To compile the sample application see :doc:`compiling`. +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 ~~~~~~~ @@ -287,38 +314,129 @@ 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 :doc:`l3_forward_power_man`. +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 -l 0-3 -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 + + --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: @@ -333,3 +451,20 @@ Where {core_num} is the lcore and channel to change frequency by scaling up/down .. code-block:: console set_cpu_freq {core_num} up|down|min|max + +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. + -- 2.17.1