path: root/doc/dlt_design_specification.txt

////
# 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 Design Specification
========================
Alexander Wenzel <Alexander.AW.Wenzel@bmw.de>
0.0.1, 2012/10/10: Initial version

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

*This document is not up to date*

== Purpose
This document specifies the usage of the DLT daemon v2 and also the internal functionality of the DLT daemon v2. The DLT daemon v2 is a complete rework of the DLT daemon v1, which is part of the GENIVI 1.0 release.
The DLT daemon is the central place where logs and traces are gathered from different applications, stored temporarily or permanently and transferred to a DLT client application, which can run directly on the GENIVI system or more likely on a external tester device.
The DLT client component is described in an extra document.
The DLT daemon component is based on the AUTOSAR 4.0 standard DLT.

== Overview

.DLT Architecture
image::images/dlt_overview.png[]

The DLT daemon is the central component in GENIVI, which gathers all logs and traces from the DLT user applications. The logs and traces are stored optionally directly in a file in the ECU. The DLT daemon forwards all logs and traces to a connected DLT client.
The DLT client can send control messages to the daemon, e.g. to set individual log levels of applications and contexts or get the list of applications and contexts registered in the DLT daemon.

== Architecture

=== DLT daemon
The DLT daemon is the central component between the DLT clients and one or more applications using the DLT user library.

==== Overview
The DLT daemon communicates with the DLT clients over TCP/IP connections or over a serial line (the message format is specified in the DLT AUTOSAR Standard), with the applications using the DLT user library over named pipes (FIFOs) or UNIX_SOCKET based on compile time configuration. More details concerning the exchanged user messages and their content can be found in chapter chapter 6.3.
The main time, the DLT daemon executes a main loop, in which file and socket descriptors are watched (via poll()). If a message is received, the DLT daemon reacts. Additionally, a thread is implemented, which if enabled sends each second a keep-alive message to all connected DLT clients.
Here is a rough schematic, how the DLT daemon is structured:

.DLT Overview
image::images/dlt_architecture.png[]

==== Initialization
During initialization of the DLT daemon, the following steps occur:

* Option handling
* Initialization of logging facility for the DLT daemon application. The DLT daemon application by itself prints to screen, if not in daemon mode. In daemon mode, it uses the syslog daemon for log messages of the DLT daemon application.
* Then the daemon enters initialization phase 1:
** Enter daemon mode, if started as daemon
** Initialize output of messages to local file
** Parse filter file, if specified; then set filters for file storage
** Setup signal handler
** Open DLT output file, if specified
* After phase 1, the daemon initializes the connection handling:
** Delete, create and open its own named FIFO /tmp/dlt or UNIX_SOCKET
** Open, bind and listen to TCP socket for incoming connections
** Setup and open serial device, if specified
* Then the daemon enters initialization phase 2:
** Initialize daemon data structures
** Initialize ring buffer for client connection
** Check if a runtime configuration exists, if yes load all stored application and context ids, as well as all log levels and trace statuses. Store this information to a local array.
** Prepare main loop
** Initialize receiver objects for socket and serial connection
** Initialize binary semaphore
** Create and start thread for timing messages, sending of these messages is disabled at default.
* Now, the initialization is finished, and the DLT daemon enters the main loop.

==== Main loop
In the main loop, the following things occur:

* Wait for event on the incoming named pipe or socket, the TCP connections (the one connection for new connections, and all TCP connections from clients), and possibly on the serial device, via poll() call.
* Distinguish from which socket/file descriptor the connection came, and handle them:
** Event from TCP server socket (New DLT client to DLT daemon):
*** Create new TCP connection
*** If the newly created connection is the first TCP connection, send all log messages already stored in ring buffer to DLT client.
** Event from incoming named pipe or unix socket(DLT user library to DLT daemon):
*** Use dlt receiver to read data
*** As long as there are DLT messages available in received data:
**** Handle user message:
***** DLT_USER_MESSAGE_REGISTER_APPLICATION
***** DLT_USER_MESSAGE_UNREGISTER_APPLICATION
***** DLT_USER_MESSAGE_REGISTER_CONTEXT
***** DLT_USER_MESSAGE_UNREGISTER_CONTEXT
***** DLT_USER_MESSAGE_OVERFLOW
***** DLT_USER_MESSAGE_LOG
***** DLT_USER_MESSAGE_APP_LL_TS
*** Move rest of data in front of buffer for next read attempt
** Event from serial device (DLT client to DLT daemon via serial device)
*** Use other dlt receiver to read data
*** As long as there are DLT messages available in received data:
**** Check for DLT message type control request, and if yes process the request
*** Move rest of data in front of buffer for next read attempt
** Event from TCP socket (DLT client to DLT daemon via TCP connection)
*** Use other dlt receiver to read data, and check for lost connection
*** As long as there are DLT messages available in received data:
**** Check for DLT message type control request, and if yes process the request
*** Move rest of data in front of buffer for next read attempt

