<?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-B386CA7A-F527-5584-9455-371E623DCF76" xml:lang="en"><title> System

Start Example</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Download</title> <p>Click on the following link to download

the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-e4fe3134-4d3b-443f-80fe-374972df6f9b.zip" scope="external"> SysStart.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-e4fe3134-4d3b-443f-80fe-374972df6f9b.html" scope="peer">browse</xref> to view the example code. </p> </section>

<section id="GUID-F3EFB022-A771-50D2-9C36-FFEFA4924441"><title> Description</title> <p>This

example demonstrates the use of resource files at the time of System Start-up.

System starter is an architecture designed to provide a consistent, transparent,

easily customisable method of starting components (i.e. servers and applications)

at device boot. It allows an ordering of components according to criticality

and dependency by means of a Static Start-up Configuration (SSC). </p> </section>

<section><title>Related APIs</title><p><xref href="GUID-478D0251-D49B-36C5-B9DF-09FFFE7CDB53.dita#GUID-478D0251-D49B-36C5-B9DF-09FFFE7CDB53/GUID-E99F5505-FC87-3232-A933-4C522C04931A"><apiname>egSysStart::E32Main () </apiname></xref></p><p><xref href="GUID-478D0251-D49B-36C5-B9DF-09FFFE7CDB53.dita#GUID-478D0251-D49B-36C5-B9DF-09FFFE7CDB53/GUID-54F036C5-D86E-34B0-B74A-AD4DF2328086"><apiname>egSysStart::Simple

()</apiname></xref></p></section>

<section id="GUID-693F8259-B441-50F2-8E2A-EB2A57E5665A"><title>Resource files</title> <p>In

this example a resource file <codeph>SSCForStartupMode0.rss</codeph> is used

at Start-up. </p> <p>On a target device booting normally, the SSC <codeph>SSCForStartupMode0.rss</codeph> is

always used for start-up. This SSC is associated with startup mode zero, which

is defined as <xref href="GUID-6866563D-8AF5-3F3F-A777-50B264194B83.dita"><apiname>EStartupModeUndefined</apiname></xref> in e32modes.h. The

System Starter architecture provides an ability to select between a number

of static Start-up configurations (rss files) depending on the desired Start-up

Mode, for example: Full, Emergency, Charging, or Test. Each of these modes

may require different sets of components and order of execution. </p> <p>The

start-up process in the resource file is staged via an ordering of Start-up

States or phases. These states cannot be removed or their values altered.

They appear in the following order: </p> <p> <xref href="GUID-F4C1F118-3580-3D25-AB14-DAD8D20CF302.dita"><apiname>EStartupStateUndefined</apiname></xref> –

Value before the system enters its first state/ undefined state. </p> <p> <xref href="GUID-DA625784-61CA-3256-9D93-EB447BF9AA62.dita"><apiname>EStartupStateCriticalStatic</apiname></xref> –

Within this Start-up State all ROM based (static) components or resources

that are critical to the operation of the phone function are started. </p> <p> <xref href="GUID-737BC60E-ECA2-3B22-A0A4-5F6F5136D6F0.dita"><apiname>EStartupStateCriticalDynamic</apiname></xref> –

Within this Start-up State all non-ROM based (dynamic) components or resources

that are critical to the operation of the phone function are started. </p> <p> <xref href="GUID-3C0E080D-7FF1-3347-B129-D2805FCD7840.dita"><apiname>EStartupStateNonCritical</apiname></xref> –

Within this Start-up State all ROM based (static) or non-ROM based (dynamic)

components or resources that are non-critical to the operation of the phone

function are started. All components that have not already been started and

are required at device boot are started in this Start-up State. </p> <p>This

allows start-up to be split into separate, distinct states with a defined

order. Within each state, a <codeph>STATE_INFO</codeph> structure containing

information regarding that state is located. This contains the following information: </p> <table id="GUID-A370B739-910B-55E5-9C92-FAC72362FDCB">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph>Id</codeph>  </p> </entry>

<entry><p>The id of the state as defined in the custom header file </p> </entry>

</row>

<row>

<entry><p> <codeph>Name</codeph>  </p> </entry>

<entry><p>A text string describing the state </p> </entry>

