summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristoph Lipka <clipka@jp.adit-jv.com>2016-10-20 11:15:26 +0900
committerChristoph Lipka <clipka@jp.adit-jv.com>2016-10-24 13:39:57 +0900
commit5eb2489014671823bb7ae579f738a7a208eae58d (patch)
tree6318198616ec28e3d84cbcb49a6e1e32dde0fead
parent5e776aa91512c2faa36cad037e30fa3aeda715a6 (diff)
downloadDLT-daemon-5eb2489014671823bb7ae579f738a7a208eae58d.tar.gz
doc: Documenatation update
Signed-off-by: Christoph Lipka <clipka@jp.adit-jv.com>
-rw-r--r--doc/CMakeLists.txt15
-rw-r--r--doc/dlt-logstorage-ctrl.136
-rw-r--r--doc/dlt-logstorage-ctrl.1.txt24
-rw-r--r--doc/dlt-passive-node-ctrl.1117
-rw-r--r--doc/dlt-passive-node-ctrl.1.txt67
-rw-r--r--doc/dlt.conf.546
-rw-r--r--doc/dlt.conf.5.txt19
-rw-r--r--doc/dlt_book.txt2
-rw-r--r--doc/dlt_design_specification.txt4
-rw-r--r--doc/dlt_multinode.txt80
-rw-r--r--doc/dlt_offline_logstorage.txt119
11 files changed, 433 insertions, 96 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 065f8ad..6c59b06 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -46,6 +46,7 @@ if(WITH_DOC)
COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_extended_network_trace.html ${CMAKE_SOURCE_DIR}/doc/dlt_extended_network_trace.txt
COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_howto_debug.html ${CMAKE_SOURCE_DIR}/doc/dlt_howto_debug.txt
COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_offline_logstorage.html ${CMAKE_SOURCE_DIR}/doc/dlt_offline_logstorage.txt
+ COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_multinode.html ${CMAKE_SOURCE_DIR}/doc/dlt_multinode.txt
COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt-kpi.html ${CMAKE_SOURCE_DIR}/doc/dlt_kpi.txt
COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt-cdh.html ${CMAKE_SOURCE_DIR}/doc/dlt_cdh.txt
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc
@@ -60,6 +61,7 @@ if(WITH_DOC)
COMMAND a2x --doctype manpage --format manpage ${CMAKE_SOURCE_DIR}/doc/dlt.conf.5.txt
COMMAND a2x --doctype manpage --format manpage ${CMAKE_SOURCE_DIR}/doc/dlt-system.conf.5.txt
COMMAND a2x --doctype manpage --format manpage ${CMAKE_SOURCE_DIR}/doc/dlt-logstorage-ctrl.1.txt
+ COMMAND a2x --doctype manpage --format manpage ${CMAKE_SOURCE_DIR}/doc/dlt-passive-node-ctrl.1.txt
)
endif(WITH_DOC)
@@ -86,7 +88,8 @@ if(WITH_MAN)
${MAN_SRC_DIR}/dlt-daemon.1
${MAN_SRC_DIR}/dlt-receive.1
${MAN_SRC_DIR}/dlt-system.1
- ${MAN_SRC_DIR}/dlt-logstorage-ctrl.1)
+ ${MAN_SRC_DIR}/dlt-logstorage-ctrl.1
+ ${MAN_SRC_DIR}/dlt-passive-node-ctrl.1)
set(MAN_BUILD_SRC
${MAN_BUILD_DIR}/dlt.conf.5
${MAN_BUILD_DIR}/dlt-system.conf.5
@@ -94,7 +97,8 @@ if(WITH_MAN)
${MAN_BUILD_DIR}/dlt-daemon.1
${MAN_BUILD_DIR}/dlt-receive.1
${MAN_BUILD_DIR}/dlt-system.1
- ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1)
+ ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1
+ ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1)
set(MAN_BUILD_GZ
${MAN_BUILD_DIR}/dlt.conf.5.gz
${MAN_BUILD_DIR}/dlt-system.conf.5.gz
@@ -102,7 +106,8 @@ if(WITH_MAN)
${MAN_BUILD_DIR}/dlt-daemon.1.gz
${MAN_BUILD_DIR}/dlt-receive.1.gz
${MAN_BUILD_DIR}/dlt-system.1.gz
- ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz)
+ ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz
+ ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz)
foreach(MAN ${MAN_SRC})
execute_process(COMMAND ${CMAKE_COMMAND} -E copy ${MAN} ${MAN_BUILD_DIR})
@@ -115,7 +120,8 @@ if(WITH_MAN)
COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-daemon.1 > ${MAN_BUILD_DIR}/dlt-daemon.1.gz
COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-receive.1 > ${MAN_BUILD_DIR}/dlt-receive.1.gz
COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-system.1 > ${MAN_BUILD_DIR}/dlt-system.1.gz
- COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1 > ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz)
+ COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1 > ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz
+ COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1 > ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz)
# If user has not set the base dir for man pages, use a default location
set(MAN_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/share/man)
@@ -132,6 +138,7 @@ if(WITH_MAN)
${MAN_BUILD_DIR}/dlt-receive.1.gz
${MAN_BUILD_DIR}/dlt-system.1.gz
${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz
+ ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz
DESTINATION ${MAN_INSTALL_DIR}/man1
)
endif(WITH_MAN)
diff --git a/doc/dlt-logstorage-ctrl.1 b/doc/dlt-logstorage-ctrl.1
index d35a6ea..ac6554d 100644
--- a/doc/dlt-logstorage-ctrl.1
+++ b/doc/dlt-logstorage-ctrl.1
@@ -7,7 +7,7 @@
.\" Source: \ \&
.\" Language: English
.\"
-.TH "DLT\-LOGSTORAGE\-CTR" "1" "02/23/2016" "\ \&" "\ \&"
+.TH "DLT\-LOGSTORAGE\-CTRL" "1" "02/23/2016" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -31,7 +31,7 @@
dlt-logstorage-ctrl \- Trigger DLT Daemon to start/stop using an offline logstorage device
.SH "SYNOPSIS"
.sp
-\fBdlt\-logstorage\-ctrl\fR [\-h] [\-c ctype] [\-d dev] [\-e ecu] [\-t timeout]
+\fBdlt\-logstorage\-ctrl\fR [\-h] [\-c ctype] [\-p path] [\-e ecu] [\-p<prop>] [\-t timeout] [\-v]
.SH "DESCRIPTION"
.sp
Send a trigger to DLT Daemon to connect/disconnect a certain offline logstorage device
@@ -49,7 +49,12 @@ Specify connection type: connect = 1, disconnect = 0\&.
.PP
\fB\-d\fR
.RS 4
-Specify device [1 \&.\&. DLT_OFFLINE_LOGSTORAGE_MAX_DEVICES]\&.
+Run as daemon: prop = use proprietary handler\&.
+.RE
+.PP
+\fB\-p\fR
+.RS 4
+Mount point path\&.
.RE
.PP
\fB\-e\fR
@@ -61,27 +66,44 @@ Specify the ECU ID\&. Default is: ECU1\&.
.RS 4
Specify connection timeout\&. Default is: 10s\&.
.RE
+.PP
+\fB\-v\fR
+.RS 4
+Print verbose output\&.
+.RE
.SH "EXAMPLES"
.sp
-Activate the offline logstorage device mounted on /tmp/dltlogs/dltlogsdev1
+Activate the offline logstorage device mounted on /mnt/dltlog\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+dlt\-logstorage\-ctrl \-c 1 \-p /mnt/dltlog\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Deactivate the offline logstorage device mounted on /mnt/dltlog\&.
.sp
.if n \{\
.RS 4
.\}
.nf
-dlt\-logstorage\-ctrl \-c 1 \-d 1
+dlt\-logstorage\-ctrl \-c 0 \-p /mnt/dltlog\&.
.fi
.if n \{\
.RE
.\}
.sp
-Deactivate the offline logstorage device mounted on /tmp/dltlogs/dltlogsdev2
+Run logstorage control application as daemon listen to udev events\&.
.sp
.if n \{\
.RS 4
.\}
.nf
-dlt\-logstorage\-ctrl \-c 0 \-d 2
+dlt\-logstorage\-ctrl -d\&.
.fi
.if n \{\
.RE
diff --git a/doc/dlt-logstorage-ctrl.1.txt b/doc/dlt-logstorage-ctrl.1.txt
index e8950da..aa7c6c8 100644
--- a/doc/dlt-logstorage-ctrl.1.txt
+++ b/doc/dlt-logstorage-ctrl.1.txt
@@ -8,7 +8,7 @@ dlt-logstorage-ctrl - Trigger DLT Daemon to start/stop using an offline logstora
SYNOPSIS
--------
-*dlt-logstorage-ctrl* [-h] [-c ctype] [-d dev] [-e ecu] [-t timeout]
+*dlt-logstorage-ctrl* [-h] [-c ctype] [-p path] [-e ecu] [-p<prop>] [-t timeout] [-v]
DESCRIPTION
-----------
@@ -23,7 +23,10 @@ OPTIONS
Specify connection type: connect = 1, disconnect = 0.
*-d*::
- Specify device [1 .. DLT_OFFLINE_LOGSTORAGE_MAX_DEVICES].
+ Run as daemon: prop = use proprietary handler
+
+*-p*::
+ Mount point path.
*-e*::
Specify the ECU ID. Default is: ECU1.
@@ -33,16 +36,22 @@ OPTIONS
EXAMPLES
--------
-Activate the offline logstorage device mounted on /tmp/dltlogs/dltlogsdev1
+Activate the offline logstorage device mounted on /mnt/dltlog
+
+----
+dlt-logstorage-ctrl -c 1 -p /mnt/dltlog
+----
+
+Deactivate the offline logstorage device mounted on /mnt/dltlog
----
-dlt-logstorage-ctrl -c 1 -d 1
+dlt-logstorage-ctrl -c 0 -p /mnt/dltlog
----
-Deactivate the offline logstorage device mounted on /tmp/dltlogs/dltlogsdev2
+Run logstorage control application as daemon listen to udev events
----
-dlt-logstorage-ctrl -c 0 -d 2
+dlt-logstorage-ctrl -d
----
EXIT STATUS
@@ -56,10 +65,9 @@ Syed Hameed (shameed (at) jp.adit-jv.com)
RESOURCES
---------
-Main web site: <http://projects.genivi.org/diagnostic-log-trace> +
+Main web site: <https://at.projects.genivi.org/wiki/display/PROJ/Diagnostic+Log+and+Trace> +
Mailinglist: <https://lists.genivi.org/mailman/listinfo/genivi-diagnostic-log-and-trace>
SEE ALSO
--------
dlt-daemon(1)
-
diff --git a/doc/dlt-passive-node-ctrl.1 b/doc/dlt-passive-node-ctrl.1
new file mode 100644
index 0000000..919182d
--- /dev/null
+++ b/doc/dlt-passive-node-ctrl.1
@@ -0,0 +1,117 @@
+'\" t
+.\" Title: dlt-passive-node-ctrl
+.\" Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 10/19/2016
+.\" Manual: \ \&
+.\" Source: \ \&
+.\" Language: English
+.\"
+.TH "DLT\-PASSIVE\-NODE\-CTRL" "1" "10/19/2016" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+dlt-passive-node-ctrl \- Send a trigger to DLT daemon to (dis)connect a passive node or get current passive node status
+.SH "SYNOPSIS"
+.sp
+\fBdlt\-passive\-node\-ctrl\fR [\-h] [\-c ctype] [\-n ecu] [\-s] [\-t timeout] [\-v]
+.SH "DESCRIPTION"
+.sp
+Send a trigger to DLT daemon to (dis)connect a passive node or get current passive node status
+.SH "OPTIONS"
+.PP
+\fB\-h\fR
+.RS 4
+Display a short help text\&.
+.RE
+.PP
+\fB\-c\fR
+.RS 4
+Specify connection type: connect = 1, disconnect = 0\&.
+.RE
+.PP
+\fB\-n\fR
+.RS 4
+Passive node identifier. E.g. ECU2\&.
+.RE
+.PP
+\fB\-s\fR
+.RS 4
+Show passive nodes connection status\&.
+.RE
+.PP
+\fB\-t\fR
+.RS 4
+Specify connection timeout\&. Default is: 10s\&.
+.RE
+.PP
+\fB\-v\fR
+.RS 4
+Print verbose output\&.
+.RE
+.SH "EXAMPLES"
+.sp
+Get status about connected passives nodes\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+dlt\-passive\-node\-ctrl \-s\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Connect to passive node ECU2\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+dlt\-passive\-node\-ctrl \-c 1 \-n ECU2\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Disconnect to passive node ECU2\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+dlt\-passive\-node\-ctrl \-c 0 \-n ECU2\&.
+.fi
+.if n \{\
+.RE
+.\}
+.SH "EXIT STATUS"
+.sp
+Non zero is returned in case of failure\&.
+.SH "AUTHOR"
+.sp
+Christoph Lipka (clipka (at) jp\&.adit\-jv\&.com)l
+.SH "RESOURCES"
+.sp
+Main web site: http://projects\&.genivi\&.org/diagnostic\-log\-trace Mailinglist: https://lists\&.genivi\&.org/mailman/listinfo/genivi\-diagnostic\-log\-and\-trace
+.SH "SEE ALSO"
+.sp
+dlt\-daemon(1)
diff --git a/doc/dlt-passive-node-ctrl.1.txt b/doc/dlt-passive-node-ctrl.1.txt
new file mode 100644
index 0000000..f60648d
--- /dev/null
+++ b/doc/dlt-passive-node-ctrl.1.txt
@@ -0,0 +1,67 @@
+DLT-PASSIVE-NODE-CTRL(1)
+========================
+:doctype: manpage
+
+NAME
+----
+dlt-passive-node-ctrl - Send a trigger to DLT daemon to (dis)connect a passive node or get current passive node status
+
+SYNOPSIS
+--------
+*dlt-passive-node-ctrl* [-h] [-c] [-n ecu] [-s] [-t timeout] [-v]
+
+DESCRIPTION
+-----------
+Send a trigger to DLT daemon to (dis)connect a passive node or get current passive node status
+
+OPTIONS
+-------
+*-h*::
+ Usage
+*-c*::
+ Connection status (1 - connect, 0 - disconnect)
+*-n*::
+ Passive Node identifier (e.g. ECU2)
+*-s*::
+ Show passive node(s) connection status
+*-t*::
+ Specify connection timeout (Default: 10s)
+*-v*::
+ Set verbose flag (Default:0)
+
+EXAMPLES
+--------
+Get status about connected passives nodes
+
+----
+dlt-passive-node-ctrl -s
+----
+
+Connect to passive node ECU2
+
+----
+dlt-passive-node-ctrl -c 1 -n ECU2
+----
+
+Disconnect to passive node ECU2
+
+----
+dlt-passive-node-ctrl -c 0 -n ECU2
+----
+
+EXIT STATUS
+-----------
+Non zero is returned in case of failure.
+
+AUTHOR
+------
+Christoph Lipka (clipka (at) jp.adit-jv.com)
+
+RESOURCES
+---------
+Main web site: <https://at.projects.genivi.org/wiki/display/PROJ/Diagnostic+Log+and+Trace> +
+Mailinglist: <https://lists.genivi.org/mailman/listinfo/genivi-diagnostic-log-and-trace>
+
+SEE ALSO
+--------
+dlt-daemon(1)
diff --git a/doc/dlt.conf.5 b/doc/dlt.conf.5
index 2768992..0dbf9b3 100644
--- a/doc/dlt.conf.5
+++ b/doc/dlt.conf.5
@@ -113,21 +113,6 @@ Default: ECU1
.\}
.RE
.PP
-\fBGatewayMode\fR
-.RS 4
-If set to 1 gateway mode is enabled which means this ECU serves as gateway to forward messages from others\&.
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-Default: 0
-.fi
-.if n \{\
-.RE
-.\}
-.RE
-.PP
\fBSharedMemorySize\fR
.RS 4
This value sets the size of the shared memory, which is used to exchange DLT messages between applications and daemon\&. This value is defined in bytes\&. If this value is changed the system must be rebooted to take effect\&.
@@ -317,6 +302,37 @@ Default: 0
.RE
.\}
.RE
+.SH "GATEWAY CONFIGURATION OPTIONS"
+.PP
+\fBGatewayMode\fR
+.RS 4
+If set to 1 gateway mode is enabled which means this ECU serves as gateway to forward messages from others\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Default: 0
+.fi
+.if n \{\
+.RE
+.\}
+.RE
+.PP
+\fBGatewayConfigFile\fR
+.RS 4
+Read gateway configuration from another location\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Default: /tmp/dlt\-ctrl\&.sock /etc/dlt_gateway\&.conf
+.fi
+.if n \{\
+.RE
+.\}
+.RE
.SH "CONTROL APPLICATION OPTIONS"
.PP
\fBControlSocketPath\fR
diff --git a/doc/dlt.conf.5.txt b/doc/dlt.conf.5.txt
index 62a69e4..8f4f2e7 100644
--- a/doc/dlt.conf.5.txt
+++ b/doc/dlt.conf.5.txt
@@ -53,12 +53,6 @@ GENERAL OPTIONS
Default: ECU1
-*GatewayMode*::
- If set to 1 gateway mode is enabled which means this ECU serves as gateway
- to forward messages from others.
-
- Default: 0
-
*SharedMemorySize*::
This value sets the size of the shared memory, which is used to exchange
DLT messages between applications and daemon. This value is defined in
@@ -129,6 +123,19 @@ GENERAL OPTIONS
Default: 0
+GATEWAY CONFIGURATION
+---------------------
+
+*GatewayMode*::
+ Enable Gateway mode
+
+ Default: 0
+
+*GatewayConfigFile*::
+ Read gateway configuration from another location
+
+ Default: /etc/dlt_gateway.conf
+
CONTROL APPLICATION OPTIONS
---------------------------
diff --git a/doc/dlt_book.txt b/doc/dlt_book.txt
index 1c0b539..695c36f 100644
--- a/doc/dlt_book.txt
+++ b/doc/dlt_book.txt
@@ -53,6 +53,8 @@ include::dlt_extended_network_trace.txt[]
include::dlt_offline_logstorage.txt[]
+include::dlt_multinode.txt[]
+
include::dlt_kpi.txt[]
include::dlt_cdh.txt[]
diff --git a/doc/dlt_design_specification.txt b/doc/dlt_design_specification.txt
index ce311d6..4d52a2a 100644
--- a/doc/dlt_design_specification.txt
+++ b/doc/dlt_design_specification.txt
@@ -43,7 +43,7 @@ The DLT daemon is the central component between the DLT clients and one or more
==== 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). 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 select()). 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.
+The main time, the DLT daemon executes a main loop, in which file and socket descriptors are watched (via epoll()). 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
@@ -77,7 +77,7 @@ During initialization of the DLT daemon, the following steps occur:
==== Main loop
In the main loop, the following things occur:
-* Wait for event on the incoming named pipe, the TCP connections (the one connection for new connections, and all TCP connections from clients), and possibly on the serial device, via select() call.
+* Wait for event on the incoming named pipe, the TCP connections (the one connection for new connections, and all TCP connections from clients), and possibly on the serial device, via epoll() 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
diff --git a/doc/dlt_multinode.txt b/doc/dlt_multinode.txt
new file mode 100644
index 0000000..c7bdee5
--- /dev/null
+++ b/doc/dlt_multinode.txt
@@ -0,0 +1,80 @@
+DLT MultiNode
+=============
+Christoph Lipka <clipka@jp.adit-jv.com>
+0.0.1, 2016/10/19 Initial Version
+
+Overview
+--------
+
+MultiNode allows to connect DLT Daemons running on different operating systems, e.g. in a virtualized environment.
+The central component is the Gateway DLT Daemon which connects external DLT Clients, like the DLT Viewer running on a host computer with Passive DLT Daemons running on nodes without a physical connection to external DLT clients.
+All communication between passive nodes and DLT Viewer has to be send via the Gateway node. The Gateway node forwards log messages coming from passive nodes to all connected DLT clients.
+The Gateway DLT Daemon also forwards command and control requests coming from DLT clients to the corresponding passive node.
+
+Precondition
+------------
+The dlt.conf configuration file which is read by each DLT Daemon on start-up contains an entry to specify the ECU identifier (node identifier).
+It has to be ensured, that each DLT Daemon in the System has a unique ECU identifier specified.
+The ECU identifier is included in every DLT Message and is used to distinguish if a DLT message has to be forwarded to a passive node or handled by the Gateway DLT Daemon itself.
+
+Configuration
+-------------
+The dlt.conf configuration file provides an option to enable the Gateway functionality of a DLT Daemon.
+The default setting is 0 (Off), which means the Gateway functionality is not available.
+
+# Enable Gateway mode (Default: 0)
+GatewayMode = 1
+
+Gateway Configuration File
+--------------------------
+The MultiNode configuration file has to be loaded by the Gateway DLT Daemon during startup.
+----
+[PassiveNode1]
+; IP Address. (Mandatory)
+IPaddress = 192.168.2.32
+; TCP port. Default 3490 is used if no port is specified
+Port = 3495
+; Passive node ECU identifier. (Mandatory)
+EcuID = ECU2
+; Connection to passive node only on demand. Default ‘OnStartup’ if not specified
+Connect = OnDemand
+; timeout in seconds
+Timeout = 10
+; Send following control messages after connection is established
+SendControl=0x03, 0x13
+; Send SerialHeader with control messages. Value in dlt.conf is used
+; as default if not specified
+SendSerialHeader=1
+----
+The configuration file is written in an INI file format and contains information about different connected passive nodes.
+Each passive node’s connection parameters are specified in a unique numbered separate section ([PassiveNode{1,2, …N}]).
+Because TCP is the only supported communication channel, the IPaddress and Port of the Passive 682 DLT Daemon has to be specified.
+
+With the Connect property it is possible to specify when the Gateway DLT Daemon shall connect to the passive node.
+The following values are allowed:
+ - OnStartup
+ The Gateway DLT Daemon tries to connect to the Passive DLT Daemon immediately after the Gateway DLT Daemon is started.
+ - OnDemand
+ The Gateway DLT Daemon tries to connect to the Passive DLT Daemon when it receives a connection request.
+
+The Timeout property specifies the time after which the Gateway DLT Daemon stops connecting attempts to a Passive DLT Daemon.
+If the connection is not established within the specified time, the Gateway DLT Daemon gives up connecting attempts and writes an error messages to its internal log.
+The following control messages are supported to be send to a passive node automatically after connection is established:
+ - 0x03: Get Log Info
+ - 0x13: Get Software Version
+
+Using dlt-passive-node control application
+------------------------------------------
+
+----
+Usage: dlt-passive-node-ctrl [options]
+Send a trigger to DLT daemon to (dis)connect a passive node or get current passive node status.
+
+Options:
+ -c Connection status (1 - connect, 0 - disconnect)
+ -h Usage
+ -n passive Node identifier (e.g. ECU2)
+ -s Show passive node(s) connection status
+ -t Specify connection timeout (Default: 10s)
+ -v Set verbose flag (Default:0)
+----
diff --git a/doc/dlt_offline_logstorage.txt b/doc/dlt_offline_logstorage.txt
index d166a2e..49a2a30 100644
--- a/doc/dlt_offline_logstorage.txt
+++ b/doc/dlt_offline_logstorage.txt
@@ -1,7 +1,7 @@
DLT Offline Logstorage
======================
Christoph Lipka <clipka@jp.adit-jv.com>
-0.0.1, 2015/05/26
+0.0.2, 2016/10/19 Updated Version
Overview
--------
@@ -11,37 +11,43 @@ The goal of DLT is the consolidation of the existing variety of logging and trac
Introduction to DLT Offline Logstorage
--------------------------------------
-With DLT Offline Logstorage it is possible to store logs on the target system or an external device connected to the target. It can be seen as an improvement of the already available Offline Trace functionality. +
-
-DLT Offline Logstorage offers the following functionality: +
-
-- store logs in sets of log files defined by configuration files
-- configuration filter options are:
- * application IDs (single apid, list of apids, .* as wildcard)
- * context IDs (single ctid, list of ctids, .* as wildcard)
- * log level
-- configuration file storing options are:
- * file name
- * file size
- * number of files
-- trigger start and stop logging by using the dlt-logstorage-ctrl application
+Logstorage is a mechanism to store DLT logs on the target system or an external device (e.g. USB stick) connected to the target.
+It can be seen as an improvement of the Offline Trace functionality which is already part of DLT.
+
+Logstorage provides the following features:
+ - Store logs in sets of log files defined by configuration files
+ - Log file content is configurable
+ - Configurable options are:
+ - Application identifier (single entry, list, wildcard)
+ - Context identifier (single entry, list, wildcard)
+ - Log level
+ - ECU identifier
+ - Log files are configurable in terms of:
+ - File name and naming scheme
+ - File size
+ - Number of files
+ - Log message synchronization strategy is configurable
+ - Trigger start and stop logging using a control application
+ - Integration into Udev device management
Filter configuration
--------------------
-The default name for the configuration file is dlt_logstorage.conf. This file has to be stored directly in the folder that will contain the log files later. Or in other words, in the folder that is mounted at the mountpoint /tmp/dltlogs/dltlogsdevX
-
-As seen in example configuration file, a filter configuration consists of +
-
-- A *unique name* of the filter (for a certain storage device). The name must be *[FILTERX]* where X is a unique number for that storage device.
-- *LogAppName* Name of application to store logs from. Multiple applications can be separated by "," and ".*" denotes all applications
-- *ContextName* Name or names of contexts to store logs from. Multiple contexts can be separated by "," and ".*" denotes all contexts of the application
-- *LogLevel* Define log level, e.g. DLT_LOG_INFO
-- *File* Base name of the created files that containing the logs, e.g. "example". The first file will have the name example_001_<timestamp>.dlt, the second example_002_<timestamp>.dlt and so on. Timestamp will be printed in form "YYMMDD-hhmmss".
-- *FileSize* File size in bytes
-- *NOFiles* Number of created files before oldest is deleted and a new one is created. The numbering will continue. E.g. If 10 files have to be created and the first is deleted, the next one is <File name>_011_<timestamp>.dlt
-
-*Note*: Not allowed is the combination of wildcards for LogAppName *and* ContextName. +
+For DLT daemon to store logs the configuration file named “dlt_logstorage.conf” should be present in external storage or internal storage device.
+The format is defined as follows:
+----
+[Filter<unique number>] # filter configration name
+LogAppName=<APID> # Name of application to store logs from. Multiple applications can be separated by "," and ".*" denotes all applications
+ContextName=<CTID> # Name or names of contexts to store logs from. Multiple contexts can be separated by "," and ".*" denotes all contexts of the application
+LogLevel=<Log level> # Define log level, e.g. DLT_LOG_INFO or DLT_LOG_FATAL
+File=<file name> # Base name of the created files that containing the logs, e.g. "example". For further file naming scheme configurations see man dlt.conf
+FileSize=<file size in bytes> # Maximum file size in bytes
+NOFiles=<number of files> # Number of created files before oldest is deleted and a new one is created
+SyncBehavior=<strategy> # Specify sync strategy. Default: Sync'ed after every message. See Logstorage Rinbuffer Implementation below.
+EcuID=<ECUid> # Specify ECU identifier
+----
+The Parameter "SyncBehavior" and "EcuID" are optional - all others are mandatory.
+*Note*: Not allowed is the combination of wildcards for LogAppName *and* ContextName. The Parameter "SyncBehavior" and "EcuID" are optional - all others are mandatory. +
An configuration file should look like: +
@@ -61,6 +67,8 @@ LogLevel=DLT_LOG_ERROR
File=Test
FileSize=250000
NOFiles=5
+SyncStrategy=ON_DEMAND
+EcuID=ECU1
----
Filter algorithm
@@ -85,23 +93,6 @@ When a message arrives at the filter, three checks have to be done. It has to be
If one or more keys are valid the message is stored in the file of the corresponding filter if the log level is lesser than specified (FATAL < ... < INFO < ...).
If not, the incoming message will be ignored.
-Default search path and folder names for Logstorage devices
------------------------------------------------------------
-Path
-~~~~
-The default search path for logstorage devices is: */tmp/dltlogs/*. This default
-path can be changed in the dlt_offline_logstorage.h header file.
-
-Folder
-~~~~~~
-The default name for Logstorage device folders is *dltlogsdevX*.
-X is a number between 1 and the maximal configured number of Logstorage devices DLT_OFFLINE_LOGSTORAGE_MAX_DEVICES.
-
-A complete Logstorage path looks like: /tmp/dltlogs/dltdevlogs1
-
-This folder can be used directly to store logs or it can be used as mount point for external devices.
-
-
Using DLT Offline Logstorage
----------------------------
Enable OfflineLogstorage by setting OfflineLogstorageMaxDevices = 1 in dlt.conf.
@@ -110,7 +101,7 @@ Be aware that the performance of DLT may drop if multiple Logstorage devices are
Create the device folder: +
----
-mkdir -p /tmp/dltlogs/dltlogsdev1
+mkdir -p /var/dltlogs
----
Create the configuration file and store it on into that folder or mount an external device containing a configuration file.
@@ -120,30 +111,33 @@ Start the DLT Daemon. This is not necessary if the DLT Daemon was started alread
Trigger DLT Daemon to use the new logstorage device: +
----
-dlt-logstorage-ctrl -c 1 -d 1
+dlt-logstorage-ctrl -c 1 -p /var/dltlogs
----
Afterwards, logs that match the filter configuration are stored onto the Logstorage device.
----
-dlt-logstorage-ctrl -c 0 -d 1
+dlt-logstorage-ctrl -c 0 -p /var/dltlogs
----
-Afterwards the configured logstorage device 1 is disconnected from the DLT Daemon.
+Afterwards the configured logstorage device is disconnected from the DLT Daemon.
Using dlt-logstorage-ctrl application
-------------------------------------
----
Usage: dlt-logstorage-ctrl [options]
-Send a trigger to DLT daemon to connect/disconnect a certain logstorage device. Logging starts after a succesfful connection automatically.
+Send a trigger to DLT daemon to connect/disconnecta certain logstorage device
Options:
-c Connection type: connect = 1, disconnect = 0
- -d Device: [1 .. DLT_OFFLINE_LOGSTORAGE_MAX_DEVICES]
+ -d[prop] Run as daemon: prop = use proprietary handler
+ 'prop' may be replaced by any meaningful word
-e Set ECU ID (Default: ECU1)
-h Usage
+ -p Mount point path
-t Specify connection timeout (Default: 10s)
+ -v Set verbose flag (Default:0)
----
Testing DLT Offline Logstorage
@@ -159,7 +153,7 @@ The following procedure can be used to test Offline Logstorage:
. Create the device folder
- $ mkdir -p /tmp/dltlogs/dltlogsdev1
+ $ mkdir -p /var/dltlog
. Create the configuration file "dlt_logstorage.conf" in this folder
and define filter configuration(s):
@@ -174,13 +168,30 @@ The following procedure can be used to test Offline Logstorage:
. Trigger dlt-daemon to use a new device
- $ dlt-logstorage-ctrl -c 1 -d 1
+ $ dlt-logstorage-ctrl -c 1 -p /var/dltlog
. Start dlt-example-user
$ dlt-example-user Hello123
-. After execution, a log file is created in /tmp/dltlogs/dltlogsdev1
+. After execution, a log file is created in /var/dltlogs
e.g. example_001_20150512_133344.dlt
. To check the content of the file open it with dlt-convert or DLT Viewer.
+
+Logstorage Ring Buffer Implementation
+-------------------------------------
+The DLT Logstorage is mainly used to store a configurable set of logs on an external mass storage device attached to the target.
+In this scenario, writing each incoming log message directly onto the external storage device is appreciate, because the storage device might be un-mounted/suddenly removed at any time.
+Writing each log message immediately avoids the problem of losing too many messages because the file system sync could not be finished before the device has been removed physically from the target.
+On the other hand the DLT Logstorage feature might be used as well to store a configurable set of logs on any internal, nonvolatile memory (e.g. FLASH storage device).
+Due to the reason of limited write cycles of a FLASH device the number of write cycles has to be reduced as much as possible.
+But the drawback of losing log messages in case of an unexpected operating system crash has to be taking into account as well.
+The obvious idea is to cache incoming log messages in memory and write the log data to disk based on a certain strategy.
+Incoming log messages are stored in a data cache with a specific size. Depending on user defined strategy, the data cache is written onto the storage device、without relying on the sync mechanism of the file system.
+
+The following strategies are implemented:
+. ON_MSG - sync every message
+. ON_DAEMON_EXIT - sync on daemon exit
+. ON_DEMAND - sync on demand
+. Combinations (not allowed: combinations with ON_MSG)