1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<?xml version="1.0" encoding="utf-8"?>
<!--
SPDX license identifier: CC-BY-SA-4.0
Copyright (C) 2015, GENIVI
This work is licensed under a Creative Commons Attribution-ShareAlike
4.0 International License.
-->
<!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="introduction">
<title>Introduction</title>
<para>
The Node Startup Controller (NSC) was introduced into the lifecycle package for
GENIVI in order to handle some startup and shutdown functionality. It essentially
"extends" systemd to implement some IVI requirements that are not done by systemd
itself because they are not generally applicable for all Linux systems (as
determined through discussion with the systemd community). However, similar
functionality might be desired in non-automotive systems so we hope this can be
useful and/or develop into something shared across domains.
</para>
<para>
The main areas of responsibility for the NSC are:
</para>
<itemizedlist>
<listitem>
<para>
Last User Context (LUC) Management
</para>
</listitem>
<listitem>
<para>
Legacy Application Management
</para>
</listitem>
<listitem>
<para>
Target Startup Monitoring
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="luc-management">
<title>Last User Context (LUC) management</title>
<para>
The Last User Context (LUC) management holds information about what applications
the user was using in the last lifecycle, in order to allow the same applications
to be restored automatically, or prioritized over other applications the next
time the system boots up. Applications are stored in the LUC groups whose start
order is defined at build time. The choice is fully flexible, but for a typical
Automotive IVI system, these groups could be:
</para>
<variablelist>
<varlistentry>
<term>Audible</term>
<listitem>
<para>
Applications that are current audible sources within the Head Unit (e.g.
radio or CD player).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Foreground</term>
<listitem>
<para>
Applications that are currently in the focus of the HMI (e.g., navigation
or web browser).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Background</term>
<listitem>
<para>
Applications that run in the background.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The LUC allows multiple applications to be registered for each LUC type at the
same time. A registration with the LUC consists of two parameters:
</para>
<orderedlist>
<listitem>
A systemd unit filename (e.g. <literal>navigation.service</literal>),</listitem>
<listitem>
The LUC type, which is a number that represents the group, e.g. 0 for audible,
1 for foreground, 2 for background.
</listitem>
</orderedlist>
<para>
The LUC management simply stores the systemd unit name (e.g.
navigation.service) for each LUC-managed application and communicates with
systemd to start up these applications shortly after boot. Systemd D-Bus
interfaces are used instead of simply a stored systemd target file on disk.
This is to allow the behavior to be flexible according to system policy and
because the behavior might also be dynamic as described in the next section.
</para>
<para>
Units in a start-up group are all started in parallel. The order in which each
group is started can be configured at build-time.
</para>
<para>
In order to reduce the amount of communication with the LUC management, multiple
applications can be registered and deregistered with a single D-Bus call.
</para>
</refsect1>
<refsect1 id="legacy-application-management">
<title>Legacy application management</title>
<para>
In this context "Legacy applications" means applications that do provide a
systemd unit file but are otherwise unaware of, or do not make use of other
GENIVI/Lifecycle components. This means that the applications will not actively
register themselves as a shutdown consumer in the Node State Manager (NSM).
(That is the normal way for the NSM to know what applications are active and can
be controlled in order to sleep/shutdown.) To solve the "legacy applications"
problem, the NSC provides a mechanism to separately register such applications
as shutdown consumers.
</para>
<para>
To solve this problem the Node Startup Controller provides a mechanism to register
shutdown consumers for individual legacy applications. This works as follows:
</para>
<orderedlist>
<listitem>
the Node Startup Controller provides an internal D-Bus interface for registering
a shutdown consumer for a given unit filename,
</listitem>
<listitem>
the Node Startup Controller provides a helper executable that takes a unit
filename and calls the above D-Bus method to register a shutdown consumer for
this unit file, an <literal>ExecStartPost</literal> command is added the unit
files of legacy applications that calls the helper script or binary.
</listitem>
</orderedlist>
<para>
Whenever the NSM decides to perform a shutdown it will ask the shutdown consumers
to shut down in reverse order of their creation. To the NSM it does not matter
whether or not the consumers are registered by applications themselves or by the
Node Startup Controller.
</para>
<para>
There is some other behavior also during shut-down which should be mentioned
here fore completeness, although it is controlled by the Node State Manager (NSM)
as opposed to NSC. Specifically it is the requirement to implement "cancelled
shutdown" which is not typically present in non-IVI Linux systems.
</para>
</refsect1>
<refsect1 id="target-startup-monitoring">
<title>Target startup monitoring</title>
<para>
The Node Startup Controller is responsible to set certain NSM states when certain
systemd targets (e.g. <literal>focussed.target</literal> or
<literal>lazy.target</literal>) have been started within or outside the
Node Startup Controller. For this, it needs to monitor systemd for unit start-up
events.
</para>
<para>
As of systemd 183, this is possible through systemd's JobRemoved signal.
</para>
<para>
The Node Startup Controller
</para>
<orderedlist>
<listitem>
sets the NSM state to <literal>BASE_RUNNING</literal> during initialization,
</listitem>
<listitem>
subscribes to systemd in order to receive signals from systemd,
</listitem>
<listitem>
evaluates the received JobRemoved signals by filtering out the signals that do
not belong to target start-up events setting the NSM state to
<orderedlist>
<listitem>
<literal>LUC_RUNNING</literal> when <literal>focussed.target</literal>
has been started,
</listitem>
<listitem>
<literal>FULLY_RUNNING</literal> when <literal>unfocussed.target</literal>
has been started,
</listitem>
<listitem>
<literal>FULLY_OPERATIONAL</literal> when <literal>lazy.target</literal>
has been started.
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</refsect1>
</refentry>
|
