|
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-0A61CB48-B8EA-5516-B24E-65898CDF2566" xml:lang="en"><title>How |
|
13 to Configure Multithreaded C32 Serial Comms: Tutorial</title><abstract><shortdesc>This page describes how a device manufacturer can configure |
|
14 the grouping of CSYs into various threads. </shortdesc> <p>The Serial Server |
|
15 on Symbian platform supports the use of multiple threads in order to separate |
|
16 the serial plug-in CSY modules. The first section provides a brief migration |
|
17 guide, while the subsequent sections provide more detail on the specific parameters |
|
18 and behaviour, and other advanced information. </p> </abstract><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
19 |
|
20 <section id="GUID-4109EB99-A9A8-597B-BF42-89CF6AD7DB73"><title>Introduction</title> <p>The |
|
21 Comms Configurator (<codeph>c32start</codeph>) uses a configuration Comms |
|
22 Module Ini file (.CMI) to load Comms Provider Modules (CPMs) into the Rootserver |
|
23 process. Each CMI file represents exactly one CPM loaded inside Rootserver. |
|
24 CPMs are the name given to threads running inside the Rootserver process, |
|
25 since they extend the thread concept by adding a wrapper of extra information |
|
26 and functionality used to manage the threads. </p> <p>The Comms Configurator |
|
27 searches for the CMI files in the <codeph>\private\101f7988</codeph> folders |
|
28 by searching from Y: to A: and then Z:. The folder <filepath>101f7988</filepath> is |
|
29 the secure area for the Comms Configurator process and its name derives from |
|
30 the UID for the process - as specified by the requirements for <xref href="GUID-1E7AA950-06C2-599C-BCC2-12BB99306E1B.dita#GUID-1E7AA950-06C2-599C-BCC2-12BB99306E1B/GUID-03558B99-2B98-579C-AD59-CF66BD98F69F">Data Caging</xref>. If the files are found in the ROM (usually Z:) they are <i>not</i> then |
|
31 copied to any other drive but only read in-place. Thus, a later configuration |
|
32 of CMI files installed on another media/drive other than the ROM drive can |
|
33 be used to override the original ROM configuration. The Configurator reads |
|
34 these files only once during boot so any further changes will not take effect |
|
35 until the next system boot. </p> </section> |
|
36 <section id="GUID-B742D7C6-ACA3-40CD-8D2D-B8E8AB4F1885"><title>Quick Migration Guide</title> <p>This section provides a brief |
|
37 description of how to migrate a configuration from the old single-threaded |
|
38 C32 Serial Server to the new multi-threaded server. As there are numerous |
|
39 potential configurations with the multi-threaded server, this migration guide |
|
40 should be used as a first step to getting any old settings migrated over and |
|
41 thus allowing the server to continue working after an upgrade of Symbian platform. </p> <p>Once |
|
42 migrated, the other sections in this article provide further useful information |
|
43 regarding configuring CMI files for better performance in line with the requirements |
|
44 of the particular device. </p> <p>The quick migration involves two steps: </p> <ul> |
|
45 <li id="GUID-07F882AE-797F-5326-A4C3-DC596F3BC888"><p>apply any special configuration |
|
46 used with the previous single-threaded C32 Serial Server to the new configuration |
|
47 files supplied with the multi-threaded server </p> </li> |
|
48 <li id="GUID-423E4236-73EA-51CA-B9E3-03761078DF86"><p>adjust the default set |
|
49 of configuration files supplied with the multi-threaded server to suit the |
|
50 particular serial plug-ins in use </p> </li> |
|
51 </ul> <p>These two steps are explained in more detail in the following sections. </p> <p><b>Migrating settings</b> </p> <p>The original single-threaded Serial Server |
|
52 was controlled by a single configuration file called (by default) <filepath>c32.cmi</filepath>, |
|
53 located in <filepath>\private\101f7988</filepath>. A default version of this |
|
54 file shipped with Symbian platform, although a device manufacturer could change |
|
55 this file. The default version of this file was: </p> <codeblock id="GUID-897E8787-4E34-5D80-B04F-85E94EE5B570" xml:space="preserve">## Comms Configurator config file for the C32 server |
|
56 |
|
57 [Loader] |
|
58 Name=CCommServer |
|
59 FileName=c32.dll |
|
60 ThreadFunctionOrdinal=87 |
|
61 IsServer=1 |
|
62 IsSticky=1 |
|
63 Priority=EPriorityMuchMore |
|
64 StackSize=8192 |
|
65 ScaledStartupState=0x1085 |
|
66 HeapOption=EDefaultHeap |
|
67 MinHeapSize=256 |
|
68 MaxHeapSize=524288 |
|
69 SystemCritical=1</codeblock> <p>The multi-threaded C32 Serial Server (C32MT) |
|
70 ships by default with five configuration files, since by default it supports |
|
71 five different threads. These configuration files are: </p> <codeblock id="GUID-AE8071D9-1ECD-58EF-AC33-713B42EDB7F8" xml:space="preserve">\private\101f7988\c32.cmi |
|
72 \private\101f7988\c32_first.cmi |
|
73 \private\101f7988\c32_second.cmi |
|
74 \private\101f7988\c32_third.cmi |
|
75 \private\101f7988\c32_fourth.cmi</codeblock> <p>They are an extended version |
|
76 of the original CMI file that shipped with the single-threaded C32. For example, |
|
77 the first of these configuration files (c32.cmi) looks like: </p> <codeblock id="GUID-6B6FF51B-A9CC-5D9D-99B0-A98BA1634FA2" xml:space="preserve"># c32_main - Comms Configurator config file forming part of the Default C32 server configuration |
|
78 |
|
79 [Loader] |
|
80 Name=C32_Main |
|
81 FileName=c32.dll |
|
82 ThreadFunctionOrdinal=87 |
|
83 IsSticky=0 |
|
84 IsServer=1 |
|
85 Priority=EPriorityMuchMore |
|
86 StackSize=16384 |
|
87 ScaledStartupState=0x1085 |
|
88 HeapOption=ENewHeap |
|
89 MinHeapSize=256 |
|
90 MaxHeapSize=524288 |
|
91 SystemCritical=1 |
|
92 Group=C32SerComms |
|
93 OnDemand=0 |
|
94 # Don't check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck) |
|
95 ControlFlags=4 |
|
96 [IniData] |
|
97 Role=Dealer |
|
98 WorkerId=0</codeblock> <p>The first step in migrating is to ensure that any |
|
99 unique configuration used with the old server is migrated across to the new |
|
100 server. The particular parameters that should be considered in this procedure |
|
101 are: </p> <codeblock id="GUID-8E2C24C0-8770-57CD-8064-5D85F4096DAE" xml:space="preserve">Priority |
|
102 StackSize |
|
103 ScaledStartupState |
|
104 MinHeapSize |
|
105 MaxHeapSize |
|
106 SystemCritical</codeblock> <p>These parameters would need migrating to each |
|
107 of the five new CMI files. The following notes relate to deliberate changes |
|
108 to parameter values between the single and multi-threaded servers: </p> <dl> |
|
109 <dlentry> |
|
110 <dt><b>HeapOption</b> </dt> |
|
111 <dd><p>The value of <codeph>HeapOption</codeph> is different between the old |
|
112 and new files - this was made to aid in debugging the new multi-threaded server |
|
113 by separating its memory from the rest of the comms system. It can be safely |
|
114 changed back if desired. </p> </dd> |
|
115 </dlentry> |
|
116 <dlentry> |
|
117 <dt><b>IsSticky</b> </dt> |
|
118 <dd><p>The value of <codeph>IsSticky</codeph> has changed from 1 to 0. The <codeph>IsSticky</codeph> parameter |
|
119 is normally unused in a production system for the Serial Server since the |
|
120 server runs as a <codeph>SystemCritical</codeph> thread and thus cannot be |
|
121 shutdown and, if it panics, the phone would reboot. The change was made to |
|
122 facilitate testing, since in a test environment the Serial Server can be shutdown, |
|
123 and to facilitate this the value of <codeph>IsSticky</codeph> must be set |
|
124 to 0. </p> </dd> |
|
125 </dlentry> |
|
126 <dlentry> |
|
127 <dt><b>StackSize</b> </dt> |
|
128 <dd><p>The value of <codeph>StackSize</codeph> has increased from 8192 for |
|
129 the single-threaded C32 to 16384 for C32MT. This change is due to the increased |
|
130 stack usage of the multi-threaded C32. The value used - 16384 - was based |
|
131 on the value proven to work with the similar ESock multi-threaded server. |
|
132 It is possible that this value could be trimmed back towards 8192 to save |
|
133 memory depending on the CSYs being used, since the ECUART CSY has been tested |
|
134 to work with the multi-threaded C32 server with a stack size of just 8192, |
|
135 and CSYs are usually much less memory-demanding than the protocols being used |
|
136 in ESock. </p> </dd> |
|
137 </dlentry> |
|
138 </dl> <p><b>Assigning |
|
139 CSY plug-ins to threads</b> </p> <p>The second part of migration to the new |
|
140 multi-threaded serial server is to alter the default set of CMI files to match |
|
141 the plug-ins (CSYs) in use and the desired operation. This step is not mandatory |
|
142 since by default C32 will load all plug-ins correctly. But, it is worth considering |
|
143 at this stage whether the default configuration needs some changes to match |
|
144 the requirements of the device. </p> <p>There are three broad configurations |
|
145 available, which are defined by whether one or more CSYs are run in the main |
|
146 thread for efficiency. The default configuration supplied with Symbian platform |
|
147 runs all the CSYs outside the main thread since this ensures that no CSY can |
|
148 deny service to the main server thread. It is expected that this configuration |
|
149 will suit most situations, but for more information on the other configurations, |
|
150 see the later section <xref href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita#GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566/GUID-5A5FEA44-F43B-51BE-9736-7FC76901DB02">Typical |
|
151 Thread Configuration Examples</xref>. </p> <p>As mentioned earlier, the default |
|
152 configuration uses five threads. The description for each of these is given |
|
153 in the following table: </p> <table id="GUID-0F03B8CD-0142-595A-874F-A35C80F8C991"> |
|
154 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
155 <thead> |
|
156 <row> |
|
157 <entry>Worker ID</entry> |
|
158 <entry>Summary</entry> |
|
159 <entry>CMI file</entry> |
|
160 <entry>Description</entry> |
|
161 </row> |
|
162 </thead> |
|
163 <tbody> |
|
164 <row> |
|
165 <entry><p>0</p> </entry> |
|
166 <entry><p>Main thread </p> </entry> |
|
167 <entry><p> <filepath>c32.cmi</filepath> </p> </entry> |
|
168 <entry><p>Runs the serial server to service client requests and pass on to |
|
169 the CSYs, possibly in other threads. This thread is expected to be started |
|
170 at device boot. </p> </entry> |
|
171 </row> |
|
172 <row> |
|
173 <entry><p>1</p> </entry> |
|
174 <entry><p>USB thread </p> </entry> |
|
175 <entry><p> <filepath>c32_first.cmi</filepath> </p> </entry> |
|
176 <entry><p>Runs the USB CSY (ECACM). This is separated from all other threads |
|
177 so that USB can run at high-speed uninterrupted. This thread is only started |
|
178 when a client requires a USB connection. </p> </entry> |
|
179 </row> |
|
180 <row> |
|
181 <entry><p>2</p> </entry> |
|
182 <entry><p>Baseband thread </p> </entry> |
|
183 <entry><p> <filepath>c32_second.cmi</filepath> </p> </entry> |
|
184 <entry><p>Runs the RS232 CSY (ECUART). This thread runs the ECUART plug-in |
|
185 separately since ECUART is sometimes used to connect to the baseband. If a |
|
186 different CSY is being used to connect to the baseband, it can be added to |
|
187 this CMI file and ECUART either moved to another thread, or removed altogether. |
|
188 As the baseband requires a high speed and fast response time, it is recommended |
|
189 that the baseband CSY should be run in this thread to separate it from all |
|
190 other CSYs. This thread is only started when a client requires the CSY. </p> </entry> |
|
191 </row> |
|
192 <row> |
|
193 <entry><p>3</p> </entry> |
|
194 <entry><p>Bluetooth and IrDA thread </p> </entry> |
|
195 <entry><p> <filepath>c32_third.cmi</filepath> </p> </entry> |
|
196 <entry><p>Runs the Bluetooth and IrDA CSYs. These CSYs usually do not have |
|
197 high requirements for throughput or response and thus can run together. This |
|
198 thread is only started when one of its CSYs is required by a client. </p> </entry> |
|
199 </row> |
|
200 <row> |
|
201 <entry><p>4</p> </entry> |
|
202 <entry><p>Default thread </p> </entry> |
|
203 <entry><p> <filepath>c32_fourth.cmi</filepath> </p> </entry> |
|
204 <entry><p>Runs any unlisted CSYs. If C32 is asked to load a CSY for which |
|
205 no thread has been identified in a CMI file, then C32 will load the CSY in |
|
206 this thread. This thread is only started when required. </p> </entry> |
|
207 </row> |
|
208 </tbody> |
|
209 </tgroup> |
|
210 </table> <p>For a particular device, the above configuration may need to be |
|
211 changed to address the requirements of the device. Typical adjustments to |
|
212 consider are: </p> <ol id="GUID-FB351652-6FBA-5176-9C51-AAC40752C333"> |
|
213 <li id="GUID-EA20A49C-FB32-5BC6-B47A-24F0487F65FD"><p>Change the CSY name |
|
214 for Worker ID 2 to match the baseband CSY, and then either move ECUART to |
|
215 Worker ID 3 or into its own new thread, or don't add it to any CMI file if |
|
216 the device doesn't use the ECUART CSY </p> </li> |
|
217 <li id="GUID-E08331AD-4AEA-5CAA-8C28-8B3001E1FAEC"><p>Add any extra low-performance |
|
218 CSYs to Worker ID 3 so that they run together with Bluetooth and IrDA. Extra |
|
219 CSYs could be run in a new separate thread but there is a memory cost for |
|
220 each new thread added so this should be considered (8K is typically allocated |
|
221 to a new thread, see <xref href="GUID-49379616-C235-598D-AE43-668998AD072B.dita#GUID-49379616-C235-598D-AE43-668998AD072B/GUID-5A573FEB-A274-5C0F-A6B6-87D5BAD8A21C">Process, |
|
222 thread, stack and memory useful information</xref>, and there is a limit to |
|
223 the number of threads with their own heaps that can be started in the Root |
|
224 Server). </p> </li> |
|
225 <li id="GUID-45D296E1-654C-5181-A38E-4D0AFC23A4A6"><p>For any extra high-performance |
|
226 CSYs, create a new CMI file so that these can run separately from the other |
|
227 CSYs. See <xref href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita#GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566/GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D">Creating |
|
228 A New CMI</xref> below </p> </li> |
|
229 <li id="GUID-BC119A2C-445A-5EF7-92DF-17D7E28A1A3B"><p>Prioritise important |
|
230 threads (or reduce the priority of lesser threads). Candidates for increased |
|
231 priority would be the Main, USB and Baseband threads. Care should be taken |
|
232 when adjusting thread priorities since these affect the whole Comms system |
|
233 - more guidance on setting thread priorities is available in the document <i>How |
|
234 To Assign Thread Priorities</i> elsewhere in this developer library. </p> </li> |
|
235 </ol> <p>When making these adjustments note that there is no cost involved |
|
236 with mentioning CSYs that may never be loaded. </p> </section> |
|
237 <section id="GUID-E7F95EA1-D91D-4623-B163-8BE198CC991C"><title>Overview of the C32 multi-threaded CMI files</title> <p>C32 |
|
238 Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading. |
|
239 The <b>Dealer</b> is the main C32 Comms Provider Module (CPM) which runs the |
|
240 C32 server; a Player is a C32 CPM that only runs one or more CSYs and takes |
|
241 the client requests from the Dealer module. </p> <p>For example: </p> <p> <b>C32.cmi</b> </p> <codeblock id="GUID-569AA81E-8689-5B15-A2C8-24E9163398A7" xml:space="preserve">[Loader] |
|
242 Name=C32_Main |
|
243 FileName=c32.dll |
|
244 ThreadFunctionOrdinal=87 |
|
245 IsServer=1 |
|
246 IsSticky=0 |
|
247 ThreadPriority=EPriorityMuchMore |
|
248 StackSize=16384 |
|
249 ScaledStartupState=0x1085 |
|
250 HeapOption=ENewHeap |
|
251 MinHeapSize=256 |
|
252 MaxHeapSize=524288 |
|
253 SystemCritical=1 |
|
254 Group=C32SerComms |
|
255 OnDemand=0 |
|
256 [IniData] |
|
257 Role=Dealer |
|
258 WorkerId=0 |
|
259 </codeblock> <p>The <xref href="GUID-83297976-F146-3B82-BE1C-C1E8F8B9DEE5.dita"><apiname>ThreadFunctionOrdinal</apiname></xref> identifier must |
|
260 refer to the correct ordinal number of the main thread function for the DLL |
|
261 file containing the Comms Provider Module. Due to binary compatibility considerations |
|
262 this must be placed at ordinal "87" in the export table. A Comms Provider |
|
263 Module/CPM is essentially a thread managed by the Comms Configurator. </p> <p>The |
|
264 description of each of the settings under <codeph>[Loader]</codeph> that are |
|
265 specific to C32 and the settings under <codeph>[IniData]</codeph> are described |
|
266 in further detail below. </p> <p>As well as the C32 server thread, any other |
|
267 CPMs that C32 needs must also have their own CMI file. One such example file |
|
268 is: </p> <p> <b>C32_Default.cmi</b> </p> <codeblock id="GUID-7E488DEF-535C-5C13-9DEA-246B11DF39E4" xml:space="preserve">[Loader] |
|
269 Name=C32_Default |
|
270 FileName=c32.dll |
|
271 ThreadFunctionOrdinal=87 |
|
272 IsServer=1 |
|
273 IsSticky=0 |
|
274 ThreadPriority=EPriorityMuchMore |
|
275 StackSize=16384 |
|
276 ScaledStartupState=0x3040 |
|
277 HeapOption=EShareHeap |
|
278 SharedHeapName=C32_Main |
|
279 MinHeapSize=256 |
|
280 MaxHeapSize=524288 |
|
281 SystemCritical=0 |
|
282 Group=C32SerComms |
|
283 OnDemand=1 |
|
284 Binding0=C32_Default:4,C32_Main:0,ECustom,42,42 |
|
285 [IniData] |
|
286 Role=Player |
|
287 WorkerId=4 |
|
288 CSYList=*</codeblock> </section> |
|
289 <section id="GUID-AEEFD832-108E-5CC2-AD5D-5CF6414CA720"><title>C32 CMI Parameter |
|
290 Descriptions</title> <p>This section gives details about the parameters available |
|
291 in the CMI file relevant to C32. The CMI file has two sections - a <codeph>[Loader]</codeph> section |
|
292 and an <codeph>[IniData]</codeph> section. The <codeph>[Loader]</codeph> section |
|
293 parameters are defined for the CPM, and the ones relevant to C32MT are detailed |
|
294 below. The <codeph>[IniData]</codeph> section contains parameters specific |
|
295 to a CPM. If further information on the format of the CMI file itself or the <codeph>[Loader]</codeph> parameters |
|
296 is required, please refer to the document <i>Comms Process Starter/Config |
|
297 Design Document</i> section <i>3.1.1</i>. This document is located in this |
|
298 developer library as well as in the <filepath>comms-infras\rootserver\Documentation</filepath> folder. </p> <p><b>A note on CMI processing</b> </p> <p>No mechanism is provided to change |
|
299 CMI files at run-time, since they are designed to be configured for inclusion |
|
300 in a ROM and then not changed through the life of a phone product. After-market |
|
301 changing of the configuration is supported via the installation of CMI files |
|
302 in a non-ROM folder which then take precedence over the ROM files when the |
|
303 device is next rebooted. Thus, any CMI configuration file problems should |
|
304 become apparent during the early stages of phone development. </p> <p>A bad |
|
305 configuration will panic in debug builds to signal the user to change/edit |
|
306 the <codeph>.CMI</codeph> files in order to make a desired and correct configuration. |
|
307 In <codeph>urel</codeph> builds a bad configuration may survive (unless the <codeph>.CMI</codeph> files |
|
308 are very malformed) but at a cost that all CSYs are loaded in the Dealer Thread |
|
309 (<codeph>Workerid=0</codeph>) making it in effect a single threaded system. </p> <p>The |
|
310 panic numbers used by the C32 Serial Server for internal server faults are |
|
311 defined in the enum <xref href="GUID-FED70722-0258-3B96-A941-1F7C13699002.dita"><apiname>TECommFault</apiname></xref>. </p> <p><b> CMI [Loader] Parameters relevant to C32</b> </p> <p><b>OnDemand </b> </p> <p>This indicates whether the CPM is started as part |
|
312 of the Configurator’s CPM load on boot ("0"), or whether the CPM should only |
|
313 be loaded via an explicit request to Configurator ("1"). The default value |
|
314 is "0". The <codeph>OnDemand</codeph> parameter for the main thread can only |
|
315 be "0" if mentioned. For Player modules the setting can be either "0" or "1". |
|
316 If a Player thread is not marked as <codeph>OnDemand=1</codeph> then it will |
|
317 load during the boot sequence. If the main thread (<codeph>Workerid=0</codeph>) |
|
318 is marked as <codeph>OnDemand=1</codeph>, then this is a configuration error |
|
319 and C32 can never be started (although in theory this is possible - see <xref href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita#GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566/GUID-6350761E-18F6-53B7-98F8-C6E2EB5DA942">Footnote |
|
320 1</xref> below). Players marked to load at boot up do not load any CSYs implicitly |
|
321 as part of the boot load. </p> <p>All Player modules for C32 must be marked |
|
322 with <codeph>OnDemand=1</codeph> since the C32 Dealer must instigate a Player |
|
323 load. If a Player thread is not marked as <codeph>OnDemand=0</codeph> then |
|
324 it will load during the boot sequence. </p> <p><b>Group </b> </p> <p>All CMI files for C32 must map to the same Group ID. |
|
325 The actual Group ID for the C32 group is <codeph>C32SerComms</codeph>. CMI |
|
326 files for C32 Players that do not have a Group member will never be loaded |
|
327 by C32 (assuming <codeph>OnDemand=1</codeph> is set for the Player threads). </p> <p>If |
|
328 there is no group defined in any CMI files and therefore no <b>[IniData]</b> is |
|
329 processed for any of them, then C32 will simply assign all CSYs to load into |
|
330 the Dealer thread. </p> <p> <b>Name</b> </p> <p>This parameter is used to |
|
331 identify the CPM to the Configurator and is used to name the thread for the |
|
332 kernel. It is stored by C32 for all CMI files in the C32SerComms group for |
|
333 use when requesting Configurator to load or unload a CPM. As this value is |
|
334 easily configurable and is used to name the thread to the kernel, software |
|
335 should not rely on the name of any C32 thread being any particular string. |
|
336 Prior to the multithreaded C32 (C32MT), the C32 thread was conventionally |
|
337 known as <codeph>CCommServer</codeph>. However, with C32 now potentially having |
|
338 a multiplicity of threads, other schemes are probable such as <codeph>C32_Main, |
|
339 C32_USB and C32_BaseBand</codeph> or <codeph>C32_BT-IR and C32_Default</codeph> </p> <p>The |
|
340 Dealer and all Players in the C32 group can have any name since C32 will find |
|
341 them as part of the same group (see Group above). The names in the C32 group |
|
342 should all be unique – if the same name is found twice or more C32 will panic |
|
343 in debug builds but attempt to recover in release builds by only processing |
|
344 the first that it finds. This is still a highly risky situation since if C32 |
|
345 needs to start that module in order to accommodate a CSY, Configurator may |
|
346 load the wrong CMI file when creating the new thread. </p> <p>When introducing |
|
347 new CMIs, care should be taken to change the <codeph>BindingN</codeph> line |
|
348 in CMI to reflect the new modulename and WorkerId. </p> <p><b>CMI [IniData] Parameters relevant to C32</b> </p> <p>In the case where |
|
349 C32 has a CMI file that loads the C32 binary during boot up, but the CMI file |
|
350 does not have an <codeph>[IniData]</codeph> section, C32 will assume that |
|
351 this CMI is for the main thread and that the CMI is a pre-C32MT file. However, |
|
352 for C32MT, this is an undesired configuration and should be rectified. Old |
|
353 versions of <codeph>c32.cmi</codeph> are only kept in the source distribution |
|
354 to support backwards compatibility and should not be used in a system which |
|
355 has C32MT present. In such backwards-compatible modes of C32MT, the main thread |
|
356 will host a Player in case no other CMI files are present. </p> <p> <b>Role</b> </p> <p>The |
|
357 value for this parameter should be either <codeph>Dealer</codeph> or <codeph>Player</codeph>. |
|
358 Only one <codeph>Dealer</codeph> can exist in a C32 system, but there can |
|
359 be any number of <codeph>Player</codeph> s. If there are two or more <codeph>Dealer</codeph> CMI |
|
360 files, the <codeph>ScaledStartupState</codeph> determines which Dealer CMI |
|
361 starts first. If both the CMIs have the same <codeph>ScaledStartupState</codeph>, |
|
362 then they are loaded in alphabetical order. Configurator is guaranteed to |
|
363 start a C: CMI file before the Z: one. If they both have the same module name |
|
364 then it is safe since Rootserver will refuse the load of the second module |
|
365 with the same name failing with <codeph>KErrAlreadyExists</codeph>. However, |
|
366 if the module name is different Rootserver will load them both and C32 will |
|
367 detect that an instance of itself is already running and exit the second thread. |
|
368 Only the IniData for the CMI file that was used to start the Dealer will be |
|
369 processed, with all other Dealer CMI files being ignored. If the main thread |
|
370 is to include a co-resident Player, the iniData should include the <codeph>CSYList</codeph> key-value |
|
371 pair discussed below. </p> <p> <b>WorkerId</b> </p> <p>The ID number of this |
|
372 thread inside the C32 system. The Id numbers should be a positive integer |
|
373 or "0" in the case of the main thread (In case CMI file of <codeph>WorkerId=0</codeph> has |
|
374 anything else than Dealer as role, it is overridden with Role=Dealer, logging |
|
375 a warning). The system expects subsequent ID numbers to be incremented up |
|
376 from the main thread's ID. Where a CMI file in the C32 group does not have |
|
377 a WorkerId, it is a bad configuration and will panic in debug builds. Allocating |
|
378 the next higher number is not possible as this Player needs to be bound with |
|
379 the Dealer using the <codeph>BindingN</codeph> line which accepts <codeph>WorkerId</codeph> parameter. |
|
380 In case of duplicate <codeph>WorkerId</codeph>, a panic occurs as the second |
|
381 module cannot be bound to the Dealer as the binding for the main thread has |
|
382 already been done. </p> <p> <b>CSYList</b> </p> <p>A comma-separated list |
|
383 of the filenames of the CSYs this thread will own. All CMIs in the C32 group |
|
384 must have a CSY list, except for the Dealer which can optionally have a <codeph>CSYList</codeph>. |
|
385 A Player with no <codeph>CSYList</codeph> represents a bad configuration as |
|
386 a Player’s sole purpose is to load CSYs. Such a Player with no CSY list will |
|
387 never be started by C32. A Dealer with no CSY list will act purely as a Dealer. |
|
388 A Dealer with a CSY list becomes a Dealer with a co-resident Player inside |
|
389 its thread. <codeph>CSYList</codeph> param determines if the CPM will host |
|
390 a Player or not. </p> <p>If a CSY appears in more than one CMI file, then |
|
391 the CSY will be assigned to one thread, but not necessarily that with the |
|
392 least number of CSYs in it. </p> <p>The comma-separated list should not have |
|
393 any spaces or other white space in it, and each CSY name must be an alphanumeric |
|
394 string. The CSY name is not case sensitive, and should not have the <codeph>.CSY</codeph> extension. |
|
395 C32 does not check whether the supplied CSY names actually exist as binaries, |
|
396 since it only refers to the list when a client asks to load a particular CSY. </p> <p>If |
|
397 an asterix ("*") appears as a CSY name in the CSY list, this is inferred by |
|
398 C32 as meaning that this thread is also to be used to load any CSYs not mentioned |
|
399 in any CMI file, and is known as the <i>default</i> thread. If two different |
|
400 CMI files in the C32 group have the wildcard then only one CMI file will be |
|
401 marked as being the host for unknown CSYs – it is not defined as to which |
|
402 one. If no CMI file has a wildcard then C32 will assign the wildcard to an |
|
403 unused Player thread so that all unlisted CSYs are isolated into their own |
|
404 thread. This is overridden if the only CMI file is for the Dealer, in which |
|
405 case the Dealer will load all CSYs into its own co-resident Player, since |
|
406 the Dealer cannot request the Configurator to start a module for which there |
|
407 is not an associated CMI file. </p> </section> |
|
408 <section id="GUID-8E49AE8A-E940-52F3-ADA5-0332DA1D58D2"><title>Important Notes</title> <p>Field |
|
409 names in the <codeph>[IniData]</codeph> are case sensitive, but fields values |
|
410 are not. </p> <p>The <codeph>BindingN</codeph> line is responsible for binding |
|
411 the Player CPM with Dealer. If you leave out the <codeph>BindingN</codeph> line |
|
412 from the CMI then the new Player will in essence remain as an island and no |
|
413 requests for loading or any subsequent operation can be passed to it from |
|
414 Dealer. This will not result in a panic. </p> <p>The <codeph>C32_Main.cmi</codeph> doesn’t |
|
415 have a <codeph>BindingN</codeph> line since it is a Dealer and thus does not |
|
416 need to bind to another Dealer. </p> </section> |
|
417 <section id="GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D"><title>Creating A |
|
418 New CMI</title> <p>To create a new CMI file, copy an existing Player CMI file, |
|
419 rename it and change the necessary parameters as detailed below. The examples |
|
420 below assume that the base CMI used was the supplied <codeph>c32_fourth.cmi</codeph>. |
|
421 The following parameters need to be changed to make a valid configuration |
|
422 file: </p> <p>In <b>[Loader] </b> section are: </p> <ul> |
|
423 <li id="GUID-6C3E5830-9A7A-5D84-B4A5-FCA7FD66E31A"><p> <b>Name</b> - This |
|
424 is the module name of CPM. </p> </li> |
|
425 <li id="GUID-D5BDBEAC-A417-5D39-BB85-4E5AB9DDD36A"><p> <b>BindingN</b> - BindingN |
|
426 line is changed to reflect the new module name and <codeph>WorkerId</codeph> value </p> </li> |
|
427 </ul> <p>In<b> [IniData] </b> section: </p> <ul> |
|
428 <li id="GUID-3855C593-297D-5360-9926-0A1BFFAC3B12"><p> <b>WorkerId</b> - This |
|
429 value is numeric and must be unique </p> </li> |
|
430 <li id="GUID-EA091203-C0E9-5303-9FD5-924F3C67FB55"><p> <b>CSYList</b> - Contains |
|
431 CSYs which you want to load in this new CPM, separated by commas, no white |
|
432 spaces allowed. </p> </li> |
|
433 </ul> <p>Since the additional CMI being added is a <codeph>Player</codeph>, |
|
434 the Role field remains the same and it can not be changed to <codeph>Dealer</codeph> as |
|
435 the CPM with <codeph>WorkerId=0</codeph> is the one and only Dealer in the |
|
436 C32MT. </p> <codeblock id="GUID-8722A0B7-FB88-5516-846B-BCC4E11D0EEE" xml:space="preserve">[Loader] |
|
437 # Change the Name value to your CSY name |
|
438 Name=C32_Default // </codeblock> <p>Change the <codeph>Name</codeph> value |
|
439 to the name of your CSY, e.g. </p> <codeblock id="GUID-EDCEA3C0-D4E6-5075-9FDE-65425194D6E5" xml:space="preserve">Name=C32_MyCSYs</codeblock> <codeblock id="GUID-B7D87670-C791-533F-A8F1-6135050387E2" xml:space="preserve">FileName=c32.dll |
|
440 ThreadFunctionOrdinal=87 |
|
441 ThreadPriority=EPriorityMuchMore |
|
442 StackSize=16384 |
|
443 ScaledStartupState=0x3040 |
|
444 HeapOption=ENewHeap |
|
445 MinHeapSize=256 |
|
446 MaxHeapSize=524288 |
|
447 SystemCritical=1 |
|
448 Group=C32SerComms |
|
449 OnDemand=1</codeblock> <p>Change the BindingN line to refer to your CSY, for |
|
450 example change from </p> <codeblock id="GUID-81BEFC33-67EE-5547-8C7C-E473F902F145" xml:space="preserve"># Change the BindingN line to refer to your CSYs |
|
451 Binding0=C32_Default:4,C32_Main:0,ECustom,42,42</codeblock> <p>to </p> <codeblock id="GUID-2B7683AF-E01F-5C7A-896B-E3E4F37FAF23" xml:space="preserve">Binding0=C32_MyCSYs:5,C32_Main:0,ECustom,42,42</codeblock> <p>And |
|
452 in the <b>[IniData]</b> section: </p> <codeblock id="GUID-A0AA8BA4-AA45-5FAE-95D4-24764695F04B" xml:space="preserve">[IniData] |
|
453 # Make sure Role is set to "Player" |
|
454 Role=Player</codeblock> <p>Change the <b>WorkerId</b>, for example from <codeph>WorkerId=4</codeph> to </p> <codeblock id="GUID-D334F3C3-38B7-578F-8E9C-2C4FBBB05C06" xml:space="preserve">WorkerId=5</codeblock> <p>and |
|
455 change the <b>CSYList</b> to specify your CSYs, e.g. change "CSYList=XX,YY,zz" |
|
456 to </p> <codeblock id="GUID-9AAAD2C9-A0D0-5733-8EFC-1CB848DB8785" xml:space="preserve">CSYList=MyCSY1,MyCSY2</codeblock> </section> |
|
457 <section id="GUID-5A5FEA44-F43B-51BE-9736-7FC76901DB02"><title>Typical Thread |
|
458 Configuration Examples</title> <p>This section describes the three broad configurations |
|
459 for threading available for the C32 Serial Server. Each has different potential |
|
460 effects on the performance of C32. </p> <p>The three broad configurations |
|
461 available, with a summary of their costs and benefits, are detailed in the |
|
462 following table: </p> <table id="GUID-5552EBC6-3387-59E6-85AC-9585F31C6ABB"> |
|
463 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
464 <thead> |
|
465 <row> |
|
466 <entry/> |
|
467 <entry>Configuration</entry> |
|
468 <entry>Advantages</entry> |
|
469 <entry>Disadvantages</entry> |
|
470 </row> |
|
471 </thead> |
|
472 <tbody> |
|
473 <row> |
|
474 <entry><p>1</p> </entry> |
|
475 <entry><p>Run all CSYs outside the main thread <b>[Default supplied CMI set]</b> </p> </entry> |
|
476 <entry><ul> |
|
477 <li id="GUID-3BD88C6F-9C4E-5001-B7D1-2A9DC3BBE649"><p>Some CSYs can be promoted |
|
478 ahead of others using thread priorities </p> </li> |
|
479 <li id="GUID-1C1C0DF2-5EED-5AE4-820A-B3020AF66AE6"><p>Main thread cannot ever |
|
480 stall when any CSY stalls </p> </li> |
|
481 <li id="GUID-F4331549-9283-5E78-AEE1-32C4CF0F11E3"><p>Stackable CSYs are possible: |
|
482 a CSY can connect to another CSY through the C32 API as long as both are in |
|
483 different threads </p> </li> |
|
484 </ul> </entry> |
|
485 <entry><ul> |
|
486 <li id="GUID-898ED70D-CCB3-5D56-A9A9-49C19BC3C5DC"><p>Operations on CSYs are |
|
487 a bit slower due to increased overhead of inter-thread communication </p> </li> |
|
488 <li id="GUID-DA120612-E01B-51A4-8B77-F582D8170318"><p>Complex to debug </p> </li> |
|
489 </ul> </entry> |
|
490 </row> |
|
491 <row> |
|
492 <entry><p>2</p> </entry> |
|
493 <entry><p>Run some CSYs in the main thread </p> </entry> |
|
494 <entry><ul> |
|
495 <li id="GUID-70EFC61A-5D52-55D1-B364-096F84D0EBDF"><p>CSYs in the main thread |
|
496 avoid the overhead of inter-thread communication </p> </li> |
|
497 <li id="GUID-63D0CE88-5B6D-5787-A2B4-936B48D16FB2"><p>Some CSYs can be promoted |
|
498 ahead of others using thread priorities </p> </li> |
|
499 <li id="GUID-71641750-5882-53FC-9B40-0421050E5355"><p>Main thread cannot stall |
|
500 when a CSY in a separate thread stalls </p> </li> |
|
501 <li id="GUID-88EEE21E-42CF-5401-B985-427E7B3641E9"><p>Stackable CSYs are possible: |
|
502 a CSY can connect to another CSY through the C32 API as long as both are in |
|
503 different threads </p> </li> |
|
504 </ul> </entry> |
|
505 <entry><ul> |
|
506 <li id="GUID-70FDC4C2-FACB-592F-AA96-9C3F980FA842"><p>If any CSY in the main |
|
507 thread stalls, the whole server stalls </p> </li> |
|
508 <li id="GUID-E5F158D5-4720-5869-9B67-7FC3001B75F2"><p>No means to prioritise |
|
509 one CSY ahead of others (without changing the CSY code) </p> </li> |
|
510 <li id="GUID-A773FE9F-AC77-59B0-AECB-FB5C8174583C"><p>Operations on CSYs outside |
|
511 the main thread are a bit slower due to the increased overhead of inter-thread |
|
512 communication </p> </li> |
|
513 <li id="GUID-C0505A00-C777-582A-8B98-C1E53AC094B7"><p>Complex to debug </p> </li> |
|
514 </ul> </entry> |
|
515 </row> |
|
516 <row> |
|
517 <entry><p>3</p> </entry> |
|
518 <entry><p>Run all CSYs in the main thread <b>[Default configuration when any |
|
519 CMI files are corrupt]</b> </p> </entry> |
|
520 <entry><ul> |
|
521 <li id="GUID-537C35E5-041E-5BDC-9298-26F89CE5E51F"><p>Simplest to debug since |
|
522 no inter-thread communication </p> </li> |
|
523 <li id="GUID-EFDEEA79-10D8-5FBF-B630-268F14362C0D"><p>All CSYs avoid the overhead |
|
524 of inter-thread communication </p> </li> |
|
525 </ul> </entry> |
|
526 <entry><ul> |
|
527 <li id="GUID-F0C2BD50-CFAD-5E99-AFDF-65BF96B5BB67"><p>If any CSY stalls, the |
|
528 whole server stalls </p> </li> |
|
529 <li id="GUID-83EDBE8F-17BD-514A-B0D5-5A6020A8DF56"><p>No means to prioritise |
|
530 one CSY ahead of others (without changing the CSY code) </p> </li> |
|
531 <li id="GUID-BE4157B4-0D0D-5520-8E85-A6C4755410B3"><p>No stackable CSYs are |
|
532 possible </p> </li> |
|
533 </ul> </entry> |
|
534 </row> |
|
535 </tbody> |
|
536 </tgroup> |
|
537 </table> <p>The default set of CMI files supplied with Symbian platform |
|
538 is based on the first broad configuration since it was decided that the small |
|
539 cost of running all CSYs outside the main thread is justified by the increased |
|
540 reliability to the whole C32 system of ensuring no CSY can deny service to |
|
541 the C32 server. Each of these configurations is explained in more detail below. </p> <fig id="GUID-BC275667-5D19-56CA-ABD9-68265A852282"> |
|
542 <title> Figure 1 - No CSYs in main thread: RootServer with 4 |
|
543 C32 CPMs </title> |
|
544 <image href="GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e124112_href.png" placement="inline"/> |
|
545 </fig> <p>Referring to Figure 1, the following can be observed: </p> <ol id="GUID-DA3BC841-1BE9-5483-8EC0-7BA479D85C14"> |
|
546 <li id="GUID-EAD7752C-A094-51CA-903C-52DCF2AB5353"><p>The Main Thread has <codeph>WorkerId=0</codeph>, |
|
547 Role as Dealer and is configured to load no CSY </p> </li> |
|
548 <li id="GUID-CE4A7176-2BD6-5149-B24A-45DCD0945C76"><p>The Player Thread 1 |
|
549 has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load |
|
550 ECACM CSY </p> </li> |
|
551 <li id="GUID-A327174B-CA1A-5AD8-92E9-9895363D7851"><p>The Player Thread 2 |
|
552 has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load |
|
553 ECUART CSY </p> </li> |
|
554 <li id="GUID-6015DA12-C259-5B9F-9D72-CFF86AA91435"><p>The Player Thread 3 |
|
555 has <codeph>WorkerId=3</codeph>, Role as Player and is configured to load <i>unlisted</i> csy. |
|
556 What unlisted csy means here is that apart from ECACM and ECUART, if any new |
|
557 csy is to be loaded, it will get loaded in this thread. </p> </li> |
|
558 </ol> <p>The <b>[IniData]</b> section for the above CPMs would look like: </p> <codeblock id="GUID-CE1D7541-5103-5E9B-A20A-11A6C17ABFCA" xml:space="preserve">[IniData] |
|
559 Role=Dealer |
|
560 WorkerId=0 |
|
561 </codeblock> <codeblock id="GUID-51C4FC4E-1F85-59D3-9F9D-FC6868042363" xml:space="preserve">[IniData] |
|
562 Role=Player |
|
563 WorkerId=1 |
|
564 CSYList=ECACM |
|
565 </codeblock> <codeblock id="GUID-F21BBEC3-482A-59C4-BBE7-9B304F07EDB3" xml:space="preserve">[IniData] |
|
566 Role=Player |
|
567 WorkerId=2 |
|
568 CSYList=ECUART |
|
569 </codeblock> <codeblock id="GUID-74C70C5D-2B37-5AF8-B703-4072610C6C3E" xml:space="preserve">[IniData] |
|
570 Role=Player |
|
571 WorkerId=3 |
|
572 CSYList=* |
|
573 </codeblock> <fig id="GUID-92921AF5-D056-52A9-B10E-80760DE9CD2F"> |
|
574 <title> Figure 2 - All CSYs in main thread: RootServer with single |
|
575 C32 CPM </title> |
|
576 <image href="GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e124179_href.png" placement="inline"/> |
|
577 </fig> <p>In Figure 2 the CPM loads any CSYs, and so should contain <codeph>CSYList</codeph> tag |
|
578 in the IniData section. </p> <p>The Main Thread has <codeph>WorkerId=0</codeph>, |
|
579 Role as Dealer and is configured to load <i>any</i> CSY. In this configuration |
|
580 since it is a single thread, all the CSYs will be loaded in the same thread. </p> <p>The <b>[IniData]</b> section |
|
581 for above CPM would look like: </p> <codeblock id="GUID-BCDEB67F-85D0-560A-AC5B-7D05B807B857" xml:space="preserve">[IniData] |
|
582 Role=Dealer |
|
583 WorkerId=0 |
|
584 CSYList=* |
|
585 </codeblock> <fig id="GUID-8F658644-2E07-53A3-A003-C1F015E1396B"> |
|
586 <title> Figure 3 - Some CSYs in main thread: RootServer with |
|
587 3 CPMs </title> |
|
588 <image href="GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e124211_href.png" placement="inline"/> |
|
589 </fig> <p>From Figure 3, the following can be observed. </p> <ol id="GUID-E945237B-900A-588A-A3FF-C0B75A43BB4A"> |
|
590 <li id="GUID-0A3CEB52-2C0F-5BB9-A271-756F9F374111"><p>The Main Thread has <codeph>WorkerId=0</codeph>, |
|
591 Role as Dealer and is configured to load HSDPA csy </p> </li> |
|
592 <li id="GUID-34EF4E58-A6DB-5EFB-8C13-EE8064A7E3F7"><p>The Player Thread 1 |
|
593 has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load |
|
594 ECACM csy </p> </li> |
|
595 <li id="GUID-BFF9FDF7-C714-5D0A-B8B3-DC4CCB2EC8FB"><p>The Player Thread 2 |
|
596 has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load |
|
597 an unlisted csy </p> </li> |
|
598 </ol> <p>The IniData section for above CPMs would look like: </p> <codeblock id="GUID-E5A77235-60E5-526D-A95C-750FCDCA96BE" xml:space="preserve">[IniData] |
|
599 Role=Dealer |
|
600 WorkerId=0 |
|
601 CSYList=HSDPA |
|
602 </codeblock> <codeblock id="GUID-ED3EE5DE-65C4-50CB-AEA1-59D89FBC0EF3" xml:space="preserve">[IniData] |
|
603 Role=Player |
|
604 WorkerId=1 |
|
605 CSYList=ECACM</codeblock> <codeblock id="GUID-00F4F479-B153-5F05-8E13-D2276D70B605" xml:space="preserve">[IniData] |
|
606 Role=Player |
|
607 WorkerId=2 |
|
608 CSYList=*</codeblock> </section> |
|
609 <section id="GUID-6350761E-18F6-53B7-98F8-C6E2EB5DA942"><title>Footnotes</title> <dl> |
|
610 <dlentry> |
|
611 <dt><b>Footnote 1</b> </dt> |
|
612 <dd><p>In theory the C32 main thread (<codeph>Workerid=0</codeph>) could be |
|
613 marked as on-demand and started by the first client to connect to it. This |
|
614 might be useful since it would save device boot time for a device that does |
|
615 not need serial comms as part of boot up. The process would require the client |
|
616 to connect to Configurator and load the C32 main module explicitly. For this |
|
617 to work the main Module’s name would have to be fixed (the reference system |
|
618 uses “<codeph>C32_Main</codeph> ”) so that the client can identify it to Configurator |
|
619 - which is not a big problem, and the client would need the appropriate capabilities |
|
620 (also not a big problem as the client could well be inside Rootserver too). |
|
621 The other problem is that making it on-demand requires that it is still started |
|
622 by a priviledged process before any unpriviledged process attempts to use |
|
623 the C32 API (since this will fail unless no CSYs require any capabilities). |
|
624 Therefore, for on-demand main thread-loading to work, intimate details about |
|
625 the specific configuration of CSYs for a device and their potential clients |
|
626 would be needed. </p> </dd> |
|
627 </dlentry> |
|
628 </dl> </section> |
|
629 </conbody></concept> |