From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id C7E3FA055B; Tue, 25 Feb 2020 18:58:31 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A2A4F1BFB3; Tue, 25 Feb 2020 18:58:31 +0100 (CET) Received: from out4-smtp.messagingengine.com (out4-smtp.messagingengine.com [66.111.4.28]) by dpdk.org (Postfix) with ESMTP id 7D3811BF8D for ; Tue, 25 Feb 2020 18:58:29 +0100 (CET) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id BA29D2211E; Tue, 25 Feb 2020 12:58:28 -0500 (EST) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Tue, 25 Feb 2020 12:58:28 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:mime-version:content-type :content-transfer-encoding; s=mesmtp; bh=mzpnO1f6s75TA7yDGP3RLUh MH4bdASv/oLIwPnRM6bM=; b=QSn55/mw8LC/v8nyc1jFLMK2jtx4wJPFmOJZTue Ch4T4wLmjc4vq8MCzV15yzZtKCfk6rXhzedktQ4Tw2tO+dj9aVpnlBZsvfM3JYe0 kwqc3bZHfJVK2y2EzmHnF3oUl25/EwbduwFu4/1zA+MzkkGctgaZZNBbNsGGkh7e SsM8= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:message-id:mime-version:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; bh=mzpnO1 f6s75TA7yDGP3RLUhMH4bdASv/oLIwPnRM6bM=; b=e64dZEpZJnN2hCnFC9nULK eZt2p1LFvYeQgJvONnAWuPR625+G1UsNbZlIqcv6vo2j5FB/jMlR9Zwz3Q2Th03P BY9MXI+RCjTursfQTKM43nKNHtdIKJC9T143EzfaYvVXV5VB14bNswwhlY3c5HWo tIO2m5Kj8z2VOg+FaMOnFgZyjbIWt2Ea9rqcgdWIJdoLp3Zd6o4js4tHAal3fPF5 JkJnUGFe7yVckahDGJ4CefDiUYtEM1lmhSS+FlzDxcV5HgGwOrI2yeVvkak3RQR1 BJLDKxW26nEKLdpV25JMSVO3CTTY7B3jzf1pGbjGMVmm8WZ515SmJa6j6FvaKpvg == X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedugedrledvgddutdeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkffogggtgfesthekredtredtjeenucfhrhhomhepvfhhohhmrghs ucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtqeenucfkph epjeejrddufeegrddvtdefrddukeegnecuvehluhhsthgvrhfuihiivgeptdenucfrrghr rghmpehmrghilhhfrhhomhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvth X-ME-Proxy: Received: from xps.monjalon.net (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id 55BE0328005A; Tue, 25 Feb 2020 12:58:27 -0500 (EST) From: Thomas Monjalon To: dev@dpdk.org Cc: ferruh.yigit@intel.com, bernard.iremonger@intel.com, David Hunt , John McNamara , Marko Kovacevic Date: Tue, 25 Feb 2020 18:58:20 +0100 Message-Id: <20200225175820.1066888-1-thomas@monjalon.net> X-Mailer: git-send-email 2.25.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH] doc: fix VM power manager guide as PDF 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: , Errors-To: dev-bounces@dpdk.org Sender: "dev" When generating PDF with on an old system, there are failures because of long tables: vm_power_management.rst:420: ERROR: Malformed table. Column span alignment problem in table line 5. vm_power_management.rst:545: ERROR: Malformed table. Column span alignment problem in table line 5. vm_power_management.rst:754: ERROR: Malformed table. Column span alignment problem in table line 5. The tables (having only two columns) are replaced with the more appropriate definition lists. Fixes: 30d3aa861db5 ("doc: rework VM power manager user guide") Signed-off-by: Thomas Monjalon --- .../sample_app_ug/vm_power_management.rst | 395 +++++++++--------- 1 file changed, 200 insertions(+), 195 deletions(-) diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index b583da36c0..e98277ccb0 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -408,26 +408,21 @@ Command Line Options for Enabling Out-of-band Branch Ratio Monitoring There are a couple of command line parameters for enabling the out-of-band monitoring of branch ratios on cores doing busy polling using PMDs as -described in the following table. +described below: -Table 1 – Command Line Options for Enabling Out-of-band Monitoring of -Branch Ratios - -=============================== ============================================== -**Command Line Option** **Description** -=============================== ============================================== -``--core-list {list of cores}`` | Specify the list of cores to monitor the ratio of branch misses - | to branch hits. A tightly-polling PMD thread has a very low - | branch ratio, therefore the core frequency scales down to the - | minimum allowed value. On receiving packets, the code path changes, - | causing the branch ratio to increase. When the ratio goes above - | the ratio threshold, the core frequency scales up to the maximum - | allowed value. -``--branch-ratio {ratio}`` | Specify a floating-point number that identifies the threshold at which - | to scale up or down for the given workload. The default branch ratio - | is 0.01 and needs adjustment for different workloads. -=============================== ============================================== +``--core-list {list of cores}`` + Specify the list of cores to monitor the ratio of branch misses + to branch hits. A tightly-polling PMD thread has a very low + branch ratio, therefore the core frequency scales down to the + minimum allowed value. On receiving packets, the code path changes, + causing the branch ratio to increase. When the ratio goes above + the ratio threshold, the core frequency scales up to the maximum + allowed value. +``--branch-ratio {ratio}`` + Specify a floating-point number that identifies the threshold at which + to scale up or down for the given workload. The default branch ratio + is 0.01 and needs adjustment for different workloads. Compiling and Running the Guest Applications @@ -533,48 +528,46 @@ Command Line Options Available When Sending a Policy to the Host ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Optionally, there are several command line options for a user who needs -to send a power policy to the host application. The following table -describes these options. +to send a power policy to the host application: -Table 1 – Command Line Options Available When Sending a Policy to the Host +``--vm-name {name of guest vm}`` + Allows the user to change the virtual machine name + passed down to the host application using the power policy. + The default is ubuntu2. -======================================= ====================================== -**Command Line Option** **Description** -======================================= ====================================== -``--vm-name {name of guest vm}`` | Allows the user to change the virtual machine name passed - | down to the host application using the power policy. The - | default is ubuntu2. -``--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 the host application maps - | these to the physical cores once the policy passes down - | to the host. Valid syntax includes individual cores - | 2,3,4, a range of cores 2-4, or a combination of both - | 1,3,5-7. -``--busy-hours {list of busy hours}`` | A comma-separated list of hours in which to set the core - | frequency to the maximum. Valid syntax includes - | individual hours 2,3,4, a range of hours 2-4, or a - | combination of both 1,3,5-7. Valid hour values are 0 to 23. -``--quiet-hours {list of quiet hours}`` | A comma-separated list of hours in which to set the core - | frequency to minimum. Valid syntax includes individual - | hours 2,3,4, a range of hours 2-4, or a combination of - | both 1,3,5-7. Valid hour values are 0 to 23. -``--policy {policy type}`` | The type of policy. This can be one of the following values: +``--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 the host application maps these to the physical cores + once the policy passes down to the host. + Valid syntax includes individual cores 2,3,4, + a range of cores 2-4, or a combination of both 1,3,5-7. - - | TRAFFIC Based on incoming traffic rates on the NIC. +``--busy-hours {list of busy hours}`` + A comma-separated list of hours in which to set the core + frequency to the maximum. + Valid syntax includes individual hours 2,3,4, + a range of hours 2-4, or a combination of both 1,3,5-7. + Valid hour values are 0 to 23. - - | TIME - Uses a busy/quiet hours policy. +``--quiet-hours {list of quiet hours}`` + A comma-separated list of hours in which to set the core frequency + to minimum. Valid syntax includes individual hours 2,3,4, + a range of hours 2-4, or a combination of both 1,3,5-7. + Valid hour values are 0 to 23. - - | BRANCH_RATIO - Uses branch ratio counters to determine - | core busyness. +``--policy {policy type}`` + The type of policy. This can be one of the following values: - - | WORKLOAD - Sets the frequency to low, medium or high - | based on the received policy setting. + - TRAFFIC - Based on incoming traffic rates on the NIC. + - TIME - Uses a busy/quiet hours policy. + - BRANCH_RATIO - Uses branch ratio counters to determine core busyness. + - WORKLOAD - Sets the frequency to low, medium or high + based on the received policy setting. - | **Note**: Not all policy types need all parameters. For - | example, BRANCH_RATIO only needs the vcpu-list - | parameter. -======================================= ====================================== + **Note**: Not all policy types need all parameters. + For example, BRANCH_RATIO only needs the vcpu-list parameter. After successful initialization, the VM Power Manager Guest CLI prompt appears: @@ -747,191 +740,203 @@ The following are the name-value pairs supported by the JSON interface: avg_packet_thresh ^^^^^^^^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "avg_packet_thresh" -================== =========================================================== - **Description:** | The threshold below which the frequency is set to the minimum value for the - | TRAFFIC policy. If the traffic rate is above this value and below the - | maximum value, the frequency is set to medium. - **Type:** integer - **Values:** | The number of packets below which the TRAFFIC policy applies the minimum - | frequency, or the medium frequency if between the average and maximum - | thresholds. - **Required:** Yes - **Example:** ``"avg_packet_thresh": 100000`` -================== =========================================================== +Description + The threshold below which the frequency is set to the minimum value + for the TRAFFIC policy. + If the traffic rate is above this value and below the maximum value, + the frequency is set to medium. +Type + integer +Values + The number of packets below which the TRAFFIC policy applies + the minimum frequency, or the medium frequency + if between the average and maximum thresholds. +Required + Yes +Example + ``"avg_packet_thresh": 100000`` busy_hours ^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "busy_hours" -================== =========================================================== - **Description:** The hours of the day in which we scale up the cores for busy times. - **Type:** array of integers - **Values:** An array with a list of hour values (0-23). - **Required:** For the TIME policy only. - **Example:** ``"busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ]`` -================== =========================================================== +Description + The hours of the day in which we scale up the cores for busy times. +Type + array of integers +Values + An array with a list of hour values (0-23). +Required + For the TIME policy only. +Example + ``"busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ]`` command ^^^^^^^ -================== =========================================================== - **Pair Name:** "command" -================== =========================================================== - **Description:** | The type of packet to send to the VM Power Manager. It is possible to create - | or destroy a policy or send a direct command to adjust the frequency of a core, - | as is possible on the command line interface. - **Type:** | string - **Values:** Possible values are: - - - CREATE: Create a new policy. - - DESTROY: Remove an existing policy. - - POWER: Send an immediate command, max, min, and so on. - - **Required:** Yes - **Example:** ``"command": "CREATE"`` -================== =========================================================== +Description + The type of packet to send to the VM Power Manager. + It is possible to create or destroy a policy or send a direct command + to adjust the frequency of a core, + as is possible on the command line interface. +Type + string +Values + Possible values are: + - CREATE: Create a new policy. + - DESTROY: Remove an existing policy. + - POWER: Send an immediate command, max, min, and so on. +Required + Yes +Example + ``"command": "CREATE"`` core_list ^^^^^^^^^ -================== =========================================================== - **Pair Name:** "core_list" -================== =========================================================== - **Description:** The cores to which to apply a policy. - **Type:** array of integers - **Values:** An array with a list of virtual CPUs. - **Required:** For CREATE/DESTROY policy requests only. - **Example:** ``"core_list":[ 10, 11 ]`` -================== =========================================================== +Description + The cores to which to apply a policy. +Type + array of integers +Values + An array with a list of virtual CPUs. +Required + For CREATE/DESTROY policy requests only. +Example + ``"core_list":[ 10, 11 ]`` mac_list ^^^^^^^^ -================== =========================================================== - **Pair Name:** "mac_list" -================== =========================================================== - **Description:** | When the policy is of type TRAFFIC, it is necessary to specify the MAC addresses - | that the host must monitor. - **Type:** | array of strings - **Values:** An array with a list of mac address strings. - **Required:** For TRAFFIC policy types only. - **Example:** ``"mac_list":[ "de:ad:be:ef:01:01","de:ad:be:ef:01:02" ]`` -================== =========================================================== - +Description + When the policy is of type TRAFFIC, + it is necessary to specify the MAC addresses that the host must monitor. +Type + array of strings +Values + An array with a list of MAC address strings. +Required + For TRAFFIC policy types only. +Example + ``"mac_list":[ "de:ad:be:ef:01:01","de:ad:be:ef:01:02" ]`` max_packet_thresh ^^^^^^^^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "max_packet_thresh" -================== =========================================================== - **Description:** | In a policy of type TRAFFIC, the threshold value above which the frequency is set - | to a maximum. - **Type:** | integer - **Values:** | The number of packets per interval above which the TRAFFIC - | policy applies the maximum frequency. - **Required:** For the TRAFFIC policy only. - **Example:** ``"max_packet_thresh": 500000`` -================== =========================================================== +Description + In a policy of type TRAFFIC, + the threshold value above which the frequency is set to a maximum. +Type + integer +Values + The number of packets per interval above which + the TRAFFIC policy applies the maximum frequency. +Required + For the TRAFFIC policy only. +Example + ``"max_packet_thresh": 500000`` name ^^^^ -================== =========================================================== - **Pair Name:** "name" -================== =========================================================== - **Description:** | The name of the VM or host. Allows the parser to associate the policy with the - | relevant VM or host OS. - **Type:** | string - **Values:** Any valid string. - **Required:** Yes - **Example:** ``"name": "ubuntu2"`` -================== =========================================================== +Description + The name of the VM or host. + Allows the parser to associate the policy with the relevant VM or host OS. +Type + string +Values + Any valid string. +Required + Yes +Example + ``"name": "ubuntu2"`` policy_type ^^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "policy_type" -================== =========================================================== - **Description:** | The type of policy to apply. See the ``--policy`` option description for more - | information. - **Type:** string - **Values:** Possible values are: +Description + The type of policy to apply. + See the ``--policy`` option description for more information. +Type + string +Values + Possible values are: - - | TIME: Time-of-day policy. Scale the frequencies of the relevant cores up/down - | depending on busy and quiet hours. - - | TRAFFIC: Use statistics from the NIC and scale up and down accordingly. - - | WORKLOAD: Determine how heavily loaded the cores are and scale up and down - | accordingly. - - | BRANCH_RATIO: An out-of-band policy that looks at the ratio between branch - | hits and misses on a core and uses that information to determine how much - | packet processing a core is doing. + - TIME: Time-of-day policy. + Scale the frequencies of the relevant cores up/down + depending on busy and quiet hours. + - TRAFFIC: Use statistics from the NIC and scale up and down accordingly. + - WORKLOAD: Determine how heavily loaded the cores are + and scale up and down accordingly. + - BRANCH_RATIO: An out-of-band policy that looks at the ratio + between branch hits and misses on a core + and uses that information to determine how much packet processing + a core is doing. - **Required:** For ``CREATE`` and ``DESTROY`` policy requests only. - **Example:** ``"policy_type": "TIME"`` -================== =========================================================== +Required + For ``CREATE`` and ``DESTROY`` policy requests only. +Example + ``"policy_type": "TIME"`` quiet_hours ^^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "quiet_hours" -================== =========================================================== - **Description:** | The hours of the day to scale down the cores for quiet times. - **Type:** array of integers - **Values:** | An array with a list of hour numbers with values in the range 0 to 23. - **Required:** For the TIME policy only. - **Example:** ``"quiet_hours":[ 2, 3, 4, 5, 6 ]`` -================== =========================================================== +Description + The hours of the day to scale down the cores for quiet times. +Type + array of integers +Values + An array with a list of hour numbers with values in the range 0 to 23. +Required + For the TIME policy only. +Example + ``"quiet_hours":[ 2, 3, 4, 5, 6 ]`` resource_id ^^^^^^^^^^^ -================== =========================================================== - **Pair Name:** "resource_id" -================== =========================================================== - **Description:** The core to which to apply a power command. - **Type:** integer - **Values:** A valid core ID for the VM or host OS. - **Required:** For the ``POWER`` instruction only. - **Example:** ``"resource_id": 10`` -================== =========================================================== +Description + The core to which to apply a power command. +Type + integer +Values + A valid core ID for the VM or host OS. +Required + For the ``POWER`` instruction only. +Example + ``"resource_id": 10`` unit ^^^^ -================== =========================================================== - **Pair Name:** "unit" -================== =========================================================== - **Description:** The type of power operation to apply in the command. - **Type:** string - **Values:** - SCALE_MAX: Scale the frequency of this core to the maximum. - - SCALE_MIN: Scale the frequency of this core to the minimum. - - SCALE_UP: Scale up the frequency of this core. - - SCALE_DOWN: Scale down the frequency of this core. - - ENABLE_TURBO: Enable Intel® Turbo Boost Technology for this core. - - DISABLE_TURBO: Disable Intel® Turbo Boost Technology for this core. - **Required:** For the ``POWER`` instruction only. - **Example:** ``"unit": "SCALE_MAX"`` -================== =========================================================== +Description + The type of power operation to apply in the command. +Type + string +Values + - SCALE_MAX: Scale the frequency of this core to the maximum. + - SCALE_MIN: Scale the frequency of this core to the minimum. + - SCALE_UP: Scale up the frequency of this core. + - SCALE_DOWN: Scale down the frequency of this core. + - ENABLE_TURBO: Enable Intel® Turbo Boost Technology for this core. + - DISABLE_TURBO: Disable Intel® Turbo Boost Technology for this core. +Required + For the ``POWER`` instruction only. +Example + ``"unit": "SCALE_MAX"`` workload ^^^^^^^^ -================== =========================================================== - **Pair Name:** "workload" -================== =========================================================== - **Description:** In a policy of type WORKLOAD, it is necessary to specify - how heavy the workload is. - **Type:** string - **Values:** - HIGH: Scale the frequency of this core to maximum. - - MEDIUM: Scale the frequency of this core to minimum. - - LOW: Scale up the frequency of this core. - **Required:** For the ``WORKLOAD`` policy only. - **Example:** ``"workload": "MEDIUM"`` -================== =========================================================== - +Description + In a policy of type WORKLOAD, + it is necessary to specify how heavy the workload is. +Type + string +Values + - HIGH: Scale the frequency of this core to maximum. + - MEDIUM: Scale the frequency of this core to minimum. + - LOW: Scale up the frequency of this core. +Required + For the ``WORKLOAD`` policy only. +Example + ``"workload": "MEDIUM"`` -- 2.25.0