Rework reference manual a bit, start reworking test case layout

11 files changed, 509 insertions, 408 deletions

diff --git a/docs/reference/node-startup-controller/Makefile.am b/docs/reference/node-startup-controller/Makefile.am
index 42c24ea..5373774 100644
--- a/docs/reference/node-startup-controller/Makefile.am
+++ b/docs/reference/node-startup-controller/Makefile.am
@@ -69,6 +69,11 @@ HTML_IMAGES=
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files =								\
+	about.xml							\
+	functional-scope.xml						\
+	legacy-app-handler.xml						\
+	public-interfaces.xml						\
+	software-architecture.xml					\
 	version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
@@ -90,7 +95,6 @@ include $(top_srcdir)/gtk-doc.make
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST +=								\
-	legacy-app-handler.xml						\
 	version.xml.in
 
 # Files not to distribute
diff --git a/docs/reference/node-startup-controller/about.xml b/docs/reference/node-startup-controller/about.xml
new file mode 100644
index 0000000..97efe9e
--- /dev/null
+++ b/docs/reference/node-startup-controller/about.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="about">
+  <refmeta>
+    <refentrytitle>About this document</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>About this document</refname>
+    <refpurpose>Understand the purpose of this document</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Purpose of the reference manual</title>
+    <para>
+      The purpose of this reference manual is to provide documentation about the public
+      API of the Node Startup Controller as well as to give an overview of the classes
+      used in the implementation internally.
+    </para>
+    <para>
+      The intended readers of the reference manual are developers of GENIVI components
+      that interact with the Node Startup Controller and people who want to contribute
+      to the Node Startup Controller development. Reading this reference manual will
+      will help them to understand how the Node Startup Controller can be used and how
+      it is organised internally.
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/reference/node-startup-controller/functional-scope.xml b/docs/reference/node-startup-controller/functional-scope.xml
new file mode 100644
index 0000000..b085437
--- /dev/null
+++ b/docs/reference/node-startup-controller/functional-scope.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="functional-overview">
+  <refmeta>
+    <refentrytitle>Functional scope</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Functional scope</refname>
+    <refpurpose>An overview of the functionality provided by the Node Startup Controller</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="luc-management">
+    <title>Last User Context (LUC) management</title>
+    <para>
+      TODO
+    </para>
+  </refsect1>
+
+  <refsect1 id="legacy-application-management">
+    <title>Legacy application management</title>
+    <para>
+      TODO
+    </para>
+  </refsect1>
+
+  <refsect1 id="target-startup-monitoring">
+    <title>Target startup monitoring</title>
+    <para>
+      TODO
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/reference/node-startup-controller/node-startup-controller-docs.xml b/docs/reference/node-startup-controller/node-startup-controller-docs.xml
index 657cd77..e7a1181 100644
--- a/docs/reference/node-startup-controller/node-startup-controller-docs.xml
+++ b/docs/reference/node-startup-controller/node-startup-controller-docs.xml
@@ -45,73 +45,45 @@
     </authorgroup>
   </bookinfo>
 
-  <chapter>
-    <title>Node Startup Controller Overview</title>
-    <sect1>
-      <title>Purpose of the Reference Manual</title>
-      <para>
-        The purpose of this reference manual is to provide documentation about the public
-        API of the Node Startup Controller as well as to give an overview of the classes
-        used in the implementation internally.
-      </para>
-      <para>
-        The intended readers of the reference manual are developers of GENIVI components
-        that interact with the Node Startup Controller and people who want to contribute
-        to the Node Startup Controller development. Reading this reference manual will
-        will help them to understand how the Node Startup Controller can be used and how
-        it is organised internally.
-      </para>
-    </sect1>
-    <sect1>
-      <title>Functional Overview</title>
-    </sect1>
-    <sect1>
-      <title>Public API Overview</title>
-    </sect1>
-    <sect1>
-      <title>Software Architecture</title>
-    </sect1>
-  </chapter>
+  <part id="overview">
+    <title>Node Startup Controller overview</title>
+    <xi:include href="about.xml"/>
+    <xi:include href="functional-scope.xml"/>
+    <xi:include href="public-interfaces.xml"/>
+    <xi:include href="software-architecture.xml"/>
+  </part>
 
