From 0d0c74640c8b792db37cb9f884f89f7561ea551f Mon Sep 17 00:00:00 2001 From: Christoph Lipka Date: Fri, 14 Dec 2018 16:55:23 +0100 Subject: Documentation update Signed-off-by: Manikandan C Signed-off-by: Christoph Lipka --- doc/dlt_for_developers.md | 426 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 doc/dlt_for_developers.md (limited to 'doc/dlt_for_developers.md') diff --git a/doc/dlt_for_developers.md b/doc/dlt_for_developers.md new file mode 100644 index 0000000..005bb8c --- /dev/null +++ b/doc/dlt_for_developers.md @@ -0,0 +1,426 @@ +# How to DLT for developers + +Table of Contents +1. [Summary](#Summary) +2. [Example Application](#DLT-Example-Application) +3. [General Rules for Logging](#General-Rules-for-Logging) +4. [The use of Log Levels](#The-use-of-Log-Levels) +5. [DLT Library Runtime Configuration](#DLT-Library-Runtime-Configuration) +6. [DLT API Usage](#DLT-API-Usage) +7. [DLT injection messages](#DLT-Injection-Messages) +8.1 Log level changed callback 21 +9 Build DLT from source 21 + +  + +## DLT Example Application +This example gives an overview of DLT usage inside an application by using a minimal code example. Detailed information about the API can be found later in this document. + +``` +#include + +DLT_DECLARE_CONTEXT(ctx); /* declare context */ + +int main() +{ + DLT_REGISTER_APP("TAPP", "Test Application for Logging"); + + DLT_REGISTER_CONTEXT(ctx, "TES1", "Test Context for Logging"); + + /* … */ + + DLT_LOG(ctx, DLT_LOG_ERROR, DLT_CSTRING("This is an error")); + + /* … */ + + DLT_UNREGISTER_CONTEXT(ctx); + DLT_UNREGISTER_APP(); + return 0; +} +``` + +DLT is quite easy to use. The first thing a developer has to do is to include the dlt header file. DLT contexts can be statically declared using the macro shown in next line. +Firstly, a DLT application has to be registered inside the main function. For this, an application identifier APID and application description has to be specified. Afterwards, one or more DLT contexts could be specified. +To log messages in verbose mode, the DLT_LOG macro can be used. As parameter, the logging context, the log level and a variable list of parameters have to be specified. DLT requires each parameter to be strongly typed using DLT type macros. In this example, DLT_CSTRING is used to specify a constant string. +On application cleanup, all DLT contexts, as well as the DLT application have to be unregistered. + +## General Rules for Logging +### Be Smart +Before implementing logging in code one should take a second to think about a concept first. Often strategic places in the software can be used as a central place for logging. Such places are often interfaces to other SW components. Use the solution with the smallest impact. Avoid logging the “good cases” but log e.g. in your error handling sections – you will need error handling anyway. In case an error occurred more logs don’t matter as long as your regular code produces little logs. Keep in mind that tracing comes with a price tag – you are working in an embedded environment where CPU, memory and Bandwidth are sparse. +### Avoid high frequency outputs +Certain events occur very often in a system – some of them dozens of times per second. In such a case do not implement logging for each occurrence. One example is the screen frame rate. Instead of printing a log for each frame rate aggregate the information and print an average once every five seconds or – even better – report once a second if the frame rate is below a critical value. +### Combine multiple messages +Please always consider that each Log message creates a certain overhead. In case of DLT as the way of logging each has a header of 20 bytes. Therefore please aggregate information. In this way all necessary information is always combined. +Please always use a human readable format; use identifiers for the different values, be consistent with separators. This helps to work with the data, especially when log messages are processed by scripts. +Such scripts often use regular expressions – make the job easier! +For example don’t write log entries like this: + +``` +Total frames: 1000 +Sync frames: 0 +Reem frames: 0 +Valid frames: 100 +Urgent frames: 0 +``` + +Better aggregate Information into a single message: +``` +Frame info: total=1000, sync=0, reem=1000, valid=0, urgent=1 +``` + +### Do not use ASCII-art +Information should be “on your fingertips”. Logging is a tool to ease crushing bugs, not to win a computer art contest. → Don’t use ASCII Art! + +### Do not create charts using ASCII +Charts can be a great help to visualize what is going on in the system. This type can be nicely done by a trace analysis or in case of usage of the DLT Viewer, in a Plugin. It certainly should always be done in a post processing step. Doing this on the target is a waste of resources. + +### Avoid tracing in loops +Bad example: +``` +for(int index=0; index 0) { + dlt_user_log_write_string(&myctxdata, "ID: "); + dlt_user_log_write_uint32(&myctxdata, 123); + dlt_user_log_write_finish(&myctxdata); +} +``` + +###### Non-Verbose + +``` +if (dlt_user_log_write_start_id(&ctx, &ctxdata, DLT_LOG_INFO, 42) > 0) { + dlt_user_log_write_string(&myctxdata, "ID: "); + dlt_user_log_write_uint32(&myctxdata, 123); + dlt_user_log_write_finish(&myctxdata); +} +``` + +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 (line 373): + +``` +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)); +} +``` + +##### Switching Verbose and Non-Verbose +To switch Verbose/Non-Verbose mode (Verbose mode is default), the following APIs are available: +``` +DLT_VERBOSE_MODE(); +DLT_NONVERBOSE_MODE(); +``` + +### Logging parameters +The following parameter types can be used. Multiple parameters can be added to a single log message. The size of all logging parameters together should not exceed 1390 bytes, including the DLT message header. + +Type | Description +--- | --- +DLT_STRING(TEXT) | String +DLT_CSTRING(TEXT) | Constant String (not send in non-verbose mode) +DLT_UTF8 | Utf8-encoded string +DLT_RAW(BUF,LENGTH) | Raw buffer +DLT_INT(VAR) | Integer variable, dependent on platform +DLT_INT8(VAR) |Integer 8 Bit variable +DLT_INT16(VAR) | Integer 16 Bit variable +DLT_INT32(VAR) | Integer 32 Bit variable +DLT_INT64(VAR) | Integer 64 bit variable +DLT_UINT(VAR) | Unsigned integer variable +DLT_UINT8(VAR) | Unsigned 8 Bit integer variable +DLT_UINT16(VAR) |Unsigned 16 Bit integer variable +DLT_UINT32(VAR) | Unsigned 32 Bit integer variable +DLT_UINT64(VAR) | Unsigned 64 bit integer variable +DLT_BOOL(VAR) | Boolean variable +DLT_FLOAT32(VAR) | Float 32 Bit variable +DLT_FLOAT64(VAR) | Float 64 Bit variable +DLT_HEX8(UINT_VAR) | 8 Bit hex value +DLT_HEX16(UINT_VAR) | 16 Bit hex value +DLT_HEX32(UINT_VAR) | 32 Bit hex value +DLT_HEX64(UINT_VAR) | 64 Bit hex value +DLT_BIN8(UINT_VAR) | 8 Bit binary value +DLT_BIN16(UINT_VAR | 16 Bit binary value +DLT_PTR(PTR_VAR) | Architecture independent macro to print pointers + +### DLT C++ Extension +Important note: By default, C++ Extension is disabled in ADIT platform. It can be enabled by setting the CMake option: *WITH_DLT_CXX11_EXT=ON*. +The DLT C++ extension was added to DLT in version 2.13 . This approach solves the need to specify the type of each argument for applications written in C++ by using C++ templates and function overloading. The following shows the usage of this API extension: + +``` +#define DLT_LOG_CXX(CONTEXT, LOGLEVEL, ...) +#define DLT_LOG_FCN_CXX(CONTEXT, LOGLEVEL, ...) + + +DLT_LOG_CXX(ctx, DLT_LOG_WARN, 1.0, 65); +DLT_LOG_FCN_CXX(ctx, DLT_LOG_WARN, "Test String", 145, 3.141); +``` + +This works as well with C++ standard containers like std::vector, std::map, std::list. Of course, the logToDlt function can be overloaded to print user defined structures or classes. +``` +struct MyStruct +{ + int64_t uuid; + int32_t interfaceId; + int32_t registrationState; +}; + +template<> +inline int logToDlt(DltContextData & log, MyStruct const & value) +{ + int result = 0; + + result += dlt_user_log_write_string(&log, "("); + result += logToDlt(log, value.uuid); + result += dlt_user_log_write_string(&log, ","); + result += logToDlt(log, value.interfaceId); + result += dlt_user_log_write_string(&log, ","); + result += logToDlt(log, value.registrationState); + result += dlt_user_log_write_string(&log, ")"); + + if (result != 0) + { + result = -1; + } + + return result; +} +``` + +### Check if a specific Log Level is enabled +In some scenarios it might be necessary to check if a specific Log Level is enabled or not, before log data is send to DLT Library. The macro is defined as follows: +DLT_IS_LOG_LEVEL_ENABLED(CONTEXT,LOGLEVEL) +In general, there is no need to check the active Log Level to decide if a log message can be send to not. This is handled inside the DLT_LOG macro. + +## DLT Injection Messages +DLT provides an interface to register injection callbacks which can be sent by a DLT Client (e.g. DLT Viewer) to the application. An injection message callback is always registered for a specific context. The API to register a callback is defined as follows: + +``` +DLT_REGISTER_INJECTION_CALLBACK(CONTEXT, SERVICEID, CALLBACK); +``` + +Injection message Service IDs must be bigger than 0xFFF, because IDs up to 0xFFF are reserved for DLT Daemon control messages. +The callback function needs to have the following definition: +``` +int injection_callback(uint32_t service_id, void *data, uint32_t length); +``` +For example, registering a callback function for a specific context with the service ID 0x1000 might look like: +``` +DLT_REGISTER_INJECTION_CALLBACK(mycontext, 0x1000, injection_callback); +``` +From DLT Viewer, an injection message can be sent by right-clicking the corresponding context in the project view (“Send injection”). A dialog will pop up to specify the injection data as shown below. + +![alt text](images/dlt-viewer-send-injection-dialog.png "DLT Viewer Send Injection Callback") + +## Log level changed callback +A callback function can be registered to be called whenever the Log Level of a context changed. The usage is similar to DLT_REGISTER_INJECTION_CALLBACK. +``` +DLT_REGISTER_LOG_LEVEL_CHANGED_CALLBACK(CONTEXT, CALLBACK) +``` \ No newline at end of file -- cgit v1.2.1