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
+<https://doc.dpdk.org/api/rte__telemetry_8h.html#a41dc74d561442bb6184ee6dd1f9b5bcc>`_
+
+**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 <https://doc.dpdk.org/api-20.05/rte__telemetry_8h.html>`_
+
+
+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`.
git.droids-corp.org / dpdk.git / blobdiff