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

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference xml:lang="en" id="GUID-10A0DC8C-70B3-53D0-B63F-786C4BAB36CF"><title>CMI File Format</title><shortdesc>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. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody><section><p>The files have an extension of <filepath>.cmi</filepath>. </p> <p>Each Comms Module Ini file represents one Comms Provider Module for the Root Server Configurator to load. </p> </section> <section><title>File Location</title> <p>Comms Module Ini files can be stored in the ROM of the device by placing the file in the <filepath>\private\101f7988</filepath> folder. For example <filepath>z:\private\101f7988\etel.cmi</filepath>. </p> <p>Comms Module Ini files can also be stored on other drives by placing the file in the same <filepath>\private\101f7988</filepath> folder on the required drive. For example <filepath>c:\private\101f7988\esock_ir.cmi</filepath>. </p> <p>The Comms Configurator searches for the Comms Module Ini files in the <filepath>\private\101f7988</filepath> 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 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. </p> </section> <refsyn><title>Syntax</title> <p>Every Comms Module Ini file contains a <codeph>[Loader]</codeph> section, which contains the parameters that the Root Server Configurator must process. Optionally the Comms Module Ini files can also contain a <codeph>[IniData]</codeph> 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. </p> <p>Note: The data in the <codeph>[IniData]</codeph> 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. </p> <p>The format of the <codeph>[Loader]</codeph> section of the file is: </p> <p> <i>Key</i>  <codeph>=</codeph>  <i>Value</i>  </p> <p>For example </p> <codeblock id="GUID-5437281B-25B2-5D59-859D-7F226BC0E951" xml:space="preserve">FileName=etel.dll</codeblock> <p>The keywords for the Loader section are summarised in the following table. </p> <table id="GUID-6D680272-D684-51E9-A2FA-A4A04265F4EE"><tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><thead><row><entry>Keyword</entry> <entry>Requirement</entry> <entry>Default</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <codeph>Name</codeph>  </p> </entry> <entry><p>Mandatory </p> </entry> <entry/><entry><p>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. </p> </entry> </row> <row><entry><p> <codeph>Filename</codeph>  </p> </entry> <entry><p>Mandatory </p> </entry> <entry/><entry><p>The host DLL containing the server or module </p> </entry> </row> <row><entry><p> <codeph>IniData</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>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 <codeph>IniData</codeph> section within this file. </p> </entry> </row> <row><entry><p> <codeph>IsSticky</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry><p>0 - Module can be unloaded </p> </entry> <entry><p>When present and with a value other than 0, specifies that clients cannot request the module to be shut down. The RootServer will return <xref href="GUID-CF080900-A9A4-391E-AC95-B93EBFB23DE3.dita"><apiname>KErrLocked</apiname></xref> on such requests. </p> </entry> </row> <row><entry><p> <codeph>ThreadFunctionOrdinal</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>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 &gt;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. </p> </entry> </row> <row><entry><p> <codeph>Priority</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>When present, the value is an string value corresponding to the <xref href="GUID-8708AFB7-92CC-34FC-9FBB-E6B16472B99D.dita"><apiname>TThreadPriority</apiname></xref> enumerated type. The results of setting it to any other value will result in a <xref href="GUID-253F06EA-F14E-3A8E-BA4C-8E787B5F0670.dita"><apiname>KErrCorrupt</apiname></xref> error code. </p> </entry> </row> <row><entry><p> <codeph>StackSize</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>When present, the value is the integer size for the module’s main thread’s stack in bytes. </p> </entry> </row> <row><entry><p> <codeph>StartSequence</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>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. </p> </entry> </row> <row><entry><p> <codeph>HeapOption</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry><p>Load into default heap </p> </entry> <entry><p>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: </p> <ol id="GUID-06FB91FD-0580-5757-B73C-EBD674A2DB86"><li id="GUID-D572E800-5A15-543D-A679-AD5142BA74B1"><p> <codeph>EDefaultHeap</codeph>, use the default shared heap for the process. </p> </li> <li id="GUID-A7687931-0794-5FCA-B2EA-60513629858E"><p> <codeph>EShareHeap</codeph>, use the same heap as module defined by the option <codeph>ShareHeapWith</codeph>. </p> </li> <li id="GUID-9134D543-B1A5-5017-8436-0B0710B02A1C"><p> <codeph>ENewHeap</codeph>, create module with a new heap. </p> </li> </ol> </entry> </row> <row><entry><p> <codeph>MinHeapSize</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>If <codeph>HeapOption</codeph> is not <codeph>ENewHeap</codeph> this section is ignored. When present, specifies the minimum size in bytes of the Comms Provider Module's heap. </p> </entry> </row> <row><entry><p> <codeph>MaxHeapSize</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>If <codeph>HeapOption</codeph> is not <codeph>ENewHeap</codeph> this section is ignored. Specifies the maximum size in bytes of the Comms Provider Module's heap. </p> </entry> </row> <row><entry><p> <codeph>ShareHeapWith</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>If <codeph>HeapOption</codeph> is not specified as <codeph>EShareHeap</codeph>, this section is ignored, otherwise it is mandatory. When present specifies which CPM to share a heap with. </p> </entry> </row> <row><entry><p> <codeph>BindingN</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>Specify a Binding between two modules </p> </entry> </row> <row><entry><p> <codeph>ScaledStartupState</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>When present the value is the integer SSA start-up state, scaled up by <codeph> KC32StartupStateScalingFactor</codeph> (0x100). </p> </entry> </row> <row><entry><p> <codeph>SystemCritical</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry><p>0</p> </entry> <entry><p>If set to 1, the Comms Provider Module runs as a System Critical thread. </p> </entry> </row> <row><entry><p> <codeph>SystemCriticalAfterInit</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry><p>0</p> </entry> <entry><p>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. </p> </entry> </row> <row><entry><p> <codeph>OnDemand</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>Only load this Comms Provider Module when a client specifically requests it. Available only to Serial Communications Server files. </p> </entry> </row> <row><entry><p> <codeph>Group</codeph>  </p> </entry> <entry><p>Optional </p> </entry> <entry/><entry><p>The value contains the name of a group in which this Comms Provider Module belongs. Available only to Serial Communications Server files. </p> </entry> </row> </tbody> </tgroup> </table> </refsyn> <example><title>CMI File Format Examples</title> <p>The following example shows a CMI file to load the Telephony Server: </p> <codeblock id="GUID-8A4DA27E-FF8C-574E-8256-E2A8A32164A4" xml:space="preserve">## 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</codeblock> <p>The following example shows a CMI file to load the IP thread for the Socket Server: </p> <codeblock id="GUID-1C0B5CF9-2483-58F2-AC01-34D1EF505B00" xml:space="preserve"># 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</codeblock> <p>The following example shows a CMI file to load the ECUART CSY into the second thread for the Serial Communications Server: </p> <codeblock id="GUID-5A63D90D-7B02-5D21-8659-092147D73EB7" xml:space="preserve"># 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</codeblock> </example> </refbody><related-links><link href="GUID-282CE322-923F-58F6-804D-E125ABACB025.dita"><linktext>What is the System Critical Parameter?</linktext> </link> <link href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita"><linktext> How

                to Configure Multithreaded C32 Serial Comms: Tutorial</linktext> </link> </related-links></reference>