<?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 xml:lang="en" id="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566"><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 OS 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><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 OS. </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 OS, 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 OS 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><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 OS 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_d0e102675_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_d0e102739_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_d0e102769_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>