OpenClovis Product Documentation - User contributions [en]

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-12T21:21:06Z

Agnes: Doc:Sdkguide/compconfig moved to Doc:Sdk 3.1/sdkguide/compconfig

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated <code>clDbalConfig.xml</code> file will look like:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|-
|<code><pre>
<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>
</pre></code>
|}

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|-
|<code><pre>
<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>
</pre></code>
|}

'''Usage of environment variable ASP_DB_SYNC :'''

ASP_DB_SYNC environment variable may be used to open all the DBs in synchronous or asynchronous mode depending on its value.
To open all the DBs in synchronous mode set ASP_DB_SYNC to TRUE and FALSE for asynchronous mode. If this variable is set then
it overrides the DBAL open flag CL_DB_SYNC (please refer the OpenClovis API Recerence Guide for usage of CL_DB_SYNC flag).

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:09:44Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:08:13Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated <code>clDbalConfig.xml</code> file will look like:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|-
|<code><pre>
<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>
</pre></code>
|}

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|-
| <code><pre>
<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>
</pre></code>
|}

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:07:40Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated <code>clDbalConfig.xml</code> file will look like:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|- <code><pre>
<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>
</pre></code>
|}

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clDbalConfig.xml
|- <code><pre>
<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>
</pre></code>
|}

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:04:54Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated <code>clDbalConfig.xml</code> file will look like:
<code><pre>
<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>
</pre></code>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:
<code><pre>
<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>
</pre></code>

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:03:59Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated <code>clDbalConfig.xml</code> file will look like:
<code><pre>
<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>
</pre></code>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:02:12Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <code><Engine> .. </Engine></code> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated clDbalConfig.xml file will look like:

<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:01:35Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <Engine> .. </Engine> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated clDbalConfig.xml file will look like:

<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:01:19Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<code><project_area>/<Model>/src/config/clDbalConfig.xml</code> file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <Engine> .. </Engine> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated clDbalConfig.xml file will look like:

<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>

Doc:Sdk 3.1/sdkguide/compconfig

2008-03-03T17:00:02Z