How the received user messages and control messages are handled, is described in the Appendix.

=== DLT user library

==== Overview
The DLT user library is linked to each application which wants to use DLT. It encapsulates the communication with the DLT daemon, and provides two interfaces: the DLT user macro interface and the DLT user functional interface. All macros from the DLT user macro interface are mapped to functions in the DLT user functional interface. The DLT user library has one additional thread, responsible for receiving messages from the DLT daemon. Parts of functions accessible by the user interface are protected by a semaphore, as well as parts of the function which is called within the thread.

==== Initialization
During initialization, the following things are done:

* Setup internal structure including Application ID and Description (textual) of application
* Get value from environment variable "DLT_LOCAL_PRINT_MODE". This variable can be used to control the local printing mode of the DLT user library. If enabled (either via "AUTOMATIC" or via "FORCE_ON"), all messages, which are prepared to be sent to the DLT daemon will also be print out locally (as ASCII string). If the environment variable is set, this value overrides the local print mode which can be set with the API function dlt_enable_local_print() or with dlt_disable_local_print() from within the application using the DLT user library. The following values are allowed:
*** "AUTOMATIC": Local printing is enabled, if NO DLT daemon is running.
*** "FORCE_ON": Local printing is always enabled.
*** "FORCE_OFF": Local printing is always disabled.
* Clear internal context array (dynamically growing in step size DLT_USER_CONTEXT_ALLOC_SIZE, typically 500). The internal context array is NOT be kept sorted, as the DLT daemon stores for each registered context the offset position within this array, and sends this offset position for faster access of a context within this internal context array). The internal context array contains one entry for each context:
** Context ID
** Log level for this context
** Trace status for this context
** Initialize table (dynamically growing in step-size 1) with function pointers for callback functions used for injection messages
** Description (textual) of context
* Initialize ringbuffer for local storage of not sent messages
* Setup signal handler and atexit handler
* Ignore all pipe signals
* Create and open own named pipe with the name /tmp/dlt<PID>, where <PID> is the process id of the application using the DLT user library.
* Open named pipe to the DLT daemon
* Open local file for storage, if specified
* Initialize receiver object
* Start receiver thread

==== De-Initialization
During de-initialization, the following things are done:

* De-register application (and all contexts belonging to this application) from DLT daemon
* Stop receiver thread
* Close and remove own named pipe
* Close named pipe to the DLT daemon
* De-Initialize receiver object
* De-Initialize ringbuffer

==== Register application and context
During register of the application, the following things occur:

* Auto-initialize DLT user library, if necessary
* Store application id to internal structure
* Store application description to internal structure
* Send message DLT_REGISTER_APPLICATION to DLT daemon

During register of a context of the application, the following things occur:

* Auto-initialize DLT user library, if necessary
* Check, if context was already registered, if not , dynamically increment if required, the context array in step size DLT_USER_CONTEXT_ALLOC_SIZE, typically 500. Then store one entry for the new context to internal context array.
* Send message DLT_REGISTER_CONTEXT to DLT daemon

==== Unregister context and application

During unregister of context, the following things occur:

* Delete context from internal structures
* Send message DLT_UNREGISTER_CONTEXT to DLT daemon

During unregister of application, the following things occur:

* Delete application from internal structures
* Send message DLT_UNREGISTER_APPLICATION to DLT daemon

==== Handling of messages received from DLT daemon

During receiver thread within the DLT user library checks for newly received messages from the DLT daemon, and handles them in the following way:

* DLT_USER_MESSAGE_LOG_LEVEL
** Store received log level and trace status for the received context to the context array
* DLT_USER_MESSAGE_INJECTION
** Check all registered callbacks for this context:
*** Compare service id of registered callback with received service id, if they matches:
**** Call registered callback function.

