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