-  <chapter>
-    <title>Building, Installing and Testing the Node Startup Controller</title>
-    <section>
-      <title>Building</title>
-    </section>
-    <section>
-      <title>Installing</title>
-    </section>
-    <section>
-      <title>Testing</title>
-      <para><xref linkend="test-general-setup" /></para>
-      <para><xref linkend="test-luc" /></para>
-      <para><xref linkend="test-legacy-app" /></para>
-      <para><xref linkend="test-tsm" /></para>
-      <xi:include href="test-general-setup.xml"/>
-      <xi:include href="test-luc.xml"/>
-      <xi:include href="test-legacy-app.xml"/>
-      <xi:include href="test-tsm.xml"/>
-    </section>
-  </chapter>
+  <part id="building">
+    <title>Building</title>
+  </part>
 
-  <chapter>
+  <part id="testing">
+    <title>Testing</title>
+    <xi:include href="test-nsm-dummy.xml"/>
+    <xi:include href="test-test-environment-setup.xml"/>
+    <xi:include href="test-luc-management.xml"/>
+    <xi:include href="test-legacy-app-handling.xml"/>
+    <xi:include href="test-target-startup-monitoring.xml"/>
+  </part>
+
+  <part id="public-api">
     <title>Public API</title>
     <xi:include href="../../../node-startup-controller/doc-org.genivi.NodeStartupController1.NodeStartupController.xml"/>
     <xi:include href="legacy-app-handler.xml"/>
-  </chapter>
+  </part>
 
-  <chapter id="node-startup-controller-classes">
-    <title>Main Classes of the Node Startup Controller</title>
+  <part id="main-classes">
+    <title>Main classes of the Node Startup Controller</title>
     <xi:include href="xml/node-startup-controller-application.xml"/>
     <xi:include href="xml/job-manager.xml"/>
     <xi:include href="xml/la-handler-service.xml"/>
     <xi:include href="xml/luc-starter.xml"/>
     <xi:include href="xml/node-startup-controller-service.xml"/>
     <xi:include href="xml/target-startup-monitor.xml"/>
-  </chapter>
+  </part>
 
-  <chapter id="common">
-    <title>Generated D-Bus Classes</title>
+  <part id="generated-classes">
+    <title>Generated D-Bus classes</title>
     <xi:include href="xml/node-startup-controller-dbus.xml"/>
     <xi:include href="xml/la-handler-dbus.xml"/>
     <xi:include href="xml/nsm-consumer-dbus.xml"/>
@@ -119,18 +91,18 @@
     <xi:include href="xml/shutdown-consumer-dbus.xml"/>
     <xi:include href="xml/systemd-manager-dbus.xml"/>
     <xi:include href="xml/systemd-unit-dbus.xml"/>
-  </chapter>
+  </part>
 
-  <chapter id="utilities">
+  <part id="utilities">
     <title>Utilities</title>
     <xi:include href="xml/shutdown-client.xml"/>
     <xi:include href="xml/watchdog-client.xml"/>
     <xi:include href="xml/glib-extensions.xml"/>
     <xi:include href="xml/nsm-enum-types.xml"/>
-  </chapter>
+  </part>
 
   <index id="api-index-full">
-    <title>API Index</title>
+    <title>API index</title>
     <xi:include href="xml/api-index-full.xml">
       <xi:fallback />
     </xi:include>