Agnes: /* Configuring Database Abstraction Layer (DBAL) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]
* [[#Configuring Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

===Configuring Database Abstraction Layer (DBAL)===

The configuration parameters for Dbal is located in
<Project-Area>/<Model>/src/config/clDbalConfig.xml file.

The various database engines supported by Dbal are listed in this file.
These engines are configured within set of <Engine> .. </Engine> tags.
By default the 'SQLite' DB Engine is configured to be used. If the user
wants to use some other engines, then he needs to comment this engine
and enable the other.

For eg: by default the IDE generated clDbalConfig.xml file will look like:

<Dbal>


<Engine>
<FileName>libClSQLiteDB.so</FileName>
<Type>SQLiteDB</Type>
</Engine>
</Dbal>

If the user needs to use Berkeley DB instead of SQLite, then he has to
do the change like below:

<Dbal>

<Engine>
<FileName>libClBerkeleyDB.so</FileName>
<Type>BerkeleyDB</Type>
</Engine>

</Dbal>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-28T19:47:17Z

Agnes: /* Log service perennial stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-28T19:46:18Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is not ROTATE, then this value has to be set 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE. If the file full action is HALT or WRAP, then this value has to be set to 0.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-28T19:26:46Z

Agnes: /* Log service perennial stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, in case the file full action is ROTATE.
If the file full action is not ROTATE, then this value has to be set 0.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-17T17:02:18Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file generated by IDE is shown in chapter ''XML Representation of the Model'' of ''OpenClovis IDE User Guide''.

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-17T16:56:26Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

An example <code>clLog.xml</code> file XML Representation of the Model

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-14T23:54:41Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so on.
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' is created under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of multicastAddress and multicastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it knows when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-04T17:27:43Z

Agnes: /* Configuring Group Membership Service (GMS) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': Name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it know when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-04T17:25:06Z

Agnes: /* Configuring Group Membership Service (GMS) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''clusterName''': name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it know when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2008-01-04T17:22:34Z

Agnes: /* Configuring Group Membership Service (GMS) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''linkName''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''multicastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''multicastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''maxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.
* '''openAisLoggingOption''': This options controls the log output from OpenAis software used by GMS. This tag can take the value 'file', 'stderr', 'syslog' and 'none'. The default value is 'none'. Note that this option is useful while debugging issues with GMS. Also note that, if the option is 'syslog', then local5 channel is used. So user needs to configure this channel in syslog.conf. And if the option is set to 'file', then a log file with name 'OpenAis.log' under <code>$ASP_LOGDIR </code> directory.

'''Note 1:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

'''Note 2:''' GMS runs on top of IP multicast. It uses the multicast address and the multicast port number specified in the configuration given above and forms a multicast group. This way it know when a new member joins a group and leaves a group. Please note that multicast has certain dependencies such as the firewall should be disabled on the machine using "iptables -F" command, etc.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-27T20:02:09Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[File:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-07T20:24:44Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-07T20:24:08Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-07T20:23:38Z

Agnes: /* Log service perennial stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by the user.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the user.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-07T20:22:30Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the user.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-12-07T20:21:55Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the user (developer, tester or system administrator) based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-28T16:46:41Z

Agnes: /* Configuring Group Membership Service (GMS) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/clGmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-28T16:44:26Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

ClLog.xml

2007-11-28T16:44:04Z

Agnes: Log.xml moved to ClLog.xml

<?xml version="1.0" encoding="UTF-8"?>
<log:BootConfig xmlns:log="log.ecore">
<log>
<logConfigData>
<maximumStreams>256</maximumStreams>
<maximumComponents>256</maximumComponents>
<maximumSharedMemoryPages>20</maximumSharedMemoryPages>
<maximumRecordsInPacket>100</maximumRecordsInPacket>
</logConfigData>
<perennialStreamsData>
<stream name="appStream">
<fileName>app</fileName>
<fileLocation>*:/tmp</fileLocation>
<fileUnitSize>1500000</fileUnitSize>
<recordSize>300</recordSize>
<fileFullAction>1</fileFullAction>
<maximumFilesRotated>0</maximumFilesRotated>
<flushFreq>64</flushFreq>
<flushInterval>100000</flushInterval>
</stream>
<stream name="sysStream">
<fileName>sys</fileName>
<fileLocation>*:/tmp</fileLocation>
<fileUnitSize>1500000</fileUnitSize>
<recordSize>300</recordSize>
<fileFullAction>1</fileFullAction>
<maximumFilesRotated>0</maximumFilesRotated>
<flushFreq>64</flushFreq>
<flushInterval>100000</flushInterval>
</stream>
</perennialStreamsData>
<precreatedStreamsData>
<stream name="test">
<fileName>testFile</fileName>
<fileLocation>*:/tmp</fileLocation>
<fileUnitSize>1500000</fileUnitSize>
<recordSize>300</recordSize>
<fileFullAction>1</fileFullAction>
<maximumFilesRotated>0</maximumFilesRotated>
<flushFreq>64</flushFreq>
<flushInterval>100000</flushInterval>
<streamScope>1</streamScope>
</stream>
</precreatedStreamsData>
</log>
</log:BootConfig>

Log.xml

2007-11-28T16:44:04Z

Agnes: Log.xml moved to ClLog.xml

#REDIRECT [[ClLog.xml]]

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-28T16:43:42Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-28T16:42:47Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===

The configuration information for Log Service is generated by IDE in the [[clLog.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-13T20:26:14Z

Agnes: /* Assigning Memory Profiles */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{| cellspacing="0" cellpadding = "0" border="0" align = "center"
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-13T20:17:58Z

Agnes: /* Assigning Memory Profiles */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{|
|-
|
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-13T20:15:18Z

Agnes: /* Assigning Memory Profiles */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:
{|
|-
<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>
|}

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-11-13T20:12:04Z

Agnes: /* Assigning Memory Profiles */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<code><pre>
<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>
</pre></code>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:15:13Z

Agnes: /* Configuring Group Membership Service (GMS) */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:14:46Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
* LOCAL
* GLOBAL

'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:13:53Z

Agnes: /* Log service perennial stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName''':
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation''':
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize''':
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size''':
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction''':
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated''':
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq''':
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval''':
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

*'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

*'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
** LOCAL
** GLOBAL

*'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

*'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
** If nodename is '*' <star> , then the file will be created where the system controller active is running.
** If nodename is '.' <dot>, then the file will be created in the local node.

*'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

*'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

*'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
** HALT
** WRAP
** ROTATE

*'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

*'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

*'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:13:08Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

*'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

*'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
** LOCAL
** GLOBAL

*'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

*'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
** If nodename is '*' <star> , then the file will be created where the system controller active is running.
** If nodename is '.' <dot>, then the file will be created in the local node.

*'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

*'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

*'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
** HALT
** WRAP
** ROTATE

*'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

*'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

*'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:12:27Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

*'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

*'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
** LOCAL
** GLOBAL

*'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

*'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/' then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.
** If nodename is '*' <star> , then the file will be created where the system controller active is running.
** If nodename is '.' <dot>, then the file will be created in the local node.

*'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

*'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

*'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
** HALT
** WRAP
** ROTATE

*'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

*'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

*'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:11:50Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

*'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

*'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid value for this tag.
** LOCAL
** GLOBAL

*'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

*'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

** If nodename is '*' <star> , then the file will be created where the system controller active is running.
** If nodename is '.' <dot>, then the file will be created in the local node.

*'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

*'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

*'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
** HALT
** WRAP
** ROTATE

*'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

*'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

*'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:11:15Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

*'''streamName''': This value of the tag specifies the name of the precreated stream. This can be any valid name.

*'''streamScope''': This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
** LOCAL
** GLOBAL

*'''fileName''' : The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

*'''fileLocation''' : The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

** If nodename is '*' <star> , then the file will be created where the system controller active is running.
** If nodename is '.' <dot>, then the file will be created in the local node.

*'''fileUnitSize''' : The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

*'''record size''': The value of this tag specifies the size of the record (single log message) in bytes.

*'''fileFullAction''': The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
** HALT
** WRAP
** ROTATE

*'''maximumFilesRotated''': The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE. If the file full action is not ROTATE, then this value will be ignored.

*'''flushFreq''': The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

*'''flushInterval''': The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:08:55Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

[[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:08:19Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency. FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T18:07:27Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

*'''maximumStream''': The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

*'''maximumComponents''': The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

*'''maximumSharedMemoryPages''': The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

*'''maximumRecordsInPacket''': The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T03:17:26Z

Agnes: /* Configuring Log Service */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream'''
The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents'''
The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages'''
The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

'''maximumRecordsInPacket'''
The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====

When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T03:16:48Z

Agnes: /* Log service precreated stream config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream'''
The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents'''
The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages'''
The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

'''maximumRecordsInPacket'''
The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====
When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====

When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T03:16:24Z

Agnes: /* Log service common config parameters */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====

These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream'''
The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents'''
The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages'''
The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

'''maximumRecordsInPacket'''
The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====
When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====
When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-18T00:09:34Z

Agnes: /* '''OpenClovis SAFplus Platform Component Configuration''' */

==OpenClovis SAFplus Platform Component Configuration==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====
These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream'''
The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents'''
The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages'''
The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

'''maximumRecordsInPacket'''
The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====
When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====
When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdk 3.1/sdkguide/compconfig

2007-10-17T18:12:47Z

Agnes:

=='''OpenClovis SAFplus Platform Component Configuration'''==

Certain Components are allowed to be configured, to provide the flexibility of configuring OpenClovis SAFplus Platform to suit your requirements. OpenClovis SAFplus Platform can be customized and configured to execute on target platforms and support your application software.This chapter provides you the configuration details of OpenClovis SAFplus Platform components.

'''Key Topics:'''
* [[#Configuring Execution Object (EO) | Configuring Execution Object (EO)]]
* [[#Configuring Memory | Configuring Memory]]
* [[#Configuring Remote Method Dispatch (RMD) | Configuring Remote Method Dispatch (RMD)]]
* [[#Configuring Clovis Object Registry (COR) | Configuring Clovis Object Registry (COR)]]
* [[#Configuring Log Service | Configuring Log Service]]
* [[#Configuring Group Membership Service (GMS) | Configuring Group Membership Service (GMS)]]
* [[#Configuring Name Service | Configuring Name Service]]

===Configuring Execution Object (EO)===

The following parameters are located in <code>'''<project_area>/<model>/src/app/clCompCfg.h '''</code> file. This file is generated through OpenClovis IDE.

EO comprises the following configurable parameters while declaring the <code>clEoConfigT</code> structure:
 '''COMP_EO_NAME'''

This attribute defines the name of the EO.
<ul>
<li>Format - To configure this parameter, set EO <code>name</code> field of the <code>ClEoConfigT</code> to the name of the EO.
 For example,
<code><pre>
ClEoConfigT clEoConfig;
clEoConfig.name = "UserEO"
</pre></code>

<li>Range - You can provide any string as the EO name that can be up to <code>CL_EO_MAX_NAME_LEN</code> characters long.
</ul>

'''COMP_EO_THREAD_PRIORITY'''

This attribute defines the EO thread priority.
<ul>
<li>Format - To configure this parameter, <code>pri</code> field of the <code>ClEoConfigT</code> to the required priority.
 For example,
<code><pre>
clEoConfig.pri = CL_OSAL_THREAD_PRI_MEDIUM
</pre></code>

<li>Range - You can define the priority to have the following values:
<code><pre>
CL_OSAL_THREAD_PRI_HIGH
CL_OSAL_THREAD_PRI_MEDIUM
CL_OSAL_THREAD_PRI_LOW
</pre></code>
Default = <code>CL_OSAL_THREAD_PRI_MEDIUM</code>
</ul>
[[File:OpenClovis_Note.png]]This parameter must not be modified. This parameter has no affect in the current implementation.

'''COMP_EO_NUM_THREAD'''

This attribute defines the number of EO worker threads.
<ul>
<li>Format - To configure this parameter, set <code>noOfThreads</code> field of the <code>ClEoConfigT</code> to the required number of RMD threads.
For example,
<code><pre>
clEoConfig.noofThreads = 2
</pre></code>

<li>Range - You can define the values in the following range:
*Minimum = 2
*Maximum = 2^32 -1
*Default = 2
</ul>

'''COMP_IOC_PORT'''

This attribute defines the requested IOC communication port.
<ul>
<li>Format - To configure this parameter, set <code>reqIocPort</code> field of the <code>ClEoConfigT</code> to the required IOC port. If 0 is specified as a port then the new port number is automatically assigned by the IOC.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_START</code>
*Maximum = <code>CL_IOC_USER_APP_WELLKNOWN_PORTS_END</code>
</ul>

For example:

If the application wants a communication port well know to other processes in the system and also which will not change on restart of the process, then it should be got as shown below.
<code><pre>
clEoConfig.reqIocPort = CL_IOC_USER_APP_WELLKNOWN_PORTS_START +
<app_specific_unique_number>;
</pre></code>

If the apllication wants the IOC to assign a communication port to it, which can change on every time the process is restarted, then 0 should be passed in <code>reqIocPort</code> field.
<code><pre>
clEoConfig.reqIocPort = 0;
</pre></code>

''' COMP_EO_USER_CLIENT_ID '''

This attribute defines the maximum number of EO clients that are initialized by the EO. This is used to allocate space needed to install the client tables.

<ul>
<li>Format - To configure this parameter, set <code>maxNoClients</code> field of the <code>ClEoConfigT</code> to the required value. The default value <code>CL_EO_USER_CLIENT_ID_START</code> allocates enough space to accommodate the OpenClovis SAFplus Platform services.
If you want to initialize additional clients, you must specify this parameter as:
<code><pre>
clEoConfig.maxNoClients = CL_EO_USER_CLIENT_ID_START + n
</pre></code>
where <code>n</code> is the number of additional clients.

<li>Range - You can define the values in the following range:
*Minimum = <code>CL_EO_USER_CLIENT_ID_START</code>
*Maximum = 2^32 -1
*Default = <code>CL_EO_USER_CLIENT_ID_START</code>
</ul>

''' COMP_EO_USE_THREAD_MODEL '''

This attribute defines whether the application needs the main thread or not. For more details on this parameter, refer to Figure [[Doc:Sdkguide/infrastructure#Illustration of the usage of application type|Illustration of the usage of application type]].
<ul>
<li>Format - To configure this parameter, set <code>appType</code> field of the <code>ClEoConfigT</code> to either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
 For example,
<code><pre>
clEoConfig.appType = CL_EO_USE_THREAD_FOR_RECV
</pre></code>

<li>Range - You can define the value of this parameter as either <code>CL_EO_USE_THREAD_FOR_RECV</code> or <code>CL_EO_USE_THREAD_FOR_APP</code>.
</ul>

===Configuring Memory===

This section provides information about configuring the memory profiles and specify the total memory space and the watermarks for the total memory consumption for each component instance.

====Heap and Buffer Memory Profiles====

The following are the configurable parameters for heap and buffer memory profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE.

'''heapConfig name'''

This is the name for the heap memory profile.

'''bufferConfig name'''

This is the name for the buffer memory profile.

'''mode'''

This indicates the type of the heap allocation mode. The values that can be provided are:
* '''NM''': This is the Native C Mode. In this mode, all requests are served by calling the C library memory allocation interface.
* '''PAM''': This is the Pre Allocated Mode. It is the OpenClovis provided implementation of the memory management library. A large chunk of the memory is pre-allocated during component initialization. The memory space is divided into pools of diverse memory chunks and serves run-time dynamic memory allocation requests.
* '''CM''': This is the Custom Mode. You can plug-in customized memory management library calls.

'''lazyMode'''

You can configure the pool in lazy mode for total memory consumption. Set the value to true or false.

When a pool exhausts its current allocation, it can still grow provided the dynamic memory space or the pool upper limit is not reached. It expands or grows by the increment size specified for the pool. In Lazy Mode, the incremented pool does not initialize until an allocation is made from that pool. In normal mode, the incremented pool initializes as soon as it is acquired by the memory management library.

The following parameters can be configured for a heap and buffer memory pools. The values are expressed in bytes.
* '''chunkSize''' = Maximum size of one allocation from the pool.
* '''initialSize''' = Initial pool size for this pool.
* '''incrementSize''' = When the pool usage exceeds the initial size, the pool size grows by the increment size, unless the max limit is already reached or the total dynamic memory space is reached.
* '''maxSize''' = Maximum pool size for this pool.

====Memory Configuration Profiles====

The following are the configurable parameters for memory configuration profiles located in <code><project_area>/<model>/src/config/clEoDefinitions.xml</code> file. This file is generated through OpenClovis IDE. These parameters are used to set the total memory usage space and the watermarks on the total memory consumption for each component instance.

'''memoryConfig name'''

This is name for the memory profile.

'''processUpperLimit'''

This is the upper limit for the total memory consumption. The value is expressed in bytes. The dynamic memory allocation cannot exceed this limit.

Three levels of watermark are provided high, medium, and low. For each level of watermark, the following attributes can be configured:

* '''lowLimit''' = Memory limit value for downward crossing in percentage.
* '''highLimit''' = Memory limit value for upward crossing in percentage.
For each watermark the following set of actions can be set to true or false:
* '''event enable''' = If the lowLimit value or highLimit value is reached, an event is generated.
* '''notification enable''' = If the lowLimit value or highLimit value is reached, a notification is generated.
* '''log enable''' = If the lowLimit value or highLimit value is reached, a log is generated.
* '''custom enable''' = If the lowLimit value or highLimit value is reached, userdefined custom function is called.

====Assigning Memory Profiles====

Memory profiles are assigned to components in the clEoConfig.xml file located in <code><project_area>/<model>/src/config/clEoConfig.xml</code> in the source code or in <code>$(ASP_DIR)/etc</code> on the target. This file is generated by the OpenClovis IDE, and so these values are better modified through the IDE.

The file contains one XML tag per component of the following format:

<eoConfig name="LOG">
<eoMemConfig heapConfig="Default" bufferConfig="Default" memoryConfig="Default"/>
<eoIocConfig/>
</eoConfig>

The "eoConfig" tag delimits all configuration for one component and has one field:

* '''name''': This is the name of the SAFplus Platform component or user application.

The "eoMemConfig" tag specifies memory profiles by name through 3 fields:

* '''heapConfig''': This is the heap memory profile that is assigned to the SAFplus Platform component or user application.

* '''bufferConfig''': This is the buffer memory profile that is assigned to the SAFplus Platform component or user application.

* '''memConfig''': This is the memory configuration profile that is assigned to the SAFplus Platform component or user application.

===Configuring Remote Method Dispatch (RMD)===

RMD comprises only one configurable parameter:

'''gClRmdMaxRetries'''

This parameter allows you to define the default value for maximum number of retries for calling a remote function.
<ul>

<li>Format - The constant <code>gClRmdMaxRetries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example:
<code><pre>
#define gClRmdMaxRetries 0
</pre></code>

<li>Range - You can define the maximum retries in the following range:
*Minimum = 0
*Maximum = 2^32-1
*Default = 8
</ul>

===Configuring Clovis Object Registry (COR)===

The configuration information for COR is generated by IDE in the <code>clCorConfig.xml</code> file. There are two configuration parameters for COR. First is the corOHMask and the other one is corSaveOption. Both of these are described below:

====COR object handle Mask (corOHMask)====

This is the COR Object Handle mask used to get the compressed version of the MOID of a MO object. The MOID comprises pairs of <code>{class Id, Instance Id}</code> traversed from root to the object.

Storing the MOID for each object can be expensive since class Id and Instance Id both take four bytes each. Looking at the tree hierarchy there can be very few nodes at the top, which may not need full eight bytes of memory space. So, to store the MOID efficiently the MOID is compressed and stored in object handle. By specifying the mask, you will know the maximum number of classes and instances that you have at each level of Instance Tree starting from Root.

The number of entries in the OH mask are always even. It contains pair of values for every level, where first one denotes the maximum number classes at any level and second one denoting the maximum number of instances that can be created for that class at that level. This maximum number in both the cases is calculated by ((2^number) -1 ). Also the number of pairs in the OH mask shows the depth of the object tree allowed for this information model.

Suppose the OH mask is {a, b, c , d}, then we can make out following things from it :
# There can be only two level of object tree possible from this.
# At first level there can be (2^a)-1 classes can be created and each class can have (2^b)-1 instances. Similarly for the second level (2^c)-1 classes can be present and each class can have (2^d)-1 instances.

Few important things about OH mask :
* The number of pairs in the OH mask can go upto only 20 level as the MOID can only access an object tree of depth 20.
* The total of all the values in the OH mask should not exceed 48. This magic number comes from the number of bits used in the structure ClCorObjectHandleT for storing the object handle. The number of bits that are used in this structure to store the classId and instance Id information is 48.

<ul>
<li>Format - Following is an example of <code>corOHMask</code>:
<code><pre>
corOHMask={4, 8, 4, 8, 4, 8, 4, 8}
</pre></code>
 Here you can tell that at level 0 (The level after root), there can be maximum of (2^4)-1 = 15 classes and (2^ 8)-1 = 255 instances per class.
 [[File:OpenClovis_Note.png]]This parameter should not changed manually as this is generated by the IDE during modeling time. Any manual change should be done at your discretion.
</ul>

====COR Repository Save Option (corSaveOption)====

This is the COR persistency option. This can take two values :
* '''CL_COR_DELTA_SAVE''' : which signifies that the all the delta changes in the COR repository during runtime should be persisted. These information will be restored by COR once it is restarted.
* '''CL_COR_NO_SAVE''' : This option tells COR that the information need not be persisted at runtime nor restored at restart.

===Configuring Log Service===
The configuration information for Log Service is generated by IDE in the [[log.xml]] file. The configuration of log service has been split into three sections. There are as follows.
* [[#Log service common config parameters|Log service common config parameters]]
* [[#Log service perennial stream config parameters|Log service perennial stream config parameters]]
* [[#Log service precreated stream config parameters|Log service precreated stream config parameters]]

====Log service common config parameters====
These values are specific and common to log services running on the cluster. The following are the configurable parameters of the Log service.

'''maximumStream'''
The value of this tag specifies the maximum number of streams can be created at log service which is running on the local node. This number is configurable by the administrator based on the memory availability of the system.

'''maximumComponents'''
The value of this tag specifies the maximum number of components(loggers) can be at the cluster. This number is configurable by the administrator.

'''maximumSharedMemoryPages'''
The value of this tag specifies the maximum number of shared memory should be allocated for new stream. This is basically talking about the size of the shared memory. This should be configurable by keeping mind the size of the record and flush frequency.
FIXME- warning.

'''maximumRecordsInPacket'''
The value of this tag specifies the maximum number records can be flushed from log server to the file. At any point of time, these many records will be multicasted by log service to the file owners.

 [[image:OpenClovis_Note.png]] These above values should not be changed at run time.

====Log service perennial stream config parameters====
When the log server comes up with SAFplus Platform, two default perennial streams will be created and predefined handles will be
populated. Any SAFplus Platform component/application can use this default streams for logging. These two streams are local streams.

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

====Log service precreated stream config parameters====
When the log server comes up with SAFplus Platform, these given precreated streams will be created and handles will not be known to the user. Any SAFplus Platform component/application can open this stream and use it. If the stream is configured as GLOBAL streams then the same configuration should be available on all the nodes in the cluster.

'''streamName'''
This value of the tag specifies the name of the precreated stream. This can be any valid name.

'''streamScope'''
This value of the tag specifies the scope of the precreated stream. One of the following varibale will be a valid
value for this tag.
* LOCAL
* GLOBAL

'''fileName'''
The value of this tag specifies the name of the file should be created for this perennial streams. Any valid file names are configurable by administrator.

'''fileLocation'''
The value of this tag specifies the log file location. Format of this filelocation is <nodname>:<path>, where node name is name of the node instance in which file will be created under the path directory. If path is start with '/'
then log service treats the path as absolute path, else this file location is prepended with the environment variable <code>ASP_DIR</code>. The directory is created by the Log Server if it does not exist. This name is configurable by the administrator.

* If nodename is '*' <star> , then the file will be created where the system controller active is running.
* If nodename is '.' <dot>, then the file will be created in the local node.

'''fileUnitSize'''
The value of this tag specifies the size of the log file in bytes. When the file size is reached its specified limit, the given file full action will be applied on the file.

'''record size'''
The value of this tag specifies the size of the record (single log message) in bytes.

'''fileFullAction'''
The value of this tag specifies the action should be taken when the file reaches its specified limit. It can take one of the following values
* HALT
* WRAP
* ROTATE

'''maximumFilesRotated'''
The value of this tag specifies the maximum number of files will be created, incase the file full action is ROTATE.
If the file full action is not ROTATE, then this value will be ignored.

'''flushFreq'''
The value of the tag specifies number of Log Records after which the Log Stream must be flushed. This is the maximum number of records on a node which are still not persisted at any given point in time. Log Service make best effort to ensure that no more than flushFreq no of records will be lost if a node fails. A value of zero indicates that this field is ignored and Log Records are flushed based on flushInterval. At least one of flushFreq and flushInterval must be non-zero for a Log Stream.

'''flushInterval'''
The value of the tag specifies time in nanoseconds after which the Log Stream must be flushed. This is the maximum time a Log Records can stay in a Log Stream un-persisted. Log Service guarantees that Log Records generated at least this much time before a node failure will not be lost on a node failure. A value of zero indicates that this field is ignored and Log Records are flushed based on flushFreq. At least one of flushFreq and flushInterval must be non-zero for a Log Stream. This field will be ignored by default. If the user configures lockMode is mutex, then this field will be considered.

===Configuring Group Membership Service (GMS)===

 The following parameters are located in <code><project_area>/<model>/src/config/gmsConfig.xml</code> file.

The following are the configurable parameters of GMS service:
* '''ClusterName''': name of the cluster
* '''MulticastAddress''': Multicast IP address used by GMS to exchange multicast messages with its peer GMS servers.
* '''MulticastPort''': Port on which GMS server binds and listens to the multicast messages from its peer GMS servers
* '''linkname''': Name of the Link to be used. For example, eth0, eth1, eth2 and so
* '''MaxNoOfGroups''': Maximum number of groups to allow in the cluster. Min = 0, Max = 256, Default = 10.

'''Note:''' Please note that the value of MulticastAddress and MulticastPort parameters should be same across all the nodes in a cluster.

===Configuring Name Service===

The following configurable parameters of Name Service are located in <code><project_area>/<model>/src/config/clASPCfg.c</code> file.

'''gClnsMaxNoEntries'''

This attribute provides the maximum number of entries that can be registered in a given context.
<ul>
<li>Format - The constant <code>gClnsMaxNoEntries</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoEntries 256
</pre></code>

<li>Range - Default value is 256. You can define any value between integers 1 to 2^32-1
*Minimum = 1
*Maximum = 2^32-1
*Default = 256
</ul>

'''gClnsMaxNoGlobalContexts'''

This attribute provides the maximum number of user-defined global contexts you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoGlobalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoGlobalContexts 10
</pre></code>

<li>Range - Default value is 10. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 10
</ul>

'''gClnsMaxNoLocalContexts'''

This attribute provides the maximum number of user-defined local contexts that you can create.
<ul>
<li>Format - The constant <code>gClnsMaxNoLocalContexts</code> must be defined in the <code>clASPCfg.c</code> file.
 For example
<code><pre>
#define gClnsMaxNoLocalContexts 2
</pre></code>

<li>Range - Default value is 2. You can define any value between integers 0 to 2^32-1
*Minimum = 0
*Maximum = 2^32-1
*Default = 2
</ul>

Doc:Sdkguide/infrastructure

2007-10-09T17:18:19Z

Agnes: /* Components of Infrastructure Layer */

=='''Infrastructure of OpenClovis SAFplus'''==

This chapter covers the following topics in detail:

'''Key Topics:'''
* [[#Components of Infrastructure Layer | Components of Infrastructure Layer]]
* [[#Componentization | Componentization]]
* [[#Execution Entities | Execution Entities]]
* [[#SAFplus Platform Distributed Infrastructure | SAFplus Platform Distributed Infrastructure]]
* [[#Componentization Process | Componentization Process]]
* [[#Component Characteristics | Component Characteristics]]
* [[#Component Initialization | Component Initialization]]
* [[#Using Availability Management Framework (AMF) | Using Availability Management Framework (AMF)]]
* [[#Characteristics of a Sample Application | Characteristics of a Sample Application]]
* [[#Sample Code for Componentization | Sample Code for Componentization]]

===Components of Infrastructure Layer===

OpenClovis Infrastructure Layer consists of libraries required for the system. It comprises the following components:
* [[#Operating System Abstraction Layer (OSAL) | Operating System Abstraction Layer (OSAL)]]
* [[#Hardware Platform Interface (HPI) | Hardware Platform Interface (HPI)]]
* [[#Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]
* [[#Execution Object (EO) | Execution Object (EO)]]
* [[#Log Service | Log Service]]
* [[#Transaction Manager (TM) | Transaction Manager (TM)]]
* [[#Basic Infrastructure Core | Basic Infrastructure Core]]
** [[#Buffer Manager Library | Buffer Manager Library]]
** [[#Heap Memory | Heap Memory]]
** [[#Timer Library | Timer Library]]
** [[#Containers | Containers]]
** [[#Circular List | Circular List]]
** [[#Queue Library | Queue Library]]
** [[#Rule-Based Engine (RBE) | Rule-Based Engine (RBE)]]
* [[#Interface Definition Language (IDL) | Interface Definition Language (IDL)]]

====Operating System Abstraction Layer (OSAL)====

The OpenClovis Operating System Abstraction Layer (OSAL) provides a standard interface to commonly used operating system functions. OSAL supports target operating systems like most variations of Carrier Grade Linux.

'''Features'''

* Easily adaptable to any proprietary target operating system.

'''How it works'''

All OpenClovis SAFplus Platform components are developed based on OSAL that provide an OS agnostic function to all system calls, such as memory management and thread management functions. Internally, OSAL maps such functions to the respective equivalent system calls provided by the underlying OS. This allows OpenClovis SAFplus Platform as well as all OpenClovis SAFplus-based applications to be ported to new operating systems with no modifications.

OpenClovis SAFplus Platform is delivered with a Posix-compliant adaptation module that allows it to operate to any Posix-compliant system, such as Linux and most UNIX systems.

Software components use the signal handlers provided by OSAL to handle critical UNIX signals. This can automatically inform OpenClovis Component Manager (CPM) about the signal and generate a fault, or trigger necessary recovery actions. OSAL is currently designed as a standalone library with no dependencies on any other OpenClovis SAFplus Platform components.

====Hardware Platform Interface (HPI)====

The OpenClovis Hardware Platform Interface (HPI) provides a programmatic interface to manage and monitor a system.

'''Features'''

* It manages only the lifecycle of the hardware platform and not the application for which the specific hardware is being used.
* In a OpenClovis SAFplus-enabled system, HPI is used for platform management and HAL is used for modeling and managing the application specifics of the hardware.

'''How it Works'''

HPI also allows the platform specific aspects of a blade to be discovered at run time without explicitly modeling it during the design process.

====Database Abstraction Layer (DBAL)====

The OpenClovis Database Abstraction Layer (DBAL) provides a standard interface for any OpenClovis SAFplus Platform infrastructure component or application to interface with the commonly used relational database.

'''Features'''

* DBAL currently supports only the GNU Database Manager (GDBM).

'''How it Works'''

The primary user of this interface is the COR component which can dump or read its object repository to and from a database for either persistent storage or offline processing. DBAL is also a standalone library with no dependencies on any other OpenClovis SAFplus Platform components.

====Execution Object (EO)====

The OpenClovis Execution Object (EO) encapsulates each distinct SAFplus-aware software component and provides an execution environment for the components.

'''Features'''

* Provides a uniform interface between the software component and the rest of the system components.
* The interfaces fall into the following two categories:
** '''Management Interface''': This interface is used to control and configure the software components.
** '''Service Interface''': This interface allows software components to expose component specific functionality.

'''How it Works'''

Both management and service interfaces are exposed using RMD APIs. EO provides threads for receiving RMD messages and worker threads to process them. The components encapsulated by EO communicate to other such components using Communication Core components such as Event Manager (EM), Remote Method Dispatch (RMD), Intelligent Object Communication (IOC), and Name Service.

====Log Service====

The OpenClovis Log Service collects, translates, and publishes log messages to record any significant event in the system. For instance, operational state change of a component, managed object attribute value change, and so on.
 [[File:OpenClovis_Info.png]]The log service supports syslog and logging facility.

'''Features'''

* Log analyzes the proper system behavior and registers the potential unintended operations.
* Log-levels can be changed during the operation.

====Transaction Manager (TM)====

The OpenClovis Transaction Manager (TM) provides an infrastructure library for resource managers to use transaction semantics to manage distributed data. Any component that wishes to be a part of transactions can link with this library and act as a resource manager.

'''Features'''

* Supports re-startable transactions. For instance, if any transaction participant fails, data recovery mechanism helps to recover the application state using the transaction logs for enhanced availability.

'''How it works'''

It automatically tracks participants and provides ACID semantics to ensure that all participants are updated properly, or will rollback to previous state assuring data integrity despite component failures.

====Basic Infrastructure Core====

The Basic Infrastructure Core (BIC) comprises libraries and functions required for the system. It provides essential basic services to all the OpenClovis software, utilities, and other customized applications.BIC includes the following software libraries (APIs):
* [[#Buffer Manager Library | Buffer Manager Library]]
* [[#Heap Memory | Heap Memory]]
* [[#Timer Library | Timer Library]]
* [[#Containers | Containers]]
* [[#Circular List | Circular List]]
* [[#Queue Library | Queue Library]]
* [[#Rule-Based Engine (RBE) | Rule-Based Engine (RBE)]]

=====Buffer Manager Library=====

The OpenClovis Buffer Manager Library is designed to provide an efficient method of user-space buffer and memory management to increase the performance of communication-intensive OpenClovis SAFplus Platform components and user applications. It contains elastic buffers that expand based on application memory requirement.

=====Heap Memory=====

Heap memory is used for dynamic memory allocation. Memory is allocated from a large pool of unused memory area called the heap. The size of the memory allocation can be determined at run-time.

=====Timer Library=====

The OpenClovis Timer Library enables you to create multiple timers to execute application specific functionality after certain intervals. It performs the following functions:
* Creates multiple timers.
* Specifies a time-out value for each timer.
* Creates one-shot or repetitive timers.
* Specifies an application specific function that should be executed every time the timer fires or expires.

[[File:OpenClovis_Note.png]]The operating systems such as Linux or BSD supports limited number of timers that can be created in an application. However, an application such as OSPF and BGP requires a lot of timers at various points during its execution of the application.

=====Containers=====

The OpenClovis Container Library provides basic data management facilities by means of container abstraction. It provides a common interface for all Container types.

It supports three types of containers listed as follows:
* Doubly linked list
* Hashtable (supports open-hashing)
* Red-Black trees (balanced binary tree)

=====Circular List=====

The OpenClovis Circular List provides implementation of circular linked list and supports addition, deletion, and retrieval of node and walks through the list.

=====Queue Library=====

 The OpenClovis Queue Library provides implementation for an ordered list. It supports enqueuing, dequeuing, and retrieval of a node and walk through the queue.

=====Rule-Based Engine (RBE)=====

The OpenClovis Rule-Based Engine (RBE) provides a mechanism to create rules to be applied to the system instance data, based on simple expressions.

An expression consists of a mask and a value. These expressions are evaluated on user data and generate a Boolean value for the decision process.

For instance, RBE is used by the Event Service to support filter-based subscriptions. The event is published with a pattern that is matched against the filter provided by the subscribers. Only those subscribers that match successfully are notified. The RBE library provides simple bit-based matching based on the flags specified.

=====Interface Definition Language (IDL)=====

The OpenClovis Interface Definition Language (IDL) is a library used by all EOs to communicate efficiently across nodes. Using IDL, OpenClovis SAFplus Platform services can communicates across endian machines and mixed mode (32-bit and 64-bit architecture). IDL is a wrapper over RMD and supports RMD functionality to provide communication across EOs.

===Componentization===

Componentization is a mechanism that enables the user application to communicate with OpenClovis SAFplus Platform. These applications can be componentized and managed for administering the lifecycle of a component, for using the manageability features of OpenClovis SAFplus Platform, or for attaining high availability.

====Significance of Componentization====

The two most common software entities within the execution context are the '''processes''' and the '''threads'''. In most systems, processes are isolated from each other, whereas failure in a thread causes other threads to be affected also.

In UNIX, the interaction between the OS and a process is passive. The OS starts up the process, sets up its environment and executes its main function. This enables the process to execute without any direct interference from the OS. It can either enter into an infinite loop or choose to intermittently request for services from the OS. Since the OS is unaware of the process' internals, it reacts only when it receives service requests from the process. The mechanism for proactively sending information to the process is using signals.

However, this is not the only model for OS to process communication and has certain limitations:
* If the OS wants full control over the complete lifecycle of a process - as found in a carrier grade system.
* Higher level of service availability cannot be achieved without considering the application-specific constraints. The OS and application need to co-operate with the lifecycle of the application.

From a functional perspective, the OS needs the ability to invoke multiple well-defined functions within a process. It must provide a generic and high bandwidth scheme for bi-directional OS to application communication.

The OS to application communication can be done with either a synchronous remote function call paradigm, which creates a tight binding between the OS and the process, or a de-linked, asynchronous message based model. The asynchronous, message based model can be more efficient and deadlock safe than the function call model. However, it can also create queues and code organization issues when used for high latency functions.

Significantly, in a system with either of these approaches, a process' internal organization changes from having a linear, synchronous flow to an asynchronous, event driven flow. It is the difference between writing a console application and a windowing application that must respond to asynchronous events.

====Features of Componentization====

Componentization provides the following features:
* Facilitates Communication
* Statistics gathering and profiling
* Resource Management
* Debugging

===Execution Entities===

An execution entity is a form of a process, a task or a thread that contains a set of data and an execution context. The execution entities running in the system without external communication is not very effective in the system, unless it is capable of interacting with other execution entities. As the execution entities are distributed in nature, they need a common mechanism to facilitate the communication between them.

'''Constituents of Execution Entity'''

The execution entity mainly consists of:
* Attributes and methods to manage the entity.
* A mechanism to communicate with external execution entities.
* Implementation of the entity specific to its responsibilities.

OpenClovis Inc. provides the first two functionalities encapsulated within the '''Execution Object (EO)'''. The Execution Object comprises all the common attributes and methods used to represent the execution entity in the system. The communication with the external entities is provided by creating a background thread that receives the messages on behalf of the execution entity. These messages are decoded and the corresponding methods within the execution entity are invoked.

====Execution Object (EO)====

OpenClovis Execution Object (EO) encapsulates each distinct SAFplus-aware software component and provides an execution environment for the components. It provides a uniform interface between the software component and the rest of the system components.

The interfaces fall into the following two categories:
* '''Management Interface''': This interface is used to control and configure the software components.
* '''Service Interface''': This interface allows software components to expose component specific functionalities.

With the help of Componentization, both management and service interfaces are exposed using RMD APIs. EO provides receiver threads for picking up messages from RMD and worker threads for processing them. It also provides an execution environment for the software component and allows it to be managed by the Component Manager.

The components encapsulated by EO communicate with other components using OpenClovis Communication Core components such as Event Manager (EM), Remote Method Dispatch (RMD), Intelligent Object Communication (IOC), and Name Service.

====EO Infrastructure====

The desired process model for a carrier grade system is the asynchronous event driven model. This can enabled in two ways:
* Write a new OS that natively supports this model.
* Design a low-level middleware that enables process manageability and provides a hook for delivering services to a process in a standard manner but without modification to the base OS.

OpenClovis EO infrastructure is the user space client library and the server infrastructure that enables these capabilities. When this infrastructure is linked into an application, it takes over the application's main function and creates communication links back to the middleware, executing application specific state changes at the behest of the middleware. This model requires some help from the application, which must be written to support multiple threads as well as an asynchronous flow.

'''Characteristics of an EO'''

You can define a "Managed EO" that comprises the following characteristics.
* An EO is a process that is modified to interface with the middleware such as having multiple threads.
* An EO can be manageable by the middleware.
* An EO can use one or more services provided by the middleware.

The EO infrastructure thus consists of an EO client library linked into each process and an EO manager library to manage the client. The client library implements the dispatching loop and manages communication between the application and OpenClovis SAFplus Platform services. Other services link to their client library functions into the EO infrastructure.

Both high level SAFplus Platform and application processes can be Componentized. The resulting applications can be "managed" or "unmanaged" depending on whether the manageability functions in their respective EOs are implemented or kept empty. Although, components like CPM cannot be Componentized as the EO infrastructure is dependent on it. Though many applications can interface with SAFplus Platform using the EO infrastructure, there can be some exceptions where the application may use a light weight library that does not link to the EO infrastructure.

===SAFplus Platform Distributed Infrastructure===

The distributed infrastructure of SAFplus Platform allows different components to communicate with each other agnostic of the computing unit. This inter-component communication is achieved through IOC Linux kernel module. RMD uses services provided by IOC to invoke remote procedure of other components.

The fundamental constituents of OpenClovis SAFplus Platform distributed infrastructure to realize a component comprises:
* '''IOC Port''' - It is a communication port where all the incoming messages are queued. Each component must have an IOC port to communicate with other components and services.
* '''Message Receiver Thread''' - The Message Receiver Thread picks up the messages from the IOC Port and queues it into EO Job Queue to further process the message.
* '''Worker Threads''' - When a message is queued into EO Job Queue the worker threads get invoked. One of these threads picks up the message and calls the corresponding function for this message. After the message is processed and the function is executed, the reply is returned depending on the options specified by you indicating whether it is a synchronous RMD call or an asynchronous RMD call.
* '''Client Tables and Function Tables''' - Each OpenClovis SAFplus Platform client and application client that the EO links can install the client tables by invoking the <code>'''clEoClientInstall'''</code> API. A client Id is used to index into the client table. The client table consists of the services exposed by the client in the form of a Function Table. These clients provide various services that are installed and registered in the Function Tables indexed by the service Id. The service Id combined with the client Id together forms the RMD number that invokes the services through RMD.

===Componentization Process===

The process of Componentization involves the following steps:
* [[#Step 1: Defining the Skeleton of a Component | Step 1: Defining the Skeleton of a Component]] Define the skeleton of a component and describe its lifecycle functions and interface functions. Assign a unique IOC communication port to the component that identifies the execution object.
* [[#Step 2: Defining clEoBasicLibs | Step 2: Defining <code>clEoBasicLibs</code>]] Define the set of OpenClovis SAFplus Platform libraries required by the component.
* [[#Step 3: Initializing the CPM Library | Step 3: Initializing the CPM Library]] Initialize the CPM client library.
* [[#Step 4: Registering the CPM | Step 4: Registering the CPM]] Register the component with CPM infrastructure.
* [[#Step 5: Un-registering the CPM Library | Step 5: Un-registering the CPM Library]] Un-register the application from CPM Infrastructure, on exit of the application.
* [[#Step 6: Finalizing the CPM Library | Step 6: Finalizing the CPM Library]] Finalize the CPM client library when the component exits.


'''Step 1: Defining the Skeleton of a Component'''

Using OpenClovis IDE, define a structure with the name as <code>'''clEoConfig'''</code> with the following fields initialized appropriately:
* Component lifecycle management parameters
* Number of receiver threads
* Unique communication port Id associated with the component for communication within the SAFplus Platform infrastructure.

<code><pre>
# define COMP_EO_NUM_THREAD 3
# define COMP_IOC_PORT 0

ClEoConfigT clEoConfig = {
COMP_EO_NAME, /* EO Name */
COMP_EO_THREAD_PRIORITY, /* EO Thread Priority */
COMP_EO_NUM_THREAD, /* No of EO thread needed */
COMP_IOC_PORT, /* Required IOC Port */
COMP_EO_USER_CLIENT_ID, /* Size of the client table */
COMP_EO_USE_THREAD_MODEL, /* Whether to use main thread for EO
* receive or not */
clCompAppInitialize, /* Function callback to initialize the
* application */
clCompAppFinalize, /* Function callback to terminate the
* application */
clCompAppStateChange, /* Function callback to change the
* application state */
clCompAppHealthCheck, /* Function callback to check the
* application health */
};
</pre></code>

Where,
<ul>
<li><code>'''COMP_EO_NAME'''</code> is the name of the component message passing infrastructure also called as the Execution Object (EO). The EO name on every node must be unique.

<li><code>'''COMP_EO_THREAD_PRIORITY'''</code> is the priority of the EO thread.

<li><code>'''COMP_EO_NUM_THREAD'''</code> is the count of worker threads for RMD message processing. This must be greater than or equal to 1.

<li><code>'''COMP_IOC_PORT'''</code> is the unique IOC communication port associated with every component.

<li><code>'''COMP_EO_USER_CLIENT_ID'''</code> is the number of clients that can exist for a given component. You can use this macro <code>COMP_EO_USER_CLIENT_ID</code>, as a default value.

<li><code>'''COMP_EO_USE_THREAD_MODEL'''</code> is the usage of the main thread. This is explained in details in Figure [[#Illustration of the usage of application type | Illustration of the usage of application type]].

<li><code>'''clCompAppInitialize'''</code> is invoked by the OpenClovis SAFplus Platform infrastructure when the componentized application is started. It performs the initialization actions (for example installing EO client tables) for any application that is being componentized. For SA-aware components, after the application is initialized, it informs AMF that it is ready to provide services using <code>clCpmComponentRegister</code> API.

<li><code>'''clCompAppFinalize'''</code> is being deprecated and must be NULL.
<li><code>'''clCompAppStateChange'''</code> is called whenever the application state needs to be changed to <code>SUSPEND</code> or <code>RESUME</code>.
<li><code>'''clCompAppHealthCheck'''</code> is called periodically by Component Manager to check the health of the componentized application. In response to this callback, you need to verify if the application is running properly and fill in the structure passed to it.
</ul>

[[File:SDK_UsageofApplicationType_70.png|frame|center| '''Illustration of the usage of application type''' ]]

[[File:OpenClovis_Note.png]]The application must consider the following while defining the <code>'''clEoConfig'''</code> structure:
* If you select <code>'''COMP_EO_USE_THREAD_MODEL'''</code> as <code>'''CL_EO_USE_THREAD_FOR_RECV'''</code>, the main thread '''must not be''' blocked in the <code>'''clCompAppInitialize'''</code>. It must return after the library is initialized. Later, the main thread will be used for RMD message receive function.
* If you select <code>'''COMP_EO_USE_THREAD_MODEL'''</code> as <code>'''CL_EO_USE_THREAD_FOR_APP'''</code>, the main thread '''must be''' blocked in the <code>'''ClEoAppCreateCallbackT'''</code> or used by the application. It must return only when the <code>'''ClCpmTerminateCallbackT'''</code> is called.


'''Step 2: Defining <code>clEoBasicLibs</code>'''

This structure contains the basic OpenClovis SAFplus Platform libraries required by the component. The first six libraries must always be set to <code>'''CL_TRUE'''</code> ; the remaining can be made <code> '''CL_TRUE'''</code> only if the corresponding services are required by the application. If set to <code>'''CL_TRUE'''</code>, the corresponding libraries will automatically get initialized during component initialization.
<code><pre>
ClUint8T clEoBasicLibs[] = {
CL_TRUE, /* OSAL */
CL_TRUE, /* Timer */
CL_TRUE, /* Buffer */
CL_TRUE, /* IOC */
CL_TRUE, /* RMD */
CL_TRUE, /* EO */
CL_TRUE, /* OM */
CL_FALSE, /* HAL */
CL_FALSE, /* DBAL */
};
</pre></code>

'''Step 2.1: Defining <code>clEoClientLibs</code>'''

This structure contains a list of client libraries which the components can initialize if they need the corresponding service within the SAFplus Platform infrastructure. All the values in this structure are optional. If set to <code>'''CL_TRUE'''</code>, the corresponding libraries will automatically get initialized during component initialization.

<code><pre>
ClUint8T clEoClientLibs[] = {
CL_TRUE, /* Clovis Object Registry */
CL_TRUE, /* Chassis Manager */
CL_TRUE, /* Name Service*/
CL_TRUE, /* Log Service*/
CL_FALSE, /* Trace Service */
CL_FALSE, /* Diagnostic Manager */
CL_TRUE, /* Transaction Manager */
CL_FALSE, /* NA */
CL_TRUE, /* Provisioning Library*/
CL_TRUE, /* Alarm Manager */
CL_TRUE, /* Debug Service*/
CL_FALSE /* Group Membership Service */
};
</pre></code>

When this is defined, the application is componentized. During startup, the stubs generated by OpenClovis IDE does all the necessary things as defined in the above structures.

[[File:OpenClovis_Note.png]]OpenClovis SAFplus Platform libraries linked to the user application require three structures to be defined, otherwise, it will lead to compilation failure.


'''Step 3: Initializing the CPM Library'''

From <code>'''clCompAppInitialize'''</code> callback, you need to initialize the CPM library by calling the <code>'''clCpmClientInitialize'''</code> and provide a structure for callback, defined as <code>'''ClCpmCallbacksT'''</code> in <code>'''clCpmApi.h'''</code> file.
* <code>'''ClCpmHealthCheckCallbackT'''</code> callback: This callback is not implemented by OpenClovis SAFplus Platform for the current release.
* <code>'''ClCpmTerminateCallbackT'''</code> callback: This is called when the application requires to be terminated. In this function callback, the application will clean up its acquired resources.
* <code>'''ClCpmCSISetCallbackT'''</code> callback: This is called when AMF assigns the workload to the application.
* <code>'''ClCpmCSIRmvCallbackT'''</code> callback: This is called when AMF removes the workload from the application.
* <code>'''ClCpmProtectionGroupTrackCallbackT'''</code> callback: This is called when there is a change in the status of the protection group of a particular CSI. The application tracks the status of the CSI using <code>'''clCpmProtectionGroupTrack'''</code> API.
* <code>'''ClCpmProxiedComponentInstantiateCallbackT'''</code> callback: This is called when the proxy component instantiates one or more of its proxied components.
* <code>'''ClCpmProxiedComponentCleanupCallbackT'''</code> callback: This is called when the proxy component clean up one or more of its proxied components.


'''Step 4: Registering the CPM'''

From <code>'''clCompAppInitialize'''</code> callback, you need to register the component by invoking <code>'''clCpmComponentRegister'''</code> API. The component must be registered only when it is ready to provide the services. After the component is registered, it can either provide some specific service or use the services provided by other components. When AMF decides to terminate the component, it calls the <code>'''ClCpmTerminateCallbackT'''</code> callback provided by the application.


'''Step 5: Un-registering the CPM Library'''

From <code>'''ClCpmTerminateCallbackT'''</code> callback, you need to un-register the component by invoking <code>'''clCpmComponentUnregister'''</code> API. The component is un-registered when the component is no longer providing the services. You can cleanup all the associated resources.


'''Step 6: Finalizing the CPM Library'''

From <code>'''ClCpmTerminateCallbackT'''</code> callback, you need to finalize CPM library by calling the <code>'''clCpmClientFinalize'''</code> API.

===Component Characteristics===

An application component in OpenClovis SAFplus Platform infrastructure has the following characteristics:
* Each component has an associated lifecycle and registers the initialization and shutdown functions with OpenClovis SAFplus Platform infrastructure.
* Each component provides implementation of high availability related OpenClovis SAFplus Platform mandated functionality. Each component has a communication port called the IOC port assigned by OpenClovis SAFplus Platform infrastructure to communicate with other components including Event, Checkpoint, Component Manager and so on. IOC manages the IOC port and implements the actual mechanism of sending and receiving messages.
* Each component installs the services into the function table indexed by the service id through the <code>'''clEoClientInstall'''</code> API. This function table is contained in the client table identified by the client id namely, <code>'''CL_EO_NATIVE_COMPONENT_TABLE_ID'''</code> . To use any service of the component, you must use the RMD number that uniquely identifies the service.
* Each component is associated with one or more worker threads. Every message intended to be delivered to a component, is set in a queue by IOC on the corresponding port. This message is then picked up by the receiver thread in EO and queued in the EO Job Queue. One of the worker threads picks up the message, decodes the RMD number, and executes the appropriate interface function.


[[File:SDK_ComponentRealization.png|frame|center| '''Component Realization in OpenClovis SAFplus Platform environment''' ]]

Figure [[#Component Realization in OpenClovis SAFplus Platform environment | Component Realization in OpenClovis SAFplus Platform environment]] explains the elements of OpenClovis SAFplus Platform component.

OpenClovis SAFplus Platform component comprises the following:
<ol>
<li>The function <code>'''cbfn3'''</code> is a callback function that represents the lifecycle function of the component. The lifecycle functions are registered with distributed infrastructure of OpenClovis SAFplus Platform and helps to initialize, finalize, and check the status of the component. These functions facilitate CPM to manage the lifecycle of the component.

<li>The functions <code>'''fn1'''</code> and <code>'''fn2'''</code> are the component interface functions with a unique identifier. These functions are called the service interface of the component and they represent the services that the components can provide.
 [[File:OpenClovis_Note.png]]The function <code>'''fn3'''</code> is a service interface of the CPM component.

<li> <code>'''App2'''</code> can make calls to <code>'''fn1'''</code> and <code>'''fn2'''</code>, component interface function of <code>'''App1'''</code> using RMD of OpenClovis SAFplus Platform distributed infrastructure. The functions <code>'''fn1'''</code> and <code>'''fn2'''</code> are depicted as <code>'''rfn1'''</code> and <code>'''rfn2'''</code> respectively in Figure [[#Illustration of the usage of application type | Illustration of the usage of application type]].
</ol>

The CPM server periodically performs a health check on the component and remotely invokes the CPM client service functionality using RMD. This functionality in turn invokes the health check up callback, illustrated as <code>'''cbfn3'''</code> in Figure [[#Illustration of the usage of application type | Illustration of the usage of application type]], of the component and returns the status to the CPM server.

===Component Initialization===

OpenClovis SAFplus Platform provides a set of libraries that must be initialized for application manageability, high availability, and pre-defined main function for easy usability.

The following are the consequences when a component application is initialized:
#It initializes the basic OpenClovis SAFplus Platform libraries to provide operating system or architecture-independent execution context for the component. It also installs the signal handler to handle all the signals that causes the process termination [for example SIGSEGV, SIGFBP, SIGILL, and so on]. Whenever a signal is generated, signal handler receives the stack trace and signal-related information. The stack trace and the signal information are then moved into the shared memory.
#It creates the communication link.
#It initializes the client libraries so that the component can use the functionality provided by other components of OpenClovis SAFplus Platform. For example, Event, Provisioning and so on.
#It passes the control to the initialization callback function provided in the <code>'''clEoConfig'''</code> structure, where it can implement the specific functionalities exposed by the application.
#If the application holds the main thread, the execution continues with the application. Otherwise, after the initialization callback returns, the main thread waits in a loop to accept messages.
#When OpenClovis SAFplus Platform requires to shutdown a component, based on the policy or during node shutdown, <code>'''ClCpmTerminateCallbackT'''</code> callback is invoked, which requires to follow the steps explained above.


[[File:SDK_ComponentInitialization.png|frame|center| '''Component Initialization sequence diagram''' ]]

[[File:OpenClovis_Note.png]]If you create new threads or tasks, and send messages from the thread context, then <code>'''clEoMyEoObjectSet()'''</code> and <code>'''clEoMyEoIocPortSet()'''</code> must be in the new thread context to set the environment for communication purpose. If not, every RMD returns a failure.

===Using Availability Management Framework (AMF)===

Componentization process helps the applications to interact with the OpenClovis SAFplus Platform infrastructure.

 Applications can be made highly available by providing certain callbacks specific to AMF. AMF requires applications to provide callbacks for lifecycle operations, work assignment operations, and protect group related operations (optional). AMF decides to instantiate and assign workload to a component. The components can be instantiated by calling the <code>'''clCompAppInitialize'''</code> callback of the component. This callback is an indication to the component to start the process.

After the component completes the start process and is ready to receive the work assignments, it informs the AMF framework by invoking the AMF <code>'''clCpmComponentRegister'''</code> API.

Registration process is an indication for AMF that the component have been successfully started and can be assigned work by AMF. On receiving the register callback AMF assigns workload to the component with appropriate high availability state using the CSI set callback API registered in the callback function list using <code>'''clCpmClientInitialize'''</code> API.

The CSI set API informs the component that a given CSI (workload) have been assigned to the component. The CSI contains information about the name-value pairs and HA state assigned to the component. The name value pairs are the names and values that a component requires to start serving the workloads. For example, a name-value pair can be a configuration filename and its path or location of checkpointed data. The high availability state is assigned by the AMF to the component, for example, ACTIVE or STANDBY. The ACTIVE HA state is an indication that the component will be active for the given CSI. The STANDBY high availability state indicates that the component must prepare itself to takeover in case of failures of the ACTIVE component.

After receiving the CSI set request, the component informs the AMF framework after it is completes the processing required for serving the CSI. This response is an indication for the AMF that the component has successfully received the CSI request and is ready to serve the CSI.

HA state can have the following values:
* '''Active''' - This means the component is ready to serve the CSI.
* '''Standby''' - This means that component is on standby for the CSI.
* '''Quiescing''' - This means the component must finish the existing operations and must not take any new assignment. After it has completed serving the existing request, it informs the AMF framework by calling <code>'''Quiescing'''</code> complete API. This is an indication to AMF that the component will not take any new assignment for the CSI and the AMF framework can remove the CSI assignments from this component and send it to other components.

AMF framework can call the CSI remove callback to remove the CSI assignments from the component. Component's response to this API is an indication for AMF to assign the CSI to other component.

AMF also provides API for interested component to track the status of protection group. Protection group comprises all the components that are assigned HA state (Active or Standby) for the CSI. Protection group tracks API allows the interested component to register with the framework indicating the CSI for which it is interested. The AMF framework informs the component whenever there is a change in the protection group by calling the protection group callback.

Proxied components can interact with the AMF framework through a proxy component. Proxy component is an SA-aware component that can communicate with the AMF framework directly. The calls to proxied component pass through the proxy component. All the lifecycle operations, workload operations for proxied component are carried through the proxy component.

===Characteristics of a Sample Application===

The sample application depicts an application to generate Global Sequence Numbers. The following are the characteristics of this component:
* <code>'''clCompAppInitialize'''</code>, <code>'''clCompAppFinalize'''</code>, and <code>'''clCompAppStateChange'''</code> are the lifecycle related functions.
* <code>'''clCompAppHealthCheck'''</code> is the functionality related to High Availability.

===Sample Code for Componentization===

<code><pre>
---------------------------------------------------------------
clCompAppMain.h
---------------------------------------------------------------
#ifndef CL_COMP_APP_MAIN
# define CL_COMP_APP_MAIN
# include <clCompCfg.h>
# ifndef COMP_NAME
# error "COMP_NAME is not defined. Bad or missing ./clCompCfg.h"
# endif
ClRcT clCompAppTerminate
(ClInvocationT invocation,
const ClNameT *compName);
ClRcT clCompAppAMFCSISet
(ClInvocationT invocation,
const ClNameT *compName,
ClAmsHAStateT haState,
ClAmsCSIDescriptorT csiDescriptor);
ClRcT clCompAppAMFCSIRemove
(ClInvocationT invocation,
const ClNameT *compName,
const ClNameT *csiName,
ClAmsCSIFlagsT csiFlags);
ClRcT clCompAppInitialize
(ClUint32T argc,
ClCharT *argv[]);
ClRcT clCompAppFinalize();
ClRcT clCompAppStateChange
(ClEoStateT eoState);
ClRcT clCompAppHealthCheck
(ClEoSchedFeedBackT *schFeedback);
#endif
---------------------------------------------------------------
clCompAppMain.c
---------------------------------------------------------------
#include <clCommon.h>
#include <clOsalApi.h>
#include <clIocServices.h>

#include <clRmdApi.h>
#include <clDebugApi.h>
#include <clOmApi.h>
#include <clOampRtApi.h>
#include <clProvApi.h>
#include <clAlarmApi.h>

#include <clEoApi.h>
#include <clCpmApi.h>
#include <clIdlApi.h>
#include <string.h>
#include "./clCompAppMain.h"
#include "clCompA.h"
#if HAS_EO_SERVICES
extern ClRcT idlClientInstall(void);
#endif
ClCpmHandleT cpmHandle;
ClRcT clCompAppTerminate(ClInvocationT invocation, const ClNameT *compName)
{
ClRcT rc;

COMPA_DBG_PRINT(("Inside %s \n", __FUNCTION__));
/*
Do the App Finalization
*/
clAppFinalize();
COMPA_DBG_PRINT(("Unregister with CPM before Exit .................%s\n",
compName->value));
rc = clCpmComponentUnregister(cpmHandle, compName, NULL);
COMPA_DBG_PRINT(("Finalize before Exit ................. %s\n",
compName->value));
rc = clCpmClientFinalize(cpmHandle);
clCpmResponse(cpmHandle, invocation, CL_OK);
return CL_OK;
}
ClRcT clCompAppAMFCSISet(ClInvocationT invocation, const ClNameT *compName,
ClAmsHAStateT haState,
ClAmsCSIDescriptorT csiDescriptor)
{
ClRcT rc = CL_OK;
COMPA_DBG_PRINT(("Inside Function %s \n", __FUNCTION__));
if (haState == CL_AMS_HA_STATE_QUIESCING)
{
/*
TODO make the quiescing complete call after the work assigned is
done
*/
rc = clAppSetQuiescingState(invocation, compName, csiDescriptor);
COMPA_DBG_PRINT(("######## before clCpmCSIQuiescingComplete for "
"%s ########\n", COMP_EO_NAME));
clCpmCSIQuiescingComplete(cpmHandle, invocation, rc);
}
else if (haState == CL_AMS_HA_STATE_ACTIVE)
{
rc = clAppSetActiveState(invocation, compName, csiDescriptor);
COMPA_DBG_PRINT(("######## before clCpmResponse(ACTIVE) for "
"%s########\n", COMP_EO_NAME));
clCpmResponse(cpmHandle, invocation, rc);
}
else if (haState == CL_AMS_HA_STATE_STANDBY)
{
rc = clAppSetStandbyState(invocation, compName, csiDescriptor);
COMPA_DBG_PRINT(("######## before clCpmResponse(STANDBY) for "
"%s########\n", COMP_EO_NAME));
clCpmResponse(cpmHandle, invocation, rc);
}
else
{
COMPA_DBG_PRINT(("######## before clCpmResponse(%d) for %s########\n",
haState, COMP_EO_NAME));
clCpmResponse(cpmHandle, invocation, CL_OK);
}
if (CL_OK != rc)
{
COMPA_DBG_PRINT(("clCompAppAMFCSISet failed with %d for %s\n", rc,
COMP_EO_NAME));
}
return CL_OK;
}

ClRcT clCompAppAMFCSIRemove(ClInvocationT invocation, const ClNameT *compName,
const ClNameT *csiName, ClAmsCSIFlagsT csiFlags)
{
ClRcT rc = CL_OK;
COMPA_DBG_PRINT(("Inside Function %s \n", __FUNCTION__));
/*
TODO stop the work assigned before making the response done
*/
rc = clAppCSIRemove(invocation, compName, csiName, csiFlags);
clCpmResponse(cpmHandle, invocation, rc);
return CL_OK;
}
/*
Service Initialization:
1. Initialize your counter and create mutex.
2. Register Name and generate Logical Address
3 Initialize Checkpoint Service
*/
ClRcT clAppInitialize(ClCpmHandleT cpmHandle)
{
ClRcT rc = CL_OK;
ClNameSvcRegisterT nameRegInfo = { {0} };
ClEoExecutionObjT *pEoObj = NULL;
ClNameT compName = { 0 };
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_DEBUG,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_0_INIT_ENTER);
gAppGlobal.version.releaseCode = 'B';
gAppGlobal.version.majorVersion = 0x01;
gAppGlobal.version.minorVersion = 0x01;
gAppGlobal.ckptName.length = sizeof(CKPT_NAME);
strncpy(gAppGlobal.ckptName.value, CKPT_NAME, strlen(CKPT_NAME));
gAppGlobal.cpmHandle = cpmHandle;
gAppGlobal.ckptHdl = -1;
/*
counter is initialized here
*/
gAppGlobal.count = 0;
rc = clOsalMutexCreate(&gAppGlobal.mutex);
if (rc != CL_OK)
{
COMPA_DBG_PRINT(("Failure in mutex create [0x %x]", rc));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_ERROR,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_1_MUTEX_CREATE_FAILED, rc);
return rc;
}
/* register your name with Name Service and get the logical address */
rc = clCpmComponentNameGet(gAppGlobal.cpmHandle, &compName);
if (CL_OK != rc)
{
COMPA_DBG_PRINT(("Failure in component name get [0x %x]", rc));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_ERROR,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_1_NAME_GET_FAILED, rc);
goto mutexCleanup;
}
rc = clCpmComponentIdGet(gAppGlobal.cpmHandle, &compName,
&gAppGlobal.compId);
if (CL_OK != rc)
{
COMPA_DBG_PRINT(("Failed to get the component ID [0x %x]", rc));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_ERROR,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_1_ID_GET_FAILED, rc);
goto mutexCleanup;
}
nameRegInfo.name.length = strlen(COMP_A_SERVICE_NAME);
strcpy(nameRegInfo.name.value, COMP_A_SERVICE_NAME);
nameRegInfo.compId = gAppGlobal.compId;
nameRegInfo.priority = CL_NS_PRIORITY_HIGH;
nameRegInfo.attrCount = 0;
gAppGlobal.nameObjRef = CL_NS_GET_OBJ_REF;
rc = clNameRegister(gAppGlobal.nameCntxId, &nameRegInfo,
&(gAppGlobal.nameObjRef));
if (rc != CL_OK)
{
COMPA_DBG_PRINT(("Failed to register with name [0x %x]", rc));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_ERROR,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_1_NAME_REGISTER_FAILED, rc);
goto mutexCleanup;
}
else
{
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_DEBUG,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_0_NAME_REGISTERED);
}
/*
Initialize the Checkpoint Service
*/
rc = clCkptInitialize(&gAppGlobal.ckptSvcHdl, NULL, &gAppGlobal.version);
if (rc != CL_OK)
{
COMPA_DBG_PRINT(("Failed in checkpoint initialize rc [0x %x]", rc));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_ERROR,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_1_CKPT_INIT_FAILED, rc);
goto nameCleanup;
}
rc = clEoMyEoObjectGet(&pEoObj);
if (rc != CL_OK)
{
COMPA_DBG_PRINT(("Failed to get the EoObject rc [0x %x]", rc));
goto ckptCleanup;
}
gAppGlobal.pEoObj = pEoObj;
rc = compADebugRegister(gAppGlobal.pEoObj);
if (rc != CL_OK)
{
COMPA_DBG_PRINT(("Failed to register with debug rc[0x %x]", rc));
goto ckptCleanup;
}
COMPA_DBG_PRINT(("Sucessfully completed initialization\n"));
clLogWrite(CL_LOG_HANDLE_APP,CL_LOG_DEBUG,COMP_A_SERVICE_NAME,
CL_COMPA_LOG_0_INIT_DONE, rc);
return CL_OK;
ckptCleanup:
clCkptFinalize(gAppGlobal.ckptSvcHdl);
nameCleanup:
clNameComponentDeregister(gAppGlobal.compId);
mutexCleanup:
clOsalMutexDelete(gAppGlobal.mutex);
return rc;
}
ClRcT clCompAppInitialize(ClUint32T argc, ClCharT *argv[])
{
ClNameT appName;
ClCpmCallbacksT callbacks;
ClVersionT version;
ClIocPortT iocPort;
ClRcT rc = CL_OK;
/*
Do the App intialization
*/
/*
Do the CPM client init/Register
*/
version.releaseCode = 'B';
version.majorVersion = 01;
version.minorVersion = 01;
callbacks.appHealthCheck = NULL;
callbacks.appTerminate = clCompAppTerminate;
callbacks.appCSISet = clCompAppAMFCSISet;
callbacks.appCSIRmv = clCompAppAMFCSIRemove;
callbacks.appProtectionGroupTrack = NULL;
callbacks.appProxiedComponentInstantiate = NULL;
callbacks.appProxiedComponentCleanup = NULL;
clEoMyEoIocPortGet(&iocPort);
COMPA_DBG_PRINT(("Application Address 0x%x Port %x\n",
clIocLocalAddressGet(), iocPort));
rc = clCpmClientInitialize(&cpmHandle, &callbacks, &version);
COMPA_DBG_PRINT(("After clCpmClientInitialize %d\t %x\n", cpmHandle, rc));
#if HAS_EO_SERVICES
idlClientInstall();
#endif
/*
Block and use the main thread if required other wise return
*/
/*
TODO: Application code should come here
*/
clAppInitialize(cpmHandle);
/*
if main thread usage policy == CL_EO_USE_THREAD_FOR_APP return from this
function only after app finishes
*/
/*
if main thread usage policy == CL_EO_USE_THREAD_FOR_RECV return from
this function immediately after doing some application initialize stuff
*/
rc = clCpmComponentNameGet(cpmHandle, &appName);
COMPA_DBG_PRINT(("After clCpmComponentNameGet %d\t %s\n", cpmHandle,
appName.value));
rc = clCpmComponentRegister(cpmHandle, &appName, NULL);
COMPA_DBG_PRINT(("After clCpmClientRegister %x\n", rc));
return CL_OK;
}
ClRcT clCompAppFinalize()
{
return CL_OK;
}
ClRcT clCompAppStateChange(ClEoStateT eoState)
{
/*
Application state change
*/
return CL_OK;
}
ClRcT clCompAppHealthCheck(ClEoSchedFeedBackT *schFeedback)
{
/*
Modify following as per App requirement
*/
schFeedback->freq = CL_EO_BUSY_POLL;
schFeedback->status = CL_CPM_EO_ALIVE;
return CL_OK;
}
ClEoConfigT clEoConfig = {
COMP_EO_NAME, /* EO Name */
COMP_EO_THREAD_PRIORITY, /* EO Thread Priority */
COMP_EO_NUM_THREAD, /* No of EO thread needed */
COMP_IOC_PORT, /* Required Ioc Port */
COMP_EO_USER_CLIENT_ID,
COMP_EO_USE_THREAD_MODEL, /* Whether to use main thread for
eo Recv or not */
clCompAppInitialize, /* Function CallBack to initialize
the Application */
clCompAppFinalize, /* Function Callback to Terminate
the Application */
clCompAppStateChange, /* Function Callback to change the
Application state */
clCompAppHealthCheck, /* Function Callback to change the
Application state */
};
/*
You may force default libraries here by using CL_TRUE or CL_FALSE or use
appropriate configuration generated by ClovisWorks in ./clCompAppMain.h The
first 6 basic libraries are mandatory.
*/
ClUint8T clEoBasicLibs[] = {
COMP_EO_BASICLIB_OSAL, /* osal */
COMP_EO_BASICLIB_TIMER, /* timer */
COMP_EO_BASICLIB_BUFFER, /* buffer */
COMP_EO_BASICLIB_IOC, /* ioc */
COMP_EO_BASICLIB_RMD, /* rmd */
COMP_EO_BASICLIB_EO, /* eo */
COMP_EO_BASICLIB_OM, /* om */
COMP_EO_BASICLIB_HAL, /* hal */
COMP_EO_BASICLIB_DBAL, /* dbal */
};
ClUint8T clEoClientLibs[] = {
COMP_EO_CLIENTLIB_COR, /* cor */
COMP_EO_CLIENTLIB_CM, /* cm */
COMP_EO_CLIENTLIB_NAME, /* name */
COMP_EO_CLIENTLIB_LOG, /* log */
COMP_EO_CLIENTLIB_TRACE, /* trace */
COMP_EO_CLIENTLIB_DIAG, /* diag */
COMP_EO_CLIENTLIB_TXN, /* txn */
CL_FALSE, /* NA */
COMP_EO_CLIENTLIB_PROV, /* Prov */
COMP_EO_CLIENTLIB_ALARM, /* alarm */
COMP_EO_CLIENTLIB_DEBUG, /* debug */
COMP_EO_CLIENTLIB_GMS /* gms */
};

#########
</pre></code>