Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/73997/?format=api
{ "id": 73997, "url": "http://patchwork.dpdk.org/api/patches/73997/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/patch/20200714101415.36890-1-ciara.power@intel.com/", "project": { "id": 1, "url": "http://patchwork.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": "<20200714101415.36890-1-ciara.power@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20200714101415.36890-1-ciara.power@intel.com", "date": "2020-07-14T10:14:15", "name": "doc: add more detail to telemetry guides", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "411f32e651e10b3e777f2df4c9c20d6d1bac904a", "submitter": { "id": 978, "url": "http://patchwork.dpdk.org/api/people/978/?format=api", "name": "Power, Ciara", "email": "ciara.power@intel.com" }, "delegate": { "id": 1, "url": "http://patchwork.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patchwork.dpdk.org/project/dpdk/patch/20200714101415.36890-1-ciara.power@intel.com/mbox/", "series": [ { "id": 11015, "url": "http://patchwork.dpdk.org/api/series/11015/?format=api", "web_url": "http://patchwork.dpdk.org/project/dpdk/list/?series=11015", "date": "2020-07-14T10:14:15", "name": "doc: add more detail to telemetry guides", "version": 1, "mbox": "http://patchwork.dpdk.org/series/11015/mbox/" } ], "comments": "http://patchwork.dpdk.org/api/patches/73997/comments/", "check": "success", "checks": "http://patchwork.dpdk.org/api/patches/73997/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 C5108A0543;\n\tTue, 14 Jul 2020 12:18:42 +0200 (CEST)", "from [92.243.14.124] (localhost [127.0.0.1])\n\tby dpdk.org (Postfix) with ESMTP id 1A68D1C295;\n\tTue, 14 Jul 2020 12:18:42 +0200 (CEST)", "from mga05.intel.com (mga05.intel.com [192.55.52.43])\n by dpdk.org (Postfix) with ESMTP id BCA2C1C0B7\n for <dev@dpdk.org>; Tue, 14 Jul 2020 12:18:40 +0200 (CEST)", "from orsmga001.jf.intel.com ([10.7.209.18])\n by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 14 Jul 2020 03:18:39 -0700", "from silpixa00399953.ir.intel.com (HELO\n silpixa00399953.ger.corp.intel.com) ([10.237.222.53])\n by orsmga001.jf.intel.com with ESMTP; 14 Jul 2020 03:18:38 -0700" ], "IronPort-SDR": [ "\n pdP7mRXTSZQcNU0Y5K1Mz3/F6skrJmB193XFx+1Cn1P1sVacIJpGV1DMqZXoWXCDRae6/ixK/z\n DpcLmqzKExiQ==", "\n y3AUtu8nC+MAwD0ZHphOj1mvrzw7MAh4233qbe+/GBgKye84Me2EcoAQxY+ynANSjYskxkKS7F\n 4MbhgmU7EBGg==" ], "X-IronPort-AV": [ "E=McAfee;i=\"6000,8403,9681\"; a=\"233724399\"", "E=Sophos;i=\"5.75,350,1589266800\"; d=\"scan'208\";a=\"233724399\"", "E=Sophos;i=\"5.75,350,1589266800\"; d=\"scan'208\";a=\"360342930\"" ], "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, 14 Jul 2020 11:14:15 +0100", "Message-Id": "<20200714101415.36890-1-ciara.power@intel.com>", "X-Mailer": "git-send-email 2.17.1", "Subject": "[dpdk-dev] [PATCH] 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 doc/guides/howto/telemetry.rst | 45 ++++-\n doc/guides/prog_guide/telemetry_lib.rst | 230 ++++++++++++++++++++++--\n 2 files changed, 250 insertions(+), 25 deletions(-)", "diff": "diff --git a/doc/guides/howto/telemetry.rst b/doc/guides/howto/telemetry.rst\nindex b4a34ed67..39cab99a7 100644\n--- a/doc/guides/howto/telemetry.rst\n+++ b/doc/guides/howto/telemetry.rst\n@@ -69,12 +69,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..d968f2169 100644\n--- a/doc/guides/prog_guide/telemetry_lib.rst\n+++ b/doc/guides/prog_guide/telemetry_lib.rst\n@@ -16,6 +16,166 @@ 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. An example of this can be seen in\n+ the EAL callback below.\n+\n+ .. code-block:: c\n+\n+ #define EAL_PARAM_REQ \"/eal/params\"\n+ #define EAL_APP_PARAM_REQ \"/eal/app_params\"\n+\n+ /* callback handler for telemetry library to report out EAL flags */\n+ int\n+ handle_eal_info_request(const char *cmd, const char *params __rte_unused,\n+ struct rte_tel_data *d)\n+ {\n+ char **args;\n+ int used = 0;\n+ int i = 0;\n+\n+ if (strcmp(cmd, EAL_PARAM_REQ) == 0)\n+ args = eal_args;\n+ else\n+ args = eal_app_args;\n+\n+ rte_tel_data_start_array(d, RTE_TEL_STRING_VAL);\n+ if (args == NULL || args[0] == NULL)\n+ return 0;\n+\n+ for ( ; args[i] != NULL; i++)\n+ used = rte_tel_data_add_array_string(d, args[i]);\n+ return used;\n+ }\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. An example of this being used is shown below.\n+\n+.. code-block:: c\n+\n+ static int\n+ handle_port_link_status(const char *cmd __rte_unused, const char *params,\n+ struct rte_tel_data *d)\n+ {\n+ static const char *status_str = \"status\";\n+ int ret, port_id;\n+ struct rte_eth_link link;\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+ ret = rte_eth_link_get(port_id, &link);\n+ if (ret < 0)\n+ return -1;\n+\n+ rte_tel_data_start_dict(d);\n+ if (!link.link_status) {\n+ rte_tel_data_add_dict_string(d, status_str, \"DOWN\");\n+ return 0;\n+ }\n+ rte_tel_data_add_dict_string(d, status_str, \"UP\");\n+ rte_tel_data_add_dict_u64(d, \"speed\", link.link_speed);\n+ rte_tel_data_add_dict_string(d, \"duplex\",\n+ (link.link_duplex == ETH_LINK_FULL_DUPLEX) ?\n+ \"full-duplex\" : \"half-duplex\");\n+ return 0;\n+ }\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+\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+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 +195,62 @@ 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+Using Commands\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+To use commands, with a DPDK app running (e.g. testpmd), use the\n+dpdk-telemetry.py script.\n \n-.. code-block:: c\n+ .. code-block:: console\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+ python usertools/dpdk-telemetry.py\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+When connected, the script displays the following, waiting for input.\n \n-.. code-block:: console\n+ .. code-block:: console\n \n- {\"/ethdev/list\": [0, 1]}\n+ Connecting to /var/run/dpdk/rte/dpdk_telemetry.v2\n+ {\"version\": \"DPDK 20.05.0-rc0\", \"pid\": 60285, \"max_output_len\": 16384}\n+ -->\n \n-For more information on the range of data functions available in the API,\n-please refer to the docs.\n+You can now input commands to send across the socket, and receive the\n+response. Some available commands are shown below.\n+\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+ --> /help,/ethdev/xstats\n+ {\"/help\": {\"/ethdev/xstats\": \"Returns the extended stats for a port.\n+ Parameters: int port_id\"}}\n", "prefixes": [] }