X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Ftelemetry_lib.rst;h=6ea16e9491fd8542c79c0f321a3d71ba2fe76720;hb=cbcda56cced98ec6cc214ed89df0703ddeb7723e;hp=8563a7200e28734cdd138adefaec7f5ca925f516;hpb=1474a341d547bf0484c0b8a3f060dc41054e24aa;p=dpdk.git diff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst index 8563a7200e..6ea16e9491 100644 --- a/doc/guides/prog_guide/telemetry_lib.rst +++ b/doc/guides/prog_guide/telemetry_lib.rst @@ -16,47 +16,151 @@ function that will format the library specific stats into the correct data format, when requested. -Registering Commands --------------------- +Creating Callback Functions +--------------------------- -Libraries and applications must register commands to make their information -available via the Telemetry library. This involves providing a string command -in the required format ("/library/command"), the callback function that -will handle formatting the information when required, and help text for the -command. An example showing ethdev commands being registered is shown below: + +Function Type +~~~~~~~~~~~~~ + +When creating a callback function in a library/app, it must be of the following type: + +.. code-block:: c + + typedef int (*telemetry_cb)(const char *cmd, const char *params, + struct rte_tel_data *info); + +An example callback function is shown below: + +.. code-block:: c + + static int + handle_example_cmd(const char *cmd __rte_unused, const char *params __rte_unused, + struct rte_tel_data *d) + +For more detail on the callback function parameters, please refer to the +`definition in the API doc +`_ + +**Example Callback** + +This callback is an example of handling multiple commands in one callback, +and also shows the use of params which holds a port ID. The ``params`` input needs +to be validated and converted to the required integer type for port ID. The ``cmd`` +parameter is then used in a comparison to decide which command was requested, +which will decide what port information should fill the ``rte_tel_data`` structure. .. code-block:: c - rte_telemetry_register_cmd("/ethdev/list", handle_port_list, - "Returns list of available ethdev ports. Takes no parameters"); - rte_telemetry_register_cmd("/ethdev/xstats", handle_port_xstats, - "Returns the extended stats for a port. Parameters: int port_id"); - rte_telemetry_register_cmd("/ethdev/link_status", handle_port_link_status, - "Returns the link status for a port. Parameters: int port_id"); + int + handle_cmd_request(const char *cmd, const char *params, + struct rte_tel_data *d) + { + int port_id, used = 0; + + if (params == NULL || strlen(params) == 0 || !isdigit(*params)) + return -1; + + port_id = atoi(params); + if (!rte_eth_dev_is_valid_port(port_id)) + return -1; + + if (strcmp(cmd, "/cmd_1") == 0) + /* Build up port data requested for command 1 */ + else + /* Build up port data requested for command 2 */ + return used; + } -Formatting JSON response ------------------------- + +Formatting Data +~~~~~~~~~~~~~~~ The callback function provided by the library must format its telemetry information in the required data format. The Telemetry library provides a data -utilities API to build up the response. For example, the ethdev library provides a -list of available ethdev ports in a formatted data response, constructed using the -following functions to build up the list: +utilities API to build up the data structure with the required information. +The telemetry library is then responsible for formatting the data structure +into a JSON response before sending to the client. + + +Array Data +^^^^^^^^^^ + +Some data will need to be formatted in a list structure. For example, if a +callback needs to return five integer values in the data response, it can be +constructed using the following functions to build up the list: .. code-block:: c - rte_tel_data_start_array(d, RTE_TEL_INT_VAL); - RTE_ETH_FOREACH_DEV(port_id) - rte_tel_data_add_array_int(d, port_id); + rte_tel_data_start_array(d, RTE_TEL_INT_VAL); + for(i = 0; i < 5; i++) + rte_tel_data_add_array_int(d, i); -The data structure is then formatted into a JSON response before sending. -The resulting response shows the port list data provided above by the handler -function in ethdev, placed in a JSON reply by telemetry: +The resulting response to the client shows the list data provided above +by the handler function in the library/app, placed in a JSON reply by telemetry:: -.. code-block:: console + {"/example_lib/five_ints": [0, 1, 2, 3, 4]} - {"/ethdev/list": [0, 1]} + +Dictionary Data +^^^^^^^^^^^^^^^ + +For data that needs to be structured in a dictionary with key/value pairs, +the data utilities API can also be used. For example, some information about +a brownie recipe is constructed in the callback function shown below: + +.. code-block:: c + + rte_tel_data_start_dict(d); + rte_tel_data_add_dict_string(d, "Recipe", "Brownies"); + rte_tel_data_add_dict_int(d, "Prep time (mins)", 25); + rte_tel_data_add_dict_int(d, "Cooking time (mins)", 30); + rte_tel_data_add_dict_int(d, "Serves", 16); + +The resulting response to the client shows the key/value data provided above +by the handler function in telemetry, placed in a JSON reply by telemetry:: + + {"/example_lib/brownie_recipe": {"Recipe": "Brownies", "Prep time (mins)": 25, + "Cooking time (mins)": 30, "Serves": 16}} + + +String Data +^^^^^^^^^^^ + +Telemetry also supports single string data. +The data utilities API can again be used for this, see the example below. + +.. code-block:: c + + rte_tel_data_string(d, "This is an example string"); + +Giving the following response to the client:: + + {"/example_lib/string_example": "This is an example string"} For more information on the range of data functions available in the API, -please refer to the docs. +please refer to the `API doc `_ + + +Registering Commands +-------------------- + +Libraries and applications must register commands to make their information +available via the Telemetry library. This involves providing a string command +in the required format ("/library/command"), the callback function that +will handle formatting the information when required, and help text for the +command. An example command being registered is shown below: + +.. code-block:: c + + rte_telemetry_register_cmd("/example_lib/string_example", handle_string, + "Returns an example string. Takes no parameters"); + + +Using Commands +-------------- + +To use commands, with a DPDK app running (e.g. testpmd), use the +``dpdk-telemetry.py`` script. +For details on its use, see the :doc:`../howto/telemetry`.