From 4d3b32d9f36e8a304e2c71503c7c824376425b0d Mon Sep 17 00:00:00 2001 From: Alexander Wenzel Date: Thu, 11 Oct 2012 17:39:25 +0200 Subject: Modfied documentation using asciibook. Signed-off-by: Alexander Wenzel --- doc/dlt_cheatsheet.txt | 239 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 doc/dlt_cheatsheet.txt (limited to 'doc/dlt_cheatsheet.txt') diff --git a/doc/dlt_cheatsheet.txt b/doc/dlt_cheatsheet.txt new file mode 100644 index 0000000..b101f7f --- /dev/null +++ b/doc/dlt_cheatsheet.txt @@ -0,0 +1,239 @@ +DLT Cheatsheet +============== +Alexander Wenzel +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. + +---- +pkg_check_modules(DLT REQUIRED automotive-dlt) +${DLT_INCLUDE_DIRS} +${DLT_LIBRARIES} +---- + +Include the DLT Header +---------------------- +To use DLT you have to include the DLT header file in each file you want to use DLT. + +---- +#include +---- + +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"); + +} +---- + +If your application uses fork(), you may not call DLT_REGISTER_APP() before fork(). And fork() should never be called after DLT_REGISTER_APP. This is because the DLT library must be initialised for each process, which is done by DLT_REGISTER_APP(). +If you are not sure where you are calling DLT_REGISTER_APP() the first time, you can initialise the DLT user library by calling the initialisation routine directly. + +---- +dlt_user_init(); +---- + +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_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_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 +#include + +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 */ + 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; + +} +---- -- cgit v1.2.1