[v1,6/7] doc/vm_power_manager: add JSON interface API info
Checks
Commit Message
Signed-off-by: David Hunt <david.hunt@intel.com>
---
.../sample_app_ug/vm_power_management.rst | 195 ++++++++++++++++++
1 file changed, 195 insertions(+)
Comments
> -----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
Hi Lei,
On 4/9/2018 6:17 AM, Yao, Lei A wrote:
>
>> -----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
>> +~~~~~~~~
>> +
--snip--
>> +: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.
>
Good catch. I missed these in the docs. Also I checked the code there
these are
used, and only two are needed. These are avg and max.
Below, avg, the freq is set to minimum
Between avg and max, the freq us set to medium
Above max, the freq is set to maximum.
I'll remove the minimum from the code, seeing as it's not used, and
document avg and max.
Rgds,
Dave.
--snip--
@@ -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
--------------------------------------------