diff --git a/docs/reference/node-startup-controller/public-interfaces.xml b/docs/reference/node-startup-controller/public-interfaces.xml
new file mode 100644
index 0000000..2be636a
--- /dev/null
+++ b/docs/reference/node-startup-controller/public-interfaces.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="public-interfaces">
+  <refmeta>
+    <refentrytitle>Public interfaces</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Public interfaces</refname>
+    <refpurpose>An overview of the public interfaces provided by the Node Startup Controller</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="luc-interface">
+    <title>Interface for LUC management</title>
+    <para>
+      TODO
+    </para>
+  </refsect1>
+
+  <refsect1 id="legacy-app-handler-interface">
+    <title>Interface for legacy application handling</title>
+    <para>
+      TODO
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/reference/node-startup-controller/software-architecture.xml b/docs/reference/node-startup-controller/software-architecture.xml
new file mode 100644
index 0000000..92e4b14
--- /dev/null
+++ b/docs/reference/node-startup-controller/software-architecture.xml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="software-architecture">
+  <refmeta>
+    <refentrytitle>Software architecture</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Software architecture</refname>
+    <refpurpose>Structure and components of the Node Startup Controller source code</refpurpose>
+  </refnamediv>
+</refentry>
diff --git a/docs/reference/node-startup-controller/test-general-setup.xml b/docs/reference/node-startup-controller/test-general-setup.xml
deleted file mode 100644
index 6f7bd74..0000000
--- a/docs/reference/node-startup-controller/test-general-setup.xml
+++ /dev/null
@@ -1,62 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<refentry id="test-general-setup">
-  <refmeta>
-    <refentrytitle>General Setup</refentrytitle>
-  </refmeta>
-
-  <refnamediv>
-    <refname>general setup</refname>
-    <refpurpose>
-      Setup information that applies to all tests
-    </refpurpose>
-  </refnamediv>
-
-  <note>
-    These tests are performed against the Node State Manager Dummy. The real
-    Node State Manager behaves differently from the NSM dummy in the following ways:
-    <itemizedlist>
-    <listitem>
-      When the NSM dummy receives a request to set the node state, it alternates
-      between successfully setting the node state, and failing to set the node state.
-    </listitem>
-    <listitem>
-      When the NSM dummy is queried as to whether the LUC is required, it alternates
-      between saying no and yes.
-    </listitem>
-    <listitem>
-      On receiving a SIGHUP, the NSM dummy will shut down all its fast shutdown
-      clients, then all its normal shutdown clients.
-    </listitem>
-    </itemizedlist>
-  </note>
-
-  <refsection>
-    <title>Setting up DLT</title>
-    <para>
-    All tests use Diagnostic Log and Trace (DLT). It can be started and directed to a log
-    file by executing the following:
-    <programlisting>
-      dlt-daemon -d
-      dlt-receive -o /tmp/dlt.log localhost &amp;
-    </programlisting>
-    </para>
-  </refsection>
-
-  <refsection>
-    <title>Reading DLT log</title>
-    <para>
-      To read this log file, execute
-      <programlisting>dlt-convert -a /tmp/dlt.log</programlisting> This will display the
-      contents of the log file in the following format:
-      <programlisting>Index Time   Timestamp Count Ecuid <emphasis role="bold">Apid Ctid</emphasis> Type Subtype Mode #Args <emphasis role="bold">Payload</emphasis></programlisting>
-      The fields we are interested in are the Apid (Application ID), Ctid (Context ID) and the Payload
-      For example:
-      <programlisting>12 2012/08/01 10:30:32.247913   17066086 006 ECU1 <emphasis role="bold">NSC- CTRL</emphasis> log info V 1 <emphasis role="bold">[Active state of unit "node-startup-controller.service" changed to active]</emphasis></programlisting>
-    </para>
-  </refsection>
-
-</refentry>
-
diff --git a/docs/reference/node-startup-controller/test-luc-management.xml b/docs/reference/node-startup-controller/test-luc-management.xml
new file mode 100644
index 0000000..759c9e5
--- /dev/null
+++ b/docs/reference/node-startup-controller/test-luc-management.xml
@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+
+<refentry id="test-luc-management">
+  <refmeta>
+    <refentrytitle>Tests for LUC management</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Tests for LUC management</refname>
+    <refpurpose>
+      How to verify that the NSC correctly sets the LUC and brings up apps in the LUC
+      correctly during start-up.
+    </refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Test environment and setup</title>
+    <refsect2>
+      <title>GDBus</title>
+      <para>
+        This test assumes that the <command>gdbus</command> command line tool is installed
+        on the system. Without this application, the LUC tests described here can not be
+        performed.
+      </para>
+    </refsect2>
+    <refsect2>
+      <title>Helpful functions</title>
+      <para>
+        gdbus functions will be used frequently. To avoid excessive typing, the following
+        functions should be defined and called:
+        <programlisting>
+# function to begin registration
+begin()
+{
+  gdbus call --system \
+    -d org.genivi.NodeStartupController1 \
+    -o /org/genivi/NodeStartupController1/NodeStartupController \
+    -m org.genivi.NodeStartupController1.NodeStartupController.BeginLUCRegistration \
+}
+
+# function to make a registration call
+register()
+{
+  gdbus call --system \
+    -d org.genivi.NodeStartupController1 \
+    -o /org/genivi/NodeStartupController1/NodeStartupController \
+    -m org.genivi.NodeStartupController1.NodeStartupController.RegisterWithLUC \
+    "$1"
+}
+
+# function to finish registration
+end()
+{
+  gdbus call --system \
+    -d org.genivi.NodeStartupController1 \
+    -o /org/genivi/NodeStartupController1/NodeStartupController \
+    -m org.genivi.NodeStartupController1.NodeStartupController.FinishLUCRegistration \
+}
+        </programlisting>
+      </para>
+    </refsect2>
+    <refsect2>
+      <title>Starting the necessary services</title>
+      <para>
+        The NSM dummy and the Node Startup Controller services need to be started
+        prior to running any of the tests described here. This is done using the
+        following commands:
+      </para>
+      <programlisting>systemctl start nsm-dummy.service
+systemctl start node-startup-controller.service</programlisting>
+      <note>
+        <para>
+          Check the DLT log after starting these services. If the following messages
+          was logged to the DLT you need to restart
+          <literal>node-startup-controller.service</literal>:
+        </para>
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[LUC is not required]</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+        <para>
+          To restart <literal>node-startup-controller.service</literal> simply run:
+        </para>
+        <programlisting>systemd node-startup-controller.service</programlisting>
+      </note>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
+    <title>Test Cases</title>
+    <para>
+      The following test cases for LUC management are described in this document:
+      <itemizedlist>
+        <listitem><para><xref linkend="test-luc-register-simple" endterm="test-luc-register-simple-title" /></para></listitem>
+        <listitem><para><xref linkend="test-luc-register-only" endterm="test-luc-register-only-title" /></para></listitem>
+        <listitem><para><xref linkend="test-luc-finish-only" endterm="test-luc-finish-only-title" /></para></listitem>
+        <listitem><para><xref linkend="test-luc-register-complex" endterm="test-luc-register-complex-title" /></para></listitem>
+        <listitem><para><xref linkend="test-luc-register-series" endterm="test-luc-register-series-title" /></para></listitem>
+        <listitem><para><xref linkend="tests-luc-register-series-reorder" endterm="tests-luc-register-series-reorder-title" /></para></listitem>
+      </itemizedlist>
+    </para>
+    <note>
+      All of these tests need to be executed in the order they are listed here.
+    </note>
+  </refsect1>
+
+  <refsect1 id="test-luc-register-simple">
+    <title id="test-luc-register-simple-title">Registration of a simple dictionary</title>
+    <refsect2>
+      <title>Description</title>
+      <para>
+        Registers one application for a single LUC type, restarts the
+        Node Startup Controller and verifies that it attempts to start this app
+        as part of the LUC.
+      </para>
+    </refsect2>
+    <refsect2>
+      <title>Test commands</title>
+      <programlisting>begin
+register "{0: ['app1.unit']}"
+end
+
+systemctl restart node-startup-controller.service</programlisting>
+    </refsect2>
+    <refsect2>
+      <title>Desired behaviour and output</title>
+      <para>
+        The DLT log should now contain the following log messages:
+      </para>
+      <informaltable><tgroup cols="3">
+        <thead>
+          <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+        </thead>
+        <tbody>
+          <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[Updated LUC to: "{0: ['app1.unit']}"]</entry></row>
+          <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[Starting LUC group: 0]</entry></row>
+          <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[Starting LUC app: app1.unit]</entry></row>
+          <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[Finished starting LUC app: app1.unit]</entry></row>
+          <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[Finished starting LUC group: 0]</entry></row>
+        </tbody>
+      </tgroup></informaltable>
+    </refsect2>
+  </refsect1>
+  <refsect1 id="test-luc-register-only">
+    <title id="test-luc-register-only-title">Registration does not happen on an isolated RegisterWithLUC() call</title>
+    <orderedlist continuation="continues">
+      <listitem><programlisting>register "{1: ['app2.unit']}"</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify this entry <emphasis>doesn't</emphasis> appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app2.unit']}"]</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+    </orderedlist>
+  </refsect1>
+  <refsect1 id="tests-luc-finish-only">
+    <title id="test-luc-finish-only-title">An isolated FinishLUCRegistration() call will not change the LUC</title>
+    <orderedlist continuation="continues">
+      <listitem><programlisting>end</programlisting></listitem>
+      <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+    </orderedlist>
+  </refsect1>
+  <refsect1 id="test-luc-register-complex">
+    <title id="test-luc-register-complex-title">Registration of a complex dictionary</title>
+    <orderedlist continuation="continues">
+      <listitem><programlisting>begin</programlisting></listitem>
+      <listitem><programlisting>register "{0: ['app1.unit'], 1: ['app1.unit', 'app3.unit'], 2: ['app2.unit']}"</programlisting></listitem>
+      <listitem><programlisting>end</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit'], 1: ['app1.unit', 'app3.unit'], 2: ['app2.unit']}"]</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+      <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app3.unit']</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 2]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app2.unit']</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+    </orderedlist>
+  </refsect1>
+  <refsect1 id="test-luc-register-series">
+    <title id="test-luc-register-series-title">Registration can happen with a series of RegisterWithLUC() calls</title>
+    <orderedlist continuation="continues">
+      <listitem><programlisting>begin</programlisting></listitem>
+      <listitem><programlisting>register "{0: ['app1.unit']}"</programlisting></listitem>
+      <listitem><programlisting>register "{1: ['app3.unit']}"</programlisting></listitem>
+      <listitem><programlisting>end</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit']}"]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit'], 1: ['app3.unit']}"]</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+      <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app3.unit']</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+    </orderedlist>
+  </refsect1>
+  <refsect1 id="tests-luc-register-series-reorder">
+    <title id="tests-luc-register-series-reorder-title">Repeated registration of an app changes the order in the LUC</title>
+    <orderedlist continuation="continues">
+      <listitem><programlisting>begin</programlisting></listitem>
+      <listitem><programlisting>register "{1: ['app1.unit', 'app2.unit']}"</programlisting></listitem>
+      <listitem><programlisting>register "{1: ['app1.unit']}"</programlisting></listitem>
+      <listitem><programlisting>end</programlisting></listitem>
+      <listitem>
+        Read the DLT logs and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app1.unit', 'app2.unit']}"]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app2.unit', 'app1.unit']}"]</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+      <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
+      <listitem>
+        Read the DLT log and verify these entries appear:
+        <informaltable><tgroup cols="3">
+          <thead>
+            <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
+          </thead>
+          <tbody>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app2.unit']</entry></row>
+            <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
+          </tbody>
+        </tgroup></informaltable>
+      </listitem>
+    </orderedlist>
+  </refsect1>
+</refentry>
diff --git a/docs/reference/node-startup-controller/test-luc.xml b/docs/reference/node-startup-controller/test-luc.xml
deleted file mode 100644
index e78896c..0000000
--- a/docs/reference/node-startup-controller/test-luc.xml
+++ /dev/null
@@ -1,282 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-
-<refentry id="test-luc">
-  <refmeta>
-    <refentrytitle>Last User Context handling</refentrytitle>
-  </refmeta>
-
-  <refnamediv>
-    <refname>luc handling</refname>
-    <refpurpose>
-      Testing that the Node Startup Controller(NSC) correctly sets the Last User Context (LUC),
-    and starts the apps correctly on NSC startup.
-    </refpurpose>
-  </refnamediv>
-
-  <refsection>
-    <title>Test environment and setup</title>
-    <refsection>
-      <title>GDBus</title>
-      <para>
-        This test assumes that the <command>gdbus</command> programme is installed on the
-        system. Without this programme, this test is impossible.
-      </para>
-    </refsection>
-
-    <refsection>
-      <title>Helpful functions</title>
-      <para>
-        gdbus functions will be used frequently. To avoid excessive typing, the following
-        functions should be defined and called:
-        <programlisting>
-          # function to begin registration
-          begin()
-          {
-            gdbus call --system \
-              -d org.genivi.NodeStartupController1 \
-              -o /org/genivi/NodeStartupController1/NodeStartupController \
-              -m org.genivi.NodeStartupController1.NodeStartupController.BeginLUCRegistration \
-          }
-
-          # function to make a registration call
-          register()
-          {
-            gdbus call --system \
-              -d org.genivi.NodeStartupController1 \
-              -o /org/genivi/NodeStartupController1/NodeStartupController \
-              -m org.genivi.NodeStartupController1.NodeStartupController.RegisterWithLUC \
-              "$1"
-          }
-
-          # function to finish registration
-          end()
-          {
-            gdbus call --system \
-              -d org.genivi.NodeStartupController1 \
-              -o /org/genivi/NodeStartupController1/NodeStartupController \
-              -m org.genivi.NodeStartupController1.NodeStartupController.FinishLUCRegistration \
-          }
-        </programlisting>
-      </para>
-    </refsection>
-
-  </refsection>
-
-  <refsection>
-    <title>Test Overview</title>
-    <para>
-      The following behaviours will be confirmed:
-      <itemizedlist>
-        <listitem><para><xref linkend="test-luc-register-simple" endterm="test-luc-register-simple-title" /></para></listitem>
-        <listitem><para><xref linkend="test-luc-register-only" endterm="test-luc-register-only-title" /></para></listitem>
-        <listitem><para><xref linkend="test-luc-finish-only" endterm="test-luc-finish-only-title" /></para></listitem>
-        <listitem><para><xref linkend="test-luc-register-complex" endterm="test-luc-register-complex-title" /></para></listitem>
-        <listitem><para><xref linkend="test-luc-register-series" endterm="test-luc-register-series-title" /></para></listitem>
-        <listitem><para><xref linkend="tests-luc-register-series-reorder" endterm="tests-luc-register-series-reorder-title" /></para></listitem>
-      </itemizedlist>
-    </para>
-  </refsection>
-
-  <refsection>
-    <title>Test cases</title>
-    <refsection>
-      <orderedlist>
-        <listitem><programlisting>systemctl start nsm-dummy.service</programlisting></listitem>
-        <listitem><programlisting>systemctl start node-startup-controller.service</programlisting></listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="test-luc-register-simple">
-      <title id="test-luc-register-simple-title">Registration of a simple dictionary</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>begin</programlisting></listitem>
-        <listitem><programlisting>register "{0: ['app1.unit']}"</programlisting></listitem>
-        <listitem><programlisting>end</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify this entry appears:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit']}"]</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-        <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
-        <note>
-          If the following entry is seen:
-            <informaltable><tgroup cols="3">
-              <thead>
-                <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-              </thead>
-              <tbody>
-                <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[LUC is not required]</entry></row>
-              </tbody>
-            </tgroup></informaltable>
-          perform the following command line again:
-          <programlisting>systemctl restart node-startup-controller.service</programlisting>
-          </note>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="test-luc-register-only">
-      <title id="test-luc-register-only-title">Registration does not happen on an isolated RegisterWithLUC() call</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>register "{1: ['app2.unit']}"</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify this entry <emphasis>doesn't</emphasis> appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app2.unit']}"]</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="tests-luc-finish-only">
-      <title id="test-luc-finish-only-title">An isolated FinishLUCRegistration() call will not change the LUC</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>end</programlisting></listitem>
-        <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="test-luc-register-complex">
-      <title id="test-luc-register-complex-title">Registration of a complex dictionary</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>begin</programlisting></listitem>
-        <listitem><programlisting>register "{0: ['app1.unit'], 1: ['app1.unit', 'app3.unit'], 2: ['app2.unit']}"</programlisting></listitem>
-        <listitem><programlisting>end</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit'], 1: ['app1.unit', 'app3.unit'], 2: ['app2.unit']}"]</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-        <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app3.unit']</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 2]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app2.unit']</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="test-luc-register-series">
-      <title id="test-luc-register-series-title">Registration can happen with a series of RegisterWithLUC() calls</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>begin</programlisting></listitem>
-        <listitem><programlisting>register "{0: ['app1.unit']}"</programlisting></listitem>
-        <listitem><programlisting>register "{1: ['app3.unit']}"</programlisting></listitem>
-        <listitem><programlisting>end</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit']}"]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{0: ['app1.unit'], 1: ['app3.unit']}"]</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-        <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 0]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app3.unit']</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-    <refsection id="tests-luc-register-series-reorder">
-      <title id="tests-luc-register-series-reorder-title">Repeated registration of an app changes the order in the LUC</title>
-      <orderedlist continuation="continues">
-        <listitem><programlisting>begin</programlisting></listitem>
-        <listitem><programlisting>register "{1: ['app1.unit', 'app2.unit']}"</programlisting></listitem>
-        <listitem><programlisting>register "{1: ['app1.unit']}"</programlisting></listitem>
-        <listitem><programlisting>end</programlisting></listitem>
-        <listitem>
-          Read the DLT logs and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app1.unit', 'app2.unit']}"]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[The new context is: "{1: ['app2.unit', 'app1.unit']}"]</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-
-        <listitem><programlisting>systemctl restart node-startup-controller.service</programlisting></listitem>
-        <listitem>
-          Read the DLT log and verify these entries appear:
-          <informaltable><tgroup cols="3">
-            <thead>
-              <row> <entry>APID</entry> <entry>CTID</entry> <entry>Payload</entry> </row>
-            </thead>
-            <tbody>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start group 1]</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app2.unit']</entry></row>
-              <row><entry>NSC-</entry> <entry>CTRL</entry> <entry>[start app 'app1.unit']</entry></row>
-            </tbody>
-          </tgroup></informaltable>
-        </listitem>
-      </orderedlist>
-    </refsection>
-  </refsection>
-</refentry>
diff --git a/docs/reference/node-startup-controller/test-tsm.xml b/docs/reference/node-startup-controller/test-target-startup-monitoring.xml
index cbf3579..48a1f79 100644
--- a/docs/reference/node-startup-controller/test-tsm.xml
+++ b/docs/reference/node-startup-controller/test-target-startup-monitoring.xml
@@ -3,16 +3,17 @@
                           "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
 
