[dpdk-dev,v3,10/10] doc: update xstats documentation
Commit Message
Signed-off-by: Remy Horton <remy.horton@intel.com>
---
doc/guides/prog_guide/poll_mode_drv.rst | 25 +++++++++++++++++++++----
1 file changed, 21 insertions(+), 4 deletions(-)
Comments
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Remy Horton
> Sent: Monday, May 30, 2016 11:48 AM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v3 10/10] doc: update xstats documentation
>
> Signed-off-by: Remy Horton <remy.horton@intel.com>
Good clear update.
Acked-by: John McNamara <john.mcnamara@intel.com>
@@ -299,10 +299,27 @@ Extended Statistics API
~~~~~~~~~~~~~~~~~~~~~~~
The extended statistics API allows each individual PMD to expose a unique set
-of statistics. The client of the API provides an array of
-``struct rte_eth_xstats`` type. Each ``struct rte_eth_xstats`` contains a
-string and value pair. The amount of xstats exposed, and position of the
-statistic in the array must remain constant during runtime.
+of statistics. Accessing these from application programs is done via three
+functions:
+
+* ``rte_eth_xstats_count``: Fetches the number of extended statistics.
+* ``rte_eth_xstats_get``: Fills in an array of ``struct rte_eth_xstats``
+ with extended statistics.
+* ``rte_eth_xstats_names``: Fills in an array of ``struct rte_eth_name``
+ with extended statistic name lookup information.
+
+Each ``struct rte_eth_xstats`` contains an identifier and value pair, and
+each ``struct rte_eth_xstats_name`` contains an identifier and string pair.
+Each identifier within ``struct rte_eth_xstats`` must have a corresponding
+entry in ``struct rte_eth_xstats_name`` with a matching identifier. These
+identifiers, as well as the number of extended statistic exposed, must
+remain constant during runtime.
+
+Note that extended statistic identifiers are driver-specific, and hence
+might not be the same for different ports. Although it is expected that
+drivers will make the identifiers used within ``struct rte_eth_xstats`` and
+``struct rte_eth_xstats_name`` entries match the entries' array index, this
+property should not be relied on by applications for lookups.
A naming scheme exists for the strings exposed to clients of the API. This is
to allow scraping of the API for statistics of interest. The naming scheme uses