summaryrefslogtreecommitdiff
path: root/doc/dlt_cheatsheet.txt
blob: 8babc2abf9aee4984805f144f69434a803647777 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
////
# SPDX license identifier: MPL-2.0
#
# Copyright (C) 2011-2015, BMW AG
#
# This file is part of GENIVI Project DLT - Diagnostic Log and Trace.
#
# This Source Code Form is subject to the terms of the
# Mozilla Public License (MPL), v. 2.0.
# If a copy of the MPL was not distributed with this file,
# You can obtain one at http://mozilla.org/MPL/2.0/.
#
# For further information see http://www.genivi.org/.
////

DLT Cheatsheet
==============
Alexander Wenzel <Alexander.AW.Wenzel@bmw.de>
0.0.1, 2012/10/11: Initial version

image::images/genivi_chrome_1_transparent.png[width=128]

Overview
--------
DLT is quiet easy to use. As an application developer you only need to follow some steps as described in this document.

Initialisation:

- Link your application against the DLT library
- Include the DLT header file
- Register your application
- Define all contexts
- Register all contexts

Now you are ready to write your logs.

Termination:

- Unregister all contexts
- Unregister application

Link your application to DLT library
------------------------------------
If you compile your application with cmake, you have to add the following lines to your CMakeLists.txt

----
find_package(PkgConfig)
pkg_check_modules(DLT REQUIRED automotive-dlt)
----

and use the variables $\{DLT_INCLUDE_DIRS\} and $\{DLT_LIBRARIES\} for the DLT include and library paths.

Include the DLT Header
----------------------
To use DLT you have to include the DLT header file in each file you want to use DLT.

----
#include <dlt.h>
----

Register your application
-------------------------
You have to register your application as early as possible during the initialisation of your application.
You have to call the DLT_REGISTER_APP().
It is only allowed to call DLT_REGISTER_APP() *once* in your application.
You have to provide a application id, which size is maximum four charcters long. In this example we use "MAPP".
And you can provide also a description for your application, here it is "Test Application for Logging".

----
int main(int argc, const char\* argv\[\])
{
  DLT_REGISTER_APP("MAPP","Test Application for Logging");

}
----

.Important notes:
* DLT may not be used in a forked child until a variant of exec() is called,
  because DLT is using non async-signal-safe functions.
----
dlt_user_init();
----
* DLT_REGISTER_APP is asynchronous. It may take some milliseconds to establish the IPC channel. Because of this, you might lose messages if you log immediately after registering. Typically this is not a problem, but may arise especially with simple examples.



Define all contexts
--------------------
You can create as many contexts as you like.
You can declare one or more contexts in a C or CPP file.
Each context is only allowed to be declared once.
You have to provide a unique variable name for your context.

----
#include <dlt.h>

DLT_DECLARE_CONTEXT(myContext1);
DLT_DECLARE_CONTEXT(myContext2);
DLT_DECLARE_CONTEXT(myContext3);
----

If you want to use a context in another C or CPP file, you can import the context by calling

----
#include <dlt.h>

DLT_IMPORT_CONTEXT(myContext1);
DLT_IMPORT_CONTEXT(myContext2);
DLT_IMPORT_CONTEXT(myContext3);
----

Register all contexts
----------------------
After you have registered your application you must register your contexts, early during initialisation of your application.
Do not call DLT_REGISTER_CONTEXT() before DLT_REGISTER_APP().
During registration of each context, you must provide a context id, which size is maximum four charcters long. In this example we use "TESX".
And you can provide also a description for your context, here it is "Test Context X for Logging".

----
int main(int argc, const char\* argv\[\])
{
  DLT_REGISTER_APP("MAPP","Test Application for Logging");

  DLT_REGISTER_CONTEXT(myContext1,"TES1","Test Context 1 for Logging");
  DLT_REGISTER_CONTEXT(myContext2,"TES2","Test Context 2 for Logging");
  DLT_REGISTER_CONTEXT(myContext3,"TES3","Test Context 3 for Logging");

}
----

Create your logs
----------------
Now you can start creating your logs.
Each log command consist of the context, the log level and a variable number of logging parameters.

Log Level
~~~~~~~~~
The log level must be one of the following values:

[options="header"]
|==================================================================
| Log level       | Description
| DLT_LOG_FATAL   | fatal system error
| DLT_LOG_ERROR   | error with impact to correct functionality
| DLT_LOG_WARN    | warning, correct behaviour could not be ensured
| DLT_LOG_INFO    | informational (default)
| DLT_LOG_DEBUG   | debug
| DLT_LOG_VERBOSE | highest grade of information
|==================================================================

