OpenClovis Product Documentation

==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: 
<br>'''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.
<br>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.
<br>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>.
<br>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.
<br>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>
<br>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. 
<br>[[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.
<br>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.
<br>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.
<br>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>libClGDBM.so</FileName>
        <Type>GDBM</Type>
     </Engine-->  
     <!--Engine>
        <FileName>libClBerkeleyDB.so</FileName>
        <Type>BerkeleyDB</Type>
     </Engine-->
     <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>libClGDBM.so</FileName>
        <Type>GDBM</Type>
     </Engine-->  
     <Engine>
        <FileName>libClBerkeleyDB.so</FileName>
        <Type>BerkeleyDB</Type>
     </Engine>
     <!--Engine>
        <FileName>libClSQLiteDB.so</FileName>
        <Type>SQLiteDB</Type>
     </Engine-->
  </Dbal>