Symbian3/SDK/Source/GUID-10A0DC8C-70B3-53D0-B63F-786C4BAB36CF.dita
changeset 7 51a74ef9ed63
parent 0 89d6a7a84779
equal deleted inserted replaced
6:43e37759235e 7:51a74ef9ed63
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE reference
       
    11   PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
       
    12 <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
       
    13 
       
    14 [Loader]
       
    15 Name=CTelServer
       
    16 FileName=etel.dll
       
    17 ThreadFunctionOrdinal=233
       
    18 IsSticky=1
       
    19 IsServer=1
       
    20 Priority=EPriorityNormal
       
    21 StackSize=16384
       
    22 ScaledStartupState=0x1085
       
    23 HeapOption=ENewHeap
       
    24 MinHeapSize=256
       
    25 MaxHeapSize=786432
       
    26 SystemCritical=1
       
    27 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
       
    28 
       
    29 [Loader]
       
    30 Name=ESock_DIP
       
    31 FileName=esocksvr.dll
       
    32 ThreadFunctionOrdinal=1
       
    33 IsSticky=0
       
    34 IsServer=1
       
    35 Priority=EPriorityMuchMore
       
    36 StackSize=16384
       
    37 ScaledStartupState=0x3040
       
    38 HeapOption=ENewHeap
       
    39 MinHeapSize=256
       
    40 MaxHeapSize=524288
       
    41 SystemCritical=0
       
    42 SystemCriticalAfterInit=1
       
    43 Binding0=ESock_DIP:1,ESock_Main:0,ECustom,15,15
       
    44 # Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
       
    45 ControlFlags=4
       
    46 [IniData]
       
    47 Role=DealerPlayer
       
    48 WorkerId=1
       
    49 EskMask=IP.*.ESK
       
    50 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
       
    51 
       
    52 
       
    53 [Loader]
       
    54 Name=C32_BaseBand
       
    55 FileName=c32.dll
       
    56 ThreadFunctionOrdinal=87
       
    57 IsSticky=0
       
    58 IsServer=1
       
    59 Priority=EPriorityMuchMore
       
    60 StackSize=16384
       
    61 ScaledStartupState=0x1087
       
    62 HeapOption=ENewHeap
       
    63 MinHeapSize=256
       
    64 MaxHeapSize=524288
       
    65 SystemCriticalAfterInit=1
       
    66 Group=C32SerComms
       
    67 OnDemand=1
       
    68 Binding0=C32_BaseBand:2,C32_Main:0,ECustom,42,42 
       
    69 # Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
       
    70 ControlFlags=4
       
    71 [IniData]
       
    72 Role=Player
       
    73 WorkerId=2
       
    74 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
       
    75                 to Configure Multithreaded C32 Serial Comms: Tutorial</linktext> </link> </related-links></reference>