From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 1FD7A1B3B3 for ; Wed, 26 Sep 2018 18:43:09 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 26 Sep 2018 09:43:06 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,306,1534834800"; d="scan'208";a="266907092" Received: from silpixa00399952.ir.intel.com (HELO silpixa00399952.ger.corp.intel.com) ([10.237.223.64]) by fmsmga006.fm.intel.com with ESMTP; 26 Sep 2018 09:37:44 -0700 From: David Hunt To: dev@dpdk.org Cc: john.mcnamara@intel.com, stephen@networkplumber.org, lei.a.yao@intel.com, anatoly.burakov@intel.com, David Hunt Date: Wed, 26 Sep 2018 17:37:27 +0100 Message-Id: <20180926163727.47337-11-david.hunt@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180926163727.47337-1-david.hunt@intel.com> References: <20180926134037.43606-1-david.hunt@intel.com> <20180926163727.47337-1-david.hunt@intel.com> Subject: [dpdk-dev] [PATCH v5 10/10] doc/vm_power_manager: add JSON interface API info 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, 26 Sep 2018 16:43:10 -0000 Also added meson/ninja build info Signed-off-by: David Hunt Acked-by: Marko Kovacevic --- .../sample_app_ug/vm_power_management.rst | 272 +++++++++++++++++- 1 file changed, 270 insertions(+), 2 deletions(-) diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index 855570d6b..1afe42809 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -199,7 +199,7 @@ see :doc:`compiling`. The application is located in the ``vm_power_manager`` sub-directory. -To build just the ``vm_power_manager`` application: +To build just the ``vm_power_manager`` application using ``make``: .. code-block:: console @@ -208,6 +208,22 @@ To build just the ``vm_power_manager`` application: cd ${RTE_SDK}/examples/vm_power_manager/ make +The resulting binary will be ${RTE_SDK}/build/examples/vm_power_manager + +To build just the ``vm_power_manager`` application using ``meson/ninja``: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + cd ${RTE_SDK} + meson build + cd build + ninja + meson configure -Dexamples=vm_power_manager + ninja + +The resulting binary will be ${RTE_SDK}/build/examples/dpdk-vm_power_manager + Running ~~~~~~~ @@ -337,6 +353,242 @@ monitoring of branch ratio on cores doing busy polling via PMDs. and will need to be adjusted for different workloads. + +JSON API +~~~~~~~~ + +In addition to the command line interface for host command and a virtio-serial +interface for VM power policies, there is also a JSON interface through which +power commands and policies can be sent. This functionality adds a dependency +on the Jansson library, and the Jansson development package must be installed +on the system before the JSON parsing functionality is included in the app. +This is achieved by: + + .. code-block:: javascript + + apt-get install libjansson-dev + +The command and package name may be different depending on your operating +system. It's worth noting that the app will successfully build without this +package present, but a warning is shown during compilation, and the JSON +parsing functionality will not be present in the app. + +Sending a command or policy to the power manager application is achieved by +simply opening a fifo file, writing a JSON string to that fifo, and closing +the file. + +The fifo is at /tmp/powermonitor/fifo + +The jason string can be a policy or instruction, and takes the following +format: + + .. code-block:: javascript + + {"packet_type": { + "pair_1": value, + "pair_2": value + }} + +The 'packet_type' header can contain one of two values, depending on +whether a policy or power command is being sent. The two possible values are +"policy" and "instruction", and the expected name-value pairs is different +depending on which type is being sent. + +The pairs are the format of standard JSON name-value pairs. The value type +varies between the different name/value pairs, and may be integers, strings, +arrays, etc. Examples of policies follow later in this document. The allowed +names and value types are as follows: + + +:Pair Name: "name" +:Description: 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: + + .. code-block:: javascript + + "name", "ubuntu2" + + +:Pair Name: "command" +:Description: The type of packet we're sending to the power manager. We can be + creating or destroying a policy, or sending a direct command to adjust + the frequency of a core, similar to the command line interface. +:Type: string +:Values: + + :CREATE: used when creating a new policy, + :DESTROY: used when removing a policy, + :POWER: used when sending an immediate command, max, min, etc. +:Required: yes +:Example: + + .. code-block:: javascript + + "command", "CREATE" + + +:Pair Name: "policy_type" +:Description: Type of policy to apply. Please see vm_power_manager documentation + for more information on the types of policies that may be used. +:Type: string +:Values: + + :TIME: Time-of-day policy. Frequencies of the relevant cores are + scaled up/down depending on busy and quiet hours. + :TRAFFIC: This policy takes statistics from the NIC and scales up + and down accordingly. + :WORKLOAD: This policy looks at how heavily loaded the cores are, + and scales up and down accordingly. + :BRANCH_RATIO: This out-of-band policy can look at the ratio between + branch hits and misses on a core, and is useful for detecting + how much packet processing a core is doing. +:Required: only for CREATE/DESTROY command +:Example: + + .. code-block:: javascript + + "policy_type", "TIME" + +: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: array with list of hour numbers, (0-23) +:Required: only for TIME policy +:Example: + + .. code-block:: javascript + + "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ] + +:Pair Name: "quiet_hours" +:Description: The hours of the day in which we scale down the cores for quiet + times. +:Type: array of integers +:Values: array with list of hour numbers, (0-23) +:Required: only for TIME policy +:Example: + + .. code-block:: javascript + + "quiet_hours":[ 2, 3, 4, 5, 6 ] + +:Pair Name: "avg_packet_thresh" +:Description: Threshold below which the frequency will be set to min for + the TRAFFIC policy. If the traffic rate is above this and below max, the + frequency will be set to medium. +:Type: integer +:Values: The number of packets below which the TRAFFIC policy applies the + minimum frequency, or medium frequency if between avg and max thresholds. +:Required: only for TRAFFIC policy +:Example: + + .. code-block:: javascript + + "avg_packet_thresh": 100000 + +:Pair Name: "max_packet_thresh" +:Description: Threshold above which the frequency will be set to max for + the TRAFFIC policy +:Type: integer +:Values: The number of packets per interval above which the TRAFFIC policy + applies the maximum frequency +:Required: only for TRAFFIC policy +:Example: + + .. code-block:: javascript + + "max_packet_thresh": 500000 + +:Pair Name: "core_list" +:Description: The cores to which to apply the policy. +:Type: array of integers +:Values: array with list of virtual CPUs. +:Required: only policy CREATE/DESTROY +:Example: + + .. code-block:: javascript + + "core_list":[ 10, 11 ] + +:Pair Name: "unit" +:Description: the type of power operation to apply in the command +:Type: string +:Values: + + :SCALE_MAX: Scale frequency of this core to maximum + :SCALE_MIN: Scale frequency of this core to minimum + :SCALE_UP: Scale up frequency of this core + :SCALE_DOWN: Scale down frequency of this core + :ENABLE_TURBO: Enable Turbo Boost for this core + :DISABLE_TURBO: Disable Turbo Boost for this core +:Required: only for POWER instruction +:Example: + + .. code-block:: javascript + + "unit", "SCALE_MAX" + +:Pair Name: "resource_id" +:Description: The core to which to apply the power command. +:Type: integer +:Values: valid core id for VM or host OS. +:Required: only POWER instruction +:Example: + + .. code-block:: javascript + + "resource_id": 10 + +JSON API Examples +~~~~~~~~~~~~~~~~~ + +Profile create example: + + .. code-block:: javascript + + {"policy": { + "name": "ubuntu", + "command": "create", + "policy_type": "TIME", + "busy_hours":[ 17, 18, 19, 20, 21, 22, 23 ], + "quiet_hours":[ 2, 3, 4, 5, 6 ], + "core_list":[ 11 ] + }} + +Profile destroy example: + + .. code-block:: javascript + + {"profile": { + "name": "ubuntu", + "command": "destroy", + }} + +Power command example: + + .. code-block:: javascript + + {"command": { + "name": "ubuntu", + "unit": "SCALE_MAX", + "resource_id": 10 + }} + +To send a JSON string to the Power Manager application, simply paste the +example JSON string into a text file and cat it into the fifo: + + .. code-block:: console + + cat file.json >/tmp/powermonitor/fifo + +The console of the Power Manager application should indicate the command that +was just received via the fifo. + Compiling and Running the Guest Applications -------------------------------------------- @@ -366,7 +618,7 @@ 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: +To build just the ``guest_vm_power_manager`` application using ``make``: .. code-block:: console @@ -375,6 +627,22 @@ To build just the ``guest_vm_power_manager`` application: cd ${RTE_SDK}/examples/vm_power_manager/guest_cli/ make +The resulting binary will be ${RTE_SDK}/build/examples/guest_cli + +To build just the ``vm_power_manager`` application using ``meson/ninja``: + +.. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + cd ${RTE_SDK} + meson build + cd build + ninja + meson configure -Dexamples=vm_power_manager/guest_cli + ninja + +The resulting binary will be ${RTE_SDK}/build/examples/guest_cli + Running ~~~~~~~ -- 2.17.1