Updated man pages and READMEs

- Updated INSTALL
- Updated README
- Fixed ReleaseNotes.txt for asciidoc generation
- Added manual for core dump handler
- Updated all man pages

Change-Id: I7154c14f92b3f7f6ca05c721d154a8e1aa7df1bf
Signed-off-by: Lutz Helwing <lutz_helwing@mentor.com>

1 files changed, 128 insertions, 0 deletions

diff --git a/doc/dlt_cdh.txt b/doc/dlt_cdh.txt
new file mode 100644
index 0000000..18302ab
--- /dev/null
+++ b/doc/dlt_cdh.txt
@@ -0,0 +1,128 @@
+////
+# 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 Core Dump Handler
+=====================
+Lutz Helwing <Lutz_Helwing@mentor.com>
+0.0.1, 23rd June 2015: Initial version
+
+image::images/genivi_chrome_1_transparent.png[width=128]
+
+
+Overview
+--------
+
+When a program crash occurs on the system the Core Dump Handler is triggered to extract relevant information from the core dump generated by the system. The handler stores this extracted information in the ECU's file system as Core Dump Handler Files. These files are transported via the link:dlt_filetransfer.html[DLT Filetransfer] mechanism. The transferred information can be combined and integrated into the developer toolchain (gdb, Release SW, etc.).
+
+image::images/dlt_core_dump_handler.png[width=600]
+
+
+Integration
+-----------
+
+To build the core dump handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add
+
+----
+-DWITH_DLT_COREDUMPHANDLER=ON -DTARGET_CPU_NAME={i686|x86_64}
+----
+
+options to cmake. The core dump handler code currently supports the i686 and x86_64 architecture.
+
+
+Temporary activation as replacement for default crash handler until next reboot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As *root* (not sudo) execute the following: +
+
+----
+echo "|/usr/local/bin/dlt-cdh %t %p %s %e" > /proc/sys/kernel/core_pattern
+----
+
+(NOTE: replace `/usr/local/bin` with the path dlt-cdh has been installed to) +
+This instructs the kernel to pipe a core dump as standard input to dlt-cdh together with the following parameters:
+
+* %t time of dump
+* %p PID of dumped process
+* %s number of signal causing dump
+* %e executable filename
+
+See
+
+----
+man core
+----
+
+for details
+
+
+Persistent activation as replacement for default crash handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In `/usr/lib/sysctl.d/` the file `50-coredump.conf` has to be created which is done automatically by
+
+----
+make install
+----
+
+Unfortunately - at least on Fedora systems - abrt has to be removed with
+
+----
+yum remove abrtd*
+----
+
+because it ruthlessly overwrites our change at every boot. +
+The core dump handler can be activated then without reboot by running
+
+----
+sysctl -p /usr/lib/sysctl.d/50-coredump.conf
+----
+
+
+Configuration of link:dlt_filetransfer.html[DLT Filetransfer] for usage with dlt-cdh
+------------------------------------------------------------------------------------
+
+Make sure the following is set in the "Filetransfer Manager" section of `/etc/dlt-system.conf`:
+
+----
+...
+FiletransferEnable = 1
+...
+FiletransferDirectory = /var/core
+...
+----
+
+
+Generation of core dump
+-----------------------
+
+When a crash happens the kernel invokes dlt-cdh and passes it the core dump as standard input. +
+dlt-cdh does the following tasks:
+
+* check if enough disk space available
+* create target directories if not existing:
+** /var/core
+** /var/core_tmp
+** /tmp/.core_locks
+* clean /var/core_tmp
+* retrieve context data mainly from /proc fs of the crashed process to a temporary context file in text format
+* initialise core dump
+* read ELF headers and notes to temporary core dump output file
+* move context file and core dump to /var/core
+* create id which identifies the crash
+
+After the files have been moved to /var/core the link:dlt_filetransfer.html[DLT Filetransfer] mechanism ensures that they are sent to connected clients.