<?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 id="GUID-1B233701-DF98-46DD-A9F0-1DBBBD8F07E3"><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 id="GUID-9C5B0C4B-32F9-4F39-8C3E-F5188A6D54AA"><title>Related APIs</title><ul>

<li><p><codeph>egSysStart::E32Main ()</codeph></p></li>

<li><p><codeph>egSysStart::Simple ()</codeph></p></li>

</ul></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-D3303938-1F27-319A-836A-FE4242E91696.dita#GUID-D3303938-1F27-319A-836A-FE4242E91696/GUID-96874644-A26A-36E6-AFE4-568B2DA8C2E5"><apiname>TStartupCommandType::EStartupStateUndefined</apiname></xref> – Value before the system enters its first state/ undefined state. </p> <p> <xref href="GUID-D3303938-1F27-319A-836A-FE4242E91696.dita#GUID-D3303938-1F27-319A-836A-FE4242E91696/GUID-1FF1DBF6-7AB1-33E0-8D10-AADE02B7D440"><apiname>TStartupCommandType::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-D3303938-1F27-319A-836A-FE4242E91696.dita#GUID-D3303938-1F27-319A-836A-FE4242E91696/GUID-A5FB6340-2EA8-32A3-8138-95DD326BC123"><apiname>TStartupCommandType::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-D3303938-1F27-319A-836A-FE4242E91696.dita#GUID-D3303938-1F27-319A-836A-FE4242E91696/GUID-5883EFE6-36A6-30EB-851B-9FD26C1C9B03"><apiname>TStartupCommandType::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>

</conbody></concept>