Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/74582/?format=api
{ "id": 74582, "url": "https://patches.dpdk.org/api/patches/74582/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20200721160924.62082-1-ciara.power@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20200721160924.62082-1-ciara.power@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20200721160924.62082-1-ciara.power@intel.com", "date": "2020-07-21T16:09:24", "name": "[v2] doc: add more detail to telemetry guides", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "d0c4da52cb9be3714451252dacafbd2442620d26", "submitter": { "id": 978, "url": "https://patches.dpdk.org/api/people/978/?format=api", "name": "Power, Ciara", "email": "ciara.power@intel.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20200721160924.62082-1-ciara.power@intel.com/mbox/", "series": [ { "id": 11219, "url": "https://patches.dpdk.org/api/series/11219/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=11219", "date": "2020-07-21T16:09:24", "name": "[v2] doc: add more detail to telemetry guides", "version": 2, "mbox": "https://patches.dpdk.org/series/11219/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/74582/comments/", "check": "warning", "checks": "https://patches.dpdk.org/api/patches/74582/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from dpdk.org (dpdk.org [92.243.14.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id B3AD8A0526;\n\tTue, 21 Jul 2020 18:14:45 +0200 (CEST)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 6BD9B1BFE7;\n\tTue, 21 Jul 2020 18:14:44 +0200 (CEST)", "from mga03.intel.com (mga03.intel.com [134.134.136.65])\n by dpdk.org (Postfix) with ESMTP id A5F2B1BFE4\n for <dev@dpdk.org>; Tue, 21 Jul 2020 18:14:42 +0200 (CEST)", "from orsmga003.jf.intel.com ([10.7.209.27])\n by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 21 Jul 2020 09:14:41 -0700", "from silpixa00399953.ir.intel.com (HELO\n silpixa00399953.ger.corp.intel.com) ([10.237.222.53])\n by orsmga003.jf.intel.com with ESMTP; 21 Jul 2020 09:14:40 -0700" ], "IronPort-SDR": [ "\n WPDY3lEutHx9B0hzT5bPGKdbnB/y1a2C52k+TgcmxrH6mZuhbcAKjgK7fcddMXEA7mqioHezDV\n WKU+0t9ajEbg==", "\n wU+N+nSyrt2ZR2HVHg7C0bL+s2ALzAaLfoLWeymnzZ/2RAAQO98rvnqNyIoHHCu3+IdBTViRyY\n AUU87T2ID3yQ==" ], "X-IronPort-AV": [ "E=McAfee;i=\"6000,8403,9689\"; a=\"150146771\"", "E=Sophos;i=\"5.75,379,1589266800\"; d=\"scan'208\";a=\"150146771\"", "E=Sophos;i=\"5.75,379,1589266800\"; d=\"scan'208\";a=\"283908568\"" ], "X-Amp-Result": "SKIPPED(no attachment in message)", "X-Amp-File-Uploaded": "False", "X-ExtLoop1": "1", "From": "Ciara Power <ciara.power@intel.com>", "To": "kevin.laatz@intel.com", "Cc": "dev@dpdk.org, bruce.richardson@intel.com,\n Ciara Power <ciara.power@intel.com>", "Date": "Tue, 21 Jul 2020 17:09:24 +0100", "Message-Id": "<20200721160924.62082-1-ciara.power@intel.com>", "X-Mailer": "git-send-email 2.17.1", "Subject": "[dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "This patch adds examples to the Telemetry HowTo guide, to demonstrate\ncommands that use parameters. The programmer's guide is also modified to\ninclude details on writing a callback function for a new command.\n\nSigned-off-by: Ciara Power <ciara.power@intel.com>\n\n---\nv2:\n - Replaced examples of using commands in the programmer's guide with\n a link to the HowTo guide.\n - Added an example showing the use of a single string value.\n - Replaced inline functions with a synthetic example function below\n the list of parameters.\n---\n doc/guides/howto/telemetry.rst | 46 ++++++-\n doc/guides/prog_guide/telemetry_lib.rst | 172 ++++++++++++++++++++----\n 2 files changed, 187 insertions(+), 31 deletions(-)", "diff": "diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst\nindex b4a34ed67..7e8a5d6f3 100644\n--- a/doc/guides/howto/telemetry.rst\n+++ b/doc/guides/howto/telemetry.rst\n@@ -1,6 +1,7 @@\n .. SPDX-License-Identifier: BSD-3-Clause\n Copyright(c) 2020 Intel Corporation.\n \n+.. _telemetry:\n \n DPDK Telemetry User Guide\n =========================\n@@ -69,12 +70,43 @@ and query information using the telemetry client python script.\n -->\n \n #. The user can now input commands to send across the socket, and receive the\n- response.\n+ response. Some available commands are shown below.\n \n- .. code-block:: console\n+ * List all commands.\n+\n+ .. code-block:: console\n+\n+ --> /\n+ {\"/\": [\"/\", \"/eal/app_params\", \"/eal/params\", \"/ethdev/list\",\n+ \"/ethdev/link_status\", \"/ethdev/xstats\", \"/help\", \"/info\"]}\n+\n+ * Get the list of ethdev ports.\n+\n+ .. code-block:: console\n+\n+ --> /ethdev/list\n+ {\"/ethdev/list\": [0, 1]}\n+\n+ .. Note::\n+\n+ For commands that expect a parameter, use \",\" to separate the command\n+ and parameter. See examples below.\n+\n+ * Get extended statistics for an ethdev port.\n+\n+ .. code-block:: console\n+\n+ --> /ethdev/xstats,0\n+ {\"/ethdev/xstats\": {\"rx_good_packets\": 0, \"tx_good_packets\": 0,\n+ \"rx_good_bytes\": 0, \"tx_good_bytes\": 0, \"rx_missed_errors\": 0,\n+ ...\n+ \"tx_priority7_xon_to_xoff_packets\": 0}}\n+\n+ * Get the help text for a command. This will indicate what parameters are\n+ required. Pass the command as a parameter.\n+\n+ .. code-block:: console\n \n- --> /\n- {\"/\": [\"/\", \"/eal/app_params\", \"/eal/params\", \"/ethdev/list\",\n- \"/ethdev/link_status\", \"/ethdev/xstats\", \"/help\", \"/info\"]}\n- --> /ethdev/list\n- {\"/ethdev/list\": [0, 1]}\n+ --> /help,/ethdev/xstats\n+ {\"/help\": {\"/ethdev/xstats\": \"Returns the extended stats for a port.\n+ Parameters: int port_id\"}}\ndiff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst\nindex 8563a7200..694cef26b 100644\n--- a/doc/guides/prog_guide/telemetry_lib.rst\n+++ b/doc/guides/prog_guide/telemetry_lib.rst\n@@ -16,6 +16,150 @@ function that will format the library specific stats into the correct data\n format, when requested.\n \n \n+Creating Callback Functions\n+---------------------------\n+\n+\n+Function Type\n+~~~~~~~~~~~~~\n+\n+When creating a callback function in a library/app, it must be of the following type:\n+\n+.. code-block:: c\n+\n+ typedef int (*telemetry_cb)(const char *cmd, const char *params,\n+ struct rte_tel_data *info);\n+\n+For example, the callback for \"/ethdev/list\" is:\n+\n+.. code-block:: c\n+\n+ static int\n+ handle_port_list(const char *cmd __rte_unused, const char *params __rte_unused,\n+ struct rte_tel_data *d)\n+\n+The parameters for a callback function are:\n+\n+* **cmd**\n+\n+ This is the command requested by the client, e.g. \"/ethdev/list\".\n+ For most callbacks this may be unused, however it will allow for handling\n+ multiple commands in one callback function. This can be seen in the example\n+ callback below.\n+\n+* **params**\n+\n+ This will contain any parameters required for the command. For example\n+ when calling \"/ethdev/link_status,0\", the port ID will be passed to the\n+ callback function in params. This can be seen in the example callback below.\n+\n+* **d**\n+\n+ The rte_tel_data pointer will be used by the callback function to format the\n+ requested data to be returned to Telemetry. The data APIs provided will\n+ enable adding to the struct, examples of this are shown later in this\n+ document.\n+\n+**Example Callback**\n+\n+This callback is an example of handling multiple commands in one callback,\n+and also shows the use of params which holds a port ID. The params input needs\n+to be validated and converted to the required integer type for port ID. The cmd\n+parameter is then used in a comparison to decide which command was requested,\n+which will decide what port information should fill the rte_tel_data structure.\n+\n+.. code-block:: c\n+\n+ int\n+ handle_cmd_request(const char *cmd, const char *params,\n+ struct rte_tel_data *d)\n+ {\n+ int port_id, used = 0;\n+\n+ if (params == NULL || strlen(params) == 0 || !isdigit(*params))\n+ return -1;\n+\n+ port_id = atoi(params);\n+ if (!rte_eth_dev_is_valid_port(port_id))\n+ return -1;\n+\n+ if (strcmp(cmd, \"/cmd_1\") == 0)\n+ /* Build up port data requested for command 1 */\n+ else\n+ /* Build up port data requested for command 2 */\n+\n+ return used;\n+ }\n+\n+\n+Formatting Data\n+~~~~~~~~~~~~~~~\n+\n+The callback function provided by the library must format its telemetry\n+information in the required data format. The Telemetry library provides a data\n+utilities API to build up the data structure with the required information.\n+The telemetry library is then responsible for formatting the data structure\n+into a JSON response before sending to the client.\n+\n+* **Array Data**\n+\n+ Some data will need to be formatted in a list structure. For example, the\n+ ethdev library provides a list of available ethdev ports in a formatted data\n+ response, constructed using the following functions to build up the list:\n+\n+ .. code-block:: c\n+\n+ rte_tel_data_start_array(d, RTE_TEL_INT_VAL);\n+ RTE_ETH_FOREACH_DEV(port_id)\n+ rte_tel_data_add_array_int(d, port_id);\n+\n+ The resulting response to the client shows the port list data provided above\n+ by the handler function in ethdev, placed in a JSON reply by telemetry:\n+\n+ .. code-block:: console\n+\n+ {\"/ethdev/list\": [0, 1]}\n+\n+* **Dictionary Data**\n+\n+ For data that needs to be structured in a dictionary with key/value pairs,\n+ the data utilities API can also be used. For example, telemetry provides an\n+ info command that has multiple key/value pairs, constructed in the callback\n+ function shown below:\n+\n+ .. code-block:: c\n+\n+ rte_tel_data_start_dict(d);\n+ rte_tel_data_add_dict_string(d, \"version\", rte_version());\n+ rte_tel_data_add_dict_int(d, \"pid\", getpid());\n+ rte_tel_data_add_dict_int(d, \"max_output_len\", MAX_OUTPUT_LEN);\n+\n+ The resulting response to the client shows the key/value data provided above\n+ by the handler function in telemetry, placed in a JSON reply by telemetry:\n+\n+ .. code-block:: console\n+\n+ {\"/info\": {\"version\": \"DPDK 20.08.0-rc0\", \"pid\": 3838, \"max_output_len\": 16384}}\n+\n+* **String Data**\n+\n+ Telemetry also supports single string data. The data utilities API can again\n+ be used for this, see the example below.\n+\n+ .. code-block:: c\n+\n+ rte_tel_data_string(d, \"This is an example string\");\n+\n+ Giving the following response to the client:\n+\n+ .. code-block:: console\n+\n+ {\"/string_example\": \"This is an example string\"}\n+\n+For more information on the range of data functions available in the API,\n+please refer to the docs.\n+\n+\n Registering Commands\n --------------------\n \n@@ -35,28 +179,8 @@ command. An example showing ethdev commands being registered is shown below:\n \"Returns the link status for a port. Parameters: int port_id\");\n \n \n-Formatting JSON response\n-------------------------\n-\n-The callback function provided by the library must format its telemetry\n-information in the required data format. The Telemetry library provides a data\n-utilities API to build up the response. For example, the ethdev library provides a\n-list of available ethdev ports in a formatted data response, constructed using the\n-following functions to build up the list:\n+Using Commands\n+--------------\n \n-.. code-block:: c\n-\n- rte_tel_data_start_array(d, RTE_TEL_INT_VAL);\n- RTE_ETH_FOREACH_DEV(port_id)\n- rte_tel_data_add_array_int(d, port_id);\n-\n-The data structure is then formatted into a JSON response before sending.\n-The resulting response shows the port list data provided above by the handler\n-function in ethdev, placed in a JSON reply by telemetry:\n-\n-.. code-block:: console\n-\n- {\"/ethdev/list\": [0, 1]}\n-\n-For more information on the range of data functions available in the API,\n-please refer to the docs.\n+To use commands, with a DPDK app running (e.g. testpmd), use the\n+dpdk-telemetry.py script. For details on its use, see the :ref:`telemetry`.\n", "prefixes": [ "v2" ] }