+
+API Design
+^^^^^^^^^^
+
+The xstats API uses the ``name``, ``id``, and ``value`` to allow performant
+lookup of specific statistics. Performant lookup means two things;
+
+* No string comparisons with the ``name`` of the statistic in fast-path
+* Allow requesting of only the statistics of interest
+
+The API ensures these requirements are met by mapping the ``name`` of the
+statistic to a unique ``id``, which is used as a key for lookup in the fast-path.
+The API allows applications to request an array of ``id`` values, so that the
+PMD only performs the required calculations. Expected usage is that the
+application scans the ``name`` of each statistic, and caches the ``id``
+if it has an interest in that statistic. On the fast-path, the integer can be used
+to retrieve the actual ``value`` of the statistic that the ``id`` represents.
+
+API Functions
+^^^^^^^^^^^^^
+
+The API is built out of a small number of functions, which can be used to
+retrieve the number of statistics and the names, IDs and values of those
+statistics.
+
+* ``rte_eth_xstats_get_names_by_id()``: returns the names of the statistics. When given a
+ ``NULL`` parameter the function returns the number of statistics that are available.
+
+* ``rte_eth_xstats_get_id_by_name()``: Searches for the statistic ID that matches
+ ``xstat_name``. If found, the ``id`` integer is set.
+
+* ``rte_eth_xstats_get_by_id()``: Fills in an array of ``uint64_t`` values
+ with matching the provided ``ids`` array. If the ``ids`` array is NULL, it
+ returns all statistics that are available.
+
+
+Application Usage
+^^^^^^^^^^^^^^^^^
+
+Imagine an application that wants to view the dropped packet count. If no
+packets are dropped, the application does not read any other metrics for
+performance reasons. If packets are dropped, the application has a particular
+set of statistics that it requests. This "set" of statistics allows the app to
+decide what next steps to perform. The following code-snippets show how the
+xstats API can be used to achieve this goal.
+
+First step is to get all statistics names and list them:
+
+.. code-block:: c
+
+ struct rte_eth_xstat_name *xstats_names;
+ uint64_t *values;
+ int len, i;
+
+ /* Get number of stats */
+ len = rte_eth_xstats_get_names_by_id(port_id, NULL, NULL, 0);
+ if (len < 0) {
+ printf("Cannot get xstats count\n");
+ goto err;
+ }
+
+ xstats_names = malloc(sizeof(struct rte_eth_xstat_name) * len);
+ if (xstats_names == NULL) {
+ printf("Cannot allocate memory for xstat names\n");
+ goto err;
+ }
+
+ /* Retrieve xstats names, passing NULL for IDs to return all statistics */
+ if (len != rte_eth_xstats_get_names_by_id(port_id, xstats_names, NULL, len)) {
+ printf("Cannot get xstat names\n");
+ goto err;
+ }
+
+ values = malloc(sizeof(values) * len);
+ if (values == NULL) {
+ printf("Cannot allocate memory for xstats\n");
+ goto err;
+ }
+
+ /* Getting xstats values */
+ if (len != rte_eth_xstats_get_by_id(port_id, NULL, values, len)) {
+ printf("Cannot get xstat values\n");
+ goto err;
+ }
+
+ /* Print all xstats names and values */
+ for (i = 0; i < len; i++) {
+ printf("%s: %"PRIu64"\n", xstats_names[i].name, values[i]);
+ }
+
+The application has access to the names of all of the statistics that the PMD
+exposes. The application can decide which statistics are of interest, cache the
+ids of those statistics by looking up the name as follows:
+
+.. code-block:: c
+
+ uint64_t id;
+ uint64_t value;
+ const char *xstat_name = "rx_errors";
+
+ if(!rte_eth_xstats_get_id_by_name(port_id, xstat_name, &id)) {
+ rte_eth_xstats_get_by_id(port_id, &id, &value, 1);
+ printf("%s: %"PRIu64"\n", xstat_name, value);
+ }
+ else {
+ printf("Cannot find xstats with a given name\n");
+ goto err;
+ }
+
+The API provides flexibility to the application so that it can look up multiple
+statistics using an array containing multiple ``id`` numbers. This reduces the
+function call overhead of retrieving statistics, and makes lookup of multiple
+statistics simpler for the application.
+
+.. code-block:: c
+
+ #define APP_NUM_STATS 4
+ /* application cached these ids previously; see above */
+ uint64_t ids_array[APP_NUM_STATS] = {3,4,7,21};
+ uint64_t value_array[APP_NUM_STATS];
+
+ /* Getting multiple xstats values from array of IDs */
+ rte_eth_xstats_get_by_id(port_id, ids_array, value_array, APP_NUM_STATS);
+
+ uint32_t i;
+ for(i = 0; i < APP_NUM_STATS; i++) {
+ printf("%d: %"PRIu64"\n", ids_array[i], value_array[i]);
+ }
+
+
+This array lookup API for xstats allows the application create multiple
+"groups" of statistics, and look up the values of those IDs using a single API
+call. As an end result, the application is able to achieve its goal of
+monitoring a single statistic ("rx_errors" in this case), and if that shows
+packets being dropped, it can easily retrieve a "set" of statistics using the
+IDs array parameter to ``rte_eth_xstats_get_by_id`` function.
+
+NIC Reset API
+~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ int rte_eth_dev_reset(uint16_t port_id);
+
+Sometimes a port has to be reset passively. For example when a PF is
+reset, all its VFs should also be reset by the application to make them
+consistent with the PF. A DPDK application also can call this function
+to trigger a port reset. Normally, a DPDK application would invokes this
+function when an RTE_ETH_EVENT_INTR_RESET event is detected.
+
+It is the duty of the PMD to trigger RTE_ETH_EVENT_INTR_RESET events and
+the application should register a callback function to handle these
+events. When a PMD needs to trigger a reset, it can trigger an
+RTE_ETH_EVENT_INTR_RESET event. On receiving an RTE_ETH_EVENT_INTR_RESET
+event, applications can handle it as follows: Stop working queues, stop
+calling Rx and Tx functions, and then call rte_eth_dev_reset(). For
+thread safety all these operations should be called from the same thread.
+
+For example when PF is reset, the PF sends a message to notify VFs of
+this event and also trigger an interrupt to VFs. Then in the interrupt
+service routine the VFs detects this notification message and calls
+_rte_eth_dev_callback_process(dev, RTE_ETH_EVENT_INTR_RESET, NULL).
+This means that a PF reset triggers an RTE_ETH_EVENT_INTR_RESET
+event within VFs. The function _rte_eth_dev_callback_process() will
+call the registered callback function. The callback function can trigger
+the application to handle all operations the VF reset requires including
+stopping Rx/Tx queues and calling rte_eth_dev_reset().
+
+The rte_eth_dev_reset() itself is a generic function which only does
+some hardware reset operations through calling dev_unint() and
+dev_init(), and itself does not handle synchronization, which is handled
+by application.
+
+The PMD itself should not call rte_eth_dev_reset(). The PMD can trigger
+the application to handle reset event. It is duty of application to
+handle all synchronization before it calls rte_eth_dev_reset().
Code Review / deb_dpdk.git / blobdiff