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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    29 System Starter architecture provides an ability to select between a number

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

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

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

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

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

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

    36 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> –

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

    38 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> –

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

    40 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> –

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

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

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

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

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

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

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

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

    49 <tbody>

    50 <row>

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

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

    53 </row>

    54 <row>

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

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

    57 </row>

    58 <row>

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

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

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

    62 </row>

    63 <row>

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

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

    66 </row>

    67 </tbody>

    68 </tgroup>

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

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

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

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

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

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

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

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

    77 <tbody>

    78 <row>

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

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

    81 </row>

    82 <row>

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

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

    85 </row>

    86 <row>

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

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

    89 </row>

    90 <row>

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

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

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

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

    95 default) </p> </li>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   112 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

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

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

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

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

   117 </row>

   118 <row>

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

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

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

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

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

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

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

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

   127 </row>

   128 <row>

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

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

   131 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

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

   133 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

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

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

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

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

   138 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

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

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

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

   142 </row>

   143 <row>

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

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

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

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

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

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

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

   151 </row>

   152 <row>

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

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

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

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

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

   158 if applicable retry_failure_recovery_startup_mode) will be used by the System

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

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

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

   162 </row>

   163 <row>

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

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

   166 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

   167 default. </p> </entry>

   168 </row>

   169 </tbody>

   170 </tgroup>

   171 </table> </section>

   172 </conbody></concept>