From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id 529034CAF for ; Thu, 30 Aug 2018 12:55:03 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 30 Aug 2018 03:55:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,306,1531810800"; d="scan'208";a="84641520" Received: from silpixa00399952.ir.intel.com (HELO silpixa00399952.ger.corp.intel.com) ([10.237.223.64]) by fmsmga004.fm.intel.com with ESMTP; 30 Aug 2018 03:55:02 -0700 From: David Hunt To: dev@dpdk.org Cc: john.mcnamara@intel.com, david.hunt@intel.com Date: Thu, 30 Aug 2018 11:54:21 +0100 Message-Id: <20180830105422.1198-7-david.hunt@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180830105422.1198-1-david.hunt@intel.com> References: <20180830105422.1198-1-david.hunt@intel.com> Subject: [dpdk-dev] [PATCH v1 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: Thu, 30 Aug 2018 10:55:03 -0000 Signed-off-by: David Hunt --- .../sample_app_ug/vm_power_management.rst | 195 ++++++++++++++++++ 1 file changed, 195 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..13a325eae 100644 --- a/doc/guides/sample_app_ug/vm_power_management.rst +++ b/doc/guides/sample_app_ug/vm_power_management.rst @@ -337,6 +337,201 @@ 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. 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: "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