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