==== Overflow handling

If the named pipe/socket of the DLT daemon is full, an overflow flag is set and the message stored in a ring buffer. The next time, a message could be send to the DLT daemon, an overflow message is send first, then the contents of the ring buffer. If sending of this message was possible, the overflow flag is reset.

==== Send log message

During sending of a log message, the following things occur:

* Auto-initialize DLT user library, if necessary
* Initialize DLT log structure
* Store log level of log message in DLT log structure
* Check if log level is smaller than or equal than the stored log level of the context, under which the message should be sent. If yes continue, else don't send this log message. This is a kind of filtering on the DLT user library side.
* In non-verbose mode, insert message id
* Add values (int, string, raw, …) to DLT log structure:
** Set argument type (only in verbose mode)
** Copy content of argument to message
** Set length information of argument
** Set number of arguments and total length of message
* Create new message with the help of the DLT log structure and handle this message:
** Initialize new message
** Add headers (standard header, extended header, storage header, ...) to this message
** If logging to a file is enabled, write the log message to file. Finished sending log.
** Print message locally, if requested by environment variable
** Check if connection to DLT daemon was lost and try to reattach to daemon.
** Check for overflow flag and try to send overflow message.
** Try to send message to DLT daemon, and check for return values. This can be:
*** data could not be written
*** handle not open or pipe/socket error
*** other error condition
*** no error, all right
** If sending failed, put this message in the ring buffer for later sending.
** Handle this error conditions.

==== Send network trace message

During sending of a network trace message, the following things occur:

* Auto-initialize DLT user library, if necessary
* Check for trace status of network trace message to be send.
* If Trace status equals on:
** Initialize DLT log structure
** Set trace status in DLT log structure to network trace type of message
** Copy length of network message header to DLT log structure
** Copy data of network message header to DLT log structure
** Copy length of network trace payload to DLT log structure
** Copy data of network trace payload to DLT log structure
** Create new message with the help of the DLT log structure and handle this message

==== Register callback function for injection message

During registration of a callback function for a injection message, the following steps are executed:

** For the specified context, check if service id is already in the table of the registered callbacks (this table is dynamically growing in steps of one entry).
*** If yes:
**** Stored service id is set to service id to be registered
**** Stored callback function pointer is set to callback function pointer to be registered
*** If no:
**** Increase nr of callbacks for this context
**** Store service id in callback table
**** Store function pointer in callback table

=== Communication between DLT daemon and DLT user library

The communication mechanism(IPC) used between DLT daemon and DLT user library are named pipes (FIFOs) or UNIX_SOCKETS (based on compile time configuration).
During startup of the DLT daemon, the DLT daemon creates and opens the IPC on configured path. If a DLT user application using the DLT user library wants to send something to the DLT daemon this IPC is used.
During startup of the DLT user application using the DLT user library, it creates and opens the same IPC (a named pipe called /tmp/dlt<PID>, where <PID> is the process id of the DLT user application or an UNIX_SOCKET). If the DLT daemon wants to send something to the DLT user application, this IPC is used.
The exchanged messages are described in the chapter 7.1.

=== Place of message creation

The following table shows, where the DLT messages are created. The message types are described in more detail in the AUTOSAR Specification for Diagnostic Log and Trace.

[options="header"]
|==============================================================================================
| Type of message  | DLT client | DLT daemon | DLT library
| Control request  |     X      |      X     |
| Control response |            |      X     |
| Log message      |            |            |       X
| Trace message    |            |            |       X
|==============================================================================================

* "Get log info" request only, if enabled with \-r option in DLT daemon during start-up
* "File generation" means, that the DLT client creates a file for testing purposes, containing multiple DLT messages. This functionality is only in the "old" DLT viewer (WX widget-based implementation) available.

This table shows, that:

** DLT messages of message type control request (e.g. "Get Log Info"-Request) are created in the DLT client, and then sent to the DLT daemon.
** DLT messages of message type control response (to a control request) are created in the DLT daemon, and then sent to the DLT client.
** DLT messages of type log and of type trace are created in the DLT user library, then passed (via the named pipe of the DLT daemon) to the DLT daemon , which forwards them to the connected DLT clients.

=== Message flow

The following figure shows the overall flow of messages.

.DLT Message flow
image::images/dlt_message_flow.png[]


== Appendix

