Guidelines +to adapt the existing GSA components to SSMA

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.

System Monitor

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.

Adaptations +to the System Monitor

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.

Current re-launch +policy

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).

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 KWaitTime seconds has elapsed (since the +last re-launch attempt). This mechanism is referred to as ‘Re-launch throttling’.

Critical +component functionality in SysMon

A new value for the retry_failure_recovery_method +(that is ECriticalNoRetries) 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.

The PlatSec capabilities required by a SysMon +client to set this value is the same as for retry_failure_recovery_method += ERestartOS. If this new value (ECriticalNoRetries) +is set as the retry_failure_recovery_method in a Static Command +List (that is for launching a process/application), SysCLE treats this as retry_failure_recovery_method += ERestartOS, and performs (if needed) the number of retries indicated +in no_of_retries_on_failure.

System Command +List Executer

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 (SysStateMgr.exe). 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.

SCLs +contains a list of commands that are run by the SSM and SysCLe runs the commands +as per the policy.

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.

+ + + + +

New commands

Description

+ + + + +

Change Domain Manager State

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.

+ + +

Change system-wide property

Changes the value of a system-wide property (P&S property).

+ + +

Call asynchronous Custom Commands

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 SysStateMgr, +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.

Note: Custom +commands allow licensees and partners to provide commands that can be run +by the SysCLE with those provided by Symbian.

+ + +

Use the switch off and restart functionally provided by the kernel +power API

It provides the ability to restart or shutdown the device.

Note: It +is expected that these commands are used as the last commands in the commandList +for the shutdown state.

+ + +

Sending save events to all clients registered to receive them through CSaveNotifier

It notifies all clients that have requested notification through +the existing CSaveNotifier interface of a save notification +event.

+ + +

Finalise the drives on the system using RFs::FinaliseDrives()

It calls the RFs::FinaliseDrives() API to finalise +the drives on the device.

Note: This is intended for use in +the shutdown commandList.

+ + +

Request for BAFL to persist the HAL attributes

It calls the BAFL::PersistHAL() API to persist +the persistent HAL values to disk.

Note: This is intended +for use in the shutdown commandList.

+ + +

Request a state transition to occur

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.

+ + +

Command severity information

When a command fails SSMA performs the following actions: Ignore, +Low, Medium, High, and Severity. For more information on command severity, +see Command +severity information.

+ + + +

Command severity +information

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.

EPanicOnCommandFailure - +Panic the system starter if command fails. This causes the device to restart.
EIgnoreCommandFailure - +Ignore the command failure

In a similar way, in SSMA, the following actions takes place when +a command fails: Ignore, Low, Medium, High, and Severity.

The following +example code shows an identifier for the level of severity to be associated +with a command failure:

/** @publishedPartner +@prototype */ +enum TCmdErrorSeverity + { + /** Ignore the command failure. */ + ECmdIgnoreFailure = 0, + ECmdLowSeverity = 25, + ECmdMediumSeverity = 50, + ECmdHighSeverity = 75, + ECmdCriticalSeverity = 100 + };

The following list shows how the new command severity +is mapped to the existing ones:

EIgnoreCommandFailure +-> ECmdIgnoreFailure
EPanicOnCommandFailure +-> ECmdCriticalSeverity

Adaptations to convert SysStart into SysCLE

The general +adaptations made to convert SysStart into SysCLE are:

The process starting +code is removed.
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).
The resource file reader +code is removed (and re-used by policy plug-ins).
The SysCLE client (internal) +API is implemented to:
- Handle the commandList +object being received, and run the commandList.
- Handle a request, to +immediately stop a commandList that is running.
The existing implementation +to Add (load) the Startup Domain Hierarchy is removed.
The SysCLE implementation +expects system state change to occur at any time in a commandList.
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 ERestartOS) this is returned to SysStart +(with any indicated Start-up mode). If a non-critical retry failure occurs +(that is EIgnoreFailure), this is also returned to SysStart.
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.