Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/5438/?format=api
{ "id": 5438, "url": "https://patches.dpdk.org/api/patches/5438/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/1434406064-25303-1-git-send-email-cristian.dumitrescu@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<1434406064-25303-1-git-send-email-cristian.dumitrescu@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/1434406064-25303-1-git-send-email-cristian.dumitrescu@intel.com", "date": "2015-06-15T22:07:44", "name": "[dpdk-dev,v2] doc: guidelines for library statistics", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "af4a7819c9ba0d55105f69ca0767b65eee273db9", "submitter": { "id": 19, "url": "https://patches.dpdk.org/api/people/19/?format=api", "name": "Cristian Dumitrescu", "email": "cristian.dumitrescu@intel.com" }, "delegate": null, "mbox": "https://patches.dpdk.org/project/dpdk/patch/1434406064-25303-1-git-send-email-cristian.dumitrescu@intel.com/mbox/", "series": [], "comments": "https://patches.dpdk.org/api/patches/5438/comments/", "check": "pending", "checks": "https://patches.dpdk.org/api/patches/5438/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [IPv6:::1])\n\tby dpdk.org (Postfix) with ESMTP id 516DE5A88;\n\tTue, 16 Jun 2015 00:07:51 +0200 (CEST)", "from mga02.intel.com (mga02.intel.com [134.134.136.20])\n\tby dpdk.org (Postfix) with ESMTP id C0C2E5A65\n\tfor <dev@dpdk.org>; Tue, 16 Jun 2015 00:07:49 +0200 (CEST)", "from orsmga002.jf.intel.com ([10.7.209.21])\n\tby orsmga101.jf.intel.com with ESMTP; 15 Jun 2015 15:07:48 -0700", "from irvmail001.ir.intel.com ([163.33.26.43])\n\tby orsmga002.jf.intel.com with ESMTP; 15 Jun 2015 15:07:47 -0700", "from sivswdev01.ir.intel.com (sivswdev01.ir.intel.com\n\t[10.237.217.45])\n\tby irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id\n\tt5FM7lsS024072; Mon, 15 Jun 2015 23:07:47 +0100", "from sivswdev01.ir.intel.com (localhost [127.0.0.1])\n\tby sivswdev01.ir.intel.com with ESMTP id t5FM7lFY025343;\n\tMon, 15 Jun 2015 23:07:47 +0100", "(from cfdumitr@localhost)\n\tby sivswdev01.ir.intel.com with id t5FM7lIU025339;\n\tMon, 15 Jun 2015 23:07:47 +0100" ], "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.13,621,1427785200\"; d=\"scan'208\";a=\"747217602\"", "From": "Cristian Dumitrescu <cristian.dumitrescu@intel.com>", "To": "dev@dpdk.org", "Date": "Mon, 15 Jun 2015 23:07:44 +0100", "Message-Id": "<1434406064-25303-1-git-send-email-cristian.dumitrescu@intel.com>", "X-Mailer": "git-send-email 1.7.4.1", "Subject": "[dpdk-dev] [PATCH v2] doc: guidelines for library statistics", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "patches and discussions about DPDK <dev.dpdk.org>", "List-Unsubscribe": "<http://dpdk.org/ml/options/dev>,\n\t<mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://dpdk.org/ml/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<http://dpdk.org/ml/listinfo/dev>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Signed-off-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>\n---\n doc/guides/guidelines/index.rst | 1 +\n doc/guides/guidelines/statistics.rst | 104 ++++++++++++++++++++++++++++++++++\n 2 files changed, 105 insertions(+), 0 deletions(-)\n create mode 100644 doc/guides/guidelines/statistics.rst", "diff": "diff --git a/doc/guides/guidelines/index.rst b/doc/guides/guidelines/index.rst\nindex b2b0a92..c01f958 100644\n--- a/doc/guides/guidelines/index.rst\n+++ b/doc/guides/guidelines/index.rst\n@@ -6,3 +6,4 @@ Guidelines\n :numbered:\n \n coding_style\n+ statistics\ndiff --git a/doc/guides/guidelines/statistics.rst b/doc/guides/guidelines/statistics.rst\nnew file mode 100644\nindex 0000000..bc91723\n--- /dev/null\n+++ b/doc/guides/guidelines/statistics.rst\n@@ -0,0 +1,104 @@\n+Library Statistics\n+==================\n+\n+Description\n+-----------\n+\n+This document describes the guidelines for DPDK library-level statistics counter\n+support. This includes guidelines for turning library statistics on and off and\n+requirements for preventing ABI changes when implementing statistics.\n+\n+\n+Mechanism to allow the application to turn library statistics on and off\n+------------------------------------------------------------------------\n+\n+Each library that maintains statistics counters should provide a single build\n+time flag that decides whether the statistics counter collection is enabled or\n+not. This flag should be exposed as a variable within the DPDK configuration\n+file. When this flag is set, all the counters supported by current library are\n+collected for all the instances of every object type provided by the library.\n+When this flag is cleared, none of the counters supported by the current library\n+are collected for any instance of any object type provided by the library:\n+\n+.. code-block:: console\n+\n+\t# DPDK file config/common_linuxapp, config/common_bsdapp, etc.\n+\tCONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n\n+\n+The default value for this DPDK configuration file variable (either \"yes\" or\n+\"no\") is decided by each library.\n+\n+\n+Prevention of ABI changes due to library statistics support\n+-----------------------------------------------------------\n+\n+The layout of data structures and prototype of functions that are part of the\n+library API should not be affected by whether the collection of statistics\n+counters is turned on or off for the current library. In practical terms, this\n+means that space should always be allocated in the API data structures for\n+statistics counters and the statistics related API functions are always built\n+into the code, regardless of whether the statistics counter collection is turned\n+on or off for the current library.\n+\n+When the collection of statistics counters for the current library is turned\n+off, the counters retrieved through the statistics related API functions should\n+have a default value of zero.\n+\n+\n+Motivation to allow the application to turn library statistics on and off\n+-------------------------------------------------------------------------\n+\n+It is highly recommended that each library provides statistics counters to allow\n+an application to monitor the library-level run-time events. Typical counters\n+are: number of packets received/dropped/transmitted, number of buffers\n+allocated/freed, number of occurrences for specific events, etc.\n+\n+However, the resources consumed for library-level statistics counter collection\n+have to be spent out of the application budget and the counters collected by\n+some libraries might not be relevant to the current application. In order to\n+avoid any unwanted waste of resources and/or performance impacts, the\n+application should decide at build time whether the collection of library-level\n+statistics counters should be turned on or off for each library individually.\n+\n+Library-level statistics counters can be relevant or not for specific\n+applications:\n+\n+* For Application A, counters maintained by Library X are always relevant and\n+the application needs to use them to implement certain features, such as traffic\n+accounting, logging, application-level statistics, etc. In this case,\n+the application requires that collection of statistics counters for Library X is\n+always turned on.\n+\n+* For Application B, counters maintained by Library X are only useful during the\n+application debug stage and are not relevant once debug phase is over. In this\n+case, the application may decide to turn on the collection of Library X\n+statistics counters during the debug phase and at a later stage turn them off.\n+\n+* For Application C, counters maintained by Library X are not relevant at all.\n+It might be that the application maintains its own set of statistics counters\n+that monitor a different set of run-time events (e.g. number of connection\n+requests, number of active users, etc). It might also be that the application\n+uses multiple libraries (Library X, Library Y, etc) and it is interested in the\n+statistics counters of Library Y, but not in those of Library X. In this case,\n+the application may decide to turn the collection of statistics counters off for\n+Library X and on for Library Y.\n+\n+The statistics collection consumes a certain amount of CPU resources (cycles,\n+cache bandwidth, memory bandwidth, etc) that depends on:\n+\n+* Number of libraries used by the current application that have statistics\n+counters collection turned on.\n+\n+* Number of statistics counters maintained by each library per object type\n+instance (e.g. per port, table, pipeline, thread, etc).\n+\n+* Number of instances created for each object type supported by each library.\n+\n+* Complexity of the statistics logic collection for each counter: when only\n+some occurrences of a specific event are valid, additional logic is typically\n+needed to decide whether the current occurrence of the event should be counted\n+or not. For example, in the event of packet reception, when only TCP packets\n+with destination port within a certain range should be recorded, conditional\n+branches are usually required. When processing a burst of packets that have been\n+validated for header integrity, counting the number of bits set in a bitmask\n+might be needed.\n", "prefixes": [ "dpdk-dev", "v2" ] }