=== Messages exchanged between DLT daemon and DLT user library

There are several user messages (each has its own message identifier DLT_USER_MESSAGE_*) which will are exchanged between DLT daemon and DLT user library, and will be described in the following sub-chapters.

From DLT user library to DLT daemon:

* DLT_USER_MESSAGE_REGISTER_APPLICATION
* DLT_USER_MESSAGE_UNREGISTER_APPLICATION
* DLT_USER_MESSAGE_REGISTER_CONTEXT
* DLT_USER_MESSAGE_UNREGISTER_CONTEXT
* DLT_USER_MESSAGE_LOG
* DLT_USER_MESSAGE_OVERFLOW
* DLT_USER_MESSAGE_APP_LL_TS

From DLT daemon to DLT user library:

* DLT_USER_MESSAGE_LOG_LEVEL
* DLT_USER_MESSAGE_INJECTION

Each of the following messages has a message header with the following information:

* Pattern: DUH0x01
* Message identifier

==== User Message: Register Application

This message is send by the DLT user library once per application to register the application to the DLT daemon.
It contains the following information:

* The application id of the application to be registered
* The process id of the process using the DLT user library. This information is required, if the DLT daemon wants to send something to the DLT user library.
* The length of the following description.
* The application description.

==== User Message: Unregister Application

This message is send by the DLT user library once per application to unregister the application from the DLT daemon.
It contains the following information:

* The application id of the application to be unregistered
* The process id of the process using the DLT user library.

==== User Message: Register Context

This message is send by the DLT user library once for each context which should be registered to the DLT daemon.
It contains the following information:

* The application id of the application to be registered
* The context id of the application to be registered
* Each created context is stored with its associated information in a dynamically growing array in the DLT user library. The index in this array is send.
* The process id of the process using the DLT user library. This information is required, if the DLT daemon wants to send something to the DLT user library.
* The initial log level of the context
* The initial trace status of the context
* The length of the following description.
* The context description.

==== User Message: Unregister Context

This message is send by the DLT user library once for each context which should be unregistered from the DLT daemon.
It contains the following information:

* The application id of the application to be unregistered
* The context id of the application to be unregistered
* The process id of the process using the DLT user library.

==== User Message: Log

This is the standard log/trace message send by the DLT user library to the DLT daemon.
It contains the following information:

* A standard DLT message header as specified in the AUTOSAR R4.0 DLT standard.
* An extended DLT message header as specified in the AUTOSAR R4.0 DLT standard.
* The payload of the DLT message

==== User Message: Overflow

This message is send from the DLT user library to the DLT daemon, if there was an overflow during writing to the DLT daemon named pipe.
It contains no further information.

==== User Message: Application Log Level and Trace Status

This message is send from the DLT user library to the DLT daemon, when the overall Log Level and Trace Status for the whole DLT application should be set from within the DLT application.
It contains the following information:

* The application id
* The Log Level to be set for the whole application
* The Trace Status to be set for the whole application

==== User Message: Log Level

If the log level or trace status is changed, or initialized, this message is send from the DLT daemon to the DLT user library to store the current log level and trace status for filtering in the DLT user library.

It contains the following information:

* The new set log level
* New set trace status.
* Each created context is stored with its associated information in a dynamically growing array in the DLT user library. The index in this array is send.

==== User Message: Injection

This message is send from the DLT daemon to the DLT user library, if an injection message was received by the DLT daemon from a DLT client. Via the context, the appropriate application and its named pipe can be identified. The injection message is then passed to this named pipe.

It contains the following information:

* Each created context is stored with its associated information in a dynamically growing array in the DLT user library. The index in this array is send.
* Service ID of the injection message
* Length of the following injection message
* The contents of the injection message

=== DLT daemon: User message handling

Following things occur for the received DLT user messages:

