<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57" xml:lang="en"><title>Guidelines
to adapt the existing GSA components to SSMA</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The existing components of GSA are EStart, AMA Starter, and System Monitor.
The following sections explain how each of these components adapt to the SSMA. </p>
<section><title>EStart</title> <p>This component is launched by the File Server.
It is responsible for completing the initialization of the File Server and
co-ordinating the launch of some base-related components (example the Domain
Manager). Then, it initiates the start up of the remaining system (example
starting the window server). </p> <p>SSM is a new process in the chain of
processes, which is responsible for starting all the major Symbian platform
services. After the migration from GSA to SSMA EStart creates SSM component
(<filepath>SysStateMgr</filepath>) instead of SysStart. </p> </section>
<section><title>System Monitor</title> <p>The System Monitor (SysMon) checks
applications and processes using SSM startup properties. An application or
process can add itself to the System Monitor's list. </p> <p><b>Adaptations
to the System Monitor</b> </p> <p>The System Health Management (SHM) manages
the system health, including the monitoring of critical processes and their
re-launch if they fail. System Monitor introduces a method for controlling
re-launch and a new value for the retry_failure_recovery_method. The following
sections explain how to monitor critical processes. </p> <p><b>Current re-launch
policy </b> </p> <p>A component is re-launched after a monitored component
has failed to re-launch the component 'n' times (where n = 1 or 2). If all
the re-launch attempts fail, then SysMon either ignores the failure of the
component, or the device is restarted (a critical component). </p> <note>An
unsuccessful re-launch attempt consists of a component’s failure to meet with
SysMon, within a finite period of time. If a monitored component is successfully
(re-)launched, and then subsequently fails, the next re-launch attempt occurs
only after atleast <codeph>KWaitTime</codeph> seconds has elapsed (since the
last re-launch attempt). This mechanism is referred to as ‘Re-launch throttling’.</note> <p><b>Critical
component functionality in SysMon</b> </p> <p>A new value for the retry_failure_recovery_method
(that is <codeph>ECriticalNoRetries</codeph>) is introduced, which instructs
SysMon to restart the Symbian platform when failure of a monitored component
is detected. In this situation, any value set for 'no_of_retries_on_failure'
is ignored by SysMon. </p> <p>The PlatSec capabilities required by a SysMon
client to set this value is the same as for <codeph>retry_failure_recovery_method
=                 ERestartOS</codeph>. If this new value (<codeph>ECriticalNoRetries</codeph>)
is set as the <codeph>retry_failure_recovery_method</codeph> in a Static Command
List (that is for launching a process/application), SysCLE treats this as <codeph>retry_failure_recovery_method
= ERestartOS</codeph>, and performs (if needed) the number of retries indicated
in no_of_retries_on_failure. </p> </section>
<section id="GUID-E2D75D7D-98A5-5419-8B0E-0A995D3EFEC9"><title>System Command
List Executer</title> <p>SCLs contain a list of commands that are run by the
SSM. The SysCLE runs these commands as per the policy. The policy for deciding
which commandLists are run by the SysCLE is included within the system state
Manager component (<filepath>SysStateMgr.exe</filepath>). When there is a
system state/property transition, SysState goes through a series of policy
steps to find which commandList must be run by SysCLE. SysCLE responds with
a result code which is passed back to the state policy plug-in. The next action
returned by the state policy plug-in depends on this result code. </p> <p>SCLs
contains a list of commands that are run by the SSM and SysCLe runs the commands
as per the policy. </p> <p>SysCLE is based on SysStart, but it is converted
into a DLL. After GSA is migrated to SSMA, the current Static Startup Configuration
(SSC) commands are maintained. The following table lists the new commands
and functions that are introduced into SysCLE. </p> <table id="GUID-80C526A2-BD7A-5E0D-A1FE-C0C5181F88ED">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>