</row>

<row>

<entry><p> <codeph>Command_list</codeph>  </p> </entry>

<entry><p>The name of the Command array in the SSC which contains the list

of Commands to invoke in that state </p> </entry>

</row>

<row>

<entry><p> <codeph>Next</codeph>  </p> </entry>

<entry><p>The name of the Command array corresponding to the next state </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>Following the <codeph>STATE_INFO</codeph> structure in the SSC

is a <codeph>COMMAND_ARRAY</codeph> structure. This contains details of all

commands to be executed within that list. Its name matches the command_list

identifier in the <codeph>STATE_INFO</codeph> struct and contains one array

entry: Commands. The Command entry contains a list of all commands to be executed.

Each instance in the rss file is headed with the <codeph>START_PROCESS_INFO </codeph> identifier

and contains any value needed to override the defaults specified in <codeph>startup.rh</codeph>. </p> <table id="GUID-7E7519BC-54C9-59E7-AB07-46748C6F7A44">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><codeblock id="GUID-44EDEC24-A19F-5991-9528-11804376ABB2" xml:space="preserve">Type</codeblock> </entry>

<entry><p>Set by default. Should not be specified in the SSC. </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-7559D8D5-DD16-5E7B-86EB-0337ED7ACCE7" xml:space="preserve">Path</codeblock> </entry>

<entry><p>The location of the binary e.g. path = "Z:\sys\bin\fbserv.exe" </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-C4C5EE86-3E58-552B-8607-F1AC8B6EDCD1" xml:space="preserve">Args</codeblock> </entry>

<entry><p>Arguments passed to the process. </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-6C04D96F-6B77-5368-9B48-9BC9D35B6710" xml:space="preserve">start_method</codeblock> </entry>

<entry><p>The enum <codeph>TStartupCommandType</codeph> is defined in <codeph>startup.hrh</codeph>.

Currently it takes one of three values: </p> <ul>

<li id="GUID-EB15D58C-A9FC-5C92-A5F6-23CA7D547C86"><p> <xref href="GUID-119A71D6-F979-345B-8AC7-7768F68A36BE.dita"><apiname>EFireAndForget</apiname></xref> (the

default) </p> </li>

<li id="GUID-FC24705E-4144-5FCA-AA4D-04871C5ED6F9"><p> <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref>  </p> </li>

<li id="GUID-BE71C616-0E0B-5916-9058-43B0CA5A278F"><p> <xref href="GUID-3C5930DE-E84C-3170-AC5A-BCFC16D6AE77.dita"><apiname>EDeferredWaitForStart</apiname></xref>  </p> </li>

</ul> <p>Use <xref href="GUID-119A71D6-F979-345B-8AC7-7768F68A36BE.dita"><apiname>EFireAndForget</apiname></xref> if there is no need for the

process to be started serially in other words as soon as the process has been

invoked, the System Starter can continue with starting the next process without

waiting for the process to rendezvous. </p> <p>Use <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> if

the process needs to get to a certain stage before starting the next process.

The starter cannot continue with the next Command until a rendezvous has been

made with the first process. </p> <p>Note that the apparc component must be

started with mode <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> to allow connection with

the server to take place. </p> <p>Use <xref href="GUID-3C5930DE-E84C-3170-AC5A-BCFC16D6AE77.dita"><apiname>EDeferredWaitForStart</apiname></xref> if

there is no need to start the process serially, but at a later stage there

is a command which cannot be invoked until this process has initialized. Using

this value allows a number of commands to be started and the System Starter

to wait for them all at a later point in the SSC. This ensures later on that

the initializations of all <xref href="GUID-3C5930DE-E84C-3170-AC5A-BCFC16D6AE77.dita"><apiname>EDeferredWaitForStart</apiname></xref> commands

have completed. </p> <p> <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> and <xref href="GUID-3C5930DE-E84C-3170-AC5A-BCFC16D6AE77.dita"><apiname>EDeferredWaitForStart</apiname></xref> depend

upon receiving a rendezvous from the started process. By default this is performed

automatically by EikonEnv. If however, you wish your component to perform

its own rendezvous, then the following function should be overridden in your

