Show a patch.

GET /api/patches/74582/
HTTP 200 OK
Allow: GET, PUT, PATCH, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "id": 74582,
    "url": "https://patches.dpdk.org/api/patches/74582/",
    "web_url": "https://patches.dpdk.org/patch/74582/",
    "project": {
        "id": 1,
        "url": "https://patches.dpdk.org/api/projects/1/",
        "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"
    },
    "msgid": "<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/",
        "name": "Power, Ciara",
        "email": "ciara.power@intel.com"
    },
    "delegate": {
        "id": 1,
        "url": "https://patches.dpdk.org/api/users/1/",
        "username": "tmonjalo",
        "first_name": "Thomas",
        "last_name": "Monjalon",
        "email": "thomas@monjalon.net"
    },
    "mbox": "https://patches.dpdk.org/patch/74582/mbox/",
    "series": [
        {
            "id": 11219,
            "url": "https://patches.dpdk.org/api/series/11219/",
            "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": {},
    "headers": {
        "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>",
        "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\""
        ],
        "IronPort-SDR": [
            "\n WPDY3lEutHx9B0hzT5bPGKdbnB/y1a2C52k+TgcmxrH6mZuhbcAKjgK7fcddMXEA7mqioHezDV\n WKU+0t9ajEbg==",
            "\n wU+N+nSyrt2ZR2HVHg7C0bL+s2ALzAaLfoLWeymnzZ/2RAAQO98rvnqNyIoHHCu3+IdBTViRyY\n AUU87T2ID3yQ=="
        ],
        "X-Amp-File-Uploaded": "False",
        "Precedence": "list",
        "X-Mailman-Version": "2.1.15",
        "X-Original-To": "patchwork@inbox.dpdk.org",
        "List-Post": "<mailto:dev@dpdk.org>",
        "X-BeenThere": "dev@dpdk.org",
        "List-Id": "DPDK patches and discussions <dev.dpdk.org>",
        "Subject": "[dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides",
        "Sender": "\"dev\" <dev-bounces@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"
        ],
        "X-Amp-Result": "SKIPPED(no attachment in message)",
        "List-Archive": "<http://mails.dpdk.org/archives/dev/>",
        "X-Mailer": "git-send-email 2.17.1",
        "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>",
        "X-ExtLoop1": "1",
        "Date": "Tue, 21 Jul 2020 17:09:24 +0100",
        "To": "kevin.laatz@intel.com",
        "From": "Ciara Power <ciara.power@intel.com>",
        "Errors-To": "dev-bounces@dpdk.org",
        "Cc": "dev@dpdk.org, bruce.richardson@intel.com,\n Ciara Power <ciara.power@intel.com>",
        "List-Help": "<mailto:dev-request@dpdk.org?subject=help>",
        "Message-Id": "<20200721160924.62082-1-ciara.power@intel.com>",
        "Return-Path": "<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"
    ]
}