* DLT_USER_MESSAGE_REGISTER_APPLICATION
** Add all information about application to a local application array (dynamically growing in a predefined step size (DLT_DAEMON_APPL_ALLOC_SIZE, typically 500)). The array is always being kept sorted (via qsort()). Finding entries in this array is done by a binary search (via bsearch()).
** Open named pipe to DLT application using the DLT user library with process id <PID>. The name of the pipe is /tmp/dlt<PID>
* DLT_USER_MESSAGE_UNREGISTER_APPLICATION
** Remove all information about this application from local application array, and remove all information of all contexts belonging to this application from local context array. The arrays are always being kept sorted, without empty entries in between. Dynamically shrinking of this array is NOT implemented.
* DLT_USER_MESSAGE_REGISTER_CONTEXT
** Add all information about context to local context array (dynamically growing in a predefined step size (DLT_DAEMON_CONTEXT_ALLOC_SIZE, typically 1000)). The array is always being kept sorted (via qsort()). Finding entries in this array is done by a binary search (via bsearch()).
** Send log level and trace status to DLT user library for this context. Therefore, the DLT_USER_MESSAGE_LOG_LEVEL is used.
** Create and send DLT control message response "get log info" for this application and context to all connected DLT clients, if requested (-r option during startup of DLT daemon).
* DLT_USER_MESSAGE_UNREGISTER_CONTEXT
** Remove all information about this context from local context array. The array is always being kept sorted, without empty entries in between. Dynamically shrinking of this array is NOT implemented.
* DLT_USER_MESSAGE_OVERFLOW
** Set internal flag for overflow.
** Create and send DLT control message response overflow to all connected TCP connections, and optionally to serial device, if connected. If the message was sent, reset the internal flag for overflow.
* DLT_USER_MESSAGE_LOG
** Overwrite ECU id, if requested
** Set storage header
** Check for filters of message, if no filter is set, or filter is matching:
*** Possibly display message as specified in the options.
**** Whole message display in hex
**** Whole message display in ASCII
**** Show message headers only
*** Store message to output file
*** Set serial header in front of message, if specified.
*** Create and try to send DLT message to all DLT clients connected via TCP connection, and optionally via serial device.
*** If the message could not be sent, store the message to a local ring buffer. The ring buffer internally uses a variable length for the buffered elements, and therefore uses the memory available for the buffer the best way possible. If the buffer is full, the oldest messages are silently discarded, until there is enough space for the message to be stored in the ring buffer.
* DLT_USER_MESSAGE_APP_LL_TS
** For all contexts belonging to the specified application:
*** Set specified log level
*** Set specified trace status
*** Send specified log level and trace status to DLT client library

=== DLT daemon: Control message handling

If the DLT daemon receives a control message request from a DLT client, it handles it in the following way. First the service id of the message is detected, and if it is no injection message, the following things occur:

* DLT_SERVICE_ID_SET_LOG_LEVEL
** Check if received log level is other then already set log level. If yes:
*** Store new log level to local array.
*** Send new log level to DLT user library for this context. Therefore, the DLT_USER_MESSAGE_LOG_LEVEL is used.
** Send DLT control response to DLT client, with status of operation.
* DLT_SERVICE_ID_SET_TRACE_STATUS
** Check if received trace status is other then already set trace status. If yes:
*** Store new trace status to local array.
*** Send new trace status to DLT user library for this context. Therefore, the DLT_USER_MESSAGE_LOG_LEVEL is used.
** Send DLT control response to DLT client, with status of operation.
* DLT_SERVICE_ID_GET_LOG_INFO
** Create answer message for DLT control response. All kinds of requests are supported:
*** Application/Context:
**** All applications and all contexts
**** One application and all of its contexts
**** One application with one context.
*** Request type (as specified in the AUTOSAR DLT Standard, 1 and 2 are not specified):
**** 3: Application ID, Context ID
**** 4: Application ID, Context ID, Log Level
**** 5: Application ID, Context ID, Trace Status
**** 6: Application ID, Context ID, Log Level, Trace Status
**** 7: Application ID, Context ID, Log Level, Trace Status, Description
** Answer is of the corresponding type 3-7, or of type 8 (no matching context ids found), or of type 2 (error).
** Send DLT control response answer to DLT client.
* DLT_SERVICE_ID_GET_DEFAULT_LOG_LEVEL
** Send DLT control response with default log level to DLT client.
* DLT_SERVICE_ID_STORE_CONFIG
** Store configuration files with currently registered application ids and context ids as well as currently set log levels and trace statuses to configuration files. If these files exists, they will be read in when the DLT daemon is started next time.
** Send DLT control response to DLT client.
* DLT_SERVICE_ID_RESET_TO_FACTORY_DEFAULT
** Delete the stored configuration files, if they exists.
** Set default log level and trace status to initial values, and inform all applications using the default log level and trace status about the new defaults.
** Send DLT control response to DLT client.
* DLT_SERVICE_ID_SET_COM_INTERFACE_STATUS
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_SET_COM_INTERFACE_MAX_BANDWIDTH
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_SET_VERBOSE_MODE
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_SET_MESSAGE_FILTERING
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_SET_TIMING_PACKETS
** Set flag to start/stop sending of timing messages in thread.
** Send DLT control response to DLT client.
* DLT_SERVICE_ID_GET_LOCAL_TIME
** Send DLT control response with local time to DLT client.
* DLT_SERVICE_ID_USE_ECU_ID
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_USE_SESSION_ID
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_USE_TIMESTAMP
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_USE_EXTENDED_HEADER
** Send DLT control response "Not supported" to DLT client
* DLT_SERVICE_ID_SET_DEFAULT_LOG_LEVEL
** Check if received default log level is other than already stored default log level. If yes:
*** Store new default log level to internal structure.
*** Send a DLT_USER_MESSAGE_LOG_LEVEL to all DLT clients containing the new default log level, which uses a context which is set to default log level.
** Send DLT control response to DLT client, with status of operation.
* DLT_SERVICE_ID_SET_DEFAULT_TRACE_STATUS
** Check if received default trace status is other than already stored default trace status. If yes:
*** Store new default trace status to internal structure.
*** Send a DLT_USER_MESSAGE_LOG_LEVEL to all DLT clients containing the new default trace status, which uses a context which is set to default trace status.
** Send DLT control response to DLT client, with status of operation.
* DLT_SERVICE_ID_GET_SOFTWARE_VERSION
** Send DLT control response containing a software version string to DLT Client.
** The software version string contains:
*** the package version of the package dltv2, e.g. "2.0.0"
*** the package status of the package dltv2, e.g. "alpha, beta, final"
*** the overall subversion revision number for the package dltv2, e.g. "2300"
* DLT_SERVICE_ID_MESSAGE_BUFFER_OVERFLOW
** Try to send DLT control response containing the status of the internal flag for overflow. If the message could be send, reset the internal flag for overflow.

