--- a/Symbian3/SDK/Source/GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita	Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -1,629 +1,629 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License 
-"Eclipse Public License v1.0" which accompanies this distribution, 
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
-    Nokia Corporation - initial contribution.
-Contributors: 
--->
-<!DOCTYPE concept
-  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566" xml:lang="en"><title>How
-to Configure Multithreaded C32 Serial Comms: Tutorial</title><abstract><shortdesc>This page describes how a device manufacturer can configure
-the grouping of CSYs into various threads. </shortdesc> <p>The Serial Server
-on Symbian platform supports the use of multiple threads in order to separate
-the serial plug-in CSY modules. The first section provides a brief migration
-guide, while the subsequent sections provide more detail on the specific parameters
-and behaviour, and other advanced information. </p> </abstract><prolog><metadata><keywords/></metadata></prolog><conbody>
-
-<section id="GUID-4109EB99-A9A8-597B-BF42-89CF6AD7DB73"><title>Introduction</title> <p>The
-Comms Configurator (<codeph>c32start</codeph>) uses a configuration Comms
-Module Ini file (.CMI) to load Comms Provider Modules (CPMs) into the Rootserver
-process. Each CMI file represents exactly one CPM loaded inside Rootserver.
-CPMs are the name given to threads running inside the Rootserver process,
-since they extend the thread concept by adding a wrapper of extra information
-and functionality used to manage the threads. </p> <p>The Comms Configurator
-searches for the CMI files in the <codeph>\private\101f7988</codeph> folders
-by searching from Y: to A: and then Z:. The folder <filepath>101f7988</filepath> is
-the secure area for the Comms Configurator process and its name derives from
-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
-copied to any other drive but only read in-place. Thus, a later configuration
-of CMI files installed on another media/drive other than the ROM drive can
-be used to override the original ROM configuration. The Configurator reads
-these files only once during boot so any further changes will not take effect
-until the next system boot. </p> </section>
-<section id="GUID-B742D7C6-ACA3-40CD-8D2D-B8E8AB4F1885"><title>Quick Migration Guide</title> <p>This section provides a brief
-description of how to migrate a configuration from the old single-threaded
-C32 Serial Server to the new multi-threaded server. As there are numerous
-potential configurations with the multi-threaded server, this migration guide
-should be used as a first step to getting any old settings migrated over and
-thus allowing the server to continue working after an upgrade of Symbian platform. </p> <p>Once
-migrated, the other sections in this article provide further useful information
-regarding configuring CMI files for better performance in line with the requirements
-of the particular device. </p> <p>The quick migration involves two steps: </p> <ul>
-<li id="GUID-07F882AE-797F-5326-A4C3-DC596F3BC888"><p>apply any special configuration
-used with the previous single-threaded C32 Serial Server to the new configuration
-files supplied with the multi-threaded server </p> </li>
-<li id="GUID-423E4236-73EA-51CA-B9E3-03761078DF86"><p>adjust the default set
-of configuration files supplied with the multi-threaded server to suit the
-particular serial plug-ins in use </p> </li>
-</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
-was controlled by a single configuration file called (by default) <filepath>c32.cmi</filepath>,
-located in <filepath>\private\101f7988</filepath>. A default version of this
-file shipped with Symbian platform, although a device manufacturer could change
-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
-
-[Loader]
-Name=CCommServer
-FileName=c32.dll
-ThreadFunctionOrdinal=87
-IsServer=1
-IsSticky=1
-Priority=EPriorityMuchMore
-StackSize=8192
-ScaledStartupState=0x1085
-HeapOption=EDefaultHeap
-MinHeapSize=256
-MaxHeapSize=524288
-SystemCritical=1</codeblock> <p>The multi-threaded C32 Serial Server (C32MT)
-ships by default with five configuration files, since by default it supports
-five different threads. These configuration files are: </p> <codeblock id="GUID-AE8071D9-1ECD-58EF-AC33-713B42EDB7F8" xml:space="preserve">\private\101f7988\c32.cmi
-\private\101f7988\c32_first.cmi
-\private\101f7988\c32_second.cmi
-\private\101f7988\c32_third.cmi
-\private\101f7988\c32_fourth.cmi</codeblock> <p>They are an extended version
-of the original CMI file that shipped with the single-threaded C32. For example,
-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
-
-[Loader]
-Name=C32_Main
-FileName=c32.dll
-ThreadFunctionOrdinal=87
-IsSticky=0
-IsServer=1
-Priority=EPriorityMuchMore
-StackSize=16384
-ScaledStartupState=0x1085
-HeapOption=ENewHeap
-MinHeapSize=256
-MaxHeapSize=524288
-SystemCritical=1
-Group=C32SerComms
-OnDemand=0
-# Don't check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
-ControlFlags=4
-[IniData]
-Role=Dealer
-WorkerId=0</codeblock> <p>The first step in migrating is to ensure that any
-unique configuration used with the old server is migrated across to the new
-server. The particular parameters that should be considered in this procedure
-are: </p> <codeblock id="GUID-8E2C24C0-8770-57CD-8064-5D85F4096DAE" xml:space="preserve">Priority
-StackSize
-ScaledStartupState
-MinHeapSize
-MaxHeapSize
-SystemCritical</codeblock> <p>These parameters would need migrating to each
-of the five new CMI files. The following notes relate to deliberate changes
-to parameter values between the single and multi-threaded servers: </p> <dl>
-<dlentry>
-<dt><b>HeapOption</b> </dt>
-<dd><p>The value of <codeph>HeapOption</codeph> is different between the old
-and new files - this was made to aid in debugging the new multi-threaded server
-by separating its memory from the rest of the comms system. It can be safely
-changed back if desired. </p> </dd>
-</dlentry>
-<dlentry>
-<dt><b>IsSticky</b> </dt>
-<dd><p>The value of <codeph>IsSticky</codeph> has changed from 1 to 0. The <codeph>IsSticky</codeph> parameter
-is normally unused in a production system for the Serial Server since the
-server runs as a <codeph>SystemCritical</codeph> thread and thus cannot be
-shutdown and, if it panics, the phone would reboot. The change was made to
-facilitate testing, since in a test environment the Serial Server can be shutdown,
-and to facilitate this the value of <codeph>IsSticky</codeph> must be set
-to 0. </p> </dd>
-</dlentry>
-<dlentry>
-<dt><b>StackSize</b> </dt>
-<dd><p>The value of <codeph>StackSize</codeph> has increased from 8192 for
-the single-threaded C32 to 16384 for C32MT. This change is due to the increased
-stack usage of the multi-threaded C32. The value used - 16384 - was based
-on the value proven to work with the similar ESock multi-threaded server.
-It is possible that this value could be trimmed back towards 8192 to save
-memory depending on the CSYs being used, since the ECUART CSY has been tested
-to work with the multi-threaded C32 server with a stack size of just 8192,
-and CSYs are usually much less memory-demanding than the protocols being used
-in ESock. </p> </dd>
-</dlentry>
-</dl> <p><b>Assigning
-CSY plug-ins to threads</b> </p> <p>The second part of migration to the new
-multi-threaded serial server is to alter the default set of CMI files to match
-the plug-ins (CSYs) in use and the desired operation. This step is not mandatory
-since by default C32 will load all plug-ins correctly. But, it is worth considering
-at this stage whether the default configuration needs some changes to match
-the requirements of the device. </p> <p>There are three broad configurations
-available, which are defined by whether one or more CSYs are run in the main
-thread for efficiency. The default configuration supplied with Symbian platform
-runs all the CSYs outside the main thread since this ensures that no CSY can
-deny service to the main server thread. It is expected that this configuration
-will suit most situations, but for more information on the other configurations,
-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
-Thread Configuration Examples</xref>. </p> <p>As mentioned earlier, the default
-configuration uses five threads. The description for each of these is given
-in the following table: </p> <table id="GUID-0F03B8CD-0142-595A-874F-A35C80F8C991">
-<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
-<thead>
-<row>
-<entry>Worker ID</entry>
-<entry>Summary</entry>
-<entry>CMI file</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p>0</p> </entry>
-<entry><p>Main thread </p> </entry>
-<entry><p> <filepath>c32.cmi</filepath>  </p> </entry>
-<entry><p>Runs the serial server to service client requests and pass on to
-the CSYs, possibly in other threads. This thread is expected to be started
-at device boot. </p> </entry>
-</row>
-<row>
-<entry><p>1</p> </entry>
-<entry><p>USB thread </p> </entry>
-<entry><p> <filepath>c32_first.cmi</filepath>  </p> </entry>
-<entry><p>Runs the USB CSY (ECACM). This is separated from all other threads
-so that USB can run at high-speed uninterrupted. This thread is only started
-when a client requires a USB connection. </p> </entry>
-</row>
-<row>
-<entry><p>2</p> </entry>
-<entry><p>Baseband thread </p> </entry>
-<entry><p> <filepath>c32_second.cmi</filepath>  </p> </entry>
-<entry><p>Runs the RS232 CSY (ECUART). This thread runs the ECUART plug-in
-separately since ECUART is sometimes used to connect to the baseband. If a
-different CSY is being used to connect to the baseband, it can be added to
-this CMI file and ECUART either moved to another thread, or removed altogether.
-As the baseband requires a high speed and fast response time, it is recommended
-that the baseband CSY should be run in this thread to separate it from all
-other CSYs. This thread is only started when a client requires the CSY. </p> </entry>
-</row>
-<row>
-<entry><p>3</p> </entry>
-<entry><p>Bluetooth and IrDA thread </p> </entry>
-<entry><p> <filepath>c32_third.cmi</filepath>  </p> </entry>
-<entry><p>Runs the Bluetooth and IrDA CSYs. These CSYs usually do not have
-high requirements for throughput or response and thus can run together. This
-thread is only started when one of its CSYs is required by a client. </p> </entry>
-</row>
-<row>
-<entry><p>4</p> </entry>
-<entry><p>Default thread </p> </entry>
-<entry><p> <filepath>c32_fourth.cmi</filepath>  </p> </entry>
-<entry><p>Runs any unlisted CSYs. If C32 is asked to load a CSY for which
-no thread has been identified in a CMI file, then C32 will load the CSY in
-this thread. This thread is only started when required. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>For a particular device, the above configuration may need to be
-changed to address the requirements of the device. Typical adjustments to
-consider are: </p> <ol id="GUID-FB351652-6FBA-5176-9C51-AAC40752C333">
-<li id="GUID-EA20A49C-FB32-5BC6-B47A-24F0487F65FD"><p>Change the CSY name
-for Worker ID 2 to match the baseband CSY, and then either move ECUART to
-Worker ID 3 or into its own new thread, or don't add it to any CMI file if
-the device doesn't use the ECUART CSY </p> </li>
-<li id="GUID-E08331AD-4AEA-5CAA-8C28-8B3001E1FAEC"><p>Add any extra low-performance
-CSYs to Worker ID 3 so that they run together with Bluetooth and IrDA. Extra
-CSYs could be run in a new separate thread but there is a memory cost for
-each new thread added so this should be considered (8K is typically allocated
-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,
-thread, stack and memory useful information</xref>, and there is a limit to
-the number of threads with their own heaps that can be started in the Root
-Server). </p> </li>
-<li id="GUID-45D296E1-654C-5181-A38E-4D0AFC23A4A6"><p>For any extra high-performance
-CSYs, create a new CMI file so that these can run separately from the other
-CSYs. See <xref href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita#GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566/GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D">Creating
-A New CMI</xref> below </p> </li>
-<li id="GUID-BC119A2C-445A-5EF7-92DF-17D7E28A1A3B"><p>Prioritise important
-threads (or reduce the priority of lesser threads). Candidates for increased
-priority would be the Main, USB and Baseband threads. Care should be taken
-when adjusting thread priorities since these affect the whole Comms system
-- more guidance on setting thread priorities is available in the document <i>How
-To Assign Thread Priorities</i> elsewhere in this developer library. </p> </li>
-</ol> <p>When making these adjustments note that there is no cost involved
-with mentioning CSYs that may never be loaded. </p> </section>
-<section id="GUID-E7F95EA1-D91D-4623-B163-8BE198CC991C"><title>Overview of the C32 multi-threaded CMI files</title> <p>C32
-Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading.
-The <b>Dealer</b> is the main C32 Comms Provider Module (CPM) which runs the
-C32 server; a Player is a C32 CPM that only runs one or more CSYs and takes
-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]
-Name=C32_Main
-FileName=c32.dll
-ThreadFunctionOrdinal=87
-IsServer=1
-IsSticky=0
-ThreadPriority=EPriorityMuchMore
-StackSize=16384
-ScaledStartupState=0x1085
-HeapOption=ENewHeap
-MinHeapSize=256
-MaxHeapSize=524288
-SystemCritical=1
-Group=C32SerComms
-OnDemand=0
-[IniData]
-Role=Dealer
-WorkerId=0
-</codeblock> <p>The <xref href="GUID-83297976-F146-3B82-BE1C-C1E8F8B9DEE5.dita"><apiname>ThreadFunctionOrdinal</apiname></xref> identifier must
-refer to the correct ordinal number of the main thread function for the DLL
-file containing the Comms Provider Module. Due to binary compatibility considerations
-this must be placed at ordinal "87" in the export table. A Comms Provider
-Module/CPM is essentially a thread managed by the Comms Configurator. </p> <p>The
-description of each of the settings under <codeph>[Loader]</codeph> that are
-specific to C32 and the settings under <codeph>[IniData]</codeph> are described
-in further detail below. </p> <p>As well as the C32 server thread, any other
-CPMs that C32 needs must also have their own CMI file. One such example file
-is: </p> <p> <b>C32_Default.cmi</b>  </p> <codeblock id="GUID-7E488DEF-535C-5C13-9DEA-246B11DF39E4" xml:space="preserve">[Loader]
-Name=C32_Default
-FileName=c32.dll
-ThreadFunctionOrdinal=87
-IsServer=1
-IsSticky=0
-ThreadPriority=EPriorityMuchMore
-StackSize=16384
-ScaledStartupState=0x3040
-HeapOption=EShareHeap
-SharedHeapName=C32_Main
-MinHeapSize=256
-MaxHeapSize=524288
-SystemCritical=0
-Group=C32SerComms
-OnDemand=1
-Binding0=C32_Default:4,C32_Main:0,ECustom,42,42
-[IniData]
-Role=Player
-WorkerId=4
-CSYList=*</codeblock> </section>
-<section id="GUID-AEEFD832-108E-5CC2-AD5D-5CF6414CA720"><title>C32 CMI Parameter
-Descriptions</title> <p>This section gives details about the parameters available
-in the CMI file relevant to C32. The CMI file has two sections - a <codeph>[Loader]</codeph> section
-and an <codeph>[IniData]</codeph> section. The <codeph>[Loader]</codeph> section
-parameters are defined for the CPM, and the ones relevant to C32MT are detailed
-below. The <codeph>[IniData]</codeph> section contains parameters specific
-to a CPM. If further information on the format of the CMI file itself or the <codeph>[Loader]</codeph> parameters
-is required, please refer to the document <i>Comms Process Starter/Config
-Design Document</i> section <i>3.1.1</i>. This document is located in this
-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
-CMI files at run-time, since they are designed to be configured for inclusion
-in a ROM and then not changed through the life of a phone product. After-market
-changing of the configuration is supported via the installation of CMI files
-in a non-ROM folder which then take precedence over the ROM files when the
-device is next rebooted. Thus, any CMI configuration file problems should
-become apparent during the early stages of phone development. </p> <p>A bad
-configuration will panic in debug builds to signal the user to change/edit
-the <codeph>.CMI</codeph> files in order to make a desired and correct configuration.
-In <codeph>urel</codeph> builds a bad configuration may survive (unless the <codeph>.CMI</codeph> files
-are very malformed) but at a cost that all CSYs are loaded in the Dealer Thread
-(<codeph>Workerid=0</codeph>) making it in effect a single threaded system. </p> <p>The
-panic numbers used by the C32 Serial Server for internal server faults are
-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
-of the Configurator’s CPM load on boot ("0"), or whether the CPM should only
-be loaded via an explicit request to Configurator ("1"). The default value
-is "0". The <codeph>OnDemand</codeph> parameter for the main thread can only
-be "0" if mentioned. For Player modules the setting can be either "0" or "1".
-If a Player thread is not marked as <codeph>OnDemand=1</codeph> then it will
-load during the boot sequence. If the main thread (<codeph>Workerid=0</codeph>)
-is marked as <codeph>OnDemand=1</codeph>, then this is a configuration error
-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
-1</xref> below). Players marked to load at boot up do not load any CSYs implicitly
-as part of the boot load. </p> <p>All Player modules for C32 must be marked
-with <codeph>OnDemand=1</codeph> since the C32 Dealer must instigate a Player
-load. If a Player thread is not marked as <codeph>OnDemand=0</codeph> then
-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.
-The actual Group ID for the C32 group is <codeph>C32SerComms</codeph>. CMI
-files for C32 Players that do not have a Group member will never be loaded
-by C32 (assuming <codeph>OnDemand=1</codeph> is set for the Player threads). </p> <p>If
-there is no group defined in any CMI files and therefore no <b>[IniData]</b> is
-processed for any of them, then C32 will simply assign all CSYs to load into
-the Dealer thread. </p> <p> <b>Name</b>  </p> <p>This parameter is used to
-identify the CPM to the Configurator and is used to name the thread for the
-kernel. It is stored by C32 for all CMI files in the C32SerComms group for
-use when requesting Configurator to load or unload a CPM. As this value is
-easily configurable and is used to name the thread to the kernel, software
-should not rely on the name of any C32 thread being any particular string.
-Prior to the multithreaded C32 (C32MT), the C32 thread was conventionally
-known as <codeph>CCommServer</codeph>. However, with C32 now potentially having
-a multiplicity of threads, other schemes are probable such as <codeph>C32_Main,
-C32_USB and C32_BaseBand</codeph> or <codeph>C32_BT-IR and              C32_Default</codeph>  </p> <p>The
-Dealer and all Players in the C32 group can have any name since C32 will find
-them as part of the same group (see Group above). The names in the C32 group
-should all be unique – if the same name is found twice or more C32 will panic
-in debug builds but attempt to recover in release builds by only processing
-the first that it finds. This is still a highly risky situation since if C32
-needs to start that module in order to accommodate a CSY, Configurator may
-load the wrong CMI file when creating the new thread. </p> <p>When introducing
-new CMIs, care should be taken to change the <codeph>BindingN</codeph> line
-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
-C32 has a CMI file that loads the C32 binary during boot up, but the CMI file
-does not have an <codeph>[IniData]</codeph> section, C32 will assume that
-this CMI is for the main thread and that the CMI is a pre-C32MT file. However,
-for C32MT, this is an undesired configuration and should be rectified. Old
-versions of <codeph>c32.cmi</codeph> are only kept in the source distribution
-to support backwards compatibility and should not be used in a system which
-has C32MT present. In such backwards-compatible modes of C32MT, the main thread
-will host a Player in case no other CMI files are present. </p> <p> <b>Role</b>  </p> <p>The
-value for this parameter should be either <codeph>Dealer</codeph> or <codeph>Player</codeph>.
-Only one <codeph>Dealer</codeph> can exist in a C32 system, but there can
-be any number of <codeph>Player</codeph> s. If there are two or more <codeph>Dealer</codeph> CMI
-files, the <codeph>ScaledStartupState</codeph> determines which Dealer CMI
-starts first. If both the CMIs have the same <codeph>ScaledStartupState</codeph>,
-then they are loaded in alphabetical order. Configurator is guaranteed to
-start a C: CMI file before the Z: one. If they both have the same module name
-then it is safe since Rootserver will refuse the load of the second module
-with the same name failing with <codeph>KErrAlreadyExists</codeph>. However,
-if the module name is different Rootserver will load them both and C32 will
-detect that an instance of itself is already running and exit the second thread.
-Only the IniData for the CMI file that was used to start the Dealer will be
-processed, with all other Dealer CMI files being ignored. If the main thread
-is to include a co-resident Player, the iniData should include the <codeph>CSYList</codeph> key-value
-pair discussed below. </p> <p> <b>WorkerId</b>  </p> <p>The ID number of this
-thread inside the C32 system. The Id numbers should be a positive integer
-or "0" in the case of the main thread (In case CMI file of <codeph>WorkerId=0</codeph> has
-anything else than Dealer as role, it is overridden with Role=Dealer, logging
-a warning). The system expects subsequent ID numbers to be incremented up
-from the main thread's ID. Where a CMI file in the C32 group does not have
-a WorkerId, it is a bad configuration and will panic in debug builds. Allocating
-the next higher number is not possible as this Player needs to be bound with
-the Dealer using the <codeph>BindingN</codeph> line which accepts <codeph>WorkerId</codeph> parameter.
-In case of duplicate <codeph>WorkerId</codeph>, a panic occurs as the second
-module cannot be bound to the Dealer as the binding for the main thread has
-already been done. </p> <p> <b>CSYList</b>  </p> <p>A comma-separated list
-of the filenames of the CSYs this thread will own. All CMIs in the C32 group
-must have a CSY list, except for the Dealer which can optionally have a <codeph>CSYList</codeph>.
-A Player with no <codeph>CSYList</codeph> represents a bad configuration as
-a Player’s sole purpose is to load CSYs. Such a Player with no CSY list will
-never be started by C32. A Dealer with no CSY list will act purely as a Dealer.
-A Dealer with a CSY list becomes a Dealer with a co-resident Player inside
-its thread. <codeph>CSYList</codeph> param determines if the CPM will host
-a Player or not. </p> <p>If a CSY appears in more than one CMI file, then
-the CSY will be assigned to one thread, but not necessarily that with the
-least number of CSYs in it. </p> <p>The comma-separated list should not have
-any spaces or other white space in it, and each CSY name must be an alphanumeric
-string. The CSY name is not case sensitive, and should not have the <codeph>.CSY</codeph> extension.
-C32 does not check whether the supplied CSY names actually exist as binaries,
-since it only refers to the list when a client asks to load a particular CSY. </p> <p>If
-an asterix ("*") appears as a CSY name in the CSY list, this is inferred by
-C32 as meaning that this thread is also to be used to load any CSYs not mentioned
-in any CMI file, and is known as the <i>default</i> thread. If two different
-CMI files in the C32 group have the wildcard then only one CMI file will be
-marked as being the host for unknown CSYs – it is not defined as to which
-one. If no CMI file has a wildcard then C32 will assign the wildcard to an
-unused Player thread so that all unlisted CSYs are isolated into their own
-thread. This is overridden if the only CMI file is for the Dealer, in which
-case the Dealer will load all CSYs into its own co-resident Player, since
-the Dealer cannot request the Configurator to start a module for which there
-is not an associated CMI file. </p> </section>
-<section id="GUID-8E49AE8A-E940-52F3-ADA5-0332DA1D58D2"><title>Important Notes</title> <p>Field
-names in the <codeph>[IniData]</codeph> are case sensitive, but fields values
-are not. </p> <p>The <codeph>BindingN</codeph> line is responsible for binding
-the Player CPM with Dealer. If you leave out the <codeph>BindingN</codeph> line
-from the CMI then the new Player will in essence remain as an island and no
-requests for loading or any subsequent operation can be passed to it from
-Dealer. This will not result in a panic. </p> <p>The <codeph>C32_Main.cmi</codeph> doesn’t
-have a <codeph>BindingN</codeph> line since it is a Dealer and thus does not
-need to bind to another Dealer. </p> </section>
-<section id="GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D"><title>Creating A
-New CMI</title> <p>To create a new CMI file, copy an existing Player CMI file,
-rename it and change the necessary parameters as detailed below. The examples
-below assume that the base CMI used was the supplied <codeph>c32_fourth.cmi</codeph>.
-The following parameters need to be changed to make a valid configuration
-file: </p> <p>In <b>[Loader] </b> section are: </p> <ul>
-<li id="GUID-6C3E5830-9A7A-5D84-B4A5-FCA7FD66E31A"><p> <b>Name</b> - This
-is the module name of CPM. </p> </li>
-<li id="GUID-D5BDBEAC-A417-5D39-BB85-4E5AB9DDD36A"><p> <b>BindingN</b> - BindingN
-line is changed to reflect the new module name and <codeph>WorkerId</codeph> value </p> </li>
-</ul> <p>In<b> [IniData] </b> section: </p> <ul>
-<li id="GUID-3855C593-297D-5360-9926-0A1BFFAC3B12"><p> <b>WorkerId</b> - This
-value is numeric and must be unique </p> </li>
-<li id="GUID-EA091203-C0E9-5303-9FD5-924F3C67FB55"><p> <b>CSYList</b> - Contains
-CSYs which you want to load in this new CPM, separated by commas, no white
-spaces allowed. </p> </li>
-</ul> <p>Since the additional CMI being added is a <codeph>Player</codeph>,
-the Role field remains the same and it can not be changed to <codeph>Dealer</codeph> as
-the CPM with <codeph>WorkerId=0</codeph> is the one and only Dealer in the
-C32MT. </p> <codeblock id="GUID-8722A0B7-FB88-5516-846B-BCC4E11D0EEE" xml:space="preserve">[Loader]
-# Change the Name value to your CSY name
-Name=C32_Default  // </codeblock> <p>Change the <codeph>Name</codeph> value
-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
-ThreadFunctionOrdinal=87
-ThreadPriority=EPriorityMuchMore
-StackSize=16384
-ScaledStartupState=0x3040
-HeapOption=ENewHeap
-MinHeapSize=256
-MaxHeapSize=524288
-SystemCritical=1
-Group=C32SerComms
-OnDemand=1</codeblock> <p>Change the BindingN line to refer to your CSY, for
-example change from </p> <codeblock id="GUID-81BEFC33-67EE-5547-8C7C-E473F902F145" xml:space="preserve"># Change the BindingN line to refer to your CSYs
-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
-in the <b>[IniData]</b> section: </p> <codeblock id="GUID-A0AA8BA4-AA45-5FAE-95D4-24764695F04B" xml:space="preserve">[IniData]
-# Make sure Role is set to "Player"
-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
-change the <b>CSYList</b> to specify your CSYs, e.g. change "CSYList=XX,YY,zz"
-to </p> <codeblock id="GUID-9AAAD2C9-A0D0-5733-8EFC-1CB848DB8785" xml:space="preserve">CSYList=MyCSY1,MyCSY2</codeblock> </section>
-<section id="GUID-5A5FEA44-F43B-51BE-9736-7FC76901DB02"><title>Typical Thread
-Configuration Examples</title> <p>This section describes the three broad configurations
-for threading available for the C32 Serial Server. Each has different potential
-effects on the performance of C32. </p> <p>The three broad configurations
-available, with a summary of their costs and benefits, are detailed in the
-following table: </p> <table id="GUID-5552EBC6-3387-59E6-85AC-9585F31C6ABB">
-<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
-<thead>
-<row>
-<entry/>
-<entry>Configuration</entry>
-<entry>Advantages</entry>
-<entry>Disadvantages</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p>1</p> </entry>
-<entry><p>Run all CSYs outside the main thread <b>[Default supplied CMI set]</b>  </p> </entry>
-<entry><ul>
-<li id="GUID-3BD88C6F-9C4E-5001-B7D1-2A9DC3BBE649"><p>Some CSYs can be promoted
-ahead of others using thread priorities </p> </li>
-<li id="GUID-1C1C0DF2-5EED-5AE4-820A-B3020AF66AE6"><p>Main thread cannot ever
-stall when any CSY stalls </p> </li>
-<li id="GUID-F4331549-9283-5E78-AEE1-32C4CF0F11E3"><p>Stackable CSYs are possible:
-a CSY can connect to another CSY through the C32 API as long as both are in
-different threads </p> </li>
-</ul> </entry>
-<entry><ul>
-<li id="GUID-898ED70D-CCB3-5D56-A9A9-49C19BC3C5DC"><p>Operations on CSYs are
-a bit slower due to increased overhead of inter-thread communication </p> </li>
-<li id="GUID-DA120612-E01B-51A4-8B77-F582D8170318"><p>Complex to debug </p> </li>
-</ul> </entry>
-</row>
-<row>
-<entry><p>2</p> </entry>
-<entry><p>Run some CSYs in the main thread </p> </entry>
-<entry><ul>
-<li id="GUID-70EFC61A-5D52-55D1-B364-096F84D0EBDF"><p>CSYs in the main thread
-avoid the overhead of inter-thread communication </p> </li>
-<li id="GUID-63D0CE88-5B6D-5787-A2B4-936B48D16FB2"><p>Some CSYs can be promoted
-ahead of others using thread priorities </p> </li>
-<li id="GUID-71641750-5882-53FC-9B40-0421050E5355"><p>Main thread cannot stall
-when a CSY in a separate thread stalls </p> </li>
-<li id="GUID-88EEE21E-42CF-5401-B985-427E7B3641E9"><p>Stackable CSYs are possible:
-a CSY can connect to another CSY through the C32 API as long as both are in
-different threads </p> </li>
-</ul> </entry>
-<entry><ul>
-<li id="GUID-70FDC4C2-FACB-592F-AA96-9C3F980FA842"><p>If any CSY in the main
-thread stalls, the whole server stalls </p> </li>
-<li id="GUID-E5F158D5-4720-5869-9B67-7FC3001B75F2"><p>No means to prioritise
-one CSY ahead of others (without changing the CSY code) </p> </li>
-<li id="GUID-A773FE9F-AC77-59B0-AECB-FB5C8174583C"><p>Operations on CSYs outside
-the main thread are a bit slower due to the increased overhead of inter-thread
-communication </p> </li>
-<li id="GUID-C0505A00-C777-582A-8B98-C1E53AC094B7"><p>Complex to debug </p> </li>
-</ul> </entry>
-</row>
-<row>
-<entry><p>3</p> </entry>
-<entry><p>Run all CSYs in the main thread <b>[Default configuration when any
-CMI files are corrupt]</b>  </p> </entry>
-<entry><ul>
-<li id="GUID-537C35E5-041E-5BDC-9298-26F89CE5E51F"><p>Simplest to debug since
-no inter-thread communication </p> </li>
-<li id="GUID-EFDEEA79-10D8-5FBF-B630-268F14362C0D"><p>All CSYs avoid the overhead
-of inter-thread communication </p> </li>
-</ul> </entry>
-<entry><ul>
-<li id="GUID-F0C2BD50-CFAD-5E99-AFDF-65BF96B5BB67"><p>If any CSY stalls, the
-whole server stalls </p> </li>
-<li id="GUID-83EDBE8F-17BD-514A-B0D5-5A6020A8DF56"><p>No means to prioritise
-one CSY ahead of others (without changing the CSY code) </p> </li>
-<li id="GUID-BE4157B4-0D0D-5520-8E85-A6C4755410B3"><p>No stackable CSYs are
-possible </p> </li>
-</ul> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>The default set of CMI files supplied with Symbian platform
-is based on the first broad configuration since it was decided that the small
-cost of running all CSYs outside the main thread is justified by the increased
-reliability to the whole C32 system of ensuring no CSY can deny service to
-the C32 server. Each of these configurations is explained in more detail below. </p> <fig id="GUID-BC275667-5D19-56CA-ABD9-68265A852282">
-<title>              Figure 1 - No CSYs in main thread: RootServer with 4
-C32 CPMs            </title>
-<image href="GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e124112_href.png" placement="inline"/>
-</fig> <p>Referring to Figure 1, the following can be observed: </p> <ol id="GUID-DA3BC841-1BE9-5483-8EC0-7BA479D85C14">
-<li id="GUID-EAD7752C-A094-51CA-903C-52DCF2AB5353"><p>The Main Thread has <codeph>WorkerId=0</codeph>,
-Role as Dealer and is configured to load no CSY </p> </li>
-<li id="GUID-CE4A7176-2BD6-5149-B24A-45DCD0945C76"><p>The Player Thread 1
-has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load
-ECACM CSY </p> </li>
-<li id="GUID-A327174B-CA1A-5AD8-92E9-9895363D7851"><p>The Player Thread 2
-has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load
-ECUART CSY </p> </li>
-<li id="GUID-6015DA12-C259-5B9F-9D72-CFF86AA91435"><p>The Player Thread 3
-has <codeph>WorkerId=3</codeph>, Role as Player and is configured to load <i>unlisted</i> csy.
-What unlisted csy means here is that apart from ECACM and ECUART, if any new
-csy is to be loaded, it will get loaded in this thread. </p> </li>
-</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]
-Role=Dealer
-WorkerId=0
-</codeblock> <codeblock id="GUID-51C4FC4E-1F85-59D3-9F9D-FC6868042363" xml:space="preserve">[IniData]
-Role=Player
-WorkerId=1
-CSYList=ECACM
-</codeblock> <codeblock id="GUID-F21BBEC3-482A-59C4-BBE7-9B304F07EDB3" xml:space="preserve">[IniData]
-Role=Player
-WorkerId=2
-CSYList=ECUART
-</codeblock> <codeblock id="GUID-74C70C5D-2B37-5AF8-B703-4072610C6C3E" xml:space="preserve">[IniData]
-Role=Player
-WorkerId=3
-CSYList=*
-</codeblock> <fig id="GUID-92921AF5-D056-52A9-B10E-80760DE9CD2F">
-<title>              Figure 2 - All CSYs in main thread: RootServer with single
-C32 CPM            </title>
-<image href="GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e124179_href.png" placement="inline"/>
-</fig> <p>In Figure 2 the CPM loads any CSYs, and so should contain <codeph>CSYList</codeph> tag
-in the IniData section. </p> <p>The Main Thread has <codeph>WorkerId=0</codeph>,
-Role as Dealer and is configured to load <i>any</i> CSY. In this configuration
-since it is a single thread, all the CSYs will be loaded in the same thread. </p> <p>The <b>[IniData]</b> section
-for above CPM would look like: </p> <codeblock id="GUID-BCDEB67F-85D0-560A-AC5B-7D05B807B857" xml:space="preserve">[IniData]
-Role=Dealer
-WorkerId=0
-CSYList=*
-</codeblock> <fig id="GUID-8F658644-2E07-53A3-A003-C1F015E1396B">
-<title>                 Figure 3 - Some CSYs in main thread: RootServer with
-3 CPMs               </title>
-<image href="GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e124211_href.png" placement="inline"/>
-</fig> <p>From Figure 3, the following can be observed. </p> <ol id="GUID-E945237B-900A-588A-A3FF-C0B75A43BB4A">
-<li id="GUID-0A3CEB52-2C0F-5BB9-A271-756F9F374111"><p>The Main Thread has <codeph>WorkerId=0</codeph>,
-Role as Dealer and is configured to load HSDPA csy </p> </li>
-<li id="GUID-34EF4E58-A6DB-5EFB-8C13-EE8064A7E3F7"><p>The Player Thread 1
-has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load
-ECACM csy </p> </li>
-<li id="GUID-BFF9FDF7-C714-5D0A-B8B3-DC4CCB2EC8FB"><p>The Player Thread 2
-has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load
-an unlisted csy </p> </li>
-</ol> <p>The IniData section for above CPMs would look like: </p> <codeblock id="GUID-E5A77235-60E5-526D-A95C-750FCDCA96BE" xml:space="preserve">[IniData]
-Role=Dealer
-WorkerId=0
-CSYList=HSDPA
-</codeblock> <codeblock id="GUID-ED3EE5DE-65C4-50CB-AEA1-59D89FBC0EF3" xml:space="preserve">[IniData]
-Role=Player
-WorkerId=1
-CSYList=ECACM</codeblock> <codeblock id="GUID-00F4F479-B153-5F05-8E13-D2276D70B605" xml:space="preserve">[IniData]
-Role=Player
-WorkerId=2
-CSYList=*</codeblock> </section>
-<section id="GUID-6350761E-18F6-53B7-98F8-C6E2EB5DA942"><title>Footnotes</title> <dl>
-<dlentry>
-<dt><b>Footnote 1</b> </dt>
-<dd><p>In theory the C32 main thread (<codeph>Workerid=0</codeph>) could be
-marked as on-demand and started by the first client to connect to it. This
-might be useful since it would save device boot time for a device that does
-not need serial comms as part of boot up. The process would require the client
-to connect to Configurator and load the C32 main module explicitly. For this
-to work the main Module’s name would have to be fixed (the reference system
-uses “<codeph>C32_Main</codeph> ”) so that the client can identify it to Configurator
-- which is not a big problem, and the client would need the appropriate capabilities
-(also not a big problem as the client could well be inside Rootserver too).
-The other problem is that making it on-demand requires that it is still started
-by a priviledged process before any unpriviledged process attempts to use
-the C32 API (since this will fail unless no CSYs require any capabilities).
-Therefore, for on-demand main thread-loading to work, intimate details about
-the specific configuration of CSYs for a device and their potential clients
-would be needed. </p> </dd>
-</dlentry>
-</dl> </section>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566" xml:lang="en"><title>How
+to Configure Multithreaded C32 Serial Comms: Tutorial</title><abstract><shortdesc>This page describes how a device manufacturer can configure
+the grouping of CSYs into various threads. </shortdesc> <p>The Serial Server
+on Symbian platform supports the use of multiple threads in order to separate
+the serial plug-in CSY modules. The first section provides a brief migration
+guide, while the subsequent sections provide more detail on the specific parameters
+and behaviour, and other advanced information. </p> </abstract><prolog><metadata><keywords/></metadata></prolog><conbody>
+
+<section id="GUID-4109EB99-A9A8-597B-BF42-89CF6AD7DB73"><title>Introduction</title> <p>The
+Comms Configurator (<codeph>c32start</codeph>) uses a configuration Comms
+Module Ini file (.CMI) to load Comms Provider Modules (CPMs) into the Rootserver
+process. Each CMI file represents exactly one CPM loaded inside Rootserver.
+CPMs are the name given to threads running inside the Rootserver process,
+since they extend the thread concept by adding a wrapper of extra information
+and functionality used to manage the threads. </p> <p>The Comms Configurator
+searches for the CMI files in the <codeph>\private\101f7988</codeph> folders
+by searching from Y: to A: and then Z:. The folder <filepath>101f7988</filepath> is
+the secure area for the Comms Configurator process and its name derives from
+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
+copied to any other drive but only read in-place. Thus, a later configuration
+of CMI files installed on another media/drive other than the ROM drive can
+be used to override the original ROM configuration. The Configurator reads
+these files only once during boot so any further changes will not take effect
+until the next system boot. </p> </section>
+<section id="GUID-B742D7C6-ACA3-40CD-8D2D-B8E8AB4F1885"><title>Quick Migration Guide</title> <p>This section provides a brief
+description of how to migrate a configuration from the old single-threaded
+C32 Serial Server to the new multi-threaded server. As there are numerous
+potential configurations with the multi-threaded server, this migration guide
+should be used as a first step to getting any old settings migrated over and
+thus allowing the server to continue working after an upgrade of Symbian platform. </p> <p>Once
+migrated, the other sections in this article provide further useful information
+regarding configuring CMI files for better performance in line with the requirements
+of the particular device. </p> <p>The quick migration involves two steps: </p> <ul>
+<li id="GUID-07F882AE-797F-5326-A4C3-DC596F3BC888"><p>apply any special configuration
+used with the previous single-threaded C32 Serial Server to the new configuration
+files supplied with the multi-threaded server </p> </li>
+<li id="GUID-423E4236-73EA-51CA-B9E3-03761078DF86"><p>adjust the default set
+of configuration files supplied with the multi-threaded server to suit the
+particular serial plug-ins in use </p> </li>
+</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
+was controlled by a single configuration file called (by default) <filepath>c32.cmi</filepath>,
+located in <filepath>\private\101f7988</filepath>. A default version of this
+file shipped with Symbian platform, although a device manufacturer could change
+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
+
+[Loader]
+Name=CCommServer
+FileName=c32.dll
+ThreadFunctionOrdinal=87
+IsServer=1
+IsSticky=1
+Priority=EPriorityMuchMore
+StackSize=8192
+ScaledStartupState=0x1085
+HeapOption=EDefaultHeap
+MinHeapSize=256
+MaxHeapSize=524288
+SystemCritical=1</codeblock> <p>The multi-threaded C32 Serial Server (C32MT)
+ships by default with five configuration files, since by default it supports
+five different threads. These configuration files are: </p> <codeblock id="GUID-AE8071D9-1ECD-58EF-AC33-713B42EDB7F8" xml:space="preserve">\private\101f7988\c32.cmi
+\private\101f7988\c32_first.cmi
+\private\101f7988\c32_second.cmi
+\private\101f7988\c32_third.cmi
+\private\101f7988\c32_fourth.cmi</codeblock> <p>They are an extended version
+of the original CMI file that shipped with the single-threaded C32. For example,
+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
+
+[Loader]
+Name=C32_Main
+FileName=c32.dll
+ThreadFunctionOrdinal=87
+IsSticky=0
+IsServer=1
+Priority=EPriorityMuchMore
+StackSize=16384
+ScaledStartupState=0x1085
+HeapOption=ENewHeap
+MinHeapSize=256
+MaxHeapSize=524288
+SystemCritical=1
+Group=C32SerComms
+OnDemand=0
+# Don't check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
+ControlFlags=4
+[IniData]
+Role=Dealer
+WorkerId=0</codeblock> <p>The first step in migrating is to ensure that any
+unique configuration used with the old server is migrated across to the new
+server. The particular parameters that should be considered in this procedure
+are: </p> <codeblock id="GUID-8E2C24C0-8770-57CD-8064-5D85F4096DAE" xml:space="preserve">Priority
+StackSize
+ScaledStartupState
+MinHeapSize
+MaxHeapSize
+SystemCritical</codeblock> <p>These parameters would need migrating to each
+of the five new CMI files. The following notes relate to deliberate changes
+to parameter values between the single and multi-threaded servers: </p> <dl>
+<dlentry>
+<dt><b>HeapOption</b> </dt>
+<dd><p>The value of <codeph>HeapOption</codeph> is different between the old
+and new files - this was made to aid in debugging the new multi-threaded server
+by separating its memory from the rest of the comms system. It can be safely
+changed back if desired. </p> </dd>
+</dlentry>
+<dlentry>
+<dt><b>IsSticky</b> </dt>
+<dd><p>The value of <codeph>IsSticky</codeph> has changed from 1 to 0. The <codeph>IsSticky</codeph> parameter
+is normally unused in a production system for the Serial Server since the
+server runs as a <codeph>SystemCritical</codeph> thread and thus cannot be
+shutdown and, if it panics, the phone would reboot. The change was made to
+facilitate testing, since in a test environment the Serial Server can be shutdown,
+and to facilitate this the value of <codeph>IsSticky</codeph> must be set
+to 0. </p> </dd>
+</dlentry>
+<dlentry>
+<dt><b>StackSize</b> </dt>
+<dd><p>The value of <codeph>StackSize</codeph> has increased from 8192 for
+the single-threaded C32 to 16384 for C32MT. This change is due to the increased
+stack usage of the multi-threaded C32. The value used - 16384 - was based
+on the value proven to work with the similar ESock multi-threaded server.
+It is possible that this value could be trimmed back towards 8192 to save
+memory depending on the CSYs being used, since the ECUART CSY has been tested
+to work with the multi-threaded C32 server with a stack size of just 8192,
+and CSYs are usually much less memory-demanding than the protocols being used
+in ESock. </p> </dd>
+</dlentry>
+</dl> <p><b>Assigning
+CSY plug-ins to threads</b> </p> <p>The second part of migration to the new
+multi-threaded serial server is to alter the default set of CMI files to match
+the plug-ins (CSYs) in use and the desired operation. This step is not mandatory
+since by default C32 will load all plug-ins correctly. But, it is worth considering
+at this stage whether the default configuration needs some changes to match
+the requirements of the device. </p> <p>There are three broad configurations
+available, which are defined by whether one or more CSYs are run in the main
+thread for efficiency. The default configuration supplied with Symbian platform
+runs all the CSYs outside the main thread since this ensures that no CSY can
+deny service to the main server thread. It is expected that this configuration
+will suit most situations, but for more information on the other configurations,
+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
+Thread Configuration Examples</xref>. </p> <p>As mentioned earlier, the default
+configuration uses five threads. The description for each of these is given
+in the following table: </p> <table id="GUID-0F03B8CD-0142-595A-874F-A35C80F8C991">
+<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
+<thead>
+<row>
+<entry>Worker ID</entry>
+<entry>Summary</entry>
+<entry>CMI file</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p>0</p> </entry>
+<entry><p>Main thread </p> </entry>
+<entry><p> <filepath>c32.cmi</filepath>  </p> </entry>
+<entry><p>Runs the serial server to service client requests and pass on to
+the CSYs, possibly in other threads. This thread is expected to be started
+at device boot. </p> </entry>
+</row>
+<row>
+<entry><p>1</p> </entry>
+<entry><p>USB thread </p> </entry>
+<entry><p> <filepath>c32_first.cmi</filepath>  </p> </entry>
+<entry><p>Runs the USB CSY (ECACM). This is separated from all other threads
+so that USB can run at high-speed uninterrupted. This thread is only started
+when a client requires a USB connection. </p> </entry>
+</row>
+<row>
+<entry><p>2</p> </entry>
+<entry><p>Baseband thread </p> </entry>
+<entry><p> <filepath>c32_second.cmi</filepath>  </p> </entry>
+<entry><p>Runs the RS232 CSY (ECUART). This thread runs the ECUART plug-in
+separately since ECUART is sometimes used to connect to the baseband. If a
+different CSY is being used to connect to the baseband, it can be added to
+this CMI file and ECUART either moved to another thread, or removed altogether.
+As the baseband requires a high speed and fast response time, it is recommended
+that the baseband CSY should be run in this thread to separate it from all
+other CSYs. This thread is only started when a client requires the CSY. </p> </entry>
+</row>
+<row>
+<entry><p>3</p> </entry>
+<entry><p>Bluetooth and IrDA thread </p> </entry>
+<entry><p> <filepath>c32_third.cmi</filepath>  </p> </entry>
+<entry><p>Runs the Bluetooth and IrDA CSYs. These CSYs usually do not have
+high requirements for throughput or response and thus can run together. This
+thread is only started when one of its CSYs is required by a client. </p> </entry>
+</row>
+<row>
+<entry><p>4</p> </entry>
+<entry><p>Default thread </p> </entry>
+<entry><p> <filepath>c32_fourth.cmi</filepath>  </p> </entry>
+<entry><p>Runs any unlisted CSYs. If C32 is asked to load a CSY for which
+no thread has been identified in a CMI file, then C32 will load the CSY in
+this thread. This thread is only started when required. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>For a particular device, the above configuration may need to be
+changed to address the requirements of the device. Typical adjustments to
+consider are: </p> <ol id="GUID-FB351652-6FBA-5176-9C51-AAC40752C333">
+<li id="GUID-EA20A49C-FB32-5BC6-B47A-24F0487F65FD"><p>Change the CSY name
+for Worker ID 2 to match the baseband CSY, and then either move ECUART to
+Worker ID 3 or into its own new thread, or don't add it to any CMI file if
+the device doesn't use the ECUART CSY </p> </li>
+<li id="GUID-E08331AD-4AEA-5CAA-8C28-8B3001E1FAEC"><p>Add any extra low-performance
+CSYs to Worker ID 3 so that they run together with Bluetooth and IrDA. Extra
+CSYs could be run in a new separate thread but there is a memory cost for
+each new thread added so this should be considered (8K is typically allocated
+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,
+thread, stack and memory useful information</xref>, and there is a limit to
+the number of threads with their own heaps that can be started in the Root
+Server). </p> </li>
+<li id="GUID-45D296E1-654C-5181-A38E-4D0AFC23A4A6"><p>For any extra high-performance
+CSYs, create a new CMI file so that these can run separately from the other
+CSYs. See <xref href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita#GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566/GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D">Creating
+A New CMI</xref> below </p> </li>
+<li id="GUID-BC119A2C-445A-5EF7-92DF-17D7E28A1A3B"><p>Prioritise important
+threads (or reduce the priority of lesser threads). Candidates for increased
+priority would be the Main, USB and Baseband threads. Care should be taken
+when adjusting thread priorities since these affect the whole Comms system
+- more guidance on setting thread priorities is available in the document <i>How
+To Assign Thread Priorities</i> elsewhere in this developer library. </p> </li>
+</ol> <p>When making these adjustments note that there is no cost involved
+with mentioning CSYs that may never be loaded. </p> </section>
+<section id="GUID-E7F95EA1-D91D-4623-B163-8BE198CC991C"><title>Overview of the C32 multi-threaded CMI files</title> <p>C32
+Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading.
+The <b>Dealer</b> is the main C32 Comms Provider Module (CPM) which runs the
+C32 server; a Player is a C32 CPM that only runs one or more CSYs and takes
+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]
+Name=C32_Main
+FileName=c32.dll
+ThreadFunctionOrdinal=87
+IsServer=1
+IsSticky=0
+ThreadPriority=EPriorityMuchMore
+StackSize=16384
+ScaledStartupState=0x1085
+HeapOption=ENewHeap
+MinHeapSize=256
+MaxHeapSize=524288
+SystemCritical=1
+Group=C32SerComms
+OnDemand=0
+[IniData]
+Role=Dealer
+WorkerId=0
+</codeblock> <p>The <xref href="GUID-83297976-F146-3B82-BE1C-C1E8F8B9DEE5.dita"><apiname>ThreadFunctionOrdinal</apiname></xref> identifier must
+refer to the correct ordinal number of the main thread function for the DLL
+file containing the Comms Provider Module. Due to binary compatibility considerations
+this must be placed at ordinal "87" in the export table. A Comms Provider
+Module/CPM is essentially a thread managed by the Comms Configurator. </p> <p>The
+description of each of the settings under <codeph>[Loader]</codeph> that are
+specific to C32 and the settings under <codeph>[IniData]</codeph> are described
+in further detail below. </p> <p>As well as the C32 server thread, any other
+CPMs that C32 needs must also have their own CMI file. One such example file
+is: </p> <p> <b>C32_Default.cmi</b>  </p> <codeblock id="GUID-7E488DEF-535C-5C13-9DEA-246B11DF39E4" xml:space="preserve">[Loader]
+Name=C32_Default
+FileName=c32.dll
+ThreadFunctionOrdinal=87
+IsServer=1
+IsSticky=0
+ThreadPriority=EPriorityMuchMore
+StackSize=16384
+ScaledStartupState=0x3040
+HeapOption=EShareHeap
+SharedHeapName=C32_Main
+MinHeapSize=256
+MaxHeapSize=524288
+SystemCritical=0
+Group=C32SerComms
+OnDemand=1
+Binding0=C32_Default:4,C32_Main:0,ECustom,42,42
+[IniData]
+Role=Player
+WorkerId=4
+CSYList=*</codeblock> </section>
+<section id="GUID-AEEFD832-108E-5CC2-AD5D-5CF6414CA720"><title>C32 CMI Parameter
+Descriptions</title> <p>This section gives details about the parameters available
+in the CMI file relevant to C32. The CMI file has two sections - a <codeph>[Loader]</codeph> section
+and an <codeph>[IniData]</codeph> section. The <codeph>[Loader]</codeph> section
+parameters are defined for the CPM, and the ones relevant to C32MT are detailed
+below. The <codeph>[IniData]</codeph> section contains parameters specific
+to a CPM. If further information on the format of the CMI file itself or the <codeph>[Loader]</codeph> parameters
+is required, please refer to the document <i>Comms Process Starter/Config
+Design Document</i> section <i>3.1.1</i>. This document is located in this
+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
+CMI files at run-time, since they are designed to be configured for inclusion
+in a ROM and then not changed through the life of a phone product. After-market
+changing of the configuration is supported via the installation of CMI files
+in a non-ROM folder which then take precedence over the ROM files when the
+device is next rebooted. Thus, any CMI configuration file problems should
+become apparent during the early stages of phone development. </p> <p>A bad
+configuration will panic in debug builds to signal the user to change/edit
+the <codeph>.CMI</codeph> files in order to make a desired and correct configuration.
+In <codeph>urel</codeph> builds a bad configuration may survive (unless the <codeph>.CMI</codeph> files
+are very malformed) but at a cost that all CSYs are loaded in the Dealer Thread
+(<codeph>Workerid=0</codeph>) making it in effect a single threaded system. </p> <p>The
+panic numbers used by the C32 Serial Server for internal server faults are
+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
+of the Configurator’s CPM load on boot ("0"), or whether the CPM should only
+be loaded via an explicit request to Configurator ("1"). The default value
+is "0". The <codeph>OnDemand</codeph> parameter for the main thread can only
+be "0" if mentioned. For Player modules the setting can be either "0" or "1".
+If a Player thread is not marked as <codeph>OnDemand=1</codeph> then it will
+load during the boot sequence. If the main thread (<codeph>Workerid=0</codeph>)
+is marked as <codeph>OnDemand=1</codeph>, then this is a configuration error
+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
+1</xref> below). Players marked to load at boot up do not load any CSYs implicitly
+as part of the boot load. </p> <p>All Player modules for C32 must be marked
+with <codeph>OnDemand=1</codeph> since the C32 Dealer must instigate a Player
+load. If a Player thread is not marked as <codeph>OnDemand=0</codeph> then
+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.
+The actual Group ID for the C32 group is <codeph>C32SerComms</codeph>. CMI
+files for C32 Players that do not have a Group member will never be loaded
+by C32 (assuming <codeph>OnDemand=1</codeph> is set for the Player threads). </p> <p>If
+there is no group defined in any CMI files and therefore no <b>[IniData]</b> is
+processed for any of them, then C32 will simply assign all CSYs to load into
+the Dealer thread. </p> <p> <b>Name</b>  </p> <p>This parameter is used to
+identify the CPM to the Configurator and is used to name the thread for the
+kernel. It is stored by C32 for all CMI files in the C32SerComms group for
+use when requesting Configurator to load or unload a CPM. As this value is
+easily configurable and is used to name the thread to the kernel, software
+should not rely on the name of any C32 thread being any particular string.
+Prior to the multithreaded C32 (C32MT), the C32 thread was conventionally
+known as <codeph>CCommServer</codeph>. However, with C32 now potentially having
+a multiplicity of threads, other schemes are probable such as <codeph>C32_Main,
+C32_USB and C32_BaseBand</codeph> or <codeph>C32_BT-IR and              C32_Default</codeph>  </p> <p>The
+Dealer and all Players in the C32 group can have any name since C32 will find
+them as part of the same group (see Group above). The names in the C32 group
+should all be unique – if the same name is found twice or more C32 will panic
+in debug builds but attempt to recover in release builds by only processing
+the first that it finds. This is still a highly risky situation since if C32
+needs to start that module in order to accommodate a CSY, Configurator may
+load the wrong CMI file when creating the new thread. </p> <p>When introducing
+new CMIs, care should be taken to change the <codeph>BindingN</codeph> line
+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
+C32 has a CMI file that loads the C32 binary during boot up, but the CMI file
+does not have an <codeph>[IniData]</codeph> section, C32 will assume that
+this CMI is for the main thread and that the CMI is a pre-C32MT file. However,
+for C32MT, this is an undesired configuration and should be rectified. Old
+versions of <codeph>c32.cmi</codeph> are only kept in the source distribution
+to support backwards compatibility and should not be used in a system which
+has C32MT present. In such backwards-compatible modes of C32MT, the main thread
+will host a Player in case no other CMI files are present. </p> <p> <b>Role</b>  </p> <p>The
+value for this parameter should be either <codeph>Dealer</codeph> or <codeph>Player</codeph>.
+Only one <codeph>Dealer</codeph> can exist in a C32 system, but there can
+be any number of <codeph>Player</codeph> s. If there are two or more <codeph>Dealer</codeph> CMI
+files, the <codeph>ScaledStartupState</codeph> determines which Dealer CMI
+starts first. If both the CMIs have the same <codeph>ScaledStartupState</codeph>,
+then they are loaded in alphabetical order. Configurator is guaranteed to
+start a C: CMI file before the Z: one. If they both have the same module name
+then it is safe since Rootserver will refuse the load of the second module
+with the same name failing with <codeph>KErrAlreadyExists</codeph>. However,
+if the module name is different Rootserver will load them both and C32 will
+detect that an instance of itself is already running and exit the second thread.
+Only the IniData for the CMI file that was used to start the Dealer will be
+processed, with all other Dealer CMI files being ignored. If the main thread
+is to include a co-resident Player, the iniData should include the <codeph>CSYList</codeph> key-value
+pair discussed below. </p> <p> <b>WorkerId</b>  </p> <p>The ID number of this
+thread inside the C32 system. The Id numbers should be a positive integer
+or "0" in the case of the main thread (In case CMI file of <codeph>WorkerId=0</codeph> has
+anything else than Dealer as role, it is overridden with Role=Dealer, logging
+a warning). The system expects subsequent ID numbers to be incremented up
+from the main thread's ID. Where a CMI file in the C32 group does not have
+a WorkerId, it is a bad configuration and will panic in debug builds. Allocating
+the next higher number is not possible as this Player needs to be bound with
+the Dealer using the <codeph>BindingN</codeph> line which accepts <codeph>WorkerId</codeph> parameter.
+In case of duplicate <codeph>WorkerId</codeph>, a panic occurs as the second
+module cannot be bound to the Dealer as the binding for the main thread has
+already been done. </p> <p> <b>CSYList</b>  </p> <p>A comma-separated list
+of the filenames of the CSYs this thread will own. All CMIs in the C32 group
+must have a CSY list, except for the Dealer which can optionally have a <codeph>CSYList</codeph>.
+A Player with no <codeph>CSYList</codeph> represents a bad configuration as
+a Player’s sole purpose is to load CSYs. Such a Player with no CSY list will
+never be started by C32. A Dealer with no CSY list will act purely as a Dealer.
+A Dealer with a CSY list becomes a Dealer with a co-resident Player inside
+its thread. <codeph>CSYList</codeph> param determines if the CPM will host
+a Player or not. </p> <p>If a CSY appears in more than one CMI file, then
+the CSY will be assigned to one thread, but not necessarily that with the
+least number of CSYs in it. </p> <p>The comma-separated list should not have
+any spaces or other white space in it, and each CSY name must be an alphanumeric
+string. The CSY name is not case sensitive, and should not have the <codeph>.CSY</codeph> extension.
+C32 does not check whether the supplied CSY names actually exist as binaries,
+since it only refers to the list when a client asks to load a particular CSY. </p> <p>If
+an asterix ("*") appears as a CSY name in the CSY list, this is inferred by
+C32 as meaning that this thread is also to be used to load any CSYs not mentioned
+in any CMI file, and is known as the <i>default</i> thread. If two different
+CMI files in the C32 group have the wildcard then only one CMI file will be
+marked as being the host for unknown CSYs – it is not defined as to which
+one. If no CMI file has a wildcard then C32 will assign the wildcard to an
+unused Player thread so that all unlisted CSYs are isolated into their own
+thread. This is overridden if the only CMI file is for the Dealer, in which
+case the Dealer will load all CSYs into its own co-resident Player, since
+the Dealer cannot request the Configurator to start a module for which there
+is not an associated CMI file. </p> </section>
+<section id="GUID-8E49AE8A-E940-52F3-ADA5-0332DA1D58D2"><title>Important Notes</title> <p>Field
+names in the <codeph>[IniData]</codeph> are case sensitive, but fields values
+are not. </p> <p>The <codeph>BindingN</codeph> line is responsible for binding
+the Player CPM with Dealer. If you leave out the <codeph>BindingN</codeph> line
+from the CMI then the new Player will in essence remain as an island and no
+requests for loading or any subsequent operation can be passed to it from
+Dealer. This will not result in a panic. </p> <p>The <codeph>C32_Main.cmi</codeph> doesn’t
+have a <codeph>BindingN</codeph> line since it is a Dealer and thus does not
+need to bind to another Dealer. </p> </section>
+<section id="GUID-C8EA2AA7-28CB-5F89-A0CC-CF20EF21AE6D"><title>Creating A
+New CMI</title> <p>To create a new CMI file, copy an existing Player CMI file,
+rename it and change the necessary parameters as detailed below. The examples
+below assume that the base CMI used was the supplied <codeph>c32_fourth.cmi</codeph>.
+The following parameters need to be changed to make a valid configuration
+file: </p> <p>In <b>[Loader] </b> section are: </p> <ul>
+<li id="GUID-6C3E5830-9A7A-5D84-B4A5-FCA7FD66E31A"><p> <b>Name</b> - This
+is the module name of CPM. </p> </li>
+<li id="GUID-D5BDBEAC-A417-5D39-BB85-4E5AB9DDD36A"><p> <b>BindingN</b> - BindingN
+line is changed to reflect the new module name and <codeph>WorkerId</codeph> value </p> </li>
+</ul> <p>In<b> [IniData] </b> section: </p> <ul>
+<li id="GUID-3855C593-297D-5360-9926-0A1BFFAC3B12"><p> <b>WorkerId</b> - This
+value is numeric and must be unique </p> </li>
+<li id="GUID-EA091203-C0E9-5303-9FD5-924F3C67FB55"><p> <b>CSYList</b> - Contains
+CSYs which you want to load in this new CPM, separated by commas, no white
+spaces allowed. </p> </li>
+</ul> <p>Since the additional CMI being added is a <codeph>Player</codeph>,
+the Role field remains the same and it can not be changed to <codeph>Dealer</codeph> as
+the CPM with <codeph>WorkerId=0</codeph> is the one and only Dealer in the
+C32MT. </p> <codeblock id="GUID-8722A0B7-FB88-5516-846B-BCC4E11D0EEE" xml:space="preserve">[Loader]
+# Change the Name value to your CSY name
+Name=C32_Default  // </codeblock> <p>Change the <codeph>Name</codeph> value
+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
+ThreadFunctionOrdinal=87
+ThreadPriority=EPriorityMuchMore
+StackSize=16384
+ScaledStartupState=0x3040
+HeapOption=ENewHeap
+MinHeapSize=256
+MaxHeapSize=524288
+SystemCritical=1
+Group=C32SerComms
+OnDemand=1</codeblock> <p>Change the BindingN line to refer to your CSY, for
+example change from </p> <codeblock id="GUID-81BEFC33-67EE-5547-8C7C-E473F902F145" xml:space="preserve"># Change the BindingN line to refer to your CSYs
+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
+in the <b>[IniData]</b> section: </p> <codeblock id="GUID-A0AA8BA4-AA45-5FAE-95D4-24764695F04B" xml:space="preserve">[IniData]
+# Make sure Role is set to "Player"
+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
+change the <b>CSYList</b> to specify your CSYs, e.g. change "CSYList=XX,YY,zz"
+to </p> <codeblock id="GUID-9AAAD2C9-A0D0-5733-8EFC-1CB848DB8785" xml:space="preserve">CSYList=MyCSY1,MyCSY2</codeblock> </section>
+<section id="GUID-5A5FEA44-F43B-51BE-9736-7FC76901DB02"><title>Typical Thread
+Configuration Examples</title> <p>This section describes the three broad configurations
+for threading available for the C32 Serial Server. Each has different potential
+effects on the performance of C32. </p> <p>The three broad configurations
+available, with a summary of their costs and benefits, are detailed in the
+following table: </p> <table id="GUID-5552EBC6-3387-59E6-85AC-9585F31C6ABB">
+<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
+<thead>
+<row>
+<entry/>
+<entry>Configuration</entry>
+<entry>Advantages</entry>
+<entry>Disadvantages</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p>1</p> </entry>
+<entry><p>Run all CSYs outside the main thread <b>[Default supplied CMI set]</b>  </p> </entry>
+<entry><ul>
+<li id="GUID-3BD88C6F-9C4E-5001-B7D1-2A9DC3BBE649"><p>Some CSYs can be promoted
+ahead of others using thread priorities </p> </li>
+<li id="GUID-1C1C0DF2-5EED-5AE4-820A-B3020AF66AE6"><p>Main thread cannot ever
+stall when any CSY stalls </p> </li>
+<li id="GUID-F4331549-9283-5E78-AEE1-32C4CF0F11E3"><p>Stackable CSYs are possible:
+a CSY can connect to another CSY through the C32 API as long as both are in
+different threads </p> </li>
+</ul> </entry>
+<entry><ul>
+<li id="GUID-898ED70D-CCB3-5D56-A9A9-49C19BC3C5DC"><p>Operations on CSYs are
+a bit slower due to increased overhead of inter-thread communication </p> </li>
+<li id="GUID-DA120612-E01B-51A4-8B77-F582D8170318"><p>Complex to debug </p> </li>
+</ul> </entry>
+</row>
+<row>
+<entry><p>2</p> </entry>
+<entry><p>Run some CSYs in the main thread </p> </entry>
+<entry><ul>
+<li id="GUID-70EFC61A-5D52-55D1-B364-096F84D0EBDF"><p>CSYs in the main thread
+avoid the overhead of inter-thread communication </p> </li>
+<li id="GUID-63D0CE88-5B6D-5787-A2B4-936B48D16FB2"><p>Some CSYs can be promoted
+ahead of others using thread priorities </p> </li>
+<li id="GUID-71641750-5882-53FC-9B40-0421050E5355"><p>Main thread cannot stall
+when a CSY in a separate thread stalls </p> </li>
+<li id="GUID-88EEE21E-42CF-5401-B985-427E7B3641E9"><p>Stackable CSYs are possible:
+a CSY can connect to another CSY through the C32 API as long as both are in
+different threads </p> </li>
+</ul> </entry>
+<entry><ul>
+<li id="GUID-70FDC4C2-FACB-592F-AA96-9C3F980FA842"><p>If any CSY in the main
+thread stalls, the whole server stalls </p> </li>
+<li id="GUID-E5F158D5-4720-5869-9B67-7FC3001B75F2"><p>No means to prioritise
+one CSY ahead of others (without changing the CSY code) </p> </li>
+<li id="GUID-A773FE9F-AC77-59B0-AECB-FB5C8174583C"><p>Operations on CSYs outside
+the main thread are a bit slower due to the increased overhead of inter-thread
+communication </p> </li>
+<li id="GUID-C0505A00-C777-582A-8B98-C1E53AC094B7"><p>Complex to debug </p> </li>
+</ul> </entry>
+</row>
+<row>
+<entry><p>3</p> </entry>
+<entry><p>Run all CSYs in the main thread <b>[Default configuration when any
+CMI files are corrupt]</b>  </p> </entry>
+<entry><ul>
+<li id="GUID-537C35E5-041E-5BDC-9298-26F89CE5E51F"><p>Simplest to debug since
+no inter-thread communication </p> </li>
+<li id="GUID-EFDEEA79-10D8-5FBF-B630-268F14362C0D"><p>All CSYs avoid the overhead
+of inter-thread communication </p> </li>
+</ul> </entry>
+<entry><ul>
+<li id="GUID-F0C2BD50-CFAD-5E99-AFDF-65BF96B5BB67"><p>If any CSY stalls, the
+whole server stalls </p> </li>
+<li id="GUID-83EDBE8F-17BD-514A-B0D5-5A6020A8DF56"><p>No means to prioritise
+one CSY ahead of others (without changing the CSY code) </p> </li>
+<li id="GUID-BE4157B4-0D0D-5520-8E85-A6C4755410B3"><p>No stackable CSYs are
+possible </p> </li>
+</ul> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>The default set of CMI files supplied with Symbian platform
+is based on the first broad configuration since it was decided that the small
+cost of running all CSYs outside the main thread is justified by the increased
+reliability to the whole C32 system of ensuring no CSY can deny service to
+the C32 server. Each of these configurations is explained in more detail below. </p> <fig id="GUID-BC275667-5D19-56CA-ABD9-68265A852282">
+<title>              Figure 1 - No CSYs in main thread: RootServer with 4
+C32 CPMs            </title>
+<image href="GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e117574_href.png" placement="inline"/>
+</fig> <p>Referring to Figure 1, the following can be observed: </p> <ol id="GUID-DA3BC841-1BE9-5483-8EC0-7BA479D85C14">
+<li id="GUID-EAD7752C-A094-51CA-903C-52DCF2AB5353"><p>The Main Thread has <codeph>WorkerId=0</codeph>,
+Role as Dealer and is configured to load no CSY </p> </li>
+<li id="GUID-CE4A7176-2BD6-5149-B24A-45DCD0945C76"><p>The Player Thread 1
+has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load
+ECACM CSY </p> </li>
+<li id="GUID-A327174B-CA1A-5AD8-92E9-9895363D7851"><p>The Player Thread 2
+has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load
+ECUART CSY </p> </li>
+<li id="GUID-6015DA12-C259-5B9F-9D72-CFF86AA91435"><p>The Player Thread 3
+has <codeph>WorkerId=3</codeph>, Role as Player and is configured to load <i>unlisted</i> csy.
+What unlisted csy means here is that apart from ECACM and ECUART, if any new
+csy is to be loaded, it will get loaded in this thread. </p> </li>
+</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]
+Role=Dealer
+WorkerId=0
+</codeblock> <codeblock id="GUID-51C4FC4E-1F85-59D3-9F9D-FC6868042363" xml:space="preserve">[IniData]
+Role=Player
+WorkerId=1
+CSYList=ECACM
+</codeblock> <codeblock id="GUID-F21BBEC3-482A-59C4-BBE7-9B304F07EDB3" xml:space="preserve">[IniData]
+Role=Player
+WorkerId=2
+CSYList=ECUART
+</codeblock> <codeblock id="GUID-74C70C5D-2B37-5AF8-B703-4072610C6C3E" xml:space="preserve">[IniData]
+Role=Player
+WorkerId=3
+CSYList=*
+</codeblock> <fig id="GUID-92921AF5-D056-52A9-B10E-80760DE9CD2F">
+<title>              Figure 2 - All CSYs in main thread: RootServer with single
+C32 CPM            </title>
+<image href="GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e117641_href.png" placement="inline"/>
+</fig> <p>In Figure 2 the CPM loads any CSYs, and so should contain <codeph>CSYList</codeph> tag
+in the IniData section. </p> <p>The Main Thread has <codeph>WorkerId=0</codeph>,
+Role as Dealer and is configured to load <i>any</i> CSY. In this configuration
+since it is a single thread, all the CSYs will be loaded in the same thread. </p> <p>The <b>[IniData]</b> section
+for above CPM would look like: </p> <codeblock id="GUID-BCDEB67F-85D0-560A-AC5B-7D05B807B857" xml:space="preserve">[IniData]
+Role=Dealer
+WorkerId=0
+CSYList=*
+</codeblock> <fig id="GUID-8F658644-2E07-53A3-A003-C1F015E1396B">
+<title>                 Figure 3 - Some CSYs in main thread: RootServer with
+3 CPMs               </title>
+<image href="GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e117673_href.png" placement="inline"/>
+</fig> <p>From Figure 3, the following can be observed. </p> <ol id="GUID-E945237B-900A-588A-A3FF-C0B75A43BB4A">
+<li id="GUID-0A3CEB52-2C0F-5BB9-A271-756F9F374111"><p>The Main Thread has <codeph>WorkerId=0</codeph>,
+Role as Dealer and is configured to load HSDPA csy </p> </li>
+<li id="GUID-34EF4E58-A6DB-5EFB-8C13-EE8064A7E3F7"><p>The Player Thread 1
+has <codeph>WorkerId=1</codeph>, Role as Player and is configured to load
+ECACM csy </p> </li>
+<li id="GUID-BFF9FDF7-C714-5D0A-B8B3-DC4CCB2EC8FB"><p>The Player Thread 2
+has <codeph>WorkerId=2</codeph>, Role as Player and is configured to load
+an unlisted csy </p> </li>
+</ol> <p>The IniData section for above CPMs would look like: </p> <codeblock id="GUID-E5A77235-60E5-526D-A95C-750FCDCA96BE" xml:space="preserve">[IniData]
+Role=Dealer
+WorkerId=0
+CSYList=HSDPA
+</codeblock> <codeblock id="GUID-ED3EE5DE-65C4-50CB-AEA1-59D89FBC0EF3" xml:space="preserve">[IniData]
+Role=Player
+WorkerId=1
+CSYList=ECACM</codeblock> <codeblock id="GUID-00F4F479-B153-5F05-8E13-D2276D70B605" xml:space="preserve">[IniData]
+Role=Player
+WorkerId=2
+CSYList=*</codeblock> </section>
+<section id="GUID-6350761E-18F6-53B7-98F8-C6E2EB5DA942"><title>Footnotes</title> <dl>
+<dlentry>
+<dt><b>Footnote 1</b> </dt>
+<dd><p>In theory the C32 main thread (<codeph>Workerid=0</codeph>) could be
+marked as on-demand and started by the first client to connect to it. This
+might be useful since it would save device boot time for a device that does
+not need serial comms as part of boot up. The process would require the client
+to connect to Configurator and load the C32 main module explicitly. For this
+to work the main Module’s name would have to be fixed (the reference system
+uses “<codeph>C32_Main</codeph> ”) so that the client can identify it to Configurator
+- which is not a big problem, and the client would need the appropriate capabilities
+(also not a big problem as the client could well be inside Rootserver too).
+The other problem is that making it on-demand requires that it is still started
+by a priviledged process before any unpriviledged process attempts to use
+the C32 API (since this will fail unless no CSYs require any capabilities).
+Therefore, for on-demand main thread-loading to work, intimate details about
+the specific configuration of CSYs for a device and their potential clients
+would be needed. </p> </dd>
+</dlentry>
+</dl> </section>
 </conbody></concept>
\ No newline at end of file