Add short explanation for DLT log level (#20)

Signed-off-by: Lutz Helwing <lutz_helwing@mentor.com>

2 files changed, 137 insertions, 0 deletions

diff --git a/doc/dlt_book.txt b/doc/dlt_book.txt
index 695c36f..1026bb4 100644
--- a/doc/dlt_book.txt
+++ b/doc/dlt_book.txt
@@ -45,6 +45,8 @@ include::dlt_user_manual.txt[]
 
 include::dlt_cheatsheet.txt[]
 
+include::dlt_loglevel_explained.txt[]
+
 include::dlt_design_specification.txt[]
 
 include::dlt_filetransfer.txt[]
diff --git a/doc/dlt_loglevel_explained.txt b/doc/dlt_loglevel_explained.txt
new file mode 100644
index 0000000..84ac11a
--- /dev/null
+++ b/doc/dlt_loglevel_explained.txt
@@ -0,0 +1,135 @@
+DLT Log Level Explained
+=======================
+Lutz Helwing <Lutz_Helwing@mentor.com>
+0.0.1, 23rd July 2017: Initial version
+
+Overview
+--------
+From the DLT point of view an application logger is defined by its "context". Part of this context is a log level value. When an application registers its context at the daemon (`DLT_REGISTER_CONTEXT()` or `dlt_register_context()`) the context's log level is set by the daemon to a value specified in dlt.conf (`ContextLogLevel`). All log messages sent by the application also have a log level which could be different from context log level. When this log level is greater than the context log level the message is not sent to dlt-daemon (i.e. filtered at application level). Usually this per-message log level is hard-coded in the application or could be part of a config file read by the application. This is a task the application developer has to take care of.
+
+Example for context log level / message log level relation:
+
+Context log level: `DLT_LOG_INFO`
+
+Message log level: `DLT_LOG_INFO`
+
+=> Message is logged
+
+
+Context log level: `DLT_LOG_INFO`
+
+Message log level: `DLT_LOG_DEBUG`
+
+=> Message is not logged
+
+
+Context log level: `DLT_LOG_ERROR`
+
+Message log level: `DLT_LOG_INFO`
+
+=> Message is not logged
+
+
+Methods to set the log level for an application context
+-------------------------------------------------------
+- dlt-daemon sets initial application log level
+    + There is a configuration parameter (see /etc/dlt.conf) `ContextLogLevel`.
+        When a new application registers itself at the daemon, the daemon sets the application's log level to the value defined by the parameter.
+    + This happens when the application registers itself with `DLT_REGISTER_CONTEXT()` or `dlt_register_context()`
+
+- Environment variable `DLT_INITIAL_LOG_LEVEL`
+    + There is an environment variable which is called `DLT_INITIAL_LOG_LEVEL`. Its value has the following form: `APID:CTID:LEVEL(;APID:CTID:LEVEL...)`. It allows to set a per-application-context log level. Values are separated by ';'.
+    + Example: `DLT_INITIAL_LOG_LEVEL="AP1:CTX1:2;MLP:MLPC:3" ./my_logging_program` => my_logging_program context is started with log level `DLT_LOG_WARN` (can be seen in DLT Viewer)
+
+- Application registers itself at daemon with self defined log level
+    + In this case no log level is set by the daemon but by the application itself.
+    + This happens when the application registers itself with `DLT_REGISTER_CONTEXT_LL_TS()` or `dlt_register_context_ll_ts()`
+
+- Client (e.g. DLT Viewer) changes the log level of a particular application context at runtime.
+    + The context's initial log level is set by one of the two methods described above.
+
+
+DLT Code Snippets
+-----------------
+Excerpt from DLT API dlt_user_macros.h (Macro interface):
+
+    /**
+     * Register context (with default log level and default trace status)
+     * @param CONTEXT object containing information about one special logging context
+     * @param CONTEXTID context id with maximal four characters
+     * @param DESCRIPTION ASCII string containing description
+     */
+    #define DLT_REGISTER_CONTEXT(CONTEXT,CONTEXTID,DESCRIPTION)
+
+    /**
+     * Register context with pre-defined log level and pre-defined trace status.
+     * @param CONTEXT object containing information about one special logging context
+     * @param CONTEXTID context id with maximal four characters
+     * @param DESCRIPTION ASCII string containing description
+     * @param LOGLEVEL log level to be pre-set for this context
+     (DLT_LOG_DEFAULT is not allowed here)
+     * @param TRACESTATUS trace status to be pre-set for this context
+     (DLT_TRACE_STATUS_DEFAULT is not allowed here)
+     */
+    #define DLT_REGISTER_CONTEXT_LL_TS(CONTEXT,CONTEXTID,DESCRIPTION,LOGLEVEL,TRACESTATUS)
+
+
+    /**
+     * Send log message with variable list of messages (intended for verbose mode)
+     * @param CONTEXT object containing information about one special logging context
+     * @param LOGLEVEL the log level of the log message
+     * @param ARGS variable list of arguments
+     * @note To avoid the MISRA warning "The comma operator has been used outside a for statement"
+     *       use a semicolon instead of a comma to separate the ARGS.
+     *       Example: DLT_LOG(hContext, DLT_LOG_INFO, DLT_STRING("Hello world"); DLT_INT(123));
+     */
+    #define DLT_LOG(CONTEXT,LOGLEVEL,ARGS...)
+
+
+
+Excerpt from DLT API dlt_user.h (function interface):
+
+    /**
+     * Register a context in the daemon.
+     * This function has to be called before first usage of the context.
+     * @param handle pointer to an object containing information about one special logging context
+     * @param contextid four byte long character array with the context id
+     * @param description long name of the context
+     * @return Value from DltReturnValue enum
+     */
+    DltReturnValue dlt_register_context(DltContext *handle, const char *contextid, const char * description);
+
+    /**
+     * Register a context in the daemon with pre-defined log level and pre-defined trace status.
+     * This function has to be called before first usage of the context.
+     * @param handle pointer to an object containing information about one special logging context
+     * @param contextid four byte long character array with the context id
+     * @param description long name of the context
+     * @param loglevel This is the log level to be pre-set for this context
+              (DLT_LOG_DEFAULT is not allowed here)
+     * @param tracestatus This is the trace status to be pre-set for this context
+              (DLT_TRACE_STATUS_DEFAULT is not allowed here)
+     * @return Value from DltReturnValue enum
+     */
+    DltReturnValue dlt_register_context_ll_ts(DltContext *handle, const char *contextid, const char * description, int loglevel, int tracestatus);
+
+    /**
+     * Write a null terminated ASCII string into a DLT log message.
+     * @param handle pointer to an object containing information about one special logging context
+     * @param loglevel this is the current log level of the log message to be sent
+     * @param text pointer to the ASCII string written into log message containing null termination.
+     * @return Value from DltReturnValue enum
+     */
+    DltReturnValue dlt_log_string(DltContext *handle,DltLogLevelType loglevel, const char *text);
+
+    /**
+     * Initialize the generation of a DLT log message (intended for usage in non-verbose mode)
+     * This function has to be called first, when an application wants to send a new log messages.
+     * Following functions like dlt_user_log_write_string and dlt_user_log_write_finish must only be called,
+     * when return value is bigger than zero.
+     * @param handle pointer to an object containing information about one special logging context
+     * @param log pointer to an object containing information about logging context data
+     * @param loglevel this is the current log level of the log message to be sent
+     * @return Value from DltReturnValue enum, DLT_RETURN_TRUE if log level is matching
+     */
+    DltReturnValue dlt_user_log_write_start(DltContext *handle, DltContextData *log, DltLogLevelType loglevel);