For handling of the injection message, the following steps occur:

* Create new user message DLT_USER_MESSAGE_INJECTION from received DLT control request message, and send this user message to the DLT application using the DLT user library.

=== Mapping to files

Here is a description, how the whole project is structured and which files exists.
The following table shows a top level view of the available Git repositories:

[options="header"]
|==============================================================================================
| Directory | Description
| dlt | DLT Daemon and Library implementation; command line utilities, examples and test programs
| dlt_viewer | DLT Client GUI (DLT Viewer): QT based implementation
|==============================================================================================

As this document has the focus on the DLT Daemon and the DLT user library, only the "dlt" directory is introduced in more detail:

[options="header"]
|==============================================================================================
| Directory | Description
| doc | Documentation
| include | Include files, installed on target
| package | Packaging support files
| src | Source Code
| src/shared | Shared source code (between DLT daemon and DLT user library)
| src/adaptor | Adaptors to DLT daemon:dlt-adaptor-stdin (for connection over stdin) dlt-adaptor-udp (for connection over UDP)
| src/console | Console utilities: dlt-receive, dlt-convert, and dlt-sortbytimestamp
| src/daemon | DLT Daemon
| src/example | Examples for usage of the DLT user library:dlt-example-user (Macro IF) anddlt-example-user-func (Function IF) andwintestclient (MS Windows based test client)
| src/lib | DLT library functions
| src/tests | Test programs:dlt-test-client and dlt-test-user for automatic tests, dlt-test-stress for stress tests, dlt-test-internal for internal tests
| src/winclientlib | MS Windows implementation of a client library
| testscripts | Several supporting scripts
|==============================================================================================

The DLT daemon implementation uses the following files, besides DLT functions from files from the shared directory:

[options="header"]
|==============================================================================================
| File | Description
| dlt-daemon.c | DLT daemon implementation
| dlt-daemon.h | Header file for dlt-daemon.c
| dlt-daemon_cfg.h | Compile time configuration for DLT daemon, Part1
| dlt_daemon_common.c | Supporting functions for a DLT daemon implementation
| dlt_daemon_common.h | Header file for dlt_daemon_common.c
| dlt_daemon_common_cfg.h | Compile time configuration for DLT daemon, Part2
|==============================================================================================

The DLT user library contains the following files:

