DPDK patches and discussions
 help / color / mirror / Atom feed
From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: Bruce Richardson <bruce.richardson@intel.com>,
	Chengwen Feng <fengchengwen@huawei.com>,
	David Marchand <david.marchand@redhat.com>
Subject: [PATCH v4 1/2] doc/contributing: provide coding details for dynamic logging
Date: Thu, 20 Jul 2023 12:05:39 +0100	[thread overview]
Message-ID: <20230720110540.231342-2-bruce.richardson@intel.com> (raw)
In-Reply-To: <20230720110540.231342-1-bruce.richardson@intel.com>

While the section on dynamic logging in the contributors guide covered
the details of the logging naming scheme, it failed to cover exactly how
the component developer, i.e. the contributor, could actually use
dynamic logging in their component.

Fix this by splitting the details of the naming scheme into a separate
subsection, and adding to the introduction on logging, a recommendation
(and example) to use RTE_LOG_REGISTER_DEFAULT.

Similarly, when discussing specialization, include a reference to the
RTE_LOG_REGISTER_SUFFIX macro.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Chengwen Feng <fengchengwen@huawei.com>
Reviewed-by: David Marchand <david.marchand@redhat.com>
---
 doc/guides/contributing/coding_style.rst | 22 ++++++++++++++++++++++
 lib/cfgfile/rte_cfgfile.c                |  2 ++
 2 files changed, 24 insertions(+)

diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index 00d6270624..383942a601 100644
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -803,6 +803,26 @@ 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.
 
+To register a library or driver for dynamic logging, using the standardized naming scheme described below,
+use ``RTE_LOG_REGISTER_DEFAULT`` macro to define a log-type variable inside your component's main C file.
+Thereafter, it is usual to define a macro or macros inside your component to make logging more convenient.
+
+For example, the ``rte_cfgfile`` library defines:
+
+.. literalinclude:: ../../../lib/cfgfile/rte_cfgfile.c
+    :language: c
+    :start-after: Setting up dynamic logging 8<
+    :end-before: >8 End of setting up dynamic logging
+
+.. note::
+
+   The statically-defined log types defined in ``rte_log.h`` are for legacy components,
+   and they will likely be removed in a future release.
+   Do not add new entries to this file.
+
+Dynamic Logging Naming Scheme
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In general, the naming scheme is as follows: ``type.section.name``
 
  * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user``
@@ -837,6 +857,8 @@ A specialization looks like this:
  * Initialization output: ``type.section.name.init``
  * PF/VF mailbox output: ``type.section.name.mbox``
 
+These specializations are created using the ``RTE_LOG_REGISTER_SUFFIX`` macro.
+
 A real world example is the i40e poll mode driver which exposes two
 specializations, one for initialization ``pmd.net.i40e.init`` and the other for
 the remaining driver logs ``pmd.net.i40e.driver``.
diff --git a/lib/cfgfile/rte_cfgfile.c b/lib/cfgfile/rte_cfgfile.c
index 9fa7d010ef..eefba6e408 100644
--- a/lib/cfgfile/rte_cfgfile.c
+++ b/lib/cfgfile/rte_cfgfile.c
@@ -27,11 +27,13 @@ struct rte_cfgfile {
 	struct rte_cfgfile_section *sections;
 };
 
+/* Setting up dynamic logging 8< */
 RTE_LOG_REGISTER_DEFAULT(cfgfile_logtype, INFO);
 
 #define CFG_LOG(level, fmt, args...)					\
 	rte_log(RTE_LOG_ ## level, cfgfile_logtype, "%s(): " fmt "\n",	\
 		__func__, ## args)
+/* >8 End of setting up dynamic logging */
 
 /** when we resize a file structure, how many extra entries
  * for new sections do we add in */
-- 
2.39.2


  reply	other threads:[~2023-07-20 11:05 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-06-13 14:33 [PATCH 0/2] Improve docs on getting info on running process Bruce Richardson
2023-06-13 14:33 ` [PATCH 1/2] doc/contributing: provide coding details for dynamic logging Bruce Richardson
2023-06-13 14:33 ` [PATCH 2/2] doc/contributing: guidelines for logging, tracing and telemetry Bruce Richardson
2023-06-13 15:21   ` Stephen Hemminger
2023-06-13 19:38   ` Morten Brørup
2023-06-14  8:36     ` Bruce Richardson
2023-06-14  9:39       ` Morten Brørup
2023-06-14 11:35   ` Ferruh Yigit
2023-06-15 11:51   ` Jerin Jacob
2023-06-20 17:07 ` [PATCH v2 0/2] Improve docs on getting info on running process Bruce Richardson
2023-06-20 17:07   ` [PATCH v2 1/2] doc/contributing: provide coding details for dynamic logging Bruce Richardson
2023-07-04  6:20     ` fengchengwen
2023-07-04  7:46     ` David Marchand
2023-06-20 17:07   ` [PATCH v2 2/2] doc/contributing: guidelines for logging, tracing and telemetry Bruce Richardson
2023-07-04  7:54     ` David Marchand
2023-07-18 16:48 ` [PATCH v3 0/2] Improve docs on getting info on running process Bruce Richardson
2023-07-18 16:48   ` [PATCH v3 1/2] doc/contributing: provide coding details for dynamic logging Bruce Richardson
2023-07-18 20:23     ` Ferruh Yigit
2023-07-18 16:48   ` [PATCH v3 2/2] doc/contributing: guidelines for logging, tracing and telemetry Bruce Richardson
2023-07-18 20:23     ` Ferruh Yigit
2023-07-19  1:07     ` lihuisong (C)
2023-07-20 10:57       ` Jerin Jacob
2023-07-18 17:40   ` [PATCH v3 0/2] Improve docs on getting info on running process Stephen Hemminger
2023-07-19  8:32     ` Bruce Richardson
2023-07-19 14:01     ` Bruce Richardson
2023-07-20 11:05 ` [PATCH v4 " Bruce Richardson
2023-07-20 11:05   ` Bruce Richardson [this message]
2023-07-20 11:05   ` [PATCH v4 2/2] doc/contributing: guidelines for logging, tracing and telemetry Bruce Richardson
2023-07-25  9:51     ` Thomas Monjalon
2023-07-20 12:38   ` [PATCH v4 0/2] Improve docs on getting info on running process Ferruh Yigit

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20230720110540.231342-2-bruce.richardson@intel.com \
    --to=bruce.richardson@intel.com \
    --cc=david.marchand@redhat.com \
    --cc=dev@dpdk.org \
    --cc=fengchengwen@huawei.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).