<?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>