|
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-8BA1EEC2-78A3-54CC-95D9-81BF2659963D" xml:lang="en"><title>Base |
|
13 Starter Technology</title><shortdesc>This topic describes the purpose of the Base Starter, and which |
|
14 parts of it can be customised by phone developers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The purpose of the Base Starter is to: </p> |
|
16 <ul> |
|
17 <li id="GUID-D6418767-A7E8-5C3F-A12D-57B038D6DDEA"><p>Define a handset's local |
|
18 drives </p> </li> |
|
19 <li id="GUID-2611D5AC-D6FD-5957-A359-11D5A7200B2F"><p>Define what file systems |
|
20 (<filepath>.FSY</filepath>) and file extensions (<filepath>.FXT</filepath>) |
|
21 are to be mounted on those drives </p> </li> |
|
22 <li id="GUID-96772B04-8CC5-5248-A015-48809163B6EA"><p>Associate drive letters |
|
23 with drives </p> </li> |
|
24 <li id="GUID-36BFBCDC-0A12-53E0-8DF6-97606089A996"><p>Modify drive start-up |
|
25 behaviour </p> </li> |
|
26 <li id="GUID-C8914C2A-4FEA-5367-9C8C-5BD1B8926416"><p>Enable <xref href="GUID-89BCF9A5-ABBD-5523-BA76-FDB00B806A30.dita">fair |
|
27 scheduling and file caching</xref> on a drive by drive basis. </p> </li> |
|
28 </ul> |
|
29 <p>Handset manufacturers need to customise the Base Starter as part of the |
|
30 process of porting Symbian platform to a new device. <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-BF793E4E-8303-5C94-A297-52C5AD781B6B">Mapping local drives</xref> is the most important part of this process, but <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-89ED1556-60A5-5030-8946-7156656B7771">customisation |
|
31 using TFSStartup</xref> is also possible. </p> |
|
32 <p>Note that there are some <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-AC49186C-F69B-5D5B-8515-3CF8CD91EAF4">activities |
|
33 that the Base Starter does not do</xref> </p> |
|
34 <section id="GUID-BF793E4E-8303-5C94-A297-52C5AD781B6B"><title>Mapping local |
|
35 drives</title> <p>There are two ways to do this: </p> <ul> |
|
36 <li id="GUID-F9A1D807-DFF0-563E-B792-0C7AE29F16CA"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-2B95B775-1BD1-5256-86D3-CD3FA12447B9">Create local drive mapping files</xref> </p> </li> |
|
37 <li id="GUID-23B391A9-70B1-54F6-A891-422B5C6274DE"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-A195BD51-80C7-5D87-ABA2-8878CC509B84">Use automatic local drive mapping</xref>. </p> </li> |
|
38 </ul> <p id="GUID-2B95B775-1BD1-5256-86D3-CD3FA12447B9"><b>Create local drive mapping |
|
39 files</b> </p> <p>A local drive mapping file is an ASCII text file that explicitly |
|
40 defines the drive letter, file system, and file extension to be associated |
|
41 with a drive. The file contains a set of records, one for each drive, that |
|
42 specifies this information. Records are also referred to as drive mappings. </p> <p>The |
|
43 file is created as part of your hardware variant's source tree, but is copied |
|
44 into a standard location in your ROM filing system when you build the ROM. </p> <p>A |
|
45 drive mapping file has a formal structure; the main rules are: </p> <ul> |
|
46 <li id="GUID-2F5C4942-D39B-5F80-8E31-CAB8E7411554"><p>the file can contain |
|
47 a maximum of 16 different drive mappings </p> </li> |
|
48 <li id="GUID-BA8CB9C2-F3D7-5A06-9385-6FE7B3472B6C"><p>each drive mapping is |
|
49 represented by a separate record; each record occupies one line; each line |
|
50 is separated by the new line character <codeph>\n</codeph> </p> </li> |
|
51 <li id="GUID-D1A6514F-3A2C-5B2E-818B-9933CA98BC1F"><p>information is represented |
|
52 by items separated by at least one blank character </p> </li> |
|
53 <li id="GUID-A6F6AD8B-361F-5DAC-8151-467164281CBD"><p>comments can occupy |
|
54 a whole line or can be added onto the end of a record (i.e. at the end of |
|
55 line). They are marked by a <codeph>#</codeph> character that must precede |
|
56 the start of the comment text. </p> </li> |
|
57 </ul> <p>A record, or drive mapping, has the following items, each separated |
|
58 by at least one blank character. Each item must appear in the order described: </p> <codeblock id="GUID-EC69C9D7-C7C3-5687-AB75-2157ABF012D5" xml:space="preserve"><drive_letter> <drive_number> <file_system_filename> <file_system> <file_extension_filename> <flags></codeblock> <table id="GUID-D09A4483-1819-56A5-96C5-167D59C79E45"> |
|
59 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
60 <tbody> |
|
61 <row> |
|
62 <entry><p> <codeph> <drive_letter></codeph> </p> </entry> |
|
63 <entry><p>A single character between <codeph>A</codeph> and <codeph>Z</codeph> followed |
|
64 by a colon. </p> </entry> |
|
65 </row> |
|
66 <row> |
|
67 <entry><p> <codeph> <drive_number></codeph> </p> </entry> |
|
68 <entry><p>The local drive number associated with the drive letter . </p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p> <codeph><file_system_filename></codeph> </p> </entry> |
|
72 <entry><p>The filename of the file system that is to be mounted on the drive. |
|
73 This should be the filename without the <filepath>.FSY</filepath> extension. |
|
74 If it is necessary to omit a file system file name for any reason, then this |
|
75 item should contain the null character: <codeph>0</codeph>. </p> </entry> |
|
76 </row> |
|
77 <row> |
|
78 <entry><p> <codeph> <file_system></codeph> </p> </entry> |
|
79 <entry><p>The name of the file system as implemented by <codeph><file_system_filename></codeph>. </p> <p>If |
|
80 the file system name is the same as the file name, as represented by the <codeph><file_system_filename></codeph> item, |
|
81 then supply the null character <codeph>0</codeph>. [Internally, the file system |
|
82 name is sometimes referred to as the object name.] </p> <p>Symbian platform |
|
83 supplies the following file systems: </p> <ul> |
|
84 <li id="GUID-BB05125F-DEAA-5881-8B5D-27CF2735598E"><p> <codeph> FAT</codeph> </p> </li> |
|
85 <li id="GUID-F9CAA425-F382-5131-A2CE-A8813EC2844C"><p> <codeph> ROFS</codeph> - |
|
86 read/only file system </p> </li> |
|
87 <li id="GUID-1C9ED727-60A6-5835-B10B-BC5DF0C11763"><p> <codeph>LFFS</codeph> - |
|
88 logging flash file system </p> </li> |
|
89 <li id="GUID-B175831B-3633-5B56-AD5A-76218DFA6032"><p> <codeph> COMP</codeph> - |
|
90 composite file system (but see the description of the <codeph>FS_COMPOSITE</codeph> flag |
|
91 below) </p> </li> |
|
92 </ul> <p>Handset manufacturers may supply other file systems. </p> </entry> |
|
93 </row> |
|
94 <row> |
|
95 <entry><p> <codeph> <file_extension_filename></codeph> </p> </entry> |
|
96 <entry><p>The filename of the file extension that is to be mounted on the |
|
97 drive. This should be the filename without the <filepath>.FXT</filepath> extension. |
|
98 If it is necessary to omit a file extension file name for any reason, then |
|
99 this item should contain the null character: <codeph>0</codeph>. </p> </entry> |
|
100 </row> |
|
101 <row> |
|
102 <entry><p> <codeph><flags></codeph> </p> </entry> |
|
103 <entry><p>A set of <i>mount</i> flags that modify the start-up behaviour of |
|
104 the local drive. More than one flag can be specified, each separated by a |
|
105 comma, with no intervening blank characters. If no flags apply, then the null |
|
106 character: <codeph>0</codeph> must be coded. </p> <p><table id="GUID-E1FCA3ED-EF56-5C3E-9596-CBBD7DF53AE1"> |
|
107 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
108 <tbody> |
|
109 <row> |
|
110 <entry><p> <codeph>FS_FORMAT_ALWAYS</codeph> </p> </entry> |
|
111 <entry><p>Formats the drive as soon as it has been mounted. </p> </entry> |
|
112 </row> |
|
113 <row> |
|
114 <entry><p> <codeph>FS_FORMAT_COLD</codeph> </p> </entry> |
|
115 <entry><p>Formats the drive as soon as it has been mounted if the device is |
|
116 performing a cold boot. This is generally required for internal RAM drives. </p> </entry> |
|
117 </row> |
|
118 <row> |
|
119 <entry><p> <codeph> FS_FORMAT_CORRUPT </codeph> </p> </entry> |
|
120 <entry><p>Formats the drive, if it is found to be corrupt when mounted. </p> </entry> |
|
121 </row> |
|
122 <row> |
|
123 <entry><p> <codeph> FS_DISMNT_CORRUPT</codeph> </p> </entry> |
|
124 <entry><p>Dismounts the drive, if it is found to be corrupt when mounted. |
|
125 The local drive mapping remains unaltered and the associated file system file |
|
126 is not unloaded. </p> </entry> |
|
127 </row> |
|
128 <row> |
|
129 <entry><p> <codeph> FS_SWAP_CORRUPT-<drv></codeph> </p> </entry> |
|
130 <entry><p>Dismounts the drive, if it is found to be corrupt when mounted, |
|
131 and swaps the mappings for this drive with the alternative drive <codeph><drv></codeph>, |
|
132 and remounts both. </p> <p>The alternative drive <codeph><drv></codeph> must |
|
133 be specified, and must follow a '<codeph>-</codeph>' character, which follows |
|
134 the <codeph>FS_SWAP_CORRUPT</codeph> symbol. </p> <p>For example, to swap |
|
135 with drive <filepath>Y:</filepath>, specify: </p> <codeblock id="GUID-9CC3B772-73D6-5F12-959A-54090AEE7EB1" xml:space="preserve">FS_SWAP_CORRUPT-Y</codeblock> <p>This |
|
136 option is commonly used when handling corrupt flash user-data drives on <filepath>C:</filepath>. |
|
137 The corrupt drive is mapped to another drive letter – allowing data to be |
|
138 extracted from it. The <filepath>C:</filepath> drive is replaced by a RAM |
|
139 disk – providing a temporary work disk for the OS, while the main one is restored. |
|
140 Note that a mapping file must not specify more than one drive for swapping, |
|
141 i.e. there can only be one occurrence of <codeph>FS_SWAP_CORRUPT</codeph> flag |
|
142 per mapping file. </p> <p>Both drives involved in the swap must be internal |
|
143 drives. </p> </entry> |
|
144 </row> |
|
145 <row> |
|
146 <entry><p> <codeph>FS_SYNC_DRIVE</codeph> </p> </entry> |
|
147 <entry><p>Mounts this drive as a synchronous drive. This means that requests |
|
148 are handled in the main file server thread rather than in a dedicated drive |
|
149 thread. This option is normally only specified for internal RAM drives. </p> </entry> |
|
150 </row> |
|
151 <row> |
|
152 <entry><p> <codeph> FS_SCANDRIVE</codeph> </p> </entry> |
|
153 <entry><p>Runs <filepath>Scandrive</filepath>, once mounted, but only if the |
|
154 rugged file system is enabled. </p> </entry> |
|
155 </row> |
|
156 <row> |
|
157 <entry><p> <codeph>FS_COMPOSITE</codeph> </p> </entry> |
|
158 <entry><p>Marks the drive as contributing to the composite file system. The |
|
159 composite file system allows multiple local drives to be overlaid with each |
|
160 other, and with the core OS ROM image, and to make them appear as one drive. </p> <p>Files |
|
161 in one drive can add to, replace, or hide (i.e. logically remove) files in |
|
162 another drive </p> <p>There are number of rules: </p> <ul> |
|
163 <li id="GUID-73C84D80-12E4-5EB2-9661-6F802696F4E8"><p>the drive letter must |
|
164 always be Z: </p> </li> |
|
165 <li id="GUID-B8BA7BF4-5451-5B14-80F7-44E37DB08B23"><p>if the file system is |
|
166 omitted, i.e. both <codeph><file_system_filename></codeph> and <codeph><file_system></codeph> are |
|
167 set to '0', then the the ROFS file system is assumed, and this can be the <i>only</i> drive |
|
168 marked with <codeph>FS_COMPOSITE</codeph> in a mapping file. </p> </li> |
|
169 <li id="GUID-E64061B1-C789-57D4-BDD2-32548AC9A97B"><p>if the file system is |
|
170 explicitly specified, i.e. <codeph><file_system_filename></codeph> and <codeph><file_system></codeph> are |
|
171 set, then more than one drive can be marked with <codeph>FS_COMPOSITE</codeph>. |
|
172 However, adding a drive that uses a file system other than ROFS is <i>strongly |
|
173 discouraged</i> for performance reasons. </p> </li> |
|
174 <li id="GUID-2B4F9A89-9907-5417-91B3-94E02F212E42"><p>the order of the records |
|
175 is important, as this defines the search order when Symbian platform is working |
|
176 out which files will contribute to the final ROM. The core OS ROM file system |
|
177 (containing the kernel, kernel extensions, media drivers, the file server, |
|
178 file systems and the Base Starter executable) is searched first, followed |
|
179 by the last drive in the mapping file marked with <codeph>FS_COMPOSITE</codeph>, |
|
180 followed by the next last drive marked with <codeph>FS_COMPOSITE</codeph> etc. </p> </li> |
|
181 </ul> <p>Note: the use of <codeph>COMP</codeph> as a <codeph><file_system></codeph> seems |
|
182 to contradict the use of this flag. <codeph>COMP</codeph> was used to specify |
|
183 a composite file system that allowed a <i>single</i> drive to be combined |
|
184 with the ROM file system. For compatibility purposes, and to ensure consistency |
|
185 of syntax, you can still specify <codeph>COMP</codeph> with <codeph>FS_COMPOSITE</codeph> on |
|
186 a drive mapping, but you cannot have any other drive mappings marked as <codeph>FS_COMPOSITE</codeph>. |
|
187 If you specify <codeph>COMP</codeph>, then the underlying file system associated |
|
188 with that drive is assumed to be <codeph>ROFS</codeph>. </p> <p>See <xref href="GUID-E55EE9B5-AC5B-5C67-A23C-DDB3F40D174A.dita">Mounting multiple ROM images |
|
189 as a single ROM drive</xref> for more detail. </p> </entry> |
|
190 </row> |
|
191 <row> |
|
192 <entry><p> <codeph> FS_NO_MOUNT</codeph> </p> </entry> |
|
193 <entry><p>Loads the file specified file system and the specified file extension, |
|
194 and maps the drive as specified, but does not mount the drive. This is often |
|
195 used in conjunction with <codeph>FS_SWAP_CORRUPT</codeph>. It allows the configuration |
|
196 for the alternative drive involved in a swap to be specified – but for the |
|
197 drive not to be mounted and accessible in normal operation. If the drive is |
|
198 involved in a swap with another, then the <codeph>FS_NO_MOUNT</codeph> state |
|
199 is ignored and the drive is mounted normally. </p> </entry> |
|
200 </row> |
|
201 <row> |
|
202 <entry><p> <codeph>FS_ALLOW_REM_ACC</codeph> </p> </entry> |
|
203 <entry><p>This is reserved for future use. </p> </entry> |
|
204 </row> |
|
205 <row> |
|
206 <entry><p> <codeph> FS_NOT_RUGGED</codeph> </p> </entry> |
|
207 <entry><p>Marks the mount as not rugged. Mounting the drive without the rugged |
|
208 file system means that <codeph>FS_SCANDRIVE</codeph> is not supported. If <codeph>FS_SCANDRIVE</codeph> is |
|
209 also defined, it is ignored. </p> </entry> |
|
210 </row> |
|
211 <row> |
|
212 <entry><p> <codeph> FS_SYSTEM_DRIVE</codeph> </p> </entry> |
|
213 <entry><p>Assigns this drive as the system drive. Applications store user |
|
214 data on the system drive, and call <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>RFs::GetSystemDriveChar()</apiname></xref> to |
|
215 discover the drive letter. </p> <p>A mapping file can only specify one drive |
|
216 as the system drive. </p> <p>See <xref href="GUID-629AB2C9-BEDD-5166-8B09-F8DFF7527C03.dita">the |
|
217 system drive</xref>. </p> </entry> |
|
218 </row> |
|
219 </tbody> |
|
220 </tgroup> |
|
221 </table> </p> </entry> |
|
222 </row> |
|
223 </tbody> |
|
224 </tgroup> |
|
225 </table> <p id="GUID-A195BD51-80C7-5D87-ABA2-8878CC509B84"><b>Use automatic local drive |
|
226 mapping</b> </p> <p>If no drive mapping file exists or is unavailable, the |
|
227 Base Starter decides which file system to mount on each local drive by interrogating |
|
228 the capabilities of those drives. This is known as auto-detection. </p> <p>Internally, |
|
229 the Base Starter holds a table containing entries for every known supported |
|
230 local drive configuration. This table is known as the auto-configuration table. |
|
231 The information supplied by each entry in the table resembles that supplied |
|
232 by a <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-2B95B775-1BD1-5256-86D3-CD3FA12447B9">local |
|
233 drive mapping file</xref>, and contains the following information: </p> <ul> |
|
234 <li id="GUID-0713E2D9-B47F-552D-B4BB-D2B587534F86"><p>The filename of the |
|
235 file system for this configuration (the <filepath>.FSY</filepath>). The filename |
|
236 corresponds to the <codeph><file_system_filename></codeph> item in a drive |
|
237 mapping file entry. </p> </li> |
|
238 <li id="GUID-A27734C1-04DC-5741-8C9F-E28DAAC12E9B"><p>The object name of the |
|
239 file system for this configuration. The object name corresponds to the <codeph> <file_system></codeph> item |
|
240 in a drive mapping file entry. </p> </li> |
|
241 <li id="GUID-1B40A8A4-C883-5385-8255-023DAA42FD24"><p>The filename of the |
|
242 file server extension for this configuration, if applicable. The filename |
|
243 corresponds to the <codeph> <file_system></codeph> item |
|
244 in a drive mapping file entry. </p> </li> |
|
245 <li id="GUID-D50A002B-A6F5-5CE0-95A8-5327F5D43F2E"><p>The set of mount flags; |
|
246 these correspond to the <codeph><flags></codeph> items in a drive mapping |
|
247 file entry. There is one exception - <codeph>FS_SWAP_CORRUPT</codeph> is not |
|
248 supported, because it is impossible to auto-detect which drive is to be swapped. </p> </li> |
|
249 <li id="GUID-1F79E6A1-FEC3-57A7-8C50-DDC7296610C5"><p>A file system identification |
|
250 function that is used to decide whether the designated file system is really |
|
251 suitable for this drive. Each function is an internal part of the generic |
|
252 Base Starter code. </p> </li> |
|
253 </ul> <p>The Base Starter uses the following default mapping of drive letters |
|
254 to drive numbers: </p> <table id="GUID-861EC91F-CB71-5E7F-A58F-F14A890C2EC1"> |
|
255 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
256 <tbody> |
|
257 <row> |
|
258 <entry><p> <b> Local drive number</b> </p> </entry> |
|
259 <entry><p> <b> Drive letter</b> </p> </entry> |
|
260 </row> |
|
261 <row> |
|
262 <entry><p> <codeph>0</codeph> </p> </entry> |
|
263 <entry><p>C</p> </entry> |
|
264 </row> |
|
265 <row> |
|
266 <entry><p> <codeph>1</codeph> </p> </entry> |
|
267 <entry><p>D</p> </entry> |
|
268 </row> |
|
269 <row> |
|
270 <entry><p> <codeph>2</codeph> </p> </entry> |
|
271 <entry><p>E</p> </entry> |
|
272 </row> |
|
273 <row> |
|
274 <entry><p> <codeph>3</codeph> </p> </entry> |
|
275 <entry><p>F</p> </entry> |
|
276 </row> |
|
277 <row> |
|
278 <entry><p> <codeph>4</codeph> </p> </entry> |
|
279 <entry><p>G</p> </entry> |
|
280 </row> |
|
281 <row> |
|
282 <entry><p> <codeph>5</codeph> </p> </entry> |
|
283 <entry><p>H</p> </entry> |
|
284 </row> |
|
285 <row> |
|
286 <entry><p> <codeph>6</codeph> </p> </entry> |
|
287 <entry><p>I</p> </entry> |
|
288 </row> |
|
289 <row> |
|
290 <entry><p> <codeph>7</codeph> </p> </entry> |
|
291 <entry><p>J</p> </entry> |
|
292 </row> |
|
293 <row> |
|
294 <entry><p> <codeph>8</codeph> </p> </entry> |
|
295 <entry><p>K</p> </entry> |
|
296 </row> |
|
297 <row> |
|
298 <entry><p> <codeph>9</codeph> </p> </entry> |
|
299 <entry><p>L</p> </entry> |
|
300 </row> |
|
301 <row> |
|
302 <entry><p> <codeph>10</codeph> </p> </entry> |
|
303 <entry><p>M</p> </entry> |
|
304 </row> |
|
305 <row> |
|
306 <entry><p> <codeph>11</codeph> </p> </entry> |
|
307 <entry><p>N</p> </entry> |
|
308 </row> |
|
309 <row> |
|
310 <entry><p> <codeph>12</codeph> </p> </entry> |
|
311 <entry><p>O</p> </entry> |
|
312 </row> |
|
313 <row> |
|
314 <entry><p> <codeph>13</codeph> </p> </entry> |
|
315 <entry><p>P</p> </entry> |
|
316 </row> |
|
317 <row> |
|
318 <entry><p> <codeph>14</codeph> </p> </entry> |
|
319 <entry><p>Q</p> </entry> |
|
320 </row> |
|
321 <row> |
|
322 <entry><p> <codeph>15</codeph> </p> </entry> |
|
323 <entry><p>R</p> </entry> |
|
324 </row> |
|
325 </tbody> |
|
326 </tgroup> |
|
327 </table> </section> |
|
328 <section id="GUID-89ED1556-60A5-5030-8946-7156656B7771"><title>Customisation |
|
329 using TFSStartup</title> <p>Most of the functionality provided by the Base |
|
330 Starter is provided by the class <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup</apiname></xref>. |
|
331 This contains a number of virtual functions with default Symbian implementations. |
|
332 A handset manufacturer can create a customised version of the Base Starter, |
|
333 which overrides these functions. </p> <ul> |
|
334 <li id="GUID-49B2FC6B-E0BF-548C-9537-FE02B420EE7A"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-9B842CF3-D1A2-5BC7-8979-42EC7CD9A523">Disabling drive auto-detection</xref> </p> </li> |
|
335 <li id="GUID-90090D6E-2788-590C-8595-4E4423E51F5B"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-4AB5A9C6-6D33-58E9-A372-033C1595DB9E">Customising for multiple hardware states</xref> </p> </li> |
|
336 <li id="GUID-1D7344CC-0876-5973-8E57-E2619E4D8B32"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-7098B073-430F-5CA6-91C6-BCF267B33BF3">Overriding the default drive mapping</xref> </p> </li> |
|
337 <li id="GUID-9399A990-84B2-553B-900A-DBBD7EC8C04F"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-904D8CCE-9E16-5A60-B141-9C838B1B8B44">Customising mount flags</xref> </p> </li> |
|
338 <li id="GUID-ED7B2E26-4147-553C-9DCF-06143EEEF2ED"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-905BFBD9-AD40-5E11-AFED-F791389F1450">Customising the drive initialisation sequence</xref> </p> </li> |
|
339 <li id="GUID-4C6122EB-9898-5874-AB65-900F739DC611"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-B93875C5-1B35-5993-89C4-B2CA5F502450">Customising Loadlocale</xref> </p> </li> |
|
340 <li id="GUID-95C61E12-EE0B-57B8-B5FA-EB476471D93C"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-0B60FAF0-5D2F-5A0F-984C-DFB35BC09ED2">Customising the restart mode</xref> </p> </li> |
|
341 <li id="GUID-1A1EDBF0-92B4-5369-9077-210842CA13C6"><p> <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-4E9AFD2A-57DE-528A-8F41-C79EBE44B2A0">Customising other behaviour</xref> </p> </li> |
|
342 </ul> <p id="GUID-9B842CF3-D1A2-5BC7-8979-42EC7CD9A523"><b>Disabling drive auto-detection</b> </p> <p>The |
|
343 most common customisation is to use the supplied version of the Base Starter |
|
344 and to create one or more local drive mapping files . In this case, savings |
|
345 in code space can be made by removing the code that deals with auto-detection. |
|
346 This is achieved by adding the following line to the <filepath>MMP</filepath> file |
|
347 describing the Base Starter, and then rebuilding it. </p> <codeblock id="GUID-4D382A63-638C-5AF2-9535-88C7E3AB0869" xml:space="preserve">MACRO AUTODETECT_DISABLE</codeblock> <p id="GUID-4AB5A9C6-6D33-58E9-A372-033C1595DB9E"><b>Customising for multiple |
|
348 hardware states</b> </p> <p>If the state of your hardware varies, and it requires |
|
349 different mapping files for different states, then it is still possible to |
|
350 use the local drive mapping scheme. Examples of hardware state variations |
|
351 might be differences in the state of a switch or jumper setting, or the presence |
|
352 or absence of a hardware feature. In this situation, the ROM can be built |
|
353 with more than one mapping file. A custom version of the Base Starter provides |
|
354 its own version of the virtual function <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::LocalDriveMappingFileName()</apiname></xref>; |
|
355 this checks the appropriate settings, and returns the name of the appropriate |
|
356 local drive mapping file. The returned name is the full path name. </p> <p id="GUID-7098B073-430F-5CA6-91C6-BCF267B33BF3"><b>Overriding the default drive |
|
357 mapping</b> </p> <p>To override the default mapping of drive letters to drive |
|
358 numbers on a drive by drive basis, a custom version of the Base Starter provides |
|
359 its own version of the virtual function <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::DefaultLocalDrive()</apiname></xref>. </p> <p>To |
|
360 override the auto-configuration table used by the automatic local drive mapping |
|
361 scheme, for example to add support for a new <filepath>.FSY</filepath>, a |
|
362 custom version of the Base Starter provides its own version of the virtual |
|
363 function <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::GetNextStandardFSInfoEntry()</apiname></xref>. </p> <p id="GUID-904D8CCE-9E16-5A60-B141-9C838B1B8B44"><b>Customising mount flags</b> </p> <p>Whether |
|
364 you use the automatic local drive mapping scheme or an explicit local drive |
|
365 mapping file, you can provide support for additional mount flags. A custom |
|
366 version of the Base Starter provides its own version of the virtual functions: </p> <ul> |
|
367 <li id="GUID-8F1D6582-946C-5D25-AEE7-95563233BDDF"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::ParseCustomMountFlags()</apiname></xref> </p> </li> |
|
368 <li id="GUID-C65F29D7-8BFD-5B84-B184-57C734F3D5EF"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::HandleCustomMountFlags()</apiname></xref> </p> </li> |
|
369 </ul> <p id="GUID-905BFBD9-AD40-5E11-AFED-F791389F1450"><b>Customising the drive initialisation |
|
370 sequence</b> </p> <p>To override the entire local drive initialisation sequence |
|
371 provided by the generic version of the Base Starter, a custom version of the |
|
372 Base Starter provides its own version of the virtual function <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartUp::LocalDriveInit()</apiname></xref>. </p> <p id="GUID-B93875C5-1B35-5993-89C4-B2CA5F502450"><b>Customising Loadlocale</b> </p> <p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>User::UTCOffset()</apiname></xref> is called within the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>LoadLocale()</apiname></xref> function. Customise <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::LoadLocale()</apiname></xref> so |
|
373 that the offset behaviour is correct for your time zone. </p> <p>Setting the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>User::UTCOffset()</apiname></xref> is required within EStart |
|
374 to provide backward compatibility and because it provides the system time |
|
375 to components before the timezone/locale services are initialised. </p> <p>See <xref href="GUID-15E048BA-E158-508D-9DB4-C9DF9A546090.dita">setting the universal time |
|
376 offset</xref>. </p> <p id="GUID-0B60FAF0-5D2F-5A0F-984C-DFB35BC09ED2"><b>Customising the restart |
|
377 mode</b> </p> <p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::GetStartupMode()</apiname></xref> and <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::GetStartupModeFromFile()</apiname></xref> must be |
|
378 implemented to get the restart mode at start-up. </p> <p>Symbian platform |
|
379 does not define any meaning to restart mode values. It is for the use of the |
|
380 device manufacturer. </p> <p>The restart mode is defined by the HAL attribute <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>EPersistStartupM</apiname></xref>. This is a <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TAttribute</apiname></xref> enum |
|
381 value defined in class <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>HALData</apiname></xref> in <filepath>..\hal\inc\hal_data.h</filepath>. </p> <p>To |
|
382 use this attribute, define it in your variant’s <filepath>config.hcf</filepath> file |
|
383 and set an initial value in your variant’s <filepath>values.hda</filepath> file. |
|
384 The template port defines the attribute as settable using the following definition |
|
385 in the <filepath>config.hcf</filepath> file. </p> <codeblock id="GUID-DCB65835-DB05-5092-B4D0-5ABA551773F8" xml:space="preserve">EPersistStartupModeKernel : set = ProcessPersistStartupMode</codeblock> <p>The value can be changed using <codeph>HAL::Set()</codeph>. <codeph>ProcessPersistStartupMode</codeph> is |
|
386 the name of a function internal to Symbian platform. If you choose to make |
|
387 the attribute settable, you must use this definition. </p> <p>Calls to <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>HAL::Get()</apiname></xref> are routed to the function <codeph>Template::VariantHal()</codeph> in |
|
388 your variant's <filepath>variant.cpp</filepath> file, and handled by the <codeph>EVariantHalGetPersistedStartupMode</codeph> case. </p> <p>Calls |
|
389 to <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>HAL::Set()</apiname></xref> are routed to the function <codeph>Template::VariantHal()</codeph> in |
|
390 your variant's <filepath>variant.cpp</filepath> file, and handled by the <codeph>EVariantHalPersistStartupMode</codeph> case. </p> <p>You |
|
391 need to do the following: </p> <ul> |
|
392 <li id="GUID-1B0499AB-4320-598D-B4FD-89B610C8CC2D"><p>If you choose to make |
|
393 the custom startup mode settable (in Symbian platform terminology, the attribute |
|
394 is said to be derived), you need to implement <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::GetStartupMode()</apiname></xref>. |
|
395 Derived attributes are saved when the system is closed down. The function <codeph>GetStartupMode()</codeph> is |
|
396 called before the file server starts. </p> </li> |
|
397 <li id="GUID-EB91080D-1321-52B1-9EEA-718B02413928"><p>If you choose to make |
|
398 the custom startup mode non-settable (in Symbian platform terminology, the |
|
399 attribute is said to be non-derived), you need to implement <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::GetStartupModeFromFile()</apiname></xref>. |
|
400 Non-derived attributes are read from file, and this function is called after |
|
401 the file server has started. </p> </li> |
|
402 <li id="GUID-8C418384-C30C-59E2-9E2A-542701C4D0DF"><p>You need to provide |
|
403 an implementation for your <codeph>Template::VariantHal()</codeph> function |
|
404 in your <filepath>variant.cpp</filepath> file. </p> </li> |
|
405 </ul> <p>The example below is the OMAP H4 variant implementation of <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>GetStartupModeFromFile()</apiname></xref> and <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>GetStartupMode()</apiname></xref> found |
|
406 in <filepath>...\dev1\omap_hrp\h4estart\estartmain.cpp</filepath>. </p> <codeblock id="GUID-8BD6A664-7A7E-580E-AD33-46C7B6AB4FB5" xml:space="preserve">TInt TH4FSStartup::GetStartupModeFromFile() |
|
407 { |
|
408 if (iStartupMode != EStartupModeUndefined) |
|
409 { |
|
410 TInt r = ReadAndReset(); |
|
411 return r; |
|
412 } |
|
413 return KErrNone; |
|
414 } |
|
415 |
|
416 TInt TH4FSStartup::GetStartupMode() |
|
417 { |
|
418 TInt r = ReadAndReset(); |
|
419 return r; |
|
420 } |
|
421 |
|
422 TInt TH4FSStartup::ReadAndReset() |
|
423 { |
|
424 TInt value; |
|
425 TInt r = HAL::Get(HALData::EPersistStartupModeKernel, value); |
|
426 if (r == KErrNone) |
|
427 { |
|
428 iStartupMode = value; |
|
429 } |
|
430 r = HAL::Set(HALData::EPersistStartupModeKernel, EStartupModeUndefined); |
|
431 return r; |
|
432 }</codeblock> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side |
|
433 Hardware Abstraction</xref>. </p> <p id="GUID-4E9AFD2A-57DE-528A-8F41-C79EBE44B2A0"><b>Customising other behaviour</b> </p> <p>You |
|
434 can change other default behaviour. For example, to add additional functionality |
|
435 related to File Server initialisation, or the initialisation of other base |
|
436 related components, then the following virtual functions can also be customised. |
|
437 Follow the links to the individual functions for more detail: </p> <ul> |
|
438 <li id="GUID-DF81E0C5-3404-50BA-B91D-D57CA5B0C08C"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::Init()</apiname></xref> </p> </li> |
|
439 <li id="GUID-3D245F97-00D2-561E-A752-2ACC2EFBEC92"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::Run()</apiname></xref> </p> </li> |
|
440 <li id="GUID-F700923A-3E2C-5BE0-8EBB-911C7A8C1D56"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::InitialiseHAL()</apiname></xref> </p> </li> |
|
441 <li id="GUID-D60B9ADD-EB13-5FB1-A632-488383D89289"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::StartSystem()</apiname></xref> </p> </li> |
|
442 <li id="GUID-93DD7CF9-77BA-56E2-8BB6-617EC6CF3865"><p> <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup::Close()</apiname></xref> </p> </li> |
|
443 </ul> </section> |
|
444 <section id="GUID-AC49186C-F69B-5D5B-8515-3CF8CD91EAF4"><title>Activities |
|
445 that the Base Starter does not do</title> <p>The Base Starter is responsible |
|
446 for mapping local drives to drive letters and for loading the appropriate |
|
447 file systems on local drives. It does <i>not</i> install media drivers, and |
|
448 is not responsible for deciding which local drive a media driver will register |
|
449 with. This is done by the individual media drivers and peripheral controllers |
|
450 when they are initialised. </p> <p>See <xref href="GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52.dita#GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52/GUID-4A8DEEAB-32C4-5431-8226-5623E2BD9098">Registering |
|
451 the media driver</xref> for information about how to register a media driver. </p> <p>See |
|
452 also <xref href="GUID-5C223AD5-4676-58B4-B3A5-066F6B69AA4D.dita#GUID-5C223AD5-4676-58B4-B3A5-066F6B69AA4D/GUID-868866C8-E90C-5291-8732-BB4E86D6B43E">Local |
|
453 Media Subsystem</xref>. </p> </section> |
|
454 </conbody></concept> |