AppUi class and return <codeph>EFalse.</codeph>  </p> <p> <codeph>TBool CCoeAppUi::FrameworkCallsRendezvous();</codeph>  </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-1E9E11D2-3BAA-54F2-9481-6A1987CF4100" xml:space="preserve">timeout</codeblock> </entry>

<entry><p>This field is for use with start_method <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> only. </p> <p>Indicate

if a timer should be started when attempting to start the process by filling

in this timeout value in milliseconds. The value is 0 by default indicating

that no timer will be started. </p> <p>Note that if the timer expires before

a rendezvous with the component is made, the component will be killed. If

the component is a critical process this will result in a Kern:4 Panic (which

on licensee phones usually initiates in a system restart). </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-CFDA47D2-551B-5215-8854-6FC63433A22B" xml:space="preserve">retry_failure_recovery_method</codeblock> </entry>

<entry><p>This specifies the action to take if an error is returned from an

attempt to start the process. </p> <p>It is set to <xref href="GUID-644CC7B0-3B94-307A-A5A1-D7EC78F10105.dita"><apiname>ERestartOS</apiname></xref> by

default. This means if the process fails to start the system will restart

in the default start-up mode. </p> <p>If it is set to <xref href="GUID-1E757E7A-98C8-3455-8D82-28A24FBEA729.dita"><apiname>EIgnoreOnFailure</apiname></xref> then

the starter will continue with the next Command. This option is intended for

non-critical components on which nothing critical is dependent. </p> <p>If

it is set to <xref href="GUID-D7BCDD4C-97A0-3068-AC4C-F10DA31DD636.dita"><apiname>ERestartOSWithMode</apiname></xref> the system will be restarted

in a specific start-up mode. </p> <p>Note: this field has a slightly different

use depending on the start mode: in modes <xref href="GUID-119A71D6-F979-345B-8AC7-7768F68A36BE.dita"><apiname>EFireAndForget</apiname></xref> and <xref href="GUID-3C5930DE-E84C-3170-AC5A-BCFC16D6AE77.dita"><apiname>EDeferredWaitForStart</apiname></xref> a

failure will be indicated only if there is an immediate error for example

the initial process creation/invocation fails. In <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> a

failure will also be indicated if there is no successful rendezvous. </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-33D3ABEE-9A48-51B7-BFB7-6CEF2AED8DAE" xml:space="preserve">no_of_retries_on_failure</codeblock> </entry>

<entry><p>For use with start_method <xref href="GUID-8415D00B-79D9-36BE-9F0B-2DAA3A553CD2.dita"><apiname>EWaitForStart</apiname></xref> only.

Set to 0 by default. </p> <p>This specifies the maximum number of times the

starter should try to start a failed process. After the process has been retried

the specified number of times, the starter will act according to the value

in the <codeph>retry_failure_recovery_method</codeph> field. This is used

in conjunction with the timeout value. </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-782C1BA6-D764-5C6C-A232-9CCD5C22AEA3" xml:space="preserve">monitor</codeblock> </entry>

<entry><p>Indicates whether the started process should be monitored for failure

by the System Monitor component. The value is 0 by default indicating that

no monitoring will be done. </p> <p>A value of 1 indicates monitoring should

be performed. The recovery policy set by <codeph>retry_failure_recovery_method</codeph> (and

if applicable retry_failure_recovery_startup_mode) will be used by the System

Monitor if a failure occurs to this process during the lifetime of the system. </p> <p>Note:

if the component being started is a System Critical process, monitoring must

not be enabled. </p> </entry>

</row>

<row>

<entry><codeblock id="GUID-8305C64D-3198-5C5B-9AD4-C774D38B9369" xml:space="preserve">retry_failure_recovery_startup_mode</codeblock> </entry>

<entry><p>For use with retry_failure_recovery_method <xref href="GUID-D7BCDD4C-97A0-3068-AC4C-F10DA31DD636.dita"><apiname>ERestartOSWithMode</apiname></xref> only. </p> <p>Used

to specify the start-up mode the system should restart with. This is set to <xref href="GUID-6866563D-8AF5-3F3F-A777-50B264194B83.dita"><apiname>EStartupModeUndefined</apiname></xref> by

default. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>