X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Fpoll_mode_drv.rst;h=802fb8f8888fff0a5055162bdda432d3f9bdd036;hb=7b2a704c4e84dcc11ffa381293d2c3d686a999b8;hp=8780ba30b651bb6293333728d4fea927e498422c;hpb=2542ad53d8676fdadc14f88ca8bef5bf68a2a606;p=dpdk.git

diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst
index 8780ba30b6..802fb8f888 100644
--- a/doc/guides/prog_guide/poll_mode_drv.rst
+++ b/doc/guides/prog_guide/poll_mode_drv.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -294,3 +294,69 @@ Ethernet Device API
 ~~~~~~~~~~~~~~~~~~~
 
 The Ethernet device API exported by the Ethernet PMDs is described in the *DPDK API Reference*.
+
+Extended Statistics API
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The extended statistics API allows each individual PMD to expose a unique set
+of statistics. Accessing these from application programs is done via two
+functions:
+
+* ``rte_eth_xstats_get``: Fills in an array of ``struct rte_eth_xstat``
+  with extended statistics.
+* ``rte_eth_xstats_get_names``: Fills in an array of
+  ``struct rte_eth_xstat_name`` with extended statistic name lookup
+  information.
+
+Each ``struct rte_eth_xstat`` contains an identifier and value pair, and
+each ``struct rte_eth_xstat_name`` contains an identifier and string pair.
+Each identifier within ``struct rte_eth_xstat`` must have a corresponding
+entry in ``struct rte_eth_xstat_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_xstat`` and
+``struct rte_eth_xstat_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
+strings split by a single underscore ``_``. The scheme is as follows:
+
+* direction
+* detail 1
+* detail 2
+* detail n
+* unit
+
+Examples of common statistics xstats strings, formatted to comply to the scheme
+proposed above:
+
+* ``rx_bytes``
+* ``rx_crc_errors``
+* ``tx_multicast_packets``
+
+The scheme, although quite simple, allows flexibility in presenting and reading
+information from the statistic strings. The following example illustrates the
+naming scheme:``rx_packets``. In this example, the string is split into two
+components. The first component ``rx`` indicates that the statistic is
+associated with the receive side of the NIC.  The second component ``packets``
+indicates that the unit of measure is packets.
+
+A more complicated example: ``tx_size_128_to_255_packets``. In this example,
+``tx`` indicates transmission, ``size``  is the first detail, ``128`` etc are
+more details, and ``packets`` indicates that this is a packet counter.
+
+Some additions in the metadata scheme are as follows:
+
+* If the first part does not match ``rx`` or ``tx``, the statistic does not
+  have an affinity with either receive of transmit.
+
+* If the first letter of the second part is ``q`` and this ``q`` is followed
+  by a number, this statistic is part of a specific queue.
+
+An example where queue numbers are used is as follows: ``tx_q7_bytes`` which
+indicates this statistic applies to queue number 7, and represents the number
+of transmitted bytes on that queue.