From 49ef927f7d3e6c9be4e6a0b81ee3bea28960db11 Mon Sep 17 00:00:00 2001
From: Martin Willers <M.Willers@gmx.net>
Date: Mon, 17 May 2021 02:51:06 +0200
Subject: Make nonverbose mode non exclusive (#300)

* Make Non-Verbose mode non-exclusive

Switching to global Non-Verbose mode now does not force Verbose messages to
also be sent as Non-Verbose ones anymore. That would not make any sense,
because Verbose messages don't have a MessageId and thus are all getting
the same MessageId of 65535.

Instead, setting global "Non-Verbose" mode will allow both Verbose and
Non-Verbose messages to be sent in a single session.
The "Verbose-APIs" (e.g. dlt_user_log_write_start()) will then only write
Verbose messages, whereas the "Non-Verbose APIs" (e.g. dlt_user_log_write_start_id())
will then only write Non-Verbose messages.

Signed-off-by: Martin Willers <M.Willers@gmx.net>
---
 doc/dlt_for_developers.md | 48 +++++++++++++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 18 deletions(-)

(limited to 'doc')

diff --git a/doc/dlt_for_developers.md b/doc/dlt_for_developers.md
index 1b30f86..1c4ef53 100644
--- a/doc/dlt_for_developers.md
+++ b/doc/dlt_for_developers.md
@@ -560,9 +560,14 @@ int main(int argc, const char* argv[])
 
 ### Logging command
 
-DLT provides functions and macros for logging, whereas the interface for
-Verbose and Non-Verbose differs. The following table shows an example of all 4
-types for logging using a constant string and an integer.
+DLT provides functions that allow for flexible construction of messages
+with an arbitrary number of arguments. Both Verbose and Non-Verbose
+messages are supported, with different APIs. Sending a message using
+these functions require multiple function calls, for starting message
+construction, adding the arguments, and sending off the message.
+
+The following table shows an example of all 4 types for logging
+using a constant string and an integer.
 
 #### Verbose vs. Non-Verbose API
 
@@ -606,32 +611,39 @@ if (dlt_user_log_write_start_id(&ctx, &ctxdata, DLT_LOG_INFO, 42) > 0) {
 }
 ```
 
-Drawback of that solution is that the developer has to decide during
-development if Verbose or Non-Verbose mode shall be used and the code most
-likely ends up as written in the dlt-example-user application:
+#### Statefulness of Verbose/Non-Verbose
 
-```
-if (gflag) {
-    /* Non-verbose mode */
-    DLT_LOG_ID(ctx, DLT_LOG_INFO, 42 /* unique msg ID */, DLT_INT(num),
-               DLT_STRING(text));
-}
-else {
-    /* Verbose mode */
-    DLT_LOG(ctx, DLT_LOG_INFO, DLT_INT(num), DLT_STRING(text));
-}
-```
+The library uses a global state that applies to all logging commands being used.
+If the library is in global "Verbose" mode, both the "Verbose" and the "Non-Verbose"
+API calls shown above will always result in Verbose messages being sent.
 
-##### Switching Verbose and Non-Verbose
+However, if the library is in global "Non-Verbose" mode, it is possible to send
+both Verbose and Non-Verbose messages in a single session; all "Verbose" APIs will
+send Verbose messages, and all "Non-Verbose" APIs will send Non-Verbose messages.
+
+It does not make sense to send a Non-Verbose message via a Verbose API, as there
+is then no sensible message ID, which is however mandatory when sending
+Non-Verbose messages.
+
+#### Switching Verbose and Non-Verbose
 
 To switch Verbose/Non-Verbose mode (Verbose mode is default), the following
 APIs are available:
 
+##### MACRO
+
 ```
 DLT_VERBOSE_MODE();
 DLT_NONVERBOSE_MODE();
 ```
 
+##### Function
+
+```
+dlt_verbose_mode();
+dlt_nonverbose_mode();
+```
+
 #### String arguments
 
 For string arguments, you can choose between ASCII and UTF-8 encoding. This
-- 
cgit v1.2.1