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.
The Comms Configurator (
The Comms Configurator searches for the CMI files in the
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.
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.
The quick migration involves two steps:
apply any special configuration used with the previous single-threaded C32 Serial Server to the new configuration files supplied with the multi-threaded server
adjust the default set of configuration files supplied with the multi-threaded server to suit the particular serial plug-ins in use
These two steps are explained in more detail in the following sections.
Migrating settings
The original single-threaded Serial Server was controlled by a single configuration file called (by default)
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:
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:
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:
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:
The value of
The value of
The value of
Assigning CSY plug-ins to threads
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.
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
As mentioned earlier, the default configuration uses five threads. The description for each of these is given in the following table:
For a particular device, the above configuration may need to be changed to address the requirements of the device. Typical adjustments to consider are:
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
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
For any extra high-performance CSYs, create a new CMI file so that these can run separately from the other CSYs. See
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 How To Assign Thread Priorities elsewhere in this developer library.
When making these adjustments note that there is no cost involved with mentioning CSYs that may never be loaded.
C32 Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading. The Dealer 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.
For example:
C32.cmi
The
The description of each of the settings under
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:
C32_Default.cmi
This section gives details about the parameters available in the CMI file relevant to C32. The CMI file has two sections - a
A note on CMI processing
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.
A bad configuration will panic in debug builds to signal the user to change/edit the
The panic numbers used by the C32 Serial Server for internal server faults are defined in the enum
CMI [Loader] Parameters relevant to C32
OnDemand
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
All Player modules for C32 must be marked with
Group
All CMI files for C32 must map to the same Group ID. The actual Group ID for the C32 group is
If there is no group defined in any CMI files and therefore no [IniData] is processed for any of them, then C32 will simply assign all CSYs to load into the Dealer thread.
Name
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
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.
When introducing new CMIs, care should be taken to change the
CMI [IniData] Parameters relevant to C32
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
Role
The value for this parameter should be either
WorkerId
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
CSYList
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
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.
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
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 default 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.
Field names in the
The
The
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
In [Loader] section are:
Name - This is the module name of CPM.
BindingN - BindingN line is changed to reflect the new module name and
In [IniData] section:
WorkerId - This value is numeric and must be unique
CSYList - Contains CSYs which you want to load in this new CPM, separated by commas, no white spaces allowed.
Since the additional CMI being added is a
Change the
Change the BindingN line to refer to your CSY, for example change from
to
And in the [IniData] section:
Change the WorkerId, for example from
and change the CSYList to specify your CSYs, e.g. change "CSYList=XX,YY,zz" to
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.
The three broad configurations available, with a summary of their costs and benefits, are detailed in the following table:
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.
Referring to Figure 1, the following can be observed:
The Main Thread has
The Player Thread 1 has
The Player Thread 2 has
The Player Thread 3 has
The [IniData] section for the above CPMs would look like:
In Figure 2 the CPM loads any CSYs, and so should contain
The Main Thread has
The [IniData] section for above CPM would look like:
From Figure 3, the following can be observed.
The Main Thread has
The Player Thread 1 has
The Player Thread 2 has
The IniData section for above CPMs would look like:
In theory the C32 main thread (
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.
The
+Comms Configurator (
The Comms Configurator
+searches for the CMI files in the
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.
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.
The quick migration involves two steps:
apply any special configuration +used with the previous single-threaded C32 Serial Server to the new configuration +files supplied with the multi-threaded server
adjust the default set +of configuration files supplied with the multi-threaded server to suit the +particular serial plug-ins in use
These two steps are explained in more detail in the following sections.
Migrating settings
The original single-threaded Serial Server
+was controlled by a single configuration file called (by default)
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:
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:
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:
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:
The value of
The value of
The value of
Assigning +CSY plug-ins to threads
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.
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
As mentioned earlier, the default +configuration uses five threads. The description for each of these is given +in the following table:
For a particular device, the above configuration may need to be +changed to address the requirements of the device. Typical adjustments to +consider are:
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
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
For any extra high-performance
+CSYs, create a new CMI file so that these can run separately from the other
+CSYs. See
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 How +To Assign Thread Priorities elsewhere in this developer library.
When making these adjustments note that there is no cost involved +with mentioning CSYs that may never be loaded.
C32 +Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading. +The Dealer 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.
For example:
C32.cmi
The
The
+description of each of the settings under
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:
C32_Default.cmi
This section gives details about the parameters available
+in the CMI file relevant to C32. The CMI file has two sections - a
A note on CMI processing
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.
A bad
+configuration will panic in debug builds to signal the user to change/edit
+the
The
+panic numbers used by the C32 Serial Server for internal server faults are
+defined in the enum
CMI [Loader] Parameters relevant to C32
OnDemand
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
All Player modules for C32 must be marked
+with
Group
All CMI files for C32 must map to the same Group ID.
+The actual Group ID for the C32 group is
If +there is no group defined in any CMI files and therefore no [IniData] is +processed for any of them, then C32 will simply assign all CSYs to load into +the Dealer thread.
Name
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
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.
When introducing
+new CMIs, care should be taken to change the
CMI [IniData] Parameters relevant to C32
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
Role
The
+value for this parameter should be either
WorkerId
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
CSYList
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
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.
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
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 default 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.
Field
+names in the
The
The
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
In [Loader] section are:
Name - This +is the module name of CPM.
BindingN - BindingN
+line is changed to reflect the new module name and
In [IniData] section:
WorkerId - This +value is numeric and must be unique
CSYList - Contains +CSYs which you want to load in this new CPM, separated by commas, no white +spaces allowed.
Since the additional CMI being added is a
Change the
Change the BindingN line to refer to your CSY, for +example change from
to
And +in the [IniData] section:
Change the WorkerId, for example from
and +change the CSYList to specify your CSYs, e.g. change "CSYList=XX,YY,zz" +to
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.
The three broad configurations +available, with a summary of their costs and benefits, are detailed in the +following table:
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.
Referring to Figure 1, the following can be observed:
The Main Thread has
The Player Thread 1
+has
The Player Thread 2
+has
The Player Thread 3
+has
The [IniData] section for the above CPMs would look like:
In Figure 2 the CPM loads any CSYs, and so should contain
The Main Thread has
The [IniData] section +for above CPM would look like:
From Figure 3, the following can be observed.
The Main Thread has
The Player Thread 1
+has
The Player Thread 2
+has
The IniData section for above CPMs would look like:
In theory the C32 main thread (