DPDK patches and discussions
 help / color / mirror / Atom feed
From: David Hunt <david.hunt@intel.com>
To: dev@dpdk.org
Cc: john.mcnamara@intel.com, david.hunt@intel.com
Subject: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON interface API info
Date: Thu, 30 Aug 2018 11:54:21 +0100	[thread overview]
Message-ID: <20180830105422.1198-7-david.hunt@intel.com> (raw)
In-Reply-To: <20180830105422.1198-1-david.hunt@intel.com>

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

  parent reply	other threads:[~2018-08-30 10:55 UTC|newest]

Thread overview: 110+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-08-30 10:54 [dpdk-dev] [PATCH v1 0/7] add json power policy interface for containers David Hunt
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 1/7] examples/power: add checks around hypervisor David Hunt
2018-08-30 16:59   ` Stephen Hemminger
2018-09-12 10:53     ` Hunt, David
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 2/7] lib/power: add changes for host commands/policies David Hunt
2018-08-30 16:59   ` Stephen Hemminger
2018-09-12 10:51     ` Hunt, David
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 3/7] examples/power: add necessary changes to guest app David Hunt
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 4/7] examples/power: add host channel to power manager David Hunt
2018-09-04  7:31   ` Yao, Lei A
2018-09-12 12:07     ` Hunt, David
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 5/7] examples/power: add json string handling David Hunt
2018-08-30 17:00   ` Stephen Hemminger
2018-08-31 13:55     ` Hunt, David
2018-09-12 10:54     ` Hunt, David
2018-08-30 10:54 ` David Hunt [this message]
2018-09-04  5:17   ` [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON interface API info Yao, Lei A
2018-09-12 11:31     ` Hunt, David
2018-08-30 10:54 ` [dpdk-dev] [PATCH v1 7/7] examples/power: add json example files David Hunt
2018-09-12 14:49 ` [dpdk-dev] [PATCH v2 0/7] add json power policy interface for containers David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 1/7] examples/power: add checks around hypervisor David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 2/7] lib/power: add changes for host commands/policies David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 3/7] examples/power: add necessary changes to guest app David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 4/7] examples/power: add host channel to power manager David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 5/7] examples/power: add json string handling David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 6/7] doc/vm_power_manager: add JSON interface API info David Hunt
2018-09-12 14:49   ` [dpdk-dev] [PATCH v2 7/7] examples/power: add json example files David Hunt
2018-09-14 13:53   ` [dpdk-dev] [PATCH v3 0/8] add json power policy interface for containers David Hunt
2018-09-14 13:53     ` [dpdk-dev] [PATCH v3 1/8] examples/power: add checks around hypervisor David Hunt
2018-09-25  9:20       ` Burakov, Anatoly
2018-09-25 13:47         ` Hunt, David
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 2/8] lib/power: add changes for host commands/policies David Hunt
2018-09-25  9:21       ` Burakov, Anatoly
2018-09-25 13:47         ` Hunt, David
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 3/8] examples/power: add necessary changes to guest app David Hunt
2018-09-25  9:23       ` Burakov, Anatoly
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 4/8] examples/power: add host channel to power manager David Hunt
2018-09-25  9:48       ` Burakov, Anatoly
2018-09-25 13:55         ` Hunt, David
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 5/8] examples/power: add json string handling David Hunt
2018-09-25 11:27       ` Burakov, Anatoly
2018-09-25 14:00         ` Hunt, David
2018-09-25 14:15           ` Burakov, Anatoly
2018-09-25 15:15             ` Hunt, David
2018-09-25 15:31               ` Burakov, Anatoly
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 6/8] examples/power: add meson/ninja build support David Hunt
2018-09-14 14:01       ` Bruce Richardson
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 7/8] doc/vm_power_manager: add JSON interface API info David Hunt
2018-09-14 13:54     ` [dpdk-dev] [PATCH v3 8/8] examples/power: add json example files David Hunt
2018-09-26 13:40     ` [dpdk-dev] [PATCH v4 0/11] add json power policy interface for containers David Hunt
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 01/11] examples/power: add checks around hypervisor David Hunt
2018-09-26 13:54         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 02/11] examples/power: allow for number of vms to be zero David Hunt
2018-09-26 13:54         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 03/11] lib/power: add changes for host commands/policies David Hunt
2018-09-26 13:54         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 04/11] examples/power: add necessary changes to guest app David Hunt
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 05/11] examples/power: add host channel to power manager David Hunt
2018-09-26 14:22         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 06/11] examples/power: increase allowed number of clients David Hunt
2018-09-26 14:23         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 07/11] examples/power: add json string handling David Hunt
2018-09-26 14:24         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 08/11] examples/power: clean up verbose messages David Hunt
2018-09-26 14:25         ` Burakov, Anatoly
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 09/11] examples/power: add meson/ninja build support David Hunt
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 10/11] doc/vm_power_manager: add JSON interface API info David Hunt
2018-09-26 14:32         ` Kovacevic, Marko
2018-09-26 13:40       ` [dpdk-dev] [PATCH v4 11/11] examples/power: add json example files David Hunt
2018-09-26 15:58         ` Kovacevic, Marko
2018-09-26 16:14           ` Hunt, David
2018-09-26 16:37       ` [dpdk-dev] [PATCH v5 0/10] add json power policy interface for containers David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 01/10] examples/power: add checks around hypervisor David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 02/10] examples/power: allow for number of vms to be zero David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 03/10] lib/power: add changes for host commands/policies David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 04/10] examples/power: add necessary changes to guest app David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 05/10] examples/power: add host channel to power manager David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 06/10] examples/power: increase allowed number of clients David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 07/10] examples/power: add json string handling David Hunt
2018-09-30  1:54           ` Yao, Lei A
2018-10-01 11:03             ` Hunt, David
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 08/10] examples/power: clean up verbose messages David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 09/10] examples/power: add meson/ninja build support David Hunt
2018-09-26 16:37         ` [dpdk-dev] [PATCH v5 10/10] doc/vm_power_manager: add JSON interface API info David Hunt
2018-09-29  2:42           ` Yao, Lei A
2018-10-01 11:02             ` Hunt, David
2018-10-02  8:43         ` [dpdk-dev] [PATCH v6 0/10] add json power policy interface for containers David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 01/10] examples/power: add checks around hypervisor David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 02/10] examples/power: allow for number of vms to be zero David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 03/10] lib/power: add changes for host commands/policies David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 04/10] examples/power: add necessary changes to guest app David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 05/10] examples/power: add host channel to power manager David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 06/10] examples/power: increase allowed number of clients David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 07/10] examples/power: add json string handling David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 08/10] examples/power: clean up verbose messages David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 09/10] examples/power: add meson/ninja build support David Hunt
2018-10-02  8:43           ` [dpdk-dev] [PATCH v6 10/10] doc/vm_power_manager: add JSON interface API info David Hunt
2018-10-17 13:05           ` [dpdk-dev] [PATCH v7 0/10] add json power policy interface for containers David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 01/10] examples/power: add checks around hypervisor David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 02/10] examples/power: allow for number of vms to be zero David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 03/10] lib/power: add changes for host commands/policies David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 04/10] examples/power: add necessary changes to guest app David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 05/10] examples/power: add host channel to power manager David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 06/10] examples/power: increase allowed number of clients David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 07/10] examples/power: add json string handling David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 08/10] examples/power: clean up verbose messages David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 09/10] examples/power: add meson/ninja build support David Hunt
2018-10-17 13:05             ` [dpdk-dev] [PATCH v7 10/10] doc/vm_power_manager: add JSON interface API info David Hunt
2018-10-26  0:05               ` Thomas Monjalon
2018-10-26  8:45             ` [dpdk-dev] [PATCH v7 0/10] add json power policy interface for containers Thomas Monjalon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20180830105422.1198-7-david.hunt@intel.com \
    --to=david.hunt@intel.com \
    --cc=dev@dpdk.org \
    --cc=john.mcnamara@intel.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).