From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <david.hunt@intel.com>
Received: from mga18.intel.com (mga18.intel.com [134.134.136.126])
by dpdk.org (Postfix) with ESMTP id 529034CAF
for <dev@dpdk.org>; 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 <david.hunt@intel.com>
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 <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Thu, 30 Aug 2018 10:55:03 -0000
Signed-off-by: David Hunt <david.hunt@intel.com>
---
.../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