From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id C56471B111 for ; Wed, 26 Sep 2018 15:41:36 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga102.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 26 Sep 2018 06:41:35 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,306,1534834800"; d="scan'208";a="83404421" Received: from silpixa00399952.ir.intel.com (HELO silpixa00399952.ger.corp.intel.com) ([10.237.223.64]) by FMSMGA003.fm.intel.com with ESMTP; 26 Sep 2018 06:41:34 -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 14:40:36 +0100 Message-Id: <20180926134037.43606-11-david.hunt@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180926134037.43606-1-david.hunt@intel.com> References: <20180914135406.52190-1-david.hunt@intel.com> <20180926134037.43606-1-david.hunt@intel.com> Subject: [dpdk-dev] [PATCH v4 10/11] 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 13:41:38 -0000 Also added meson/ninja build info Signed-off-by: David Hunt --- .../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..931a73f55 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:: console + + 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:: console + + {"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 intgers, 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:: console + + ""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:: console + + "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:: console + + "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:: console + + "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:: console + + "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:: console + + "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:: console + + "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:: console + + "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:: console + + "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:: console + + "resource_id": 10 + +JSON API Examples +~~~~~~~~~~~~~~~~~ + +Profile create example: + + .. code-block:: console + + {"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:: console + + {"profile": { + "name": "ubuntu", + "command": "destroy", + }} + +Power command example: + + .. code-block:: console + + {"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