# 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
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST += \
- legacy-app-handler.xml \
version.xml.in
# Files not to distribute
--- /dev/null
+<?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>
--- /dev/null
+<?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>
</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"/>
<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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
+++ /dev/null
-<?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 &
- </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>
-
--- /dev/null
+<?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>
+++ /dev/null
-<?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>
"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>
--- /dev/null
+<?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 &</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>
+
projects / profile / ivi / node-startup-controller.git / commitdiff