From 10a2c7673d2ae9d9ef8d59a417b6554881531a66 Mon Sep 17 00:00:00 2001
From: eBardieCT <40671803+eBardieCT@users.noreply.github.com>
Date: Tue, 25 Sep 2018 14:49:29 +0100
Subject: Add dlt-sortbytimestamp utility plus documentation (#73)

* Add dlt-sortbytimestamp utility plus documentation

    Add a commandline utility to sort a DLT file by timestamp.

    By default a DLT file's messages are in the order they were
    received by the logger. This is not ideal for tracing problems on
    systems with multi-threaded programmes running on multi-core CPUs
    since message reception order will not always (or even often)
    correspond to message creation order.

    The documentation deals with how to handle the problem case of DLT
    files containing messages from multiple boot cycles.
---
 doc/dlt_user_manual.txt | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'doc/dlt_user_manual.txt')

diff --git a/doc/dlt_user_manual.txt b/doc/dlt_user_manual.txt
index 8b937b1..c8f444e 100644
--- a/doc/dlt_user_manual.txt
+++ b/doc/dlt_user_manual.txt
@@ -36,6 +36,7 @@ The SW components of DLT:
 * dlt-adaptor-stdin
 * dlt-adaptor-udp
 * dlt-convert
+* dlt-sortbytimestamp
 * dlt-receive
 * dlt-dbus
 * dlt-kpi
@@ -137,12 +138,13 @@ See Manpage dlt-system(1).
 See Manpage dlt-system.conf(5).
 
 == DLT command line tools
-Three command line tools are provided together with DLT daemon implementation.
+Four command line tools are provided together with DLT daemon implementation.
 
 These tools are:
 
 * Data logger: dlt-receive
 * Converter: dlt-convert
+* Sorter: dlt-sortbytimestamp
 * Configuration: dlt-control (planned)
 
 
@@ -162,6 +164,20 @@ The dlt-convert console utility is used to read DLT files, print DLT messages in
 ==== Command line interface
 See Manpage dlt-convert(1).
 
+=== dlt-sortbytimestamp
+
+==== Overview
+By default messages in DLT files are ordered according to the time the logger received them. This can unhelpful when tracing a sequence of events on a busy multi-threaded/multi-core system, because thread pre-emption combined with multiple processes attempting to log messages simultaneously means that the order in which the messages are received may vary significantly from the order in which they were created.
+
+The dlt-sortbytimestamp console utility is used to re-order the messages in DLT files, sorting them according to when the messages were created.
+
+Filters can be used to filter messages OR a range of messages to be processed can specified.
+
+Ranges are essential when processing a DLT file covering more than a single reboot cycle. This is because message timestamps are recorded relative to boot time and thus timestamping is reset to zero at each boot. Events from different boot cycles will have differing receive times, but may have identical boot relative timestamps. Using *dlt-sortbytimestamp* to sort such a DLT file will result in a tangled mess. Use ranges to avoid this. Use *dlt-viewer* to ascertain the start and end message indices of the desired range.
+
+==== Command line interface
+See Manpage dlt-sortbytimestamp(1).
+
 == DLT adaptors
 The DLT adaptors are used to interface legacy linux applications with the DLT daemon. Therefore, there are two adaptors:
 
-- 
cgit v1.2.1