-<refentry id="test-tsm">
+<refentry id="test-target-startup-monitoring">
   <refmeta>
-    <refentrytitle>Target Startup Monitor</refentrytitle>
+    <refentrytitle>Tests for target startup monitoring</refentrytitle>
   </refmeta>
 
   <refnamediv>
-    <refname>Target Startup Monitor</refname>
+    <refname>Tests for target startup monitoring</refname>
     <refpurpose>
-      Testing that the target startup monitor correctly identifies targets have started, and
-      sets the Node State Manager's state accordingly.
+      How to verify that the target startup monitoring functionality of the
+      NSC correctly identifies targets have started, and sets the node state
+      accordingly via the NSM.
     </refpurpose>
   </refnamediv>
 
diff --git a/docs/reference/node-startup-controller/test-test-environment-setup.xml b/docs/reference/node-startup-controller/test-test-environment-setup.xml
new file mode 100644
index 0000000..f27266a
--- /dev/null
+++ b/docs/reference/node-startup-controller/test-test-environment-setup.xml
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<refentry id="test-environment-setup">
+  <refmeta>
+    <refentrytitle>Test environment setup</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Test environment setup</refname>
+    <refpurpose>Information on how to prepare the runtime environment for testing</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Setting up the Diagnostic Log and Trace (DLT) framework</title>
+    <para>
+      In order to support manual testing, the Node Startup Controller logs any useful
+      information using the Diagnostic Log and Trace (DLT) framework. The DLT runtime
+      components relevant for testing are the <literal>dlt-daemon</literal> and the
+      <literal>dlt-receive</literal> tools.
+    </para>
+    <para>
+      The <literal>dlt-daemon</literal> logging daemon is started follows:
+    </para>
+    <programlisting>dlt-daemon -d</programlisting>
+    <para>
+      Afterwards, the <literal>dlt-receive</literal> can be used to forward all
+      messages logged via the DLT to a specific file. The following command attaches
+      the <literal>dlt-receive</literal> tool to the <literal>dlt-daemon</literal>
+      running on the same machine and writes all output to
+      <literal>/tmp/dlt.log</literal>:
+    </para>
+    <programlisting>dlt-receive -o /tmp/dlt.log localhost &amp;</programlisting>
+  </refsect1>
+
+  <refsect1>
+    <title>Reading DLT log</title>
+    <para>
+      In order to check whether the Node Startup Controller behaves correctly, the
+      messages it logs to the DLT have to be investigated. The log file is not plain
+      text, so a special tool called <literal>dlt-convert</literal> needs to be used
+      to convert it into human-readable form.
+    </para>
+    <para>
+      The <literal>dlt-convert</literal> tool can be executed using the following
+      command:
+    </para>
+    <programlisting>dlt-convert -a /tmp/dlt.log</programlisting>
+    <para>
+      This will display the contents of the log file in the following format:
+    </para>
+    <programlisting>Index Time   Timestamp Count Ecuid <emphasis role="bold">Apid Ctid</emphasis> Type Subtype Mode #Args <emphasis role="bold">Payload</emphasis></programlisting>
+    <para>
+      Here is one example:
+    </para>
+    <programlisting>12 2012/08/01 10:30:32.247913   17066086 006 ECU1 <emphasis role="bold">NSC- CTRL</emphasis> log info V 1 <emphasis role="bold">[Active state of unit "node-startup-controller.service" changed to active]</emphasis></programlisting>
+    <para>
+      The fields we are interested for debugging and testing in are the Apid
+      (Application ID), Ctid (Context ID) and the Payload. The test cases described
+      in the following chapters include the exact log values for these fields needed
+      to verify the correctness of behaviour of the Node Startup Controller.
+    </para>
+  </refsect1>
+</refentry>
+