DLT_LOG_FATAL, DLT_LOG_ERROR and DLT_LOG_WARN should be used in your application, when something is going wrong.
DLT_LOG_INFO should be used to send the most important information.
DLT_LOG_DEBUG and DLT_LOG_VERBOSE should be only used for testing information.

Each context is set by default to DLT_LOG_INFO log level. All log message are send, which use this loglevel or a lower loglevel.
If you also want to see DLT_LOG_DEBUG and DLT_LOG_VERBOSE log messages, you have to raise the log level with the DLT viewer.

Logging parameters
~~~~~~~~~~~~~~~~~~
The following parameter types can be used.
You can add one or more parameters to a single log message.
The size of all logging parameters together should not exceed 2kBytes, including the DLT message header.

[options="header"]
|===============================================================
| Type                | Description
| DLT_STRING(TEXT)    | String
| DLT_RAW(BUF,LENGTH) | Raw buffer
| DLT_INT(VAR)        | Integer variable, dependent on platform
| 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_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 Bitvariable
|===============================================================

Logging command
~~~~~~~~~~~~~~~
Here are some examples for complete log messages.
The contexts must be registered before.

----
DLT_LOG(myContext1,DLT_LOG_ERROR,DLT_INT(5),DLT_STRING("This is a error"));
DLT_LOG(myContext2,DLT_LOG_INFO,DLT_INT(5),DLT_STRING("But this only information"));
DLT_LOG(myContext3,DLT_LOG_DEBUG,DLT_INT(5),DLT_STRING("But this only information"));
----

Unregister contexts and applications
------------------------------------
Before terminating your application you must unregister all registered contexts and unregister at last your application.

----
int main(int argc, const char\* argv\[\])
{
  DLT_REGISTER_APP("MAPP","Test Application for Logging");

  DLT_REGISTER_CONTEXT(myContext1,"TES1","Test Context 1 for Logging");
  DLT_REGISTER_CONTEXT(myContext2,"TES2","Test Context 2 for Logging");
  DLT_REGISTER_CONTEXT(myContext3,"TES3","Test Context 3 for Logging");

  DLT_UNREGISTER_CONTEXT(myContext1);
  DLT_UNREGISTER_CONTEXT(myContext2);
  DLT_UNREGISTER_CONTEXT(myContext3);

  DLT_UNREGISTER_APP();

  return 0;
}
----

Example
-------
Finally here is a complete example for using DLT:

.dlt_example.c
----
#include <stdio.h>
#include <dlt.h>

DLT_DECLARE_CONTEXT(myContext1);
DLT_DECLARE_CONTEXT(myContext2);
DLT_DECLARE_CONTEXT(myContext3);

int main()
{
  /* register application */
  DLT_REGISTER_APP("MAPP","Test Application for Logging");

  /* register all contexts */
  DLT_REGISTER_CONTEXT(myContext1,"TES1","Test Context 1 for Logging");
  DLT_REGISTER_CONTEXT(myContext2,"TES2","Test Context 2 for Logging");
  DLT_REGISTER_CONTEXT(myContext3,"TES3","Test Context 3 for Logging");

  /* Write your logs */
  DLT_LOG(myContext1,DLT_LOG_ERROR,DLT_INT(5),DLT_STRING("This is a error"));
  DLT_LOG(myContext2,DLT_LOG_INFO,DLT_INT(5),DLT_STRING("But this only information"));
  DLT_LOG(myContext3,DLT_LOG_DEBUG,DLT_INT(5),DLT_STRING("But this only information"));

  /* Sleep some time to avoid a flaw in dlt-daemon that would eat your messages
     if you deregister while it still processes your registration */
  sleep(3);

  /* unregister your contexts */
  DLT_UNREGISTER_CONTEXT(myContext1);
  DLT_UNREGISTER_CONTEXT(myContext2);
  DLT_UNREGISTER_CONTEXT(myContext3);

  /* unregister your application */
  DLT_UNREGISTER_APP();

  return 0;

}
----

.CMakeLists.txt
----
cmake_minimum_required(VERSION 2.6)

find_package(PkgConfig)
pkg_check_modules(DLT REQUIRED automotive-dlt)

include_directories("${DLT_INCLUDE_DIRS}")

project(DLTexample)
add_executable(dlt_example dlt_example.c)

target_link_libraries(dlt_example ${DLT_LIBRARIES})
----

.Build steps
----
mkdir build
cd build
cmake ..
make
----