This section describes the format of the files loaded at startup by the Root Server Configurator. The files are known as Comms Module Ini (CMI) files and are used to describe Comms Provider Modules to be started by Root Server.
The files have an extension of .cmi.
Each Comms Module Ini file represents one Comms Provider Module for the Root Server Configurator to load.
Comms Module Ini files can be stored in the ROM of the device by placing the file in the \private\101f7988 folder. For example z:\private\101f7988\etel.cmi.
Comms Module Ini files can also be stored on other drives by placing the file in the same \private\101f7988 folder on the required drive. For example c:\private\101f7988\esock_ir.cmi.
The Comms Configurator searches for the Comms Module Ini files in the \private\101f7988 folders by searching from Y: to A: and then Z:. The folder 101f7988 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 Data Caging. If the files are found in the ROM (usually Z:) they are not then copied to any other drive but only read in-place. Thus, a later configuration of Comms Module Ini 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 startup so any further changes will not take effect until the next time the system is started.
Every Comms Module Ini file contains a [Loader] section, which contains the parameters that the Root Server Configurator must process. Optionally the Comms Module Ini files can also contain a [IniData] section which is read and sent in 8 bit form to the Comms Provider Module as part of the parameters to the main thread function.
Note: The data in the [IniData] does not need to follow the Comms Module Ini file format, since everything from the section header to the end of the file is passed verbatim to the Comms Provider Module.
The format of the [Loader] section of the file is:
Key = Value
For example
FileName=etel.dll
The keywords for the Loader section are summarised in the following table.
| Keyword | Requirement | Default | Description |
|---|---|---|---|
Name |
Mandatory |
The value specifies the server or CPM name to use in all references to this module, e.g. when enumerating loaded modules. This must be unique. |
|
Filename |
Mandatory |
The host DLL containing the server or module |
|
IniData |
Optional |
When present, the value is the name of an initialisation file whose contents are loaded into a descriptor and passed to the CPM as part of the parameters to the main thread function. The usage of this key overrides the usage of a IniData section within this file. |
|
IsSticky |
Optional |
0 - Module can be unloaded |
When present and with a value other than 0, specifies that clients cannot request the module to be shut down. The RootServer will return KErrLocked on such requests. |
ThreadFunctionOrdinal |
Optional |
If not specified, or set to 0, it is assumed that the main thread function of the CPM is the default ordinal (which is the first ordinal in the export table - ordinal 1). If set to an integer number >0, the corresponding ordinal of the CPM DLL will be used as the main thread function. Anything else than 0 or a positive number is illegal. |
|
Priority |
Optional |
When present, the value is an string value corresponding to the TThreadPriority enumerated type. The results of setting it to any other value will result in a KErrCorrupt error code. |
|
StackSize |
Optional |
When present, the value is the integer size for the module’s main thread’s stack in bytes. |
|
StartSequence |
Optional |
When present, the value is the integer start sequence. This is the legacy way of controlling the module start-up point and is translated into the ScaledStartupState. |
|
HeapOption |
Optional |
Load into default heap |
When present, controls whether the module is loaded with a new heap, attempts to share a heap, or simple uses the Root Server's heap. Values: |
MinHeapSize |
Optional |
If HeapOption is not ENewHeap this section is ignored. When present, specifies the minimum size in bytes of the Comms Provider Module's heap. |
|
MaxHeapSize |
Optional |
If HeapOption is not ENewHeap this section is ignored. Specifies the maximum size in bytes of the Comms Provider Module's heap. |
|
ShareHeapWith |
Optional |
If HeapOption is not specified as EShareHeap, this section is ignored, otherwise it is mandatory. When present specifies which CPM to share a heap with. |
|
BindingN |
Optional |
Specify a Binding between two modules |
|
ScaledStartupState |
Optional |
When present the value is the integer SSA start-up state, scaled up by KC32StartupStateScalingFactor (0x100). |
|
SystemCritical |
Optional |
0 |
If set to 1, the Comms Provider Module runs as a System Critical thread. |
SystemCriticalAfterInit |
Optional |
0 |
If set to 1, the Comms Provider Module runs as a System Critical thread once the Root Server Configurator has started all non-on-demand Comms Provider Modules. |
OnDemand |
Optional |
Only load this Comms Provider Module when a client specifically requests it. Available only to Serial Communications Server files. |
|
Group |
Optional |
The value contains the name of a group in which this Comms Provider Module belongs. Available only to Serial Communications Server files. |
The following example shows a CMI file to load the Telephony Server:
## Comms Configurator config file for the ETel server [Loader] Name=CTelServer FileName=etel.dll ThreadFunctionOrdinal=233 IsSticky=1 IsServer=1 Priority=EPriorityNormal StackSize=16384 ScaledStartupState=0x1085 HeapOption=ENewHeap MinHeapSize=256 MaxHeapSize=786432 SystemCritical=1 ControlFlags=1
The following example shows a CMI file to load the IP thread for the Socket Server:
# Comms Configurator config file for the ESock IP Data worker [Loader] Name=ESock_DIP FileName=esocksvr.dll ThreadFunctionOrdinal=1 IsSticky=0 IsServer=1 Priority=EPriorityMuchMore StackSize=16384 ScaledStartupState=0x3040 HeapOption=ENewHeap MinHeapSize=256 MaxHeapSize=524288 SystemCritical=0 SystemCriticalAfterInit=1 Binding0=ESock_DIP:1,ESock_Main:0,ECustom,15,15 # Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck) ControlFlags=4 [IniData] Role=DealerPlayer WorkerId=1 EskMask=IP.*.ESK PlayerRole=0x0001 # Hosting only data
The following example shows a CMI file to load the ECUART CSY into the second thread for the Serial Communications Server:
# c32_second - Comms Configurator config file forming part of the Default C32 server configuration [Loader] Name=C32_BaseBand FileName=c32.dll ThreadFunctionOrdinal=87 IsSticky=0 IsServer=1 Priority=EPriorityMuchMore StackSize=16384 ScaledStartupState=0x1087 HeapOption=ENewHeap MinHeapSize=256 MaxHeapSize=524288 SystemCriticalAfterInit=1 Group=C32SerComms OnDemand=1 Binding0=C32_BaseBand:2,C32_Main:0,ECustom,42,42 # Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck) ControlFlags=4 [IniData] Role=Player WorkerId=2 CSYList=ECUART