From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 95DFE2862 for ; Tue, 4 Sep 2018 07:18:15 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Sep 2018 22:18:14 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,328,1531810800"; d="scan'208";a="87394570" Received: from fmsmsx108.amr.corp.intel.com ([10.18.124.206]) by orsmga001.jf.intel.com with ESMTP; 03 Sep 2018 22:18:14 -0700 Received: from fmsmsx102.amr.corp.intel.com (10.18.124.200) by FMSMSX108.amr.corp.intel.com (10.18.124.206) with Microsoft SMTP Server (TLS) id 14.3.319.2; Mon, 3 Sep 2018 22:18:14 -0700 Received: from shsmsx152.ccr.corp.intel.com (10.239.6.52) by FMSMSX102.amr.corp.intel.com (10.18.124.200) with Microsoft SMTP Server (TLS) id 14.3.319.2; Mon, 3 Sep 2018 22:18:13 -0700 Received: from shsmsx102.ccr.corp.intel.com ([169.254.2.226]) by SHSMSX152.ccr.corp.intel.com ([169.254.6.150]) with mapi id 14.03.0319.002; Tue, 4 Sep 2018 13:17:39 +0800 From: "Yao, Lei A" To: "Hunt, David" , "dev@dpdk.org" CC: "Mcnamara, John" , "Hunt, David" Thread-Topic: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON interface API info Thread-Index: AQHUQFAZZYHLFmlB1UqyezFE37xRJKTfm4yw Date: Tue, 4 Sep 2018 05:17:38 +0000 Message-ID: <2DBBFF226F7CF64BAFCA79B681719D953A53BA56@shsmsx102.ccr.corp.intel.com> References: <20180830105422.1198-1-david.hunt@intel.com> <20180830105422.1198-7-david.hunt@intel.com> In-Reply-To: <20180830105422.1198-7-david.hunt@intel.com> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiOTdhYjZkZjUtZmQ4MC00Y2ZlLWEzMDctMGQxNDE0NmFhMTc4IiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX05UIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE3LjEwLjE4MDQuNDkiLCJUcnVzdGVkTGFiZWxIYXNoIjoiYjd2Z0hjRGtSKzhLc09jSW1uNkMzNG50XC9GZXFNQ2Q0TnFGREsxUW9KeW9Vc1A5UDRMSmkrekpGYVZNYXBDU04ifQ== x-ctpclassification: CTP_NT dlp-product: dlpe-windows dlp-version: 11.0.400.15 dlp-reaction: no-action x-originating-ip: [10.239.127.40] Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Subject: Re: [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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 04 Sep 2018 05:18:16 -0000 > -----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 ; Hunt, David > > Subject: [dpdk-dev] [PATCH v1 6/7] doc/vm_power_manager: add JSON > interface API info >=20 > Signed-off-by: David Hunt > --- > .../sample_app_ug/vm_power_management.rst | 195 > ++++++++++++++++++ > 1 file changed, 195 insertions(+) >=20 > 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. >=20 >=20 > + > +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, wri= ting > +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 differe= nt > +depending on which type is being sent. > + > +The pairs are the format of standard JSON name-value pairs. The value ty= pe > +varies between the different name/value pairs, and may be intgers, strin= gs, > +arrays, etc. Examples of policies follow later in this document. The all= owed > +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 bu= sy > + 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 > -------------------------------------------- >=20 > -- > 2.17.1