Re: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON interface API info

["Yao, Lei A" <lei.a.yao@intel.com>]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Hunt
> Sent: Thursday, August 30, 2018 6:54 PM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>; Hunt, David
> <david.hunt@intel.com>
> Subject: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON
> interface API info
> 
> 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 ]
> +
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