<entry><p><b>New commands</b></p></entry>
<entry><p><b>Description</b></p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Change Domain Manager State </p> </entry>
<entry><p>It changes the state in the Domain Manager. This ‘Change State’
command is used only when a valid Domain Hierarchy is loaded (although this
is not checked programmatically). This command allows SysCLE to run some commands
before the state is changed. </p> </entry>
</row>
<row>
<entry><p>Change system-wide property </p> </entry>
<entry><p>Changes the value of a system-wide property (P&amp;S property). </p> </entry>
</row>
<row>
<entry><p>Call asynchronous Custom Commands </p> </entry>
<entry><p>It is a new method of calling asynchronous functionality in DLLs
and is required in the SCLs (allowing asynchronous ‘Custom Commands’). To
ease the creation of custom commands, the API allows setup and teardown methods
to manage the common handles for many custom commands. It is also necessary
to provide each custom command with an environment. This environment provides
common handles, such as RFs, to the custom command and information from <filepath>SysStateMgr</filepath>,
such as start-up mode and reason. This prevents the need for the custom commands
to connect back to SysState to query state about the system. </p> <p> <b>Note:</b> Custom
commands allow licensees and partners to provide commands that can be run
by the SysCLE with those provided by Symbian. </p> </entry>
</row>
<row>
<entry><p>Use the switch off and restart functionally provided by the kernel
power API </p> </entry>
<entry><p>It provides the ability to restart or shutdown the device. </p> <p> <b>Note:</b> It
is expected that these commands are used as the last commands in the commandList
for the shutdown state. </p> </entry>
</row>
<row>
<entry><p>Sending save events to all clients registered to receive them through <codeph>CSaveNotifier </codeph>  </p> </entry>
<entry><p>It notifies all clients that have requested notification through
the existing <codeph>CSaveNotifier</codeph> interface of a save notification
event. </p> </entry>
</row>
<row>
<entry><p>Finalise the drives on the system using <codeph>RFs::FinaliseDrives() </codeph>  </p> </entry>
<entry><p>It calls the <codeph>RFs::FinaliseDrives()</codeph> API to finalise
the drives on the device. </p> <p> <b>Note:</b> This is intended for use in
the shutdown commandList. </p> </entry>
</row>
<row>
<entry><p>Request for BAFL to persist the HAL attributes </p> </entry>
<entry><p>It calls the <codeph>BAFL::PersistHAL()</codeph> API to persist
the persistent HAL values to disk. </p> <p> <b>Note:</b> This is intended
for use in the shutdown commandList. </p> </entry>
</row>
<row>
<entry><p>Request a state transition to occur </p> </entry>
<entry><p>It calls the request system state transition that is provided by
SSM. This request is treated like any other requested system state transition
with the policy plug-in being able to accept, fail, or queue the transition.
This command handles the automatic transition from the final commandList of
the start-up state to the normal state. </p> </entry>
</row>
<row>
<entry><p>Command severity information </p> </entry>
<entry><p>When a command fails SSMA performs the following actions: Ignore,
Low, Medium, High, and Severity. For more information on command severity,
see <xref href="GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57.dita#GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57/GUID-AA207E56-2F87-54E5-B19D-5246C5526827">Command
severity information</xref>. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p id="GUID-AA207E56-2F87-54E5-B19D-5246C5526827"><b>Command severity
information</b> </p> <p>Each command supports a Severity level, to determine
the response during a command failure. In SysStart two actions take place
when a command fails that is panic and ignore. </p> <ul>
<li id="GUID-2D276EEA-C5F2-5F0A-AF42-50B869963D6D"><p> <codeph>EPanicOnCommandFailure</codeph> -
Panic the system starter if command fails. This causes the device to restart. </p> </li>
<li id="GUID-3FD86DCE-FC7A-53A0-801E-8CDF9A6D8597"><p> <codeph>EIgnoreCommandFailure</codeph> -
Ignore the command failure </p> </li>
</ul> <p>In a similar way, in SSMA, the following actions takes place when
a command fails: Ignore, Low, Medium, High, and Severity. </p> <p>The following
example code shows an identifier for the level of severity to be associated
with a command failure: </p> <codeblock id="GUID-9990B545-1B5C-5E93-A7A0-D37D7F7EF6FE" xml:space="preserve">/** @publishedPartner
@prototype */
enum TCmdErrorSeverity
    {
    /** Ignore the command failure.    */
    ECmdIgnoreFailure = 0,
    ECmdLowSeverity = 25,
    ECmdMediumSeverity = 50,
    ECmdHighSeverity = 75,
 ECmdCriticalSeverity = 100
    };</codeblock> <p>The following list shows how the new command severity
is mapped to the existing ones: </p> <ul>
<li id="GUID-F863355B-0A8B-5FED-A840-D3D60CB2703A"><p> <codeph>EIgnoreCommandFailure
-&gt; ECmdIgnoreFailure</codeph>  </p> </li>
<li id="GUID-18F6DB1E-A126-5F3F-9421-5BA5EB5C179B"><p> <codeph>EPanicOnCommandFailure
-&gt; ECmdCriticalSeverity</codeph>  </p> </li>
</ul> <p><b>Adaptations to convert SysStart into SysCLE</b> </p> <p>The general
adaptations made to convert SysStart into SysCLE are: </p> <ul>
<li id="GUID-7AE47B3F-B8C9-531E-A0D1-F95F23E4B39E"><p>The process starting
code is removed. </p> </li>
<li id="GUID-9412EC1A-896B-5A4A-92C2-B251D3525F6F"><p>The existing implementation
to read the Start-up mode and convert this into an SSC filename is removed
(and re-used by policy plug-in). </p> </li>
<li id="GUID-9BE3D557-F031-52D6-B599-4564B804FA84"><p>The resource file reader
code is removed (and re-used by policy plug-ins). </p> </li>
<li id="GUID-32E427E3-59FF-5C54-8FB4-1F90D6A4A436"><p>The SysCLE client (internal)
API is implemented to: </p> <ul>
<li id="GUID-D719DD35-9F5E-50F3-95ED-06C9E31AB145"><p>Handle the commandList
object being received, and run the commandList. </p> </li>
<li id="GUID-81B84D78-9ED8-5B88-9AAA-B07AB4B3C9DA"><p>Handle a request, to
immediately stop a commandList that is running. </p> </li>
</ul> </li>
<li id="GUID-92282F21-D127-5BDA-9848-A86873D506E6"><p>The existing implementation
to Add (load) the Startup Domain Hierarchy is removed. </p> </li>
<li id="GUID-0577911A-F289-5B28-A796-CA4FF000C6EF"><p>The SysCLE implementation
expects system state change to occur at any time in a commandList. </p> </li>
<li id="GUID-1EE3E9B5-5430-5548-BDD5-4C789BF77D95"><p>The handling of the
retry_failure_recovery_method must be adapted. The SysStart decides on the
recovery policy when a commandList fails to run. When a critical retry failure
occurs (that is <codeph>ERestartOS</codeph>) this is returned to SysStart
(with any indicated Start-up mode). If a non-critical retry failure occurs
(that is <codeph>EIgnoreFailure</codeph>), this is also returned to SysStart. </p> </li>
<li id="GUID-A4DC8B53-095B-599D-A582-60EBF7B46222"><p>The ability for SysState
to query if any non-critical commands failed to run successfully in the commandList.
This API also provides further information about the failed command and not
just returns a Boolean value describing if a command failed or not. Allowing
SysState to store or act on this information provides information as to what
state the system is when debugging. </p> </li>
</ul> </section>
</conbody></concept>