From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id D32D569F9 for ; Mon, 30 May 2016 12:48:26 +0200 (CEST) Received: from orsmga003.jf.intel.com ([10.7.209.27]) by fmsmga104.fm.intel.com with ESMTP; 30 May 2016 03:48:26 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,389,1459839600"; d="scan'208";a="817650959" Received: from rhorton-mobl.ger.corp.intel.com (HELO VM.ir.intel.com) ([163.33.228.212]) by orsmga003.jf.intel.com with ESMTP; 30 May 2016 03:48:25 -0700 From: Remy Horton To: dev@dpdk.org Date: Mon, 30 May 2016 11:48:12 +0100 Message-Id: <1464605292-4599-11-git-send-email-remy.horton@intel.com> X-Mailer: git-send-email 2.5.5 In-Reply-To: <1464605292-4599-1-git-send-email-remy.horton@intel.com> References: <1464605292-4599-1-git-send-email-remy.horton@intel.com> Subject: [dpdk-dev] [PATCH v3 10/10] doc: update xstats documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 30 May 2016 10:48:27 -0000 Signed-off-by: Remy Horton --- doc/guides/prog_guide/poll_mode_drv.rst | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst index 7698692..6cd86dd 100644 --- a/doc/guides/prog_guide/poll_mode_drv.rst +++ b/doc/guides/prog_guide/poll_mode_drv.rst @@ -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 -- 2.5.5