CMI File Format

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.

File Location

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.

Syntax

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:

  1. EDefaultHeap, use the default shared heap for the process.

  2. EShareHeap, use the same heap as module defined by the option ShareHeapWith.

  3. ENewHeap, create module with a new heap.

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.

CMI File Format Examples

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