> -----Original Message-----
> From: dev [mailto:dev-boun...@dpdk.org] On Behalf Of David Hunt
> Sent: Thursday, August 30, 2018 6:54 PM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnam...@intel.com>; Hunt, David
> <david.h...@intel.com>
> Subject: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON
> interface API info
>
> Signed-off-by: David Hunt <david.h...@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 ]
> +
Do you think we need document following three key here?
min_packet_thresh
avg_packet_thresh
max_packet_thresh
I see them in the code but not documented.
> +: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
