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 B73354CA1 for ; Wed, 12 Sep 2018 16:50:49 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 12 Sep 2018 07:50:47 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,365,1531810800"; d="scan'208";a="261983342" Received: from silpixa00399952.ir.intel.com (HELO silpixa00399952.ger.corp.intel.com) ([10.237.223.64]) by fmsmga005.fm.intel.com with ESMTP; 12 Sep 2018 07:49:40 -0700 From: David Hunt To: dev@dpdk.org Cc: john.mcnamara@intel.com, stephen@networkplumber.org, lei.a.yao@intel.com, David Hunt Date: Wed, 12 Sep 2018 15:49:29 +0100 Message-Id: <20180912144930.50578-7-david.hunt@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180912144930.50578-1-david.hunt@intel.com> References: <20180830105422.1198-1-david.hunt@intel.com> <20180912144930.50578-1-david.hunt@intel.com> Subject: [dpdk-dev] [PATCH v2 6/7] 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, 12 Sep 2018 14:50:50 -0000 Signed-off-by: David Hunt --- .../sample_app_ug/vm_power_management.rst | 236 ++++++++++++++++++ 1 file changed, 236 insertions(+) diff --git a/doc/guides/sample_app_ug/vm_power_management.rst b/doc/guides/sample_app_ug/vm_power_management.rst index 855570d6b..b5b0179d2 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -337,6 +337,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.0 + +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.0 + +The console of the Power Manager application should indicate the command that +was just received via the fifo. + Compiling and Running the Guest Applications -------------------------------------------- -- 2.17.1