|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57" xml:lang="en"><title>Guidelines |
|
13 to adapt the existing GSA components to SSMA</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The existing components of GSA are EStart, AMA Starter, and System Monitor. |
|
15 The following sections explain how each of these components adapt to the SSMA. </p> |
|
16 <section><title>EStart</title> <p>This component is launched by the File Server. |
|
17 It is responsible for completing the initialization of the File Server and |
|
18 co-ordinating the launch of some base-related components (example the Domain |
|
19 Manager). Then, it initiates the start up of the remaining system (example |
|
20 starting the window server). </p> <p>SSM is a new process in the chain of |
|
21 processes, which is responsible for starting all the major Symbian platform |
|
22 services. After the migration from GSA to SSMA EStart creates SSM component |
|
23 (<filepath>SysStateMgr</filepath>) instead of SysStart. </p> </section> |
|
24 <section><title>System Monitor</title> <p>The System Monitor (SysMon) checks |
|
25 applications and processes using SSM startup properties. An application or |
|
26 process can add itself to the System Monitor's list. </p> <p><b>Adaptations |
|
27 to the System Monitor</b> </p> <p>The System Health Management (SHM) manages |
|
28 the system health, including the monitoring of critical processes and their |
|
29 re-launch if they fail. System Monitor introduces a method for controlling |
|
30 re-launch and a new value for the retry_failure_recovery_method. The following |
|
31 sections explain how to monitor critical processes. </p> <p><b>Current re-launch |
|
32 policy </b> </p> <p>A component is re-launched after a monitored component |
|
33 has failed to re-launch the component 'n' times (where n = 1 or 2). If all |
|
34 the re-launch attempts fail, then SysMon either ignores the failure of the |
|
35 component, or the device is restarted (a critical component). </p> <note>An |
|
36 unsuccessful re-launch attempt consists of a component’s failure to meet with |
|
37 SysMon, within a finite period of time. If a monitored component is successfully |
|
38 (re-)launched, and then subsequently fails, the next re-launch attempt occurs |
|
39 only after atleast <codeph>KWaitTime</codeph> seconds has elapsed (since the |
|
40 last re-launch attempt). This mechanism is referred to as ‘Re-launch throttling’.</note> <p><b>Critical |
|
41 component functionality in SysMon</b> </p> <p>A new value for the retry_failure_recovery_method |
|
42 (that is <codeph>ECriticalNoRetries</codeph>) is introduced, which instructs |
|
43 SysMon to restart the Symbian platform when failure of a monitored component |
|
44 is detected. In this situation, any value set for 'no_of_retries_on_failure' |
|
45 is ignored by SysMon. </p> <p>The PlatSec capabilities required by a SysMon |
|
46 client to set this value is the same as for <codeph>retry_failure_recovery_method |
|
47 = ERestartOS</codeph>. If this new value (<codeph>ECriticalNoRetries</codeph>) |
|
48 is set as the <codeph>retry_failure_recovery_method</codeph> in a Static Command |
|
49 List (that is for launching a process/application), SysCLE treats this as <codeph>retry_failure_recovery_method |
|
50 = ERestartOS</codeph>, and performs (if needed) the number of retries indicated |
|
51 in no_of_retries_on_failure. </p> </section> |
|
52 <section id="GUID-E2D75D7D-98A5-5419-8B0E-0A995D3EFEC9"><title>System Command |
|
53 List Executer</title> <p>SCLs contain a list of commands that are run by the |
|
54 SSM. The SysCLE runs these commands as per the policy. The policy for deciding |
|
55 which commandLists are run by the SysCLE is included within the system state |
|
56 Manager component (<filepath>SysStateMgr.exe</filepath>). When there is a |
|
57 system state/property transition, SysState goes through a series of policy |
|
58 steps to find which commandList must be run by SysCLE. SysCLE responds with |
|
59 a result code which is passed back to the state policy plug-in. The next action |
|
60 returned by the state policy plug-in depends on this result code. </p> <p>SCLs |
|
61 contains a list of commands that are run by the SSM and SysCLe runs the commands |
|
62 as per the policy. </p> <p>SysCLE is based on SysStart, but it is converted |
|
63 into a DLL. After GSA is migrated to SSMA, the current Static Startup Configuration |
|
64 (SSC) commands are maintained. The following table lists the new commands |
|
65 and functions that are introduced into SysCLE. </p> <table id="GUID-80C526A2-BD7A-5E0D-A1FE-C0C5181F88ED"> |
|
66 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
67 <thead> |
|
68 <row> |
|
69 |
|
70 <entry><p><b>New commands</b></p></entry> |
|
71 <entry><p><b>Description</b></p></entry> |
|
72 </row> |
|
73 </thead> |
|
74 <tbody> |
|
75 <row> |
|
76 <entry><p>Change Domain Manager State </p> </entry> |
|
77 <entry><p>It changes the state in the Domain Manager. This ‘Change State’ |
|
78 command is used only when a valid Domain Hierarchy is loaded (although this |
|
79 is not checked programmatically). This command allows SysCLE to run some commands |
|
80 before the state is changed. </p> </entry> |
|
81 </row> |
|
82 <row> |
|
83 <entry><p>Change system-wide property </p> </entry> |
|
84 <entry><p>Changes the value of a system-wide property (P&S property). </p> </entry> |
|
85 </row> |
|
86 <row> |
|
87 <entry><p>Call asynchronous Custom Commands </p> </entry> |
|
88 <entry><p>It is a new method of calling asynchronous functionality in DLLs |
|
89 and is required in the SCLs (allowing asynchronous ‘Custom Commands’). To |
|
90 ease the creation of custom commands, the API allows setup and teardown methods |
|
91 to manage the common handles for many custom commands. It is also necessary |
|
92 to provide each custom command with an environment. This environment provides |
|
93 common handles, such as RFs, to the custom command and information from <filepath>SysStateMgr</filepath>, |
|
94 such as start-up mode and reason. This prevents the need for the custom commands |
|
95 to connect back to SysState to query state about the system. </p> <p> <b>Note:</b> Custom |
|
96 commands allow licensees and partners to provide commands that can be run |
|
97 by the SysCLE with those provided by Symbian. </p> </entry> |
|
98 </row> |
|
99 <row> |
|
100 <entry><p>Use the switch off and restart functionally provided by the kernel |
|
101 power API </p> </entry> |
|
102 <entry><p>It provides the ability to restart or shutdown the device. </p> <p> <b>Note:</b> It |
|
103 is expected that these commands are used as the last commands in the commandList |
|
104 for the shutdown state. </p> </entry> |
|
105 </row> |
|
106 <row> |
|
107 <entry><p>Sending save events to all clients registered to receive them through <codeph>CSaveNotifier </codeph> </p> </entry> |
|
108 <entry><p>It notifies all clients that have requested notification through |
|
109 the existing <codeph>CSaveNotifier</codeph> interface of a save notification |
|
110 event. </p> </entry> |
|
111 </row> |
|
112 <row> |
|
113 <entry><p>Finalise the drives on the system using <codeph>RFs::FinaliseDrives() </codeph> </p> </entry> |
|
114 <entry><p>It calls the <codeph>RFs::FinaliseDrives()</codeph> API to finalise |
|
115 the drives on the device. </p> <p> <b>Note:</b> This is intended for use in |
|
116 the shutdown commandList. </p> </entry> |
|
117 </row> |
|
118 <row> |
|
119 <entry><p>Request for BAFL to persist the HAL attributes </p> </entry> |
|
120 <entry><p>It calls the <codeph>BAFL::PersistHAL()</codeph> API to persist |
|
121 the persistent HAL values to disk. </p> <p> <b>Note:</b> This is intended |
|
122 for use in the shutdown commandList. </p> </entry> |
|
123 </row> |
|
124 <row> |
|
125 <entry><p>Request a state transition to occur </p> </entry> |
|
126 <entry><p>It calls the request system state transition that is provided by |
|
127 SSM. This request is treated like any other requested system state transition |
|
128 with the policy plug-in being able to accept, fail, or queue the transition. |
|
129 This command handles the automatic transition from the final commandList of |
|
130 the start-up state to the normal state. </p> </entry> |
|
131 </row> |
|
132 <row> |
|
133 <entry><p>Command severity information </p> </entry> |
|
134 <entry><p>When a command fails SSMA performs the following actions: Ignore, |
|
135 Low, Medium, High, and Severity. For more information on command severity, |
|
136 see <xref href="GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57.dita#GUID-1F2911DC-7D71-573D-AFD2-1EA4BBA88A57/GUID-AA207E56-2F87-54E5-B19D-5246C5526827">Command |
|
137 severity information</xref>. </p> </entry> |
|
138 </row> |
|
139 </tbody> |
|
140 </tgroup> |
|
141 </table> <p id="GUID-AA207E56-2F87-54E5-B19D-5246C5526827"><b>Command severity |
|
142 information</b> </p> <p>Each command supports a Severity level, to determine |
|
143 the response during a command failure. In SysStart two actions take place |
|
144 when a command fails that is panic and ignore. </p> <ul> |
|
145 <li id="GUID-2D276EEA-C5F2-5F0A-AF42-50B869963D6D"><p> <codeph>EPanicOnCommandFailure</codeph> - |
|
146 Panic the system starter if command fails. This causes the device to restart. </p> </li> |
|
147 <li id="GUID-3FD86DCE-FC7A-53A0-801E-8CDF9A6D8597"><p> <codeph>EIgnoreCommandFailure</codeph> - |
|
148 Ignore the command failure </p> </li> |
|
149 </ul> <p>In a similar way, in SSMA, the following actions takes place when |
|
150 a command fails: Ignore, Low, Medium, High, and Severity. </p> <p>The following |
|
151 example code shows an identifier for the level of severity to be associated |
|
152 with a command failure: </p> <codeblock id="GUID-9990B545-1B5C-5E93-A7A0-D37D7F7EF6FE" xml:space="preserve">/** @publishedPartner |
|
153 @prototype */ |
|
154 enum TCmdErrorSeverity |
|
155 { |
|
156 /** Ignore the command failure. */ |
|
157 ECmdIgnoreFailure = 0, |
|
158 ECmdLowSeverity = 25, |
|
159 ECmdMediumSeverity = 50, |
|
160 ECmdHighSeverity = 75, |
|
161 ECmdCriticalSeverity = 100 |
|
162 };</codeblock> <p>The following list shows how the new command severity |
|
163 is mapped to the existing ones: </p> <ul> |
|
164 <li id="GUID-F863355B-0A8B-5FED-A840-D3D60CB2703A"><p> <codeph>EIgnoreCommandFailure |
|
165 -> ECmdIgnoreFailure</codeph> </p> </li> |
|
166 <li id="GUID-18F6DB1E-A126-5F3F-9421-5BA5EB5C179B"><p> <codeph>EPanicOnCommandFailure |
|
167 -> ECmdCriticalSeverity</codeph> </p> </li> |
|
168 </ul> <p><b>Adaptations to convert SysStart into SysCLE</b> </p> <p>The general |
|
169 adaptations made to convert SysStart into SysCLE are: </p> <ul> |
|
170 <li id="GUID-7AE47B3F-B8C9-531E-A0D1-F95F23E4B39E"><p>The process starting |
|
171 code is removed. </p> </li> |
|
172 <li id="GUID-9412EC1A-896B-5A4A-92C2-B251D3525F6F"><p>The existing implementation |
|
173 to read the Start-up mode and convert this into an SSC filename is removed |
|
174 (and re-used by policy plug-in). </p> </li> |
|
175 <li id="GUID-9BE3D557-F031-52D6-B599-4564B804FA84"><p>The resource file reader |
|
176 code is removed (and re-used by policy plug-ins). </p> </li> |
|
177 <li id="GUID-32E427E3-59FF-5C54-8FB4-1F90D6A4A436"><p>The SysCLE client (internal) |
|
178 API is implemented to: </p> <ul> |
|
179 <li id="GUID-D719DD35-9F5E-50F3-95ED-06C9E31AB145"><p>Handle the commandList |
|
180 object being received, and run the commandList. </p> </li> |
|
181 <li id="GUID-81B84D78-9ED8-5B88-9AAA-B07AB4B3C9DA"><p>Handle a request, to |
|
182 immediately stop a commandList that is running. </p> </li> |
|
183 </ul> </li> |
|
184 <li id="GUID-92282F21-D127-5BDA-9848-A86873D506E6"><p>The existing implementation |
|
185 to Add (load) the Startup Domain Hierarchy is removed. </p> </li> |
|
186 <li id="GUID-0577911A-F289-5B28-A796-CA4FF000C6EF"><p>The SysCLE implementation |
|
187 expects system state change to occur at any time in a commandList. </p> </li> |
|
188 <li id="GUID-1EE3E9B5-5430-5548-BDD5-4C789BF77D95"><p>The handling of the |
|
189 retry_failure_recovery_method must be adapted. The SysStart decides on the |
|
190 recovery policy when a commandList fails to run. When a critical retry failure |
|
191 occurs (that is <codeph>ERestartOS</codeph>) this is returned to SysStart |
|
192 (with any indicated Start-up mode). If a non-critical retry failure occurs |
|
193 (that is <codeph>EIgnoreFailure</codeph>), this is also returned to SysStart. </p> </li> |
|
194 <li id="GUID-A4DC8B53-095B-599D-A582-60EBF7B46222"><p>The ability for SysState |
|
195 to query if any non-critical commands failed to run successfully in the commandList. |
|
196 This API also provides further information about the failed command and not |
|
197 just returns a Boolean value describing if a command failed or not. Allowing |
|
198 SysState to store or act on this information provides information as to what |
|
199 state the system is when debugging. </p> </li> |
|
200 </ul> </section> |
|
201 </conbody></concept> |