From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by dpdk.org (Postfix) with ESMTP id 64F061B018 for ; Thu, 25 Jan 2018 10:01:30 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga105.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 25 Jan 2018 01:01:28 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,411,1511856000"; d="scan'208";a="25310919" Received: from silpixa00398672.ir.intel.com ([10.237.223.111]) by fmsmga001.fm.intel.com with ESMTP; 25 Jan 2018 01:01:27 -0800 From: Harry van Haaren To: dev@dpdk.org Cc: Harry van Haaren , marko.kovacevic@intel.com Date: Thu, 25 Jan 2018 09:00:53 +0000 Message-Id: <1516870870-168223-2-git-send-email-harry.van.haaren@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1516870870-168223-1-git-send-email-harry.van.haaren@intel.com> References: <1516870870-168223-1-git-send-email-harry.van.haaren@intel.com> Subject: [dpdk-dev] [PATCH 01/18] doc/contrib: document dynamic logging format X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 25 Jan 2018 09:01:30 -0000 This commit adds a section to the DPDK style guide to set the dynamic logging formatting naming scheme. Signed-off-by: Harry van Haaren --- Maintainer: Cc: marko.kovacevic@intel.com --- doc/guides/contributing/coding_style.rst | 53 ++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index d8e4a0f..a859350 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -702,3 +702,56 @@ All Python code should work with Python 2.7+ and 3.2+ and be compliant with `PEP8 (Style Guide for Python Code) `_. The ``pep8`` tool can be used for testing compliance with the guidelines. + + +Dynamic Logging +--------------- + +DPDK provides infrastructure to perform logging during runtime. This is very +useful for enabling debug output without recompilation. To enable or disable +logging of a particular topic, the ``--log-level`` parameter can be provided +to EAL, which will change the log level. DPDK code can register topics, +which allows the user to adjust the log verbosity for that specific topic. + +In general, the naming scheme is as follows: ``type.section.name`` + + * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user`` + are the common options. + * Section refers to a specific area, for example a poll-mode-driver for an + ethernet device would use ``pmd.net``, while an eventdev PMD uses + ``pmd.event``. + * The name identifies the individual item that the log applies to. + The name section must align with + the directory that the PMD code resides. See examples below for clarity. + +Examples: + + * The virtio network PMD in ``drivers/net/virtio`` uses ``pmd.net.virtio`` + * The eventdev software poll mode driver in ``drivers/event/sw`` uses ``pmd.event.sw`` + * The octeontx mempool driver in ``drivers/mempool/octeontx`` uses ``pmd.mempool.octeontx`` + * The DPDK hash library in ``lib/librte_hash`` uses ``lib.hash`` + +Specializations +~~~~~~~~~~~~~~~ + +In addition to the above logging topic, any PMD or library can further split +logging output by using "specializations". A specialization could be the +difference between initialization code, and logs of events that occur at runtime. + +An example could be the initialization log messages getting one +specialization, while another specialization handles mailbox command logging. +Each PMD, library or component can create as many specializations as required. + +A specialization looks like this: + + * Initialization output: ``type.section.name.init`` + * PF/VF mailbox output: ``type.section.name.mbox`` + +A real world example is the i40e poll mode driver which exposes two +specializations, one for initialization ``pmd.i40e.init`` and the other for +the remaining driver logs ``pmd.i40e.driver``. + +Note that specializations have no formatting rules, but please follow +a precedent if one exists. In order to see all current log topics and +specializations, run the ``app/test`` binary, and use the ``dump_log_types`` +command. -- 2.7.4