[options="header"]
|==============================================================================================
| File | Description
| dlt_user.c | Implementation of functions, available via the DLT user library interface.
| dlt_user_cfg.h | Compile time configuration for dlt_user.c
| dlt_client.c | Functions required for DLT Client implementations
| dlt_client_cfg.h | Compile time configuration for dlt_client.c
|==============================================================================================

The shared directory contains the following files:

[options="header"]
|==============================================================================================
| File | Description
| dlt_common.c | Common helper functions, such as:
- Print functions for DLT messages
- Functions for handling DLT Ids
- Filter functions
- DLT message handling functions
- Functions for handling DLT files
- DLT receiver functions
- Log handling
- Ringbuffer functions
- Setting and checking of storage header
| dlt_common_cfg.h | Compile time configuration for dlt_common.c
| dlt_user_shared.c | Shared functions, required by the DLT daemon and the DLT user library, such as:
- Setting and checking the user header
- Sending DLT messages over named pipes (FIFOs)
| dlt_user_shared.h | Header file for dlt_user_shared.c
| dlt_user_shared_cfg.h | Compile time configuration for dlt_user_shared.c
|==============================================================================================

The public available include directory contains the following header files:

|==============================================================================================
| File | Description
| dlt.h | Overall include file, includes dlt_common.h and dlt_user.h
| dlt_common.h | Include file for dlt_common.c
| dlt_user.h | Include file for dlt_user.c, contains the "User API" functions
| dlt_user_macros.h | Include file for dlt_user.c, contains the "User API" macros
| dlt_client.h | Include file for dlt_client.c
| dlt_protocol.h | DLT protocol specfic definitions and macros
| dlt_types.h | Definition of types, must be adapted to the target architecture and compiler toolchain.
|==============================================================================================

=== Description of used structures in implementation

The following important structures are used in the DLT Daemon and DLT User Library:

[options="header"]
|==============================================================================================
| Structure | Description
| DltDaemonFlags | Flags and values, set over command line during start-up of DLT daemon
| DltDaemonLocal | Global variables of the DLT Daemon, grouped together in a struct
| DltDaemon | Parameters of the DLT daemon
| DltDaemonApplication | Parameters of an application, used within DLT daemon
| DltDaemonContext | Parameters of a context, used within DLT daemon
| DltUserControlMsg... | User control messages
| DltContext | Each context is represented with this structure
| DltContextData | Temorary used structure for constructing a log message
| DltUserInjectionCallback | One entry in dynamic callback table for callback function
| dlt_ll_ts_type | Table managing all contexts (and loglevels and trce statuses) within DLT user library, contains dynamicly growing array with "DltUserInjectionCallback" entries
| DltUser | Parameters for DLT user library application, contains dynamically growing array with "dlt_ll_ts_type" entries
| DltStorageHeader | Storage header
| DltStandardHeader | Structure for standard header of a DLT message |
| DltStandardHeaderExtra | Structure for standard header extra fields of a DLT message
| DltExtendedHeader | Structure for extended header of a DLT message
| DltService... | Structures for control messages (requests and responses)
| DltFilter | Structure to store filter parameters
| DltMessage | Structure to organize a DLT message, includes pointers to DltStorageHeader, DltStandardHeader, DltStandardHeaderExtra, and DltExtendedHeader, data of message is stored within a private buffer within this structure
| DltFile | Structure to organize access to a DLT File
| DltReceiver | Structure to organize the receiving of data
| DltRingbuffer | Structure to organize a ring buffer
|==============================================================================================

==== Implementation specifics

* The following preconditions were given prior to implementation:
** C-only implementation for the DLT daemon and the DLT user library
** Implementation of common functions, which can be used in a command line utility as well as in an Graphical UI
** Implementation of C+\+ like classes in C, see dlt_common.c and dlt_common.h
* The current implementation of the DLT daemon and DLT user library is only tested with gcc under Ubuntu 16.04 on Intel HW.
* It is assumed that packed structs are always stored in memory in the order specified within the packed struct.
* The implementation is multithread safe.
* Initialize DLT application and contexts, then forking and using the forked process, will lead to unclear behavior (or in worst case to a crash), as the forked process uses another process id as the parent process. Instead, initialize the DLT application and contexts in the forked process.
* Calling of DLT logging and tracing functions within a callback function for injections is not supported, and will lead to an unclear behavior.