OpenClovis Product Documentation - User contributions [en]

Doc:latest/awdguideCrawler

2010-08-27T05:14:05Z

Senthilk:

Table of contents:

* [[Doc:sdk_4.1/awdguide/preface | Preface ]]
* [[Doc:sdk_4.1/awdguide/overview | Overview ]]
* [[Doc:sdk_4.1/awdguide/deppkg | Deployment and Packaging ]]
* [[Doc:sdk_4.1/awdguide/swmgmt | Software Management ]]
** [[Doc:sdk_4.1/awdguide/appbundle | Application Bundle Format ]]
* [[Doc:sdk_4.1/awdguide/pms | Plaftorm Management (ATCA chassis) ]]
* [[Doc:sdk_4.1/awdguide/screens | Screens ]]
** [[Doc:sdk_4.1/awdguide/login | Login ]]
** [[Doc:sdk_4.1/awdguide/frame | AWD Frame and Common Elements ]]
** [[Doc:sdk_4.1/awdguide/nodes | Nodes Page ]]
*** [[Doc:sdk_4.1/awdguide/newnode | New Node Page ]]
** [[Doc:sdk_4.1/awdguide/applications | Applications (SAF Software Bundles) Page ]]
*** [[Doc:sdk_4.1/awdguide/deploy | Application Deployment Page ]]
** [[Doc:sdk_4.1/awdguide/deployments | Deployments (SAF Service Groups) Page ]]
** [[Doc:sdk_4.1/awdguide/programs | Programs (SAF Components) Page ]]
** [[Doc:sdk_4.1/awdguide/upgrade | Upgrade Page ]]
** [[Doc:sdk_4.1/awdguide/nodedetails | Node Details Page ]]
** [[Doc:sdk_4.1/awdguide/deploymentdetails | Deployment Details (Service Group) Page ]]
*** [[Doc:sdk_4.1/awdguide/si | Application Work Details (SAF Service Instance) Page ]]
* [[Doc:Sdk_4.1/awdguide/apiexamples | API Examples]]

Doc:latest/awdguide

2010-08-27T05:13:09Z

Senthilk:

Table of contents:

* [[Doc:sdk_4.1/awdguide/preface | Preface ]]
* [[Doc:sdk_4.1/awdguide/overview | Overview ]]
* [[Doc:sdk_4.1/awdguide/deppkg | Deployment and Packaging ]]
* [[Doc:sdk_4.1/awdguide/swmgmt | Software Management ]]
** [[Doc:sdk_4.1/awdguide/swmgmt#Software_Lifecycle | Software Lifecycle ]]
** [[Doc:sdk_4.1/awdguide/appbundle | Application Bundle Format ]]
* [[Doc:sdk_4.1/awdguide/upgradedirector | Upgrade Director ]]
* [[Doc:sdk_4.1/awdguide/pms | Plaftorm Management (ATCA chassis) ]]
* [[Doc:sdk_4.1/awdguide/screens | Screens ]]
** [[Doc:sdk_4.1/awdguide/login | Login ]]
** [[Doc:sdk_4.1/awdguide/frame | AWD Frame and Common Elements ]]
** [[Doc:sdk_4.1/awdguide/nodes | Nodes Page ]]
*** [[Doc:sdk_4.1/awdguide/newnode | New Node Page ]]
** [[Doc:sdk_4.1/awdguide/applications | Applications (SAF Software Bundles) Page ]]
*** [[Doc:sdk_4.1/awdguide/deploy | Application Deployment Page ]]
** [[Doc:sdk_4.1/awdguide/deployments | Deployments (SAF Service Groups) Page ]]
** [[Doc:sdk_4.1/awdguide/programs | Programs (SAF Components) Page ]]
** [[Doc:sdk_4.1/awdguide/upgrade | Upgrade Page ]]
** [[Doc:sdk_4.1/awdguide/nodedetails | Node Details Page ]]
** [[Doc:sdk_4.1/awdguide/deploymentdetails | Deployment Details (Service Group) Page ]]
*** [[Doc:sdk_4.1/awdguide/si | Application Work Details (SAF Service Instance) Page ]]
* [[Doc:Sdk_4.1/awdguide/apiexamples | API Examples]]
* [[Doc:Sdk_4.1/awdguide/releasenotes | Release Notes]]

Deadpages/Doc:Sdk 5.0/taeguide

2010-08-27T05:11:29Z

Senthilk:

Table of contents:

* [[Doc:sdk_4.1/taeguide/preface | Preface ]]
* [[Doc:sdk_4.1/taeguide/overview | Overview ]]
* [[Doc:sdk_4.1/taeguide/deppkg | Deployment and Packaging ]]
* [[Doc:sdk_4.1/taeguide/testimpl | Testcase Implementation ]]
* [[Doc:sdk_4.1/taeguide/testintg | Testcase Integration]]
* [[Doc:sdk_4.1/taeguide/runtae | Running the TAE ]]
* [[Doc:sdk_4.1/taeguide/reportserver | TAE Report Server]]
** [[Doc:sdk_4.1/taeguide/screens | Screens ]]
*** [[Doc:sdk_4.1/taeguide/projects | Projects ]]
*** [[Doc:sdk_4.1/taeguide/projectSummary | Project Summary ]]
*** [[Doc:sdk_4.1/taeguide/reports | Test Reports ]]
*** [[Doc:sdk_4.1/taeguide/testreport | Test Report in Detail ]]
*** [[Doc:sdk_4.1/taeguide/logfiles | TAE log files and Node postmortem files ]]
*** [[Doc:sdk_4.1/taeguide/models | Models ]]
*** [[Doc:sdk_4.1/taeguide/fixtures | TAE Fixtures ]]
*** [[Doc:sdk_4.1/taeguide/testcases | Testcases ]]

Doc:latest/taeguide

2010-08-27T05:11:29Z

Senthilk:

Doc:latest/taeguide/screens

2010-08-27T05:10:25Z

Senthilk:

==Screens==

Below is a list of some of the screen shots of various tabs present on OpenClovis Test Automation Environment page:

* [[Doc:sdk_4.1/taeguide/projects | Projects ]]
* [[Doc:sdk_4.1/taeguide/projectSummary | Project Summary ]]
* [[Doc:sdk_4.1/taeguide/reports | Test Reports ]]
* [[Doc:sdk_4.1/taeguide/testreport | Test Report in Detail ]]
* [[Doc:sdk_4.1/taeguide/logfiles | TAE log files and Node postmortem files ]]
* [[Doc:sdk_4.1/taeguide/models | Models ]]
* [[Doc:sdk_4.1/taeguide/fixtures | TAE Fixtures ]]
* [[Doc:sdk_4.1/taeguide/testcases | Testcases ]]

Doc:latest/taeguide/reportserver

2010-08-27T05:08:54Z

Senthilk:

TAE report server configuration and monitoring

===Start taereport server ===
<pre>
# cd <TAEBASE>/tae/taereport
# python start-taereport.py
</pre>
You should preferably start this server as a background job.

once TAE report server is started, the interface can be accessed through a browser using URL "http://localhost:5000".

===Server Configuration files and parameters===

*dev.cfg (present in directory <TAEBASE>/tae/taereport) 
It contains several configurations but the configuration which user would be interested is "server port". By default this value is set to 5000

===Report directory===
All TAE reports should be submitted to the directory "<TAEBASE>/tae/taereport/import". taereport server continuously polls for report(s) and if present it processes the report(s) and uploads the processed result(s) to the report server. These reports could be accessed through a browser by opening report server interface using "http://localhost:5000" and then browsing to the correct project and the reports.

* [[Doc:sdk_4.1/taeguide/screens | Screens ]]
** [[Doc:sdk_4.1/taeguide/projects | Projects ]]
** [[Doc:sdk_4.1/taeguide/projectSummary | Project Summary ]]
** [[Doc:sdk_4.1/taeguide/reports | Test Reports ]]
** [[Doc:sdk_4.1/taeguide/testreport | Test Report in Detail ]]
** [[Doc:sdk_4.1/taeguide/logfiles | TAE log files and Node postmortem files ]]
** [[Doc:sdk_4.1/taeguide/models | Models ]]
** [[Doc:sdk_4.1/taeguide/fixtures | TAE Fixtures ]]
** [[Doc:sdk_4.1/taeguide/testcases | Testcases ]]

Doc:latest/taeguide/runtae

2010-08-27T05:08:14Z

Senthilk:

===TAE help===

To know about various TAE options, you can use "tae --help". This provides detailed information about all the TAE options and their usage.
<pre>
# <TAEBASE>/tae/tae --help
</pre>

<pre>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~ OpenClovis Test Automation Environment (TAE) - Version 0.8 ~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Usage:
tae [options] [command]
Options:
-h, --help This help page
fetch
-f, --force Force action despite stamp shows it has been completed in
previous session, but executing unfinished prerequisites
-i, --ignore Ignore prerequisites. Same as -f (--force), but it does not
check for prerequisites. This should be used only if you
specifically want to skip prerequisites.
-q, --quiet Be more quiet (can be issued multiple times)
-v, --verbose Be more verbose (can be issued multiple times)
-s, --suppress
Do not show testcase error details on TAE console output
-u, --unload-tipc
Unload the tipc kernel module before starting SAFplus Platform during the
start stage
-b, --no-nodeinfo
Do not show nodeinfo/bladeinfo for each fixture node. By
default this information is requested and printed for each node
-w <cols>, --width=<cols>
Use this width instead of the actual width of the terminal
when printing results to output
-c, --clean Run a 'make clean' before configure
-r, --revert Run an 'svn revert' on any SVN-based images before running
'svn update' on the tree
--show-config Shows all the config attributes parsed from the config files
and then quits
-o <variable>=[<value>]
Allow manual override of a config attribute
-d Start tae in debug mode. Any Python error will launch a JIT
Python debug (pdb) session, allowing quick code analyzis.
This applies to Python errors in testcases too, which would
otherwise let TAE to continue
-n, --netid Manual override of the TIPC netid that will be used on the
target
-p <port>, --gms-port=<port>
Manual override of the GMS port number used on the target
-m <mcast-ip>, --gms-mcast=<mcast-ip>
Manual override of the GMS multicast IP address
-L, --list List test cases in model
-l <file>, --log=<file>
Put detailed tae log here (default is log/tae.log)
-t <filter>, --testcase-filter=<filter>
Execute test cases matching this filter expression only (by
default all testcases in model are executed). A filter
expression is a testcase identifier, with wildcard characters
also allowed. Examples:
TAE-TST-ACC.TC001
TAE-TST-ACC.TC0??
*-ACC*
*TC001
-T <file>, --testcase-file=<file>
Execute test cases specified in this file. The first word of
each line is treated as a filter expression which will be
matched against testcase ids. Lines started with a comment
character (#) are ignored.
-C <config-file>, --config=<file>
Config file to define the model, fixture, mapping, and other
operational parameters. This information can be provided in
one single file, or can be separated into multiple config
files. To read more than one config file this option can be
used repeatedly. If the same configuration attribute is defined
in more than one file, the last read file takes precedence.
If no config file is specified, tae will attempt to
read all local files with '*.cfg' extensions in alphabetical
order.

Deprecated config file options:
The following four options are still allowed, but their use is deprecated.
Use the -C option instead to read any and all config files.
-E <file>, --environment=<file>
Environment definition config file.
-F <file>, --fixture=<file>
Test fixture config file.
-M <file>, --model=<file>
Model definition config file.
-P <file>, --mapping=<file>
Model node name to fixture node mapping config.

Command:

Command describes what needs to be done in terms of the sequential stages
of a full test run. The following stages are defined (in the order of
progression):

fetch, populate, configure, build, package, deploy, start, test, stop

The following forms are allowed as command:

<stage> Run up to this stage, doing all prerequisites (any previous
stages that were not done yet)

When no command is specified, the last stage (report) is assumed to be the
target stage.

When combined with the -f (--force) option, the command can be in either of
the following forms:

<stage> Redo this stage even if it has been done before. Also do all
prerequisite stages if they have not been completed yet
<stage> Redo all stages from fetch to the named stage, even if all or
some have been done previously.
<stage>: Starting from named stage, redo everything
<st1>:<st2> Redo everything from stage st1 through stage st2

When the -i (--ignore) option used, TAE does not check for prerequisites,
but attempt to run the specified stage or stages. It implies the -f (--force)
option.

The meanings of these stages are:

fetch Fetch model for purpose of test case extract
populate Grab the images and populate working dirs for build
configure Configure the project for target fixture
build Build project for target fixture
package Package project for target fixture deployment
deploy Deploy images to target fixture
start Bring up SAFplus Platform on target fixture
test Run all or selected tests
stop Shut down SAFplus Platform on target fixture

</pre>

===TAE configuration files===
To run TAE with your model, you need to create a directory (rest of the document will refer to this directory using the symbol <TAECFGDIR>). It is generally a good idea to create separate <TAECFGDIR> for testing different models. A <TAECFGDIR> should contain at least following configuration files (these are just sample files, you need to change the configuration according to your requirement):

====mapping.cfg====

<pre>

<map_config ver="1.0.0.0">
<mapping>
<SCNode0 node="node1" role="controller" order="1" asp_dir="/root/simulation/asp1"/>
<SCNode1 node="node2" role="controller" order="2" asp_dir="/root/simulation/asp2"/>
<WorkerNode0 node="node3" role="worker" order="3" asp_dir="/root/simulation/asp3"/>
<WorkerNode1 node="node4" role="worker" order="4" asp_dir="/root/simulation/asp4"/>
<WorkerNode2 node="node5" role="worker" order="5" asp_dir="/root/simulation/asp5"/>
<WorkerNode3 node="node6" role="worker" order="6" asp_dir="/root/simulation/asp6"/>
<WorkerNode4 node="node7" role="worker" order="7" asp_dir="/root/simulation/asp7"/>
<WorkerNode5 node="node8" role="worker" order="8" asp_dir="/root/simulation/asp8"/>
</mapping>
<gms mcast_port="8788" />
<tipc netid="8239" />
</map_config>
</pre>

*Where SCNode0, SCNode1, WorkerNode0, etc are the node instances of the model. You also need to mention the role of the node instance. The "order" field is used to set the order of SAFplus Platform bring up on the nodes. "mcast_port" in gms tag can be used to override the value of "GMS_MCAST_PORT" present in "<model>/src/target.conf" Similarly "netid" in tipc tag can be used to override the value of "TIPC_NETID" (these values will be overridden in the "package" stage of TAE)
*asp_dir attribute is required only when TAE has to run in simulation setup(It deploys the asp images to specified directory), otherwise this attribute has to be removed.

====fixture.cfg====

<pre>
<fixture_config ver="1.0.0.0">
<build_server ip='localhost' os='kubuntu' user='build_user' password='password' />
<nodes>
<node1 ip='10.10.3.10' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node2 ip='10.10.3.20' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node3 ip='10.10.3.30' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node4 ip='10.10.3.40' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node5 ip='10.10.3.50' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node6 ip='10.10.3.60' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node7 ip='10.10.3.90' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
<node8 ip='10.10.3.100' os='wrs-pnele-1.4' crossbuild='i586-wrl-pnele1.4-2.6.14-mpcbl0001' user="root" password="password-of-this-node" />
</nodes>
<description>
HP 14-slot chassis with MPCBL0001 cards
</description>
<lockfile value="/home/build_user/run_tae/test_on_hp/hp_chassis.lock" />

</fixture_config>
</pre>

*Normally the build server (where the SAFplus Platform code along with the model is compiled) is localhost (the same machine from where TAE is being run). One can use any other machine on the network for this purpose by specifying the ip, username and password of that machine. <nodes> tag contains the information about the machines where SAFplus Platform will be running during the test run.
*"crossbuild" attribute in node<number> tag is used for the purpose of building the SAFplus Platform binaries for the machine which is architecturally different than the build machine. The value of "crossbuild" attribute should be the name of the toolchain present for that kind of achitecture (located in <sdk-dir>/buildtools/"). If architecture of build and target machine are same, then "crossbuild" field has to be removed.
*lockfile tag can be used to maintain the integrity of the test. Once specified it doesn't allow any other test to use the same fixture. This way you can avoid interrupting an already running test on the same fixture.
*simulation value is used only when tae has to be run in simulation mode i.e. more than one node on same machine.

====model.cfg====

<pre>
<model_config ver="1.0.0.0">
<project value="CLASP3.1" />
<models>
<amsTestGeneric>
<image_source value="dir:~/run_tae/test_on_hp/asptest3.1/" />

<make_options value="AMS_PERF_TEST=1" />
</amsTestGeneric>
</models>

<asp>
<image_source value="dir:~/run_tae/test_on_hp/clasp3.1/" />


</asp>

<testcase_dir value="~/run_tae/test_on_hp/asptest3.1" />

<buildserver>
<sdk_root_dir value="/opt/clovis" />
<asp_dir value="~/run_tae/test_on_hp/clasp3.1" />
<project_dir value="~/run_tae/test_on_hp/asptest3.1" />
</buildserver>


</model_config>
</pre>

* This file contains the model specific configurations like model name, make options, source code directory etc. In the above sample file "amsTestGeneric" is the model name.

* Below are the description of all the tags in the model.cfg file:
** <image_source>: In this attribute, we have to specify the location of SAFplus Platform source code and model directory. This can be any directory on build server (In the example it is ~/run_tae/test_on_hp/clasp3.1/ directory on build server) or it can be the path from where we have to checkout from SVN or any other repository or it can be any link on internet or ftp details.
** <make_options>: In this tag we provide all the flags with which we have to compile the code. In the example above it is AMS_PERF_TEST=1. So, code will be compiled with "make AMS_PERF_TEST=1".
** <testcase_dir>: It is the directory where all test cases of the model will be present.
** <sdk_root_dir>: In this we specify the directory where sdk is installed.
** <asp_dir>: In this we specify the directory where SAFplus Platform is checked out.
** <project_dir>: In this we specify the directory where model is checked out.
** <skip_stages>: By specifying this we can skip some of the steps of complete tae run.

*There are many ways to specify the location of SAFplus Platform source code. "dir:" can be used to specify the local directory as the source code directory for SAFplus Platform in the <asp> <image_source> tag and <model-name><image_source> tag for the model directory.

====env.cfg====

<pre>
<env_config ver="1.0.0.0">
<svn>
<timeout>
<checkout value='10000' />
<update value='10000' />
<revert value='3000' />
<status value='6000' />
</timeout>
</svn>
<report_url value="scp://<user>:<password>@<ip>/<taereport-dir>/import" />

</env_config>
</pre>

*This file contains the timeout values for various TAE operations. After the test run TAE will send the report tarball to the machine specified in <report_url>. Below are the list of all tags used in this config file:
** checkout: It is time in seconds for which tae will wait for checkout to happen before timing out.
** update: It is time in seconds for which tae will wait for svn update to complete before timing out.
** revert: It is time in seconds for which tae will wait for svn revert before timing out.
** status: It is time in seconds for which tae will wait for svn status before timing out.
** report_url: In this we specify the command (to copy) and location where tae report has to be copied.

===Selecting and running the tests===

If following command is issued from the <TAECFGDIR> directory, it lists all the test cases present in the model.
<pre>
# <TAEBASE>/tae/tae -L
</pre>

<pre>
#----------------------------------------------------------------------
# ID State Brief description
#----------------------------------------------------------------------
AMF-CMP-KIL.TC001 E Active Comp Kill Test : Verify SI/CSI assignments after fail-over
AMF-CSI-DEP.TC001 E CSI Dependency Test : Verify CSI assignments order after switch-over
AMF-HA-TST.TC001 E SI Swap Test : Verify SI/CSI assignments after switch-over
AMF-HA-TST.TC002 E SU Lock Test : Verify SI/CSI assignments after switch-over
AMF-NOD-LCK.TC001 E Node Lock Test : Verify SI/CSI assignments after switch-over
AMF-RDN-PRC.TC001 E AMF Reduction Procedure Test : Verify SI/CSI assignments in the reduced mode
AMF-SU-SDN.TC001 E SU Shutdown Test : Verify SI/CSI assignments after switch-over

</pre>

you can then put some of the test cases in a file (say tests.lst) and specify the test-case-filter-file name while running tae using -T switch

<pre>
# <TAEBASE>/tae/tae -T tests.lst -f fetch:stop
</pre>

*Note that the above command should be issued from <TAECFGDIR> directory for the model

*It will execute all the steps from fetch to stop (fetch, populate, configure, build, package, deploy, start, test, stop).

*Some of the steps can be skipped by specifying the stage-name in <skip_stages value="" /> tag present in "model.cfg" file. Alternatively, you can also specify something like "-f build:test" if the requirement is to build the model from already existing code base and then run the test cases.

*If neither of "-t" or "-T" switch is specified, then TAE runs all the test cases present in the "<model>/src/test" directory. One can also use "-t *" to run all the test cases. Remember, the regular expression syntax is supported while specifying the filter for testcases, which can be very handy sometime.

===TAE logs===
TAE log files will be present in "log" directory of your model <TAECFGDIR>. Following log files are created by TAE for various different purposes:

*tae.log : contains detailed log of all the commands executed by the TAE while performing the test.
*bash_127.0.0.1_build_server.log : Contains the logs of commands executed during the SAFplus Platform and model build. It also contains the "make" output in case of build error.
*bash_local.log : Contains the commands performed on the local machine like scp the tarball to the remote nodes etc.
*Node level postmortem files (e.g. SysCtrlI0.postmortem.tgz) : Contains the node level logs as well as the runtime files of the node.

Doc:latest/taeguide/testintg

2010-08-27T05:07:40Z

Senthilk:

=== Integration ===

After you have created the model using IDE and generated the source, add a "test" directory just below the model's root (as a peer to "app") and make subdirectories below "test" for your major functional blocks.

==== Python TAE Interface ====
The python testcase files should be present in "<model>/src/test" directory. Since you are probably already programming your test cases in Python using our testcase framework, nothing further need be done.

==== C TAE Interface ====
The Python "layer" for an exclusively "C" implementation is simple :

<pre>
import openclovis.test.testcase as testcase

class test(testcase.TestGroup):

def test_sg006(self):
r"""
\testcase BIC-UTL-BIT.TG001
\brief Test group based on SG "tcSg005Bitmap"
"""
# List of service groups to unlock, Maximum time (in seconds) that the test takes to run
self.run_sg_based_test(['tcSg005Bitmap'], 60)

</pre>

This python file should be present in "<model>/src/test" directory.

You also need to add some test initialization code in clCompAppMain.c of the component. Here is an example of what all you need to initialize/register :

===== Stub1 =====
In the global context of the file clCompAppMain.c, you need to add following code with BEGIN/END block :
<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/

int
clTestBitmapRun(ClTcParamListT *param_list)
{
clTestBitmapMain();
return 0;
}

void*
clTcRunThread(void *param)
{
clTcRun();
return NULL;
}

/*
* ---END_APPLICATION_CODE---
*/
</pre>

*Where, clTestBitmapMain() is the main test function (where all the test cases will start their execution). The example code for this function is present in "Testcase Implementation" section.

===== Stub2 =====
In main() function, TC initialize should be done in following way :
<pre>
/*
* Do the application specific initialization here.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
rc = clTcInitialize("Bitmap Utility", "BIT", clTestBitmapRun);
if(CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR, "clTcInitialize() failed, rc : 0x%x", rc);
return rc;
}

/*
* ---END_APPLICATION_CODE---
*/
</pre>

===== Stub3 =====
Before blocking on AMF file descriptor for callbacks, in main() function a thread should be created to run the test in the thread context. Alternatively, you can block on the AMF file descriptor in another thread and let the test run in main thread.

<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
rc = clOsalTaskCreateDetached(NULL, CL_OSAL_SCHED_OTHER,
CL_OSAL_THREAD_PRI_NOT_APPLICABLE,
CL_OSAL_MIN_STACK_SIZE,
clTcRunThread, NULL);

/*
* ---END_APPLICATION_CODE---
*/

/*
* Block on AMF dispatch file descriptor for callbacks
*/
</pre>

===== Stub4 =====
In clCompAppTerminate() finalize the TC in following way :

<pre>
/*
* ---BEGIN_APPLICATION_CODE---
*/
clTcFinalize();

/*
* ---END_APPLICATION_CODE---
*/
</pre>

===== Stub5 =====
In clCompAppAMFCSISet(), call TC activate in SA_AMF_HA_ACTIVE context :

<pre>
switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clTcActivate((ClAmsCSIDescriptorT*)&csiDescriptor, haState);

/*
* ---END_APPLICATION_CODE---
*/

</pre>

Doc:latest/taeguide/testimpl

2010-08-27T05:06:55Z

Senthilk:

=== Create your model ===

Create a model using the OpenClovis IDE. Your model can use any redundancy model and contain any number of components and/or service groups. It can expect any number of blades. However, the most common configuration will be 2 system controllers and 0 or more payload blades. It would be best if your model supports this configuration (or fewer) and is capable of utilizing extra blades if they exist.

=== Add your tests ===

There are various ways/options to implement SAFplus Platform testcases:
# Write testcase in C as part of an SAFplus-based component. Such testcases should use the C TAE Interface, see below.
#* Such testcases should be triggered by unlocking AMF entities, typically Service Groups.
#* Such testcases should use the TAE C interface to start and end of testcases, and the result of the testcases.
#* Such testcases will be activated from the TAE robot, using a special 1-line wrapper (explained in "Testcase Integration" section).
# Write testcases purely in Python at the TAE robot side.
#* Such testcase is implemented as a test*.py file.
#* Such testcases can typically do anything that can be done using normal shell access to the target blades and debug CLI access to SAFplus Platform.
#* In the near future, direct access to HPI actions will also be supported.
#* '''It is also possible to invoke C functions in your (test) application from the Python test script, provided that the function is exposed using the SOAP RPC method described with a code snippet below.'''
#* Such testcases may not use the TAE C interface at all.
# The 3rd type of testcase is a mixture of the two extremes above, and implement tests using the C interface, but also have more than just one line code in the Python layer (robot side).

==== When to Use What Approach? ====
When you try to decide what is the best approach for a given testcase, think from a application perspective. Some guidelines:
* If the scenario you want to test is representative of what applications would do, lean more on the C-level implementation. Example:
** An application uses the checkpoint service to save some data, and a standby component is trying to read that data.
* If the scenario has to emulate some artificial external events, use the Python layer to induce the event. Example:
** You need to reset a blade or emulate a kernel crash by invoking some command line commands. Would this code ever be done in a user application? NO! So, you should not (need to) implement this in C, but rather figure out a simple way of doing this from the Python testcase code.
* If the scenario involves artificial sequencing of otherwise randomly occurring events across multiple nodes, the sequencing is better to be left for the Python layer. Example:
** You need to bring some components up, and then crash them in a certain order. Again, you should ask: does the code that crashes the component have a natural place in the application? Would a customer ever write such code as natural part of his application? Hardly. Also, would the sequencing be controlled in C from some other application? No. So, in that case implementing the sequencing and the crash is better to be left to the Python (robot) layer.

==== Python TAE Interface ====
If you plan to implement your tests in a combination of C and Python by invoking some C functions from Python testcase, you must now add the TAE SOAP server and remotely callable functions to your model. For an example of how to do this, please look at the "sysctrlcomp" component in the "bicTests" model in the "asptest" project [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/clCompAppMain.c?root=asptest&rev=946&view=markup here]. This component is untouched except for the addition of 2 remotely callable functions. You must also add the "tae" subdirectory, as seen [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/?root=asptest here]. This is where you define and implement your RPC calls. Finally, you must hook up the Makefiles, so that the "tae" subdirectory is build, as seen [http://clovisforge.openclovis.org:8888/plugins/scmsvn/viewcvs.php/root/bicTests/src/app/sysctrlcomp/Makefile?root=asptest&rev=1270&view=markup here].

Next you must implement your tests in Python, and have them call down to the C layer. This information is best shown by example [[Doc:Sdk_4.0/taeguide/testimpl#Python_test_case | test_lint.py]]

==== C TAE Interface ====
* Any service group instances that run tests MUST be called tcSg<number>[Name]
* For example:
* tcSg001MessagingTest, tcSg034,
** To run 2 service group instances simultaneously use tcSg<same number>[different name]
** For example:
** tcSg001a and tcSg001b, or tcSg005MsgClient and tcSg005MsgServer

=====Include and Library=====

#include <clTestApi.h>

Code is located in the SAFplus Platform utils library (SAFplus/components/utils/...).

=====Summary=====

The module provides a set of functions that are useful while implementing regression tests.

The module creates a hierarchy of tests; a test, a test case, and a test point. The "test" is started/stopped by clTestInitialize/clTestFinalize (clTestStart/End deprecated) and should precede and succeed all other clTest function calls. In general, you'll call these functions once each in your program. Next, within a "test", you are allowed to implement any number of "test cases". A test case is whatever you want it to be, but generally think of it as a grouping based on configuration, load, or strategy. To start/end a test case, use clTestCaseStart/End. You can also use "clTestCase" if your test is a single line (like a function call) -- it's just syntactic sugar.

Finally, individual predicates are called "test points". Use the clTestXXX for these. The basic function is clTest. You essentially pass it a predicate (an expression that evaluates to a boolean) and it checks the truth of that predicate. There is also a similar function that lets you also execute code if the test failed. This is mostly used to skip subsequent test points in a setup where each point requires that the prior succeed. Finally, you can claim that a test succeeded, failed or malfunctioned, without checking any predicate.

Malfunctioned? What's that? A "malfunction" occurs when initial conditions necessary to run the test were not met. For example, let's say you are running a messaging test. The test checks that messaging works between 2 processes on the same blade, and then checks between 2 blades. But what if it is run on a chassis with a single blade? In this case, the test could call TestMalfunction.

=====Context=====

These functions will act differently depending on the context in which they are executed.

* If run independent of a Test Automation Environment (TAE) they will print out consistently formatted messages that can be analysed by scripts. '''To stop the deluge of data, there is a mode that does not print test point successes'''

* If run within a TAE, they will communicate state to the TAE.

Note, some functions ask for formatted strings. Please refrain from using newline or line feeds "\n" or "\l" since these functions will do formatting for you. Also, do not use success or failure words, for example "Failed", "Pass", "Success", or "Ok", since the functions will also add this annotation.

=====Functions=====

<TBD> Available C Test APIs (library : libClTcUtils.a, header file : clTestApi.h, clTcUtilsApi.h)

==== Failover support ====

The Python TAE interface can be used to trigger various failures in the chassis. Organise your tests to use the Python layer.

==== Multi-blade coordination ====

If your test must coordinate the activity of multiple blades then you must use the Python layer. There are rich set of APIs provided by TAE for this purpose.

=== Debug ===

==== Python TAE Interface ====
You can call your Python-to-C functions outside of the TAE with some very simple code. In this example, assume that your RPC function is called "Log", and that you have set the MyPort variable to the TCP port of your TAE server (initialized in your component). Your function will be magically created as a member of the WSDL.Proxy class, so in the example below it will be called in the line "soap.Log(...)".

<pre>
import pdb
from SOAPpy import *
from SOAPpy import WSDL
Config.simplify_objects = 1

MyPort = 8100
soap = WSDL.Proxy("http://localhost:%d/wsdl" % MyPort)

# Call your function. NOTE you MUST use the keyword=value argument format!
print soap.Log(severity=1, area="TST", context="RPC", log="Test the RPC")

</pre>

==== C TAE Interface ====
You can debug your own test by unlocking it as you would a normal application through the debug CLI (asp_console). The output of your test (i.e calls to clTestXXX functions) will be stored in /var/log/testresults.txt.

==Examples==
===Python test case===

*test_lint.py

<pre>

import pdb
import openclovis.test.testcase as testcase

class arbitraryname(testcase.TestCase): # The name of the class does not matter

# This function is executed before each test_xxxx member function is called
def set_up(self):

# self.fixture is a large data structure that models the whole
# chassis or cluster (i.e. all of the machines SAFplus Platform runs on).
fix = self.fixture
# pdb.set_trace()

# Get to the right node in the chassis.
node = fix.nodes["SysCtrl0"]

# Connect to a process on the system controller blade so RPC calls can
# be made. Note that the port 8100 is "well known" for that application.
self.rpc = node.get_rpc("sysctrl", 8100)

# This function is executed after each test_xxxx member function is called
def tear_down(self):
del self.rpc # Clean up my RPC client

def test_doesnotmattername(self): # methods with 'test' prefix are testcases
r"""
\testcase SQA-TAE-REG.TC001
\brief TAE regression test and demo testcase (LINT)
\description
This is a "veterinary horse" kind of a testcase, demonstrating the
various features of the test environment and testing these
features in the same time.
"""

##----------------------------------------------------------------
##
## Logging
##
## .log object
## .log.debug() method
## .log.info() method
## .log.warning() method
## .log.error() method
## .log.critical() method
##
##----------------------------------------------------------------

self.log.debug('This is a sample debug message')
self.log.info('This is a sample info message')
self.log.warning('A sample warning')
self.log.error('A sample error that is recoverable')
self.log.critical('A sample critical error')

##----------------------------------------------------------------
## Local bash access
##
## .tae_host object
## .tae_host.run() method
## .tae_host.run_cmd() method
##
##----------------------------------------------------------------

#
# Running Unix commands on the local host that the tae robot is
# running (this is not part of the fixture), using the pre-opened
# bash session 'tae_host':
#

# Just need output of command. In case of error, an exception is thrown.
# Before using 'run' check for a member function that already implements
# your command. If it exists it will parse the output and return
# 'Pythonized' data (like a list of filenames for 'ls').

# If the member function does not exist, consider writing one!
res = self.tae_host.run('wc -l /etc/passwd')

# res includes the trailing newline; to ignore it, use rstrip()
self.log.debug('Output: %s' % res.rstrip())

# Need both return code and output (does not throw an exception)
rc, out = self.tae_host.run_cmd('wc -l /etc/passwd')
self.log.debug('Return values: rc=[%d] out=[%s]' % (rc, out.rstrip()))

##----------------------------------------------------------------
##
## Build server features
##
## .fixture object
## .fixture.build_server object
## .fixture.build_server.run() method
## .fixture.build_server.run_cmd() method
## .fixture.build_server.scp() method
##
##----------------------------------------------------------------

# Running Unix commands on the build server of the fixture

res = self.fixture.build_server.run('hostname')
self.log.debug('The buildserver is [%s]' % res.rstrip())

# Miscellaneous info about the build server

self.log.debug('Build server IP : [%s]' % self.fixture.build_server.ip)
self.log.debug('Build server login : [%s]' % self.fixture.build_server.user)
self.log.debug('Build server passwd: [%s]' % self.fixture.build_server.password)

# Run scp on the build server to copy in or out something
# Syntax: scp(frm, to, pw) where either frm or to can also include
# a username.
self.log.info('Checking accessibility by ping before attempting scp...')
if not self.fixture.build_server.run_cmd('ping -c 1 10.10.6.1')[0]:
self.fixture.build_server.scp('root@10.10.6.1:.bashrc', '.', 'clovis')

##----------------------------------------------------------------
##
## Fixture target node features
##
## .fixture.nodes object, works as dictionary
## .fixture.nodes.keys() method
## .fixture.nodes.values() method
## .fixture.nodes.items() method
## .fixture.nodes[name].name str
## .fixture.nodes[name].ip str
## .fixture.nodes[name].user str
## .fixture.nodes[name].password str
## .fixture.nodes[name].ping method
##
##----------------------------------------------------------------

# Target node access, based on the model mapping
# Key: self.fixture.nodes is a Python dictionary indexed by the node
# names. Each element is a Node class with a few useful info and
# methods.

# List of node names in the fixture:
node_names = self.fixture.nodes.keys()
self.log.debug('Model node names: %s' % str(node_names))

# To access a given node:
node = self.fixture.nodes['SysCtrl0']

# A few useful values in node:
self.log.debug('Fixture node name : [%s]' % node.name)
self.log.debug('Fixture node ip : [%s]' % node.ip)
self.log.debug('Fixture node login : [%s]' % node.user)
self.log.debug('Fixture node passwd: [%s]' % node.password)

# A few useful methods:
if node.ping(): # ping node from tae server and check if accessible
self.log.debug('Fixture [%s] at [%s] is accessible' %
(node.name, node.ip))
else:
self.log.error('Fixture [%s] at [%s] is not accessible' %
(node.name, node.ip))

##----------------------------------------------------------------
##
## Unix commands on fixture node
##
## .fixture.nodes[name].bash object (session)
## .fixture.nodes[name].bash.run() method
## .fixture.nodes[name].bash.run_cmd() method
##
##----------------------------------------------------------------

# To run a Unix command line command on the fixture node using a
# preinstantiated bash session (this works in the same way as the
# build_server bash session above):
res = self.fixture.nodes['SysCtrl0'].bash.run('df -h . | tail -n 1')
self.log.debug('Disk on fixture node [%s] is [%s] percent full ([%s] available)' %
(node.name, res.split()[4], res.split()[3]))

# Note you must leave this bash session at the Unix prompt!
# For example, do not do .bash.run("tail -f /var/log/asp")
# For this, you can create your own bash session.

shell = self.fixture.nodes['SysCtrl0'].create_bash()
# To start a command that you don't expect to complete:
# expect = shell.start("tail -f /var/log/messages")
# Returned is a pexpect object

##----------------------------------------------------------------
##
## Other generic fixture node methods (also available as methods
## of any bash session)
##
## .fixture.nodes[name].get_pid() method
## .fixture.nodes[name].kill() method
## .fixture.nodes[name].killall() method
##
##----------------------------------------------------------------

# To get list of pids for any running process by given name
pids = self.fixture.nodes['SysCtrl0'].get_pid('bash') # returns a list
self.log.debug('Number of bash sessions: [%d]' % len(pids))
self.log.debug('PID of first bash session: [%s]' %
(len(pids) and pids[0] or 'N/A'))

# To kill a process by pid or process name
node = self.fixture.nodes['SysCtrl0']
node.bash.run('ping localhost > /dev/null & ' * 4) # starting 4 pings
pids = node.get_pid('ping')
self.log.debug('Number of ping sessions: [%d]' % len(pids))

node.kill(pids[0])
node.kill(pids[1], signal=9)
self.log.debug('Number of ping sessions: [%d]' % len(node.get_pid('ping')))

node.killall('ping')
self.log.debug('Number of ping sessions: [%d]' % len(node.get_pid('ping')))

##----------------------------------------------------------------
##
## SAFplus Platform specific fixture node methods
##
## .fixture.nodes[name].asp_running() method
## .fixture.nodes[name].start_asp() method
## .fixture.nodes[name].stop_asp() method
## .fixture.nodes[name].restart_asp() method
##
##----------------------------------------------------------------

# Check if SAFplus Platform is running and start it if not

# Note, the framework starts the SAFplus Platform before running your test case,
# so you can assume that the SAFplus Platform is running. That is, you don't
# need to call this function, unless your test shuts down SAFplus Platform.

if self.fixture.nodes['Worker0'].asp_running():
self.log.debug('SAFplus Platform is running on the node already')
else:
self.fixture.nodes['Worker0'].start_asp()

# Bring down SAFplus Platform and then back
if self.fixture.nodes['Worker0'].asp_running():
self.log.debug('Stopping SAFplus')
self.fixture.nodes['Worker0'].stop_asp()
self.fixture.nodes['Worker0'].start_asp()

# Restart SAFplus Platform in a single command
self.fixture.nodes['Worker0'].restart_asp()

##----------------------------------------------------------------
##
## Fixture-wide methods
## Note that all fixture-wide methods have node equivalents that
## have the same name but are members of the 'node' object.
##
## .fixture.start_asp() method
## .fixture.stop_asp() method
## .fixture.restart_asp() method
##
##----------------------------------------------------------------

# Stopping SAFplus Platform on all nodes
### self.fixture.stop_asp()

# Starting up SAFplus Platform on all nodes
### self.fixture.start_asp()

# Restarting SAFplus Platform on all nodes
# Does it wait?
### self.fixture.restart_asp()

# self.fixture.wait_until_asp_up(50) # TBD,

##----------------------------------------------------------------
##
## Test case python script debugging
##
## pdb.set_trace() method
##
##----------------------------------------------------------------
##
## To get the python debugger break during test execution, issue the
## pdb.set_trace() call ANYWHERE IN YOUR TESTCASE code. To check this
## feature out, uncomment the two lines below
##

#import pdb
#pdb.set_trace()

##----------------------------------------------------------------
##
## Debug CLI access
##
## .fixture.has_debug_cli() method
## .fixture.start_debug_cli() method
## .fixture.debug_cli.root() method
## .fixture.debug_cli.run() method
##
##----------------------------------------------------------------

# All "get_xxx" functions return a cached version if it exists or create
# if it does not.
# All "create_xxx" functions create a new one and pass it back to you.

# In the case of the debug CLI, there can be only 1 instance, so there
# is no "create" function.
dbgcli = self.fixture.get_debug_cli()

# Run some native debug cli commands:
dbgcli.run('setc 1')
dbgcli.run('setc cpm')

# You may also use the fixture variable debug_cli, if you are sure
# that it is valid.
res = self.fixture.debug_cli.run('compList')
self.log.debug('First 20 partial lines of component list:')
for line in res.splitlines()[:20]:
self.log.debug('>> %-65s ...' % line[:60])

##----------------------------------------------------------------
##
## Determining test result
##
## Test ERROR is not the same as a FAIL-ed test
##
## The former means the test is not conclusive because the test
## procedure itself could not be completed dur to some errors.
## The latter means the test subject failed the test.
##
## Test errors: any unhandled Python exception that occurs during
## running the testcase will be regarded by the test
## framework as a test error and the failure of the
## Test failure: test failures are generated when an explicit
## verification of some result produces a negative
## result. These types of check are done using one of
## the following method calls:
##
## .assert_true(condition [, failure info])
## .assert_false(condition [, failure info])
## .assert_equal(value1, value2 [, failure info])
## .assert_not_equal(value1, value2 [, failure info])
## .assert_almost_equal(value1, value2 [, failure info])
## .assert_not_almost_equal(value1, value2 [, failure info])
## .assert_raises(exception [, failure info])
##
## These are demonstrated in separate testcases below not as part
## of this LINT testcase
##
##----------------------------------------------------------------

def test_always_errors1(self):
r"""
\testcase SQA-TAE-REG.TC002
\brief This testcase should always produce an ERROR
"""
l = [0, 1]
print l[100] # index is out of range, will generate a python exception

def test_always_fails(self):
r"""
\testcase SQA-TAE-REG.TC003
\brief This testcase should always produce a FAIL
"""
self.assert_equal(1, 10, 'This test is failed purposely')

def test_well_documented(self):
r"""
\testcase SQA-TAE-REG.TC004

\brief This is a well documented testcase example

\description
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.
You can have an arbitrarily long description of the testcase.

\state enabled

\prerequisites
* SC0 is accessible
* OS booted on system controller
* Python test environment (with PyOpenHPI) is available on SC0
* IP address to shelf manager is know as SHMGR_IP environment variable

\steps
1 start test application which will attempt to setup HPI session and
wait till its output is printed

\criteria
\li HPI session open returns with success
"""
pass # always passes

def test_unimplemented(self):
r"""
\testcase SQA-TAE-REG.TC005

\brief Unimplemented testcase (always errors out)
"""
self.log.debug('This is an unimplemented testcase')
raise testcase.TestcaseNotImplemented

def test_with_measurement(self):
r"""
\testcase SQA-TAE-REG.TC006

\brief Testcase example with measurements

\description
This measures two attributes, as described below.

\measured
\data FREE_DISK_SPACE [MB] Free disk space on first node
\data RANDOM_NUMBERS [] Random numbers in [0, 1) interval
\data ASP_STARTUP_TIME [ms] Ping latency between two nodes

"""
##----------------------------------------------------------------
##
## Measurements related stuff
##
## openclovis.test.bin module
## openclovis.test.bin.Bin() class
## openclovis.test.bin.Bin.record() method
## .report_data() method
##
##----------------------------------------------------------------

import openclovis.test.bin as bin

# Free disk space example
raw_data = self.fixture.nodes['SysCtrl0'].bash.run('df -m . | tail -n 1')
free_space = int(raw_data.split()[3])
self.report_data(bin.Bin('FREE_DISK_SPACE', free_space, unit='MB'))

# Random number measurement
import random
array = [random.random() for foo in range(10000)]
self.report_data(bin.Bin('RANDOM_NUMBERS', array, fmt='%6.4f'))

# Step-by-step data collection
data = bin.Bin('ASP_STARTUP_TIME', unit='s')
import time
self.log.info('Measuring SAFplus Platform startup time, using 5 runs')
if self.fixture.nodes['Worker0'].asp_running():
self.fixture.nodes['Worker0'].stop_asp()
for i in range(5):
start_time = time.time()
self.fixture.nodes['Worker0'].start_asp()
stop_time = time.time()
data.record(stop_time - start_time)
self.fixture.nodes['Worker0'].stop_asp()
self.log.debug('- Iteration %d done' % (i+1))
self.report_data(data)

def test_with_rpc(self):
r"""
\testcase SQA-TAE-REG.TC007
\brief Testcase example with RPC calls

\description
This runs 2 functions on the target within a particular process.
To see the server side implementation, look at:
SAFplus/models/unitTests/app/sysctrlcomp/tae

\measured
\data Length of a task delay.
"""
# This example shows passing strings.
self.rpc.Log(severity=1,area="TST",context="LNT", log="Testing the RPC mechanism. This log actually originated from the test_lint.py script running on the TAE.")

# This example shows how a complex data structure can be returned.
ret = self.rpc.TaskSleep(sec=3,msec=0)
self.log.info("Raw data received from RPC call: %s" % str(ret))
self.log.info('Sleep of 3 seconds was measured (on the node) as taking %d ms' % ((int(ret["sec"]) * 1000) + int(ret["msec"])))

def test_disabled(self):
r"""
\testcase SQA-TAE-REG.TC008
\brief Disabled testcase
\state disabled
"""
self.log.critical('You should never see this testcase executed by TAE')

</pre>

===C testcase (SG based)===

*testBitmap.c

<pre>

void TC2_BitMap(void)
{
ClBitmapHandleT bitHdl = CL_BM_INVALID_BITMAP_HANDLE;
ClRcT rc = CL_OK;
ClRcT retVal = CL_OK;
ClUint32T bitCount= 0;
ClUint32T bitNum = 0;

for(bitCount = 3, bitNum = 1; bitCount <= 100; bitCount += 2, bitNum++)
{
clTestCaseMalfunction(
("Bitmap create"),
(rc = clBitmapCreate(&bitHdl, bitCount)) == CL_OK,
return);

clTest(("Bitmap set bit [%d]", bitNum),
(rc = clBitmapBitSet(bitHdl, bitNum)) == CL_OK,
("Error: rc[0x %x]", rc));

clTest(("Bitmap is bit[%d] set?", bitNum),
(((clBitmapIsBitSet(bitHdl, bitNum, &retVal))
== CL_BM_BIT_SET) && CL_OK == retVal),
("Error: rc[0x %x]", retVal));

clTest(("Bitmap set bit [%d]", (bitNum + 2)),
(rc = clBitmapBitSet(bitHdl, (bitNum + 2))) == CL_OK,
("Error: rc[0x %x]", rc));

clTest(("Bitmap is bit[%d] set?", (bitNum + 2)),
(((clBitmapIsBitSet(bitHdl, (bitNum + 2), &retVal))
== CL_BM_BIT_SET) && CL_OK == retVal),
("Error: rc[0x %x]", retVal));

clTest(("Bitmap destroy"),
(rc = clBitmapDestroy(bitHdl)) == CL_OK,
("Error: rc[0x %x]", rc));

}

}

void
clTestBitmapMain(void)
{

clTestGroupInitialize(("Test of Bitmap utility"));

clTestCase(("BIC-UTL-BIT.TC003 Set Bits in a bitmap and Verify whether the bits are set"),
TC2_BitMap());

(void) clTestGroupFinalize();

}

</pre>

* This example shows just one test case of many that can appear in a single service group. To make this example a "fully" runnable standalone test, you would have to call clTestGroupInitialize and clTestGroupFinalize functions before and after calling a set of clTestCase().

*When a service group is assigned work (a CSI) this should trigger your test to run. When your test is complete it should simply wait until the work is unassigned. Also, the service group should be modeled to be in lock assigned mode.

* Your tests must call the functions in the Test API defined in "clTestApi.h". You can also use the Test Lifecycle APIs defined in "clTcUtilsApi.h" to facilitate starting test cases with different parameters.

Doc:latest/taeguide/deppkg

2010-08-27T05:05:01Z

Senthilk:

==Deployment and Packaging==
The OpenClovis TAE is provided in the form of a gzipped tar file (.tar.gz). You can open this file (tar xvfz <filename>) in directory (as "root" user). It will create a directory called openclovis-tae-<version>. The rest of this document will refer to this directory using the symbol <TAEBASE>. This directory should contain following files/directories :
*README.txt
*Python-2.5.2.tgz
*setuptools-0.6c9.tar.gz
*TG_setup_files.tgz
*tae (directory)

==Steps to install TAE==

* Install Python-2.5.2
# tar zxvf Python-2.5.2.tgz
# cd Python-2.5.2
# ./configure
# make
# make install

* Install setuptools (required for easy_install used in next step)

# tar zxvf setuptools-0.6c9.tar.gz
# cd setuptools-0.6c9
# python setup.py install

* Install Turbougear and tae-report server dependent packages

# tar zxvf TG_setup_files.tgz
# cd TG_setup_files
# easy_install -Hlocalhost *.egg

* Install tae 3rdparty packages

# cd tae/3rdparty/
# make install

* Build initial database

# cd taereport
# rm devdata.sqlite*
# tg-admin sql create

* Run

# iptables -F # Turn off firewall needed on some linux distributions (or you can edit your firewall settings to let TAE through)
# python start-taereport.py

* Set up database

#Open browser, and go to <taeserver>:5000/catwalk
#Click project->Add project
#Status: 1
#Description: <anything>
#Created: <leave>
#Brief: <anything>
#Label: <specify the project name that appears throughout the rest of the TAE reports>
#anonymous_view: <specify 1 to allow anonymous users>

* All Done!

#Use TAE report server: Open browser, and go to <taeserver>:5000

* Next steps:

# Read and follow the OpenClovis TAE user/programming guide
# Start running tests and upload them to <taeserver>/<taedirectory>/taereport/import

Doc:latest/taeguide/overview

2010-08-27T05:04:02Z

Senthilk:

== Organization ==

The TAE is organized following the [http://en.wikipedia.org/wiki/Matryoshka_doll Matryoshka principle] in that each facility requires all "smaller" facilities, yet any particular facility and all "smaller" facilities comprises a working automation environment (albeit missing the features provided by the "larger" facilities) and is useful in certain circumstances.

The purpose of this organization is most importantly to create an incremental development schedule that will yield a usable test framework rapidly and a fully-featured one when those features are required.

Another extremely important purpose is to allow the automation environment to be run in a variety of different situations and by a variety of different users. For example, it could be run by an automated nightly verification system (layer 3), or by a developer fixing a bug (layer 1,2). It could be run by an OpenClovis engineer (layer 1,2 or 3), or by a customer who is verifying compatibility with his hardware (layer 3).

Lastly, it is designed to allow programs written for a variety of purposes -- test, demo, eval, and real systems -- to be run. Traditionally automated test frameworks are so encompassing that the only software that can be run are test suites designed from the bottom-up to fit within the automated test framework. This framework allows software that was not written for the express purpose of testing to be annotated with compile-time optional tests (similar to assert()) that can be used to verify the correct execution of that software.

Each layer is summarized in this document and contains a link to a detailed design.

=== Layer 1: C program API (Clovis Test API) ===

The smallest layer is the API used in a program to run tests. This layer consists of a set of C macros that group and run tests. When not testing, these macros can be compiled out. This is very similar to unit testing packages found for many languages.

If this layer is run alone, it will simply print test successes and failures to the screen.

When run within the layer 3 framework, test successes and failures will be posted to the TAE report server.

=== Layer 2: Python based testing (using APIs provided by TAE)===

This is another layer to write test programs in python and run tests. Here the test program uses the rich set of APIs (written in python) present in the TAE infrastructure. This layer provides multiple utilities to run tests in a distributed environment.

If this layer is run alone, it will simply print test successes and failures to the screen.

When run within the layer 3 framework, test successes and failures will be posted to the TAE report server.
=== Layer 3: Test Execution Management and Event Simulation ===

The Test Execution Management and Event Simulation (TEMES) layer consists of a separate machine (test driver) that controls the test "fixture" (the set of machines that constitute a test environment). It is capable of taking software from either a local directory, a ftp site, an http site or from subversion repository, unpacking it (if needed), installing it on the fixture, compiling it, and running a series of tests.

These tests primarily constitute executable programs that use the Layer 1 and 2 APIs, and conform to a loose modeling format.

Additionally, a test-specific scripts may be run on the TEMES that can "drive" the progress of the test and cause events such as process, network, and machine failures.

If this layer is run alone, it will run through a complete test suite and report successes and failures.

=== Layer 4: Automated Run and Longitudinal Reports ===

The Automated Run and Longitudinal Reporting (ARLR) layer consists of a single globally accessible server (ARLR server) and a source repository (subversion etc). The ARLR server contains a web site that allows users to see which source code branches are failing which tests on what hardware and it keeps a history of this information. It also will communicate with unused (or layer 3 dedicated) test drivers to schedule runs of a set of test suites against a set of branches and receive results from these drivers.

Doc:latest/taeguide/preface

2010-08-27T05:03:23Z

Senthilk:

=='''Preface'''==

''OpenClovis Test Automation Environment (TAE) User Guide'' provides information about the usage of OpenClovis TAE. TAE provides an infrastructure to allow comprehensive system and unit tests to be written and executed easily. It also contains a web-based test report server for permanent storage and retrieval of test reports. This guide helps you to utilize the OpenClovis TAE in your own environment.

OpenClovis TAE is designed to simplify and accelerate the testing of Telecom application software over OpenClovis platform. It also provides a simple and powerful mechanism to coordinate the activities of multiple blades of a chassis or multiple systems in a network.

===Audience===

OpenClovis TAE User Guide is designed for system integrators, developers, and testers. To use this OpenClovis product, you must be aware of the fundamentals of operation, management, and configuration of telecommunication and networking domains. You must also be familiar with Python programming, the OpenClovis SAFplus Platform product, and have a basic knowledge of Linux.

===Documentation Conventions===

This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table:

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Notation
!style="color:#66b154; background:#09477c"| Description
|- style="color:#ffffff; background:#549cc6"
| style="color:black" | <code><pre>Code</pre></code>
| This font denotes the source code provided in various examples.
|- style="color:#ffffff; background:#549cc6"
|
Cross reference
|
This font denotes a hyper link. You can click on the hyper link text to access the reference location, which can be either a section within the User Guide or a URL link.
A cross reference refers to a section name accesses the first page of that section.
|- style="color:#ffffff; background:#549cc6"
|
'''Bold Text'''
|
Menu items and button names.
|- style="color:#ffffff; background:#549cc6"
|
''Italic Text''
|
Variables for which you enter values.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Related Documentation===

For additional information about OpenClovis products, refer to the following guides:
* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.
* '''OpenClovis Evaluation System User Guide''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''OpenClovis SDK User Guide''' provides information about OpenClovis Application Service Platform (SAFplus Platform) architecture, various OpenClovis SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the OpenClovis SAFplus Platform code to build your custom application.
* '''OpenClovis Log Tool User Guide''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

For additional information about TurboGears, the web application mega-framework used by the OpenClovis SAFplus Platform Web Director please refer to:
* Turbogears web site at http://www.turbogears.org.

===OpenClovis Online Technical Support===

OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum.

===Documentation Feedback===

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Post your feedback on documentation at: http://www.openclovis.org/forum.

Deadpages/Doc:Sdk 5.0/taeguide

2010-08-27T05:02:57Z

Senthilk:

Table of contents:

* [[Doc:sdk_5.0/taeguide/preface | Preface ]]
* [[Doc:sdk_5.0/taeguide/overview | Overview ]]
* [[Doc:sdk_5.0/taeguide/deppkg | Deployment and Packaging ]]
* [[Doc:sdk_5.0/taeguide/testimpl | Testcase Implementation ]]
* [[Doc:sdk_5.0/taeguide/testintg | Testcase Integration]]
* [[Doc:sdk_5.0/taeguide/runtae | Running the TAE ]]
* [[Doc:sdk_5.0/taeguide/reportserver | TAE Report Server]]
** [[Doc:sdk_5.0/taeguide/screens | Screens ]]
*** [[Doc:sdk_5.0/taeguide/projects | Projects ]]
*** [[Doc:sdk_5.0/taeguide/projectSummary | Project Summary ]]
*** [[Doc:sdk_5.0/taeguide/reports | Test Reports ]]
*** [[Doc:sdk_5.0/taeguide/testreport | Test Report in Detail ]]
*** [[Doc:sdk_5.0/taeguide/logfiles | TAE log files and Node postmortem files ]]
*** [[Doc:sdk_5.0/taeguide/models | Models ]]
*** [[Doc:sdk_5.0/taeguide/fixtures | TAE Fixtures ]]
*** [[Doc:sdk_5.0/taeguide/testcases | Testcases ]]

Doc:latest/taeguide

2010-08-27T05:02:57Z

Senthilk:

Table of contents:

* [[Doc:latest/taeguide/preface | Preface ]]
* [[Doc:latest/taeguide/overview | Overview ]]
* [[Doc:latest/taeguide/deppkg | Deployment and Packaging ]]
* [[Doc:latest/taeguide/testimpl | Testcase Implementation ]]
* [[Doc:latest/taeguide/testintg | Testcase Integration]]
* [[Doc:latest/taeguide/runtae | Running the TAE ]]
* [[Doc:latest/taeguide/reportserver | TAE Report Server]]
** [[Doc:latest/taeguide/screens | Screens ]]
*** [[Doc:latest/taeguide/projects | Projects ]]
*** [[Doc:latest/taeguide/projectSummary | Project Summary ]]
*** [[Doc:latest/taeguide/reports | Test Reports ]]
*** [[Doc:latest/taeguide/testreport | Test Report in Detail ]]
*** [[Doc:latest/taeguide/logfiles | TAE log files and Node postmortem files ]]
*** [[Doc:latest/taeguide/models | Models ]]
*** [[Doc:latest/taeguide/fixtures | TAE Fixtures ]]
*** [[Doc:latest/taeguide/testcases | Testcases ]]

Doc:latest/sdkguide/glossary

2010-08-27T04:14:25Z

Senthilk:

=='''Appendix A: Glossary of Terms'''==

'''Alarm''' An alarm is a warning about the abnormal conditions of Managed Object (MO).
 [[File:OpenClovis_Note.png]]An alarm always does not represent an error.

'''Alarm Lifecycle''' The Alarm Managed Service Object (MSO) associated with an MO depicts the lifecycle of an alarm as:
* An alarm is raised by the alarm service, if the abnormal condition relating to the alarm persists for a time, at least equal to the soaking interval specified. This alarm may be cleared by:
** The alarm service, when it gets a notification from the MO that the abnormal condition which caused the alarm has been cleared.
** RESET, if the MO is hardware, and RESTART, if the MO is software Execution Object (EO).

'''Alarm Manager''' The alarm manager enables configuring and handling of alarms. It provides support for alarm soaking, masking, alarm hierarchies, retrieving previous alarm conditions, and correlation of the alarms before publishing.

'''Alarm Masking''' Multiple alarms can be raised in a system. Alarm-masking is a procedure that enables the alarm service to publish the alarms with high priority for fault recovery.The current alarm-masking logic implies that all MOs are organized in a fault containment hierarchy which represents the relationship "is physically contained in" for hardware and "runs on" for software. The alarm-masking algorithm masks all alarms of the same or lesser severity level within any sub-tree in the hierarchy.

'''Alarm Service''' The OpenClovis alarm service implements a generic engine to process abnormal conditions reported by managed resources. The process includes identifying the alarm type and its severity level and determining whether an alarm has to be raised after running it through soaking and masking procedures.Potential subscribers for alarm events are - OpenClovis Fault Management Service, OpenClovis Availability Management Service and other agents like SNMP, CLI, and so on for reporting alarms to external managers.

'''Alarm Severity''' The alarm severity specifies the condition of the service provided by the MO. The severity levels can be critical, major, minor, warning, or cleared and indeterminate (CCITT X.733). The cleared and indeterminate level indicates clearing of one or more previously reported alarms. The critical and major alarms are service-affecting alarms.

'''Alarm Soaking''' Soaking is the time defined for extreme conditions before reporting as an alarm. Alarm soaking is possible when a managed resource provides a pair of notifications - one for the occurrence of an extreme condition and another for clearing of the extreme condition. Soaking avoids raising an alarm unless the extreme condition of the alarm persists for a period of time. Sometimes, you may not get a notification for clearing of an extreme condition. In such cases, a poll mechanism can be used to see if the alarm condition is still present after the soaking interval.

'''Application''' An Application is customer software built using OpenClovis infrastructure that provides services to the end users. For instance: A SIP server customer application.

'''SAFplus Platform Console''' A command-line Interface for debugging allows access to the managed object repository for creating, deleting and otherwise manipulating objects. SAFplus Platform Console also provides viewers for system log and trace data as well as interfaces to individual EOs to view and modify their private (non-persistent) data.

'''Attributes''' Attributes are the characteristics or parameters of a Managed Object.

'''ATCA Chassis''' An Advanced Telecom Computing Architecture [ATCA] specification is designed to use in the central office grade equipment at the telecommunications sector. The ATCA defines the rack and chassis [shelf] form factors, [passive] backplane, cards, power, and keying. An ATCA card can handle up to 4 PMC daughter cards.

'''Availability Management Framework (AMF)''' AMF is a software entity that provides a framework for high availability of applications in a system. It is responsible for instantiating and managing all the OpenClovis SAFplus Platform services. It executes configured recovery actions on the failure of application components. The AMF is built with the close association of two OpenClovis SAFplus Platform components: Component Manager and the Availability Management Service (AMS).

'''Boot Level''' OpenClovis SAFplus Platform services and customer applications are mapped to different Boot Levels. The Boot Management Service starts these services (applications) when it reaches the specified BOOT_LEVEL. The BMS can be constrained to boot-up only to a specified BOOT_LEVEL.
 [[File:OpenClovis_Note.png]]BOOT_LEVEL is conceptually similar to the run_level concept in Unix.

'''Boot Management Service''' OpenClovis Boot Management Service provides the support for starting or shutting down of the OpenClovis SAFplus Platform services and customer applications on a OpenClovis SAFplus Platform managed platform. The Boot service assumes that an OS has already been booted-up in the target environment. While starting or shutting down a system, the BMS has several BOOT_LEVELS in sequence. At each level, certain services (applications) are started or shutdown.

'''Boot Profile''' The boot profile defines a particular type or a particular mode of boot configuration. The list of services performed can be different for different profiles. This helps in obtaining different configurations containing different set of boot levels and different Service Units assigned to them.For Instance, a profile named debug can define a boot configuration, which can be helpful in debugging the boot up process, whereas a profile named production can be used when the desired configuration for normal deployment boot needs to be specified.

'''Boot State Machine''' The boot state machine provides a mechanism for a customer to control boot-up (sequences, dependencies, exception handling) using BOOT_LEVELS, RUN-LEVELS, and so on.

'''Chassis Management Service''' OpenClovis Chassis Management Service provides support for resource discovery, sensors, and controls on chassis-based hardware platforms. The platforms can be standard-based (ATCA, BladeCenter and so on) or proprietary. The Chassis Management Service can be customized for any platform by providing the platform specific plug-ins.

'''Checkpoint Service (CPS)''' CPS provides synchronization of run-time data and context to ensure a seamless failover or switchover of applications. It allows the application to store its internal state and retrieve the information. It also provides a facility for processes to record checkpoint data incrementally and supports non-transparent mode of Checkpointing.

'''Clovis Object Repository (COR)''' Clovis Object Repository (COR) is an in-memory object-oriented hierarchical distributed repository of MOs. COR contains the description of each MO and relationships between different MOs. Multiple relationships - hierarchical containment and associations - are supported. COR provides Object lifecycle management, transactions on multiple objects, object change notification, object change propagation and other services.Each OpenClovis SAFplus Platform instance has an instance of the Clovis Object Repository associated with it.The COR instance on the System Director links with COR instances on Blade Directors to provide a single logical system view of all the MOs.

'''Cold Restart''' Cold Restart is an element that carries out the entire initialization sequence from the beginning. For example power-on.

'''COR Persistence''' The Clovis Object Repository may be persisted using a persistent database. The effect of this is as follows: When a OpenClovis SAFplus Platform instance boots up, COR reads the database and restores the persisted state to each MO. This state is used, for example, by the provisioning service to provision all objects on boot-up.

'''DBAL''' Provides a standard interface for any OpenClovis SAFplus Platform infrastructure component or application to interface with the commonly used relational. DBAL currently supports GNU Database Manager.

'''Default Boot Level''' During startup, the Component Manager boots the components to a boot level called default boot level as specified in the deployment configuration file. All the components specified up to and including the default boot level are started.

'''EO Management service''' The OpenClovis Execution Object (EO) Management Service monitors the health and controls the state of all Execution Objects in the system. State control includes the ability to start, stop, suspend, resume, kill and restart an EO.

'''EOID''' Identifier for execution object (EOID is unique within a OpenClovis SAFplus Platform instance).

'''Error''' Error is the deviation in the system state or behavior as a result of the use of incorrect data or signal.

'''Event''' Events are means by which data may be exchanged between event publishers and event subscribers. An event is characterized by an event channel and event ID.

'''Event Channel''' An event channel is a mechanism used by the event service for publishers and subscribers to communicate via events. One or more events (with distinct event ID's) may correspond to an event channel.

'''Event Filter''' These are filters used by an EO to specify the events it is interested in.

'''Event Publisher''' An EO that publishes an event.

'''Event Service''' An OpenClovis SAFplus Platform service that provides a mechanism to publish or subscribe communication based on event channels and asynchronous communication between publishers and subscribers.

'''Event Subscriber''' An EO that is interested in receiving published events on a specific event channel.

'''Execution Object''' The motivation for the OpenClovis EO is to provide execution contexts independent of process architecture in any OS.Execution objects are programs that implement management interfaces (mandated by OpenClovis SAFplus Platform). These programs allow them to be managed in a OpenClovis SAFplus Platform environment. (Refer to EO Management Service, for details of management functions).EOs may use services provided by other EOs (For example, Checkpointing service). If so, they need to implement client interfaces for the service in question.EOs may provide services to other EOs. In this case they need to implement the service interface.EOs may be made visible to an external manager by representing them as MOs.

'''Failure''' A failure in a system occurs when the consumer (human or non-human) of a service is affected by the fact that the system has not delivered the expected service. It is a reflection of unacceptable or incorrect results delivered by a system with respect to a specification. It is an unexpected behavior perceived by the consumer or user of a service.

'''Fault''' A fault is a Physical or algorithmic cause of a malfunction. Faults manifest themselves as errors.

'''Fault Diagnosis''' Fault Diagnosis is the process of determining the cause of a fault. Fault diagnosis is provided to the granularity of an FRU to support maintainability or serviceability.

'''Fault Management Service''' OpenClovis FMS provides a framework for fault management, including fault diagnosis and progressive recovery. Standard recovery methods for software exceptions are available. You can plug-in custom fault recovery methods.

'''Fault Manager''' The Fault Manager manages faults in a system and initiates actions. It can handle various user-defined run-time faults, including hardware and software faults. It can prioritize faults to ensure that the critical faults are addressed before the normal or the low-priority faults.The Fault Manager client library notifies alarms to the Fault Manager server located on the same node. The actions to be taken on receiving a fault are controlled by the FM policy associated with the faults.

'''Field Replaceable Unit (FRU)''' Field Replaceable Unit is the hardware element of a system that can be replaced by a similar element in the field.

'''Group Membership Service (GMS)''' Group membership service provides the facility of leader election. Any application or OpenClovis SAFplus Platform service can register with GMS to keep track of information such as leader change and cluster membership change.

'''Hardware Abstraction Layer''' Provides a uniform management interface to hardware peripheral devices via their respective device drivers. Device types include Framer, NP, ASIC, LIU, Switch chip, DSP, and so on. HAL supports the following interfaces: Access, Init, Open, Close, Control, Retrieve, Send, Receive, Download OpenClovis SAFplus Platform. Customer applications are made entirely transparent to configuration changes in the underlying devices by the HAL.

'''Heartbeat''' Heartbeat is a message exchanged at regular intervals between two OpenClovis SAFplus Platform instances. A missed heartbeat is the non-arrival of a heartbeat within a timeout period. A configurable number of missed heartbeats are taken to indicate that one of the two instances in question is no longer running or is incommunicable.

'''Heartbeat Service''' A service that runs on every OpenClovis SAFplus Platform instance and monitors the health of other OpenClovis SAFplus Platform instances using the heartbeats.

'''High Availability (HA)''' High Availability (HA) is used when referring to a system that is capable of providing service most of the time.

'''Hot Plug Unit''' An FRU that can be removed or re-inserted even while the system is powered.

'''Intelligent Object Communication (IOC)''' OpenClovis Intelligent Object Communication (IOC) provides a transport and OS neutral, fault tolerant communication between OpenClovis Execution Objects using physical links available and user defined transports (E.g.: UDP, TCP, or Ethernet).

'''Interface Definition Language (IDL)''' )IDL is a library used by all EOs to communicate efficiently across nodes. Using IDL, OpenClovis SAFplus Platform services can communicate across endian machines and mixed mode (32-bit and 64-bit architecture).

'''IOC Address''' Address of a OpenClovis IOC instance that maps to a transport address for each transport or physical link provided.

'''Link''' A link is a physical interconnection between nodes. Also referred to as physical medium.

'''Local Managed Object''' A managed object abstracting a local resource.

'''Local Resource''' A resource that is contained from a fault-containment point of view within a physical node. (Local resources can be software abstractions implemented by programs running on the node, or hardware attached to the node, or the node itself).

'''Log Service''' Log service collects, translates, and publishes log messages to record any significant event in the system. For example: operational state change of a component, managed object attribute value change, and so on.

'''Managed Object (MO)''' Managed Object provides an abstraction for the manageable properties of a resource in the system. MOs have attributes, support management operations, exhibit behavior and can emit notifications(CCITT X.700).Operations on an MO can be Create or Delete Instances; Get or Modify attributes; Action.Notifications emitted by an MO instance are instance created/deleted; report attribute change; class specific notification such as alarms.Attributes can be single valued, multivalued or grouped in an attribute group (Ex; Chassis attributes relating to blades may be grouped).

'''Managed Service Object (MSO)''' MSOs encapsulate the attributes of a Managed Object specific to the particular Object Implement (OI) they are associated with. (Ex: Alarm severity is an attribute related to the alarm MSO; it is a part of the Alarm MSO associated with any MO desiring an alarm service).

'''Management Information Base (MIB)''' Management Information Base is a data structure that holds information on how a system is configured or functioning.

'''Management Interfaces''' Methods available for managing a system at the boundary of the system and management middleware. In OpenClovis SAFplus Platform, management interfaces (for different management protocols) are provided by the Mediation Library.

'''Mediation Library''' The Mediation Library mediates between management agents implementing standard protocols (such as CISCO CLI or SNMP) and the OpenClovis SAFplus Platform to service management requests from respective (CLI, SNMP) management stations. Requests from outside the system are translated to requests on MOs and forwarded to the appropriate MO.

'''Mean Time to Failure (MTTF)''' MTTF is the interval in which the system or element can provide service without failure.

'''Mean Time to Repair (MTTR)''' MTTR represents the interval in time it takes to resume service whenever a failure occurs.

'''Middleware''' OpenClovis SAFplus Platform is often referred to as a middleware. This is to reflect that OpenClovis SAFplus Platform is a layer over the OS, providing system services and APIs to user applications. Applications must be written to OpenClovis SAFplus Platform API's (rather than directly to OS API's) in order to be OS, database and hardware independent and to be manageable and available.

'''MOID''' Managed Object Identifier - The MOs have unique global handles associated with them within the system, and using these handles one can address the MOs. The COR handle uses a pair of object class index and object instance index. Object class index uniquely identifies a managed object class and managed object instance index uniquely identifies an instance of a managed object within that class.

'''MO (Instance) Tree''' Managed Object Instance Naming Tree - The MO fault containment hierarchy (see OpenClovis Information Model) is used to name instances of objects. For example, in a chassis based system, an instance of a port could be located as follows: Chassis (0)/Blade (3)/Port (2)

'''MSG-Q''' A transport supported by the OpenClovis SAFplus Platform infrastructure as an alternative to UDP using message queuing service of the OS. Restricted to use when the sender & the receiver are in the same OS/OpenClovis SAFplus Platform instance.

'''Name Service''' The name service facilitates location transparency to the communicating objects by allowing use of object name instead of location specific address. The name service provides name to IOC address translation. A name is user-defined data.

'''Node Profile''' Node Profile describes the list of services that can be run on this node and the various attributes of these services. It also describes the characteristics of the node with respect to its role in the chassis. A node can either behave as a Controller Node for the complete chassis or as a normal processing node in the chassis.

'''Notification''' Managed Objects emit notifications. Notifications emitted by an MO instance are instance created/ deleted; report attribute-change; class-specific notification such as Alarm (Also referred to as COR notification).

'''OAMP''' Refers to Operations, Administration, Maintenance and Provisioning.

'''OpenClovis SAFplus Platform Services''' OpenClovis SAFplus Platform services are Execution Objects that provide core-underlying services for OpenClovis SAFplus Platform and applications.

'''OpenClovis IDE''' This is a Graphical User Interface (GUI) tool designed to simplify and accelerate the development of System Infrastructure Software for Telecom and other networking products. It enables the customer to rapidly create an information model of the Resources that will be required to manage. It generates customized code for OpenClovis SAFplus Platform, a flagship product of OpenClovis Inc.

'''OpenClovis Information Model''' An OpenClovis Information Model (IM) is a generic framework or an abstract representation of the entities in a managed environment.It is a mechanism that describes the characteristics of the network element for which the infrastructure software is being implemented. IM provides a unified view and association of all the physical and logical objects in the managed environment. Information Modeling transports the current content or state of a OpenClovis SAFplus Platform Object such as a blade, port, or any other logical object between different Execution Objects.

'''Operating System Abstraction Layer (OSAL)''' The OpenClovis Operating System Abstraction Layer provides commonly used APIs to abstract OS services for OpenClovis EOs and customer applications.The basic OS services include the following:
* Memory Management, Timer Management, Executive Task/Process/thread Management, Signal/Event Management, Resource Management, Messaging services, RTOS task profiling services, synchronization and semaphore management.
* OSAL enables one to easily port the OpenClovis SAFplus Platform and OpenClovis SAFplus-enabled customer applications onto new RTOS environments.

'''Physical Node''' A physical node is a particular type of resource that can run a single instance of the operating system and OpenClovis software. (Ex: a blade with a general purpose CPU). Physical nodes may be interconnected via some form of communication medium (Ex: multiple blades via a chassis backplane).The process model describes how OpenClovis SAFplus Platform service EO's and user application EO's map to processes in a specific operating system. (Example: in the multi-process version of Release 1.0 for Linux, all OpenClovis SAFplus Platform EOs run in a single Unix process and user application EOs may be combined in one or more processes).

'''Pre-provisioning''' Normally, the provisioning of an object corresponding to an FRU occurs when that FRU is present. However, pre-provisioning takes place when an MO exists and the FRU is absent. Scenarios where this occurs:
* A blade lost power or was extracted from the chassis after being provisioned.
* A user pre-provisioned a blade in the Provision Manager's database in the absence of a blade.
* When the blade becomes active, the provisioning service on the System Controller verifies the provisioned data against the properties of the blade and pushes the data down to the blade if the blade's properties match; otherwise, an identity mismatch alarm will be raised and no data will be pushed down.

'''Provisioning Service''' The Provisioning service is an Engine that provisions any type of equipment and facility, virtual or physical in the most generic way. Provisioning is accomplished using the Provisioning EOs and provisioning MSOs.

'''Reboot''' Cold reboot occurs when a system is powered off and then powered on. In a warm reboot, the hardware remains powered on and provisioning is not disturbed; the OS is re-started.

'''Remote Method Dispatch (RMD)''' Remote Method Dispatch is the foundation for all OpenClovis SAFplus Platform client APIs. It implements remote procedure call semantics using both synchronous and asynchronous methods.

'''Resource''' A resource is any entity that can be managed by the OpenClovis SAFplus Platform. A resource is either hardware equipment (for example, a blade) or a software abstraction implemented by programs running on that hardware (for example, a software process).

'''Routing Table''' Based on the information in this table, IOC module selects a transport and the next IOC hop, to send a message towards its destination. Multiple routes (to the same destination) are required for fault tolerance.

'''Rule-Based Engine (RBE)''' Rule-Based Engine (RBE) provides a mechanism to create rules to be applied to the system instance databased 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.

'''Run Level''' Mechanism used to synchronize and order the execution of EOs within and across different OpenClovis SAFplus Platform instances.OpenClovis EOs are configured to execute at some run-level; therefore, they can be controlled by the Boot Manager's Run-Level Controller (RLC). For example, the Alarm Agent is configured at Level 2 after the Provisioning Agent, which is at Level 1. This implies that the Alarm Agent has some execution dependency on the Provisioning Agent and that there is some critical section in the Provisioning Agent's initialization code that needs to execute first before the Alarm Agent can continue its execution.

'''Shelf''' It is a structure/frame where one or more chassis are mounted.

'''Service''' Service is the output of a system that meets the specification for which the system is devised.

'''Service ID''' Uniquely references a service (OpenClovis SAFplus Platform or customer designed).

'''Simple Network Management Protocol (SNMP)''' Simple Network Management Protocol (SNMP) is a sub-agent, which provides the flexibility to manage platform and non-platform hardware and OpenClovis SAFplus Platform Information Model. Using SNMP, you can manage the attributes of an MO that includes run a get, set, or notification.

'''Route Station List''' List of EOs associated with an COR MSO that need to be visited before an attribute of that MSO is modified.

'''System''' The system consists of a collection of physical nodes and programs running on those nodes (Ex: A chassis with multiple blades and running software programs).

'''System Log''' A persistent file that records the significant events occuring in the system. Typical entries include events related to boot-up, shutdown, errors, recovery, operator commands, operator log-on and log-off. Each log entry contains a timestamp, reporting entity, affected entity, and severity code and operator identity (if applicable).

'''Transactions''' OpenClovis SAFplus Platform supports transactions in the following sense:
* Any service that changes the state of managed objects may provide three methods: validate(), update () and rollback(). All these methods must be successfully executed for the transaction to be complete. The affected MO state is also updated in the persistent COR database as part of the transaction.
* OpenClovis SAFplus Platform also supports complex transactions. A list of component (called route station list) may be associated with each MO/MSO. Each component in the list may provide the three methods listed above. The nested transaction is implemented as follows: The list is traversed top down and the validate method of each successive component is executed. When the last component in the list is reached, the update methods for all the components are executed. If there is any failure happening in the validate() callback, then the rollback () callback is executed for all the components involved in the transaction. The transaction is considered successful if no error is reported by validate method executed as part of transaction. Any error happening in the update phase or the rollback phase is not returned as transaction failure.

'''Transport''' OpenClovis term for user (system developer) provided communication facility, which provides IOC access to the physical medium.

Doc:latest/sdkguide/troubleshooting

2010-08-27T04:13:38Z

Senthilk:

==Troubleshooting SAFplus Platform==

'''Conventions:'''

* '''Sandbox'''

When you extract SAFplus Platform image (output of make images) into particular location, the following directory structure will be created

** <top-level>
*** bin -- Location of all SAFplus Platform as well as application binaries
*** etc -- Location of all SAFplus Platform configuration files
*** lib -- Location of all the libraries used by SAFplus Platform (except system)
*** modules -- Ignore this
*** share -- SNMP MIB related stuff. Ignore if you are not using SNMP features provided by SAFplus Platform.
*** var -- All the runtime data generated by SAFplus Platform and their locations inside var/
*** all the log files -- var/log
*** all the non persistent database files and other run time files -- var/run
*** all the persistent database files -- var/lib/<comp-name> where component name is currently ams and cor

This <top-level> directory is called '''sandbox'''.

===Environment Variables===

* '''ASP_SAVE_PREV_LOGS''' -- if set to 1 will save logs in the sandbox from the previous run of SAFplus Platform (if any) during SAFplus Platform startup into location specified by the environment variable ASP_PREV_LOG_DIR or to /tmp/asp_saved_logs, creating the directory if necessary. If set to 0, the logs will deleted. Default value is 1.

* '''ASP_PREV_LOG_DIR''' -- place where logs of previous SAFplus Platform run will be stored. Default value is /tmp/asp_saved_logs

* '''ASP_LOG_FILTER_DIR''' -- place where log filter file should be present. It should be named logfilter.txt. Default value /tmp

* '''CL_LOG_SEVERITY''' -- Environment variable used to set the log filter. You can export this env variable to any log severity like DEBUG, INFO, NOTICE, ERROR, etc. Note that setting of this env variable has higher priority than the log filter file explained above.

* '''CL_LOG_CODE_LOCATION_ENABLE''' -- Environment variable if set to 1, will show the file name, function name and line number when displaying logs. Default value is 0.

* '''ASP_RESTART_SAFplus''' -- if set to 1 will restart SAFplus Platform in case AMF crashed or SAFplus Platform was not able to come up for some reason, if set to 0 will not restart SAFplus Platform. Default value is 1.

* '''ASP_APP_BINDIR''' -- Can be used to specify if the application binaries are stored in a different place than <sandbox>/bin directory.

===Logging===

* The logs generated by SAFplus Platform are present in two places:
** Standard out/standard error & startup/shutdown: -- stored in <sandbox>/var/log/<node-name.log>
*** Output can be controlled by log filter
** By Log infrastructure -- stored in <sandbox>/var/log/<stream-name>.latest (by default)
*** sys and app are two streams created by default. The "sys" logs are logs coming from the SAFplus Platform, "app" logs come from your programs. For e.g. var/log/sys.latest will contain log messages written to the system stream.
*** Output cannot be controlled by log filter
* Log filter file

The log filter file lets you selectively filter logging at log generation time, so that you can focus on debugging a subset of components. The log filter file is a text file located at /tmp/logfilter.txt OR $(ASP_LOG_FILTER_DIR)/logfilter.txt (i.e. you may set this env variable to your preferred directory).

Log filter file should contain one rule per line, where the format of the rule is as follows:

<pre>
(<node-name>:<component-eo-name>.<area>.<context>)[file_name]=<severity>
</pre>

The '*' matches anything and can be used in any field. Any line starting with # starts a comment.

<code><node-name></code> is the name of the SAFplus Platform node as found in etc/asp.conf

<code><component-eo-name></code> can be found by looking in etc/clEoConfig.xml

<code><area></code> and <code><context></code> are string that denote particular sub component of the component.

<code><file_name></code> refers to the name of the file in which the message was logged.

E.g.:

* show debugging (and greater severity) messages from all the components, useful when debugging.
<code><pre>
(*:*.*.*)[*]=DEBUG
</pre></code>

* show debugging messages only from AMF and error messages from all the other components (note that both lines are required)
<code><pre>
(*:*.*.*)[*]=ERROR
(*:AMF.*.*)[*]=DEBUG
</pre></code>

* show debugging messages of AMF and CKPT
<code><pre>
(*:*.*.*)[*]=ERROR
(*:AMF.*.*)[*]=DEBUG
(*:CKP.*.*)[*]=DEBUG
</pre></code>

Please refer to section 5.1.1.8 of OpenClovis 3.1 SDK guide for more information.

* Enabling openais logs
** In etc/clGmsConfig.xml file change the value of tag "openAisLoggingOption" from "none" to "stderr".

===Possible errors during startup of SAFplus Platform and solutions/workarounds===

As you troubleshoot using the logs, note that when an error occurs the system
shuts down and issues a lot of logging describing its shutdown actions. These
logs are not going to help diagnose the problem. Instead you need to find the
error that caused the shutdown. A general rule of thumb is to look for the
first error in the file...

Please look for messages at the log levels of ERROR, CRITICAL and if they are any of the following, follow the steps as mentioned in the Solution section.

<hr>
 '''Error:'''
 
<code>
Fri Jan 2 04:50:09 1970 (SCMI0.256802883 : AMF.---.---.00035 : NOTICE) AMF
server fully up
 
Fri Jan 2 04:50:09 1970 (SCMI0.256802883 : AMF.CPM.LCM.00037 : NOTICE)
Launching binary image [asp_logd] as component [logServer_SCMI0]...
 
Fri Jan 2 04:50:09 1970 (SCMI0.256921623 : LOG.---.---.00015 : ERROR) Error
finding opening shared library 'libClSQLiteDB.so': No such file or directory
 
Fri Jan 2 04:50:09 1970 (SCMI0.256921623 : LOG. EO.INI.00016 : CRITIC)
Failed to initialize basic library [Dbal], error [0x30011
 
Fri Jan 2 04:50:09 1970 (SCMI0.256921623 : LOG. EO.INI.00017 : CRITIC)
Failed to initialize all basic libraries, error [0x30011]
 
Fri Jan 2 04:50:09 1970 (SCMI0.256921623 : LOG. EO.INI.00018 : CRITIC)
Exiting : EO setup failed, error [0x30011]"
</code>

 '''Solution:'''
 
This problem means that proper database has not been specified in the file
etc/clDbalConfig.xml. Please uncomment the proper "Engine" tag in this
file. (For qnx it is libBerkeleyDB.so)


<hr>
 '''Error:'''
 
<code>
Wed Nov 19 10:20:35 2008 (SysCtrlI0.29013 : GMS.GEN.---.00032 : NOTICE) GMS
Server registering with debug service
 
Wed Nov 19 10:20:35 2008 (SysCtrlI0.29013 : GMS.GEN.---.00033 : DEBUG)
LINK_NAME env is exported. Value is eth1
 
Wed Nov 19 10:20:36 2008 (SysCtrlI0.29013 : GMS.GEN.---.00034 : EMRGN)
ioctl() system call failed while getting details of interface [eth1]
 
Wed Nov 19 10:20:36 2008 (SysCtrlI0.29013 : GMS.GEN.---.00035 : EMRGN) -
ioctl() returned error [Cannot assign requested address]
 
Wed Nov 19 10:20:36 2008 (SysCtrlI0.29013 : GMS.GEN.---.00036 : EMRGN) -
This could be because the interface [eth1] is not configured on the system
 
Wed Nov 19 10:21:25 2008 (SysCtrlI0.28990 : AMF.TSK.POL.00042 : INFO)
Creating new task
 
Wed Nov 19 10:21:25 2008 (SysCtrlI0.28990 : AMF.---.---.00043 : ERROR)
Component [gmsServer_SysCtrlI0] did not instantiated within the specified
limit
 
Wed Nov 19 10:21:25 2008 (SysCtrlI0.28990 : AMF.---.---.00044 : ERROR)
Component gmsServer_SysCtrlI0 did not start within the specified limit
</code>

 '''Solution:'''
This error is because of the ethernet interface specified in asp.conf (as
value of LINK_NAME env variable) is not present in the system.


<hr>
 '''Error:'''
 
<code>
Thu Jan 1 02:25:00 1970 (SCMI1.2818074 : AMF.CPM.GMS.00075 : ERROR) Failed
to receive GMS cluster track callback, error [0x10014]
</code>

 '''Solution:'''
Please make sure that firewall is not enabled on the machine. Try increasing
the value of "bootElectionTimeout" in etc/clGmsConfig.xml to some higher
value (default value is 5, try making it 10 or 15). If this doesn't help,
try enabling the openais logs as indicated in the logging section, to see if
any other unwanted node is communicating with this node.


<hr>
 '''Error:'''
 
<code>
Wed Nov 19 09:33:39 2008 (SysControllerI0.6139 : GMS.LEA.---.00068 :
CRITIC) No nodes in the cluster view to run leader election.
 
Wed Nov 19 09:33:39 2008 (SysControllerI0.6139 : GMS.LEA.---.00069 :
CRITIC) - This could be because:
 
Wed Nov 19 09:33:39 2008 (SysControllerI0.6139 : GMS.LEA.---.00070 :
CRITIC) - Firewall is enabled on your machine which is restricting multicast
messages
 
Wed Nov 19 09:33:39 2008 (SysControllerI0.6139 : GMS.LEA.---.00071 :
CRITIC) - Use 'iptables -F' to disable firewall
 
Wed Nov 19 09:33:39 2008 (SysControllerI0.6139 : GMS.LEA.---.00072 :
ERROR) Error in boot time leader election. rc [0x11]
</code>

 '''Solution:'''
This error is coming because, GMS uses IP Multicast and if firewall is
configured on your machine, then it would be blocking the multicast
messages. Hence GMS is not able to see any node joins in the cluster, as
described in the above error message.

To resolve this problem you can run "iptables -F" command on the machine
which will flush all the firewall rules and enable IP multicast. Note that
this setting remains until next reboot of the node. So you need to run
this command every time you reboot your machine. Otherwise, contact your
system administrator to disable or configure the firewall to allow IP
multicast.


<hr>
 '''Error:'''
 
<code>
Thu Jan 1 02:26:55 1970 (SCMI1.2818074 : AMF.AMS.BOO.00116 : CRITIC)
Inconsistency between GMS and TIPC configuration detected, master address as
per GMS is [0x1], but master address as per TIPC is [0x2]
</code>


 '''Solution:'''
Please make sure that the value of "multicastPort" is not clashing with that
of any other nodes, except the one that are configured in the cluster. Similary make sure that TIPC netid (exported as TIPC_NETID in etc/asp.conf) is not clashing with other unwanted nodes.


<hr>
 '''Error:'''
 
<code>
Thu Jan 1 01:26:28 1970 (SCMI0.13049881 : AMF.---.---.01234 : CRITIC)
Duplicate entry SCMI0 in AMS configuration"
</code>


 '''Solution :''' same as above 

<hr>
 '''Error:'''
 
<code>
Error in parsing XML tag <tag-name> in file [clAmfDefinitions.xml]
 
Fri May 23 20:25:17 2008 (SCMI0.9282 : AMF.---.---.00071 : CRITIC) Fn
[clAmsParserMain (DEFN_FILE_NAME,CONFIG_FILE_NAME)] returned [0x220105]
 
Fri May 23 20:25:17 2008 (SCMI0.9282 : AMF.---.---.00072 : ERROR) ALERT
[clAmsInitialize:293] : Fn
[clAmsParserMain(DEFN_FILE_NAME,CONFIG_FILE_NAME)] returned [0x220105]
 
Fri May 23 20:25:17 2008 (SCMI0.9282 : AMF.CPM.AMS.00073 : CRITIC) Unable
to initialize AMS, error = [0x220105]
</code>

 '''Solution:'''
This means that there was an error in parsing the XML configuration file. This error should not occur unless you have hand edited the XML file. In case the error does occur, it indicates either SAFplus Platform IDE modelling error or bug in SAFplus Platform.


<hr>
 '''Error:'''
 
<code>
DBAL: .: No such file or directory
 
DBAL: PANIC: No such file or directory
 
DBAL: environment open: DB_RUNRECOVERY: Fatal error, run database recovery
</code>


 '''Solution:'''
Unfortunately this errors comes only on QNX and we are still looking into resolving the same. Simply restarting the SAFplus Platform may make the problem go away.


<hr>
 '''Error:'''
 
<code>
Tue Jun 10 21:45:41 2008 (SCMI1.13591 : AMF.CPM.AMS.00372 : CRITIC)
Node failfast called on [standby] node [ SCMI0] !!!
This indicates that the cluster has become unstable. Doing self
shutdown...
</code>


 '''Solution:'''
This error indicates that:
* There was a change in network configuration of the cluster.
* Some other nodes are interfering with the cluster. Please make sure TIPC netid and GMS port are same on all the nodes of the cluster and is unique per cluster.


<hr>
 '''Error:'''
 
<code>
Tue Jul 22 10:33:43 2008 (SCMI0.5935 : AMF.---.---.00192 : ERROR) Component
[<comp-name>] did not instantiated within the specified limit
 
Thu Jan 1 01:00:55 1970 (SCMI0.3211296 : AMF.---.---.00376 : ERROR)
Component [<comp-name>] instantiate error [0x220014]. Will cleanup
</code>


 '''Solution:'''
These error messages indicates that SAFplus Platform was not able to start the component within the configured timeout value in clAmfDefinitions.xml file. Possible reasons for this happening are:
* Component is taking too long to start. For e.g. it may be taking a lot of time in initialization etc. Increasing the instantiation timeout value (using IDE or if you know what you are doing, directly in clAmfDefinitions.xml file itself) should help in this case.
* Component has crashed before registering with AMF. Look for core dump in <sandbox>/var/run/ (for linux) or in /root (for qnx) to see if the component has dumped core.


<hr>
 '''Error:'''
 
<code>
Thu Jan 1 01:25:43 1970 (SCMI0.13049881 : AMF.---.---.00814 : ERROR) SI
[<si-name>] assignment to SU [<su-name>] returned Error [0x220014]
</code>


 '''Solution:'''
This error message indicates that SAFplus Platform was not able to assign work(SI) for particular SU due to time out. Possible reasons for this error are:
* The component crashed in the work assignment processing callback i.e. csi set/remove callback.
* The component is not responding with saAmfResponse(clCpmResponse) function within the csi set/remove timeout value configured in clAmfDefinitions.xml file.


<hr>
 '''Error:'''
 
<code>
Wed Nov 19 09:50:49 2008 (SysControllerI0.20584 : AMF.TRIGGER.INI.00073
WARN) Trigger XML parse error. Running with defaults
</code>

 ''' Solution:'''
Above warning message are related to AMF entity trigger framework and they
can be ignored.


<hr>
 '''Error:'''
 
<code>
12:25:33:Mon Nov 17 15:32:59 2008 (SysControllerI0.11049 : GMS.GEN.---.
00201 : ERROR) This sync message is not intended for this node
</code>


 '''Solution:'''
This error message is releated to GMS process group service and can be ignored.


<hr>
 '''Error:'''
 
<code>
Thu Jan 1 04:25:48 1970 (SCMI0.39657513 : AlarmMgr_EO.ACU.IDG.39051 : ERROR) Failed to get the alarm index for probable cause [2] and specific problem [0]
 
Thu Jan 1 04:25:48 1970 (SCMI0.39657513 : AlarmMgr_EO.ALM.ALE.39052 : ERROR) Failed to get the alarm index for the probable cause [2]:Specific Problem [0]. rc[0x4]
 
Thu Jan 1 04:25:48 1970 (SCMI0.39657513 : AlarmMgr_EO.ALM.ALR.39053 : ERROR) Failed while processing the alarm . rc[0x4]
 
Thu Jan 1 04:25:48 1970 (SCMI0.39657513 : AlarmMgr_EO.ALM.ALR.39054 : ERROR) Failed while Sending RMD to the client owning the alarm resource. rc[0x4]
 
Thu Jan 1 04:25:48 1970 (SCMI0.39657513 : AlarmMgr_EO.---.---.39055 : ERROR) Error in raising alarm, rc [0x4]
</code>


 '''Solution:'''
This error message shows that the user is trying to raise alarm with invalid probable cause and specific problem combination which is not modeled. Please check the list of alarm profiles attached to that resource, inside alarm owner
cl<comp-name>alarmMetaStruct.c file.


===Informational messages to observe in SAFplus Platform log files===
<hr>
 '''Message:'''
 
<code>
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00206 : DEBUG) GMS CONFIGURATION CHANGE
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00207 : DEBUG) GMS Configuration:
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00208 : DEBUG) r(0) ip(192.168.11.11)
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00209 : DEBUG) r(0) ip(192.168.90.44)
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00210 : DEBUG) Members Left:
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00211 : DEBUG) r(0) ip(192.168.90.43)
 
Mon Nov 17 15:35:08 2008 (SysControllerI0.11049 : GMS.OPN.AIS.00212 : DEBUG) Members Joined:
</code>

 '''Description:'''
These messages above are indicating the join/leave states of the nodes in
the cluster. In the above sample output, you can note that the node with IP
192.168.90.43 has left the cluster and at this point the cluster configuration has nodes 192.168.11.11 and 192.168.90.44.

This info will be useful when debugging few issues where a node is repeatedly going down or not behaving as expected.


<hr>
 '''Message:'''
 
<code>
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00827 :
CRITIC) CPM/G active got IOC/TIPC notification for node [3] --
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00828 :
CRITIC) - Possible reasons for this are on node [3] :
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00829 :
CRITIC) - 1. AMF crashed.
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00830 :
CRITIC) - 2. AMF was killed.
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00831 :
CRITIC) - 3. Critical component failed.
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00832 :
CRITIC) - 4. Kernel panicked.
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00833 :
CRITIC) - 5. Communication was lost.
 
Mon Nov 17 15:35:10 2008 (SysControllerI0.11014 : AMF.CPM.AMS.00834 :
CRITIC) - 6. AMF was shutdown.
</code>

 '''Description:'''
Above error message means that this node has detected TIPC notification for node death for node 3 and the message also explains probable reasons for this to happen. So user need to observe if this node death was due to admin operations or due to any error.


<hr>
 '''Message:'''
 
<code>
Mon Nov 17 15:35:44 2008 (SysControllerI0.11014 : AMF.CPM.GMS.00844 : DEBUG) Received cluster track callback from GMS on node [SysControllerI0]
...
 
Mon Nov 17 15:35:44 2008 (SysControllerI0.11014 : AMF.CPM.GMS.00845 : DEBUG) - Leader : [1]
 
Mon Nov 17 15:35:44 2008 (SysControllerI0.11014 : AMF.CPM.GMS.00846 : DEBUG) - Deputy : [3] (-1 -> No deputy)
</code>


 '''Description:'''
Above message indicates the result of leader election for system controllers. As it is described after this leader election node 1 has become active (leader) and node 3 is standby (deputy). If Deputy value is -1, it indicates that there is only 1 system controller running in the cluster.


<hr>
 '''Message:'''
 
<code>
Wed Nov 19 10:11:49 2008 (PayloadNodeI0.23101 : GMS.LEA.---.00100 :
WARN) Could not elect any leader from the current cluster view.
 
Wed Nov 19 10:11:49 2008 (PayloadNodeI0.23101 : GMS.LEA.---.00101 : WARN)
- Possibly no system controller is running
 
Wed Nov 19 10:11:49 2008 (PayloadNodeI0.23101 : GMS.CLM.---.00102 : ERROR)
Leader election failed. rc = 0x0
 
Wed Nov 19 10:12:11 2008 (PayloadNodeI0.23068 : AMF.CPM.CPM.00081 : WARN)
CPM/G standby/Worker blade waiting for CPM/G active to come up...
</code>


 '''Description:'''
Above 2 warning messages indicate that a payload node was started without having any system controller node running in the cluster.


<hr>
 '''Message:'''
 
<code>
Tue Nov 18 16:24:48 2008 (ctrlI0.17729 : AMF.CPM.LCM.00339 : NOTICE)
[clCpmComponent.c:1885] Launching binary image [ClusterMgr] as component
[ClusterMgrI0]...
 
Tue Nov 18 16:24:48 2008 (ctrlI0.17729 : AMF.CPM.LCM.00340 : INFO)
[clCpmComponent.c:1952] Component [ClusterMgrI0] started, PID [17822]
</code>


 '''Description:'''
These logs indicate that the AMF attempted to start your component.


<hr>
 '''Message:'''
 
<code>
Tue Nov 18 16:24:48 2008 (ctrlI0.17729 : AMF. SU.INST.00343 : INFO)
[clAmsPolicyEngine.c:6615] SU [ClusterMgrSUI0] instantiated [1] components
at level [1]
</code>


 '''Description:'''
This log indicates that your component registered with the AMF.


===Essential <code>asp_console</code> commands to understand the system state of SAFplus Platform===

The asp_console command in <sandbox>/bin directory is a very useful utility
to understand the SAFplus Platform state at any point of time. After starting SAFplus Platform, you
can start it using:

<code><pre>
$ cd <sandbox>
$ ./bin/asp_console
</pre></code>

You will see a message and the following prompt like this:

<code><pre>
To get started, type 'help intro'

cli[Test]->
</pre></code>

If you are a first time user please give the command "help intro" as
indicated and read the brief help message.

You can press TAB to autocomplete any command or show the list of all the commands.

Press ? to see the list of available commands

Typing list (or li, if a command has unique prefix, then just typing that and pressing enter is equivalent to giving that command) in the above prompt gives:

<code><pre>
cli[Test]-> list

Slot Node
1 SCNode0

cli[Test]->
</pre></code>

It means that currently cluster is running with one node named SCNode0. You
MUST see in this list as many nodes as you have started, that are meant to
be part of this cluster. Otherwise it means that the nodes are not communicating because of either GMS or TIPC issues as indicated above. Make sure that GMS multicast port as well as TIPC netid is same on all the nodes involved.

Type the command setc ("set context") followed by the slot to change context to the node "master" i.e. the active node in the cluster.

<code><pre>
cli[Test]-> setc master
</pre></code>

and you should see a prompt like this:

<code><pre>
cli[Test:SCNode0]->
</pre></code>

(please remember that you can type either 'help' or ? to see list of
available commands)

You can also "setc" to a particular slot by passing a number:

<code><pre>
cli[Test]-> setc 1
</pre></code>

but this is used rarely.

Type the command setc again this time to change context to a particular component within node 1 i.e. SCNode0. You can type the command 'list' to see the list of available components. You can register your application component too with this console using debug cli client library.

<code><pre>
cli[Test:SCNode0]-> list
cpm
corServer_SCNode0
faultServer_SCNode0
eventServer_SCNode0
nameServer_SCNode0
txnServer_SCNode0
gmsServer_SCNode0
alarmServer_SCNode0
logServer_SCNode0
ckptServer_SCNode0

cli[Test:SCNode0]->
</pre></code>

to change context to AMF for e.g. give the following command

<code><pre>
cli[Test:SCNode0]-> setc cpm

cli[Test:SCNode0:CPM]->
</pre></code>

You can type help to see the available commands followed by a brief descriptive message about what the command does.

To move up a context (i.e. from component context to node context or from node context to top level context) type the command 'end'. For e.g.

<code><pre>
cli[Test:SCNode0:CPM]-> end

cli[Test:SCNode0]->
</pre></code>

The SAFplus Platform components except for the AMF, are suffixed by the node name.

To view if the cluster is in a consistent state give this command:

<code><pre>
cli[Test:SCNode0]-> setc gmsServer_SCNode0

cli[Test:SCNode0:gms]-> memberList 0

--------------------------------------------------------------------------------------------------------

Cluster/Group Name : cluster0
bootTime : Wed Nov 12 17:36:56 2008
View Number : 2
--------------------------------------------------------------------------------------------------------
NodeId NodeName HostAddr Port Leader Credentials PrefLead LeadshipSet BootTime
--------------------------------------------------------------------------------------------------------
1 SCNode0 1 9 Yes 100 No No Wed Nov 12 17:36:56 2008
2 SCNode1 2 9 No 100 No No Wed Nov 12 19:28:42 2008

cli[Test:SCNode0:gms]->
</pre></code>

Again, you should see as many nodes as configured in the cluster. In the
above output, node with id 1 is a leader.

To see if a node has come up properly:
(don't forget:
setc master
setc cpm
to get into the correct context!)

<code><pre>
cli[Test:SCNode0:CPM]-> amsentityprint node SCNode0

Name | SCNode0
Configuration ------------------------------- | ---------------------------
Start time | Wed Nov 12 17:37:02 2008
Admin State | Unlocked
Computed Admin State | Unlocked
Id | 0
Class Type | Class B
SubClass Type |
Is Swappable | True
Is Restartable | True
Is SAFplus Platform Aware | True
Auto Repair on Join | True
SU Failover Probation Time | 10000 ms
SU Failover Count | 10
Node Dependents | Count[0]
| <None>
Node Dependencies | Count[0]
| <None>
SUs in Node | Count[6]
| SC0_twoNAdmin_SU0
| SC0_amsTestGenTC_SU0
| SC0_noRedundancy_SU0
| SC0_twoNRank_SU0
| SC0_twoNRank_Spare_SU1
| SC0_twoNRank_Spare_SU0
Status -------------------------------------- | ---------------------------
Presence State | Instantiated
Oper State | Enabled
Is Instantiable | True
Is Cluster Member | True
Was Cluster Member Before | False
Last Recovery | None
Num Instantiated SUs | 0
Num Assigned SUs | 0
SU Failover Probation Timer | Inactive
SU Failover Count | 0
--------------------------------------------- | ---------------------------
Timers Running | 0
Debug Flags | 0x1
</pre></code>

===Miscellaneous===

* Please note that by default, SAFplus Platform assumes that the shared memory location (tmpfs) is mounted on standard location /dev/shm and cleans up whatever shared memory segments created by the SAFplus Platform during previous run. If you have mounted your tmpfs some where else, you have two options:
** Mount the tmpfs to /dev/shm so that SAFplus Platform will take care of cleaning up shared memory segments. ('''Recommended''')
** During packaging of the model add a cleanup script in model-name/src/extras/asp.d/ (creating this location if it is not there) which will be called with 'start' argument before SAFplus Platform starts. This cleanup script can then remove the shared memory segments from whichever location the tmpfs is currently mounted on.
* Please note that starting SAFplus Platform "by hand" is not supported, i.e. starting asp_amf executable by command line is not supported. The starting of SAFplus Platform depends for some setup/cleanup actions on the SAFplus Platform startup script and hence SAFplus Platform should always be started using the etc/init.d/asp script.

Doc:latest/sdkguide/knowledgebase

2010-08-27T04:12:11Z

Senthilk:

=='''Knowledge Base'''==

===Logging===

====What is the default log rotation policy, and how can it be set?====
The default file rotation policy is WRAP (as specified by fileFullAction
tag in clLog.xml file in <model-name>/src/config or <sandbox>/etc/).
This value has to be specified per stream.

The value WRAP means that the log service will start to overwrite the
file once log file becomes full (the file size can be specified by
fileUnitSize tag (again per stream).

Other possible actions are HALT and ROTATE. HALT means that log service will stop writing into file as soon as it becomes full. ROTATE policy means that log service will rotate the logs up to certain number of files (as specified by maximumFilesRotated tag) before overwriting the oldest log file. This is similar to the policy used by /var/log/messages.

It can be set either in IDE or by hand modifying the clLog.xml file. In
IDE you can set it under log section in SAFplus Platform component configuration in
clovis menu. Please refer to ide user guide section 7.2.2. Only thing to
remember is that you need to set maximumFilesRotated to 0 if rotation
policy is either HALT or WRAP.

Programmatically it can be set when you are creating a new log stream using clLogStreamOpen() API. You need to set the fileFullAction field of pStreamAttr field (of type ClLogStreamAttributesT) which is fourth parameter to clLogStreamOpen() API.

====Can it be set dynamically?====

Once the stream is already opened with a set of attributes (through APIs at runtime), its attributes cannot be changed thereafter. So if you already opened a stream with fileFullAction set to ROTATE, you cannot change it to HALT.

====Is there a way to operationally force a log file rotation?====
The rotation for nodename.log files could be forced through debug cli on cpm context.

bin/asp_console

setc master ;setc cpm; logrotate

(setc master would directly work on AMF master. You could also do : setc <slotid> to target a particular node listed with "list")

After the above debug cli, a subsequent: amsdbprint output goes to a new nodename.log and the last one is moved to nodename.log.1.

I also found it pretty useful.

Unrelated though but useful for you:
export CPM_LOG_FILE_SIZE=5m
export CPM_LOG_FILE_ROTATIONS=3
would force the nodename log files to be rotated within 5MB limit 3 times.

The default is 10MB, 4 rotations.

====Is the flush interval applicable to log server or log client?====

This is applicable to the Log server. i.e. When an application has any logs to be written, the log client would immediately write the records into the shared memory, and it won't wait for the flush interval. However, the log server would flush these records from the shared memory to the log handler (a file) at the given flush interval. This means that if a component crashes or hangs all logs will be written. However if the board fails, it is possible to lose all logs that haven't been flushed.

====Does SAFplus Platform take any action when we fail to log? For example, if the log server is not able to log the records because the disk is full, then do we take any action so that we failover?====

No. As of now the log server does not escalate this error to the AMF and hence failover is not done.

====Can logs appear on both the system controller nodes?====

By default the SAFplus Platform is configured to log to a local file for debugging convenience. However, the SAFplus Platform allows logs to be sent to other nodes in the system via configuration in the log.xml file. Additionally, a program on any node can always open any global log stream and process or forward the logs in any desired manner. See the Log API documentation for more details.

===Startup Log Messages===

====Invalid [identifier] value in tag or attribute, rc=[0x0]====

====ERROR) Cannot get IOC master, return code [0x50016]====
These can be ignored during bootup. "Cannot get IOC master" from log server during bootup is the phase during which AMF awaits leader election callback from GMS for the cluster leader and our log service is dependent on this since it also has HA.

====ERROR) Configuration file [.../etc/clAmfEntityTrigger.xml] is missing====
The AMF trigger xml parse error is fine (unless, of course you are using the AMF trigger feature). It refers to a feature w.r.t feeding triggers into a amftrigger framework controlled by thresholds for various entities as defined in clAmfEntityTrigger.xml which won't be present for normal cases.

====ERROR) Parser open error for file [clAmfEntityTrigger.xml]====
The AMF trigger xml parse error is fine (unless, of course you are using the AMF trigger feature). It refers to a feature w.r.t feeding triggers into a amftrigger framework controlled by thresholds for various entities as defined in clAmfEntityTrigger.xml which won't be present for normal cases.

====WARN) DB not present. Reading AMS config from XML====
The DB read warning from AMS means that you are either doing a first time startup or a start with --remove-persistent-db option (./etc/init.d/asp start --remove-persistent-db). It means that the model configuration is being read from XML files instead of from database, so the model that comes up will be the unmodified model created in the IDE. Any modification you may have made through the AMF mgmt API calls are stored in the DB.

===Alarms===

====Could I replace OpenClovis's alarm mib (current alarm table...) with a proprietary MIB?====
First of all there is no OpenClovis' propriety alarm MIB. Customers can use any propriety MIB with alarms defined and the generated code would take care of raising traps when an alarm is raised.

====Is there an alarm history mib?====
No. But the alarm history can be viewed/queried via our debug CLI commands viz. queryAlarm, querypublishedAlarms, showpublishedAlarms.

===Mixed Endian and Mixed Word-size (Heterogeneous) Clusters===

====How are mixed endian and mixed word-size clusters supported?====

Certain OpenClovis communications mechanisms, notably RMD (our remote procedure call library), allow communications to occur between machines of different endian (endian agnostic). Since all OpenClovis components are based on RMD, this allows OpenClovis to run in a heterogeneous environment.

Xdr is the library that transforms data structures to and from network-endian format (and into canonical-size data items) so that they can be sent to other machines. RMD uses Xdr internally to implement its endian-agnostic feature.

The customer can also take advantage of XDR and RMD. There are 2 ways; first, you can always just access the APIs directly (for example the APIs located in clXdrApi.h to do endian-swapping). Secondly, by defining your remote procedure calls in an XML format that we call "IDL" we will automatically generate wrappers around the RMD and XDR APIs that implement the marshalling and unmarshalling required to do a remote procedure call, with the result that on the client side the remote procedure call looks just like a normal function call.

====Is Mixed Endian Checkpointing supported?====

The SAF checkpoint API does not handle endian-swapping as it is defined based on a byte buffer. Unfortunately, without knowing the structure of the data it is impossible to byte-swap data to be checkpointed. Therefore to implement endian-safe checkpointing, you first transform the buffer via calls to the XDR library, and then write the checkpoint. Of course, upon read you must again use XDR to transform the buffer back to the machine's endian.

====Are there any limitations to using mixed endian in the cluster?====

The 2 system controllers must be of the same architecture (endian and word size). By requiring this, we reduce the latency and the CPU utilization of the communication that occurs between the 2 system controllers.

===Failovers===

====When a split brain scenario (double failure of ethernet link) is healed, who becomes master?====

In case of split brain, always the node with higher node ID will take over as leader. So you could set a higher node ID to the node which you want to be the leader, and this will take effect on merge from split brain.

===Healthcheck/Heartbeat===

====Is component health check supported?====

Yes, there are two component heathcheck mechanisms, passive and SAF. Passive healthchecking is enabled by default. To enable the SAF healthcheck just use the SAF APIs supported by OpenClovis. The minimum SAF healthcheck period is 5 seconds. However, the passive healthcheck operates in the order of few milliseconds. Essentially, the SAFplus Platform intranode communications mechanism implements a healthcheck. Whenever a component dies, the TIPC Linux driver is notified since each component has open TIPC sockets. The SAFplus Platform AMF receives TIPC notifications of component deaths and publishes an event. Any of your applications interested in knowing the departure of the component can subscribe for these events and act appropriately. Note that this is the faster means of healthcheck (in the order of few milliseconds), and this is the reason active healthcheck is disabled by default. To use this means of healthcheck your program simply must quit or abort (exit(), abort(), assert() for example) when it has an unrecoverable error.

This passive heartbeating through TIPC avoids majority of the requirement for a SAF-style healthcheck except for the case when the component is deadlocked. To take care of this case you can enable SAF healthcheck, or you can create your own periodic thread that analyses verifies the operation of your program and exits if there is a problem.

===AMF Configuration (Cluster-wide Application Structure)===

====Load Balancing Applications: We have two applications that have a dependency on each other, such that if either one restarts the other must also be restarted. The complication is they are running on separate blades, and therefore separate service groups. Can you suggest how we can restart the dependant application when either is restarted?====

There are 2 ways of adding dependencies in the system, inter-node and inter-Service Instance.

If you want application 1 to depend on 2, then I would recommend using SI (service instance) dependencies. SI dependencies essentially means that the dependent application (2) will not be "unlocked" until application 1 is unlocked, and 2 will be "locked assignment" if 1 fails. Now this may not be quite what you were asking for, because you wanted 2 to be "restarted" (aka "locked instantiation" in SAF terminology), not just moved to "locked assignment". However, it should not be too hard to implement "shutdown" logic at the application layer in app 2 whenever the app is "locked assignment".

The best "shutdown" implementation would be to stop the app's processing and wait in an idle loop. That interpretation is most in line with SAF concepts and will help you when you add HA to the systems.

To set up SI dependencies, in the IDE use Clovis->AMF Configuration->Service Group List->(pick dependent SG)->Service Instance List->(Pick your SI)->Dependencies Edit button. A dialog box will pop up showing all SIs in the system. Pick the one you want to be dependent on.

The inter-node method creates dependencies between nodes, which only is useful to solve the above problem if you are running just one application on each node.
If you want the system to require blade B, than you can specify all other blades to be dependent on B. This is available in the IDE under the Clovis->AMF Configuration->Node Instance List->(pick dependent node)->Dependencies Edit button. Check node B and then click OK. You need to do this for every node that is dependent on B.

==== How do I make an application automatically run (or not run) when the SAFplus Platform is started? ====
You can start and stop applications using our debug cli; refer to the evaluation guide as to how to do so. But to have the system start up with a particular application stopped, you must modify the startup configuration. You may do so via the IDE and regenerate the configuration files, but in this case it will be faster to simply edit the config files directly.

Go to the system controller blade and load the file "/root/asp/etc/amfDefinitions.xml". In here, all of the "service groups" (SAF terminology for a highly available group of applications) are defined. Each definition looks like this:

<sgType name="vlcGroup_MN">
<failbackOption>CL_FALSE</failbackOption>
<restartDuration>10000</restartDuration>
<numPrefActiveSUs>2</numPrefActiveSUs>
<numPrefStandbySUs>1</numPrefStandbySUs>
<numPrefInserviceSUs>3</numPrefInserviceSUs>
<numPrefAssignedSUs>3</numPrefAssignedSUs>
<numPrefActiveSUsPerSI>1</numPrefActiveSUsPerSI>
<maxActiveSIsPerSU>1</maxActiveSIsPerSU>
<maxStandbySIsPerSU>2</maxStandbySIsPerSU>
<compRestartDuration>10000</compRestartDuration>
<compRestartCountMax>0</compRestartCountMax>
<suRestartDuration>10000</suRestartDuration>
<suRestartCountMax>0</suRestartCountMax>
<adminState>CL_AMS_ADMIN_STATE_LOCKED_I</adminState>
<redundancyModel>CL_AMS_SG_REDUNDANCY_MODEL_M_PLUS_N</redundancyModel>
<loadingStrategy>CL_AMS_SG_LOADING_STRATEGY_LEAST_SI_PER_SU</loadingStrategy>
<autoRepair>CL_TRUE</autoRepair>
</sgType>

Note that the first tag names the "service group":
<sgType name="vlcGroup_MN">

In this example the service group is named "vlcGroup_MN". Go down to the <adminState> tag. It is probably "CL_AMS_ADMIN_STATE_UNLOCKED". "Unlocked" is SAF terminology for "run this application". To not run the application when the system is started, change this field to "CL_AMS_ADMIN_STATE_LOCKED_I". "LOCKED_I" is short for "Locked Instantiation", which is the SAF terminology for "do not run this application".

So, specifically, set all service groups to "CL_AMS_ADMIN_STATE_LOCKED_I" except for the one named "vlcGroup". That one is the havlc program.

Remember to make this edit on the system controller! Making this change on any other blade will have no effect, since it is the system controller that starts and stops applications on all blades.

Doc:latest/sdkguide/commandref

2010-08-27T04:11:30Z

Senthilk:

==SAFplus Platform Command Line and Environment Variable Reference==

===Environment Variables===

====Variables controlling automatic restart or reboot of SAFplus Platform or Node====
* '''ASP_RESTART_SAFplus''' -- If set to 1 will restart SAFplus Platform in case AMF crashed or SAFplus Platform was not able to come up for some reason, if set to 0 will not restart SAFplus Platform. Default value is 1.
* '''ASP_NODE_REBOOT_DISABLE''' --
* '''ASP_NODE_RESTART''' --

 
This table describes the interaction between the various SAFplus Platform restart and reboot variables:
{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| ASP_NODE_REBOOT_DISABLE
!style="color:#66b154; background:#09477c"| ASP_RESTART_SAFplus Platform
!style="color:#66b154; background:#09477c"| ASP_NODE_RESTART
!style="color:#66b154; background:#09477c"| Action taken
|- style="color:#ffffff; background:#549cc6"
| undefined
| undefined
| undefined
| reboot
|- style="color:#ffffff; background:#549cc6"
| 1
| undefined
| undefined
| Restart SAFplus Platform
|- style="color:#ffffff; background:#549cc6"
| 1
| 0
| undefined
| SAFplus Platform stopped
|- style="color:#ffffff; background:#549cc6"
| 1
| 0
| 1
| Restart SAFplus Platform
|}

====Cluster Membership Configuration (GMS)====
* '''CL_LEADER_NODE_ID''' --
* '''LINK_NAME''' -- This tells SAFplus Platform which Network Interface (ex. eth0, bind0, lo, etc.) to be used for communication with other SAFplus Platform's on same/other nodes.
* '''ASP_MULTINODE''' -- This environment variable must be used, when multiple SAFplus Platform's are to be run on single machine. Then user must export this environment variable before starting each of SAFplus Platform's.

====ValGrind====
* '''ASP_VALGRIND_FILTER''' --
* '''ASP_VALGRIND_CMD''' --

====Logging====

* '''ASP_LOG_FILTER_DIR''' -- place where log filter file should be present. It should be named logfilter.txt. Default value /tmp
* '''CL_LOG_SEVERITY''' -- Environment variable used to set the log filter. You can export this env variable to any log severity like DEBUG, INFO, NOTICE, ERROR, etc. Note that setting of this env variable has higher priority than the log filter file explained above.
* '''CL_LOG_CODE_LOCATION_ENABLE''' -- Environment variable if set to 1, will show the file name, function name and line number when displaying logs. Default value is 0.
* '''CL_LOG_TO_FILE'''
* '''CL_LOG_STREAM_ENABLE'''
* '''CL_LOG_TIME_ENABLE'''
* '''CL_LOG_DEBUG_LEVEL''' (clLogDebug.c)
* '''ASP_SAVE_PREV_LOGS''' -- if set to 1 will save logs in the sandbox from the previous run of SAFplus Platform (if any) during SAFplus Platform startup into location specified by the environment variable ASP_PREV_LOG_DIR or to /tmp/asp_saved_logs, creating the directory if necessary. If set to 0, the logs will deleted. Default value is 1.
* '''ASP_PREV_LOG_DIR''' -- place where logs of previous SAFplus Platform run will be stored. Default value is /tmp/asp_saved_logs
* '''AMS_DEBUG''' -- Enable special availability management framework console logging. This occurs outside of the normal log infrastructure since the AMF process manages the logging process.
* '''AMS_NOTIFICATION_DEBUG''' --
* '''CPM_LOG_FILE_SIZE''' --
* '''CPM_LOG_FILE_ROTATIONS''' --
* '''ASP_CPM_LOGFILE''' --

====Miscellaneous====
* '''ASP_RMD_METRIC''' --
* '''CL_TXN_DSBLE_CKPT''' --
* '''CL_HEAP_DEBUG''' --
* '''CL_MEM_TIME''' --
* '''ASP_WITHOUT_CPM''' --
* '''CL_NODE_REPRESENTATIVE''' --
* '''ASP_DB_SYNC''' --

====Debugging====
* '''CL_DEBUG_PAUSE''' --
* '''CL_DEBUG_PAUSE_CODE_ERROR''' --
* '''CL_DEBUG_COMP_NO_KILL''' --
* '''CL_DEBUG_COMP_TIMEOUT_OVERRIDE''' --
* '''CL_DEBUG_LOG_LEVEL''' --
* '''CL_DEBUG_RESOURCE_LOG_LEVEL''' --
* '''CL_DEBUG_REVERSE_TIMING''' --

====Intra-Cluster Message Traffic Shaping====
OpenClovis SAFplus Platform optionally uses a well known traffic shaping algorithm to modulate intracluster traffic. This is very useful if the internal communications between your applications can potentially overwhelm an application with requests. But if your application's inter-communication is designed to ensure that this cannot happen then the traffic shaping is not needed. By default (compile time) it is off.

These environment variables can be used to override the default leaky bucket intra-cluster message shaping parameters.
* '''CL_LEAKY_BUCKET_VOL''' -- Leaky bucket volume in bytes
* '''CL_LEAKY_BUCKET_LEAK_SIZE''' -- Leaky bucket removal in bytes
* '''CL_LEAKY_BUCKET_LEAK_INTERVAL''' -- How often the leak occurs in milliSeconds

===Environment Variables Set by OpenClovis SAFplus Platform===
These variables are available for use in your application:

====Locations====
Note these environment variables have equivalent "C" global variables (defined in clEoApi.h) which are recommended over using the environment variable directly.

* '''ASP_NODENAME''' -- The name of the node (as defined in the SAF AMF model)
* '''ASP_COMPNAME''' -- The name of this component (as defined in the SAF AMF model)
* '''ASP_RUNDIR''' -- The "current working directory" SAFplus Platform runs from
* '''ASP_LOGDIR''' -- The SAFplus Platform log directory
* '''ASP_BINDIR''' -- The location of SAFplus Platform binaries
* '''ASP_APP_BINDIR''' -- The location of the program binary. This is often, but not always the same as ASP_BINDIR.
* '''ASP_CONFIG''' -- Directory of the SAFplus Platform configuration files (normally <asp install dir>/etc)
* '''ASP_CPM_CWD''' -- The current working directory to use for SAFplus Platform and programs started by SAFplus Platform (defaults to var/run)
* '''ASP_DBDIR''' -- The location the SAFplus Platform stores its database files

===Starting and Stopping SAFplus Platform: <aspDir>/etc/init.d/asp===
Usage : asp {start|stop|restart|console|status|zap|help} [options]

options can be one of the following : (these options only work with start command, e.g. etc/init.d/asp start -v etc.)

-v : Be verbose
--enforce-tipc-settings : Use etc/asp.conf's TIPC settings overriding the system TIPC settings
--ignore-tipc-settings : Use systems TIPC settings ignoring the etc/asp.conf's settings
--remove-persistent-db : Delete all of the SAFplus Platform persistent database files
--asp-log-level <level> : Start SAFplus Platform with particular log level. <level> is [trace|debug|info|notice|warning|error|critical]

===CLI===

====bin/asp_console====
SAFplus Platform console is a comprehensive CLI for examination and debugging of the SAFplus Platform system. SAFplus Platform console documentation is available as a separate document.

Start:
<aspDir>/etc/init.d/asp console
or
<aspDir>/bin/asp_console

====bin/asp_info====
The SAFplus Platform info CLI is a simple interface for display of SAFplus Platform status and basic control

<aspDir>/bin/asp_info

===Directly running a component: bin/asp_run===

Doc:latest/sdkguide/startermodels

2010-08-27T04:08:14Z

Senthilk:

=="Starter" Applications (Models)==

Experts at the OpenClovis IDE can brew a complex redundancy model from scratch in just an hour or two. However building a model from scratch is more difficult for a beginner than modifying an existing model. To help new users, the OpenClovis SAFplus Platform provides "starter" models that can be used to begin your model. These are different from the "eval" kit in that the eval kit is made to showcase the features and functionality of the SAFplus Platform and as such are defined to use a very minimal physical (2-3 nodes) layout and simple redundancy model. On the other hand, the "Starter" Models are useful models that you may base your model off of.

The models are located src/examples/ide_workspace (IDE model) and src/examples/ (generated code).

===The "Starter" Application - IP Address Failover - src/examples/virtualIp ===

This starter model implements a commonly-desired feature that is often considered difficult to implement, but becomes very simple on top of the OpenClovis SAFplus Platform infrastructure - IP address failover.

The idea behind IP address failover is to have a "virtual IP" address that can be moved from the active blade to another blade when the active fails. This is an essential component of many highly available network servers.

The Translation into a SAF/OpenClovis model is very simple. Each Virtual IP address is defined as a "Component Service Instance" (CSI), essentially a "work assignment". Each CSI contains the IP Address (e.g. 192.168.1.2) and the physical network interface (e.g. eth0) on which it should be assigned. When the OpenClovis SAFplus Platform "assigns" the CSI to a blade, the software assigns the IP address to the physical network interface using the standard linux "ifconfig" utility. It then issues a "gratituous ARP" to notify the larger network of the IP address change. When the OpenClovis SAFplus Platform "removes" the CSI from a blade, the software removes the IP address from the physical network interface using "ifconfig".

The only custom code needed is the application-specific code needed to bring up an interface and issue the gratituous ARP.

This model can be packaged with the OpenClovis SAFplus Platform or as an application-only deployable bundle (using SAFplus Platform Web Director). To create an application-only bundle, first build SAFplus Platform package normally (i.e. configure; make). Next, go to the "virtualIp/bundle" directory and type "make". An application tarball will be created.

Doc:latest/sdkguide/envvars

2010-08-27T03:57:55Z

Senthilk:

==Runtime environmental variables exported by the OpenClovis SAFplus Platform environment==

Following are the environmental variables exported by the OpenClovis SAFplus Platform environment, which are available to the application developers. Using these environmental variables to create additional files/logs (if any) etc is recommended, because in case of any problems in SAFplus Platform, it will be easier to correlate the log files present in these locations and hence to diagnose the cause of the problem.

* '''ASP_DIR''' - Location of the sandbox directory, i.e. the directory in which SAFplus Platform is deployed.
* '''ASP_RUNDIR''' - Default working directory of application components.
* '''ASP_LOGDIR''' - Place where the log files should be created. (This can be overridden using the clLog.xml, but it is recommended that application developers create their logs here.)
* '''ASP_DBDIR''' - Location where persistent files (if any) by the application should be created.
* '''ASP_CONFIG''' - Place where all the configuration data used by the SAFplus Platform is stored.
* '''ASP_BINDIR''' - Location of all the binaries (SAFplus Platform as well as user applications).

[[File:OpenClovis_Note.png]]When deploying SAFplus Platform images on a particular node, if there is a 'extras' directory present in the model directory, then the directory structure underneath it will be overlaid on top of the sandbox directory, without overwriting the files in the sandbox directory, in case of file name clash. For e.g. if model name is test, and if there is a file called test/extras/bin/test_bin, then if the deployed image is extracted to directory called `asp', then asp/bin/ will contain test_bin file (provided there already isn't test_bin file in bin/ directory). This can be helpful to package custom scripts, binaries etc when deploying an SAFplus Platform image.

Doc:latest/sdkguide/deploy

2010-08-27T03:57:19Z

Senthilk:

==Deployment==

This chapter covers various topics related to deploying SAFplus Platform and the SAFplus-based applications onto a given target hardware (cluster).

===Deploying and Running OpenClovis SAFplus Platform on a Target System===

In order to deploy an OpenClovis SAFplus-based model on to a run-time target system, we need to specify the model's target system configuration, and create the run-time images that will be deployed on the target system. The target system is configured using the <code>target.conf</code> configuration file and the run-time images are created using the <code>make images</code> command. This step creates run-time images for all types of nodes covered by the model (system controller nodes and worker nodes).

[[File:OpenClovis_Note.png]] Image generation can also be accomplished in IDE. For more information, see ''OpenClovis IDE User Guide''.

====Target System Configuration - target.conf====

A model's target system configuration is specified using a configuration file - <code>target.conf</code>. It is located at <code><project_area>/<model>/src/target.conf</code>. Open this file using your favorite editor (e.g. <code>vi</code>):
<code><pre>
$ vi <project_area>/<model>/src/target.conf
</pre></code>

This file specifies a number of parameters that need to be defined for a given run-time target:
<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have and SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager e.g.:
<code><pre>
CMM_IP=10.10.4.1
</pre></code>
<li>'''CMM_USERNAME''', '''CMM_PASSWORD''' and '''CMM_AUTH_TYPE''' (Mandatory if deployed on an ATCA chassis): Specifies the username, password, and authentication type required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
CMM_AUTH_TYPE=md5
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of OpenClovis SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1337
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located at. When deployed to an ATCA chassis, this corresponds to the physical slot the blade is situated at. When deployed to regular (non-ATCA) systems, this is a logical slot, and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth0
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth0

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
<li>'''AUTO_ASSIGN_NODEADDR=default|physical-slot''' (Optional): Specifies the scheme that determines how Node Addresses are assigned at run time. If <code>physical-slot</code> is specified, the SAFplus Platform startup script will attempt to determine it's own slot number and utilize that instead of the SLOT_ number specified above if it is able. If <code>default</code> is specified, or the value is unspecified, it will function in the default manner of using the SLOT_ number defined above.
</ol>

====Generating Run-time Images====

In order to generate the run-time images based on the target system configuration specified in <code>target.conf</code>, run the following command at the <code><project_area>/<model></code> directory:
<code><pre>
$ make images
</pre></code>

If <code>target.conf</code> has been configured to instantiate images and create tarballs as recommended, these are populated at <project_area>/target/<model>/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For a model containing three nodes: <code>SCNodeI0</code>, <code>PayloadNodeI0</code> and <code>PayloadNodeI1</code>, the following are the files and directories generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+var
|-SCNodeI0.tgz
|+PayloadNodeI0
|-PayloadNodeI0.tgz
|+PayloadNodeI1
|-PayloadNodeI1.tgz
</pre></code>

====Copying Images to Run-time System====

The node-specific images are deployed to the nodes in the run-time system at <code>/root/asp</code>. They can be deployed to the target nodes in a variety of ways, for example:
<ol>
<li>Using '''rsync''': This option requires an ssh server running on each target node. In order to use this option, run the following commands on each target node:
<code><pre>
# cd /root
# mkdir asp
</pre></code>
On the development host, switch to the target image directory using the following command:
<code><pre>
$ cd <project_area>/target/<model>/images
</pre></code>
Then, for each node instance <node_instance>, run the following command to copy the image to its corresponding target node at <node_ip>:
<code><pre>
$ rsync -avH <node_instance>/* root@<node_ip>:asp/.
</pre></code>
<li>Using the generated node-specific tarballs:
Copy the node-specific tarballs from the development host to the target nodes using ftp, scp, or any method that is available. e.g. To copy the tarballs using <code>scp</code>, switch to the target image directory on the development host using the following command:
<code><pre>
$ cd <project_area>/target/<model>/images
</pre></code>
Then, for each node instance <node_instance>, run the following command to copy the image to its corresponding target node at <node_ip>:
<code><pre>
$ scp <node_instance>.tgz root@<node_ip>:.
</pre></code>
On each target node, run the following commands to finish deploying the image:
<code><pre>
# mkdir /root/asp
# cd /root/asp
# tar xzfm ../<node_instance>.tgz
</pre></code>
</ol>

====Running OpenClovis SAFplus Platform on the Deployed Run-time System====

To start OpenClovis SAFplus Platform on the run-time system, run the following commands as root on each target node:
<code><pre>
# cd /root/asp
# etc/init.d/asp start
</pre></code>

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run properly with an enabled firewall. See the ''Environment Related Observation'' section of the ''OpenClovis Release Notes'' for more information.

[[File:OpenClovis_Note.png]] By default SCNodeI0, PayloadNodeI0 and PayloadNodeI1 are configured (see target.conf) to use the eth0 ethernet interface. Within each of the nodes this configuration information is stored within the following two files.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

This is not always the case, for example on one of your nodes you may want to switch to eth1. If you would like to do so without changing target.conf and rebuilding the images and redeploying then use your favourite editor, eg vi, to replace the occurrence of eth0 with the appropriate form, e.g. eth1 in these two files.

===Deployment of OpenClovis SAFplus Platform on Production Systems===

The deployment mechanism described above is well suited for development environments and will also work for production environments. However, sometimes different deployment behavior is desired in production environments. For example, in the above deployment the node's "personality" depends on what software (tar file) is loaded and run on the node. Another option is to have the node's "personality" depend on what slot the node is inserted into. For example, a project that is using physically different blades or deploying rack mount servers (i.e. there is no "slot") will likely want the personality to follow the loaded software. But a project that uses the exact same blade in and ATCA chassis may want the personality to follow the slot for simplicity in FRU replacement (i.e. a spare blade will automatically use the correct "personality" when inserted in the dead blade's slot). Alternately, a project that requires a specific pairing of blades due to custom hardware or upstream network redundancy will require that the personality follow the slot.

To change the "personality" of a blade edit the "etc/asp.conf" file on your node after the SAFplus Platform software has been deployed. This file defines several environment variables:

<ul>

<li>'''export NODENAME=\<your node name\>'''
 This variable controls the node personality. The NODENAME variable defines the node's personality as you specified in the AMF configuration dialog in the OpenClovis IDE.

<li>'''export SYSTEM_CONTROLLER=\<1 or 0\>'''
 This second variable defines whether this node is a system controller or not. Note that this variable cannot be changed to "toggle" system controller functionality -- whether or not the node is a system controller is defined by the node's personality in the OpenClovis IDE and this variable must be set correctly. It exists due to the internal design of the SAFplus Platform platform; essentially the SAFplus Platform must act as a system controller (or not) before it gains enough information to know whether a particular NODENAME is supposed to be a system controller.
 Therefore to toggle system controller behavior, you must change both NODENAME and the SYSTEM_CONTROLLER variables.

<li>'''export DEFAULT_NODEADDR=\<a positive integer\>'''
 This variable is only used in rack-mount systems or systems where OpenClovis SAFplus Platform cannot determine the slot number. Every node in the cluster must be given a unique node address. In "slot-based" systems, the slot number will be used as the node address, but in systems where OpenClovis SAFplus Platform cannot determine the slot number then this default will be used.
 As an aside, note that to integrate OpenClovis SAFplus's slot numbering with a custom chassis all that must be done is to set this variable to the actual slot number.

</ul>

====Deployment on Machines that Lack Storage====

The mechanics of deployment on diskless machines (i.e using PXE or tftp to get a linux kernel from another node on the network) is node and operating system specific and is beyond the scope of the OpenClovis SDK. However, commonly these methods require that a single image be booted on all nodes. Therefore, the default OpenClovis deployment where the node "personality" is determined by the software image is not appropriate. Instead, deployment on diskless machines can be accomplished using the same strategy used for deployment where the personality is determined by the slot, as described in the prior section.

Note that although this strategy was presented using the slot number as the deterministic value it is not limited in this way. Any accessible data can be used to set the NODENAME, SYSTEM_CONTROLLER, and DEFAULT_NODEADDR variables. Implementation is left to the customer but some options include a byte in the node's non-volatile (CMOS or flash) memory, the node's MAC address, a file in a mounted NFS volume, or a boot-time parameter.

===Setting Up SAFplus Platform On A Multi-Subnet System===

Clustered environments often assume that all nodes in the cluster are connected via the same Layer-2 subnet, such as an Ethernet subnet, or often a redundant pair of such subnets.
Indeed, OpenClovis SAFplus Platform has been designed to exploit the benefits of the single-subnet setup to achieve optimal communication and failover performance.

However, in certain systems the cluster must span across multiple layer-2 subnets that are connected directly or indirectly over layer-3 (IP) routers. Albeit somewhat more involved, SAFplus Platform can be setup for these networks, as it is explained and demonstrated in this section.

====Requirements on the Subnet Connectivity====

SAFplus Platform uses three types of communications among its nodes, all of which must be working in order to provide its functionality:
* IP (UDP) unicast forwarding, used by the Group Membership Service (GMS) protocol
* IP (UDP) multicast forwarding, used also by GMS
* Layer 2 forwarding, used by TIPC for the rest of the inter-node communication

Hence, in order to provide all 3 types of connectivity between the subnets, the router(s) or switch(es) that connect the subnets must provide the following capabilities. These capabilitits are rather common in modern routers and switches, and are also provided by standard Linux-based systems:
* IPv4 unicast forwarding (routing)
* IPv4 multicast forwarding (multicast routing)
* Ethernet bridging for selected Ethernet frames, based on Ethernet protocol type field

====Example Setup Using a Linux-based Router====

Setting up a router to perform the above services is vendor and model specific. Therefore we illustrate the setup for the case when a common Linux-based PC is used as a router between the subnets. This configuration can be directly transposed to other commercial router products that have the above 3 capabilities.

We assume that the Linux PC has two Ethernet NICs. The steps involves setting up IP forwarding to allow normal traffic to be routed across the subnets, creating an Ethernet bridge to allow TIPC traffic to be bridged across the subnets (i.e. see both subnets as one), and setting up multicast routing across the subnets to allow SAFplus Platform GMS traffic across the subnets (i.e., again, to see both subnets as one).

In our example we assume that the two subnets are:
*<code>10.10.0.0/16</code> (gateway <code>10.10.0.1</code>)
*<code>10.20.0.0/16</code> (gateway <code>10.20.0.1</code>)
and our Linux router will have the following two interfaces:
*<code>eth0: 10.10.0.99</code>
*<code>eth1: 10.20.0.1</code> (gateway for <code>10.20.0.0/16</code> subnet)

=====IP Unicast Forwarding=====

<ol>
<li>Ensure that IP Forwarding is enabled by setting the following in <code>/etc/sysctl.conf</code>:
<code><pre>
net.ipv4.ip_forward = 1
</pre></code>
<li>Run the following to reload <code>/etc/sysctl.conf</code>:
<code><pre>
# sysctl -p
</pre></code>
</ol>

With the two interfaces configured, ensure that the default route points to <code>10.10.0.1</code> on <code>eth0</code>:
# route del default
# route add default gw 10.10.0.1 dev eth0

Note: Ensure that the gateway for the <code>10.10.0.0/16</code> subnet (in our case <code>10.10.0.1</code>) has a route in place for the <code>10.20.0.0</code> subnet using the following command:
# route add -net 10.20.0.0 netmask 255.255.0.0 gw 10.10.0.99

=====Ethernet Bridging for TIPC traffic=====

You will need the <code>ebtables</code> and <code>bridge-utils</code> packages installed, as well as support for Ethernet bridging (802.1d) and ebtables enabled in the kernel.

<ol>
<li>Create a new Ethernet bridge using the following:
<code><pre>
# brctl addbr br0
</pre></code>
<li>Add <code>eth0</code> and <code>eth1</code> to the bridge:
<code><pre>
# brctl addif br0 eth0
# brctl addif br0 eth1
</pre></code>
<li>Bring the bridge interface <code>br0</code> up:
<code><pre>
# ifconfig br0 0.0.0.0 up
</pre></code>
<li>Next, set the default bridge "brouting" policy to <code>DROP</code> to ensure that all traffic is routed at Layer-3 via iptables as normal:
<code><pre>
# ebtables -t broute -P BROUTING DROP
</pre></code>
<li>Finally, allow TIPC traffic (protocol <code>0x88ca</code>) to be bridged across the subnets, bypassing Layer-3 routing:
<code><pre>
# ebtables -t broute -A BROUTING -p 0x88ca -j ACCEPT
</pre></code>
</ol>
<code>0x88ca</code> is the Ethernet protocol type value for TIPC Ethernet frames.

=====Multicast Routing Using mrouted for SAFplus Platform GMS Traffic=====

You will need the <code>mrouted</code> package installed and support for multicast routing enabled in your kernel. Do not proceed before these are installed and your kernel is multicast-enabled.

<ol>
<li>Add the following entries to <code>/etc/mrouted.conf</code>:
<code><pre>
phyint eth0 rate_limit 0 igmpv1
phyint eth1 rate_limit 0 igmpv1
</pre></code>
<li>Add the default multicast route to the routing table with the following command:
<code><pre>
# route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
</pre></code>
<li>Start <code>mrouted</code> using the following command:
<code><pre>
# mrouted -c /etc/mrouted.conf
</pre></code>
or using the appropriate service startup script, e.g.:
<code><pre>
# /etc/init.d/mrouted start
</pre></code>
for Red Hat, Gentoo, Ubuntu and other distributions
</ol>

For more information, please see the [http://www.jukie.net/~bart/multicast/Linux-Mrouted-MiniHOWTO.html Linux-Mrouted-MiniHOWTO].

=====Patching SAFplus Platform to Allow GMS Multicast Packets to Traverse the Router=====

In the current version of SAFplus Platform, when the multicast port is opened by GMS, the default TTL value 1 (Linux default) is unchanged. Consequently, the router will drop the GMS multicast packets.
To allow multicast routing, the GMS code must be modified to override the default TTL value. When the two subnets are connected directly via a router, the TTL=2 value is sufficient. (In case the connectivity involves tunnels and/or multiple routers, a larger TTL value may be needed, depending on the number of hops. In order to prevent multicast traffic "leaking" into neighboring subnets, never use a TTL value larger than what you really need.)

Hence, the following patch needs to be applied to the code. In the next release of SAFplus Platform, the TTL value will be configurable from the GMS configuration file, so this patch is a temporary fix.

<code><pre>
Index: 3rdparty/openais/openais-0.80.3/exec/totemnet.c
===================================================================
--- 3rdparty/openais/openais-0.80.3/exec/totemnet.c (revision 1710)
+++ 3rdparty/openais/openais-0.80.3/exec/totemnet.c (working copy)
@@ -885,6 +885,7 @@
int addrlen;
int res;
int flag;
+ unsigned char ttl;

/*
* Create multicast recv socket
@@ -1066,16 +1067,23 @@
* Set multicast packets TTL
*/

- if ( bindnet_address->family == AF_INET6 )
- {
+ switch ( bindnet_address->family ) {
+ case AF_INET:
+ ttl = 2;
+ if (setsockopt (sockets->mcast_send, IPPROTO_IP,
+ IP_MULTICAST_TTL, &ttl, sizeof(ttl)) < 0) {
+ perror ("cannot set mcast ttl");
+ return (-1);
+ }
+ break;
+ case AF_INET6:
flag = 255;
- res = setsockopt (sockets->mcast_send, IPPROTO_IPV6,
- IPV6_MULTICAST_HOPS, &flag, sizeof (flag));
- if (res == -1) {
- perror ("setp mcast hops");
+ if (setsockopt (sockets->mcast_send, IPPROTO_IPV6,
+ IPV6_MULTICAST_HOPS, &flag, sizeof (flag)) < 0) {
+ perror ("cannot set mcast ttl");
return (-1);
}
- }
+ break;
+ }

/*
* Bind to a specific interface for multicast send and receive
</pre></code>

Please copy the above patch into a file, e.g., <code>gms_ttl2.patch</code>, and apply it to the SAFplus Platform source tree as follows:
<code><pre>
# cd <clovis-sdk-dir>/sdk-3.0/src/SAFplus Platform
# patch -p0 < gms_ttl2.patch
</pre></code>
and rebuild SAFplus Platform.

=====GMS Multicast IP Address Selection=====

In order to allow GMS multicast packets traverse the router, don't forget to pick a routable multicast address. Addresses between 224.0.0.0 through 224.0.0.255 are not routable, but 224.0.1.0 or above are routable. This address can be specified in various ways, including:
* by using the IDE
* by modifying the target.conf file manually before packaging for deployment
* by modifying the clGmsConfig.xml file on the target nodes after deployment

=====Bringing Up SAFplus Platform on the Multi-Subnet Cluster=====

At this point SAFplus Platform can be started on nodes connected to either of the two subnets, they will be able to join the SAFplus Platform cluster irrespective of their location. Starting, stopping, and using SAFplus Platform is identical to the single subnet case.

Doc:latest/sdkguide/build

2010-08-27T03:54:58Z

Senthilk:

==Building SAFplus Platform and SAFplus-based Systems==

This chapter covers new features that are related to building SAFplus Platform and SAFplus-based systems. Key new features include:

#SAFplus Platform and model tree separation
#Pre-built SAFplus Platform library support
#Multi-target build support
#Integration with WindRiver Workbench SDK

Note: In the context of this chapter, a target platform is any blade type or architecture that OpenClovis SAFplus Platform can be built for (e.g. WindRiver PNE-LE 1.4 on dual Xeon-based Intel MPCBL0001 blades, or Yellow Dog Linux on PowerPC based blades). OpenClovis provides a variety of cross build toolchains that can optionally be used with the SDK to build SAFplus Platform for these targets.

Working with the OpenClovis SDK involves the following steps:

#Installing the SDK, which is covered in ''OpenClovis Installation Guide''
#Optionally preparing the SDK for use with the WindRiver Workbench development tools
#Optionally pre-building SAFplus Platform libraries for a given target platform.
#Creating a project area (optionally populated with one or more existing SAFplus Platform models)
#Using the OpenClovis IDE to create a new SAFplus Platform model, generate its code, and modify this code to create desired functionality. This part is covered in ''OpenClovis IDE User Guide''
#Configuring and building the desired model for one or more target platform

===Using OpenClovis SDK with the WindRiver Workbench===

It is possible to use OpenClovis SDK with the WindRiver Workbench development tools. This section describes an optional step that creates a 'virtual' toolchain that allows SAFplus Platform to be built using the WindRiver Workbench development tools for a given WindRiver board support package. This also builds the 3rd party prerequisites using the Workbench tools so that they may be deployed on the specific platform. It requires both WindRiver Workbench (for the development tools) as well as a WindRiver board support package for a specific target platform. Platform specific HPI libraries from Pigeon Point Systems and RadiSys can optionally be built into the virtual toolchains using packages supplied by either vendor. It is possible to create as many virtual toolchains as necessary for a variety of platforms.

This is done by using the cl-create-wrs-toolchain utility (as root, if OpenClovis SDK was installed as root, or as a normal user if not):

# cl-create-wrs-toolchain -w <WindRiver Workbench install dir> \
-b <bsp name> \
[ -l <libhcl_tarball> ] \
[ -p <pps_openhpi_tarball> ] \
<toolchain_name>

The <code>-l</code> option accepts the full path to a RadiSys-provided libhcl package tarball. If specified, it will be built in to the virtual toolchain.
The <code>-p</code> option accepts the full path to a Pigeon Point Systems-provided OpenHPI package tarball. If specified, it will be built into the virtual toolchain instead of the stock OpenHPI package from the OpenClovis-provided 3rd party package tarball.

e.g.:

# cl-create-wrs-toolchain -w /opt/WindRiver \
-b intel_mpcbl0001 wrs_mpcbl0001

This will create a toolchain called <code>wrs_mpcbl0001</code> in your existing SDK buildtools directory that is built using the WindRiver installation at <code>/opt/WindRiver</code> for the <code>intel_mpcbl0001</code> board support package. This toolchain will be visible when using <code>configure --help</code>, as will be noted in a following section.

Note: The virtual toolchain requires the WindRiver Workbench installation to be available when it is used, as it merely provides references to the development tools in the Workbench installation. Should the installation be moved or replaced, the virtual toolchain would need to be built again.

===Pre-building SAFplus Platform Libraries for a Given Target Platform===

This is an optional step that pre-builds SAFplus Platform libraries for use with a given platform (i.e. using a specific toolchain). With these in place, it is no longer necessary to rebuild SAFplus Platform every time in order to build an SAFplus Platform model. (For the purpose of this document, we assume that the SDK is installed at <code>/opt/clovis</code>, by root. Consequently, example steps will be run as root. If the SDK is installed as a normal user at a location available to him, these steps can be run as the normal user itself.)

We first create a special project area for the SAFplus Platform library build, and change to it:

# mkdir asp_build
# cd asp_build

This project area is then initialized with the configure script as:

# /opt/clovis/sdk-3.0/src/SAFplus/configure --with-asp-build \
[--with-cross-build=<toolchain>] \
[--prefix=<alternate SAFplus Platform libs installation dir>]

By default, the libraries will ultimately be installed to the SDK installation directory, in this case: <code>/opt/clovis/sdk-3.0/target/<arch>/<kernel>/lib</code>, and header files will be available at <code>/opt/clovis/sdk-3.0/include</code>.

If --with-cross-build=<toolchain> is unspecified, libraries will be built for the local system.

If --prefix=<prefix> is specified, libraries will be installed to <code><prefix>/<arch>/<kernel>/lib</code>, and header files to <code><prefix>/include</code>

For example:

# /opt/clovis/sdk-3.0/src/SAFplus/configure --with-asp-build \
--with-cross-build=i586-wrl-pnele1.4-2.6.14_mpcbl0001

will cause libraries to be built from the i586-wrl-pnele1.4-2.6.14_mpcbl0001 toolchain and installed to <code>/opt/clovis/sdk-3.0/target/i386/linux-2.6.14/lib</code>, with header files populated at <code>/opt/clovis/sdk-3.0/include</code>, and

# /opt/clovis/sdk-3.0/src/SAFplus/configure --with-asp-build \
--prefix=/opt/asplib

on an Ubuntu 7.04 (feisty fawn) system will cause libraries to be installed to <code>/opt/asplib/i686/linux-2.6.20/lib</code>, and header files to be populated at <code>/opt/asplib/include</code>.

The following steps build and install the libraries as configured above:

# make asp-libs
# make asp-install

===Creating a Project Area===

A new project area with no model code is created by running the <code>cl-create-project-area</code> command:
<code><pre>
$ <install_dir>/sdk-3.0/bin/cl-create-project-area project_area
</pre></code>

This project area is ready for use with OpenClovis IDE to generate model code that will be built in a following step.

Existing models (from model-specific branches) can be copied over into a project area, and re-running <code>configure</code> using <code>--with-model-name</code> with any copied models will configure them for building.

A typical project area is laid out as:

project_area
+- ide_workspace
+- model_1
+- model_2
+- model_1
+- src/
+- target.conf
+- build/
+- target/
+- model_2
+- src/
+- target.conf
+- build/
+- target/

Note: The <code>configure</code> script does not copy models into the project area. The old behavior of copying models out from SAFplus/models is no longer required. The sample evaluation model that was at <code><install_dir>/sdk-3.0/src/SAFplus/models</code> has been moved to its own <code>examples</code> project area adjacent to the SAFplus Platform tree, at <code><install_dir>/sdk-3.0/src/examples</code>. To use it, one would change to the <code>examples</code> directory and issue a <code><path-to>/configure --with-model-name=eval</code>. Alternately, if the <code>examples</code> project area is in a non-user-writeable location (e.g. in the case of a root-installed SDK), it can be copied out to a user-writeable location and used there instead in the same manner.

===Configuring and Building the Model===

In this section, we will configure and build the <model> model in an existing project area.
<ol>
<li>Configure the <model> model for building by running the following:
<code><pre>
$ cd <project_area>
$ <install_dir>/sdk-3.0/src/SAFplus/configure --with-model-name=<model> \
--with-asp-build
</pre></code>

This will configure the <model> model for deployment on the local machine. In order to crossbuild this model for deployment on a non-native target supported by the <crossbuild> toolchain, run:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure --with-model-name=<model> \
--with-asp-build \
--with-cross-build=<crossbuild>
</pre></code>

It is possible to configure the model to be built for multiple targets by issuing as many <code>configure</code> commands as necessary. Each run sets up a target-specific build location at <code><project_area>/<model>/build</code>.

If this model is to be deployed on an ATCA-based system with OpenHPI-based shelf management, enable Chassis Manager with:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure --with-model-name=<model> \
--with-asp-build \
--with-cross-build=<crossbuild> \
--with-cm-build=openhpi
</pre></code>
[[File:OpenClovis_Note.png]] '''Using Chassis Manager requires OpenClovis Platform Support Package, distributed separately from OpenClovis SDK.'''

For a complete list of options to <code>configure</code>, including a list of available crossbuild toolchains, run:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure --help
</pre></code>

If the necessary crossbuild toolchain does not exist, then you must install it by downloading it adjacent to the OpenClovis SDK installer and re-running install.sh.

The configure step prepares the project area to build the <model> model, with the following directory structure:
<code><pre>
<project_area>
|ide_workspace
|+<model>
|+build
| |+local
| | |-Makefile
| |+<crossbuild>
| | |-Makefile
|+src
| |+app
| |+config
| |+doc
| |-target.conf
|+target
|-Makefile
</pre></code>

<li>Build the configured model by issuing <code>make</code> in <code><project_area>/<model></code>:
<code><pre>
$ make
</pre></code>

This will build the <model> model for all the targets it has been configured to build. In order to do a target-specific build, issue <code>make</code> from the target-specific build location. e.g. for a local build:
<code><pre>
$ cd <project_area>/<model>/build/local
$ make
</pre></code>
For a target supported by the <crossbuild> toolchain:
<code><pre>
$ cd <project_area>/<model>/build/<crossbuild>
$ make
</pre></code>

For a complete list of options to <code>make</code>, run:
<code><pre>
$ make help
</pre></code>

The model source is located at <code><project_area>/<model>/src</code>. If any changes are made to this, rebuild the model by issuing another <code>make</code> from either the target-specific build location or the model directory.
</ol>

[[File:OpenClovis_Note.png]] Model building can also be accomplished in IDE. For more information, see ''OpenClovis IDE User Guide''.

Doc:latestsdkguide/debugging

2010-08-27T03:53:41Z

Senthilk:

==Debugging EO Applications and SAFplus Platform Components==

The high availability features of the SAFplus Platform interfere with debugging applications because the act of debugging an application breaks the performance and availability "contract" between the SAFplus Platform and an application and therefore causes the SAFplus Platform to restart the application.

This HOWTO describes strategies that can be used to debug within an high availability environment. It is not a primer on gdb. In fact, it assumes an in-depth knowledge of debugging using gdb (or gdb derivatives such as Wind River's IDE) and therefore focuses exclusively on the interactions between the debugger and the SAFplus Platform.

It is useful to toggle the following debugging interventions on an as needed basis since many "defeat" the high availability features of the SAFplus Platform. Therefore the examples below use a global variable (defined in your component's clCompAppMain.c) called debuggingOn to control these features.

int debuggingOn = 1; /* Set to 0 to turn debugging off, 1 to turn it on */

These features will be generally available and integrated into the SAFplus Platform in the upcoming release.

=== Stopping Process Health Monitoring ===

It is extremely irritating to attach to your process via a debugger only to have the SAFplus's high availability features intervene and kill the process you are trying to debug! Certain techniques can be used to temporarily "defeat" this feature to allow debugging to occur. Of course, while the feature is "off" the high availability features will not work.

==== Turning off heartbeat ====

Turning off your component's heartbeat solves 95% of the problem. The SAFplus Platform expects your process to periodically state that it is "OK"; if it does not (for example, if stopped in a debugger) the SAFplus Platform will kill your process.

Replace the function in clCompAppMain.c (in every one of your components) with this function, and create a "debuggingOn" global variable. This will turn off the polling of your component and so the SAFplus Platform will not kill your component if it is being debugged. This will allow you to load up gdb and then "attach" to your component.

int debuggingOn = 1;

ClRcT clCompAppHealthCheck(ClEoSchedFeedBackT* schFeedback)
{
/*
Add code for application specific health check below. The defaults
indicate EO is healthy and polling interval is unaltered.
*/

ClRcT rc = CL_OK;

/* If you want to attach to gdb */
if (debuggingOn) schFeedback->freq = CL_EO_DONT_POLL;
else
{
schFeedback->freq = CL_EO_DEFAULT_POLL;
schFeedback->status = CL_CPM_EO_ALIVE;
rc = eoapp->HealthCheck();
}

return rc;
}

==== "ACK"ing Messages Early ====

The SAFplus Platform also monitors the response of certain crutial messages to your component. If your component does not respond in time, the SAFplus Platform kills your component. This feature ensures that your application does not have a bug in the handling of these messages; however when debugging the message handling we must "defeat" this feature. The most common messages are the CSI assignment messages, which trigger the "clCompAppAMFCSISet" (clCompAppMain.c) function call. When debugging your component, it is best to "ACK" the message right away so the SAFplus Platform will think that you have handled the message. However, it is important to NOT do so when not in debugging mode, to ensure that the HA features work.

In the routine below, note that the "clCpmResponse(cpmHandle, invocation, CL_OK);" function has been moved above the switch statement when debugging is on (and moved to below it, for succinctness, when debugging is off).

ClRcT clCompAppAMFCSISet(
ClInvocationT invocation,
const ClNameT *compName,
ClAmsHAStateT haState,
ClAmsCSIDescriptorT csiDescriptor)
{
/* If component hang detection is off, then reply with an OK first,
so that this call won't time out causing the controller to kill me. */
if (debuggingOn)
{
if (haState != CL_AMS_HA_STATE_QUIESCING)
clCpmResponse(cpmHandle, invocation, CL_OK);
}

/* DO NOT SET BREAKPOINTS ABOVE THIS LINE (IN THIS FUNCTION)

(the controller will think that your process is dead)

To set a breakpoint in this routine:

1. First set "debuggingOn" to 1
2. Set your breakpoint below this comment
3. Continue
*/

/* Print information about the CSI Set */
clprintf ("Component [%s] : PID [%d]. CSI Set Received\n",
compName->value, mypid);
clCompAppAMFPrintCSI(csiDescriptor, haState);

/* Take appropriate action based on state */
switch ( haState )
{
case CL_AMS_HA_STATE_ACTIVE:
{
/*
AMF has requested application to take the active HA state
for the CSI.
*/
break;
}
case CL_AMS_HA_STATE_STANDBY:
{
/*
AMF has requested application to take the standby HA state
for this CSI.
*/
break;
}
case CL_AMS_HA_STATE_QUIESCED:
{
/*
AMF has requested application to quiesce the CSI currently
assigned the active or quiescing HA state. The application
must stop work associated with the CSI immediately.
*/
break;
}
case CL_AMS_HA_STATE_QUIESCING:
{
/*
AMF has requested application to quiesce the CSI currently
assigned the active HA state. The application must stop work
associated with the CSI gracefully and not accept any new
workloads while the work is being terminated.
*/
clCpmCSIQuiescingComplete(cpmHandle, invocation, CL_OK);
break;
}
default:
{
/*
Should never happen. Ignore.
*/
}
}

/* If I'm am killing components, then reply with an OK after
execution, to ensure that the handling did not hang */
if (!debuggingOn)
{
if (haState != CL_AMS_HA_STATE_QUIESCING)
clCpmResponse(cpmHandle, invocation, CL_OK);
}
return CL_OK;
}

==== Component State Transition Timeouts ====

The SAFplus Platform also ensures that your component transitions through various states within reasonable a time. To debug during these transitions (startup, shutdown, etc) it is necessary to increase these timeouts.

The code that must be changed is in function cpmCompConfigure() in SAFplus/components/amf/server/cpm/clCpmComponent.c. In each timeout there is a "tsSec" variable that is set to zero since the configured value is specified in milliseconds. Instead of setting it to zero, set it to a global variable (in this case "clDbgComTimeoutOverride"). When debugging, set this variable to a large number so that the timeout essentially never fires.

Here is the changed code:
<code><pre>
/*
Create One shot timer component instantiation, with a timeout value
equal to comp->compConfig->compInstantiateTimeout
*/
cpmTimeOut.tsSec = clDbgCompTimeoutOverride; /* default is zero, */
/* this override help debug apps, since the app won't be killed
if you set the # high. */
cpmTimeOut.tsMilliSec = tmpComp->compConfig->compInstantiateTimeout;
rc = clTimerCreate(cpmTimeOut, CL_TIMER_ONE_SHOT, CL_TIMER_SEPARATE_CONTEXT,
cpmTimerCallback, (void *) tmpComp,
&(tmpComp->cpmInstantiateTimerHandle));
/*
Create One shot timer for component termination, with a timeout value
equal to comp->compConfig->compTerminateCallbackTimeOut
*/
cpmTimeOut.tsSec = clDbgCompTimeoutOverride; /* default is zero, */
/* this override help debug apps, since the app won't be killed
if you set the # high. */
cpmTimeOut.tsMilliSec = tmpComp->compConfig->compTerminateCallbackTimeOut;
rc = clTimerCreate(cpmTimeOut, CL_TIMER_ONE_SHOT, CL_TIMER_SEPARATE_CONTEXT,
cpmTimerCallback, (void *) tmpComp,
&(tmpComp->cpmTerminateTimerHandle));
/*
FIXME: following two need should be created only if this component is
proxy for a component
*/
/*
Create One shot timer proxied component Instantiate, with a timeout
value equal to comp->compConfig->compInstantiateTimeout
*/
cpmTimeOut.tsSec = clDbgCompTimeoutOverride; /* default is zero, */
/* this override help debug apps, since the app won't be killed
if you set the # high. */
cpmTimeOut.tsMilliSec =
tmpComp->compConfig->compProxiedCompInstantiateCallbackTimeout;
rc = clTimerCreate(cpmTimeOut, CL_TIMER_ONE_SHOT, CL_TIMER_SEPARATE_CONTEXT,
cpmTimerCallback, (void *) tmpComp,
&(tmpComp->cpmProxiedInstTimerHandle));
/*
Create One shot timer for proxied component cleanup, with a timeout
value equal to comp->compConfig->compInstantiateTimeout
*/
cpmTimeOut.tsSec = clDbgCompTimeoutOverride; /* default is zero, */
/* this override help debug apps, since the app won't be killed
if you set the # high. */
cpmTimeOut.tsMilliSec =
tmpComp->compConfig->compProxiedCompCleanupCallbackTimeout;
rc = clTimerCreate(cpmTimeOut, CL_TIMER_ONE_SHOT, CL_TIMER_SEPARATE_CONTEXT,
cpmTimerCallback, (void *) tmpComp,
&(tmpComp->cpmProxiedCleanupTimerHandle));
</pre></code>

=== Creating core files on failure ===

To create core files, you need to change the core file size limit. Do this by adding "ulimit -c unlimited" to the "asp/etc/init.d/sisp" script just before the sisp_amf program is run in the "start()" function. The following code shows the change:

cd $SISP_DIR/bin
ulimit -c unlimited
env $SISP_ENV ./$prog $SISP_OPTIONS > ${SISP_OUTPUT} 2>&1 &
RETVAL=$?

Core files will be created in the "bin" (/root/asp/bin) directory. You can test core creation by jamming a SEGFAULT into a program by doing "kill -SEGV <process id>".

'''Note that when you redeploy (i.e. detar your image tarball onto the target machine) this file is overwritten!''' I just keep a copy in my home directory and copy it back after deployment.

=== Pausing and Resuming a Thread ===

Sometimes a problem occurs during startup -- before you have the opportunity to attach to a process, set a breakpoint, and resume the process. In a standard application this is easy to debug because "gdb" starts up with your program "stopped". But in a high availability framework, where the SAFplus Platform starts and stops programs, this is trickier.

To debug this, I added 2 functions, one which "pauses" the calling thread, the other "resumes" it. The programmer adds the "pause" function to the code and recompiles. When "debuggingOn" is true and the function is called, the thread will output a log and block on a semaphore. The programmer can then check the logs to see if a thread was paused. If so, he goes into gdb, attaches to the process, finds the thread that is paused -- "thread apply all backtrace" ("thr a a bt") and look for a call to "pause" -- switches to that thread ("thread x"), and then "resumes" the thread by calling the "resume" function from gdb's prompt:

gdb> call clDbgResume()

The "pause" function is actually a macro so that I can also pass the file and line from which the function was called. This information is very useful if you accidently forget to remove a call to clDbgPause!

#define clDbgPause() clDbgPauseFn(__FILE__,__LINE__)

sem_t clDbgSem;
int clDbgSemInited = 0;

/* Call this from the code to pause your program. */
void clDbgPauseFn(char* file, int line)
{
if (debuggingOn != 0)
{
if (!clDbgSemInited)
{
int rc;
clDbgSemInited = 1;
rc = sem_init(&clDbgSem,0,0);
if (rc == 0)
{
CL_DEBUG_PRINT(CL_DEBUG_CRITICAL,
("dbgPause function called from %s:%d. Thread is paused."
"Open the debugger and execute dbgResume() to continue.",
file,line));
do {
rc = sem_wait(&clDbgSem);
} while ((rc == -1)&&(errno == EINTR));
}
else
{
int err = errno;
CL_DEBUG_PRINT(CL_DEBUG_CRITICAL,
("Can't create debug semaphore, error: %s, errno %d.",
strerror(err), err));
}
}
}
}

/* Call this from gdb to continue your program. */
void clDbgResume()
{
sem_post(&clDbgSem);
}

=== Intercepting the Automatic Start of a Component ===

It is possible to run your component within a wrapper application (such as gdb or purify). When the SAFplus Platform is deployed on a target, all applications are placed in the "bin" subdirectory of the SAFplus Platform tree (for example "/root/asp/bin"). To intercept the application start for debugging purposes:
# rename your application
# create a script and name it the same as the original application name
# edit the script to add your wrapper.
## Note that you will have to start a separate window for applications that need a console (like gdb)

For example the following simple script can be used to make your application start within gdb (note though that it must be used in conjunction with the techniques described in the "Stopping Process Health Monitoring" section above unless you are a very fast typist, since your application's initialization will be monitored by the OpenClovis HA infrastructure to ensure that it succeeds). This script assumes that your application is called "myapp" and that you moved it to "/root/asp/bin/myapp.orig". It also assumes that your Linux installation has X-windows and the gnome desktop environment installed:

<code><pre>
#!/bin/bash
/usr/bin/gnome-terminal --window --command \
"gdb /root/asp/bin/myapp.orig $1 $2 $3 $4 $5 $6 $7 $8 $9"
</pre></code>

Doc:latest/sdkguide/compdev

2010-08-27T03:52:55Z

Senthilk:

==Developing Application Components in OpenClovis SAFplus Platform Environment==

===Eonization===

'''Eonization''' is a mechanism that enables the user application to communicate with OpenClovis SAFplus Platform. The name eonization derives from the word 'EO' or execution object. The end product of eonization is an EO that is able to communicate with other EOs in the SAFplus Platform environment.

Eonization enables an application to :
# Invoke services exposed by the other EOs.
# Expose services so that other EOs can invoke the same.
# Provide some callbacks so that its lifecycle can be monitored by the SAFplus Platform.
# Use the manageability features provided by the SAFplus Platform.
# Integrate it with the AMF so that the application becomes highly available.

====Significance of Eonization====

The two most common software entities which are provided and managed (rather primitively) by many operating systems are '''processes''' and the '''threads'''. In most systems, processes are isolated from each other, whereas threads share same address space and hence error/failure in one of the threads can lead to errors/failures in other threads 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 only mechanism for pro-actively sending information to the process is using signals.

But this model of OS to process communication is insufficient for middleware systems in carrier grade system, where the OS needs more fine grained control over the processes it creates and manages them over time. So we have two possible approaches in as far as the OS to process communication models are concerned in carrier grade system :
* Write an OS from scratch, which will periodically invoke specific set of callbacks in the context of processes that it creates, to manage the component. or
* Create a wrapper over a normal application and make the application register some callbacks when initializing, which is called by the SAFplus Platform middleware to manage the application. This approach requires some work from applications side like providing those callbacks and registering them etc.

The OpenClovis SAFplus Platform follows the second approach and this process of "wrapping the component and it registering the callbacks which will be invoked by the middleware" is called '''Eonization'''. So the life cycle of a typical application will be :
* Register the callbacks with the SAFplus Platform.
* The callbacks will be invoked asynchronously by the SAFplus Platform, to manage the application.

The above model is similar to the life cycle of an X window client application, which registers set of callbacks to be invoked whenever there is a key press event or button press event etc. and the X server asynchronously invoking the corresponding callback in the context of the X window client application.

It is important to realize that this eonization provided by the OpenClovis EO infrastructure is much more general than one required to support programming models such as SAF programming model. Not only does it support AMF managing the component through invoking callbacks for a particular component, it allows any component to invoke callbacks provided by any other component, thus allowing for a much more powerful and generic programming model.

===Steps involved in developing application components===

 [[File:OpenClovis_Note.png]]Using the OpenClovis IDE to build a model and generate the corresponding code automates the steps outlined in this section. For more information regarding the OpenClovis IDE see the ''OpenClovis Sample Application Tutorial'' and the ''OpenClovis IDE User Guide''.
* [[#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 worker 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, /* Client table ID*/
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, also called as the Execution Object (EO).

<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 maximum number of clients that can exist for a given component. The default value that can be used for this is <code>COMP_EO_USER_CLIENT_ID_START</code>.

<li><code>'''COMP_EO_USE_THREAD_MODEL'''</code> indicates whether the application should block the main thread or not.

<li><code>'''clCompAppInitialize'''</code> is invoked by the OpenClovis SAFplus Platform infrastructure when an eonized application is started. It is similar to the main() function of a typical C program. The application should do all its application specific initialization in this function. For SA-aware components, after the application has done its initialization, 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 an eonized application, if the heart beating is enabled. In response to this callback, the application is supposed to check if it is in a state of providing service and if so provide appropriate feedback to CPM saying so.
</ul>

{{internal-begin}}

[[File:SDK_UsageofApplicationType_70.png|frame|center| '''Illustration of the usage of application type''' ]]

{{internal-end}}

[[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 eonized. 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 termination functions with OpenClovis SAFplus Platform infrastructure.
* 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| '''A Typical Component in OpenClovis SAFplus Platform Environment''' ]]

Figure [[#A Typical Component in OpenClovis SAFplus Platform Environment | A Typical Component 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 [[#A Typical Component in OpenClovis SAFplus Platform Environment | A Typical Component in OpenClovis SAFplus Platform Environment]].
</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 [[#A Typical Component in OpenClovis SAFplus Platform Environment | A Typical Component in OpenClovis SAFplus Platform Environment]], 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)===

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 developing an application component===

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

Doc:latest/sdkguide/compconfig

2010-08-27T03:52:05Z

Senthilk:

==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:latest/sdkguide/lifecycle

2010-08-27T03:51:12Z

Senthilk:

=='''Development Lifecycle Topics'''==

This chapter covers some key aspects of using the OpenClovis SDK in the various phases in the system development lifecycle.

{{internal-begin}}

'''THIS CHAPTER IS WORK IN PROGRESS. THE FOLLOWING TOPICS WILL BE COVERED:'''

'''Key Topics:'''
* '''Installing the SDK'''
** link to Installation Guide
* '''Creating a new Project Area'''
** link to SDK User Guide (/build#Creating_a_Project_Area)
* '''Creating a new OpenClovis SAFplus Platform Project'''
** link to Sample App Tutorial (#Creating_the_Sample_Project) and IDE User Guide (#Creating_OpenClovis_IDE_Project)
* '''Defining the System Model using the OpenClovis IDE'''
** link to Sample App Tutorial and IDE User Guide
* '''Generating the source code skeleton and the run-time configuration files'''
** link to IDE User Guide (#Generating_Source_Code)
* '''Refining the System Model and re-generating the files'''
** link to IDE User Guide (#Generating_Source_Code)
* '''Working with the generated source code'''
** link to SDK User Guide (/compdev#Steps_involved_in_developing_application_components)
* '''Developing green-field applications based on SAFplus'''
** no document to link to
* '''Integrating legacy applications with the generated code skeleton'''
** no document to link to
* '''Adding diagnostics/debug hooks to access application internals from SAFplus Platform console'''
** link to SDK User Guide (/debugging)
* '''Configuring the project for build, including local build or cross-build'''
** link to IDE User Guide (#Building_the_Project) for UI based
** link to SDK User Guide (/build#Configuring_and_Building_the_Model) for command line
* '''Building the binary images'''
** link to IDE User Guide (#Building_the_Project) for UI based
** no document to link to for command line configuration
* '''Building the binary images for a heterogeneous target cluster'''
** no document to link to
* '''Cross-building binaries using OpenClovis-provided toolchains'''
** no document to link to
* '''Generating new toolchains for Wind River PNE LE based targets'''
** no document to link to
* '''Packaging and deploying the binary images to the target nodes'''
** link to IDE User Guide (#Making_Project_Images) for UI based
** link to SDK User Guide (/deploy#Deploying_and_Running_OpenClovis_ASP_on_a_Target_System) for command line
* '''Managing the life-cycle of SAFplus Platform on the target nodes'''
** no document to link to
* '''Setting up SAFplus Platform to be started and stopped automatically when the OS boots and shuts down on the target'''
** no document to link to
* '''Accessing SAFplus Platform status and vital information on the live targets'''
** no document to link to (is there a debug CLI or aspinfo user guide?)
* '''Managing the life-cycle of SAFplus-based components on the targets'''
** no document to link to
* '''Collecting and interpreting log files generated from SAFplus Platform on the target, online and offline'''
** link to Log Tool User Guide
* '''Connecting to the target from an SNMP browser to access managed object information'''
** no document to link to

'''AT THIS TIME NOT ALL THE ABOVE INFORMATION IS COVERED IN THIS DOCUMENT YET. WHAT IS COVERED BELOW MAY NOT BE ORGANIZED ACCORDING TO THE LAYOUT OUTLINED ABOVE.'''

{{internal-end}}

Doc:latest/sdkguide/platform

2010-08-27T03:49:56Z

Senthilk:

==Hardware Platform Support==

The features described in the previous chapters can provide complete service without any assumption on or any special integration with the underlying hardware.
For example, fault detection and service recovery works without direct tie between SAFplus Platform and the hardware.
This ensures that SAFplus Platform and SAFplus-based systems are portable across a wide range of hardware, from a cluster of desktop PCs, rack mount servers, to carrier grade, chassis based systems and virtual hosts.
However, additional communication between the software and the underlying hardware platform can further ''enhance'' some key characteristics of the system.

Modern hardware platforms provide a set of control and monitoring access for the software running on them.
Such platforms are often referred to as "managed hardware platforms."
Tapping into these interfaces can provide additional features or can strengthen the characteristics of existing features of a carrier grade middleware such as SAFplus Platform.

In order to exploit the advantages of managed hardware platforms OpenClovis provides additional Platform Support Packages (PSPs).
The PSP realizes a direct interface between SAFplus Platform and the underlying hardware platform, using an open, standards-based API, the Hardware Platform Interface (HPI) defined by the Service Availability Forum.
This solution preserves the hardware agnostic nature of SAFplus Platform.

The specific benefits of the PSP, and its realization are described in this chapter.

===Benefits of the Platform Support Package===

The PSP provides the following additional main benefits compared to running SAFplus Platform on an "unmanaged" hardware platform:
* Early detection of hardware anomalies and faults can be fed into the HA decision process
* Service impacting faults can trigger immediate service failover from the impacted hardware. Since these anomalies are often precursors of impending hardware failures, yet the hardware may be still operational, the handling of these events provides a chance to ''gracefully'' fail over the software service, thus minimizing service impact.
* Minor hardware events (no direct threat to service) can be routed to Fault Manager, which allows customized event handlers to deal with the problem
* Dependency relationships between various hardware components can be described using dependency tables
* SAFplus Platform is notified in case of hot-swapping or hot removal of blades, allowing the SAFplus Platform Availability Manager Framework (AMF) to fail over all services from the to-be-removed blade before the blade is powered off

In addition to the above main benefits, a few add-on tools, scripts are also included in the PSP:
* <code>bladeinfo</code> utility - this command line program provides an easy access to vital information about the host FRU. When executed on an IPMI-enabled FRU (as part of the OpenClovis SAFplus Platform installation), it can display the following information: IPMI address, logical slot, physical slot, slot type, board/product manufacturer, board/product name, product part number, board/product serial number. This information can be readily used in other scripts to make decisions based on such information. Examples of such use are:
** Physical slot based IP addresses
** Blade model based role selection
** Unique blade identifier based on serial number
* <code>lifesignal</code> utility (for AdvancedTCA blades only) - a small program that can control LED 2 on an AdvancedTCA blade to show vital status information about an SAFplus-based node running on the blade. Different color and timing patterns identify different states.

[[File:OpenClovis_Note.png]] Both <code>bladeinfo</code> and <code>lifesignal</code> require local IPMI driver on the node. In addition, bladeinfo requires IPMI over RMCP access to the shelf manager in order to determine the physical slot. This requires knowledge of the IP address of the shelf manager card and may also require username and password (depending on the shelf manager's configuration).

[[File:OpenClovis_Note.png]] PSPs are available only for commercially licensed version of the OpenClovis SDK, and are not available for a GPL-licensed SDK.

For all supported hardware platforms, OpenClovis conducts a series of integration tests to verify correct operation.
As there are slight variations in how chassis from different vendors work, sometimes small adjustments are needed in the software.
At the time of the release of OpenClovis SDK 3.0, a single Platform Support Package, called "OpenClovis Common PSP" contains all such adjustments.
For the list of hardware platforms supported by the Common PSP, please turn to the ''OpenClovis Release Notes''.

As OpenClovis integrates with additional platforms over time, additional changes/extensions may be packaged into separate, platform specific PSPs.

===How to Work With PSPs===

The following topics are covered here:
* [[#How to install PSP(s)|How to install PSP(s)]]
* [[#How to build SAFplus Platform to include platform management|How to build SAFplus Platform to include platform management]]
* [[#What to expect when running SAFplus Platform on the target|What to expect when running SAFplus Platform on the target]]

====How to install PSP(s)====

As noted above, PSPs are offered only for commercially licensed version of OpenClovis SDK.
PSPs are packaged separately and need to be installed separately on the development host.

The installation process is as follows:
<ol>
<li> (Prerequisite) Complete the OpenClovis SDK installation as directed in the ''OpenClovis Installation Guide''
<li> Fetch/download the OpenClovis Common PSP (file name is <code>openclovis-sdk-3.0*-psp-common*.tar.gz</code>) and optionally the MD5 signature file (<code>openclovis-sdk-3.0*-psp-common*.md5</code>) into an arbitrary directory
<li> File integrity can be verified by running <code>md5sum</code> on the .tar.gz file and comparing its output with the content of the .md5 file.
This step is optional. Example:
<code><pre>
md5sum -c openclovis-sdk-3.0-psp-common.md5
</pre></code>
This should report OK.
<li> Untar the .tar.gz file by running (example):
<code><pre>
tar xmf openclovis-sdk-3.0-psp-common.tar.gz
</pre></code>
This will create a subdirectory called <code>openclovis-sdk-3.0-psp-common</code>.
<li> Enter the newly created subdirectory and initiate installation. '''If you installed the OpenClovis SDK as <code>root</code>, you will need to install the PSP also as <code>root</code>.'''
<code><pre>
cd openclovis-sdk-3.0-psp-common
./install
</pre></code>
<li> Follow the install script directions to complete the installation. The install script will prompt for the SDK installation root directory. By default this will be the place where you last installed SAFplus Platform using the same user account that you are using now. Therefore, in most cases the default can be accepted. Otherwise, please specify the proper location.
If all went well, the install script will report <code>installation completed</code>.
</ol>

=====Additional steps=====

For SAFplus Platform to communicate with the hardware, it needs to be built with using the proper HPI client library for the given hardware platform. The Common PSP supports the following HPI client libraries:
* Radisys <code>libhcl</code> (version 1.1 or 1.4.4) used for Radisys Promentum-6000 and 6010 AdvancedTCA chassis
* OpenHPI daemon and client libraries (version 2.8.0 and above) used for chassis that utilize the Pigeon Point Systems (PPS) Shmm 500 shelf manager module (Sentry). The OpenClovis Common PSP has been tested with both the open source version as well as the PPS-provided commercial version of OpenHPI.

If you intend to use the open-source version of OpenHPI, no additional special installation steps are necessary as it is installed by default during the SDK installation.

If you intend to use Pigeon Point System's OpenHPI package, please follow these steps:
# Consult with your Pigeon Point Systems representative or your chassis vendor to obtain the source package of Pigeon Point OpenHPI
# If your target OS is Wind River PNE LE 1.4, please follow the instructions in the SDK Guide, Section "Building SAFplus Platform and SAFplus Platform Based Systems", Sub-section "Using OpenClovis SDK with Wind River Workbench" to generate a cross-build toolchain which integrates the Pigeon Point OpenHPI.
# For any other target OS, please contact an OpenClovis field engineer for further support.

If you intend to use the Radisys libhcl client, please follow these steps:
# Make sure you have the <code>libhcl</code> software package (named as <code>libhcl-1.4.4.tar.gz</code> or similar). If you do not have it, consult with your Radisys representative to obtain the package.
# If your target OS is Wind River PNE LE 1.4, please follow the instructions in the SDK User Guide, Section "Building SAFplus Platform and SAFplus Platform Based Systems", Sub-section "Using OpenClovis SDK with Wind River Workbench" to generate a cross-build toolchain which integrates the <code>libhcl</code> library.
# For any other target OS, please contact an OpenClovis field engineer for further support.

==== How to build SAFplus Platform to include platform management====

The PSP installation by itself does not make subsequent builds to include platform support. When configuring SAFplus Platform, you need to '''explicitly''' request the build to include platform support.
Once your project is configured to use platform management, all subsequent builds will create and package the additional binaries.

Configuring SAFplus Platform to use platform management can be done either from the IDE or from the command line:
# From the IDE, use the '''Project > Build Project''' menu to bring up the '''Build Configuration''' dialog, enable "Include Chassis Manager for HPI Access" option and select the proper HPI client library type. Click OK. All subsequent builds will contain platform support. For further details, check the ''OpenClovis IDE User Guide'', Section "Building the Project."
# Alternatively, the same can be achieved from the command line. Go to the top level directory of your project area, and re-issue the <code>configure</code> step, this time with using the <code>--with-cm-build[=mode]</code> option, where <code>mode</code> is either <code>openhpi</code> or <code>libhcl</code>. If the mode is omitted, it defaults to openhpi. For more information, check Section [[Doc:sdkguide/build#Building SAFplus Platform and SAFplus-based Systems|Building SAFplus Platform and SAFplus-based Systems]].

Next, during the packaging step you need to specify a few additional information, such as IP address of the shelf manager and (for Pigeon Point based hardware platforms) the user credentials to access the shelf manager.
This can be done either from the IDE or from the command line:
# For the IDE based process, check the "Making Project Images" in the ''OpenClovis IDE User Guide''. Please note that for Radisys chassis using the libhcl client library only the shelf manager's IP address needs to be provided, the remaining three fields (Module IP, Username, and Password) should be left blank. For platforms using the openhpi libraries all four fields need to be provided. The last three fields must correspond to a valid user account defined on the shelf manager. The user account must have Administrator privileges. Note: do not use the "openhpi" user account, as that disables the default hot-swap operation of the shelf manager. Once the IDE dialog is properly completed, the IDE will generate/update the <code>target.conf</code> configuration file under the model's <code>src</code> subdirectory and will complete the packaging with the correct information.
# Alternatively, the same result can be achieved by editing the corresponding four fields in the <code>target.conf</code> configuration file mentioned above with a text editor. Once the values are specified in target.conf, any subsequent <code>make images</code> operation will correctly embed this information to the run-time images.

For those who are interested in the details, the <code>make images</code> step uses the platform management settings from the <code>target.conf</code> file in two ways:
* For openhpi based systems, it generates the proper <code>openhpi.conf</code> file as part of the target image
* For libhcl based systems, it properly defines the <code>SAHPI_UNSPECIFIED_DOMAIN_ID</code> environment variable which is used to convey the IP address of the shelf manager to the libhcl client library.

====What to expect when running SAFplus Platform on the target====

The active presence of the Platform Support Package will result in the following new behavior (compared to a system with no PSP):
* On each system controller node an additional middleware component, the Chassis Manager (CM, processo <code>asp_cm</code>) will be installed and started when SAFplus Platform starts.
* The booting time of CM depends on the underlying shelf manager technology. On some shelves the HPI discovery time can take significant amount of time (20-40 seconds). CM will wait till the discovery completes before it send its readiness signal to the availability manager. Consequently the boot time of SAFplus Platform may be longer.
* A major or critical HPI event on a server FRU (that runs SAFplus Platform) will trigger SAFplus Platform to preventively remove all service assignments from the problematic FRU. In case the HPI event is de-asserted later, the services will be re-assigned to the recovered FRU. (Indirect FRU dependencies can be modeled during design time by extending the FRU dependency table used by CM.)
* Upon an extraction request event (triggered either by manually opening the ejection latches/levers of an AdvatncedTCA blade or other FRU, or requesting such event via the shelf manager or HPI interface), CM will notify AMF about such event, and AMF will immediately remove the services from the given FRU. In case of redundant setup, the services will be switched over to other FRUs. Then, SAFplus Platform will allow normal OS shutdown to take place. Upon completion of the OS shutdown process, the blade will be powered down as usual, hence reaching the deactivated state, allowing the removal of the FRU. Please note that once the shutdown process is started, closing the latch will not reverse the process: the blade will be inactivated. Once the inactive state is reached, the FRU can be freely removed or it can be re-activated by opening and closing the latches.
* If a minor HPI event is detected by CM, it will be processed using customized callback functions, if provided. Callback functions can be specific to FRU types and instances. The default behavior is to ignore all minor events.

Doc:latest/sdkguide/basicinfrastructure

2010-08-27T03:48:10Z

Senthilk:

=='''Basic Infrastructure'''==

It is well known that the standard C library contains deficiencies in scope, simply because it has not been updated to reflect modern programming needs. For example, while it does encapsulate standard operating services such as disk and terminal IO, it does not capture operating system services such as threads, and timers. It also does not provide a standard set of container data structures, like linked lists and hash tables. Additionally, various operating systems sometimes differ in their support for these newer services; to support multiple operating systems a compatibility layer must be written. Finally, certain operating system services are not sufficient for modern use or not sufficent for use within a clustered environment -- for example, the standard Unix timer allows only a single timer per process (we allow thousands), and the logging service has only minimal cluster support (we provide a fully cluster-aware logging system).

The Basic Infrastructure addresses these deficiencies by providing libraries that supply additional functionality, address insufficient APIs, and provide a compatibility layer. Additionally, the Basic Infrastructure handles the operational details of running within the OpenClovis distributed computing environment. These essential services, memory and data management are used by all the OpenClovis software and utilities. Customer applications are also welcome to use these APIs to take advantage of this infrastructure.

===Components of Basic Infrastructure===

'''Basic Services''':
* [[#Execution Object (EO) | Execution Object (EO)]]
* [[#Log Service | Log Service]]
* [[#Operating System Abstraction Layer (OSAL) | Operating System Abstraction Layer (OSAL)]]
* [[#Timer Library | Timer Library]]
* [[#SAFplus Platform Console | SAFplus Platform Console]]
* [[#Rule-Based Engine (RBE) | Rule-Based Engine (RBE)]]

'''Memory Management''':
* [[#Containers | Containers]]
* [[#Circular List | Circular List]]
* [[#Queue Library | Queue Library]]
* [[#Buffer Manager Library | Buffer Manager Library]]
* [[#Heap Memory | Heap Memory]]

'''Data Management''':
* [[#Database Abstraction Layer (DBAL) | Database Abstraction Layer (DBAL)]]

====Log Service====

SAFplus Platform Log Service provides the facility of recording the information about various events of applications. Any application/SAFplus Platform component in the cluster can use the Log Service to record the information. Log Service persist the information recorded by its clients so that it is available for consumption at later points in time also. The consumer may be an offline consumer, consuming the information at some later point in time, or an online consumer, consuming the information as soon as it is generated. Log Service does not interpret the information recorded by its clients. It treats the information as octet stream and does not apply any semantic meaning to it.

'''Features'''

* SAFplus/Log service provides high performance, low overhead logging.
* SAFplus/Log service supports ASCII, binary and Tag-Length-Value (TLV) logging.
* It provides support for LOCAL/GLOBAL streams.
* Log-levels can be changed during the operation.
* Redundancy support during failover and switch over.

=====Logging Types=====

There are three different kind of logging modes are supported by SAFplus/Log Service. They are as follows Binary logging, TLV logging and ASCII logging. During logging message
msgId field of clLogWriteAsync() API will identify what kind of record is being logged. This msgId is typically an identifier for a string message which the viewer is aware of through off-line mechanism. Rest of the arguments of this function are interpreted by the viewer based on this identifier. By default, SAFplus Platform components log their messages as ASCII logging by using clLog() macro which intern puts the messages into predefined SYS stream using CL_LOG_HANDLE_SYS as handle.

*'''ASCII Logging'''
There are two ways application can do ASCII logging. The first method is by calling clLogWriteAsync() with msgId field as CL_LOG_MSGID_PRINTF_FMT, the second way is by calling clAppLog() macro.

*'''Binary Logging'''
Binary logging should be done through clLogWriteAsync() API with msgId field as CL_LOG_MSGID_BUFFER.

*'''TLV(Tag-Length-Value) Logging'''
TLV logging should be done through clLogWriteAsync() API with user defined msgIds other than CL_LOG_MSGID_BUFFER and CL_LOG_MSGID_PRINTF_FMT.

=====Log Service Entities=====

*'''Log Record''': One unit of information related to an event. This is an ordered set of information. Log Record has two parts - header and user data. Header contains meta-information regarding the event and data part contains the actual information. All information related to one event is stored as one unit. This unit is known as Log Record.

*'''Log Stream''': Log Records are grouped together based on certain client defined theme. This group is called Log Stream. These Log Streams can be shared by various components of an application or of different applications. The theme and the users of a Log Stream are defined by the application.

*'''Log File''': One of the destination for Log Stream and persistent store for Log Records. A collection of Log Streams can flow into one Log File for the ease of management of data.

*'''Log Stream Attributes''': Each Log Stream is characterized by a set of attributes. These attributes are specified at the time of creation of the Stream and can not be modified during the lifetime of that Stream. The attributes include the file name and the location of the file where the Stream should be persisted, size of each record in the Log Stream, maximum number of records that can be stored in one physical file, action to be taken when the file becomes full, whether the file has a backup copy and the frequency at which the Log Records must be flushed. These attributes are specified through ClLogStreamAttributesT structure.

*'''GLOBAL Log Stream''': All global streams will have unique name within the cluster with stream scope of CL_LOG_STREAM_GLOBAL. A global stream is accessible throughout the cluster irrespective of where it is created.

*'''LOCAL Log Stream''': All local streams will have unique name within the node with stream scope of CL_LOG_STREAM_LOCAL. A local stream is restricted to local node.

=====Log Record Format=====

SAFplus/Log service follows two different record formats. Those are binary record format
and ASCII record format.

'''Binary Record Format'''

Binary record format is described as below.

* Byte 0 of Log Record has 3 fields
** Bit 0 denotes endianess(Bit value 1 denotes little endian)
** Bit 1 denotes Header extension bit, currently unused
** Bit 2 - Bit 3 are currently unused
** Bit 4 - Bit 7 denotes record format version, currently 0
* Byte 1 denotes severity with which the Log Record is logged
* Byte 2 - Byte 3 denotes StreamId of Log Stream to which the Log Record belongs
* Byte 4 - Byte 7 denotes ClientId of the component logging the record
* Byte 8 - Byte 9 denotes ServiceId of the component logging the record
* Byte 10 - Byte 17 denotes timestamp of the Log Record
* Byte 18 - Byte 19 denotes messageId of the message that follows it

[[File:SDK_logrecord.png|frame|center|'''Binary Record Format''']]

Each log record contains a bit specifying the endianness of the format in which
the log record is stored. This is the 0th bit of the 0th byte. If the bit is
set then the log record format is stored in little endian format otherwise on
big endian.

First Byte that we put in configuration file, filename_<creationTime>.cfg,
denotes the endianess of machine on which the File Handler is running.
Again, value of 1 denotes little endian machine.

'''ASCII Record Format'''

The ASCII record format contains only the log message. The content and format
of the log message is left to the caller. In order to create coherent and
consistent log records, the caller should define a consistent style and
insert all desired meta data into each log record. These may include
timestamp, severity, source process, etc. For convenience, OpenClovis provides
a macro, clAppLog(), which takes care of consistent formatting by
automatically inserting the following information into each log record:
* timestamp
* node name
* process pid number
* program (EO) name
* message number
* file name and line number (conditional)

In addition, the following structured information must be provided by the
user as macro arguments:
* area name
* context name
* severity
* actual log message

=====Viewing Log Records of Different Types=====

'''ASCII log records'''

To view an ASCII log file simply open them with your favorite editor.

'''Binary log records and TLV(Tag-Length-Value) records'''

To view these two types of records OpenClovis provides following log viewing tools :
#Online log viewer ('asp_binlogviewer' present in $ASP_BINDIR directory)
#Offline log viewer ('cl-log-viewer' present in <installation_directory>/sdk-3.0/bin directory)

If the log file contains the log records of TLV type then user need to provide the TLV mapping file which contains user defined message id to actual log message mapping. Following is a sample TLV map file which contains message id to TLV message mapping. TLV File content should be in following format, where <code><space></code> is a single space.:

Message_ID<space>Message containing %TLV

All the %TLV are replaced by their corresponding values from log record's tag, length, value information for that message id. Following are the sample content of a TLV map file <code>tlvmap.txt</code>:

5 Component %TLV was unble to start on node %TLV
6 State Change: Entity [%TLV] Operational State (%TLV -> %TLV) AMF (%TLV)
7 Registering Component %TLV via eoPort %TLV
8 Extending %TLV byte pool of %TLV chunkSize

For detailed usage of log view tools, please refer to ''OpenClovis Log Tool User Guide''.

=====Log File and Its Characteristics=====

Multiple Log Streams may be persisted in one Log File. Local and Global streams can be mixed together in one Log File. But, in such a case, all the stream attributes other than flushFreq and flushInterval must be same.
Log File is a logical concept and it is a collection of physical files. Each such physical file is called a Log File Unit. In case the action on Log File being full is specified as CL_LOG_FILE_FULL_ACTION_HALT or CL_LOG_FILE_FULL_ACTION_WRAP, the Log File consists of only one Log File Unit, whereas if the action is CL_LOG_FILE_FULL_ACTION_ROTATE, one Log File contains multiple Log File Units. Each Log File Unit is of same size specified as fileUnitSize in Log Stream Creation attributes. Maximum number of Log File Units in a Log File is governed by maxFilesRotated attribute of Log Stream. The Log File Unit names follow the following pattern: fileName_<creationTime>, where fileName is a stream attribute and <creationTime> is the wall clock time at which this Log File Unit is created, this time is in ISO 8601 format. One more file per Log File is generated with the name filename_<creationTime>.cfg to store the metadata of Log Streams being persisted in the Log File. This file contains attributes of the Log Streams going in this file and streamId to streamName mapping

=====Log Service Configuration=====

The common log service parameters, and the configuration parameters of the perennial and precreated log streams are described in section [[Doc:sdkguide/compconfig|OpenClovis SAFplus Platform Component Configuration]].

=====Controlling Logging Behavior from the Applications=====

To change the default log level set the environment variable "CL_LOG_SEVERITY" to one of the following values:

* EMERGENCY
: system is unusable
* ALERT
: action must be taken immediately
* CRITICAL
: critical conditions
* ERROR
: error conditions
* WARN
: warning conditions
* NOTICE
: normal but significant condition
* INFO
: informational messages
* DEBUG
: debug-level messages
* TRACE
: Information about entering and leaving functions and libraries.

The meaning of each level is the same as the standard syslog levels (RFC 3164), with the addition of TRACE.

A log will be printed if it is more severe or equal in severity to the level set in CL_LOG_SEVERITY. Additionally, if the log level is set to DEBUG, then all log messages will also contain the file and line number of the statement that generated the log. If this environment variable is not set, "NOTICE" is used. Logs that are less severe than NOTICE (INFO, DEBUG, TRACE) may impact system performance.

Example:
export CL_LOG_SEVERITY=DEBUG

To add or remove time stamps form logs use the 'CL_LOG_TIME_ENABLE' variable. Time stamps are enabled by default. Example:
export CL_LOG_TIME_ENABLE=0

[[File:OpenClovis_Info.png]] For further information on the Log Service and its APIs, please refer to the Log Service section of the ''OpenClovis API Reference Guide''.

=====Advanced Filtering Techniques of ASCII Log Files=====

Setting the log level to DEBUG or TRACE can generate too many irrelevant logs to easily debug a problem, and may impact system performance. To solve this problem a more sophisticated rule based filtering system is available. To use this system, create a file called "/tmp/logfilter.txt" (located in the /tmp directory so it will not be removed if you delete and redeploy SAFplus Platform).

This file must contain filter rules, 1 per line. The format of a rule is as follows:
(''NodeName'':''ProgramName''.''AreaName''.''ContextName'')[''FileName'']=''Severity''

''NodeName''
: The name of the node as specified in the IDE (it also is used as the name of the deployment .tgz file)

''ProgramName''
: The name of the program as specified in the IDE

''AreaName''
: This arbitrary string is passed as a parameter to the clAppLog function, and is meant to correspond to some aspect of the software organization

''ContextName''
: This arbitrary string is passed as a parameter to the clAppLog function, and is meant to correspond to the software library

''FileName''
: The source file that generated the log

''Severity''
: The log severity (values defined above) to use as the cutoff for all matching logs.

Note that the asterisk "*" character may be used in any of these fields to match all possibilities.

The following is an example of a filter file:

<code><pre>
#this file containes set of rules to filter out debug messages
#while bring up SAFplus Platform. User can add as many rules as they want.
#Rules will be considered as OR.

#SYNTAX for the follows
#(NodeName:ServerName.AreaName.ContextName)[fileName]=Severity

#The following are the set of rules.

#For all the messages from SysCtrl0 , set the severity level to ERROR.
(SysCtrl0:*.*.*)[*]=ERROR

#For all the message from logServer, set the severity level to INFO.
(*:LOG.*.*)[*]=INFO

#For all the message from ckpt AREA name, set the severity level to NOTICE.
(*:*.CKP.*)[*]=NOTICE
</pre></code>

====Operating System Abstraction Layer (OSAL)====

The OpenClovis Operating System Abstraction Layer (OSAL) provides a standard interface to commonly used operating system functions. The OSAL layer supports target operating systems like most varieties of Linux.

'''Features'''

* Easily adaptable to any proprietary target operating system.

'''How it works'''

All OpenClovis SAFplus Platform components are developed based on OSAL that provides an OS agnostic function to all system calls, such as process 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.

OSAL is currently designed as a standalone library with trivial dependencies on the Util and Debug OpenClovis SAFplus Platform components for debugging and logging.

The full OSAL API documentation is located in the ''OpenClovis API Reference Guide'', included in your SAFplus Platform documentation package.

==== Task Pool and Job Queue====

A Task pool is a manager of a set of threads that provides a simple facility for deferring jobs to tasks in the pool and has the ability to automatically create/delete tasks when needed. Task Pools can be created using clTaskPoolCreate/clTaskPoolRun.

Taskpool could be stopped with clTaskPoolStop and deleted with clTaskPoolDelete.

Taskpools could be also monitored externally by another guy to check for deadlocks with the job threads with clTaskPoolMonitorStart providing a monitorThreshold and a monitorCallback thats invoked whenever any thread in the taskpool is blocked on a job callback for more than configured threshold. The callback is invoked with the ThreadID, interval at which the thread was blocked and the max. allowed threshold for the task pool configured.

A job queue is a list of "work items" (a function pointer and argument) that is attached to a task pool. Tasks in the pool automatically consume and execute any jobs that are placed on the queue. The flexibility and power is increased through clJobQueueInit with a task pool max threads limit (non-zero). Jobs are be pushed through clJobQueuePush API that takes a job handler(function pointer) and a job argument. This job is then run in the context of a task pool thread.

Job/Taskpool processing could be stalled through clJobQueueQuiesce/clTaskPoolQuiesce and only taskpools could be resumed with clTaskPoolResume. Job queues created are deleted with clJobQueueDelete.

Please see the API documentation for more details.

====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.

[[File:OpenClovis_Info.png]] For further information on the Timer Library and its APIs, please refer to the Timer section of the ''OpenClovis API Reference Guide''.

====SAFplus Platform Console====

The OpenClovis SAFplus Platform Console is a simple command line interface (CLI) that provides diagnostic access to all system components (including OpenClovis SAFplus Platform service components, and eonized customer applications), irrespective of the location (node) where the component runs. This CLI is designed to assist the application developers and field engineers in testing and debugging applications, and so is also called the "Debug CLI".

The CLI infrastructure routes the commands to the respective component which processes the commands and provides responses to the user. OpenClovis SAFplus Platform service components provide custom commands so that functionality specific to that service component can be accessed.

'''Features'''

* Using CLI commands, you can view or manipulate the data managed by OpenClovis SAFplus Platform components.
* SAFplus Platform Console can be used for eonized customer applications. The framework ensures that the application is accessible from the central CLI server. Customer applications add custom commands and functionality by "registering" commands and function handlers into the SAFplus Platform Console through APIs defined in the "Debug" library.
* SAFplus Platform Console allows examination of information stored in the COR database, without the need to write custom handlers.
* SAFplus Platform Console provides a centralized access to all OpenClovis SAFplus Platform components and eonized applications. Using custom CLI commands a wide variety of services and features can be exposed to the CLI framework, which allows sophisticated, multi-component tests orchestrated through this interface.

Specific information is located in the ''OpenClovis SAFplus Platform Console Reference Guide'' provided with your OpenClovis SDK documentation set.

====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.

====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.

====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. The OpenClovis heap memory subsystem allows the components to be configured with allocation limits so that a process with a memory leak will not consume resources needed by other processes. Additionally allocation alarms can be configured so that the operator can be notified of imminent memory exhaustion and appropriate action be taken.

For information about configuring these limits and alarms see [[Doc:sdk_3.1/sdkguide/compconfig | OpenClovis SAFplus Platform Component Configuration]].

====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 databases.

'''Features'''

* DBAL currently supports:
** the SQLite database
** the GNU Database Manager (GDBM).
** the Oracle Berkeley DB

'''How it Works'''

The primary user of this interface is the COR component which can write 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.

For information about selecting a database engine see [[Doc:sdk_3.1/sdkguide/compconfig | Configuring Database Abstraction Layer (DBAL)]].

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

=====Introduction=====

Before understanding the concept of an execution object, we need to understand the concept of execution entity in general. The execution entity itself is an abstraction model and the execution object is an implementation of that model in the SAFplus Platform environment.

=====Execution Entity=====

An execution entity is a form of a process, a task or a thread that contains a set of data and an execution context. Any form of interaction in a networked environment involves execution entities and so the concept of execution entities is not specific to the carrier grade middleware like OpenClovis SAFplus Platform. However, from pragmatic point of view, the execution entities running in a distributed system like OpenClovis SAFplus Platform environment are not very effective if they do not have the facility of external communication and thereby not 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.

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.

=====Execution Object - Execution entity of OpenClovis SAFplus Platform environment=====

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) 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.

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.

Both management and service interfaces provided by an EO are exposed using RMD APIs. In fact, the terms "management" and "service" interface are only conventions used to indicate whether the function is exposed or not in the context of a particular EO. For e.g. the service provided by an EO can be a management interface to another EO, if the latter EO manages the first EO. Managing can be as simple as invoking any method in the context of EO in order to carry out some action on EO like for e.g. checking if the EO is capable of providing service. The messages received at the EO are processed by the worker threads which finally invoke the proper functions in the context of the EO.

The application components encapsulated by EO communicate with other components using other OpenClovis communication infrastructure components such as Event Manager (EM), Remote Method Dispatch (RMD), Transparent Inter Process Communication (TIPC), and Name Service.

=====Execution Object - Thread/task pooling=====

Note: OpenClovis uses the terms task and thread interchangeably

We have a taskpool per ioc/tipc priority per EO. The taskpool is attached to a per EO job queue and is configured in code to have taskpools with a thread limit. (This configuration is not allowed as of now through IDE).

Whenever an incoming request comes into EO via ioc/tipc receive, the priority of the header is mapped to the appropriate job queue before getting pushed into that job queue. And then the job is picked up by the taskpool that schedules an idle thread of the taskpool to process the job (or creates a new one if within the limit) and the job handler is then subsequently invoked in the context of the thread.

EO job queues are monitored for blocked threads and will log an entry to our log file whenever a possible deadlock or threadblock is detected.

The taskpool APIs can be used independently by applications. For more information please see the [[Doc:latest/sdkguide/basicinfrastructure#Task_Pool_and_Job_Queue|Task Pool and Job Queue]] sections under [[Doc:latest/sdkguide/basicinfrastructure | Basic Infrastructure]]

Doc:latest/sdkguide/cominfrastructure

2010-08-27T03:47:07Z

Senthilk:

=='''Communication Infrastructure'''==

Intracluster Communications is a critical element in any tightly coupled distributed system, and is very different from standard TCP client/server communications paradigms. OpenClovis provides several communications facilities that are used by the SAFplus Platform framework and that should be used by customer software. OpenClovis provides an abstraction for simple low-latency LAN based direct message passing called IOC, and provides an implementation of the same over TIPC - the standard Linux inter-cluster low-latency communications mechanism. All OpenClovis services use IOC to communicate with peers except for GMS (Group management) which uses IP multicast. Therefore, a customer can port the entire SAFplus Platform to another messaging system simply by implementing the IOC interfaces.

These communications services are available on every SAFplus Platform node and are automatically integrated into EO-inized applications. They allow any component to directly communicate with any other component running on any node and allow components to be identified (addressed) either by location or by an arbitrary name (location transparent addressing). These "arbitrary names" can be move from component to component as need or failures dictate. The communications system also automatically provides component and node failure notifications via a heartbeat mechanism.

Higher level communications abstractions and tools such as events, remote procedure calls, and endian translation are also supported.

Components of Communication Infrastructure:
* [[#Event Service | Event Service]]
: Publish/Subscribe multipoint communications model.
* [[#Intelligent Object Communication (IOC)| IOC]]
: Low level messaging abstraction layer
* [[#Name Service | Name Service]]
: Identify nodes via names instead of physical addresses. Names can be transferred between nodes to implement failover.
* [[#Remote Method Dispatch (RMD)| Remote Method Dispatch (RMD)]]
: Call functions on other nodes
* [[#Interface Definition Language (IDL) | Interface Definition Language (IDL)]]
: Abstract definition language that can be used in mixed-endian environments to allow data do be automatically swapped.

[[File:SDK_ComInfrastructure2.png|center|frame|'''Communication Infrastructure''']]

===Event Service===

====Overview====

The Event Service is a publish/subscribe multipoint-to-multipoint communication mechanism that is based on the concept of event channels, where a publisher communicates asynchronously via with one or more subscribers over a channel. The publishers and subscribers are unaware of each others existence.

====Terms, Definitions====

* '''Event''': Any data that needs to be communicated to interested parties in a system is called an event. This data typically describes an action that was taken or a problem that was detected.
* '''Subscribers''': Entities interested in listening to an event
* '''Publishers''': Entities that generate the event. An entity can be both a publisher and a subscriber
* '''Event Channel''': A global or local communication channel that allows communication between publishers and subscribers. By sending events in channels, all events do not need to go to all Subscribers.
* '''Event Data''': Zero or more bytes of payload associated with an event
* '''Event Attributes''': The publisher can associate a set of attributes with the each event such as the event pattern, publisher name, publish time, retention time, priority, etc.
* '''Event Pattern''': The attribute which describes type of an event and categorizes it. This is used for filtering events.
* '''Event Filter''': The subscribers use filters based on the patterns exposed by the publisher to choose the events of interest, ignoring the rest.

====Features====

* SAF compliant implementation
* The publisher and the subscriber can be:
** In the same process address space
** Distributed across multiple processes on the same CPU/board
** Distributed across multiple processes on various CPU/boards
* Event Channels can be local or global
** Local channels for SAFplus Platform node internal events
** Global channels for SAFplus Platform cluster wide events
* Multiple subscribers and publishers can open the same channel
* Events are delivered in strict order of generation
* Guaranteed delivery
* At most once delivery
* Events can have
** Any payload associated with them
** Pattern defining the type of the event
** A specified priority
** A retention time for which the event is to be held before discarding
* Events published on a channel can be subscribed to, based on a filter that matches the event pattern
* Debug support by monitoring and logging
** Controlled at run time

====Architecture====
[[File:SDK_EMArchitecture.png|center|frame|'''Event Service Architecture''']]

The Event Service is based on RMD and IOC. It involves the communication between publishers and subscribers without requiring either side to explicitly "identify" the other side. That is, the publisher does not need to know who the subscribers are and vice versa. This is accomplished via an abstraction called an event channel. All events published to a channel go to all subscribers of the channel. To handle node specific events efficiently, a channel is categorized as local and global. The local channel is limited to a single node while a global channel spans across the nodes in the cluster. This feature is an extension to the SA Forum (SAF) event system where there is no such distinction and all channels are inherently global. An event published on a global channel requires a network broadcast while a local event does not use the network and is therefore very efficient.

====Flow====

[[File:SDK_EMFlow.png|center|frame|'''Event Service Flow''']]

To use the Event Service an understanding has to be established between the publisher and the subscriber. The type of the payload that shall be exchanged should be known to both and also if any pattern is used by the publisher it has to be made known to the subscriber.

Both the subscriber and publisher are required to do a Event Client Library initialize to use the Event Service. Both then open the channel, subscriber with the subscriber flag and publisher with publish flag. To both publish and subscribe to a channel, set both flags. This means that the subscriber and publisher can be the same entity. However, for the purposes of clarity in this description the logical separation of "subscriber" and "publisher" will be maintained.

The subscriber than subscribes to a particular event using a filter that will match specific event patterns that interests that subscriber. The publisher on the other hand will allocate an event and set it's attributes. It optionally sets the pattern to categorize the event. This pattern is matched against the filter supplied by the subscriber. The publisher then publishes the event on the channel. If channel is global the event is sent to all the event servers on the cluster who in turn deliver the event to any subscribers on that node. If the channel is local the event is delivered to the subscribers who have subscribed to this event locally. The event is delivered only to those subscribers which have an appropriate filter.

For further details on the usage of Event Service kindly refer to the OpenClovis API Reference Guide.

===Transparent Inter Process Communication (TIPC)===
TIPC provides a good communication infrastructure for a distributed, location transparent, highly available applications. TIPC is a Linux kernel module; it is a part of the standard Linux kernel and is shipped with most of standard distributions of Linux. It supports both reliable and unreliable modes of communications, reliable being desired by most applications (even if the hardware is reliable, buffering issues can make the program-to-program communications unreliable). Since TIPC is a Linux kernel module and works directly over the Ethernet, any communication that uses TIPC will be very fast compared to other protocols. The TIPC kernel module provides a few important features like topology service, signaling link protocol, location transparent addressing. This section describes only the features of TIPC as used by SAFplus Platform, although SAFplus Platform programs are welcome to access the TIPC APIs directly to use other features. For more details please refer to the tipc project located at http://tipc.sourceforge.net.

From TIPC view point the network is organized into a 5-layer structure.

* TIPC Network : This is the ensemble of all the computers interconnected via TIPC. This is a domain within which any computer can reach any other computer using the TIPC address.
* TIPC Zone : This is group of clusters is a zone.
* TIPC Cluster : A group of computers is called a cluster.
* TIPC Node : A node is a computer.
* TIPC Slave Node : It is same as a node, but will communicate with only one node in a cluster. This is unlike normal nodes which are connected to all the nodes in the cluster.

TIPC does not use "normal" ethernet MAC addresses or IP addresses. Instead it uses a "TIPC address" that is formed from these fields. In general, this complexity is hidden from the SAFplus Platform programmer since addresses are automatically assigned.

====TIPC features====
The list below describes some features of TIPC:
* Broadcast.
* Location Transparent Addressing.
* Topology Service.
* Link Level Protocol.
* Automatic Neighbor Detection.

====Broadcast====
TIPC supports unicast, multicast and broadcast modes of sending a packet. Depending on the intended mode the TIPC address has to be specified. The format of the address looks like (type, lower instance and upper instance).
* type : This is the port number of a component to which the packet is to be sent to.
* lower instance : This is the lowest address of the nodes to which the packet should go to.
* upper instance : It is the highest address of the nodes to which the packet should go to.
The lower instance and upper instance together form the range of address. If these 2 are same then the packet will be unicasted to that destination node. And if the the range covers all the nodes of a system then it is a broadcast packet and will be sent to all the nodes node in the system.

====Location Transparent Addressing====
An application can be contacted without having the knowledge of its exact location. This is possible through Location Transparent Addressing. A highly available application in a system while providing service to many of its clients might suddenly go down due to this some kind of failure in the system. And the same application can come up on another node/machine with the same Location transparent address. This way the clients can still reach the server with the same address, which they used to contact previously.

====Topology Service====
TIPC provides a mechanism of inquiring or subscribing for the availability of a address or range of addresses.

===Intelligent Object Communication (IOC)===

The Intelligent-Object-Communication(IOC) module of SAFplus Platform provides the basic communication infrastructure for an SAFplus Platform enabled system. The IOC is a compatibility layer on top of TIPC that will allow customers to port SAFplus Platform to other architectures. Therefore, all SAFplus Platform components use the IOC APIs rather than TIPC APIs. IOC exposes only the most essential TIPC features to make porting simpler. IOC also abstracts and simplifies some of the legwork required to connect a node into the TIPC network. Customers are encouraged to use the IOC layer (or higher lever abstractions like event and RMD) to ensure portability in their applications, or may use TIPC directly.

====IOC Architecture====

[[File:SDK_IOCArchitecture.png|center|frame|'''IOC Architecture''']]

====IOC Features====

* Reliable and Unreliable mode of communication.
* Broadcasting of messages.
* Multicasting of messages.
* Transparent/Logical Address to a component.
* An SAFplus Platform node arrival/departure notification.
* The arrival/departure notification of a component.

=====Reliable and Unreliable mode of communication=====
The IOC with the help of TIPC allows the applications to create a reliable or an unreliable communication port. All the communication ports are connectionless ports. This helps to achieve a high speed data transfer. Reliable communications are highly recommended and is the default used by OpenClovis SAFplus Platform. It should be used even within an environment with extremely low message loss at the hardware level (such as an ATCA chassis) because message loss may also occur in the linux kernel or network switch due to transient spikes in bandwidth utilization.

=====Broadcasting of messages=====
IOC supports the broadcasting of messages, qualified by destination port number. This means that a broadcast message sent from a component will reach all components on all nodes in the cluster that are listening to the communications port specified in the destination-address field of the message.

=====Multicasting of messages=====
Multicasting is sending of a message to only a group of components. Any component may join the group by registering itself with IOC for a specific multicast address. Thereafter any message sent to that multicast address will reach all the registered components in the cluster.

=====Location Transparent/Logical Address to a component=====
Transparent addressing support of IOC makes communication possible for an SAFplus Platform component with another another SAFplus Platform component without knowing the second one's physical address. Location Transparent addressing is commonly used in the case of redundant components that provide a single service. If the service uses a Location Transparent address, clients do not need to discover what component is currently providing the service; a client simply addresses a message to the Location Transparent Address, and that message is automatically sent to the component that is currently "active".

On the server side, it is the responsibility of the "active" component of the redundant pair to "register" with IOC for all messages sent to the Location Transparent Address.

=====SAFplus Platform node arrival/departure Notification=====
In a cluster having many SAFplus Platform nodes in a system, some SAFplus Platform components might be interested in knowing when a node in the cluster arrives and when one leaves. This feature of IOC informs such an event to all the interested SAFplus Platform components in the whole SAFplus Platform system. Components may use either a query or a callback based interface.

=====The arrival/departure notification of a component=====
This feature of IOC helps the components which are interested in other components' health status. The IOC with the help of TIPC will come to know about every SAFplus Platform components health in a system and it conveys this to all the interested SAFplus Platform components though a query or callback interface. Component arrival and departure is actually measured by when the component creates or removes its connection to TIPC, as opposed to when the process is created or deleted. The OpenClovis EO infrastructure always creates a default connection upon successful initialization, so this measurement is actually more accurate than process monitoring. A thread is automatically created in each process as part of the EO infrastructure to monitor all other components health status and to handle SAFplus Platform communications.

===Interface Bonding===

Any fully redundant solution requires physical redundancy of network links as well as node redundancy. This link-level redundancy is particularly important between application peers (i.e. between nodes in the cluster) because if peer communications fail at the ethernet level than it is not possible to distinguish certain link failure modes from node failure modes. In these cases each peer will assume that the other has failed, leading to a situation where all nodes assume the "active" role. In the worst case, each "active" node will service requests and so the state on each node will diverge (in practice the nodes tend to interfere with eachother, by both claiming the same IP address for example, resulting in loss of service). When the link failure is resolved, one of the 2 nodes will revert back to "standby" status, losing all state changes on that node. The solution to this "catastrophic" failure mode is simply to have link redundancy so that no single failure will cause the system to enter this state.

The simplest link redundancy solution can be implemented at the operating system layer and is called "interface bonding". In essence 2 "real" interfaces, say "eth0" and "eth1" are combined to form a single "virtual" interface called "bondN" (or "bond0" in this case) that behaves from the applications' perspective like a single physical interface. Policies can be chosen as to how to distribute or route network traffic between these 2 interfaces.

The OpenClovis SAFplus Platform can be configured to use a "bonded" interface for its communications in the exact same way as it is configured to use a different "real" interface (see the IDE user guide or XML configuration file formats for more information). Customers may want to configure their "bonded" interface in different ways based on their particular solution. Details describing how to enable bonding in operating system and OS distribution specific and is therefore beyond the scope of this document and the OpenClovis SAFplus Platform software. However a bonding configuration that is considered the "best practice" for use with OpenClovis SAFplus Platform is described in the following sections.

====Configuring the bonding====
The Interface Bonding is a Linux kernel module. To work with this the kernel should have been compiled with the "Bonding driver support" (for major distributions, this flag is often on by default). For more details on how to install bonding driver module into the kernel please refer to the "bonding.txt" in Linux Documentation's "networking" section.

<ol>
<li> Loading the kernel module
The following two lines are needed to be added to /etc/modprobe.conf or /etc/modules.conf

alias bond0 bonding
options bond0 mode=active-backup arp_interval=100 \
arp_ip_target=192.168.0.1 max_bonds=1

* mode : Specifies one of the bonding policies.
**active-backup : Only one slave in the bond is active. A different slave becomes active if, and only if, the active slave fails. The bond's MAC address is externally visible on only one port (network adapter) to avoid confusing the switch. This mode provides fault tolerance.
* arp_interval : Specifies the ARP monitoring frequency in milli-seconds.
* arp_ip_target : Specifies the ip addresses to use when arp_interval is > 0. These are the targets of the ARP request sent to determine the health of the link to the targets. Specify these values in ddd.ddd.ddd.ddd format. Multiple ip addresses must be separated by a comma. At least one ip address needs to be given for ARP monitoring to work. The maximum number of targets that can be specified is set at 16.
* max_bonds : Specifies the number of bonding devices to create for this instance of the bonding driver. E.g., if max_bonds is 3, and the bonding driver is not already loaded, then bond0, bond1 and bond2 will be created. The default value is 1.

<li> Use the standard distribution techniques to define the network interfaces. For example, on Red Hat distribution create an ifcfg-bond0 file in /etc/sysconfig/network-scripts directory that resembles the following :

DEVICE=bond0
ONBOOT=yes
BOOTPROTO=dhcp
TYPE=Bonding
USERCTL=no

<li> All interfaces that are part of a bond should have SLAVE and MASTER definitions. For example, in the case of Red Hat, if you wish to make eth0 and eth1 a part of the bonding interface bond0, their config files (ifcfg-eth0 and ifcfg-eth1) should resemble the following:

DEVICE=eth0
USERCTL=no
ONBOOT=yes
MASTER=bond0
SLAVE=yes
BOOTPROTO=none

Use DEVICE=eth1 in the ifcfg-eth1 config file. If you configure a second bonding interface (bond1), use MASTER=bond1 in the config file to make the
network interface be a slave of bond1.

<li> Restart the networking subsystem or just bring up the bonding device if your administration tools allow it. Otherwise, reboot. On Red Hat distros you can issue 'ifup bond0' or '/etc/rc.d/init.d/network restart'.

<li> The last step is to configure your model to use bonding. This can be done in the IDE through the "SAFplus Platform Component Configuration.Boot Configuration.Group Membership Service.Link Name" field. This default can also be overridden on a per-node basis through the "target.conf" file, LINK_<nodename> variable.
</ol>

===Name Service===
====Overview====
Naming Service is mechanism that allows an object to be referred by its "friendly" name rather than its "object(service) reference". The "object reference" can be logical address, resource id, etc. and as far as Name Service is concerned, "object reference" is opaque. In other words, Naming service (NS) returns the logical address given the "friendly" name. Hence, Name Service helps in providing location transparency.This "friendly" name is topology and location agnostic.

====Basic concept====

The name service maintains a mapping between objects and the object reference (logical address) associated with the object. Each object consists of an object name, an object type, and other object attributes. The object names are typically strings and are only meaningful when considered along with the object type. Examples of object names are "print service", "file service", "user@hostname", "function abc", etc. Examples of object types include services, nodes or any other user defined type. The object may have a number of attributes (limited by a configurable maximum number) attached to it. An object attribute is itself a <attribute type, attribute value> pair, each of which is a string. Examples of object attributes are, <"version", "2.5">, <"status", "active"> etc.

The name service API provides methods to register/deregister object names, types, attributes and associated addresses. A process may register multiple services with the same address or multiple processes may register the same service name and attributes. Some object names, attributes and addresses may also be 'statically' defined at start time. It is the responsibility of the process that registers an object to remove it when the object is no longer valid. However in the case where a process undergoes an abnormal termination, the name service will automatically remove associated entries.

The name service provides the ability to query the name database in various ways. Clients may query the name service to obtain the address and attributes of a object by giving the object name and type. "Content-addressable" access is also provided. In other words, clients may give attributes and ask for object names that satisfy those attributes.

====Features====
* The name service maps "service names" to attributes, including addresses
* Service Providers register their "service name", "address" and attributes with the Name Service
* Service Users query the Name Service to get information about a service
* Service users can communicate with service providers without knowing their logical address or physical location
* Multiple service providers can register the same name. The name service maintains a reference count for each "name" registered
* The name service subscribes to component failure notification from AMF. If a component dies, the reference count for the services it has registered is decremented.
* Supports context based naming to allow partitioning of the name space
** Local name spaces are local to the Name Server on a SAFplus Platform node
** Global Name Spaces are global to the SAFplus Platform cluster
** Name spaces are dynamically created at run time
* Supports three type of queries
** Query based on "Service Name": Given a service name returns the address and service attributes
** Query based on "Service attributes": Given service attributes, returns the Service Name and address
** Query based on "name space context": Given a name space context, returns all names in that space

====Subcomponents====

Based on the responsibilities, the Name Service component can be further subdivided into following modules

* '''Core Module'''
:Responsible for supporting the creation and deletion of user defined contexts and processing the requests for registration, deregistration. Also responsible for supporting the various NS related queries

* '''Life cycle Management Module'''
:Responsible for initialization, finalization, restart and other management functionalities

* '''Syncup Manager Module'''
:Responsible for NS DB synchronization and backing up of DB in persistent memory

====Contexts and Scopes====
The name service supports different sets of name-to-object reference mappings(also referred to as "context"). A particular "name" is unique in the context. A process will specify the context and the scope of its service during registration with the name service.

'''Context'''

* '''User-defined set'''
Applications may choose to be a part of a specific set (or context). For that, first a context has to be created. For example, all the SAFplus Platform related services can be a part of a separate context.

* '''Default set'''
Name Service supports a default context for services that don't form a part of any specific context.

'''Scope'''

* '''Node-local scope'''
The scope is local to the node. That is, the service provider and the user should co-exist on the same blade.

* '''Global or cluster-wide scope'''
The service is available to any user on any of the blades.

====Registration and Deregistration====
As the name suggests, during registration, an entry (i.e mapping between "name" and logical address) for the component is added into the name service database and during deregistration the entry is deleted.
 
In a typical SAFplus Platform HA scenario, whenever a component comes up and ACTIVE HA state is assigned to it, it registers with the local name service giving a string name for the service, the logical address, context and scope (the application obtains the logical address by using CL_IOC_LOGICAL_ADDRESS_FORM). Next the entry is added to the local name service database. If the scope is cluster-wide, the local name service indirectly passes this information to the name service master. Based on the context, the name service master decides whether to store the entry in the default context or the given user defined context. The name service also stores the component identifier along with that entry so that the entry can be purged if the component dies.
 
Note that the Name Service does not care about the HA state assigned to the component. On the one hand, this means that the component author must handle registration and deregistration when the service becomes active or standby. On the other hand, this allows great flexibility since standby components can still register names. The name service maintains reference count of instances providing a given service. Whenever a component registers with the name service, this reference count is incremented and whenever a component dies or deregisters, this reference count is decremented by the name service. If nobody is refering to a particular entry, then that entry will be deleted. Whenever a component goes down gracefully, it is the responsiblity of the component to delete the service which it registered.

====Name Service entries====
The name service database contains the following entries Name to Logical Address mapping, CompId of the component hosting the service, Count of no. of instances for the given service, a set of user defined attributes - The attributes will be <attribute type, attribute value> pair, each of which is a string. Examples of object attributes are, <"version", "2.5">, <"status", "active"> etc. The upper limit on no. of attributes is user configurable.

====Querying Name Service====
Whenever a component wants to get the logical address of a service, it queries its local Name Server specifying the context. Context is needed because "name" is not unique across contexts i.e. Same "name" can map to different objects in different contexts. Local Name Server checks both the node-local and the cluster-wide entries.
The Name Service query is based on "Name". If an application queries the local NS EO, and an entry is not found in local NS database (there is a chance that NS updation message did not reach the NS/L), the NS/L EO contacts the NS/M EO, which looks up its cluster-wide entries and gets the information. If the information is found, NS/L updates its local database as well.

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

====Overview====

This service is generically known as RPC (Remote Procedure Calls). In a system with a single address space, function calls made are local to the address space. However, in a distributed system, the services sought by a caller may not always be available locally, but at some remote node. Remote Method Dispatch or RMD facilitates calls to the remote callee and returns the results to the caller. From the point of view of the caller, and RMD call looks exactly like a local function call. However, the function is actually executed on another node. Details like what node provides the service, how to communicate with this node, and platform specifics like endianess is hidden from the caller.

====Features====

* Similar to RPC - Remote Procedure Call
* Enables you to make a function call in another process, irrespective of the location of the process
* Communication takes place over low latency IOC/TIPC layer
* Reliable communication ("at most once" semantics)
* Support both synchronous and asynchronous flavors
* IDL can be used to generate client/server stubs for user components (and is of course used internally for SAFplus Platform components)
* Platform agnostic - works across mixed endian and mixed mode (32 bit and 64 bit)

====Types of RMD Calls====

* Sync (with or without Response)
** This call will block until a response is received
** Reliable - function caller knows whether or not it succeeded when the call returns
* Async with Response
** This will initiate the function call and include a callback function to handle the response
** Reliable - function caller knows whether or not it succeeded via the callback
* Async without Response
** This sends NULL for callback function
** Not reliable

====RMD Usage====

From the caller's perspective, RMD usage is essentially a function call if IDL was used to generate the client/server stubs. RMD functions can be defined, and code generated through the OpenClovis IDE; please refer to the ''OpenClovis IDE User's Guide'' chapter 'Defining IDL'

Underneath the IDL are calls to the RMD API which are rarely used directly but described here for completeness.

Irrespective of the type of the call the RMD API will require at least the following parameters:
* IOC address (destination address and port)
* Input message (Input arguments to the call)
* Output message (The returned arguments)
* flags
* RMD options

Additionally, in case of async call, a callback function and a cookie (piece of context data that is not used by RMD, but passed back to the callback) need to be passed.

As illustrated in the diagram below the address comprises of the node address and port on which the application/service provider is listening. The user is also required to specify the service he wants executed via a RMD number which comprises of the Client ID and Service ID. The former helps identify which client service is sought - this could be the native table which consists of the services exposed by the application or any other client table installed by the libraries to which the application is linked. The service number is the index of the service that is desired.

[[File:SDK_RMDAddressing.png|center|frame|'''RMD Addressing''']]

For further details on the RMD usage kindly refer ''OpenClovis API Reference Guide''.

====RMD IDL====

RMD is typically used via IDL so that the user is saved from the idiosyncrasies of the underlying architectures and such.

* RMD IDL simplifies building of RMDs
** Generates server and client stubs
** Stubs do marshalling and un-marshalling of arguments making them platform agnostic
** Select appropriate semantics
** Takes care of endianness and mixed mode issues
** Uses XDR (see internet RFC1014) notation
* OpenClovis/IDE enables the generation of RMDs and linking them to a client EO
* Any function installed in an EO client can be called remotely

====RMD/EO Interface====

[[File:SDK_RMD_EO_70.png|center|frame|'''EO Execution Interface''']]

RMD and EO are tightly knit as can be observed in the illustration above. The service provider or server exposes a certain set of services by installing it in the EO. The client application interested in the service makes a RMD call to the server with the desired arguments. The node address specifies the node on which the server resides and the port identifies the server process. The RMD number specifies the service that needs to be executed of a particular client residing on the server. This request is sent across over TIPC/IOC layer to the server. The receiver thread of the server picks up this request and queues the same into the EO job queue and wakes up one of the worker threads to process the request. The worker thread checks the service requested and processes the request in the context of the server. The client is totally unaware where the service is processed. It could be in the same process address space, on a process on the same node or a process on a remote node.

Please refer the Componentization section of this document for a better understanding.

===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 mixed endian machines and mixed mode (32-bit and 64-bit architecture) setup. This it accomplishes by providing marshalling and unmarshalling functions for the various types of arguments. Thus IDL in combination with RMD is used to provide a simple and efficient means of communication across EOs.

====IDL Usage====

The IDL generation is done through a script that takes 2 arguments:
* the xml file which provides a definition of the user's EO and relevant data structures
* a directory in which to generate the code

It then generates client and server side code for the xml definition into the specified directory. The user then issues a top level build whereafter the server & client side libraries are generated. The user should link with the client side libraries and include the client and xdr headers in his code to make client calls. On the server side, the user is expected to provide actual function definitions corresponding to the service definitions present in the xml file. He is also expected to install the server stubs before using & uninstall them during termination using the install/uninstall functions provided on a per EO basis.

Code is generated as follows:
* Top level makefile that recursively descends into client & server
* The directory xdr in which, a .c & .h is generated for every custom defined data structure in the xml.
For every struture,corresponding marshal.c and unmarshall.c files will be generated.
* client - a .c & .h is generated in this directory. They contain the definition and declaration respectively of the sync client, async client and the async callback for each EO service defined in the xml. It also contains a makefile that generates a library out of the files in this directory and the xdr directory.
* server - a .c & .h is generated in this directory. They contain the definition and declaration respectively of the server stub and the server function for each EO service defined in the xml. It also contains a makefile that generates a library out of the files in this directory and the xdr directory.

The generated code inside the target directory looks like the following:

[[File:SDK_IDL_DirectoryStructure_80.png|center|frame|'''Directory Structure of Generated Code''']]

IDL translates the user's data structures passed through a function call to a message and vice versa. Therefore it requires the user to specify the function signatures. This is currently being done through xml. The user defines the EO through the xml along with the relevant data structures. The following section describes the xml definition in detail.

====IDL Specification====

The IDL script expects the EO interface definition from the user in XML format.

=====User-Defined Types=====
The IDL uses XDR representation to store application data internally while transferring it to another EO. Therefore, IDL requires the application to specify the data structures that will be transferred through RMD so that it can generate XDR functions required to marshal/un-marshal these data structures. Marshalling is the process of converting the native data to XDR format and un-marshalling is retrieving the data back to native format. There can be three user-defined types: structures, unions and enumerations. These are explained below.

======Enumerations======
Enumerations are like enums in C and are defined likewise.

======Structures======
These are like structures in C. Therefore, every structure defined is composed of data members. There is a restriction that structures within the structures are not allowed to be defined. However, this restriction can be overcome by defining the two structures separately and embedding one inside another as a data member. Data members have the following attributes:

'''name'''
This is the name of the data member and it is referred to within the structure by this name.

'''type'''
This can be one of the pre-defined Clovis data types or a user-defined type. It is the user's
responsibility to make sure that there are no circular inclusions. Circular inclusions happen when two or more UDTs include each other in their respective definitions in such a way that it creates a cyclic dependency amongst all the involved UDTs. The supported pre-defined Clovis data types are ClInt8T, ClUint8T, ClInt16T, ClUint16T, ClInt64T, ClUint64T, ClInt32T , ClUint32T.
ClNameT and ClVersionT.

======pointer======
This is an optional attribute. When this is enabled, it means that the data member is a pointer to the type specified. We cannot specify more than one level of indirection since it is necessary to specify the number of elements being pointed to for every level of indirection.

======lengthVar======
This attribute should be specified only if the data member is a pointer type, which means that the pointer attribute is set to true. This attribute specifies which data member in the structure will contain the number of elements being pointed to. It is an optional attribute. When no such attribute is specified for a pointer type data member, it is assumed that a single element is being pointed to.

======multiplicity======
This attribute is used to specify an array type of data member. The number of elements is specified through this attribute. This attribute must not be specified along with the pointer attribute. This is an optional attribute.

======Unions======
These are defined similar to structures. The difference is in terms of the interpretation and generation.

=====EO Interface=====

The EO has multiple tables called Clients into which the exported interface functions are installed. The user has to specify which functions are installed in which tables and then give a declaration of the functions themselves. Thus, an EO interface definition consists of one or more clients:

======Client======
A client has a Client-Id, which must either be a number or a constant. A client has multiple functions called Services. A Service has a name and zero or more Arguments. The Arguments to a Service are defined as follows:

'''Handle'''
The handle is the first parameter to be passed to a call on the client side or the server side. It is initialized with the address of the destination EO, and parameters like timeout, retries and priority on the call. For more details on handles, please refer to the SISP API Reference Manual.

'''Argument'''
An argument is similar to a data member, except for the following differences:
* It does not have a multiplicity
* It has an additional attribute where the user specifies if the argument is of type:
** [CL_IN]: argument is an input to the function.
** [C_inout]: argument is an input to the function and the function is expected to fill it up and pass it back to the caller.
** [out]: the function is expected to fill the argument and pass it back to the caller.
Since an inout or an out type of argument is supposed to be passed back to the user, it must always have the pointer attribute set to true.

====XDR marshalling and unmarshalling====

The IDL uses XDR to store data into a message. This is called marshalling of data. The reverse process i.e. Of retrieving data from the message into the native format is called unmarshalling of data. XDR stands for eXternal Data Representation Standard (described in RFC 1832). It is a means of storing data in a machine independent format. We will look at relevant sections of XDR in this section.

Data structures:
IDL recognizes the following data structures:
* ClInt8T
* ClUint8T
* ClInt16T
* ClUint16T
* ClInt32T
* ClUint32T
* ClInt64T
* ClUint64T
* ClNameT
* ClVersionT
* struct formed from other data structures
* union formed from other data structures
* enum

All data structures map to respective C structures except for 'union'.
In XDR, we need to know which member in a union is valid since it needs to be marshalled/unmarshalled. Therefore a union is implemented as a structure which aggregates the respective C-style union and a member called discriminant which takes appropriate values for every member of the C-style union.

=====Marshalling=====

In all of the marshalling algorithms, the message is written to only if non-zero. The message should be 0 if the veriable under consideration needs to be deleted. All data is converted to network byte order before writing to message.

=====Unmarshalling=====

In all of the unmarshalling algorithms, the message should always be non-zero. All data is converted to host order before reading from a message.

====IDL Stubs====

The IDL generates the following for every function installed in the EO interface:
* sync client stub
* async client stub
* server stub
* async callback

In addition, it generates 2 functions to install and uninstall the server functions into the EO.

A client function is defined by it's arguments.

'''Arguments'''
Arguments or parameters are marshalled into a message which are passed to the server functions and vice versa. Therefore it is necessary to understand what type of arguments can be available and how the marshalling/unmashalling can be done. There are 2 orthogonal classifications of arguments.

Classification based on direction of transfer:
* CL_IN - these are provided as an input to a function. In our case, they are sent to the server through input message
* CL_OUT - these are used to return results to the caller. In our case, these parameters are sent from the server to the client in the output message
* CL_INOUT - these act as both input as well as output arguments. Consequently in our case, they are sent in both directions.As of now we are not handling inout variables.

Classification based on passing:
* By value - these are passed as a copy. The original variables are not modifiable.
* By reference - these are passed as address. Therefore the original variables are modifiable. Since IDL marshalls/unmarshalls the These are further categorized as:
** without count - when pointers are passed without count, they are assumed to point to a single element
** with count - when a reference is passed with a count variable (an input basic type parameter), the count variable is assumed to contain the number of elements being pointed to.

Thus an argument can be classified into one of the following categories:
* CL_IN, by value (CL_OUT type parameters return results to the callee, they always need to be passed by reference)
* CL_IN, by reference without count
* CL_IN, by reference with count
* CL_OUT, by reference without count
* CL_OUT, by reference with count

=====IDL Sync Client Stub=====

The IDL sync client stub is generated from the EO definition provided in the xml file. A stub is generated for every function installed in the EO clients. The first argument of the stub is always the handle which contains the RMD parameters and it needs to be pre-initialized. For more information on the handle, please refer to the API guide.
It has the same signature as is specified in the xml file.

=====IDL Async Client Stub=====

Same as the sync stub except that the RMD call is asynchronous. Additional arguments are supplied for this - the callback to be invoked on successful invocation and also the cookie to be passed as an argument to the callback.

=====IDL Async Callback=====

This is the function that is called when an async call is made and the context from the server returns. It is similar to the part of sync client stub which is present after the sync RMD call returns.
This function is invoked from the RMD's context.

=====IDL Server Stub=====

The IDL server stub is invoked by RMD server library in response to a request from the client. This stub gets installed in the EO's client tables.
This stub does the reverse of the sync client stub. It extracts the in from the input message and calls the actual server function with these parameters. When the function returns, it packs the out parameters in a the output message and returns destroys the variables it created.

Doc:latest/sdkguide/manageability

2010-08-27T03:46:16Z

Senthilk:

=='''System Management'''==

OpenClovis SAFplus Platform provides a comprehensive platform and system management and component manageablity. It delivers a high degree of redundancy, delivering access to key services through highly-resilient traffic handling and system recovery mechanisms. The SAFplus Platform manageability infrastructure provides the capability for managing the resources in the system, reporting problems happening on those resource and provides infrastructure which can take customized action based on these problems.

Manageability comprises the following components:
* [[#Clovis Object Repository (COR)|Clovis Object Repository (COR)]]
* [[#Alarm Manager (AM)|Alarm Manager (AM)]]
* [[#Fault Manager (FM)|Fault Manager (FM)]]
* [[#Transaction Manager (TM) | Transaction Manager (TM)]]
* [[#Provisioning Library|Provisioning Library]]
* [[#Mediation Library|Mediation Library]]
* [[#Simple Network Management Protocol (SNMP)|Simple Network Management Protocol (SNMP)]]

[[File:SDK_SystemMngmtinSAFplus Platform.png|frame|center| '''System Management in SAFplus''' ]]

This chapter provides information about the various components of mangeability, concepts of managed objects, and using subagents for custom MIBs.

'''Key Topics:'''
* [[#Components of Manageability | Components of Manageability]]
* [[#Working with Clovis Object Repository (COR) | Working with Clovis Object Repository (COR)]]
* [[#Attributes of Managed Objects| Attributes of Managed Objects]]
* [[#Developing SNMP Subagent for Custom MIBs | Developing SNMP Subagent for Custom MIBs]]
* [[#SAFplus Platform Manageability End to End | SAFplus Platform Manageability End to End ]]

===OpenClovis Information Model===

OpenClovis Information Model is a hierarchical, object-oriented management information model that facilitates the abstraction of all physical and logical entities in a managed environment.

'''Key Topics:'''
* [[#Introduction to the OpenClovis Information Model | Introduction to the OpenClovis Information Model]]
* [[#Building an Information Model Using the OpenClovis IDE | Building an Information Model Using the OpenClovis IDE]]

For more information on Information Modeling, please refer to Distributed Management Task Force (DMTF) Common Information Model (CIM) available at http://www.dmtf.org.

====Introduction to the OpenClovis Information Model====

The OpenClovis Information Model is built on a generic framework that provides a unified view of hardware and software elements and the services provided by them. It helps you to define the interdependencies and relationships between the managed objects. It is a mechanism to capture the application models and integrate them with OpenClovis SAFplus Platform.

To manage any hardware or software entity, it must be represented as a Resource in the Information Model. Hardware entities include chassis, blade, interface port, logical port, logical connections such as ATM VPC, VLAN, and so on. Software entities includes software processes, operating system features or application protocols such as OSPF, SS7, and so on.

The OpenClovis IDE helps you to build your Information Model using UML notation. This is accomplished through its editors, namely the Resource Editor and the Component Editor. For more information please refer to ''OpenClovis IDE User Guide''.

The Information Model allows the definition of managed objects for an OpenClovis SAFplus-based system encapsulating chassis management, devices, alarms, faults, component states, and provisioned attributes of OpenClovis SAFplus Platform components and customer applications. The model provides support for SNMP MIB import as well as Object ID (OID) to Managed Object ID (MOID) mapping.

====Building an Information Model Using the OpenClovis IDE====

The OpenClovis IDE provides a graphical development environment for defining the SAFplus Platform model. Using the OpenClovis IDE you can design the model, generate/customize the code, and build the images for your target environment. Building the information model involves the following steps:
* Create a project using the OpenClovis IDE.
* Build the resource view in the Resource Editor.
* Define the hardware and software objects of the system and model them as Resources.
* Set the attributes for the resources.
* Create components to manage the resources using the Component Editor and then associate the components with the resources.
* Set the attributes for the components.
* Configure the build-time OpenClovis SAFplus Platform components and save the data as XML files.
* Generate the code representing the defined model.
* Compile the code.
* Create the binary deployment images.

You can compile and link the code to the OpenClovis SAFplus Platform libraries to build the platform software customized for the target application. To get started using the OpenClovis IDE and build a sample model see the ''OpenClovis Sample Application Tutorial.''

===Components of Manageability===

====Clovis Object Repository (COR)====

Clovis Object Repository (COR) is an in-memory, object-oriented distributed repository service enabled with system modeling constructs. It implements data management capabilities like meta-data management as well as data management. Meta-data is expressed as class creation, deletion, and attribute definitions.

Data management capabilities include object creation, deletion, query, indexing, and distribution. COR also provides ability to implement services associated data definition using transaction, recovery, and so on. COR provides the ability for class inheritance and containment.

The Clovis Object repository is updated in the active System Controller instance and an exact replica is maintained (synchronized) in the System Controller Standby to provide high availability. In addition COR provides persistence storage of the repository to provide HA across restart scenarios. It routes the management stations requests to the user component or the object implementer for updating the component managing the hardware or the software resource. The COR supports transient attribute. An object implementer keeps track of the latest value of this attribute. Any get operation from the north bound on this attribute will be routed to the primary OI and latest value will be returned.

====Alarm Manager (AM)====

The OpenClovis Alarm Manager (AM) provides an infrastructure for configuring and handling alarms. It provides support for alarm soaking, masking, alarm hierarchies, and correlation of the alarms before publishing. It stores the information for all the alarm being published untill it is cleared. The alarm client library attached to the component which is managing the alarm resource always sends the request to the alarm manager running on the local node for the processing.

It provides the functionality of reporting the alarm from the south bound entity. It publishes events for all the alarms reported or cleared, so somebody interested in this can register for this subscription.

====Fault Manager (FM)====

The OpenClovis Fault Manager (FM) infrastructure provides a hierarchical scheme for managing faults in a system and initiating actions as configured during the design time. It can handle various user-defined run-time faults, including hardware and software faults and can prioritize faults to ensure that the critical faults are addressed before the normal or the low-priority faults.

The alarms are notified by the Fault Manager client library to the Fault Manager server located on the same node. The actions to be taken on receiving a fault are controlled by the FM policy associated with the faults.

====Transaction Manager (TM)====

The OpenClovis Transaction Manager (TM) is an infrastructure service for providing the 2-phase commit transaction semantics. Along with this it provides two libraries the client library and the agent library. The client library is used to submit the transaction jobs and also the information about all the participating components. Any component that wishes to be a part of transactions can link with the agent library and act as a resource manager.

'''Features'''

* Supports re-startable transactions. For instance, if the Transaction Manager dies, all the pending transactions will be restarted when it is coming up again.

'''How it works'''

It tracks the participants and provides ACID semantics to ensure that all the participants are updated properly, or will rollback to previous state assuring data integrity despite component failures.

====Provisioning Library====

The OpenClovis Provisioning Library manages all aspects of the various hardware and software resources on the system.

Provisioning Library:
* Is a client module that is automatically bound to every component that manages a hardware resource or a software resource.
* It keeps track of all the resources being managed which are modeled to be owned by the component. It also keep account for all the runtime creation or deletion of the resource to be managed.
* Propagates the attributes to the corresponding hardware resource, when it is set from the North bound.
* Fetches the value of the runtime attributes from the component when a get operation is done on it from the North bound.

====Mediation Library====

The OpenClovis Mediation Library acts like a gateway to the OpenClovis SAFplus Platform runtime environment on the system controller. It interacts with external management agents like SNMP, CLI, and OpenClovis SAFplus Platform components.

The Mediation Library helps in translating the service requests from the management station into requests pertaining to OpenClovis SAFplus Platform runtime environment. The extensible plug-in architecture of Mediation Library allows the external management agents to control the configuration and operation of the various managed objects within the system.

====Simple Network Management Protocol (SNMP)====

The OpenClovis Simple Network Management Protocol (SNMP) sub-agent provides the flexibility to manage both platform and non-platform hardware, OpenClovis Information Model, and the alarms present in the system. Using SNMP, you can manage the attributes of an MO that includes a get, set, or notification.

===Working with Clovis Object Repository (COR)===

This section provides information about the value addition that COR provides to an application, and outlines the concepts of managed objects, their related databases, and classes. The following topics are discussed in this section:
* [[#Terms and Definitions | Terms and Definitions]]
* [[#COR: Value-Addition to an Application | COR: Value-Addition to an Application]]
* [[#OpenClovis Information Model | OpenClovis Information Model]]
* [[#COR Architecture | COR Architecture]]
* [[#COR Functionality | COR Functionality]]

====Terms and Definitions====

'''Class''' - An individual entity with attributes.
 '''MO''' - Managed Object provides an abstraction for the manageable properties of a resource in the system. MOs have attributes, support management operations, exhibit behavior and send notifications. Operations on an MO can be Create or Delete Instances; Get or Modify attributes; Action. Notifications emitted by an MO instance are instances that are created/deleted; report attribute change; class specific notification such as alarms.
 '''MO Class''' - Specifies the containment relationship between classes. For example: chassis/gigeblade/gigeport.
 '''MO Class Tree''' - Hierarchical representation of the containment relationship between MO classes.
 '''MOId''' - Unique Identifier of an instance of MO class. It is a hierarchical containment of a resource. MOs have these unique MOIds associated with them within the system. MOIds can be used as the address for MOs. For example: Chassis 0/Gigeblade 1/ Gigeport 2.
 '''MO Instance''' - Instantiation of MO class. For example, Gigeport 3 is an instance of Gigeport class.
 '''MO Instance Tree''' - Collection of MO instances with containment relationship specified. For example, in a chassis based system, an instance of a port could be: Chassis (0)/Blade (3)/Port (2).
 '''MSO''' - Encapsulates the attributes of a Managed Object specific to the particular service they are associated with. (For example, Alarm severity is an attribute related to the alarm service; it is a part of the Alarm MSO associated with any MO desiring an alarm service).

====COR: Value-Addition to an Application====

Almost every telecommunication or data communication system has a managed object database, which captures data pertaining to the system as captured in the information model. Following are the different features provided by COR:
* '''Creation of classes -''' A class is a blueprint of an object. It defines the different attributes of an object. COR provides a capability to inherit one class from another. The inherited class inherits all the attributes of parent class.
* '''Definition of attributes in a class -''' A class when created is an empty class, meaning that it does not contain any attributes other than those defined for the parent. COR supports addition of attributes into classes through APIs.
* '''Creation of MO classes -''' The MO classes when created, defines hierarchy (invariably a physical containment hierarchy) between different classes. The MO class hierarchy is blueprint of Object Tree. This is one way by which a Telecommunication Equipment Vendor enforces a hierarchy in which object can be created by system developer.
* '''Creation and deletion of Objects -''' The Objects can be created in a hierarchical fashion as per blueprint defined by MO class tree. COR provides ability to create/delete objects.
* '''Set and Get operation support -'''The values of the attributes which were modeled as part of the managed resource class can be changed at runtime using set operation after objects of these managed object are created. The latest values of these attributes can be fetched from COR using the get operations. Both these operations support single and bulk semantics.
* '''Object Tree Walk -'''The object tree can be navigated using the features provided in the COR. This walk can be restricted to a particular subtree starting from a defined root.
* '''Distribution of COR repository''' - The COR repository are replicated on the two system controller cards. Exact replica of runtime data and metadata is maintained on both the cards. In case of failure of one card, the data can be obtained from another card.
* '''Transaction Support''' - COR provides an ability to invoke the Managed Service Providers when a data managed by the Object implementer is changed. This is done through transaction mechanism. The transaction mechanism also ensures atomicity and consistency of an operation. A transaction is started for object creation/deletion and attribute set operation started by a user.
* '''Notification Support''' - COR provides support for subscription of notification after completion of transaction. A notification is published for object creation/deletion as well as for setting an attribute of an object.

The following diagram depicts the relationship between COR classes, MO classes, and COR objects:
[[File:SDK_ClassesMOClassesObjects.png|frame|center| '''Classes, MO Classes, and Objects''' ]]

The object creation is performed in three steps. The first two steps are hidden from the user as the information model created using IDE is read by COR at the startup. All the defined classes and MO class tree will be created during this time. The object creation will start only after these two steps are done. A brief description of these three steps is as follows:
# '''Create COR class''' - The COR class is created and attributes are added to it. The class represents a resource in a system.
# '''Create MO classes''' - MO classes are nothing but COR classes arranged in hierarchy. These first two steps define model of a system. These first two steps are performed by COR as a part of Information Model development. A COR class defined in the first step above can be used for multiple MO classes, for example STS1 class can be used for Sonet STS1 as well as DS3 STS1. You need not define a separate COR class for them since attributes of both the STS1 MO classes are the same. An MO class is identified by MO class path which in a string format appears as follows: \chassisMO\SonetBladeMO\SonetPortMO for a sonet port.
# '''Create objects''' - Objects are created when the system starts running (either during boot-up or dynamically, by the System Developer using a management agent (such as SNMP/TL1 CLI). The objects can be created only according to the blueprint defined in steps 1 and 2 above. For example, the system developer can not create DS3 port under a Sonet card since it is not according to the blueprint.

====COR and OpenClovis Information Model====

This section describes the OpenClovis Information Model and how COR is used to capture the Information Model. The following section describes a two-step approach towards defining the OpenClovis information model:
# Metamodel Definition - Metamodel is a language for specifying an information model. It is the responsibility of OpenClovis SAFplus Platform to define metamodel.
# Defining System Model - Using the defined metamodel, the systems vendors define an information model.

=====Metamodel Definition=====

A metamodel defines language for specifying an information model. The following section describes OpenClovis SAFplus Platform's Metamodel and defines different metaobjects used in the metamodel. Example of different metaobjects used in metamodel are class, attributes, relationships, and so on.

The following UML diagram captures OpenClovis SAFplus Platform's metamodel:
[[File:SDK_SAFplus Platform'sMetaModel.png|frame|center| '''OpenClovis SAFplus Platform's Metamodel''' ]]

The left hand side model, as demarcated by blue line, represents the physical view or management view of the system. The right hand side of the model represents logical view. The physical view defines attributes for hardware and software resources contained in the system and the logical view defines metaclasses.

All the metaclasses below the red line are base classes. These classes will not change as we go forward. The classes above red line are specialization of the base classes defined below the red line.

Different relationships exist between metaclasses defined in both the physical view and logical view. These relationships are defined using standard UML notations.

'''Example:''' Defining System Model

Figure [[#Instance of OpenClovis SAFplus Platform's Metamodel | Instance of OpenClovis SAFplus Platform's Metamodel]] illustrates an example for OpenClovis SAFplus Platform's Metamodel.
[[File:SDK_InstanceofSAFplus Platform'sMetaModel.png|frame|center| '''Instance of OpenClovis SAFplus Platform's Metamodel''' ]]

The data present in the information model is captured in COR. The output of information model is captured as user configuration. The information model translates in the COR MO class tree. In the information model as defined above two COR MO class trees shall be generated, one for resources and other for classes. The classes can be captured in the table format. COR provides utility functions to read the table and create COR classes as well as MO classes from it.

====COR Architecture====

COR runs on two redundant system controller cards. This section talks about the network model for COR and provides details of COR subcomponents. Figure [[#COR Network Model | COR Network Model]] illustrates the COR network model:
[[File:SDK_CORNetworkModel.png|frame|center| '''COR Network Model''' ]]

Although distributed databases are complex as opposed to centralized databases, they provide some very important advantages, if implemented, such as:
* '''Performance''' - A proper distribution criterion can ensure that the data is close to the location where it is frequently accessed from.
* '''High Availability of Data''' - In distributed database, cache of an object can be maintained at multiple locations, making the data available in spite of failure of a location.

COR provides High Availability of data by means of making a replica of it on two redundant controller cards.

====COR Functionality====
COR provides the following functionalities:
# MO Class Creation.
# MO Instance Tree creation and Navigation
# Atomic Object Manipulation
# Notification Services
# Object Ownership Services

 '''MO Class Tree Navigation''': Given a class, assigns an API.
 '''Atomic Object Manipulation''': Provides APIs to create multiple objects. Either the operation suceeds or fails. Manipulation includes creation / deletion / modification. For example: In an output, multiple objects can be specified to be created. COR ensures that either all are created or deleted.
Ownership provides component to be owner of an object. An owner of an object participates in the object manipulation operation. The owner provides the three functions:
 '''Validate''': Output is validated by the object owner. If the validation fails, object manipulation on the whole fails.
 '''Rollback''': If validation fails, the object owner needs to roll back its state information.
 '''Commit''': The object owner accepts the creation only if Y is provided in the validate phase. For example: If MTU size of Gigeport is set, then the object owner of gigeport will set the MTU size in the gigeport hardware during the Commit phase.
 '''Notification''': After COR issues notification, this notification is subscribed by components.

====Node Independent Managed Objects====

In a distributed communication system, multiple applications running across multiple nodes can share MOs. Such MOs are not specifically bound to any blade or a node. They are owned by one application but the application is implemented by a pair of ACTIVE and STANDBY SUs and their software components running on different nodes. The MO can be accessed from the north-bound interface irrespective of the location of its owner application. In case of failover, the STANDBY registers the MO without affecting the north-bound interface.

OpenClovis IDE enables you to define MOs in OpenClovis MIB that are not related to any physical entity in the system. These MOs reside in a logical hierarchy tree attached directly to the root MO. For example, two gigE ports are defined in the Resource Editor of IDE with 1+1 redundancy model. These ports are associated with same OI as they collectively provide the gigE service that contains its own MO. This is a logical MO and is blade independent. The configuration of this MO is applied to both the ports.

===Attributes of Managed Objects===

Clovis Object Registry (COR) is a repository of Managed Objects representing the network element resources in a system. COR provides functions that enable read operation on the Managed Objects. These functions are used to access the values of the attributes of an object known by its MoID. Once an application discovers the object hierarchy, it can use this interface to retrieve the attribute values.

'''Definitions'''

* '''Management Station ''': This is used to view the current status of the managed entity or change its state. This can be any management process for example it can be a SNMP MIB browser, a CLI, web-based application etc.
* '''The Object Implementer (OI)''': It is a software component which owns the managed resource. There can be multiple OIs for a managed object but out of all of them there can be only one OI which will act as a primary OI. The get request from the management stations lands in the COR and then it contacts the OI(s) of a managed resource. The primary OI holds the latest value of a runtime attribute. For the configuration attribute there are corresponding attributes present at all the OIs. So when any set request is send by north bound, all the OIs are contacted to update their corresponding attribute.
* There are two types of attributes that can be part of a managed resource, one is called configuration and other is runtime or transient attribute. There are certain properties of these attributes called as attribute-flag which are as follows:
** '''Cached''' - The attribute which is stored in COR. The latest value of cached attribute is always obtained from COR.
** '''Persistent''' - This property of the attribute gives that the attribute value should be stored in a presistent Db file and should be restored in case of restart. Only a cached attribute can be persistent.
** '''Writable''' - An attribute which can be changed at runtime is called writable. This shows that it can be settable from the north bound. A initialized attribute is always non-writable.
** '''Initialized''' - A key attribute of a class has this property. This attribute is for example a index attribute which can be used to identify a row in a snmp table. The value of this attribute should be supplied while creating the object of this class. These attributes are non-writable at runtime.

====Types of Attributes====

The different types of attributes of an object are:
<ul>
<li>'''Configuration Attribute''' - A configuration attribute is used to store the configuration information about the managed resource. For example the maximum memory size can be a configuration attribute of a process resource. These attributes are always cached and persistent. These attribute are always writable to the north bound unless it is marked as initialized, as a initialized or a key attribute should not be modified at runtime.
<li>'''Runtime Attribute''' - This attribute is the property of the managed resource that keeps changing so only the primary object implementer (OI) of this resource manages its latest value. For example - If a component is managing a process running in the system, then information about the current memory used by a process is known only to the component. These attributes are not writable from management station. There is a slight variation of the runtime attribute when it is very slow changing for example - The number of days a process has run. These kind of attributes can be cached in the COR. Whenever it changes, the primary OI can set this attribute. So a runtime attribute is cached or non-cached in COR based on its nature. It can be persistent only when it is cached.
 
[[File:OpenClovis_Note.png]]The runtime cached attribute is writable only from the primary OI. It is non-writable to the north bound agent.
</ul>

A managed resource can contain both configuration attribute and runtime attribute based on the requirement. The configuration attribute will be used to store the configuration information. The runtime attribute is the transient property of the managed resource. Normally its value is maintained by the primary OI. But if it is a very slow changing one, it should be stored in COR which is updated time to time in COR by the primary OI.

====Implementation of Configuration and Runtime Attributes====

For example, COR has objects for every process running in the system. Each process has various attributes associated with it, such as name, process Id, memory usage, maximum memory size, maximum number of open files and so on. Whenever a process starts, COR creates an object of type process with specific attributes. The objects represented in COR are identified by their MoID. You must specify the MoID of an object to perform get and set operations it. When a user queries for a list of all the processes running in the system, COR returns the MoIDs for them based on the number of instances of process managed resources created. The northbound interface creates a table with the MoIDs of all the process.

Now suppose multiple processes are running on a node. Each process occupies some memory that changes during runtime. These processes are treated as managed resources in COR. The management stations can monitor these processes and send requests to know the memory usage of every process at a given time. Since the memory occupied by these processes varies at runtime, this data should not be stored in COR. This attribute is a candidate of being a runtime attribute of the process MO class.

If a transient property of the managed resource changes very slowly then that attribute can be cached in COR. For example the number of hours a process has run. If needed this attribute can also be persistent in COR. The primary OI of the managed resource has to update its value in COR whenever it changes.

The configuration attribute is the placeholder for the configuration information of the managed object. It is always cached in COR. It can be persistent in COR if required. For example, If the component wants to manage a process running in a system which has an attribute which gives the maximum number of open files it can have, then it can be made as a configuration attribute for the process managed resource.

====Importance of OI for attribute types====

A managed object can contain both configuration and runtime attributes. A managed object is managed by the object implementer. These are hidden from the management station. Whenever a request is sent from the north bound interface of a management station, the COR takes care of routing the request to the respective OI(s) of the managed object.

The Object Implementer will be involved while doing get operation on a runtime attribute or while performing a set operation on a configuration attribute.

When a read operation is done on a runtime or transient attribute, a particular OI is contacted to get the value of the attribute. The OI that provides the runtime value of an attribute is the primary OI.

For example in a 2N Redundancy model, one process acts as the ACTIVE and the other as the STANDBY. When you perform a get operation, since the ACTIVE process provides the requested value, so it is the primary OI.

For a configuration attribute of a managed resource in COR, there is a corresponding attribute present in the OI. For any set operation, all the OIs should be contacted inorder to facilitate the modification of their attribute. The request from the north bound first land in COR. It takes care of routing these requests to all the OIs where they can update the respective data bases. Also this set operation updates the value of configuration attribute in COR. So it always has the latest value of a configuration attribute.

The user can specify a particular OI to act as the Primary OI for a managed resource. Setting a OI as the Primary OI involves some restrictions. Please refer the documentation of the API clCorPrimaryOISet in the API reference guide for more information.

====Retrieving Values of Attributes====

The COR provides the mechanism to get the value of the multiple runtime and configuration attributes in one request. This can be done using the bundle get feature of COR.

You can retrieve the value of a runtime attribute of an object at a given time in order to know the value of the transient state of the managed resource. For example, to know the memory usage of a process, you must communicate with the process that implements the object (OI).

A runtime attribute can be stored at the OI if its frequency of change is high. In this case the Primary Object Implementer (OI) is a process that is responsible for providing the value of non-cached runtime attributes. When you query for memory usage of a process, COR communicates with its primary OI to retrieve the information as shown in Figure [[#Accessing MO Attributes | Accessing MO Attributes]]. Depending on the frequency of update, the information returned can contains an earlier value.

 [[File:OpenClovis_Note.png]]Only one Primary OI exists for a particular object in the system.
[[File:SDK_AccessingMOAttributes.png|frame|center|'''Accessing MO Attributes''']]

In the other case, if the frequency of change for a runtime attribute is very low, then it can be cached in COR. So COR itself can provide its latest value in the case of a get operation. The primary OI has to set the latest value of this attribute in COR whenever it is changing.

The COR always stores the latest value of the configuration attribute. So in case of a get operation on this attribute, the COR gives its value.

====Setting Values of Attributes====

You can set the values of configuration attributes from the northbound interface. SAFplus Platform provides an efficient way of performing and managing set operations on a large number of attributes. The set on the runtime attribute is not allowed from the north bound.

Similarly, you can set the values of a common attribute that is shared among multiple processes running in the system, for example the max limit of memory of all processes. A common attribute is not contained in a particular object but is centralized in one object only. Such attributes are shared by all the process running in the system.

When you modify a configuration attribute of a shared managed resource, all the OIs associated with the process are invoked where they can do the respective changes to their attribute. For example : if the configuration attribute corresponding to the maximum limit of memory in the "process" managed resource is changed and if it is being managed by multiple Object implementers, then COR will route the request to each of the OI where they can change the corresponding parameter for the process they are managing.

[[File:OpenClovis_Note.png]]When a set operation is performed on more than one process simultaneously, multiple OIs are invoked whereas in a get operation, only one OI is invoked.

====Storing Values of Attributes====

The management station that send requests from the northbound interface are unaware of the OI. It communicates with COR to retrieve any information. If the attribute is configured as cached, the information is contained within the object. If the attribute is configured as persistent, the information is stored in a file system or a permanent storage disk. The persistent attributes are always cached.

By default, the transient attributes are neither cached nor persistent, since COR does not contain its values. But it can be configured as cached if its value does not change frequently. The OI updates COR only when the value changes to reduce network traffic. If the runtime attribute is cached, the value of the attribute is saved in COR since it changes only periodically. For example, you want to know for how many hours a process is run. So, the information is updated once in every hour. If the cached runtime attribute is not persistent, COR does not save the data.

The configuration attributes are always cached in COR. These attributes are always persistent.

====Raising Alarms====

You can configure the process and get the value of runtime attributes from the northbound interface. A process can have its memory limits as high, medium and low. When the memory of a process exceeds its max limit, you can configure your application to raise alarms. An alarm is a communication medium from the OI to the northbound if an unexpected behavior is observed or a fault condition occurs. Currently, the northbound is a "pull" model as it is not informed about any value unless it sends a get request.

====Types of Process Classes====

The following are the two types of process classes:
* provClass
* alarmClass

You must specify the service Id to access a process class. You can define the service Id of a class to assign it as either a provClass or an alarmClass type. The provClass contains both configuration and runtime attributes.

A node can have multiple process classes running on it. These classes contain various attributes. The hierarchy from the node to the attribute is represented by a MO class path. A process running in a system is uniquely identified by its MoId, that is, <code><node_name>.<node_instance>/<process_name>.<process_instance></code>.

You must specify the MoID of the object from the northbound interface to communicate with COR and retrieve or modify its value. The northbound interface is exposed to different management stations such as CLI, SNMP, XML and so on. The requests from the northbound interface are passed through a Mediation Layer before it reaches COR. The Mediation Layer translates the requests sent through the MIB table from the northbound interface into COR understandable format as shown in Figure [[#Accessing MO Attributes | Accessing MO Attributes]].

To access a particular attribute, you must specify the MoId, the ServiceId and the attributeId. Generally, the configuration from the northbound interface is performed as a bulk operation. When a set operation is performed, OI communicates with the COR. You can provide a transactionId to apply all the configuration changes in bulk and save them in COR in one transaction. This reduces the frequency of communication between COR Server running on the System Controller node and COR client running on worker blades.

For example, you want to change an attribute, such as the max memory limit of all the processes running on a node. An attribute can be in the form of an array and can be updated after a certain index. If a get is performed on the transients attribute, and the primary OI is not available for a few attributes, it returns only those attributes that are associated with Primary OI.

For example, an object contains memory configuration of all the processes running on a node. When a process is started, it reads the object in COR and applies its respective configuration. So every process knows the objects that it belongs to and becomes the OI of that object.

===Provisioning OI Callbacks===

This section will describe the flow of OI callbacks which will get called whenever the managed resources are modified in COR and also during OI initialization if the resources are already present in COR.

====Flow of OI callbacks when the resource is modified in COR====

When the resource managed by a OI is modified in COR, a transaction is getting initiated and all the OIs managing that resource will be involved in the transaction. The diagrams will show the flow by which the OI's callbacks will get called.

=====Flow Diagrams=====

These diagrams will show the flow for the following cases :

*'''Case 1 :''' If the transaction contains CREATE jobs.
*'''Case 2 :''' If the transaction contains multiple SET jobs for different MOs.
*'''Case 3 :''' If the transaction contains DELETE jobs.
*'''Case 4 :''' If the transaction contains READ jobs.

'''CASE 1 :''' The Transaction contains CREATE jobs.

[[File: ProvCallbacksFig_1_1.png|frame|center|'''Transaction which contains CREATE jobs''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> ROLLBACK -> TXN END

[[File: ProvCallbacksFig_1_2.png|frame|center|'''Flow of OI callbacks for ROLLBACK for CASE 1''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> UPDATE -> TXN END

[[File: ProvCallbacksFig_1_3.png|frame|center|'''Flow of OI callbacks for UPDATE for CASE 1''']]

'''CASE 2 :''' Transaction contains multiple SETs for different MOs.

[[File: ProvCallbacksFig_2_1.png|frame|center|'''Transaction which contains SET jobs for different MOs''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> ROLLBACK -> TXN END

[[File: ProvCallbacksFig_2_2.png|frame|center|'''Flow of OI callbacks for ROLLBACK for CASE 2''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> UPDATE -> TXN END

[[File: ProvCallbacksFig_2_3.png|frame|center|'''Flow of OI callbacks for UPDATE for CASE 2''']]

'''CASE 3 :''' Transaction contains a DELETE jobs.

[[File: ProvCallbacksFig_3_1.png|frame|center|'''Transaction which contains DELETE jobs''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> ROLLBACK -> TXN END

[[File: ProvCallbacksFig_3_2.png|frame|center|'''Flow of OI callbacks for ROLLBACK for CASE 3''']]

'''Txn Cycle :''' TXN START -> VALIDATE -> UPDATE -> TXN END

[[File: ProvCallbacksFig_3_3.png|frame|center|'''Flow of OI callbacks for UPDATE for CASE 3''']]

'''CASE 4 :''' Transaction contains READ jobs for a MO

[[File: ProvCallbacksFig_4_1.png|frame|center|'''Transaction which contains READ jobs for a MO''']]

'''Txn Phase :''' READ

[[File: ProvCallbacksFig_4_2.png|frame|center|'''Flow of OI callbacks for READ for CASE 4''']]

====Flow of OI callbacks when it is coming up====

Pre-provisioning is done when the application is coming up. Prov will read the MOs in COR for which the application is interested and call the application's callbacks, so that it can know the current values of the Objects in COR.

The below diagrams will show the flow by which the application's callbacks will be called during pre-provisioning.

For example if there are two objects \A:0 and \B:0 present in COR which contains the following attributes.

[[File: ProvCallbacksFig_5_1.png|frame|center|'''COR objects for which a OI is interested''']]

then the pre-provisioning will be done in the following manner.

=====Flow Diagram=====

[[File: ProvCallbacksFig_5_2.png|frame|center|'''Flow of OI callbacks during pre-provisioning''']]

===Developing SNMP Subagent for Custom MIBs===

A Management Information Base (MIB) is a type of database used to manage entities in a communications network. It comprises a collection of objects in a (virtual) database which are used to manage entities (such as routers and switches) in a network. A MIB defines the attributes/information of resources, but is only a schema of information. This schema is populated to create a custom MIB.

A SNMP subagent is a process that handles all set/get operations for the MIB. The subagent registers with the SNMP daemon to inform it that all operations for that MIB should be passed on to the subagent. Typically, a SNMP command would come from a monitoring or management station to the SNMP daemon. The daemon then passes on the command to the subagent. The subagent communicates to COR through a mediation library to set or retrieve the values in COR, and returns the result via the SNMP daemon.

With OpenClovis 3.0, the SNMP subagent can now be automatically generated. This section will walk you through the steps to configure and generate the subagent. The OpenClovis IDE is capable of fully generating an SNMP subagent from a MIB or set of MIBs.

====Importing a MIB====

From the menu, select '''Clovis -> Importing Mib Objects ...'''. Click on the '''Load''' button to browse to the location of your MIB file. Once the MIB has been loaded, click on the MIB entry in upper box, and its associated MIB objects will appear in the lower box.


[[File:SDK_SNMP_SelectMibs-fig1.png|frame|center| '''Selecting MIB Objects''']]

In the example shown in Figure [[#Selecting_MIB_Objects|Selecting MIB Objects]], DEMO-MIB has three different objects. One is a set of scalars, the other a table, and the last is a trap. Select the MIB objects you want to import into your model, and then click on the '''Import''' button.

If you are importing objects from multiple MIBs, load all the MIB files. Then for each MIB, you will need to select the MIB from the upper box, and highlight each MIB object from the lower box and import it.


[[File:SDK_SNMP_ResourceEditorWithMibObjects-fig2.png|frame|center| '''Resource Editor with MIB Objects''']]

When finished, you should see in the resource editor, something similar to Figure [[#Resource_Editor_with_MIB_Objects| Resource Editor with MIB Objects]]. You may have noted that three MIB objects were listed in the DEMO-MIB example, but only two are present in the resource editor. The third object was a trap, which gets imported as an alarm.

In the example shown, there is now an MO called demoStatusTable. In reality, this only represents one row of a table. To increase the maximum number of rows in the table, double click on the table. Under the '''Resource''' options, increase the number of '''Maximum Instances''' to match your needs. In this example shown in Figure below, there are a maximum of 10 rows.


[[File:SDK_SNMP_MaxInstances-fig3.png|frame|center| '''Select Maximum Instances''']]

====SNMP Traps====

As mentioned earlier, the trap was imported as an alarm. To adjust the type and severity of an imported alarm, from the menu select '''Clovis -> Alarm Profile ...'''. See Chapter ''Defining Alarm Profiles'' of the ''OpenClovis IDE User Guide'' for further information on the configuration of alarms.

When your alarm is appropriately configured, you can associate it with a resource. Double-click on the resource you wish to have this alarm. Under '''alarmManagement''', click on the '''Enable''' checkbox. Then under '''Associate Alarms''', highlight the alarm(s) and click on the '''Add''' button. See Figures [[#Alarm_Management|Alarm Management]] and [[#Associate_Alarms|Associate Alarms]].


[[File:SDK_SNMP_AlarmManagement-fig4.png|frame|center| '''Alarm Management''']]


[[File:SDK_SNMP_AlarmManagement-fig5.png|frame|center| '''Associate Alarms''']]

====Configuring the Subagent====

The SNMP subagent is a SA Aware Component. To configure a component to be a subagent, you need to do the following steps. First, double-click on the component to see the properties, and set '''Is SNMP Sub-Agent''' to '''true''' as shown in Figure [[#SNMP_Component_Properties|SNMP Component Properties]].


[[File:SDK_SNMP_SnmpComponentProperties-fig6.png|frame|center| '''SNMP Component Properties''']]

Next, right-click on the component and select '''Sub-Agent Properties''' from the pop up menu. Here there are two fields that need to be filled out. See Figure below.


[[File:SDK_SNMP_SubAgentProperties-fig7.png|frame|center| '''SubAgent Properties''']]

The first field will set SNMP's MIBDIRS environment variable necessary during the the subagent code generation. This is a colon ':' separated value containing all the directories to look for MIB files in. For this to work properly, you will need to make sure that net-snmp's <code>mibs</code> directory is included, which would be in your clovis installation directory. If you installed the Clovis software in the default location, it would be <code>/opt/clovis/buildtools/local/share/snmp/mibs</code>.

The second field would be the top level node name for your MIB. If you just have one MIB, this would be the MODULE-IDENTITY name in your MIB file. If you have several MIB files, it would be the MODULE-IDENTITY of the top layer in your MIB tree.

=== SAFplus Platform Manageability End to End===

The SAFplus Platform components which are used for providing the manageability infrastructure are as follows:
* Clovis Object Repository
* SNMP sub agent
* Mediation library
* Provisioning library
* Alarm Management
* Fault Management

This section describes about how these components interact to provide the resource management and fault reporting capability to the SAFplus Platform middleware.

==== North bound Requests ====
The management station requests - walk, set or get operations - are handled by the SAFplus Platform middleware using some of the above mentioned components. These operations can be done from the management station on one table or it can span multiple tables. Each table represent one managed entity in COR. The rows of the table maps to different instances of the resource. Each column of the table denotes different attributes of the resource. All this information are stored in COR. When the GET, SET or a WALK request reaches SNMP sub-agent, it is translated by the mediation library into a COR request and sent to it. This data is also cached in the sub-agent which is retrieved from COR based on the expiration of caching frequency time period.

The SET and GET operation can be done in a singular or a bulk manner. The bulk set operation is done using the transaction. The SET operation is validated with all the object implementers of the managed resource and only when all of them agrees to the change, then only it is updated otherwise the rollback is done on all of them. The Get operation can be done for configuration and transient attributes. For configuration information only COR is contacted but for transient attribute the primary OI is contacted to get its latest value.

The diagram below shows the SNMP request being processed by the SAFplus Platform. The request is first received by the SNMP sub-agent. This request is then translated into a COR based request by the mediation library and sent to it for processing. Based on the type of request, COR processes it locally or sends it to the Object implementers. If it is a SET request, COR sends the request to the Object implementers where provisioning library attached to it does the job of validating the request and then updating it on their end. If it is a GET request or WALK request on a transient attribute, it is sent to the Primary Object Implementer to get the latest value of this attribute. If it is a get request or a walk on a cached attribute, the COR will process it locally and send the response.
[[File:snmp-set-get-request.png|frame|center| '''SNMP SET/GET/WALK request processing in SAFplus''' ]]

==== Reporting failures in the system via alarms ====
The asynchronous events happening in the system are reported as alarms. These alarms can be modeled as traps in the MIB. This MIB cab be imported using IDE which will take care of configuring the alarms. So whenever these alarms occur in the system, they are reported as traps to the north bound interface.

All the alarms modeled in the system can be configured to be raised by some application using the IDE. So a component can be assigned the task of raising these alarms based on certain conditions. When these alarms are published, the mediation library along with the SNMP-subagent takes care of sending these configured alarms as traps to the north bound entity. The COR server stores the latest information about the alarm.

The diagram below shows the trap reporting feature of SAFplus Platform. A component with the alarm client library and having alarm configured through IDE, can raise the alarm. This component can run on any node. In the figure it is shown as a part of payload node. The SNMP sub-agent can be part of any node. In the diagram it is shown as part of controller node. Once the alarm is raised, the alarm server publishes the event. The mediation library attached to the SNMP sub-agent listens for this event. It verifies whether the alarm raised is configured to be raised as trap. If it is so, then it forwards the request to the SNMP sub-agent which takes care of reporting this alarm as trap to the north bound management station.

[[File:SDK_SendingTraps.png|frame|center| '''SNMP Trap reporting using SAFplus''' ]]

==== Fault reporting and repair action ====

The fault management feature of the manageability infrastructure allows the application to take customized action when the faults occur in the system. There are two kinds for fault handling supported by the Fault Manager which are described below.
*'''Fault Reporting'''
The fault reporting is done for non-service impacting alarms. The non-service impacting alarm are the one with severity less then major that is minor, warning and indeterminate. For each alarm category and severity combination, there are five escalation levels defined. For each escalation level there can be a callback associated and inside that user defined action can be taken. The fault manager calls the callback based on the category + severity + escalation level. The callback on the level one is called if the fault occur for the first time. The fault level is escalated, when the frequency of fault is more than the probation period. Both the callbacks and the probation period are configurable through IDE.
* '''Fault Repair'''
The fault repair can be done by the application which wants to trigger an action based on the service impacting problem happening on the managed resource. The managed resource on which repair action need to be done are modeled with an alarm MSO. Whenever a problem is detected on such resource, an alarm is reported to the alarm server. The alarm handle obtained after alarm raised or the alarm handle obtained in the alarm event delivery is used in the repair action. This is necessary as fault repair action is done only on the service impacting alarms. The fault manager on receiving the repair action request calls the callback assigned to the resource. This callback function is generated by the IDE for every resource having alarm MSO.

The figure shows the fault reporting and repair action feature of the SAFplus Platform. Whenever an alarm is raised in the system, the Alarm Server decides whether it should be reported as fault or not. Only the non-service impacting alarms are reported as fault. So for all these alarms, it contacts Fault Manager which takes care of calling the registered callbacks. The figure also describes the fault repair actions feature. The component doing the repair action should have the alarm handle corresponding the alarm raised. The alarm repair action should be done for service impacting alarms. So a component raising this alarm or listening for the alarm events, can trigger the repair action. In the diagram the "Fault Mgmt App" shows as alarm reporter as well alarm listener. There can be two different applications doing this job. So a component doing fault repair action can be the one which reports the alarm or the one which listens for the alarm notifications.

[[File:SDK_FaultReporting.png|frame|center| '''Fault handling using SAFplus''' ]]

Doc:latest/sdkguide/highavailability

2010-08-27T03:44:26Z

Senthilk:

=='''High Availability'''==

High Availability (HA) is used when referring to a system that is capable of providing service "most of the time."
High availability can be achieved by combining many different design concepts and system characteristics, including hardware and software level redundancy, fault detection capabilities, component failover, fault isolation, fault recovery, alarm notification, and so on. This chapter provides a short introduction to the key concepts, and presents the relevant features and services of ''OpenClovis SAFplus''.

'''Key Topics:'''
* [[#HA Concepts, Terms, and Definitions | HA Concepts, Terms, and Definitions]]
* [[#SAFplus Platform Features for High Availability | SAFplus Platform Features for High Availability]]
* [[#Availability Management Framework (AMF) | Availability Management Framework (AMF)]]
* [[#Fault Detection and Handling | Fault Detection and Handling]]
* [[#Checkpointing Service (CPS) | Checkpointing Service (CPS)]]
* [[#Group Membership Service (GMS) | Group Membership Service (GMS)]]
* [[#Typical Usage of High Availability | Typical Usage of High Availability]]

===HA Concepts, Terms, and Definitions===

Availability is a measure of the probability that a service is available for use at any given instant. It allows service failure, with the assumption that the service restoration is imminent. The key to high availability is to continue the service without significant interruption.

The quantitative definition of ''availability'' is:

Availability = MBTF/(MBTF+MTTR)= 0.9xxx

where MTBF is the mean time between failures, and MTTR is the mean time to repair. In layman terms, <code>Availability</code> is simply the percentage uptime of the system, that is, the percentage of time the system is providing the given service. As this number is typically always below but very close to 1.0 in a highly available system (e.g., 0.999), it is often expressed in terms of "N-nines". The table below illustrates the downtime of systems with various "N-nines".



{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Availability and Downtime '''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c" width="250"| Availability
!style="color:#66b154; background:#09477c"| Downtime
|- style="color:#ffffff; background:#549cc6"
|
two-nines (99%)
|
~3.7 days/year (~14 min/day)
|- style="color:#ffffff; background:#549cc6"
|
three-nines (99.9%)
|
~ 8.75 hr/year
|- style="color:#ffffff; background:#549cc6"
|
four nines (99.99%)
|
~ 1 hr/year
|- style="color:#ffffff; background:#549cc6"
|
five nines (99.999%)
|
~ 5.25 min/year
|}

The five key system characteristics contributing to HA are:
* '''Failure detection''': how reliably and quickly can failure be detected
* '''Failure notification''': how reliably and quickly can the information of the failure be passed to an authority that can decide how to handle the failure
* '''Response time''': how long it takes for the failure handling authority to process the information about the failure and come to a decision on how to best handle the failure
* '''Repair/replacement time''': how long it takes to repair or replace the failed component
* '''Recovery/restart/reboot time''': how long it takes to restore the original system state and hence restore the service.

Each of the above five system characteristics directly contribute to the downtime after a failure, and hence to the ''availability'' of the system. However, a few design concepts can greatly reduce many of these times and even eliminate the affect of some. These are:

* '''Redundant components with failover capabilities''': In a system where the same service can be provided by two or more identical redundant components, the service can be quickly recovered before the failed component is actually repaired or restarted, by switching the service over to a healthy component. This effectively eliminates the repair/replacement time from contributing to the ''availability''. It replaces with a new characteristics, however: the '''failover time'''. Redundancy can be provided at various levels:
** Hardware (e.g., redundant hardware elements in an AdvancedTCA chassis
** Software (e.g., standby software components)
* '''Automated failure detection, response, and reconfiguration''' By fully automating the entire event flow from fault detection to recovery (and thereby excluding human intervention from the picture), the remaining four factors can be greatly reduced. In modern systems, such as built on OpenClovis SAFplus Platform, the service can be recovered by means of component failover within tens of milliseconds from the time the failure occurred.

OpenClovis SAFplus Platform provides infrastructure for the end-to-end life-cycle of failure handling, including failure detection, to policy-based recovery decision making, through failover and fault repair operations. However, for custom software applications to be able to quickly fail over without major disturbance to the rest of the system, the applications themselves need to exhibit some special characteristics. These include:
* capability to move state data and context among redundant components
* move the service from one component to another in a way that the failover is transparent to the rest of the system

In addition to the above mentioned end-to-end failure handling, OpenClovis SAFplus Platform provides additional services to allow application programmers to implement the above characteristics. These include checkpoint service (to save, pass, and restore system state) and location-transparent addressing (to hide the failover from other components).

Redundant components providing the same service can be arranged in many relationships. The most common arrangements are:
* 2N (1+1) redundancy: for every active component there is exactly one standby component
* M+N redundancy: for every M active components there are N standby components, any of which is ready to take over the service from any of the active components. (Note that 1+1 is merely a special, but most common, case of M+N.)
Additional models, such as N-Way and N-Way-Active, are also often used. See a more authoritative description in the ''Application Interface Specification (AIS)'' from the SA Forum.

Before describing the individual models it may be useful to describe the SA Forum HA model and its associated terminology.

[[File:SDK_SAF_HA_Model.png|center|frame|'''SA Forum HA Model''']]

The SAF concepts introduced in the figure can be explained as follows:

* '''Component''': It is the smallest logical entity on which AMF performs error detection, isolation, recovery, and repair. A component is a single process or multiple processes that AMF manages based on its configured attributes. A component is further classified depending on whether it is an SA-aware or a non SA-aware, whether it is pre-instantiable or not and whether it is a proxy for other components or can be proxied by other components. A component is a hardware or a software entity or a combination of both. A hardware component is a blade, a standalone PC, a PMC or any entity that can be considered as one distinct unit for the purpose of error isolation, recovery and repair. A software component is realized as a process, a thread, or a collection of processes. Hardware entities are typically viewed as either non-preinstantiable, non-proxied components or proxied components. They are not directly controlled by the HA infrastructure. All interactions with them must go through a software proxy component, which can be directly controlled by the HA infrastructure.
* '''Component Service Instance (CSI)''': It represents a unit of workload that is assigned to a component. Each CSI has a set of attributes that characterizes the workload assigned to the component. These attributes are not used by AMF and are passed to the components.
* '''Service Instance (SI)''': It is an aggregation of various CSIs that can be assigned to the components in the SU. These CSIs can be ranked in order or priority.
* '''Service Unit (SU)''': It is an aggregation of one or more components that are managed together to provide a service. Redundancy is provided to the SU as a whole. This implies that all the processes that are clubbed together with an SU will switchover or failover as a unit.
* '''Service Group (SG)''': It is a collection of service units (SUs) of the same type that collectively provide service availability for one or more service instances. A redundancy model associated with the service group defines how the service units in the group are used to provide service availability. An SG is defined at run-time and is dynamically populated with the required SUs.
* '''Node''': A logical representation of a physical node that houses Service Units and components.
* '''Cluster''': It comprises the entire system containing multiple nodes.

OpenClovis SAFplus Platform provides a SA Forum compliant implementation of the 2N and M+N redundancy models. These two models can be used to provide Active/Active and N Way Active functionality if desired as well.
[[File:Ha_models.png|center|frame|'''SA Forum Compliant Redundancy Models''']]

The figure shows a SA Forum compliant 1:1 and 2:1 redundancy model applied to a Cluster of Nodes. A ''Service Engine'' is interchangeable with Node in this dicusssion.

===SAFplus Platform Features for High Availability===

OpenClovis SAFplus Platform includes a powerful set of integrated High Availability services that are used to manage resource failures without interrupting services. High Availability of services provide software exception handling and recovery mechanisms. OpenClovis SAFplus Platform services can identify their failure modes and can implement system-defined mechanisms. The following features are supported by SAFplus Platform:

====SA Forum Compliant Model and AMF APIs====
Availability Management Framework (AMF) closely follows the SA Forum AMF specification.

====Creation of HA Models====
HA Model definitions and their instantiations are defined prior to runtime. The HA Models can be specified during the modelling phase, where the graphical IDE provides convenient UML based icons to specify the HA model desired (including the desired availability model of every service group (SG) in the system and the required actions for every component on their failures) and all the corresponding fault escalation and recovery policies. This is then converted into a set of ''XML'' configuration files that define the type and instance information. The ''XML'' files can be modified as well prior to starting SAFplus Platform.

====Redundancy Models Supported====
<ul>
<li>'''2N (or 1:1) Redundancy Model''': OpenClovis SAFplus Platform provides a SAF compliant implementation of the 2N redundancy model. 2N redundancy model allows N number of Service Groups, each with up to one active and one standby Service Unit (SU) and with arbitrary number of spares. Active components provide service, standbys are prepared to take over the service in case of a component failure. Active and standby components may reside either on the same node or on different nodes. Standbys for multiple actives can reside on the same node. Active and standby can share states using checkpointing (hot/warm standby).

 The traditional rendition of this redundancy model is described in the Figure [[#SAF_Compliant_Redundancy_Models | SA Forum Compliant Redundancy Models ]]. Another feature availbale to the system designer is the concept of ''Spare SUs'' that enables design of robust 1:1 protection scheme as described below:

[[File:Ha_spare.png|center|frame|'''1:1 Redundancy with Spare SU''']]

A ''Spare SU'' is not activated or given a workload assignment when the Active SU and Standby SU are operational. However if the Active or Standby SU fail, for instance if the Node housing the Active SU becomes inoperational, the Standby SU is made Active and the ''Spare SU'' is promoted to Standby Role. If the failed SU is brought back into service, either automatically by the HA infrastructure or manually through administrative interface, it assumes the ''Spare SU'' role.

<li>'''M+N Redundancy Model''': The ''Spare SU'' concept holds true for the M+N redundancy as well. The variations of M+N supported and tested for by OpenClovis are N:1, N:N and M:N, for instance 3:1 ( 3 Active and 1 Standby), 3:2 (3 Active and 2 standby) 3:3 (3 Active and 3 Standby).

<li>'''Active/Active''': The ''N Way Active'' redundancy model of which ''Active/Active'' is a subset is not explicitly supported by OpenClovis SAFplus Platform, however, this can be achieved effectively in the following manner:

[[File:Active_active.png|center|frame|'''Using 1:1 redundancy to achieve Active/Active redundancy''']]

In the figure above is shown two SGs each identical in definition, but reversed in the order of Active and Standby SUs. When a SU is made Active it is assigned a Component Service Instance (CSI) which defines its work assignment, so that in this example each SU will be given 1/2 (or whatever fraction desired) of the total workload. In the above Figure if the there is a Node 2 fails or the Active SU in Node 2 fails, then Node 1 takes on the entire workload.
</ul>

====Node Type Distinctions====

An OpenClovis cluster has two classes of nodes:
# System Controller
# Payload (Worker) Node

Only System Controller nodes are allowed to take part in leader election, so that one is elected master, and the other is elected deputy. System Controller nodes can run user applications just like any other node in the cluster. In addition there are certain processes that only run on the System Controller, they are:
# Availability Management Framework (AMF): The availability Management Framework is a single ''Linux'' process but contains two distinct logical components. On a Payload Blade the AMS component is inactive and CPM component takes on the CPM-L flavor, however the same physical program runs on both node class types.
#* Availability Management Service (AMS): SAF compliant implementation of AMF, that takes care of implementing the policy based HA logic, for instance failover policy. The logic here needs a global view of the cluster in order to make decisions and so by its very nature must be centralized.
#* Component Manager Global (CPM-G): The Component Manager controls the lifecyle and monitors all SAFplus Platform components including SAFplus Platform servers. There are Component Managers running on Payload Blades (CPM-L) as well, the difference between the CMP-L and CPM-G is that CPM-L acts under the control of CPM-G.
# Clovis Object Repository (COR): This is SAF IMM aligned object repository that is centralized to the active and standby System Controllers. The major reason for keeping this central was due to performance considerations when compared to a distributed Object Repository. It should be pointed out here, that access to COR is distributed so that COR clients on any node in the cluster make the same API calls to access COR.
# Platform Support Package (PSP): PSP is integrated with SAF compliant HPI implementations like OpenHPI to communicate with the Shelf Manager of an ATCA chassis to provide platform management. The PSP is an optional package and is tuned to particular ATCA or proprietary chassis.

====Fault Management====
This includes Fault Removal and Failure Forecasting. The system helps in Fault Detection, Fault Isolation, Fault Recovery, Fault Repair, Fault Notification, and Prediction.

====Checkpointing Service====
The Checkpointing Service allows the applications to save their internal state, and retrieve it later. This enables quick restart. Alternatively, the state is retrieved by standby components for very quick failovers.

===Availability Management Framework (AMF)===

The Availability Management Framework (AMF) functions are collectively
implemented in the Availability Management Service (AMS) and the Component
Manager (CPM) software components.

AMS is the primary decision making entity in the system with respect to service availability.

The CPM is the operational manager entity and is responsible for managing the various components through their life cycle, based on the configured policy as well as directions from AMS.

AMS and CPM together maintain a view of the system model that describes the various software and hardware components in the system, their attributes, dependencies on each other, rules for grouping them together for providing services availability, current state and policies to be applied in the event of failure.

====CPM-AMS interaction====

In SAFplus Platform world, the Availability Management Framework is implemented as two
entities Availability Management Service (AMS) and Component Manager (CPM). Even
though both the entities are in the same process, there is a very clear separation of functionalities between AMS and CPM.

# AMS is a 'server library' that maintains the (configuration and status) information about the whole cluster, knows the policies that has been configured for different entities, the recovery (or repair) actions to be taken in case of an application failure, based on both the configured policies as well as the current cluster system state. AMS deals only with application components.
# CPM is an operational entity which simply carries out the commands given by the AMS. However, CPM does manage the complete life cycle of the SAFplus Platform components. The recovery policy for the SAFplus Platform components is unlike AMS, very primitive. If an SAFplus Platform component fails, it will be simply restarted. There is a limit to these restart attempts however, after which the node will be shutdown.

====Summary of interactions between AMS and CPM====

#AMS to CPM :
## Call to CPM for managing the life cycle of the component.
## Call to CPM for assigning (and removing) work to the component.
## Informing CPM that some node for whom the shutdown request has come can (or cannot) be shutdown.
## Informing CPM when taking node level recovery actions. (Node failfast and node failover.)
#CPM to AMS :
## Responding to AMS the success/failure of component life cycle or work assignment/removal request.
## Reporting fault on the component, whenever a failure on that component is detected.
## Querying AMS about the HA state of the component.
## Informing to AMS that node is joining the cluster and is ready to provide service.
## Informing to AMS that some node wants to leave the cluster and so if it is permitted for the node to be shutdown, switchover all the components and do the shutdown.
## Informing to AMS that some node has exited ungracefully and hence do the failover the components without actually trying to contact the failed node.
## Informing to AMS about availability/unavailability of some of the SAFplus Platform components.

====Architecture of the CPM====

In an SAFplus Platform cluster, there is a CPM running on every node, managing the components on that node. This is in contrast to the AMS, which will be brought into life by CPM only if that node happens to be a system controller.

Based on whether AMS is initialized by CPM or not there are two types of CPM:
# Local Component Manager. This is also called \b CPM/L (L standing for the local). The node (or blade) where CPM/L is running is called Worker Blade. The word Worker Node also means the same thing.
# Global Component Manager. This is also called \b CPM/G (G standing for the global). The node (or blade) where CPM/G is running is called System Controller Blade or simply System Controller .

The terms CPM/G and System Controller, CPM/L and Worker Blade (Worker Node) are used interchangeably, sometimes referring to the CPM running on the node as an entity and sometimes referring to the node itself where the particular type of CPM is running.

The differences between CPM/G and CPM/L are :

# The AMS will be running only on System Controller node. The system controller node where AMS is running in active mode is said to have and Active HA state. Similarly the system controller where the AMS is running in standby mode is said to have Standby HA state. There will be no AMS running on a Worker Node however and so worker node does not have any HA state associated with it.
# The CPM/G(Both active and standby) maintains the information about all the nodes (but not the components in those nodes) in the cluster and does the heart beating of all the nodes which are up and running. The CPM/L does not maintain any such information.
# The active CPM/G or active system controller blade is the one where all the HA related activities take place. It is the place to where all the triggers about various events happening in the cluster (e.g. node failure, user component failure, node is ready to provide service etc) will go either directly or indirectly and the corresponding actions are taken.
# On ungraceful termination of any node, CPM/G will publish an event providing information about the failed node.
# The active CPM/G acts as an intermediate entity between AMS and real world. It is the one which brings AMS to life and keeps it informed about the events which are going on in the cluster such as :
## Node is joining because it is ready to provide service.
## Node is leaving because shutdown was issued on the node.
## Node has left the cluster, because it was killed or crashed for some reason (e.g. communication failure, kernel panic etc)
# The active CPM/G is the one which actually carries out various operations specified by the AMS in reaction to the various events

The commonalities between CPM/G and CPM/L are :

# Both types of CPM manage life cycle of the SAFplus Platform components on the local node.
# Heart beating of the components. Both types of the CPMs do heart beating of the local components and take the following actions :
## If the heart beat loss was for an SAFplus Platform component, then the CPM will restart it. But if this failure happens more than certain number of times within a particular time window, then the node will be shutdown gracefully.
## If the heart beat loss was for an user defined component, then the CPM will report the failure to AMS via clCpmComponentFailureReport() API.
# On death of any component whether SAFplus Platform or user defined, CPM will publish an event using event management API, providing information about the failed component.

The OpenClovis Availability Management Framework (AMF) is a software entity that is primarily responsible for service recovery. It provides a framework for high availability of applications in a system by coordinating with the redundant resources.

It executes pre-configured recovery actions on failure of the application and ensures that no loss of service occurs when components are removed from services either due to component failure or any administrative actions. It also escalates the faults to larger scope as per the pre-configured escalation rules.

AMF is built with the close association of two OpenClovis SAFplus Platform components, the Component Manager (CPM) and the Availability Management Service (AMS). These two components work together as defined by the Service Availability Forum. AMS is the primary decision making entity towards service availability in the system. CPM is the operational manager and is responsible for actually managing the various components through their lifecycle, depending on the configured policies.

====Functions of AMF====

The main functions provided by AMF are:
* It maintains the view of one logical cluster that comprises several cluster nodes. These nodes host various resources in a distributed computing environment that describes the software and hardware components of the system.
* It stores information about attributes of the resources, their dependencies, rules for grouping them together for providing services, their current state, and the set of policies to apply on failures.
* Using OpenClovis IDE, you can configure the desired availability policies with AMF on how to recover in case of failure of a service.
* AMF handles fault detection, fault isolation, and redundancy wherein constant health monitoring of the components is performed. Fault Manager handles fault recovery and repair actions.

====Classification of Components====

High availability components can be classified based on:
* Integration mechanism with AMF
* Run-time characteristics

=====Classification Based on Integration Mechanism with AMF=====

Depending on the type of integration with AMF, the components are:

'''SA-Aware Components'''
 SA-Aware components contains processes linked to AMF library. The process of registering the component is called '''Registered Process''' with AMF. AMF utilizes this process to handle callbacks.

'''Non-SA-Aware Components'''
 There is no registered process for non-SA-aware components. Non-SA-aware components uses proxy components to register with AMF. All the available processes are application processes. Examples of non-SA-aware components are scripts for applications, hardware specific resources, and so on.

'''Proxy component'''
 All SA-aware components need to be directly registered with AMF. The proxy component can act as the proxy between AMF and the non-SA-aware components. Proxy component registers the non-SA-aware components to AMF, whenever AMF needs to perform an operation on proxied component, it will be achieved through a proxy component. These type of components should have a Managed EO. SA-aware component which does not proxy any proxied component are called as non-proxy component. The Availability Management Framework uses the callback functions for managing the proxied components registered by a proxy component to control the proxy component and the proxied components for which the proxy component mediates.

'''Proxied Component'''
 There are components, which do not directly register with the AMF, called as non-SA-aware component. These type of components are proxied by a SA-aware component and are called as proxied components. This maps to a component that does not have any Managed EO. For example, hardware and legacy applications.

'''Proxy-Proxied Relationship'''
 Proxy-Proxied Relationship is a function that facilitates a non-SA-aware Component to be managed by OpenClovis SAFplus Platform. In OpenClovis IDE, create a non-SA-aware component by selecting the non SAF Component (proxied) component from the palette in the Component Editor. The non-SA-aware component is called as the proxied component and the SA-aware component is called the proxy component. The AMF manages the proxied component indirectly via proxy component, by invoking callbacks for the proxied in the context of its managing proxy. An indirect process registration occurs between the non-SA-aware component and AMF if using proxy-proxied relationship. The proxy component is the mediator between the AMF and the proxied component, there must be sufficient logic in the proxy component to mediate the communication between the two entities.

The proxy-proxied relationship is modeled in IDE by creating a SA-aware component and then a non-SA-aware component, which are linked by using the auto relation relationship and provides a proxy-proxied relationship between the two components. A proxy component can proxy any number of proxied components and the AMF defines the logic for assigning CSI workloads on those proxied components. The proxied component does not have any EO properties settings in the IDE. Since SAFplus/AMF does not have a direct control on the non-SA-aware component, and eonization is not taking place there, generally a non-SA-aware component will be a legacy application that needs to be managed by SAFplus Platform.
* A proxy-proxied relationship can span across different Nodes/SUs/SGs in the Component Editor.
* A directory is not created for a proxied component in <code><project_area>/<model>/src/app</code>, also the binary is not generated from SAFplus Platform compilation. The application is an external entity. It is linked using the relationship between the proxy and the proxied component.
* The redundancy model of the proxy component can be different from that of its proxied components.
* AMF does not consider the failure of the proxied component to be the failure of the proxy component. Similarly, the failure of the proxy component does not indicate a failure of the proxied components.

=====Classification Based on Run-time Characteristics=====

Depending on the run-time characteristics, the components are classified as:

'''Pre-Instantiable Components'''
 These components have the ability to stay idle after getting instantiated. They only start to provide a particular service(s) when instructed to do so by AMF. All SA-Aware components have to be preinstantiable.

'''Non-Pre-Instantiable Components'''
 These components start providing service as soon as they get instantiated. These type of components cannot be instantiated as a spare unit. While instantiating a SU or assigning SI to an SU, AMF looks at the component type. The proxy component is responsible for conveying requests made by the AMF to its proxied components. When the proxy component registers with AMF, it decides the proxied components that a proxy component is responsible for based on configuration and other factors like availability of components in the cluster. AMF conveys this decision to the proxy component by assigning it a workload in the form of a Component Service Instance (CSI).
* A single proxy component can mediate between AMF and the multiple proxied components.
* The redundancy model of the proxy component can be different from that of its proxied components.
* The Availability Management Framework does not consider the failure of the proxied component to be the failure of the proxy component. Similarly, the failure of the proxy component does not indicate a failure of the proxied components.

====About Availability Management Service (AMS)====

Availability Management Service (AMS) comes with a default set of policies on how to recover a service. These include restart or switchover of services to a standby. The following are the functions of AMS:
* '''Defining System Model''' - You can define a system model in an xml file and feed it to AMS. This includes configuration of AMS entities, attributes and relationships between the entities. Configuration is statically read at startup time, however, the AMS code can accept new configuration at run-time. The association and containment relationship can be configured and used by AMS.
* '''Service Unit and Component Lifecycle Management''' - AMS can start and stop the appropriate number of service units as per the rules configured with their service groups. AMS can be configured to retry starting and terminating a component as many times as required before declaring the instantiation or the termination as failed. If a component fails to terminate properly, it is cleaned up as per its configuration.
* '''Service Group Management''' - AMS supports the following redundancy models:
** 2N redundancy model
** M+N redundancy model
** No redundancy model
* '''Best Possible Assignment at Boot-time''' - During the system boot-up, the SUs take time to instantiate. If AMS starts assigning SIs to them immediately, the initial assignment of SIs to SUs will not match the required ranking. AMS, therefore, waits for a configurable period of time for an SG to stabilize at boot time before assigning SIs to SUs. Multiple SIs can be assigned to an SU.
* '''CSI Assignment''' - Multiple CSIs can be assigned to a component based on the components capability. If there are multiple components in an SU that support the same CSI types, the assignment is based on the rank of components in the SU. It requires the ordered list container functions, otherwise the first suitable component found in the list is assigned.
* '''Node Management''' - Using AMS, you can join the nodes or leave the cluster at any given time.
* '''Administrative Control''' - AMS provides you with the administrative rights to control the entities using SAFplus Platform Console commands. You can perform various functions on these entities, such as lock, unlock, shutdown, restart, and repair.
* '''Fault Recovery''' - Faults can be reported on the components as well as the nodes. These faults are handled based on the following rules:
** Default recovery policy configured for the component to restart the component or the SU, and to cause a failover of the SU or the node.
** The number of components in an SU that fail after a certain time interval can cause an escalation to restart the SU.
** The number of SUs in an SG that fail after a certain time interval can cause an escalation to restart the node.
** The number of node wide SUs that fail after a certain time interval can cause an escalation to failover of the node.
* '''Faults at Node''' - The faults occurring at a node result in a failover of all the SUs on the node.
* '''AMF Client API''' - Clients can register with the AMF and CSIs can be assigned to or removed from them using the AMF client API.

====About Component Manager (CPM)====

The CPM is an operational manager entity, responsible for managing the various Service Units and components through their lifecycle, based on configured policy and instructions from the AMS.The following are the functions of CPM:
* '''Hierarchical Component Management''': SAFplus Platform deploys node-local Component Managers (CPM/L) as well as a Global Component Manager (CPM/G) supervising the entire system. The latter, typically is located on the system controller card and can have a standby on a standby system controller card. The CPM/Ls are responsible to provide boot management and basic lifecycle management for all components running at the node. CPM/G coordinates the entire system by talking to all CPM/Ls.
* '''Boot Management''': SAFplus Platform provides fine-grained control over booting a node and starting SAFplus Platform components and other applications. A deployment configuration file, an XML file generated by IDE, describes all software entities to be started on the node.
* '''Basic Component Lifecycle Management''': CPM provides basic component lifecycle management, including health monitoring of each component.
* '''Component Health Monitoring''': CPM monitors the health of every local component and can automatically detect the failure of a component. In addition, a component can self-declare a failure to CPM. In addition, CPM/G conducts periodic health check of every CPM/L in the system. CPM/L also pro-actively notifies CPM/G on a failure of any of the local components.
* '''Failure Event Generation''': All component failures detected by CPM are posted to a dedicated event channel to which any component in the system can subscribe.
* '''Automatic Logging of Health State Changes''': CPM/L can automatically log any changes to the state of any of the supervised components.

===Fault Detection and Handling===

====Software Fault Detection====

Software failure detection is done actively and passively. For passive monitoring OpenClovis SAFplus Platform leverages the high performance features of TIPC to detect socket bind and release events and notify other components of this fact. For details on TIPC capabilities please refer to TIPC documentation that can be downloaded from tipc.sourceforge.net.

=====Passive Software Failure Detection=====

[[File:Software_monitoring.png|center|frame|'''Passive software monitoring in OpenClovis SAFplus''']]

Each SAFplus Platform Component has a dedicated IOC port (translates to a TIPC socket) associated with it, and remains open for the life of this component. All internal communication and control over this Component is performed via this port and is transparent to the user. Building upon this fact a Component arriving will result in a ''TIPC socket bind'' event and a Component departing will result in a ''TIPC socket release'' event.

TIPC allows any process to subscribe to these events on a cluster wide basis, and
on each Node an SAFplus Platform ''Node Rep'' thread subscribes to ''TIPC Socket Bind'' and ''TIPC Socket Release'' events for all SAFplus Platform components local to this Node. If a Component departs this fact is broadcast to all the other components in this Node, and multicasts a message to all the peer ''Node Reps'' on other Nodes. The ''Component Manager Global'' (CPM/G) registers this fact on the System Controller and takes appropriate recovery and repair action.

=====Passive Node Departure Detection=====
The architecture for detecting component arrival and departure is also used to detect Node arrival and departure, since the ''Node Reps'' on each Node open a dedicated IOC port to communicate with each other. The departure of the ''Node Rep'' will be received by all ''Node Reps'' in the system and is broadcast as a ''Node Departure'' event locally. Since the ''Node Rep'' is a thread within the ''AMF'' Server as described earlier, it effectively represents the Node.

=====Active Software Failure Detection=====
Each SAFplus Platform Component has a heartbeat callback that is invoked periodically to check on the health of the Component. This heartbeat interval can be temporarily disabled or scaled back when a Component is under heavy load conditions.

The purpose of this heartbeat is to enable the Component to perform an internal audit and report back success or failure. If a failure is reported the AMF can take appropriate recovery and repair action as the policy for the Component.

====Hardware Fault Detection====
In an ATCA environemnt OpenCLovis SAFplus Platform relies on the Shelf Manager and the HPI interface to obtain information related to
* Hot Swap Events: In this case the AMF takes control of the card from the shelf manager and performs a Node Switchover so that all services are migrated to the standby card. After this all SAFplus Platform Services on the Node are shut down and contol returned to the Shelf Manager to power down the card.
* Alarms related to hardware failure: If the alarm is service affecting, then a Node failover action is performed migrating all services running on the affected card to a standby, after which all SAFplus Platform Services on the Node are shut down. Not all hardware is monitored by HPI, and in this user monitoring Components can use the SAFplus Platform Alarm infrastructure to raise a critical alarm to migrate service from the failing hardware to a standby.

In case of application where the HPI interface is not used, however there is some mechanism to
* Detect Hot Swap Events
* Monitor hardware via diagnostic software and raise an Event if a fault is detected.

=====Managed Hot Swap Events=====
It is assumed here that a SAFplus Platform user component will receive the ''Hot Swap Event''. Once it receives this event it perform a Node ''shutdown'' of the affected Node resulting in the graceful removal of service on the affected Node and a switchover to standby. All SAFplus Platform Service on the Node will then be shut down. Please refer to the section related to AMF Administrative API for more details.

=====Diagnostics Driven Fault Event=====
[[File:SDK_Diagnostic_alarm.png|center|frame|'''Basic mechanism to tie in diagnostic fault events to AMF''']]

The Figure illustrates a solution by which the application that does hardware diagnostics can tie into the OpenClovis SAFplus Platform Alarm infrastructure to force a Node ''failover'' if a service affecting hardware fault is detected.

====Fault Escalation====
OpenClovis AMF provides an extensive fault escalation policy that can be briefly described as follows
# Component
#* Specify number of restarts (N) within a given time period (T) before escalating to SU failure
# SU
#* Specify number of restarts (N) within a given time period (T) before escalating to SU failover
# Node
#* Specify maximum number of SU failovers that can occur within a given time period (T) before escalating to a Node failover

In addtion you can specify that failure of any Component should result in any of the following actions:
# Component restart
# Component failover (SU failover)
# Node switchover
# Node failover
# Node restart

====Fault Repair====
The user can specify the following policies for repair action that should be performed by the AMF on failure. This include
# Component restart
# SU restart
# Auto repair on SU failover. All components in the failed SU will be restarted.

In addition custom repair action can be performed using the Fault Management infrastructure. The user can associate a callback API that will be invoked after AMF performs the default repair action.

====Adminstrative Control====
Please look in the section detailing the AMF Adminsitrative Interface for details on this subject.

===Checkpointing Service (CPS)===

The OpenClovis Checkpointing Service (CPS) is a high availability infrastructure component that provides synchronization of run-time data and context to ensure a seamless failover or switchover of applications.

====Features of CPS====

Checkpointing Service provides the following features:
* It allows the application to store its internal state and retrieve the information immediately, at regular intervals or in case of failover, or switchover.
* It provides a facility for processes to record checkpoint data incrementally, which can be used to protect an application against failures. When recovering from failover or switchover situations, the checkpoint data can be retrieved, and execution can be resumed by restoring the checkpointed state recorded before the failure.
* It supports non-transparent mode of checkpointing where an application needs to trigger the checkpoint write and checkpoint read.

A given process can use one or several checkpoints to save its state. To avoid the accumulation of unused checkpoints in the system, checkpoints have retention duration. When a checkpoint has not been opened by any process for the retention duration, the CPS automatically deletes the checkpoint. If a process terminates abnormally, the CPS automatically closes all of its open checkpoints.

====Entities of Checkpointing Service====

The main entities of Checkpointing Service are:
* '''Checkpoints''': Checkpoints are cluster-wide entities that are designated by unique names.
* '''Sections''': Each checkpoint is structured to hold up to a maximum number of sections. The maximum number of sections is specified when the checkpoint is created. For more details, refer to <code>'''clCkptCheckpointOpen'''</code> and <code>'''clCkptCheckpointOpenAsync'''</code> API functions in the ''OpenClovis API Reference Guide''.
* '''Checkpoint Replica''': A copy of the data that is stored in a checkpoint is called a checkpoint replica or a replica. It is stored in RAM File System (RAMFS) instead of a disk for performance reasons. A given checkpoint may have several checkpoint replicas (or copies) that reside on different nodes. A checkpoint can be replicated immediately on a different blade and can be stored indefinitely or consumed immediately.
* '''Checkpoint Data Access''': A process can use the handle that the Checkpoint Service returned at open time to perform read and write operation. It can access various portions of different sections within a checkpoint simultaneously.

====Architecture====
OpenClovis SAFplus Platform provides a high performance distributed checkpoint service, with Checkpoint Servers resident on each Node in the Cluster. The basic architecture of the Checkpoint Service can be described as shown below:

[[File:Ckpt_arch.png|center|frame|'''Checkpoint Service Architecture''']]

The Checkpoint Servers essentially behave as peers, except that the Servers on the System Controllers maintain the Global Checkpoint database. This database consists of the the metadata describing each checkpoint, so as to ensure that each checkpoint created in the cluster is unique. In addition the Server on the System Controller is also responsible for ensuring that there is at least one replica for each checkpoint in the system, so that loss of a Node does not mean that checkpoint data is lost too.

Each checkpoint server maintains a local Checkpoint database as well. This database contains the actual checkpointed data, and the location of all replicas of this checkpoint in the cluster. It is the responsibility of the Checkpoint Server to update all replicas in the system.

====Checkpoint Types====

OpenClovis SAFplus Platform provides support for two kinds of checkpoints:

* '''File based Checkpoints''': Slower in performance since the checkpoint is stored in persistent storage. However checkpoints can survive Node restarts, as well as component failovers and component restarts. This is an enhancement to SAF requirements.
* '''Server based Checkpoints''': Higher performance, supports failover and Component restarts.

The rest of this section will deal with Server Based Checkpoints. Server based checkpoints provide support for synchronous and asynchronous checkpoints. The attributes defining a checkpoint are described at creation time.

* '''Synchronous Checkpoints''': A checkpoint write here ensures that all replicas of the checkpoint are updated before returning control back to the writer.
* '''Asynchronous Checkpoints''': In this case after the active replica is updated, an asynchronous update message is sent to all other replicas in the cluster. The location of the active replica can be controlled by specifying that the asynchronous checkpoint created is:
** '''Collocated''': In the case the active replica is local to checkpoint writer.
** '''Non-collocated''': The checkpoint server determines the Node on which to place the active checkpoint based on load balancing considerations.

[[File:ckpt.png|center|frame|'''Illustration of a checkpoint''']]

A checkpoint consists of multiple sections, where each section can be of arbitrary size. Testing is being performed for checkpoints upto 10,000 sections each of 10,000 bytes for a total checkpoint size of 100 Megabytes

====Flexibility of Checkpointing Updates====

Requirements regarding the consistency of the various replicas associated to a given checkpoint can have negative effects on the performance of checkpoint write operations. To provide flexibility with Checkpoint Service, strong atomicity and strong ordering semantics are not required. In particular, if two processes perform a concurrent write to the same portion of a checkpoint, no global ordering of replica updates is ensured. After both write operations complete successfully, some replicas may contain data written by one process while other replicas contain data written by the other processes.

To accommodate different trade-offs between checkpoint update performance and replica consistency, different options are provided when a checkpoint is created. These options are:
* '''Synchronous Update''': The write and overwrite calls and calls for the creation and deletion of a section return only when all checkpoint replicas have been updated.
* '''Asynchronous Update''': The write and overwrite calls as well as calls for the creation and deletion of a section return immediately when the active checkpoint replica has been updated. Other replicas are updated asynchronously. At any time, there is at most one active replica.

====Collocated and Non-Collocated Checkpoints====

Management of replicas for Collocated and Non-Collocated Checkpoints.
* '''Collocated Checkpoints''': When using a checkpoint with the asynchronous update option, optimal performance for updating the checkpoint is achieved when the active replica is located on the same node as the process accessing the checkpoint. However, because the process accessing the checkpoint can change depending on the role assigned by the Availability Management Framework, optimal performance can be achieved only if the application informs the Checkpoint Service about which replica should be active at a particular time. This can be performed for checkpoints having the collocated attribute. Such a checkpoint is referred as a collocated checkpoint.
* '''Non-Collocated Checkpoints''': Checkpoints created without the collocated attribute are called non-collocated checkpoints. The management of replicas of non-collocated checkpoints and whether they are active or not is mainly the duty of the Checkpoint Service. The processes using the Checkpoint Service are not aware of the location of the active replicas.

The Checkpoint Service may create replicas other than the ones that may be created when opening a checkpoint. This can be useful to enhance the availability of checkpoints. For example, if there are at a certain point in time two replicas, and the node hosting one of these replicas is administratively taken out of service, the Checkpoint Service may allocate another replica on another node while this node is not available.

'''Persistence of Checkpoints'''
 As mentioned earlier, Checkpoint Service stores checkpoint data in the RAMFS of the nodes. Irrespective of the retention time, a checkpoint and its sections do not exist if the Checkpoint Service stops running on all nodes hosting replicas for this checkpoint. This can be caused by administrative actions or node failures.

'''Prerequisites for Persistence of Checkpoints'''
* The checkpoint data is not persistent across node reboots.
* If a checkpoint is stored in a persistent store such as hard disk or flash drive, it is the system integrators responsibility to ensure that the data is deleted before starting CPS.

====Hot Standby Support====

One of the limitation of SAF checkpoints is the absence of a notification to the reader or consumer of a checkpoint, when the data within the checkpoint has been updated. If the designer wants to implement true hot standby capability, it is upto the designer to either poll the checkpoint periodically or establish some other means of communication with the active Component to know when the checkpoint has been updated.

To remedy this situation OpenClovis Checkpoint Service allows applications to register with the Checkpoint Server for notifications related to any checkpoint of interest. During the registration the application specifies a callback API, which gets invoked when a checkpoint has been updated. The callback contains the name of the checkpoint being updated and the contents of the checkpoint.

===Group Membership Service (GMS)===
Group Membership Service (GMS) is OpenClovis SA Forum compliant Cluster Membership Service (CLM). In addition to providing cluster membership services, it also provides leader election services to elect Active System Controller and Deputy. It extends the SA Forum CLM by providing generalized group membership service, which enables software processes to form Groups.

The OpenClovis Group Membership Service (GMS) provides following services:

*'''CLM Functionality:''' GMS forms a cluster of nodes that have unique attributes like node name, node id, etc, and that are running SAFplus Platform. It does a leader election on the nodes in the cluster and elects a leader and a deputy node, which act as ''Active System Controller'' and ''Standby System Controller'' for the given SAFplus Platform cluster. It also provides functionality using which the user can keep track of the changes in the cluster such as node joins, node leaves and leadership changes. Any application or OpenClovis SAFplus Platform service can register with GMS to keep track of the changes in the cluster.

*'''Multicast Group Functionality:''' GMS with Intelligent Object Communication (IOC) provides multicast messaging capability. GMS provides APIs for user applications to form a multicast group and use IOC multicast capabilities to send the messages to the registered users in a given multicast group. GMS also provides APIs to track the membership of each multicast group for member and non-member applications.

The following sections describe how you can implement these features, it involves understanding the following services:
* [[#Group Management | Group Management ]]
* [[#Group Addressing and Multicasting using Intelligent Object Communication (IOC) | Group Addressing and Multicasting using Intelligent Object Communication (IOC) ]]
* [[#The Remote Method Dispatch (RMD) Advantage | The Remote Method Dispatch (RMD) Advantage ]]

One of the guarantees given by GMS is a uniform view of the cluster to be given to each cluster member, for which it relies on the Totem protocol. The Totem protocol is a reliable and fault tolerant multicast protocol that deliver messages in total order, also referred to as atomic multicast. The protocol is designed to handle processor crash failure and network partitioning.

A side effect of the multicast protocol is that all Nodes within a cluster have to be within a subnet. If you have Nodes in seprate subnets that have to be part of the same cluster the subnets can be bridged to form a ring if the router in between is configured with a multicast protocol to forward packets from one subnet to other.

The underlying Totem Protocol used by GMS is the same as that used by the openAIS CLM, and the author of this software has the following caveat for the use of packet forwarding between subnets: ''"The TTL of packets is set to zero. I dont have a router setup to test openais in this configuration but it should work assuming the router offers low latency. To ensure it working, the ttl of the packets would have to be increased and routing of multicast and udp unicast would have to be enabled on the router."''

====Group Management====

Group Membership Service (GMS) exposes APIs that enable you to manage multicast groups. Group Management involves:
* Creating/Deleting Groups
* Joining Groups
* Tracking Groups
* Updating Groups

'''Creating/Deleting Groups'''
 You can create a multicast group using the <code>'''clGmsGroupCreate'''</code> API. GMS generates and returns a unique group ID. Currently, all GMS groups are IOC multicast groups. GMS allocates a unique IOCMulticastAddress (MA) to each group. You can delete a group using the <code>'''clGmsGroupDestroy'''</code> API.

'''Joining Groups'''
 A user application or a node can join a multicast group using the <code>'''clGmsGroupJoin'''</code> API. By joining a group, a node becomes a member of that group. Components running on different nodes can join a group. Each component is assigned a member ID based on their compId (component ID). A component can receive messages sent to a group, only if it is a member of that group.
 A component can leave the group using <code>'''clGmsGroupLeave'''</code> API. After the component leaves the group, GMS ensures that the component does not receive any messages sent to this group.

'''Tracking Groups'''
 Group Membership Service provides processes to retrieve information about the group nodes and the group membership. The <code>'''clGmsGroupTrack'''</code> API provides the capability to retrieve information regarding the status and the list of nodes within a group.
All members are informed whenever a member leaves or joins the group. A non-member can also keep track of the events in the group such as a node failure or a service failure.
 You can retrieve information about a group such as IOC MulticastAddress created by GMS, number of members in a group, and so on using <code>'''clGmsGetGroupInfo'''</code> API.

'''Updating Groups'''
 If a component or a node fails, GMS deregisters that component or node from the IOCMulticastAddress group. It ensures that the failed components are removed from the group and communicates to all the other members about the status of the group.

====Group Addressing and Multicasting using Intelligent Object Communication (IOC)====

IOC provides the basic messaging and distribution mechanism to communicate between inter-node and intra-node components. If the destination address is a logical address, IOC sends the message to the corresponding physical address. If destination address is of a broadcast address type, IOC sends the message to all the existing nodes.

IOC, with the TIPC Linux Kernel module also provides the multicast capability. Multicast is a technique of delivering information to a group of members simultaneously.

An application wanting to start a group has to create and join the group using <code>'''clIocMulticastRegister'''</code> API. For creating a multicast address the macro <code>'''CL_IOC_MULTICAST_ADDRESS_FORM'''</code> should be used. Once the group is created, all the components, which are interested in joining the group can join the group using the same API mentioned above. When a component leaves a group, the IOC disassociates the member with the multicast/group address.

Group members and non-members can send IOC multicast messages. A component can send a message to a group with destination address as group's multicast address in <code>'''clIocSend'''</code> API. This is an asychronous API. On receiving a send request IOC checks the destination-address type and if it is a multicast-address then IOC using the TIPC Linux kernel module sends the message to all the member components of the group.

=====Benefits=====

IOC multicasting uses the broadcast capability of the underlying TIPC Linux kernel transport module and triggers a single message send that is sent to all the components in the group. This would help reduce the processing time as opposed to sending it to each component separately.

A set of applications that need to share information with each other may form an IOC group and use this mechanism to convey the information. They can use GMS generic group membership to keep track of each other and use the GMS join/leave calls to manage the IOC group address. Any entity that is not a member of an IOC group can also use the IOC group address to communicate simultaneously to all members of that group.

====The Remote Method Dispatch (RMD) Advantage====

A broadcast message can be sent to a multicast group synchronously using the <code>'''clRmdWithMsg'''</code> API that is part of the RMD library. This API takes the IOC address where the function is exposed as the parameter. RMD also ensures at-most-once delivery to all members of a multicast group. For detailed information about all the APIs and how to use them, refer to IOC, GMS, and RMD in ''OpenClovis API Reference Guide''.

===Typical Usage of High Availability===

Assuming the case of a 2N redundancy model, there are two service units running the same set of services, one of which is an Active system, and the other is the stand-by. AMS is responsible for switchover, and contains all the policies. CPM executes the commands that are provided by AMS. CPM checks the status of the service provider and informs the status of the provider to AMS. AMS takes a decision to either perform a switchover or a re-start of the service provider. CPS checkpoints the completion of an activity and starts the standby from the checkpointed state.

====Logical Addressing and Location Transparency====

The IOC Transparency Layer database is a hashtable that contains the logical addresses of the components received from the Name Server. The Name Server contains the mapping information of logical addresses to the physical addresses and the HA states of the components.

The location transparency can be achieved as follows:
* The Transparency Layer database is synced up after every 5 seconds through an IOC broadcast to other nodes. It is also synced up when a new entry is either registered or deregistered in the Transparency Layer database.
* When the CSI is assigned to or removed from the component, the component informs the Transparency Layer about its HA state.
* When AMS assigns Active or Standby state to a component through CSI assignment, the component registers itself as active or standby for that logical address. AMS can perform a switchover or a failover of the Active component to a Standby and a new CSI is assigned to the standby but the CSI assigned earlier is not removed. The component must register itself as Active with the Transparency Layer in order to continue receiving messages.
* When a component is terminated or locked, AMS issues instructions for the removal of the CSI for the application. The component must deregister itself from the Transparency Layer for all logical addresses.
* When a message is sent, the Transparency Layer translates the logical address of the component to the physical address. Since the Transparency Layer is part of IOC, the translation is performed effectively.

=====Usage Scenario=====

Let us assume the following scenario to understand the concept of logical addressing. COMP A and COMP B are running on Node 1 and Node 2 respectively. COMP A is active and COMP B is standby component. The logical address and the physical address mappings of COMP A and COMP B on both the nodes is specified in Table [[#LogicaltoPhysicalAddressMapping|Logical to Physical Address Mapping]].


{| border="0" cellpadding="3"
|+ align="bottom" | '''Logical to Physical Address Mapping'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Nodes : Component : Logical Address
!style="color:#66b154; background:#09477c"| Physical Address Mapping
|- style="color:#ffffff; background:#549cc6"
|
'''Node 1''' : COMP A : 1
|
* [physical address of COMP A, hastate ACTIVE] The physical address of COMP A is registered with Transparency Layer when COMP A is started on Node 1.
* [physical address of COMP B, hastate STANDBY] This entry is synced up when COMP B is started on Node 2.
|- style="color:#ffffff; background:#549cc6"
|
'''Node 2''' : COMP B : 1
|
* [physical address of COMP B, hastate STANDBY] The physical address of COMP B is registered with Transparency Layer when COMP B is started on Node 2.
* [physical address of COMP A, hastate ACTIVE] This entry is synced up on Node 1 by COMP A when COMP B is started on Node 2.
|}

Thus, the logical address of both COMP A and COMP B are same. The physical address mappings along with HA state are synced up periodically. It is also synced up when the Transparency Layer is registered or deregistered, that is, during the state change of the component.

When the active COMP A is terminated, it deregisters its correponding physical address mapping in the IOC Transpancy Layer database. This triggers the sync up of the Transparency Layer on the other nodes and deregisters the entry of COMP A. The logical address 1 obtained from Name Service maps to the physical address of standby COMP B running on Node 2.

When AMS instantiates the standby COMP B and makes it as ACTIVE, the HA state of COMP B in IOC Transparency Layer database is changed from STANDBY to ACTIVE and the database is synced up as an IOC level broadcast in the cluster. The logical address 1 maps to the physical address of COMP B with ACTIVE HA state in the cluster.

When COMP B is terminated, its physical address mapping is deregistered. Since the database is synced up, database consistency is maintained across all nodes. Hence, whenever any component in any node wants to reach COMP A, it requests the logical address of COMP A from the Name Server and sends message using the logical address to attain location transparency.

The IOC Transparency Layer searches the database for mapping the logical address 1 of COMP A. This returns the ACTIVE physical address of COMP A which is used by the Transparency Layer to communicate with COMP A. Name Server assigns the logical address and IOC maps the logical address to the corresponding ACTIVE physical address through the Transparency Layer. The Transparency Layer is consistent across the cluster to manage the state change of the node or the component.

Doc:latest/sdkguide/overview

2010-08-27T03:43:30Z

Senthilk:

=='''Overview'''==

This chapter provides an introduction to OpenClovis SAFplus Platform and IDE, its key features, and the system architecture.

OpenClovis SAFplus Platform and IDE provides a modular, cost-effective application for creating next-generation communication systems. OpenClovis SAFplus Platform and IDE is designed for solution integrators, Network Equipment Manufacturers (NEPs), and Telecommunication Equipment Manufacturers (TEMs) to facilitate the creation of a broad range of telecommunication devices, including routers, switches, media gateways, and wireless infrastructure nodes.

OpenClovis fits seamlessly with various distributions of Linux and hardware platforms such as AdvancedTCA, BladeCenter T, and other off-the-shelf hardware.

'''OpenClovis Application Service Platform (SAFplus Platform)''' is a middleware that offers a comprehensive set of modular, portable, reusable software components designed to provide system management and high availability functionality. The OpenClovis SAFplus Platform is the run-time part of the OpenClovis offering. It provides run-time services for your value add applications, offering a layered, hardware-platform independent application environment.

'''OpenClovis Integrated Development Environment (IDE)''' is designed to simplify and accelerate the development of application service platforms for the telecommunication marketplace. Coupled with the OpenClovis SAFplus Platform, this intuitive software solution streamlines the process of specifying the information model, High Availability (HA) aspects and the communication infrastructure of a system. OpenClovis IDE stores all information describing a project in well defined XML files that can be modified by the user. Modeling of system resources and relationships are specified using a graphical UML editor.

'''Key Topics:'''
* [[#Benefits of OpenClovis SAFplus Platform and IDE | Benefits of OpenClovis SAFplus Platform and IDE]]
* [[#Key Features of OpenClovis SAFplus Platform | Key Features of OpenClovis SAFplus]]
* [[#Key Features of OpenClovis IDE | Key Features of OpenClovis IDE]]
* [[#Supported Hardware and Operating Systems | Supported Hardware and Operating Systems]]
* [[#OpenClovis Architecture | OpenClovis Architecture]]

===Benefits of OpenClovis SAFplus Platform and IDE===

OpenClovis solution offers the following benefits to its customers
* Enhances developer productivity
* Reduces time-to-market
* Ensures reusability of core development efforts
* Offers platform-independent modeling and implementation
* Increases development process consistency
* Facilitates Platform component integration
* Minimizes software footprint for optimized performance
* Supports a broad range of industry standards such as, Advanced Telecom Computing Architecture (ATCA), Carrier Grade Linux (CGL), and SA Forum Application Interface Specification (AIS)

===Key Features of OpenClovis SAFplus Platform===

The following are the key features of OpenClovis SAFplus Platform:
* '''Distributed''': Most SAFplus Platform components are implemented in a distributed way, instantiated on every node, providing local access to system data and taking care of reliable and consistent data replication across all system nodes.
* '''Modular''': The SAFplus Platform infrastructure suite is implemented as many independent SAFplus Platform service components, realized as user space processes and/or client libraries. Only needed components are loaded on a given node, avoiding unnecessary resource tie-down.
* '''Open Architecture''': SAFplus Platform components communicate with each other using well-defined, documented APIs. This allows arbitrary user applications to tap into the wide range of basic and advanced infrastructure services provided by SAFplus Platform. It also enables the extension or replacement of selected SAFplus Platform components by other proprietary or 3rd-party components.
* '''Standards Compliant''': OpenClovis APIs comply to applicable, available industry standards such as SA Forum AIS and HPI APIs, and IETF protocols like SNMP.
* '''Scalable''': Automatic, adaptive data replication across nodes. Single-blade solutions to large systems of chassis and rack-mount servers.
* '''Dependable''': SAFplus Platform components are written to be robust and highly available. This is realized by state replication (checkpointing), automatic restart and fault recovery and support for multi-version interoperability. All this minimizes down-time and allows the SAFplus Platform layer to be operational through planned and unplanned down-time, eliminating service interrupts due to single points of failure.
* '''Extensible Infrastructure''': All SAFplus Platform components expose open APIs, allowing easy extension of SAFplus Platform functionality. Some components use plug-ins (dynamically loadable modules) that allow for easy extensibility during design and also after deployment.
* '''Flexible Application Adaptation''': The OpenClovis infrastructure provides a wide range of options for porting applications. Options range from:
** No adaptation that is, still utilizing platform management capabilities of SAFplus Platform.
** Non-intrusive application porting that is, non-intrusive EOnization which requires no or very minimal changes to the existing application.
** Porting to SAFplus-based application development, when the application directly exploits the services provided by SAFplus Platform using SAFplus Platform APIs.
* '''Configuration Flexibility''': Configuration and customization options are available throughout the product life-cycle, specifically at system modeling time, target image build-time, boot-time, and run-time. Configuration and customization options in the system modeling and target image build-time are available only to system designers, while the boot-time and run-time are exposed to the final user who deploys the SAFplus-based system. The deployment configuration files are XML based and the build-time configuration files are C header files. Both types of files are typically generated from OpenClovis IDE.
* '''Location Transparency''': SAFplus Platform provides a generic scheme for using distributed resources with location transparency. This is further supported by logical addresses supported by SAFplus Platform communication layer. Refer IOC and TIPC for more details.
* '''Service Concurrency''': SAFplus Platform components export resources that can be simultaneously accessed by multiple, distributed clients, yet maintaining the consistency of the shared resources.
* '''Portable''': SAFplus Platform is built on a set of adaptation and abstraction layers that minimizes its direct dependency on any given operating system, hardware, or database system. This allows easy porting of both SAFplus Platform and SAFplus-based applications to new platforms.

===Key Features of OpenClovis IDE===

The following are the key features of OpenClovis IDE:
* '''Eclipse based IDE for System and Information Modeling''': Powerful, Eclipse-based graphical user interface for system modeling, information modeling, and SAFplus-based product development.
* '''UML Based''': Model components and their relationship such as containment, aggregation, and inheritance, are edited using a graphical UML editor.
* '''Projects Based''': Modeling work files are organized into projects. Many model artifacts are reusable across projects.
* '''Integrate with other IDE Tools''': Due to its Eclipse based nature, IDE can be integrated with other Eclipse based IDEs.

===Supported Hardware and Operating Systems===

The ''OpenClovis SDK'' follows the conventions of embedded system development, where the development host (on which much of the software development happens) is different from the actual target host (where SAFplus Platform and SAFplus-based applications run). Therefore, the supported hardware and operating systems, and also the environmental requirements are treated separately in the following sections.
This distinction is not enforced, and the development host can be used also as a target host, or vice versa, as long as the same host satisfies both sets of requirements.

[[File:OpenClovis_Note.png]] Supported systems and system requirements are subject to change without notice. Please consult with the ''OpenClovis SDK Release Notes'' for the most up-to-date information on supported systems and their requirements.

====Development Host====

The OpenClovis SDK can be installed and is tested to work on the following systems:



{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Supported Development Hosts'''
|- style="color:#ffffff; background:#549cc6"
|
Hardware
|
* Intel compatible PC (including CPUs with 64-bit extensions)
|- style="color:#ffffff; background:#549cc6"
|
Linux Distributions
|
* Red Hat Enterprise Linux 4
* Ubuntu 7.04, 7.10 Linux
* CentOS 4.x, 5.0
* Gentoo Linux
* Fedora Linux
|}

The system requirements for the development host are summarized in Table [[#Table_SysReq_DevHost|System Requirements for a Development Host]].

[[File:OpenClovis_Note.png]] During installation the OpenClovis SDK installer can reliably detect if any of the 3rd-party software packages listed below are not present on the development host or if their version do not satisfy the requirements. The installer will then install such packages onto the '''OpenClovis installation directory''', satisfying the SDK requirements, but without altering the system-installed software base on the development host. Refer to the ''OpenClovis Installation Guide'' for further information.



{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''System Requirements for a Development Host'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c" width="150"| Requirement Type
!style="color:#66b154; background:#09477c"| Requirements
|- style="color:#ffffff; background:#549cc6"
|
Hardware
|
* Intel Pentium II (or higher) or compatible AMD processors
* Hard Disk - 10 GB (minimum suggested)
* RAM - 512 MB (minimum suggested)
|- style="color:#ffffff; background:#549cc6"
|
Linux Distributions
|
* See ''Supported Development Hosts'' above
|- style="color:#ffffff; background:#549cc6"
|
 Third Party Packages
|
* glib-2.0 - 2.6.0
* glibc 2.3.2 or later
* gcc 3.2.3 or later
* beecrypt
* gdbm 1.8.0
* net-snmp 5.4
* openhpi 2.8.1
* openhpi-subagent 2.3.4
* Gtk
* Eclipse SDK 3.2.2
* EMF SDK 2.2.2
* GEF SDK 3.2.2
* JRE 1.5.0_03
* Python 2.4.1 or later
|}

====Target Hosts====

This section lists the supported (certified) target hardware and operating systems for target hosts to run ''OpenClovis SAFplus''. See Table [[#Table_SysReq_TargetPlatform|System Requirements for the Target Platform]] below.



{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''System Requirements for the Target Platform'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c" width="150"| Requirement Type
!style="color:#66b154; background:#09477c"| Requirements
|- style="color:#ffffff; background:#549cc6"
|
CPU Types
|
* Intel x386 compatible processors: Pentium III, Pentium M, Pentium 4, Xeon, AMD Opteron, and AMD Athlon, including processors with AMD64 extensions
* PowerPC processors: PowerQuicc III, PowerPC G4
|- style="color:#ffffff; background:#549cc6"
|
Hardware platforms
|
*'''AdvancedTCA Chassis'''
** Blades: Intel MPCBL0001, Intel MPCBL0030, Intel MPCBL0040, Intel MPCBL0050
** PowerPC-based base cards and AMC SBCs
** Shelf Management: Pigeon Point ShMM500 or Radisys Promentum 2100/2210 switch/shelf manager cards
*'''Rack Mount Servers and Desktop PCs'''
** Any PC satisfying the CPU and OS requirements
|- style="color:#ffffff; background:#549cc6"
|
 Linux Distributions
|
* Wind-River PNE LE 1.2 (2.6.10 kernel)
* Wind-River PNE LE 1.3 (2.6.14 kernel)
* Wind-River PNE LE 1.4 (2.6.14 kernel)
* Red Hat Enterprise Linux 4.0 (2.6.9.5 kernel)
* Ubuntu 7.04 Linux (i386 and x86_64)
* CentOS 4.x, 5.0 (i386 and x86_64)
* Gentoo Linux (i386 and x86_64)
* Fedora Linux (i386 and x86_64)
* Yellow Dog Linux 4
|}

In case of AdvancedTCA platforms satisfying the above shelf manager requirements is used, OpenClovis SAFplus Platform can be strongly integrated with the shelf manager, providing additional features and benefits in the area of system management and high availability.
Customers wishing to utilize such platform support need to acquire the OpenClovis ''Base Platform Support Package'' for AdvancedTCA platforms.
The same benefit is not available for platforms with no shelf management capabilities (unmanaged platforms).

[[File:OpenClovis_Note.png]] Additional standardized or customer specific hardware platforms can be supported using custom PSPs. Please contact OpenClovis for further information.

===OpenClovis Architecture===

The OpenClovis architecture comprises an extensive set of high-quality, modular and reusable software components and tools that are standards based and hardware and operating system (OS) agnostic. The hardware and software components communicate with each other through APIs, client libraries, and user space processes.

[[File:SDK_architecture_50_updated.png|frame|center| '''OpenClovis Architecture''' ]]

The comprehensive set of OpenClovis SAFplus Platform components can be broadly categorized into the following functional domains, as illustrated in Figure [[#Functional Scope of OpenClovis SAFplus Platform | Functional Scope of OpenClovis SAFplus]]:
* High Availability
* System Management
* Communication Infrastructure
* Basic Infrastructure

[[File:SDK_FunctionalScopeofSAFplus Platform.png|frame|center| '''Functional Scope of OpenClovis SAFplus''' ]]

====High Availability Domain====

Ensuring high availability across the network is a key concern in mission-critical telecom environments. OpenClovis architecture delivers a high degree of redundancy, delivering access to key services via three highly-resilient traffic handling and system recovery mechanisms.
* Availability Management Framework (AMF) controls the active and standby availability states of components that are providing a given service, and supports automatic failover according to user-configured policies. AMF organizes redundant components in various configurations, such as 1:1 and N+M.
* Checkpointing Service delivers redundant component synchronization of run-time data and context to ensure smooth failover if a fault occurs.
* Group Membership Service assists applications and other OpenClovis components to define, form, manage and monitor service groups.

Refer Chapter [[Doc:sdkguide/highavailability#High Availability | High Availability]] for more information.

====System Management Domain====

Another aspect of achieving mission-critical availability is providing comprehensive software and hardware component manageability.
* Provisioning Manager is a client module that is automatically bound to every software component that manages a software and/or hardware resource. Provisioning attributes are created and deleted as components start and terminate service.
* Alarm Manager provides an infrastructure for configuring alarms, and defining the actions to be taken when an alarm is generated.
* Fault Manager offers a hierarchical system for managing both hardware and software faults. Faults can be prioritized to ensure they are responded to in the order of their importance, and associated actions can be specified.
* Component Manager monitors the health and controls the life-cycle of all active service components executing within the system.
* Chassis Manager supervises the components of a chassis field replaceable units (FRUs), such as blades, AMCs, and PMCs. Capable of detecting hot-swapped modules, the system is able to receive instructions from other system resources.
* Mediation Library provides a unified interface to the external management protocols and services (CLI, SNMP) to control the configuration and operation of all managed objects within the system.
* Clovis Object Registry (COR) is a distributed, object-oriented database that captures and stores data on system-managed objects and the relationships between them. COR also manages the object life-cycle, transactions on multiple objects, object change notifications, and object change propagation across all the various distributed MOs.
* Transaction Manager provides an infrastructure library that uses transaction semantics to manage distributed data, enabling components that need to participate in a transaction to act as a resource manager.

Refer Chapter [[Doc:sdkguide/manageability#System Management | System Management]] for more information.

====Communication Infrastructure Domain====

OpenClovis SAFplus Platform is capable of pulling a cluster of computers together into one homogeneous system. In order to achieve this, it relies on numerous communication services, which are implemented as part of SAFplus Platform. These services are also offered to the applications that are built on top of SAFplus Platform.
* Event Manager provides a flexible, scalable, distributed service infrastructure for event notification across multiple blades, following a publish-subscribe model, where the publishers of events are unaware of the subscribers, and vice versa. It maintains a copy of the local subscriber database for resilient system recovery in the event of a server failure.
* Name Service provides storage and look-up for one-to-one mappings between the name of a service and its object reference. It replicates the name database across all nodes to allow efficient, scalable lookups between applications and the local name server.
* Remote Method Dispatch (RMD) provides remote function call semantics across application processes and nodes. It allows both synchronous and asynchronous calls, the latter supporting asynchronous message passing programming models. In both cases, marshaling and unmarshaling of C-level user data is provided by an XDR (eXternal Data Representation) layer, which can be autogenerated from Interface Description Language (IDL) files.
* Intelligent Object Communication (IOC) provides efficient transport for communication between Clovis Objects. It supports both reliable and unreliable modes of communication. The IOC layer currently utilizes TIPC as the underlying communication protocol, but it can be ported to other low-level IPC services.

Refer Chapter [[Doc:sdkguide/cominfrastructure#Communication Infrastructure | Communication Infrastructure]] for more information.

====Basic Infrastructure Domain====

OpenClovis SAFplus Platform consists of (and builds upon) a large number of basic services, all of which are offered to user applications. Three categories of basic infrastructure services are:
* Basic Services include logging service, execution object wrapper, OS abstratction layer, handle management, SAFplus Platform debug console, and timer library
* Memory Management includes a feature-reach low-level heap manager, and several higher-level services such as buffer management, queue library, circular list library, and container library
* Data Management comprises the database abstraction layer (DBAL) that provides an implementation agnostic API to access various database managers to store and retrieve data.

Refer Chapter [[Doc:sdkguide/basicinfrastructure#Basic Infrastructure | Basic Infrastructure]] for more information.

To summarize, OpenClovis SAFplus Platform provides an extensive set of high-quality, modular, portable, reusable software components that enable rapid integration of system management and high availability functionalities into next generation communication platforms. The use of these readily available components yields more controlled development risks, drastically reduced development time, and lower development costs.

Doc:latest/sdkguide

2010-08-27T03:41:56Z

Senthilk:

Table of contents:

* [[Doc:latest/sdkguide/preface | Preface ]]
* [[Doc:latest/sdkguide/overview | Overview ]]
* [[Doc:latest/sdkguide/highavailability | High Availability]]
* [[Doc:latest/sdkguide/manageability | System Management]]
* [[Doc:latest/sdkguide/cominfrastructure| Communication Infrastructure]]
* [[Doc:latest/sdkguide/basicinfrastructure| Basic Infrastructure]]
* [[Doc:latest/sdkguide/platform | Hardware Platform Support]]
* [[Doc:latest/sdkguide/lifecycle | Development Lifecycle with OpenClovis SDK]]
** [[Doc:latest/sdkguide/compconfig | OpenClovis SAFplus Platform Component Configuration]]
** [[Doc:latest/sdkguide/compdev | Developing Application Components in OpenClovis SAFplus Platform Environment]]
** [[Doc:latestsdkguide/debugging | Debugging EO Applications and SAFplus Platform Components]]
** [[Doc:latest/sdkguide/build | Building SAFplus Platform and SAFplus-based Systems]]
** [[Doc:latest/sdkguide/deploy | Deploying SAFplus Platform onto the Target]]
** [[Doc:latest/sdkguide/envvars | Runtime environmental variables exported by the OpenClovis SAFplus Platform environment]]
* [[Doc:latest/sdkguide/startermodels | "Starter" Models]]
* [[Doc:latest/sdkguide/commandref | Command Line and Environment Variable Reference ]]
* [[Doc:latest/sdkguide/knowledgebase | Knowledge Base (FAQ, Questions and Answers) ]]
* [[Doc:latest/sdkguide/troubleshooting | Troubleshooting ]]





* [[Doc:latest/sdkguide/glossary | Glossary of Terms]]

Doc:latest/sdkguide/preface

2010-08-27T03:37:45Z

Senthilk:

=='''Preface'''==

''OpenClovis Applications Service Platform (SAFplus Platform)'' is a modular, high-performance, scalable software platform (sometimes also referred to as ''middleware'') to facilitate the speedy development and run-time operation of highly-available and manageable communications systems.
SAFplus Platform has been primarily designed for complex, multi-processor, distributed systems, consisting of multiple processor cards or chassis, using heterogeneous CPU types and operating system versions.
SAFplus Platform has been fine-tuned for software applications that not only demand reliability and manageability, but also scalability and high performance.

In a typical SAFplus-enabled communication device, SAFplus Platform resides on every (or most) processor entities that need to be involved in the manageability and configuration of the device, or which need to perform redundant services in order to provide high availability.
On each of such processors SAFplus Platform is present in the form of a few run-time processes (daemons), while application-specific components that need to use any of the SAFplus Platform services communicate with these daemons using SAFplus Platform client libraries.
For most SAFplus Platform services, the SAFplus Platform middleware takes care of all needed inter-processor communication and data replication among the various processor entities, effectively tying these into one seamless cluster, hiding the inter-processor aspects from the SAFplus-based custom applications.

During development of an SAFplus-enabled communication system, system architects and software designers work with the ''OpenClovis Software Development Kit (SDK)''.
The SDK includes the ''OpenClovis Integrated Development Environment (IDE)'', a graphical user interface to define, model, and configure the system, as well as all the relevant source files, header files, run-time libraries, build tools that are needed to create, test, and debug the target system.

With this product, OpenClovis provides Original Equipment Manufactures (OEMs), Telecommuncations Equipment Manufacturers (TEMs) with an efficient and cost-effective solution for creating highly available, manageable products with short time-to-market.

This ''OpenClovis SDK User Guide'' provides system architects and software developers with further information about the OpenClovis SAFplus Platform and its companion SDK. It provides an overview of the SAFplus Platform architecture, the various SAFplus Platform components, and their interactions. This guide also helps you to understand how to work with the OpenClovis Software Development Kit (SDK) when modeling, configuring, building, and deploying SAFplus Platform and SAFplus Platform based applications on target systems.

===Audience===

''OpenClovis SDK User Guide'' is written for system architects, software designers, developers, and system integrators. To use this OpenClovis product, you must be aware of the fundamentals of operation, management, and configuration of telecommunication and networking systems. You must also be familiar with basic high availability concepts, C programming, UML notations, and have the basic knowledge of Linux.

===Documentation Conventions===

This user guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table:
{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Notation
!style="color:#66b154; background:#09477c"| Description
|- style="color:#ffffff; background:#549cc6"
| style="color:black" |<code><pre>Code</pre></code>
| This font denotes the C code provided in various examples.
|- style="color:#ffffff; background:#549cc6"
|
Cross reference
|
This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the User Guide or a URL link.
A cross reference refers to a section name accesses the first page of that section.
|- style="color:#ffffff; background:#549cc6"
|
'''Bold Text'''
|
Menu items and button names.
|- style="color:#ffffff; background:#549cc6"
|
''Italic Text''
|
Variables for which you enter values.
|}
 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Document Organization===

OpenClovis SDK User Guide is organized into various chapters to provide information on specific areas. The following table introduces the chapter names and a brief overview of the content.

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Chapter
!style="color:#66b154; background:#09477c"| Overview
|- style="color:#ffffff; background:#549cc6"
|
Chapter 1, Overview
|
This chapter helps you understand the conceptual information, advantages and key features of OpenClovis SAFplus Platform and IDE.
|- style="color:#ffffff; background:#549cc6"
|
Chapter 2, High Availability (HA)
|
This chapter provides an introduction to the basic concepts of HA and the relevant SAFplus Platform features and SAFplus Platform components, namely: Availability Management Framework (AMF), Checkpointing Service, and Group membership Service (GMS).
|- style="color:#ffffff; background:#549cc6"
|
Chapter 3, System Management
|
This chapter provides information about the various SAFplus Platform features and components for system management, such as: Clovis Object Registry (COR), Mediation Library, Transaction Service, Provisioning Library, Alarm Service, Chassis Management, and SNMP Sub-Agents
|- style="color:#ffffff; background:#549cc6"
|
Chapter 4, Communications Infrastructure
|
This chapter provides an overview of the features, services and relevant components of SAFplus Platform in the domain of inter-process and inter-processor data communication.
|- style="color:#ffffff; background:#549cc6"
|
Chapter 5, Basic Infrastructure
|
OpenClovis SAFplus Platform is built on a number of basic infrastructure elements, which are described in this chapter.
|- style="color:#ffffff; background:#549cc6"
|
Chapter 6, Hardware Platform Support
|
The specific benefits of the Platform Support Package, and its realization are described in this chapter.
|- style="color:#ffffff; background:#549cc6"
|
Chapter 7, Development Lifecycle and OpenClovis SDK
|
This chapter describes how the various SDK features fit in the workflow of a typical development life-cycle, and provides detailed information about the key phases, such as configuring, building, and deploying SAFplus-enabled systems.
|- style="color:#ffffff; background:#549cc6"
|
Chapter 8, "Starter" Models
|
This chapter summarizes the so-called starter models provided by OpenClovis to jump-start the development of your own application, as an alternative to starting from scratch.
|- style="color:#ffffff; background:#549cc6"
|
Appendix A, Glossary of Terms
|
This provides complete information about all the terms and definitions specific to OpenClovis SAFplus Platform and its components.
|}

===Related Documentation===

For additional information about the OpenClovis SAFplus Platform, SDK, and IDE, please refer to the following companion documents:
* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum specifications.
* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.
* '''OpenClovis Evaluation System User Guide''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''OpenClovis IDE User Guide''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''OpenClovis Log Tool User Guide''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.
* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

All the above document are available in both Portable Document Format (PDF) as well as a set of cross-referenced, browsable HTML pages. They can be found under the <code>/doc</code> subdirectory of the installed SDK (under the <code>/pdf</code> and <code>/html</code> subdirectories, respectively). Please refer to the installation guide for further information.

===OpenClovis Online Technical Support===

OpenClovis customers and partners can register on our website and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com Send your queries to: support@openclovis.com. Open source community support is available at:
http://www.openclovis.org/forum

===Documentation Feedback===

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to:
support@openclovis.com Post your feedback on documentation at: http://www.openclovis.org/forum

Doc:latest/ideguide

2010-08-27T03:37:11Z

Senthilk:

Doc:latest/logtoolguide

2010-08-27T03:36:03Z

Senthilk:

=='''Preface'''==

 ''OpenClovis Log Tool User Guide'' provides information about the usage of OpenClovis Log Tool.
OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. By analyzing this information, you can troubleshoot the errors. These log files are in raw format and hard to read. Log Tool allows you to format the files and filter them for the required entries.

===Documentation Conventions===

This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table:

{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Notation
!style="color:#66b154; background:#09477c"| Description
|- style="color:#ffffff; background:#549cc6"
|style="color:black" | <code><pre>Code</pre></code>
|
This font denotes various commands and their usage.
|- style="color:#ffffff; background:#549cc6"
|
Cross reference
|
This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the User Guide or a URL link.
A cross reference refers to a section name accesses the first page of that section.
|- style="color:#ffffff; background:#549cc6"
|
'''Bold Text'''
|
Menu items and button names.
|- style="color:#ffffff; background:#549cc6"
|
''Italic Text''
|
Variables for which you enter values.
|}

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Document Organization===

This guide is organized into various chapters to provide information on specific areas. The following table introduces the chapter names and a brief overview of the content.
{| border="0" cellpadding="3"
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Chapter
!style="color:#66b154; background:#09477c"| Overview
|- style="color:#ffffff; background:#549cc6"
|
Preface
|
This chapter gives an introduction to OpenClovis Log Tool.
|- style="color:#ffffff; background:#549cc6"
|
Available Tools
|
This chapter helps you understand the conceptual information, advantages and key features of OpenClovis Log Tools. It provides information to access the available Log Tools, Command Line Log Tool and Offline GUI Log Tool.
|}
 

===Related Documents===

For additional information about OpenClovis products, refer to the following guides:
* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.
* '''OpenClovis Evaluation System User Guide''' provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the ''OpenClovis Sample Application Tutorial'' as it builds on the example created in that document.
* '''OpenClovis SDK User Guide''' provides information about OpenClovis Application Service Platform (SAFplus Platform) architecture, various OpenClovis SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the OpenClovis SAFplus Platform code to build your custom application.
* '''OpenClovis IDE User Guide''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform platform. This guide helps you to understand how to use the various features of the IDE to build the application.
* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

===OpenClovis Online Technical Support===

OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum

===Documentation Feedback===

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Post your feedback on documentation at: http://www.openclovis.org/forum

=='''Available Log Tools'''==

Log files come in 2 flavors, binary and ASCII. ASCII files are easily viewable using standard Linux editors and tools (vi, emacs, tail, etc). By default OpenClovis writes all of its logs in ASCII format. However you may want to change this to binary format or create your own binary format logs. For the binary format logs OpenClovis provides access using following tools :
* [[#Using Command Line Log Tool | Command Line Log Tool ]]
* [[#Using Offline GUI Log Tool | Offline GUI Log Tool ]]

===Using Command Line Log Tool===

The online log viewer is a command line utility which may be used to view the Log Records present in the binary log files. The online log viewer only works on binary log files. To view an ASCII log file simply open them with your favorite editor.

The online log viewer displays the log records after some required conversion. It converts the Severity, StreamId, ComponentId to their corresponding names. This conversion is done using information present in metadata file (cfg file) corresponding to each log file. By default, the online log viewer displays the following fields of a log record:
# SeverityName
# StreamName
# ComponentName
# ServiceId
# MessageId
# TimeStamp
# Message

[[File:OpenClovis_Note.png]]Its very rare that log viewer does not find the stream id to stream name mapping in cfg file. If it does not then it would display the stream id in place of stream name. Same holds true for component id to component name mapping. In this situation it would not be possible to apply filter on that field.

Online log viewer executable <code>'''asp_binlogviewer'''</code> is deployed in <code>'''bin'''</code> directory of the SAFplus Platform. This online log viewer may be used in following ways :
<ol>

<li> To view log records present in a log file (or a set of log files when multiple log files are present for a logical log file) in real time i.e. when logging is going on. In this case it seeks to the latest record and starts displaying the record from that point (which can even be the last record of the log file). As the Log Server writes, this Log Tool tails the files and prints it to the Console. It automatically detects file rollover and tails the new file.
 '''Usage''':
<code><pre>
asp_binlogviewer -l <log_file_prefix>
[-f <filter>]
[-t <msg_id_map_file>]
[-p <num_prev_recs>]
[-c <column(s)>]
[-a] [-h|--help]
</pre></code>

<li>To convert a binary log file to its corresponding text file (this text file contains the log records in exactly the same format as it is displayed on the console) :
 '''Usage''':
<code><pre>
asp_binlogviewer -L <log_file_path>
[-C <cfg_file_path>]
[-t <msg_id_map_file>]
[-h|--help]
</pre></code>
[[File:OpenClovis_Note.png]]User may convert a binary log file to its corresponding text file when logging is going on as well as when it has stopped.

</ol>

====Viewing log records in real time====

=====Specify the location of log files=====

*<code>-l</code>: This is the mandatory option for viewing records in real time.

It is used to specify the common prefix to log files (symbolic links to log files) on file system. <code><log_file_prefix></code> is common prefix of log file names.

'''Example''':
 The log files are <code>/tmp/logFile.0</code> <code>/tmp/logFile.1</code> and <code>/tmp/logFile.2</code>.

'''Usage''':
<code><pre>
$ASP_BINDIR/asp_binlogviewer -l /tmp/logFile
</pre></code>

=====Setting Filter on a header field=====

*-f : User may specify filter on one of the header fields

<code><filter></code> should be specified as:

"<header field><comparision operator><value>"

'''\<header field\> options:'''

* s - SeverityName
* r - StreamName
* c - ComponentName
* v - ServiceId
* t - TimeStamp
* m - MessageId

'''\<comparision operator\> options:'''

* <code>=</code> Equal To
* <code>!=</code> Not Equal To
* <code><</code> Less Than
* <code><=</code> Less Than and Equal To
* <code>></code> Greater Than
* <code>>=</code> Greater Than and Equal To

'''Possible \<value\> in a filter:'''

'value' should be:

*String for following fields : SeverityName, StreamName, ComponentName
*HH:MM:SS for TimeStamp
*Integer for following fields : ServiceId, MessageId

'''Example''':
 Set filter on stream name (StreamName) 'CL_LOG_APPLICATION'

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l <log_file_prefix> -f "r=CL_LOG_APPLICATION"

For time stamp having value greater than 4.30pm...

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l <log_file_prefix> -f "t>16:30:00"

=====Specify TLV mapping file=====

*-t : This option is used when log files contain records of TLV (tag length value) format.

Specify complete path to TLV mapping file.

'''Example''':
 <code>tlvmap.txt</code> contains the TLV mapping for log records of log file /tmp/sys.0

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l /tmp/sys -t tlvmap.txt

Following is a sample TLV map file which contains message id to TLV message mapping. TLV File content should be in following format :
<code><pre>
Message_ID<space>Message containing %TLV
</pre></code>
where <code><space></code> is a single space.

[[File:OpenClovis_Note.png]]All the %TLV are replaced by their corresponding values from log record's tag, length, value information for that message id.

Following are the sample content of a TLV map file tlvmap.txt :
<code><pre>
5 Component %TLV was unble to start on node %TLV
6 State Change: Entity [%TLV] Operational State (%TLV -> %TLV) AMF (%TLV)
7 Registering Component %TLV via eoPort %TLV
8 Extending %TLV byte pool of %TLV chunkSize
</pre></code>

This file contains the message id to string mapping for TLV (tag lengh value) messages. '%TLV' of tlv strings are replaced by the corresponding value found in the log record.

=====Display previous log records=====

* -p: Display <code><num_prev_recs></code> previous log records and exit

<code><num_prev_recs></code> is the number of previous log records to be displayed. If user specifies a number greater than the maximum log records or number of log records actually present in all the log files then entire log is displayed.

'''Example''':
 View 10 previous records

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l <log_file_prefix> -p 10

=====Display only selected fields of Log Record=====

*-c : Display selected field(s) of Log Record

User may choose to display only selected fields of log record. This can be achieved by using -c option where the numbers are separated by ',' .

The default columns are :
# SeverityName
# StreamName
# ComponentName
# ServiceId
# MessageId
# TimeStamp
# Message

'''Example''':
 Display only the following fields: StreamName, ServiceId, TimeStamp

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l <log_file_prefix> -c 2,4,6

=====Display records present in entire log file(s)=====
*-a : Display entire log and exit

This option displays all the log records present in a log file or all log files when multiple log files are present for single logical file.

'''Example''':
 Display all the log records which file <code>/tmp/sys.0</code> contains

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -l /tmp/sys -a

====Convert a binary log file to text file====

=====Specify complete path to log file=====

* -L : <log_file_path> is complete path to a log file.

* -C : <cfg_file_prefix> is prefix to cfg (metadata) file. This is an optional argument which is required when log file name and prefix of cfg file are different.

* -t : If log file contains TLV messages then please specify TLV file path using this option.

If log file is <code>/tmp/logFile</code> the corresponding text file will be <code>/tmp/logFile.txt</code>

'''Example''':
 When log file name and prefix of cfg files are the same (log file is <code>/tmp/sys_2007-04-18T18:58:36</code> and cfg file is <code>/tmp/sys_2007-04-18T18:58:36.cfg</code>) :

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -L /tmp/sys_2007-04-18T18:58:36

'''Example''':
 When log file name and prefix of cfg files are different (log file is <code>/tmp/sys_2007-04-18T18:58:37</code> and cfg file is <code>/tmp/sys_2007-04-18T18:58:36.cfg</code>) :

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -L /tmp/sys_2007-04-18T18:58:37 \
-C /tmp/sys_2007-04-18T18:58:36

====For detailed help use --h or --help====

*--help | -h : Display help and exit

'''Usage''':
$ASP_BINDIR/asp_binlogviewer -h

$ASP_BINDIR/asp_binlogviewer --help

====Command line log tool Output Format====

As the Log Server writes, this Log Tool tails the files and prints it to the Console. It automatically detects file rollover and tails the new file.

The output is of the form:

<code><pre>
SEVERITY STREAMNAME COMPONENTNAME SERVICEID MESSAGEID TIMESTAMP MESSAGE
</pre></code>

For example,

<code><pre>
DEBUG applogs cpmServer_SysController_1 10 0 {Mon Jan 22 17:41:08 2007} \
( 0x6d 0x53 0x27 0x2a 0x97 0x22 0x1e 0x34 )
</pre></code>

where,

*<code>Debug</code> is the Severity
*<code>applogs</code> is the Stream Name
*<code>cpmServer_SysController_1</code> is the Component Name
*<code>10</code> is the Service ID
*<code>{Mon Jan 22 17:41:08 2007}</code> is the Time Stamp
*<code>0</code> is the Message ID which indicates that it is BUFFER type Binary Message. Message ID 1 is for ASCII message and it is not supported by log viewer, Message IDs other than 0 and 1 are of TLV type Binary Message.
*<code>( 0x6d 0x53 0x27 0x2a 0x97 0x22 0x1e 0x34 )</code> This is the hex value of each message byte separated by a space.
*online log viewer doesn't interpret the message part in case of BUFFER type records, it simply prints each byte of the message.
 

===Using Offline GUI Log Tool===

OpenClovis Offline Log Tool is an interactive GUI utility that allows you to view log files in a readable format and provides support for navigation, filtering and sorting of the log records. The Offline Log Tool only works on binary log files. To view ASCII log file simply open them with your favorite editor.

====Getting Started====

This provides information to launch the GUI Log Tool and helps you familiarize with its features.

=====How To Launch? =====

The Log Tool is installed in the <code>'''<installation_directory>/sdk-3.0/bin'''</code> directory during OpenClovis SDK installation.

If you have created the symbolic links during OpenClovis SDK installation, execute the following command:
<code><pre># cl-log-viewer</pre></code>

If you have not created the symbolic links during OpenClovis SDK installation, go to the <code>'''<installation_directory>/sdk-3.0/bin'''</code> directory and execute the following command:
<code><pre># cl-log-viewer</pre></code>

Alternatively, you can go to the <code>'''<installation_directory>/sdk-3.0/logviewer'''</code> directory and execute the following command:
<code><pre># ./logViewer.sh</pre></code>

Using 'cl-log-viewer' approach to launch the Log Tool is encouraged.

The '''Log Tool''' window is displayed.

[[File:LogTool_MainWindow.jpg|frame|center|'''Log Tool Main Window''']]
 

* [[#Using Menus | Using Menus]]
* [[#Using Toolbar | Using Toolbar]]

=====Using Menus=====

Log Tool has the following three menus:
* '''File''' - The File menu has options that allow you to open a file, close the current open file, close all open files, and exit the tool.
* '''Tools''' - The Tools menu has options that allow you to create and save filters, access the saved filters, and configure settings for the filter location and the mapping file.
* '''Help''' - The Help menu provides information about the Log Tool.

=====Using Toolbar=====

The add-on icons for the Log Tool are as shown.

[[File:LogTool_ToolBar.jpg|frame|center| '''Log Tool Toolbar''']]
* '''Open Stream''' icon - Use this icon to open a Log file.
* '''Close Stream''' icon - Use this icon to close a Log file.
* '''Create Advanced Filter''' icon - Use this icon to create, apply, and save filters.
* '''Saved Filters''' - Use this icon to apply the saved filter to a set of records.
* '''Exit Log Tool''' - Use this icon to close the '''Log Tool''' window.
 

====Viewing Log Files====

This section provides information to open log files, use filters to customize views, configure the user directory, and mapping file locations.

'''Key Topics''' :
* [[#Opening Log File | Opening Log File]]
* [[#Sorting Log Records | Sorting Log Records]]
* [[#Navigating Log Records | Navigating Log Records]]

=====Opening Log File=====

To open a Log file:

<ol>
<li>From the '''File''' menu, click '''Open''' or press '''Ctrl+O'''. The '''File Selection Dialog''' dialog box is displayed.
[[File:LogTool_FileSelectionDialog.jpg|frame|center|'''File Selection Dialog''']]
<li>Enter the following:
* '''Log File''' - Click '''Browse'''. The '''Select Log File''' dialog box is displayed. Specify the binary Log file that you need to view. The log file has the log records in the binary format. Click '''OK'''. The '''Select Log File''' dialog box closes.
[[File:LogTool_SelectLogFile.jpg|frame|center| '''Select Log File''' ]]
* '''Config File''' - Click '''Browse'''. The '''Select Config File''' dialog box is displayed. Specify the configuration file that configuration data (such as record length, component ID mapping, and stream ID mapping) for the log file. Click '''OK''' . The '''Select Config File''' dialog box closes.
[[File:LogTool_SelectConfigFile.jpg|frame|center|'''Select Config File''']]
<li>In the '''File Selection Dialog''' dialog box, click '''OK'''. The selected Log file opens in the '''Log Tool''' window.
</ol>

Validations are performed to check if you have specified the correct files. If the files are not correct, the corresponding error message is displayed.
[[File:LogTool_OpenedLogFile.jpg|frame|center|'''Opened Log File''']]

=====Sorting Log Records=====

You can click each column header to sort the entries. Every time you click the column header, the direction of sorting changes. Sorting is applicable for the current batch of records only.

=====Listing Log Records=====

The following options are provided for listing Log Records:
* Click '''First''' to view the first batch of records.
* Click '''Next''' to view the next batch of records.
* Click '''Previous''' to view the previous batch of records.
* Click '''Last''' to view the last batch of records.

====Using Filters====

This chapter provides information on using basic filter, creating and saving filter and using saved filters.

A typical log file generally contains large number of entries. When you need to troubleshoot a problem, only certain entries may be relevant. For example, you may need to view logs with severity level 3. You can use filters to view the log file based on certain criteria to create customized views. You can also save the filter criteria and use it at a later time.

'''Key Topics''' :
* [[#Using Basic Filter | Using Basic Filter]]
* [[#Creating and Saving Filter | Creating and Saving Filter]]
* [[#Using Saved Filter | Using Saved Filter]]

=====Using Basic Filter=====

Basic filter comprises the drop-down lists available in the '''Log Tool''' window.

To filter records using the basic filter:
<ol>

<li>From the first drop-down list, select the filtering option. The options available are:
* Record Number
* Severity
* StreamId
* ComponentId
* ServiceId
* TimeStamp
* MessageId
* Message

<li>From the second drop-down list, select the type of filtering. The options in this list is displayed based on your selection in the first drop-down list.

<li>Based on these two selections, you can perform one of the following:
* In the text box, enter the filter criteria.
* In the value selector, specify a value.

If you select '''TimeStamp''' as the filter type in the first drop-down list, you need to specify the date and the time as the values.

<li>Click '''Filter'''. The records are filtered and displayed based on the specified criteria.
Figure [[#Filtered List | Filtered List]] shows the records filtered based on Severity 2.
[[File:LogTool_FilteredList.jpg|frame|center|'''Filtered List''']]

<li>Click '''Clear''' to clear the applied filter and display the records from the start of the file.
</ol>

The following table provides information about the various filter options and the types:

{| align="center" border="0" cellpadding="3"
|+ align="bottom" | '''Filter Options and Types'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Filter Option
!style="color:#66b154; background:#09477c"| Filter Type
|- style="color:#ffffff; background:#549cc6"
|Message
|
* Is
* Is Not
* Contains
* Does Not Contain
* Starts With
* Does not start with
* Ends With
* Does not End With
|- style="color:#ffffff; background:#549cc6"
|
Severity
 
StreamId
 
ComponentId
 
ServiceId
 
TimeStamp
 
Record Number
 
MessageId
|
* =
* <
* >
* <=
* >=
* Between
* Range
|}

=====Creating and Saving Filter=====

You can create and save filters so that you can apply the saved filters to a set of records at a later time.

To create a filter:
<ol>
<li>From the '''Tools''' menu, click '''Advanced Filter''' or press '''Ctrl+F'''. The '''No previous Filter''' dialog box is displayed if you are creating a filter for the first time. Otherwise, the '''Advanced Filter''' window is displayed.
[[File:LogTool_NoPreviousFilter.jpg|frame|center|'''No Previous Filter''']]

<li>Click '''OK'''. The '''Advanced Filter''' window is displayed.
[[File:LogTool_AdvancedFilter.jpg|frame|center|'''Advanced Filter''']]

<li>Enter the following information:
* '''Filter Name''': This is the name for the new filter.
* '''Filter Type''': Select the type of the filter. The available options are:
** AND - Select this option if you need all the criterion to be satisfied.
** OR - Select this option if at least one of the criteria has to be satisfied.
* Click '''Create Filter Criterion''' to specify the criterion in the drop-down lists.
* From the first drop-down list, select the filtering option.
* From the second drop-down list, select the type of filtering. The options in this list is displayed based on your selection in the first drop-down list.
* Based on these two selections, in the text box, enter the filter criteria or specify a value. If you select '''TimeStamp''' as the filter type in the first drop-down list, you need to specify the date and the time as the values.

<li>Click '''Apply''' to apply the filter to the existing records.
<li>Click '''Save''' to save the filter.
</ol>

Click '''Remove''' to remove a filter criteria.

Click '''Cancel''' to cancel creating the filter.

=====Using Saved Filter=====

To use a saved filter:
<ol>
<li>From the '''Tools''' menu, click '''Saved Filters''' or press '''Ctrl+S'''. The '''Saved Filter''' dialog box displays the list of saved filters. [[File:LogTool_SavedFilters.jpg|frame|center|Saved Filters]]

<li>Select the filter that you need to apply and click '''Apply'''. The selected filter is applied to the existing records.

<li>To add more filters, click '''Add'''. The '''Advanced Filter''' window is displayed. For information to create and save a filter, refer to the section [[#Creating and Saving Filter | Creating and Saving Filter]].

<li>To remove a saved filter, select the filter and click '''Remove'''. The selected filter is removed from the list.

<li>Click '''OK''' to close the '''Saved Filters''' dialog box.

<li>Click '''Cancel''' to cancel the process of applying a saved filter.
</ol>

====Configuring User Directory and Mapping File Location====

To configure the location for user-defined filters and mapping files:
<ol>
<li>From the '''Tools''' menu, click '''Settings''' or press '''Ctrl+T'''. The '''Settings''' window is displayed.
[[File:LogTool_ConfigureLocation.jpg|frame|center|'''Settings''']]

<li>Enter the following information:
* '''User Directory''': This is the directory where the created filters are saved. This must be an existing directory.
* '''TLV Mapping File''': This is the directory where the mapping file for the MessageId is stored. A log file represents the MessageIds in a sequence of bytes. The mapping file contains the string representation for these MessageIds. If you specify a mapping file, then the corresponding string representation for the MessageId is displayed when you open the Log file using the Log Tool. If you do not specify the mapping file, then the MessageId is displayed as a sequence of bytes.
<li>Click '''Apply''' to apply the configured locations to the current open Log file.
<li>Click '''OK''' to save the settings.
</ol>

Click '''Restore Defaults''' to restore the default locations.

Click '''Cancel''' to cancel the settings.

====Closing Log File(s)====

To close a Log file, from the '''File''' menu, click '''Close''' or press '''Ctrl+C'''. The Log file that is currently open is closed.

To close all open Log files, from the '''File''' menu, click '''Close All''' or press '''Ctrl+Shift+C'''. All Log files that are open are closed.

====Exiting Log Tool====

To exit from Log Tool, from the '''File''' menu, click '''Exit''' tor press '''Ctrl+X''' . The '''Log Tool''' window closes.

Doc:latest/evalguide/app ide

2010-08-27T03:33:42Z

Senthilk:

==Appendix A: OpenClovis IDE==

OpenClovis IDE is an Integrated Development Environment designed to simplify and accelerate the development of software with the OpenClovis SDK. It provides a simple and powerful mechanism with easy drag-and-drop features, to create Resources and Components, define attributes and relationships between them. The OpenClovis IDE graphical interface enables you to capture the Information Models through UML notifications and save them as XML files.

This Appendix is only a brief introduction to the IDE and only provides basic information on how to
*start the OpenClovis IDE
*view the model which was used to build the the skeleton code for csa101 to csa113
*generate code based upon the model.

Further information concerning the IDE and creating a model can be found within the ''OpenClovis IDE User Guide'' and ''OpenClovis Sample Application Tutorial''.

As previously mentioned, this appendix assumes you have followed the instructions found in the document ''OpenClovis Installation Guide,'' and installed the SDK. After installing the SDK, we need to create a project area. You may have already created a project area either by the command <code>cl-create-project-area</code> or <code>cl-eval-wizard</code>. Again to prevent the repetition of data we suggest looking at section [[Doc:Evalguide/build#Evaluation Wizard - Single Node Setup|Evaluation Wizard - Single Node Setup]] and [[Doc:Evalguide/build#Manually Building the Target Images|Manually Building the Target Images]].

===Scope===

This appendix covers instructions to start the OpenClovis IDE and introduce you to the evaluation model that forms the foundation of the Evaluation System. You will be able to see how the values set for Clovis Sample Applications, affect the source code generated and behavior.

Instructions are provided to generate source code. Once the code is generated you have the opportunity to see how we enhanced the generated source code to create the Clovis Sample Applications which were run in Chapter [[Doc:Evalguide/csa#Sample Applications|Sample Applications]].

Although the generated code provides a framework for the Sample Applications without any functionality, instructions are provided on how to configure, build and start SAFplus Platform.

===Starting the IDE===

If you chose to create symbolic links during installation, from the command line enter <code>cl-ide</code> to launch OpenClovis IDE. Otherwise, from the command line you can either:
<ul>
<li>Add the installation directory to the shell's search path. For example with a bash shell,
<code><pre>export PATH=$PATH:$install_dir/sdk-3.0/bin</pre></code>
or
<li>Execute the command
<code><pre><install_dir>/sdk-3.0/bin/cl-ide</pre></code>
</ul>

The splash screen for OpenClovis IDE is displayed followed by the Workspace Launcher, as presented in Figure [[#eval_IDEWorkspaceLauncher|OpenClovis IDE Workspace Launcher]].


[[File:eval_IDEWorkspaceLauncher.png|frame|center|'''OpenClovis IDE Workspace Launcher''']]

Within the '''Workspace''' field the default location of the workspace of IDE is placed. This is the location where information concerning the IDE and models created is saved. This can be altered by pressing the '''Browse''' button. Select the workspace directory and click OK to launch OpenClovis IDE as illustrated in the Figure
[[#eval_IDEWelcomeScreen|OpenClovis IDE Welcome Screen]].


[[File:eval_IDEWelcomeScreen.png|frame|center|'''OpenClovis IDE Welcome Screen''']]

===Importing the Evaluation Model===

First, we need to import the model.


[[File:eval_ImportEvalModel.png|frame|center|'''Importing Evaluation Model into Eclipse Workspace''']]

The Clovis Works model is now presented within the Clovis Workspace View. To, view the Resource Editor, right click on '''eval''' -> select '''Clovis''' -> select '''Resource Editor.''' For the Component Editor right click on '''eval'''-> select '''Clovis''' -> select '''Component Editor.''' The Resource and Component Editor views will now be presented. See Figures below.


[[File:eval_IDEComponentView.png|frame|center|'''Component View''']]


[[File:eval_IDEResourceView.png|frame|center|'''Resource View''']]

This is the Evaluation Model used as the foundation of our Evaluation System. From here you have the opportunity to explore the model in its entirety. To understand how to navigate the IDE please refer to the OpenClovis IDE User Guide.

===Generating Source Code===

To generate source code a number of steps are required. Firstly the location of SAFplus Platform and Python needs to be correct.


[[File:eval_IDEASPPython.png|frame|center|'''Set SAFplus Platform and Python Location''']]

<ul>
<li>'''SAFplus Platform Location''':
 This usually appears by default. This is the location where the SAFplus Platform source code is installed. The default location is usually
 <code><install_dir>/sdk-3.0/src/SAFplus Platform</code>.

<li>'''Python Location''':
 Again the location of Python 2.4.2 should appear by default. If this is not the case python can be located within
 <code><installation-directory>buildtools/local/bin</code>
 The default <code><installation-directory></code> is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. This is determined during the installation of the SDK.
</ul>

Once we are certain the locations of SAFplus Platform and Python 2.4.1 are correct we can now generate the code.
#Within the '''Clovis Workspace View''' highlight '''eval;''' and right click to present a menu.
#Within the menu select '''Generate Source.'''
#A '''Project Validation''' pop up window is displayed with the message: '''''eval model has errors/warnings. Do you want to continue?''''' Press '''OK'''

Once '''OK''' is pressed the XML and source code is generated and placed within
<project-area_dir>/eval

You will now be able to view this generated source code within
<project-area_dir>/eval/src

You have the opportunity to compare how we built upon the generated code to further develop the Clovis Sample Application found within Chapter [[Doc:Evalguide#Sample Applications|Sample Applications]].

===Configuring & Building Generated Code, and Starting SAFplus Platform===

Once the code for the eval model is generated, the first choice you will have to make is decide which hardware setup to run the generated code. This information can be found within is discussed in full within Chapter [[Doc:Evalguide/setup#Runtime Hardware Setup|Runtime Hardware Setup]].

The next logical step is to configure and build this code. There are two methods of doing this, the first via the OpenClovis IDE, as covered within the ''OpenClovis Sample Application Tutorial''.

The second method, as discussed earlier, is via the command line. As you already have this document open we suggest looking again at Chapter [[Doc:Evalguide/build#Building the Evaluation System and Deploying Runtime Images|Building the Evaluation System and Deploying Runtime Images]]:

<ul>
<li>[[Doc:Evalguide/build#Modifying the Clovis Sample Applications|Modifying the Clovis Sample Applications]]
 Provides instructions on modifying the generated code.

<li>[[Doc:Evalguide/build#Building SAFplus Platform and the Evaluation System|Building SAFplus Platform and the Evaluation System]]
 Provides details on how to configure and build SAFplus Platform and the generated model. One small difference here is that when we run <code><install_dir>/sdk-3.0/src/SAFplus/configure -with-model-name</code> it should be run with the generated eval model. E.g.:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure \
--with-asp-build --with-model-name=eval
</pre></code>

<li>[[Doc:Evalguide/build#Configuration file - target.conf|Configuration file - target.conf]]
 The Hardware Setup choice you made will be required here in setting up the target.conf file

<li>[[Doc:Evalguide/build#Building Single/Distributed Target Image(s)|Building Single/Distributed Target Image(s)]]
 Lists commands required to build the target images.

<li>[[Doc:Evalguide/build#Content of Target Images|Content of Target Images]]
 Provides details of the content of the target images for both the singe and distributed setups.

<li>[[Doc:Evalguide/build#Runtime Software Installation|Runtime Software Installation]]
 Once the images have been created this section provides information on how these can be copied to the target.

Once the images are copied to their targets we now have to start/stop SAFplus Platform. This is discussed within Section [[Doc:Evalguide/csa#Starting and Stopping SAFplus|Starting and Stopping SAFplus]].
</ul>

===Running the Sample Applications===

The sample applications can be run via the SAFplus Platform Console, however, as the code is simply generated from the IDE nothing will happen.

===Summary and Next Steps===

This appendix provided you with specific steps to open the OpenClovis IDE, import and open the Evaluation Model and generate the source code.

Doc:latest/evalguide/csasum

2010-08-27T03:32:34Z

Senthilk:

==Summary and Next Steps==

This chapter has provided a number of sample applications that aimed to provide you with a better understanding of the OpenClovis SDK. To gain further information there are a number of documents you may wish to read. To gain further knowledge on the IDE and create a model read the ''OpenClovis Modeing Tutorial'' or for more in depth information on the SDK read the ''OpenClovis SDK User Guide'' and ''OpenClovis API Reference Guide''.

Doc:latest/evalguide/dhaDemo

2010-08-27T03:31:49Z

Senthilk:

==Dynamic HA Evaluation Guide==

===Objective===

This sample application demonstrates dynamic HA (High Availability) functionality. The application has two components : dhaDemo and dummyComp
*dhaDemo creates/deletes the AMF entities (SG, SI, CSI, SU, Component, etc) dynamically.
*dummyComp is a sample SAF component whose binary(executable) will be used while launching the dynamically created component.

===What you will learn===

*How to create a 2N model dynamically by creating/deleting various AMF entities using Clovis AMF management APIs related to Dynamic HA.

===Building the dynamic HA model (dynamicHaDemo) and deploying runtime images===

The Clovis dynamic HA Application is located in : <install_dir>/sdk-3.1/src/examples/dynamicHaDemo

You need to build the model and deploy the runtime images for following nodes : SysCtrlI0, WorkerI0, WorkerI1

It can be done in very similar manner to evaluation system model (eval). For more information about building and deploying a model, please refer to the following section of evalguide: 
Building the Evaluation System and Deploying Runtime Images

===Code===

The application code can be found within the following directory
<project-area_dir>/dynamicHaDemo/src/app/dhaDemo

This sample component is implemented in a single C module (clCompAppMain.c).

====Start/Stop the application====

The <code>clCompAppAMFCSISet()</code> function is called to set the component's HA state, and the following block of code assigns this requested state to the component, while verbosely detailing this process:

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

switch ( haState )
{
case SA_AMF_HA_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/
clprintf(CL_LOG_SEV_NOTICE, "Starting dynamic HA demo.");
clprintf(CL_LOG_SEV_NOTICE, "It will create 2N SG : %sSG", BASE_NAME);
rc = clDhaDemoStart();
if(rc != CL_OK)
{
clprintf(CL_LOG_SEV_CRITICAL, "Failed to start dynamic HA demo.");
}

/*
* ---End_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

* clDhaDemoStart() will start the workload in a separate thread to create the AMF entities (SG, SI, CSI, SU, Components, etc) when the HA state of dhaDemo becomes ACTIVE. In this case dhaDemo will be assigned active state when you unlock the SG 'dhaDemoSG'

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

case SA_AMF_HA_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

rc = clDhaDemoStop();
if(rc != CL_OK)
{
clprintf(CL_LOG_SEV_CRITICAL, "Failed to stop dynamic HA demo.");
}

/*
* ---END_APPLICATION_CODE---
*/

saAmfResponse(amfHandle, invocation, SA_AIS_OK);
break;
}

</pre></code>
|}

* clDhaDemoStop() will start the workload in a separate thread to delete the AMF entities (SG, SI, CSI, SU, Components, etc) only if they are already created, when the HA state of dhaDemo becomes QUIESCED or QUIESCING. In this case dhaDemo will be get QUIESCED state when you lock the unlocked SG 'dhaDemoSG'

====Create/Delete the AMF entities====

* clDhaDemoCreate() contains the code to create various AMF entities dynamically.

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

rc = clAmsMgmtInitialize(&mgmtHandle, NULL, &version);
if(rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "AmsMgmt initialize returned [%#x]", rc);
return NULL;
}

clDhaExmpExec(("Running MGMT CCB initialize"),
(rc = clAmsMgmtCCBInitialize(mgmtHandle, &ccbHandle)) == CL_OK,
("MGMT CCB initialize returned [%#x]", rc),
goto out1);

/*
* Create the entities only if they are not created already
*/
entity.type = CL_AMS_ENTITY_TYPE_SG;
snprintf(entity.name.value, sizeof(entity.name.value), "%sSG", pBaseName);
entity.name.length = strlen(entity.name.value)+1;

rc = clAmsMgmtEntityGetConfig(mgmtHandle,
&entity,
&pEntityConfig);

clHeapFree(pEntityConfig);

if(rc == CL_OK)
{
clprintf(CL_LOG_SEV_INFO, "Not creating SG[%sSG], it already exist", pBaseName);
goto out2;
}

/* SG doesn't exist, create SG and other entities dynamically*/

/*First create the service hierarchies*/

clprintf(CL_LOG_SEV_NOTICE,
"Creating 2N SG [%sSG] and other entities(si, csi, su, comp, etc)",
pBaseName);

/* Create SG*/
entity.type = CL_AMS_ENTITY_TYPE_SG;
snprintf(entity.name.value, sizeof(entity.name.value),
"%sSG", pBaseName);
entity.name.length = strlen(entity.name.value)+1;

clDhaExmpExec(("Creating SG [%s]",
entity.name.value),
(rc = clAmsMgmtCCBEntityCreate(ccbHandle,
&entity)) == CL_OK,
("SG create returned [%#x]", rc),
goto out2);

/* Create SI*/
entity.type = CL_AMS_ENTITY_TYPE_SI;
snprintf(entity.name.value, sizeof(entity.name.value),
"%sSI", pBaseName);
entity.name.length = strlen(entity.name.value)+1;
clDhaExmpExec( ("Create SI [%s]", entity.name.value),
(rc = clAmsMgmtCCBEntityCreate(ccbHandle, &entity)) == CL_OK,
("SI create returned [%#x]", rc),
goto out2);

...
...
...

/* CCB Commit*/
clDhaExmpExec(("CCB Commit Create"),
(rc = clAmsMgmtCCBCommit(ccbHandle)) == CL_OK,
("CCB commit returned [%#x]", rc),
goto out2);

...
...

</pre></code>
|}

* clDhaDemoDelete() contains the code to delete the created AMF entities dynamically.

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

rc = clAmsMgmtInitialize(&mgmtHandle, NULL, &version);
if(rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "AmsMgmt initialize returned [%#x]", rc);
return NULL;
}

clDhaExmpExec(("Running MGMT CCB initialize"),
(rc = clAmsMgmtCCBInitialize(mgmtHandle, &ccbHandle)) == CL_OK,
("MGMT CCB initialize returned [%#x]", rc),
goto out1);

/*
* Delete the entities only if they exist
*/
entity.type = CL_AMS_ENTITY_TYPE_SG;
snprintf(entity.name.value, sizeof(entity.name.value), "%sSG", pBaseName);
entity.name.length = strlen(entity.name.value)+1;

rc = clAmsMgmtEntityGetConfig(mgmtHandle,
&entity,
&pEntityConfig);
clHeapFree(pEntityConfig);
if(rc != CL_OK)
{
clprintf(CL_LOG_SEV_INFO, "Not deleting SG[%sSG], SG config get returned [%#x]", pBaseName, rc);
goto out2;

}

/* SG exist, Delete SG and other entities dynamically*/

clprintf(CL_LOG_SEV_NOTICE,
"Deleting SG [%sSG] and other entities(si, csi, su, comp, etc)",
pBaseName);

/*First move entities to lock instantiated mode*/
clDhaExmpExec(("LockI AMS entities"),
(rc = clAmsMgmtTestLockI(mgmtHandle, ccbHandle, pBaseName)) == CL_OK,
("Unlock AMS entities returned [%#x]", rc),
goto out2);

...
...

/* Delete SI*/
entity.type = CL_AMS_ENTITY_TYPE_SI;
snprintf(entity.name.value, sizeof(entity.name.value),
"%sSI", pBaseName);
entity.name.length = strlen(entity.name.value)+1;
clDhaExmpExec( ("Delete SI [%s]", entity.name.value),
(rc = clAmsMgmtCCBEntityDelete(ccbHandle, &entity)) == CL_OK,
("SI delete returned [%#x]", rc),
goto out2);

/* Delete SG*/
entity.type = CL_AMS_ENTITY_TYPE_SG;
snprintf(entity.name.value, sizeof(entity.name.value),
"%sSG", pBaseName);
entity.name.length = strlen(entity.name.value)+1;
clDhaExmpExec(("Deleting SG [%s]",
entity.name.value),
(rc = clAmsMgmtCCBEntityDelete(ccbHandle,
&entity)) == CL_OK,
("SG delete returned [%#x]", rc),
goto out2);

/* CCB Commit*/
clDhaExmpExec(("CCB Commit Delete"),
(rc = clAmsMgmtCCBCommit(ccbHandle)) == CL_OK,
("CCB commit returned [%#x]", rc),
goto out2);

...
...

</pre></code>
|}

====Usage of AMF management APIs for Dynamic HA====

The detailed documentation of AMF management APIs can be found in "OpenClovis API Reference Guide". Please refer "Availability Management Service" section under the High Availability.

===How to Run dhaDemo application and What to Observe===

We will use the SAFplus Platform Console to manipulate the administrative state of the dhaDemoSG service group.

<ol>

<li>Start the SAFplus Platform on all deployed nodes<code><pre>
# cd /root/asp/
# ./etc/init.d/asp start</pre></code>

<li>Start the SAFplus Platform Console<code><pre>
# cd /root/asp/bin
# ./asp_console</pre></code>

<li>Then put the dhaDemoSG service group into lock assignment state using the following commands.<code><pre>
# cli[Test]-> setc master
# cli[Test:SysCtrlI0]-> setc cpm
# cli[Test:SysCtrlI0:CPM]-> amsLockAssignment sg dhaDemoSG
</pre></code>

The logs for dhaDemo application will be logged into file <code>/root/asp/var/log/app.0</code> on node WorkerI0. Viewing these application logs using the <code>tail -f</code>, you should see the following :

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/app.0
|-
|<code><pre>

Wed Sep 3 16:03:02 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00031 : INFO) Component [dhaDemo] : PID [21785]. Initializing

Wed Sep 3 16:03:02 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00032 : INFO) IOC Address : 0x3

Wed Sep 3 16:03:02 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00033 : INFO) IOC Port : 0x80

</pre></code>
|}

<li>To create the AMF entities dynamically, unlock the dhaDemoSG service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SysCtrlI0:CPM]-> amsUnlock sg dhaDemoSG
</pre></code>
and in the <code>/root/asp/var/log/app.0</code> file (on node WorkerI0) , we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/app.0
|-
|<code><pre>

Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00036 : INFO) Component [dhaDemo] : PID [21785]. CSI Set Received

Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00037 : INFO) CSI Flags : [Add One]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00038 : INFO) CSI Name : [dhaDemoCSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00039 : INFO) Name value pairs :
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00040 : INFO) HA state : [Active]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00041 : INFO) Active Descriptor :
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00042 : INFO) Transition Descriptor : [1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00043 : INFO) Active Component : [dhaDemo]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00044 : NOTICE) Starting dynamic HA demo.
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00045 : NOTICE) It will create 2N SG : dynamicTwoNSG
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00046 : INFO) Running MGMT initialize
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00047 : INFO) Running MGMT CCB initialize
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00048 : NOTICE) Creating 2N SG [dynamicTwoNSG] and other entities(si, csi, su, comp, etc)
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00049 : INFO) Creating SG [dynamicTwoNSG]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00050 : INFO) Create SI [dynamicTwoNSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00051 : INFO) Create CSI [dynamicTwoNCSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00052 : INFO) Create SU [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00053 : INFO) Create SU [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00054 : INFO) Create COMP [dynamicComp0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00055 : INFO) Create COMP [dynamicComp1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00056 : INFO) CCB Commit Create
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00057 : INFO) Fill SG config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00058 : INFO) SG config get [dynamicTwoNSG]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00059 : INFO) SG set SI [dynamicTwoNSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00060 : INFO) SG set SU [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00061 : INFO) SG set SU [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00062 : INFO) SG set commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00063 : INFO) Fill SI config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00064 : INFO) SI config get [dynamicTwoNSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00065 : INFO) SI config set [dynamicTwoNSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00066 : INFO) SI set CSI [dynamicTwoNCSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00067 : INFO) SI set commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00068 : INFO) Fill CSI config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00069 : INFO) CSI config get [dynamicTwoNCSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00070 : INFO) CSI type set [dynamicTwoNCSIType]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00071 : INFO) CSI set nvplist
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00072 : INFO) CSI ccb commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00073 : INFO) Fill SU config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00074 : INFO) SU config get [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00075 : INFO) SU config set [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00076 : INFO) SU config set [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00077 : INFO) SU [dynamicTwoNSU0] add comp [dynamicComp0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00078 : INFO) SU [dynamicTwoNSU1] add comp [dynamicComp1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00079 : INFO) SU set commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00080 : INFO) Fill NODE config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00081 : INFO) NODE config get [WorkerI1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00082 : INFO) Node set SU [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00083 : INFO) NODE config get [WorkerI0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00084 : INFO) Node set SU [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00085 : INFO) Node set commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00086 : INFO) Fill COMP config
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00087 : INFO) COMP config get [dynamicComp0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00088 : INFO) Comp config set [dynamicComp0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00089 : INFO) Comp config set [dynamicComp1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00090 : INFO) Comp set commit
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00091 : INFO) Unlock AMS entities
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00092 : INFO) LockA [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00093 : INFO) Unlock [dynamicTwoNSU0]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00094 : INFO) LockA [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00095 : INFO) Unlock [dynamicTwoNSU1]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00096 : INFO) Unlock SI [dynamicTwoNSI]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00097 : INFO) LockA SG [dynamicTwoNSG]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00098 : INFO) Unlock SG [dynamicTwoNSG]
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00099 : INFO) Running CCB finalize
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.DHA.DMO.00100 : INFO) Running MGMT finalize
Wed Sep 3 16:07:33 2008 (WorkerI0.21785 : dhaDemo_EO.---.---.00101 : NOTICE) Successfully created 2N SG [dynamicTwoNSG] and its entities(si, csi, su, comp, etc) dynamically

</pre></code>
|}

*The dynamically created components 'dynamicComp0' and 'dynamicComp1' will come up as active/standby. Which can be verified through the logs present at nodes WorkerI0 and WorkerI1.

<code>/root/asp/var/log/app.0</code> file (on node WorkerI0) , we should see the dynamically created component getting assigned ACTIVE state:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/app.0
|-
|<code><pre>

Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00031 : INFO) Component [dynamicComp0] : PID [22187]. Initializing

Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00032 : INFO) IOC Address : 0x3

Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00033 : INFO) IOC Port : 0x81

Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00036 : INFO) Component [dynamicComp0] : PID [22187]. CSI Set Received

Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00037 : INFO) CSI Flags : [Add One]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00038 : INFO) CSI Name : [dynamicTwoNCSI]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00039 : INFO) Name value pairs :
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00040 : INFO) Name : [model]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00041 : INFO) Value : [twoN]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00042 : INFO) HA state : [Active]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00043 : INFO) Active Descriptor :
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00044 : INFO) Transition Descriptor : [1]
Wed Sep 3 16:07:43 2008 (WorkerI0.22187 : dummyComp_EO.---.---.00045 : INFO) Active Component : [dynamicComp0]

</pre></code>
|}

<code>/root/asp/var/log/app.0</code> file (on node WorkerI1) , we should see the dynamically created component getting assigned STANDBY state:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/app.0
|-
|<code><pre>

Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00031 : INFO) Component [dynamicComp1] : PID [14623]. Initializing

Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00032 : INFO) IOC Address : 0x4

Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00033 : INFO) IOC Port : 0x80

Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00036 : INFO) Component [dynamicComp1] : PID [14623]. CSI Set Received

Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00037 : INFO) CSI Flags : [Add One]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00038 : INFO) CSI Name : [dynamicTwoNCSI]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00039 : INFO) Name value pairs :
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00040 : INFO) Name : [model]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00041 : INFO) Value : [twoN]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00042 : INFO) HA state : [Standby]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00043 : INFO) Standby Descriptor :
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00044 : INFO) Standby Rank : [1]
Wed Sep 3 16:07:43 2008 (WorkerI1.23159 : dummyComp_EO.---.---.00045 : INFO) Active Component : [dynamicComp0]

</pre></code>
|}

[[File:OpenClovis_Note.png]]Note : The dynamically created component might come up as ACTIVE on WorkerI1 and STANDBY on WorkerI0 or vice versa (depending on the order in which they are launched).

<li>To delete the AMF entities dynamically, lock the dhaDemoSG service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SysCtrlI0:CPM]-> amsLockAssignment sg dhaDemoSG
</pre></code>
and in the <code>/root/asp/var/log/app.0</code> (on node WorkerI0) file, we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/app.0
|-
|<code><pre>

Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00102 : INFO) Component [dhaDemo] : PID [17193]. CSI Set Received

Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00103 : INFO) CSI Flags : [Target One]
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00104 : INFO) CSI Name : [dhaDemoCSI]
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00105 : INFO) HA state : [Quiesced]
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00106 : INFO) Running MGMT initialize
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00109 : INFO) Component [dhaDemo] : PID [17193]. CSI Remove Received

Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00110 : INFO) CSI : dhaDemoCSI

Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00111 : INFO) CSI Flags : 0x2

Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00112 : INFO) Running MGMT CCB initialize
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00113 : NOTICE) Deleting SG [dynamicTwoNSG] and other entities(si, csi, su, comp, etc)
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00114 : INFO) LockI AMS entities
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00115 : INFO) LockA [dynamicTwoNSU0]
Wed Sep 3 16:34:27 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00116 : INFO) LockI [dynamicTwoNSU0]
Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00046 : INFO) Component [dynamicComp0] : PID [17217]. CSI Set Received

Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00047 : INFO) CSI Flags : [Target One]
Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00048 : INFO) CSI Name : [dynamicTwoNCSI]
Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00049 : INFO) HA state : [Quiesced]
Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00052 : INFO) Component [dynamicComp0] : PID [17217]. CSI Remove Received

Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00053 : INFO) CSI : dynamicTwoNCSI

Wed Sep 3 16:34:27 2008 (WorkerI0.17217 : dummyComp_EO.---.---.00054 : INFO) CSI Flags : 0x2

Wed Sep 3 16:34:29 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00117 : INFO) LockA [dynamicTwoNSU1]
Wed Sep 3 16:34:29 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00118 : INFO) LockI [dynamicTwoNSU1]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00119 : INFO) LockA SI [dynamicTwoNSI]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00120 : INFO) LockA SG [dynamicTwoNSG]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00121 : INFO) LockI SG [dynamicTwoNSG]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00122 : INFO) Delete COMP [dynamicComp0]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00123 : INFO) Delete COMP [dynamicComp1]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00124 : INFO) Delete SU [dynamicTwoNSU0]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00125 : INFO) Delete SU [dynamicTwoNSU1]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00126 : INFO) Delete CSI [dynamicTwoNCSI]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00127 : INFO) Delete SI [dynamicTwoNSI]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00128 : INFO) Deleting SG [dynamicTwoNSG]
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00129 : INFO) CCB Commit Delete
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00130 : INFO) Running CCB finalize
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.DHA.DMO.00131 : INFO) Running MGMT finalize
Wed Sep 3 16:34:31 2008 (WorkerI0.17193 : dhaDemo_EO.---.---.00132 : NOTICE) Successfully deleted dynamically created SG [dynamicTwoNSG] and other entities(si, csi, su, comp, etc)

</pre></code>
|}

These can be watched in a separate terminal window using <code>tail -f <file_name> </code>

<li>You can continue to observe this create/delete of AMF entities dynamically by unlocking/locking the SG dhaDemoSG.

*To unlock the dhaDemoSG using the SAFplus Platform Console (this will create the AMF entities dynamically):
<code><pre>
# cli[Test:SysCtrlI0:CPM]-> amsUnlock sg dhaDemoSG
</pre></code>

*To lock the dhaDemoSG using the SAFplus Platform Console (this will delete the AMF entities dynamically):
<code><pre>
# cli[Test:SysCtrlI0:CPM]-> amsLockAssignment sg dhaDemoSG
</pre></code>

*To stop the demo and exit, following CLI commands may be used:
<code><pre>
# cli[Test:SysCtrlI0:CPM]-> amsLockAssignment sg dhaDemoSG
# cli[Test:SysCtrlI0:CPM]-> amsLockInstantiation sg dhaDemoSG
# cli[Test:SysCtrlI0:CPM]-> bye
</pre></code>

</ol>

===Summary===

This Sample Application has covered basic dynamic HA functionality, with creation/deletion of AMF entities (SG, SI, CSI, SU, Component, etc) using Clovis AMF management APIs.

Doc:latest/evalguide/csa113

2010-08-27T03:30:00Z

Senthilk:

==csa113 Event Publication==

===Objective===

The objective is to learn how to write an event publishing application using Clovis' Event Manager API.

===What You Will Learn===

*You will learn how to publish events using Clovis' Event Manager API.

===Code===

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(
ClUint32T argc,
ClCharT *argv[])
{
ClNameT appName;
ClCpmCallbacksT callbacks;
ClVersionT version;
ClIocPortT iocPort;
ClRcT rc = CL_OK;

/*
* ---BEGIN_APPLICATION_CODE---
*/
ClVersionT evtVersion = CL_EVENT_VERSION;
ClEventCallbacksT evtCallbacks = { NULL, NULL };

/*
* ---END_APPLICATION_CODE---
*/
...

if ( (rc = clCpmClientInitialize(&cpmHandle, &callbacks, &version)) )
goto errorexit;

....
</pre></code>
|}

In the <code>clCompAppInitialize</code> function of this example we again see a call to <code>clEventInitialize</code>. Most everything else in the appInitialize function is the same as before in csa112, except that both callback function pointers are specified as <code>NULL</code>. This is because we neither open the event channel asynchronously, or subscribe to any events in this application. So there is no need to specify a callback to receive an event.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(
ClUint32T argc,
ClCharT *argv[])
{

...

// Open an event chanel so that we can subscribe to events on that channel
rc = clEventChannelOpen(evtHandle,
&evtChannelName,
(CL_EVENT_CHANNEL_PUBLISHER |
CL_EVENT_GLOBAL_CHANNEL |
CL_EVENT_CHANNEL_CREATE),
(ClTimeT)CL_RMD_TIMEOUT_FOREVER,
&evtChannelHandle);
</pre></code>
|}

Here we open the event channel. This is the same as in csa112 except that rather than opening as a SUBSCRIBER, we open as a <code>PUBLISHER</code> (by specifying <code>CL_EVENT_CHANNEL_PUBLISHER</code> flag)

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(
ClUint32T argc,
ClCharT *argv[])
{

...

rc = clEventAllocate(evtChannelHandle, &eventHandle);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate event [0x%x]",
rc);
return rc;
}

rc = clEventExtAttributesSet(eventHandle,
EVENT_TYPE,
1,
0,
&publisherName);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to set event attributes [0x%x]",
rc);
return rc;
}
</pre></code>
|}

The call to <code>clEventAllocate</code> allocates an event header. This header is identified by the event handle passed back to <code>gTestInfo.eventHandle</code>. The handle should be used any time the event header is to be used to manipulate the header, either by using <code>clEventExtAttributesSet</code> (right below), or to send an event using the header as in <code>clEventPublish</code>. The call to <code>clEventExtAttributesSet</code> defines the <code>EVENT_TYPE</code> which is defined as 5432 in <code>common/common.h</code> and is used in the event subscriber. It also defines the priority to be 1 which is just below the highest priority of <code>CL_EVENT_HIGHEST_PRIORITY</code> which is defined as 0 where <code>CL_EVENT_LOWEST_PRIORITY</code> is defined as 3. The retention time is specified as 0 since we don't want the event to be kept around if there is no subscriber to pick it up. Finally the <code>publisherName</code> is specified because it's required. Our subscriber doesn't care who publishes the events it receives.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(
ClUint32T argc,
ClCharT *argv[])
{

...

while (!exiting)
{
if (running && ha_state == CL_AMS_HA_STATE_ACTIVE)
{
csa113Comp_PublishEvent();
}
sleep(1);
}
</pre></code>
|}

Here is the main loop. As long as the application is running and active we make a call to <code>csa113Comp_PublishEvent</code>. The work of the application takes place in <code>csa113Comp_PublishEvent</code>, which is presented below.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
csa113Comp_PublishEvent()
{
ClRcT rc = CL_OK;
ClEventIdT eventId = 0;
static int index = 0;
ClSizeT data_len = 0;
char *data = 0;
typedef void (*Generator)(char **, ClSizeT*);

//
// Note: to add a new generator, just define it above and then include
// the new functions name in the generators list.
// Next, maybe something that gets disk free info by way of getfsent
// and statfs?
static Generator generators[] =
{
generate_time_of_day,
generate_load_average
};

//
// every time through increment index and then set index to
// it's value modulo the number of entries in the generators
// array. This will cause us to cycle through the list of
// generators as we're called to publish events.
(*generators[index++])(&data, &data_len);
index %= (int)(sizeof generators / sizeof generators[0]);
if (data == 0 || data_len == 0)
{
clprintf(CL_LOG_SEV_ERROR, "no event data generated");
return CL_ERR_NO_MEMORY;
}
clprintf(CL_LOG_SEV_NOTICE,"Publishing Event: %.*s", (int)data_len, data);
rc = clEventPublish(eventHandle, data, data_len, &eventId);
clHeapFree(data);

return CL_OK;
}
</pre></code>
|}

There's code to call one of a list of generator functions. The functions on the list, return a pointer and a length which are used to pass to <code>clEventPublish</code>. We pass the eventHandle prepared earlier with <code>clEventAllocate</code> and <code>clEventExtAttributesSet</code>. Pass the pointer and the length that we get back from the generator function. Those are used to package up the event data and send it to any subscribers. We also pass the address of the <code>eventId</code> local variable. This is required so that the <code>clEventPublish</code> function can return the event ID. We don't need it, so we promptly drop it in the bit bucket. Finally, we free the data that was allocated in the generator function and passed back as we no longer need it.

===csa213 SA Forum Compliant Event Publication===

This sample application demonstrates the usage of SA Forum Event Service. As mentioned previously, this sample application does not deviate functionally with csa113. The code differences are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaEvtHandleT
|ClEventHandleT
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|SaEvtEventAllocate
|ClEventAllocate
|-
|saEvtEventAttributesSet
|clEventExtAttributesSet
|-
|saEvtEventPublish
|clEventPublish
|}

===How to Run csa113 and What to Observe===

In csa113 you will be observing an event publishing application. This will be far more interesting if you observe an event subscription application at the same time. For this we will use the example from csa112.

<ol>
<li>First you should start up csa112 and put it in a LockAssignment state so that it can receive events.(Unlock csa212SGI0 instead of csa112SGI0 to run csa213).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa112SGI0
</pre></code>

In the csa112 application log you should see:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00037 : INFO)
csa112: Instantiated as component instance csa112CompI0.
Mon Jul 14 22:50:34 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00038 : INFO)
csa112CompI0: Waiting for CSI assignment...
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00041 : INFO)
Component [csa112CompI0] : PID [24830]. CSI Set Received
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00043 : INFO)
CSI Name : [csa112CSII0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00048 : INFO)
Active Component : [csa112CompI0]
Mon Jul 14 22:51:20 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00049 : INFO)
csa112: ACTIVE state requested; activating service
</pre></code>
|}
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described above for the the amsLockAssignment and amsUnlock commands. Unlock csa212SGI0 instead of csa112SGI0.

<li>Now you can start up the event publishing application and put it in a LockAssignment state. (Unlock csa213SGI0 instead of csa113SGI0 to run csa213).
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa113SGI0
</pre></code>

Putting csa113 into a LockAssignment state caused it to begin publishing events. Using <code>tail -f /root/asp/var/log/csa113CompI0Log.latest</code> on the csa113 application log you can see the events being published.(Unlock csa213SGI0 instead of csa113SGI0 to run SAF version).
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| $ /root/asp/var/log/csa113CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00028 : INFO)
Component [csa113CompI0] : PID [24890]. Initializing
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00029 : INFO)
IOC Address : 0x1
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00030 : INFO)
IOC Port : 0x81
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00037 : INFO)
Instantiated as component instance csa113CompI0.
Mon Jul 14 22:53:54 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00038 : INFO)
csa113CompI0: Waiting for CSI assignment...
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00041 : INFO)
Component [csa113CompI0] : PID [24890]. CSI Set Received
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00042 : INFO)
CSI Flags : [Add One]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00043 : INFO)
CSI Name : [csa113CSII0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00044 : INFO)
Name Value Pairs :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00045 : INFO)
HA State : [Active]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00046 : INFO)
Active Descriptor :
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00047 : INFO)
Transition Descriptor : [1]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00048 : INFO)
Active Component : [csa113CompI0]
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00049 : INFO)
csa113: ACTIVE state requested; activating service
Mon Jul 14 22:53:59 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00050 : NOTICE)
Publishing Event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00052 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00054 : NOTICE)
Publishing Event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00056 : NOTICE)
Publishing Event: 0.05 0.07 0.03
Mon Jul 14 22:54:03 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00058 : NOTICE)
Publishing Event: Mon Jul 14 22:54:03 2008
Mon Jul 14 22:54:04 2008 (SCNodeI0.24890 : csa113CompEO.---.---.00060 : NOTICE)
Publishing Event: 0.05 0.07 0.03
</pre></code>
|}

Since the event subscriber application is also running you can see the events that it is receiving in the csa112 application log file. Again using <code>tail -f /rootasp//var/log/csa112CompI0Log.latest</code> you can see the following:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00052 : NOTICE)
We've got an event to receive
Mon Jul 14 22:53:59 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00054 : NOTICE)
received event: Mon Jul 14 22:53:59 2008
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00058 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:00 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00060 : NOTICE)
received event: 0.05 0.07 0.03
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00064 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:01 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00066 : NOTICE)
received event: Mon Jul 14 22:54:01 2008
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00070 : NOTICE)
We've got an event to receive
Mon Jul 14 22:54:02 2008 (SCNodeI0.24830 : csa112CompEO.---.---.00072 : NOTICE)
received event: 0.05 0.07 0.03
</pre></code>
|}

<li>Now you can shut everything down in the usual manner. Note that you will be shutting down two service groups.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa113SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>

</ol>

===Summary and References===

We've seen how to initialize the event manager subsystem as an event publisher. We've seen:
*events flow from the event publisher to the subscriber.
*how to format events and send them through the event manager subsystem
*For further reading, check the same sources as listed under the csa112 section.

Doc:latest/evalguide/csa112

2010-08-27T03:29:16Z

Senthilk:

==csa112 Event Subscription==

===Objective===

The objective of csa112 is to learn how to use Clovis' event service to subscribe to events and to extract the relevant information from the events received by subscription.

===What you will learn===

You will learn
*how to initialize the event library
*how to subscribe to events
*how to receive events
*how to extract the event data

===Code===

One difference to note between this application and previous ones is that this application will not have a main loop in <code>clCompAppInitialize</code>. Instead we will do our work in callback code. This means that when we return from <code>clCompAppInitialize</code> we won't exit the application.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClNameT evtChannelName = {
sizeof EVENT_CHANNEL_NAME - 1,
EVENT_CHANNEL_NAME
};

ClEventChannelHandleT evtChannelHandle = CL_HANDLE_INVALID_VALUE;
ClEventInitHandleT evtHandle = CL_HANDLE_INVALID_VALUE;

static void
csa112Comp_appEventCallback( ClEventSubscriptionIdT subscriptionId,
ClEventHandleT eventHandle,
ClSizeT eventDataSize);

</pre></code>
|}

Here we define variables to hold the payload of our event. Note the initialization of the <code>evtChannelName</code>. The length is set to the length of the <code>EVENT_CHANNEL_NAME</code> string WITHOUT including the <code>null</code> terminator.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(ClUint32T argc,ClCharT *argv[])
{
....

ClEventCallbacksT evtCallbacks = {
NULL,
csa112Comp_appEventCallback
};

...

// publish our event callbacks
rc = clEventInitialize(&evtHandle, &evtCallbacks, &evtVersion);

...
</pre></code>
|}

We initialize the OpenClovis Event Manager with <code>clEventInitialize</code>. We pass the address of the variable where we want the event handle stored. We pass the address of our event callback functions structure. Note that the only event callback function that we specify is <code>csa112Comp_appEventCallback</code>. We do not specify the other callback which is the Asynchronous channel open callback. We specify <code>NULL</code> for that field of <code>evtCallbacks</code> because we don't open our event channel asynchronously.:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppInitialize(ClUint32T argc, ClCharT *argv[])
{

....

// Open an event chanel so that we can subscribe to events on that channel
rc = clEventChannelOpen(evtHandle,
&evtChannelName,
(CL_EVENT_CHANNEL_SUBSCRIBER |
CL_EVENT_GLOBAL_CHANNEL |
CL_EVENT_CHANNEL_CREATE),
(ClTimeT)CL_RMD_TIMEOUT_FOREVER,
&evtChannelHandle);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "csa112\t:Failure opening event channel[0x%x]",
rc);
return rc;
}

rc = clEventExtSubscribe(evtChannelHandle, EVENT_TYPE, 1, (void*)0);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to subscribe to event channel [0x%x]",
rc);
return rc;
}

</pre></code>
|}

Within the above code we open the channel synchronously. We pass the handle we got back from <code>clEventInitialize</code>, the channel name we defined previously, flags that indicate this process is subscribing to the channel and it's a global channel, and that the channel should be created if it's not already there, a timeout value of "forever", and the address of the location where the channel handle should be stored. Then, we subscribe to a specific event stream on the event channel. The <code>EVENT_TYPE</code> constant is defined in <code>common/common.h</code> as 5432. This value is used by the event publisher when it sends events. The constant 1 being passed simply identifies this specific subscription on this channel. This value will be passed to our event delivery callback function.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static void
csa112Comp_appEventCallback( ClEventSubscriptionIdT subscriptionId,
ClEventHandleT eventHandle,
ClSizeT eventDataSize)
{
ClRcT rc = CL_OK;
ClPtrT resTest = NULL;
ClSizeT resSize;
if (running == 0 || ha_state != CL_AMS_HA_STATE_ACTIVE)
{
goto cleanup;
}
clprintf(CL_LOG_SEV_NOTICE,"We've got an event to receive");

resTest = clHeapAllocate(eventDataSize + 1);
if (resTest == NULL)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to allocate space for event");
goto cleanup;
}
*(((char *)resTest) + eventDataSize) = 0;
resSize = eventDataSize;
rc = clEventDataGet(eventHandle, resTest, &resSize);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR, "Failed to get event data [0x%x]", rc);
clHeapFree(resTest);
goto cleanup;
}

clprintf(CL_LOG_SEV_NOTICE,"received event: %s", (char *)resTest);

cleanup:
//Free the memory associated with eventHandle
clEventFree(eventHandle);
}
</pre></code>
|}

The event delivery callback function is named <code>csa112Comp_appEventCallback</code>. First it checks that the running variable is not zero and that the High Availability State is <code>CL_AMS_HA_STATE_ACTIVE</code>, otherwise it returns, dropping the event in the bit bucket. Next it checks whether our incoming data buffer needs to be deallocated. If there is a buffer, it deallocates it and then allocates enough data to receive the incoming event data. Then, we extract the data from the event into the newly allocated buffer using <code>clEventDataGet</code>. Finally, we print the event data we received using <code>clprintf</code> which is another member of Clovis' OS Abstraction Layer. As its name and usage suggest, it is the OSAL replacement for printf.

===csa212 SA Forum Compliant Event Subscription===

csa212 demonstrates the usage of SA Forum's Event Service. This sample application does not deviate functionally from csa112. The differences in code are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaEvtHandleT
|ClEventInitHandleT
|-
|SaEvtChannelHandleT
|ClEventChannelHandleT
|-
|SaEvtCallbacksT
|ClEventCallbacksT
|-
|SA_EVT_CHANNEL_SUBSCRIBER
|CL_EVENT_CHANNEL_SUBSCRIBER
|-
|SA_EVT_CHANNEL_CREATE
|CL_EVENT_CHANNEL_CREATE
|-
|SA_TIME_END
|CL_RMD_TIMEOUT_FOREVER
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|SaEvtInitialize
|ClEventInitialize
|-
|saEvtChannelOpen
|clEventChannelOpen
|-
|saEvtEventSubscribe
|clEventExtSubscribe
|-
|saEvtEventDataGet
|clEventDataGet
|-
|saEvtChannelClose
|clEventChannelClose
|-
|saEvtFinalize
|clEventFinalize
|}

===How to Run csa112 and What to Observe===

<ol>
<li>Start example csa112 in the same manner that we have started previous examples, with the SAFplus Platform Console.(Unlock csa212SGI0 instead of csa112SGI0 to run csa212).
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
</pre></code>

Looking at the log file for this example you should see the following.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 21:59:49 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00028 : INFO)
Component [csa112CompI0] : PID [24077]. Initializing
Mon Jul 14 21:59:49 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00029 : INFO)
IOC Address : 0x1
Mon Jul 14 21:59:49 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00030 : INFO)
IOC Port : 0x80
Mon Jul 14 21:59:49 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00037 : INFO)
csa112: Instantiated as component instance csa112CompI0.
Mon Jul 14 21:59:49 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00038 : INFO)
csa112CompI0: Waiting for CSI assignment...
</pre></code>
|}

<li>Now unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa112SGI0
</pre></code>

At this point you should see the following in the log.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa112CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 22:01:29 2008 (SCNodeI0.24077 : csa112CompEO.---.---.00049 : INFO)
csa112: ACTIVE state requested; activating service
</pre></code>
|}

Thats all there is to this example. What you are looking at in the log is the output of our event listener. It doesn't appear very interesting because we have not yet written an event publisher that will give the program something to output. We'll do that in the next example (csa113).

<li>At this point we can shut down our example in the usual fashion.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa112SGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>
</ol>
[[File:OpenClovis_Note.png]]When running model csa212 you will not see the output described for the the amsLockAssignment and amsUnlock commands.

===Summary and References===

We've seen how to create a basic event subscriber application using Clovis' event manager library. For further reading check the Clovis SAFplus Platform API reference guide, specifically the section on the event manager. Also, the header file: <code>clEventExtApi.h</code> should be helpful.

Doc:latest/evalguide/csa105

2010-08-27T03:28:36Z

Senthilk:

==csa105 Software Alarm Management and Provisioning==

===Objective===

The goal of this sample application is to show
*how provisioning and alarm libraries work together to achieve a simple software alarm management
*how COR change notification is utilized

===What You Will Learn===

You will learn how the Clovis Object Manager (OM) is used to achieve interactions between the alarm and provisioning libraries. In addition, two ways to report an alarm is introduced: COR change notification and fault reporting.

===Code===

The code in csa105 is a bit different than our previous examples. csa105 contains two components instead of one. The first component (csa105Comp) is much like the other examples. It runs within a loop printing out 'Hello World' and with each iteration it increments a counter value. Once this counter value meets or exceeds a defineable threshold, the component raises an alarm. The second component (csa105AlmLstnerComp) registers itself with SAFplus Platform as an alarm subscriber or listener. Once our first component raises the alarm our second component receives notification of this and prints some information out to a log file so that we can see.

There is also a new source file that you will see. This file is '''clcsa105CompalarmMetaStruct.c'''. This file contains definitions for the counter threshold crossing alarm. Everything in this file is generated by the IDE. We will not be customizing it.

The code can be found within the following directories
<project-area_dir>/eval/src/app/csa105Comp
<project-area_dir>/eval/src/app/csa105AlmLstner

This example is built on top of the csa104 example. We will only look at the code that has been added for this example. First we will look at the code in <project-area_dir>/eval/src/app/csa105Comp.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClUint32T counter_threshold = 55; // the value determining the counter threshold.
...
static ClRcT raise_alarm_on_counter(ClCorMOIdT, ClNameT, ClUint32T);
</pre></code>
|}

First we define and initialize the counter threshold. This is the value our counter will be compared against to determine if an alarm should be raised.
 Next we declare the function that will be called to raise the alarm.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
clCompAppInitialize():

...

if (counter_threshold <= counter)
{
clCorMoIdServiceSet(&moId, CL_COR_SVC_ID_ALARM_MANAGEMENT);
if (( rc = raise_alarm_on_counter (moId, appName, counter)) != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Error [0x%x]: Alarm raise has failed. Exiting. ",
appname, rc);
counter = 0;
break;
}
counter = 0;
continue;
}
...

</pre></code>
|}

The clCompAppInitialize() function is where our main loop runs that prints 'Hello World' and increments our counter. Each time through the loop we will now compare our counter value against the threshold value. If the counter is equal to or greater than this threshold we will call our raise_alarm_on_counter function. We also set the counter back to 0.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
raise_alarm_on_counter (ClCorMOIdT moId , ClNameT compName, ClUint32T counter)
{
ClRcT rc = CL_OK;
static ClUint32T iterator = 0, lastCounter = 0;
ClCharT str [80] = {0};
ClAlarmInfoT *pAlarmInfo = {0};
ClAlarmHandleT alarmHandle = {0};
ClUint8T * pBuf = NULL;
ClUint32T size = 0;
ClAlarmUtilPayLoadListPtrT pPayloadList = NULL;

if (lastCounter != counter)
{
lastCounter = counter;
iterator = 0;
}

pPayloadList = clHeapAllocate(sizeof(ClAlarmUtilPayLoadListT));
if (pPayloadList == NULL)
{
clprintf(CL_LOG_SEV_ERROR,"Failed to allocate the memory for the alarm payload list.");
return CL_ERR_NO_MEMORY;
}

pPayloadList->numPayLoadEnteries = 1;
pPayloadList->pPayload = clHeapAllocate(sizeof(ClAlarmUtilPayLoadT));
if (NULL == pPayloadList->pPayload)
{
clprintf(CL_LOG_SEV_ERROR,"Failed while allocating payload array.");
clHeapFree(pPayloadList);
return CL_ERR_NO_MEMORY;
}

pPayloadList->pPayload[0].numTlvs = 1;
clCorMoIdClone(&moId, &pPayloadList->pPayload[0].pMoId);

pPayloadList->pPayload[0].pTlv = clHeapAllocate(sizeof(ClAlarmUtilTlvT));
if (NULL == pPayloadList->pPayload[0].pTlv)
{
clprintf(CL_LOG_SEV_ERROR,"Failed while allocating the pTlv array. ");
clAlarmUtilPayloadListFree(pPayloadList);
return CL_ERR_NO_MEMORY;
}

sprintf(str, "[%s]: The Alarm has been raised as the counter became [%d] for [%d] time",
appname, counter, ++iterator);

pPayloadList->pPayload[0].pTlv[0].type = CL_COR_UINT8;
pPayloadList->pPayload[0].pTlv[0].value = clHeapAllocate(strlen(str) + 1);
if (NULL == pPayloadList->pPayload[0].pTlv[0].value)
{
clprintf(CL_LOG_SEV_ERROR,"Failed while allocating the value for the attribute.");
clAlarmUtilPayloadListFree(pPayloadList);
return CL_ERR_NO_MEMORY;
}

</pre></code>
|}

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

pPayloadList->pPayload[0].pTlv[0].length = strlen(str) + 1;

memset(pPayloadList->pPayload[0].pTlv[0].value, 0, strlen(str) + 1);

memcpy(pPayloadList->pPayload[0].pTlv[0].value, str, strlen(str));

rc = clAlarmUtilPayloadFlatten(pPayloadList, &size, &pBuf);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"[%s]. Failed while getting the flat buffer for the payload. rc[0x%x]",
appname, rc);
return rc;
}

pAlarmInfo = clHeapAllocate (sizeof(ClAlarmInfoT) + size);
if (NULL == pAlarmInfo)
{
clprintf(CL_LOG_SEV_ERROR,"[%s]: Failed to allocate the memory for alarm information. ", appname);
clAlarmUtilPayloadListFree(pPayloadList);
clAlarmUtilPayloadBufFree(pBuf);
return CL_ERR_NO_MEMORY;
}

pAlarmInfo->moId = moId;
pAlarmInfo->probCause = CL_ALARM_PROB_CAUSE_THRESHOLD_CROSSED;
pAlarmInfo->severity = CL_ALARM_SEVERITY_WARNING;
memcpy (&pAlarmInfo->compName, &compName, sizeof(ClNameT));
pAlarmInfo->alarmState = CL_ALARM_STATE_ASSERT;
pAlarmInfo->len = size;

memcpy(pAlarmInfo->buff, pBuf, pAlarmInfo->len);

clAlarmUtilPayloadListFree(pPayloadList);
clAlarmUtilPayloadBufFree(pBuf);

clprintf(CL_LOG_SEV_ERROR,"[%s]: Raising the alarm as the counter threashold has reached. ", appname);

rc = clAlarmRaise (pAlarmInfo, &alarmHandle);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: [0x%x]: The alarm raise has failed. ", appname, rc);
clHeapFree(pAlarmInfo);
return rc;
}

pAlarmInfo->alarmState = CL_ALARM_STATE_CLEAR;
rc = clAlarmRaise (pAlarmInfo, &alarmHandle);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: [0x%x]: The alarm clear has failed. ", appname, rc);
clHeapFree(pAlarmInfo);
return rc;
}

clHeapFree(pAlarmInfo);
return rc;
}
</pre></code>
|}

The raise_alarm_on_counter function receives some information when called such as the application name and the counter value. It creates an <code>ClAlarmInfoT</code> structure and fills it with some useful information. It then calls the <code>clAlarmRaise</code> api twice. The first call is to raise the alarm and the second call is to clear the alarm. (Notice that the alarm state is set to <code>CL_ALARM_STATE_ASSERT</code> for the first call and <code>CL_ALARM_STATE_CLEAR</code> for the second call). The reason for this is that a given alarm is only raised once unless it is cleared. This is to avoid an alarm continually being sent.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa105CompOAMPConfig.c
|-
|<code><pre>
ClOmClassControlBlockT pAppOmClassTbl[] =
{
{
CSA105COMP_CSA105RES_ALARM_CLASS_NAME,
sizeof(CL_OM_ALARM_CSA105RES_CLASS),
CL_OM_ALARM_CLASS_TYPE,
clcsa105CompCSA105RESAlarmConstructor,
clcsa105CompCSA105RESAlarmDestructor,
NULL,
CSA105COMP_CSA105RES_ALARM_CLASS_VERSION,
0,
CL_MAX_OBJ,
0,
CSA105COMP_CSA105RES_ALARM_MAX_SLOTS,
CL_OM_ALARM_CSA105RES_CLASS_TYPE
},

{
CSA105COMP_CSA105RES_PROV_CLASS_NAME,
sizeof(CL_OM_PROV_CSA105RES_CLASS),
CL_OM_PROV_CLASS_TYPE,
clcsa105CompCSA105RESProvConstructor,
clcsa105CompCSA105RESProvDestructor,
NULL,
CSA105COMP_CSA105RES_PROV_CLASS_VERSION,
0,
CL_MAX_OBJ,
0,
CSA105COMP_CSA105RES_PROV_MAX_SLOTS,
CL_OM_PROV_CSA105RES_CLASS_TYPE
},
};
</pre></code>
|}

This OM class table is generated by the IDE in <code>clcsa105CompOAMPConfig.c</code>. The definition for <code>ClOmClassControlBlockT</code> can be found in:
<project-area_dir>/SAFplus/components/om/include/clOmApi.h

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa105Compcsa105Res.c
|-
|<code><pre>
ClRcT clcsa105CompCSA105RESProvUpdate(CL_OM_PROV_CLASS* pThis, ClHandleT txnHandle,
ClProvTxnDataT* pProvTxnData)
{

...

switch (pProvTxnData->provCmd)
{
case CL_COR_OP_CREATE :
case CL_COR_OP_CREATE_AND_SET:

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_ERROR,"%s: Inside create request for the object [%s] ", appname, moIdName.value);

/*
* ---END_APPLICATION_CODE---
*/

break;
case CL_COR_OP_SET:

/*
* ---BEGIN_APPLICATION_CODE---
*/

switch (pProvTxnData->attrId)
{
case CSA105RES_DELTA_T:
delta_t = *(ClUint32T *)pProvTxnData->pProvData;
clprintf(CL_LOG_SEV_NOTICE,"%s: The delta time is now [%d] ", appname, delta_t);
break;
case CSA105RES_COUNTER_THRESH:
counter_threshold = *(ClUint32T *)pProvTxnData->pProvData;
clprintf(CL_LOG_SEV_NOTICE,"%s: The counter threshold is now [%d] ", appname, counter_threshold);
}

/*
* ---END_APPLICATION_CODE---
*/

break;

case CL_COR_OP_DELETE:

/*
* ---BEGIN_APPLICATION_CODE---
*/

/*
* ---END_APPLICATION_CODE---
*/

break;
default:
clprintf (CL_LOG_SEV_ERROR, "Prov command is not proper");

}
</pre></code>
|}

This base provisioning class method is generated by The IDE but requires application-specific logic to be filled in. <code>clcsa105CompCSA105RESProvUpdate()</code> is called to update an object's attribute. This has changed from our csa104 example as you can now change the counter threshold as well as the delta time.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa105Compcsa105Res.c
|-
|<code><pre>
ClRcT clcsa105CompCSA105RESAlarmConstructor( void *pThis, void *pUsrData, ClUint32T usrDataLen )
{
ClRcT rc = CL_OK;

return rc;
}

ClRcT clcsa105CompCSA105RESAlarmDestructor ( void *pThis , void *pUsrData, ClUint32T usrDataLen )
{
ClRcT rc = CL_OK;

return rc;
}
</pre></code>
|}

There are two new functions that have been added as well. These are a constructor and destructor for the alarm. The definition for <code>clcsa105CompCSA105RESAlarmConstructor</code> and <code>clcsa105CompCSA105RESAlarmDestructor</code> can be found in the file <code>clcsa105CompOAMPConfig.h</code>

Now lets look at the code in <project-area_dir>/eval/src/app/csa105AlmLstner.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
....
ClRcT
alarm_event_subscribe_callback(const ClAlarmHandleInfoT* pAlarmInfo);
...
</pre></code>
|}

Near the top of the module we declare the function that will be used to subscribe to alarm events.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppAMFCSISet(
ClInvocationT invocation,
const ClNameT *compName,
ClAmsHAStateT haState,
ClAmsCSIDescriptorT csiDescriptor)
{

switch ( haState )
{
case CL_AMS_HA_STATE_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);

rc = clAlarmEventSubscribe(&alarm_event_subscribe_callback);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed while subscribing for the alarm events. rc[0x%x]",
appname, rc);
return rc;
}
break;
}

case CL_AMS_HA_STATE_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

case CL_AMS_HA_STATE_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);

rc = clAlarmEventUnsubscribe();
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed while un-subscribing for the alarm evnets. rc[0x%x] ",
appname, rc);
return rc;
}
break;
}

case CL_AMS_HA_STATE_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

// ...

/*
* ---END_APPLICATION_CODE---
*/

clCpmCSIQuiescingComplete(cpmHandle, invocation, CL_OK);
break;
}

default:
{
/*
* Should never happen. Ignore.
*/
}
}

</pre></code>
|}

The <code>clCompAppAMFCSISet</code> function is called when the state of the CSI is set. Here we call the <code>clAlarmEventSubscribe</code> api (passing it a handle to our callback function) when the CSI becomes active. When the CSI becomes innactive we call the <code>clAlarmEventUnsubscribe</code> api.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
alarm_event_subscribe_callback(const ClAlarmHandleInfoT* pAlarmInfo)
{
ClRcT rc = CL_OK;
ClNameT moIdName = {0};
ClCorMOIdT moId = pAlarmInfo->alarmInfo.moId;
ClAlarmUtilPayLoadListPtrT pPayloadList = NULL;

rc = clCorMoIdToMoIdNameGet(&moId, &moIdName);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"[%s]:Failed while getting the moId from MOId Name. rc[0x%x] ",
appname, rc);
return rc;
}

rc = clAlarmUtilPayLoadExtract((ClUint8T *)pAlarmInfo->alarmInfo.buff,
pAlarmInfo->alarmInfo.len, &pPayloadList);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"[%s]: Failed while extracting the payload information. rc[0x%x] ",
appname, rc);
return rc;
}

clprintf(CL_LOG_SEV_INFO,"______________________________________________________");
clprintf(CL_LOG_SEV_INFO,"The alarm is [%s] ", pAlarmInfo->alarmInfo.alarmState ?"RAISED":"CLEARED");
clprintf(CL_LOG_SEV_INFO,"The alarm Raised on the resource [%s] ", moIdName.value);
clprintf(CL_LOG_SEV_INFO,"Component which has raised the alarm is [%s] ", pAlarmInfo->alarmInfo.compName.value);
clprintf(CL_LOG_SEV_INFO,"Probable cause of the alarm is [%d] ", pAlarmInfo->alarmInfo.probCause);
clprintf(CL_LOG_SEV_INFO,"Severity of the alarm is [%d] ", pAlarmInfo->alarmInfo.severity);
clprintf(CL_LOG_SEV_INFO,"The payload information : [%s] ", (char*)pPayloadList->pPayload[0].pTlv[0].value);
clprintf(CL_LOG_SEV_INFO,"______________________________________________________");

clAlarmUtilPayloadListFree(pPayloadList);
return rc;
}
</pre></code>
|}

Finally we the callback function. Since this component has registered itself as an alarm listener when it becomes active, this function will be called when the alarm is raised. The function simply prints out a message displaying some of the data that was loaded into the <code>ClAlarmHandleInfoT</code> structure when the alarm was raised.

===How to Run csa105 and What to Observe===

<ol>
<li>Start the application as usual with the SAFplus Platform Console. Since our example has two components we will put them both into a lock assignment state.
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa105SGI0
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa105AlmLstnerSGI0
</pre></code>

This example actually creates three log files...<code>/root/asp/var/log/csa105CompI0Log.latest</code>, <code>/root/asp/var/log/csa105CompI1Log.latest</code> and <code>/root/asp/var/log/csa105AlmLstnerCompLog.latest</code>. The only ones that we are interested in are <code>/root/asp/var/log/csa105CompI0Log.latest</code> and <code>/var/log/csa105AlmLstnerCompLog.latest</code>. Open up two separate command windows. We will view each of the logs in a separate window. In one window type the command <code>tail -f /root/asp/var/log/csa105CompI0Log.latest</code>. In the other type the command <code>tail -f /root/asp/var/log/csa105AlmLstnerCompLog.latest</code>. You should see the following output. (The csa105AlmLstnerComp.log file will not have any output yet.)

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa105CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00135 : INFO)
Component [csa105CompI0] : PID [22201]. Initializing
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00136 : INFO)
IOC Address : 0x1
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00137 : INFO)
IOC Port : 0x81
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00138 : INFO)
csa105: instantiated as component instance csa105CompI0.
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00139 : INFO)
csa105CompI0: cpmHandle = 0x1
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00140 : INFO)
csa105CompI0: Waiting for CSI assignment...
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00141 : INFO)
csa105CompI0: checkpoint_initialize
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00148 : INFO)
csa105CompI0: Checkpoint service initialized (handle=0x1)
Mon Jul 14 20:15:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00150 : INFO)
csa105CompI0: Checkpoint opened (handle=0x2)
</pre></code>
|}

<li>Now unlock the '''csa105AlmLstnerSGI0''' service group.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa105AlmLstnerSGI0
</pre></code>

<li>Next unlock the '''csa105SGI0''' service group.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa105SGI0
</pre></code>

You should see the following output in the <code>/root/asp/var/log/csa105CompI0Log.latest</code> log file.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa105CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00286 : INFO)
csa105CompI0: Hello World! (count = 0)
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00291 : INFO)
**** Inside the function : [clCompAppProvTxnStart] ****
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00293 : INFO)
Inside the function clcsa105CompCSA105RESProvObjectStart
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00295 : INFO)
Inside the function clcsa105CompCSA105RESProvValidate
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00311 : INFO)
Inside the function clcsa105CompCSA105RESProvUpdate
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00313 : INFO)
Inside the function clcsa105CompCSA105RESProvObjectEnd
Mon Jul 14 20:21:18 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00322 : INFO)
**** Inside the function : [clCompAppProvTxnEnd] ****
Mon Jul 14 20:21:19 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00329 : INFO)
csa105CompI0: Hello World! (count = 1)
Mon Jul 14 20:21:20 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00330 : INFO)
csa105CompI0: Hello World! (count = 2)
Mon Jul 14 20:21:21 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00331 : INFO)
csa105CompI0: Hello World! (count = 3)
</pre></code>
|}

You will notice that the '''csa105CompI0''' component has begun printing out the 'Hello World'. You can also see that the counter value is incrementing.

Keep watching the counter value as it increments. Remember that we set up an initial counter threshold of 65. Once the counter value reaches 65 you will see the following in the <code>/root/asp/var/log/csa105AlmLstnerCompLog.latest</code> log file.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/cscsa105AlmLstnerCompLog.latest
|-
|<code><pre>
__________________________________________________________________________________
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00109 : INFO)
The alarm is [RAISED]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00110 : INFO)
The alarm Raised on the resource [\Chassis:0\csa105Res:0]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00111 : INFO)
Component which has raised the alarm is [csa105CompI1]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00112 : INFO)
Probable cause of the alarm is [16]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00113 : INFO)
Severity of the alarm is [4]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00114 : INFO)
The payload information : [[csa105CompI0]: The Alarm has been raised as the counter
became [65] for [1] time]
__________________________________________________________________________________
__________________________________________________________________________________
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00134 : INFO)
The alarm is [CLEARED]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00135 : INFO)
The alarm Raised on the resource [\Chassis:0\csa105Res:0]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00136 : INFO)
Component which has raised the alarm is [csa105CompI1]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00137 : INFO)
Probable cause of the alarm is [16]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00138 : INFO)
Severity of the alarm is [4]
Mon Jul 14 20:22:23 2008 (SCNodeI0.22234 : csa105AlmLstner_EO.---.---.00139 : INFO)
The payload information : [[csa105CompI0]: The Alarm has been raised as the counter
became [65] for [1] time]

__________________________________________________________________________________
</pre></code>
|}

As you can see our callback function in the module <code><project-area_dir>/eval/src/app/csa105AlmLstner/clCompAppMain.c</code> was called twice. Once when the alarm was raised and once when it was cleared. Looking at the <code>/root/asp/var/log/csa105CompI0Log.latest</code> log file you can see that the alarm was raised and cleared from this component and then the counter value was reset.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa105CompI0Log.l
|-
|<code><pre>
Mon Jul 14 20:22:22 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00812 : INFO)
csa105CompI0: Hello World! (count = 64)
Mon Jul 14 20:22:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00813 : INFO)
csa105CompI0: Hello World! (count = 65)
Mon Jul 14 20:22:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00814 : INFO)
[csa105CompI0]: Raising the alarm as the counter threashold has reached.
Mon Jul 14 20:22:23 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00843 : INFO)
csa105CompI0: Hello World! (count = 0)
Mon Jul 14 20:22:24 2008 (SCNodeI0.22201 : csa105Comp_EO.---.---.00844 : INFO)
csa105CompI0: Hello World! (count = 1)
</pre></code>
|}

This behavior will continue each time the counter value reaches 65.

<li>Now lets change the threshold value. We do this through the SAFplus Platform Console. In the SAFplus Platform Console return to the SCNodeI0 context by entering <code>end</code> until it prints the SCNodeI0 prompt: <code>cli[Test:SCNodeI0]-></code>.
<code><pre>
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]->
</pre></code>

<li>Now set the context to the COR server using the following command:
<code><pre>
cli[Test:SCNodeI0]-> setc corServer_SCNodeI0
</pre></code>

<li>Then, dump the object tree:
<code><pre>
cli[Test:SCNodeI0:COR]-> objTreeShow
</pre></code>

You should see something like the following. There may be extra entries, but you should at least see an entry where <code>ClassName = CLASS_CSA105RES_PROV_MS0</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
cli[Test:SCNodeI0:COR]-> objtreeshow

Objects (Instance Tree):
[0] ClassName=Chassis ClassId=0x10001 inst=0 [flgs=0x508]
[0] ClassName=SCNodeRes ClassId=0x10007 inst=0 [flgs=0x508]
*[3] ClassName=CLASS_SCNODERES_PROV_MSO ClassId=0x10009 inst=0 [flgs=0x508]
[0] ClassName=csa105Res ClassId=0x10004 inst=0 [flgs=0x508]
*[2] ClassName=CLASS_CSA105RES_ALARM_MSO ClassId=0x10006 inst=0 [flgs=0x508]
*[3] ClassName=CLASS_CSA105RES_PROV_MSO ClassId=0x10005 inst=0 [flgs=0x508]
</pre></code>
|}

<li>Next, dump the <code>CLASS_CSA105RES_PROV_MS</code> object with:
<code><pre>
cli[Test:SCNodeI0:COR]-> objectShow \Chassis:0\csa105Res:0 3
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
Showing Object
ClCorMOId:[Svc: 3] (/).(10001:0000).(10004:0000):

[Class:0x10005] Object
{
[CSA105RES_COUNTER ] [0x0004] = [41]
[CSA105RES_COUNTER_THRESH ] [0x0005] = [65]
[CSA105RES_DELTA_T ] [0x0006] = [1000]
}
</pre></code>
|}

The 3 is the service ID of the object and is the value in brackets next to the asterisk on the <code>ClassName=CLASS_CSA105RES_PROV_MSO</code> line.

<li>Now, set the counter_thresh attribute to 20 instead of 65 with:
<code><pre>
cli[Test:SCNodeI0:COR]-> attrSet \Chassis:0\csa105Res:0 3 null 5 -1 20
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
Execution Result : Passed
</pre></code>
|}

Now you will notice that the alarm is raised every time the counter value reaches 20.

<li>To end this example first get back to the CPM context.
<code><pre>
cli[Test:SCNodeI0:COR]-> end
cli[Test:SCNodeI0]-> setc cpm
</pre></code>

<li>Now shut things down in the usual fashion. Remember that this example has two components to shut down.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa105SGI0
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa105AlmLstnerSGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa105SGI0
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa105AlmLstnerSGI0
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>

</ol>

===Summary and References===

This application is built upon the csa104 application and presents :
*how provisioning and alarm libraries work together to achieve a simple software alarm management
*how COR change notification is utilized

Doc:latest/evalguide/csa104

2010-08-27T03:27:51Z

Senthilk:

==csa104 Provisioning==

===Objective===

The objective is to demonstrate some of the features of the Clovis Object Registry (COR) and Clovis' Object Management (OM) framework.

===What you will learn===

*How to use the Clovis Object Registry to set configuration values in a simple SAFplus Platform application.
*How to manipulate COR values from the SAFplus Platform Console line interface.

===Code===

The code can be found within the following directory
<project-area_dir>/eval/src/app/csa104Comp

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClUint8T clEoClientLibs[] =
{
COMP_EO_CLIENTLIB_COR, /* Lib: Common Object Repository */
COMP_EO_CLIENTLIB_CM, /* Lib: Chassis Management */
COMP_EO_CLIENTLIB_NAME, /* Lib: Name Service */
COMP_EO_CLIENTLIB_LOG, /* Lib: Log Service */
COMP_EO_CLIENTLIB_TRACE, /* Lib: Trace Service */
COMP_EO_CLIENTLIB_DIAG, /* Lib: Diagnostics */
COMP_EO_CLIENTLIB_TXN, /* Lib: Transaction Management */
CL_FALSE, /* NA */
COMP_EO_CLIENTLIB_PROV, /* Lib: Provisioning Management */
COMP_EO_CLIENTLIB_ALARM, /* Lib: Alarm Management */
COMP_EO_CLIENTLIB_DEBUG, /* Lib: Debug Service */
COMP_EO_CLIENTLIB_GMS /* Lib: Cluster/Group Membership Service */
};
</pre></code>
|}

Here we present the Client Libraries. These are set within <code>clCompCfg.h</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompCfg.h
|-
|<code><pre>
#define COMP_EO_CLIENTLIB_COR CL_TRUE
#define COMP_EO_CLIENTLIB_CM CL_FALSE
#define COMP_EO_CLIENTLIB_NAME CL_FALSE
#define COMP_EO_CLIENTLIB_LOG CL_FALSE
#define COMP_EO_CLIENTLIB_TRACE CL_FALSE
#define COMP_EO_CLIENTLIB_DIAG CL_FALSE
#define COMP_EO_CLIENTLIB_TXN CL_TRUE
#define COMP_EO_CLIENTLIB_NA CL_FALSE
#define COMP_EO_CLIENTLIB_PROV CL_TRUE
#define COMP_EO_CLIENTLIB_ALARM CL_FALSE
#define COMP_EO_CLIENTLIB_DEBUG CL_FALSE
#define COMP_EO_CLIENTLIB_GMS CL_FALSE
</pre></code>
|}

Within <code>clCompCfg.h</code> we set Clovis Object Registry (COR), the Transaction (TXN), and Provisioning (Prov) libraries to <code>TRUE</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClCompAppInitialize()

...
clCorMoIdInitialize(&moId);
clCorMoIdAppend(&moId, CLASS_CHASSIS_MO, 0);
clCorMoIdAppend(&moId, CLASS_CSA104RES_MO, 0);
clCorMoIdServiceSet(&moId, CL_COR_SVC_ID_PROVISIONING_MANAGEMENT);
rc = clCorObjectHandleGet(&moId, &objH);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed [0x%x] to get the object handle. ",
appname, rc);
return rc;
}

while (!exiting)
{
if (running && ha_state == CL_AMS_HA_STATE_ACTIVE)
{
clprintf(CL_LOG_SEV_INFO,"%s: Hello World! (count = %d)", appname, counter);
#ifdef CL_INST
if ((rc = clDataTapSend(counter)) != CL_OK && (rc != CL_ERR_INVALID_PARAMETER))
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed [0x%x] to send data tap data",
appname, rc);
}
#endif
if ((rc = update_counter_in_cor(time(0), objH, counter)) != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: [0x%x]: cor update failed. Exiting.",
appname, rc);
break;
}

/* Checkpoint new counter number */
rc = checkpoint_write_counter(counter);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: [0x%x]: Checkpoint write failed. Exiting.",
appname, rc);
break;
}

counter++;
}

usleep((useconds_t)delta_t*1000);
}
</pre></code>
|}

The main loop body is as we've seen several times already. But, the sleep, rather than being <code>sleep(1)</code> is a <code>usleep()</code> of a variable duration. The duration: <code>delta_t</code> is a number in milliseconds that is settable from COR. We'll see where it gets set later.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
#include <stdio.h>
#include <string.h>
...
#include <clDebugApi.h>
...
</pre></code>
|}

We including standard header files, including <code>clDebugApi.h</code> which allows the application to interact with the SAFplus Platform Console.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clcsa104CompOAMPConfig.c
|-
|<code><pre>
#include <clcsa104CompOAMPConfig.h>
</pre></code>
|}
Within <code>clcsa104CompOAMPConfig.c</code> we include <code>clcsa104CompOAMPConfig.h</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"|clcsa104CompOAMPConfig.h
|-
|<code><pre>
#include <clOmApi.h>
#include <clCorApi.h>
#include <clProvOmApi.h>
#include <clProvApi.h>
#include <clAlarmOM.h>
#include <clHalApi.h>
#include <clHalObjectApi.h>

typedef ClRcT (*fp) (CL_OM_PROV_CLASS*, ClHandleT, ClProvTxnDataT*);

CL_OM_BEGIN_CLASS(CL_OM_PROV_CLASS, CL_OM_PROV_CSA104RES_CLASS)

CL_OM_END

ClRcT clcsa104CompCSA104RESProvConstructor( void *pThis, void *pUsrData,
ClUint32T usrDataLen );
ClRcT clcsa104CompCSA104RESProvDestructor ( void *pThis , void *pUsrData,
ClUint32T usrDataLen );
ClRcT clcsa104CompCSA104RESProvValidate(CL_OM_PROV_CLASS* pThis,
ClHandleT txnHandle, ClProvTxnDataT* pProvTxnData);

ClRcT clcsa104CompCSA104RESProvUpdate(CL_OM_PROV_CLASS* pThis,
ClHandleT txnHandle, ClProvTxnDataT* pProvTxnData);

ClRcT clcsa104CompCSA104RESProvRollback(CL_OM_PROV_CLASS* pThis,
ClHandleT txnHandle, ClProvTxnDataT* pProvTxnData);

ClRcT clcsa104CompCSA104RESProvRead(CL_OM_PROV_CLASS* pThis,
ClHandleT txnHandle, ClProvTxnDataT* pProvTxnData);

void clcsa104CompCSA104RESProvObjectStart(ClCorMOIdPtrT pMoId,
ClHandleT txnHandle);

void clcsa104CompCSA104RESProvObjectEnd(ClCorMOIdPtrT pMoId,
ClHandleT txnHandle);
</pre></code>
|}

Next in <code>clcsa104CompOAMPConfig.h</code> we have several header files being included. Included is <code>clOmApi.h</code> which is the main header file for using the Object Management subsystem. This is Clovis' support for object-oriented like programming in C. Next <code>clCorApi.h</code> is the main header for using the Clovis Object Registry. <code>clProvOmApi.h</code> is the main header for the Clovis Provisioning OM class. We define an Object Management class: <code>CL_OM_PROV_CSA104RES_CLASS</code> which inherits from another Object Management class: <code>CL_OM_PROV_CLASS</code>. This last class is the class whose API was imported with the <code>#include clProvOmApi.h</code>. The subsequent code in the above table declare functions that will be member functions of the new Object Management class: <code>CL_OM_PROV_CSA104_CLASS</code>. Note that function header comments have been omitted for clarity.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa104Compcsa104Res.c
|-
|<code><pre>
extern ClUint32T delta_t;
extern ClCharT appname[80];
</pre></code>
|}

Above we define/declare a variable that is used for provisioning. The extern is a reference to a variable defined in clCompAppMain.c.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa104CompOAMPConfig.c
|-
|<code><pre>
ClOmClassControlBlockT pAppOmClassTbl[] =
{
{
CSA104COMP_CSA104RES_PROV_CLASS_NAME,
sizeof(CL_OM_PROV_CSA104RES_CLASS),
CL_OM_PROV_CLASS_TYPE,
clcsa104CompCSA104RESProvConstructor,
clcsa104CompCSA104RESProvDestructor,
NULL,
CSA104COMP_CSA104RES_PROV_CLASS_VERSION,
0,
CL_MAX_OBJ,
0,
CSA104COMP_CSA104RES_PROV_MAX_SLOTS,
CL_OM_PROV_CSA104RES_CLASS_TYPE
},

};
</pre></code>
|}

Within <code>clcsa104CompOAMPConfig.c</code> we define the global <code>pAppOmClassTbl</code> so that will know about the new class and be able to instantiate members of the class. Line 27 specifies the name of the class. This is optional. Defined is the size of instances of the class, next we specify the base class, followed by the constructor and destructor for the class respectively. The <code>NULL</code> specifies the table of functions for the class, in this case there is no such table. <code>0</code> is the instance table pointer. The next three lines of code.
 --> <code>CL_MAX_OBJ,</code>
 --> <code>0,</code>
 --> <code>CSA104COMP_CSA104RES_PROV_MAX_SLOTS,</code>
 specify the max number of object instances allowed, current number of object instances, and max number of object instances so far respectively. Followed by the Class Type ID for the class.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa104Compcsa104Res.c
|-
|<code><pre>
ClRcT clcsa104CompCSA104RESProvConstructor( void *pThis, void *pUsrData,
ClUint32T usrDataLen )
{
ClRcT rc = CL_OK;

/* Override "semantic check" virtual method in provClass*/
((CL_OM_PROV_CLASS*)pThis)->clProvObjectStart = clcsa104CompCSA104RESProvObjectStart;
((CL_OM_PROV_CLASS*)pThis)->clProvValidate = (fp)clcsa104CompCSA104RESProvValidate;
((CL_OM_PROV_CLASS*)pThis)->clProvUpdate = (fp)clcsa104CompCSA104RESProvUpdate;
((CL_OM_PROV_CLASS*)pThis)->clProvRollback = (fp)clcsa104CompCSA104RESProvRollback;
((CL_OM_PROV_CLASS*)pThis)->clProvRead = (fp)clcsa104CompCSA104RESProvRead;
((CL_OM_PROV_CLASS*)pThis)->clProvObjectEnd = clcsa104CompCSA104RESProvObjectEnd;

...

return rc;
}

ClRcT clcsa104CompCSA104RESProvDestructor ( void *pThis , void *pUsrData,
ClUint32T usrDataLen )
{
ClRcT rc = CL_OK;

...

return rc;
}
</pre></code>
|}

The above table presents the Contructor. It initializes the function pointers defined in the Base Class. These are the Update method, the provisioning validation method, and the provisioning rollback method. These are declared in <code>clcsa104CompOAMPConfig.h</code> in the class definition. The destructor doesn't do anything except return <code>CL_OK</code>. There's no destruction work to do for this class.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa104Compcsa104Res.c
|-
|<code><pre>
ClRcT clcsa104CompCSA104RESProvUpdate(CL_OM_PROV_CLASS* pThis,
ClHandleT txnHandle, ClProvTxnDataT* pProvTxnData)
{
ClRcT rc = CL_OK;

/*
---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO, "Inside the function %s", __FUNCTION__);

ClNameT moIdName = {0};

rc = clCorMoIdToMoIdNameGet((ClCorMOIdPtrT)pProvTxnData->pMoId, &moIdName);
if (CL_OK != rc)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed while getting the MOId Name from moid. rc[0x%x] ", appname, rc);
return rc;
}
/*
---END_APPLICATION_CODE---
*/

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clcsa104Compcsa104Res.c
|-
|<code><pre>
switch (pProvTxnData->provCmd)
{
case CL_COR_OP_CREATE :
case CL_COR_OP_CREATE_AND_SET:

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"%s: Inside create request for the object [%s] ", appname, moIdName.value);

/*
* ---END_APPLICATION_CODE---
*/

break;
case CL_COR_OP_SET:

/*
* ---BEGIN_APPLICATION_CODE---
*/

if ( pProvTxnData->attrId == CSA104RES_DELTA_T)
{
delta_t = *(ClUint32T *)pProvTxnData->pProvData;
clprintf(CL_LOG_SEV_INFO,"%s: The delta time is now [%d] ", appname, delta_t);
}

/*
* ---END_APPLICATION_CODE---
*/

break;

case CL_COR_OP_DELETE:

/*
* ---BEGIN_APPLICATION_CODE---
*/

/*
* ---END_APPLICATION_CODE---
*/

break;
default:
clprintf (CL_LOG_SEV_ERROR, "Prov command is not proper");
}

...

return rc;
}
</pre></code>
|}

When the COR object associated with csa104's provisioning is updated, <code>clcsa104CompCSA104RESProvUpdate</code> function is called. A new value is set for the <code>delta_t</code> variable that is used to control the sleep interval in the application's main loop.

===How to Run 104 and what to observe===

<ol>
<li>Start the application as usual with the SAFplus Platform Console.
<code><pre>
# cd /root/asp/bin
# ./asp_console

cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa104SGI0
</pre></code>

Again, there are two log files to observe <code>/root/asp/var/log/csa104CompI0Log.latest</code> and <code>/var/log/csa104CompI1Log.latest</code>. After running the above commands you should see the following output in these logs when using <code>tail -f</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa104CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00051 : INFO)
Component [csa104CompI0] : PID [21202]. Initializing
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00052 : INFO)
IOC Address : 0x1
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00053 : INFO)
IOC Port : 0x80
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00054 : INFO)
csa104: instantiated as component instance csa104CompI0.
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00055 : INFO)
csa104CompI0: cpmHandle = 0x1
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00056 : INFO)
csa104CompI0: Waiting for CSI assignment...
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00057 : INFO)
csa104CompI0: checkpoint_initialize
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00064 : INFO)
csa104CompI0: Checkpoint service initialized (handle=0x1)
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00066 : INFO)
csa104CompI0: Checkpoint opened (handle=0x2)
Mon Jul 14 19:06:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00067 : INFO)
csa104CompI0: Section created
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa104CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00049 : INFO)
Component [csa104CompI1] : PID [21209]. Initializing
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00050 : INFO)
IOC Address : 0x1
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00051 : INFO)
IOC Port : 0x81
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00052 : INFO)
csa104: instantiated as component instance csa104CompI1.
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00053 : INFO)
csa104CompI1: cpmHandle = 0x1
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00054 : INFO)
csa104CompI1: Waiting for CSI assignment...
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00055 : INFO)
csa104CompI1: checkpoint_initialize
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00062 : INFO)
csa104CompI1: Checkpoint service initialized (handle=0x1)
Mon Jul 14 19:06:29 2008 (SCNodeI0.21209 : csa104CompEO.---.---.00064 : INFO)
csa104CompI1: Checkpoint opened (handle=0x2)
</pre></code>
|}

<li>As before, unlock the application with:
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa104SGI0
</pre></code>

In the active component log file you should start to see the "Hello World" lines displaying at a rate of about 1 per second.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa104CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00080 : INFO)
csa104CompI0: Hello World! (count = 0)
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00085 : INFO)
**** Inside the function : [clCompAppProvTxnStart] ****
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00087 : INFO)
Inside the function clcsa104CompCSA104RESProvObjectStart
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00089 : INFO)
Inside the function clcsa104CompCSA104RESProvValidate
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00105 : INFO)
Inside the function clcsa104CompCSA104RESProvUpdate
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00107 : INFO)
Inside the function clcsa104CompCSA104RESProvObjectEnd
Mon Jul 14 19:07:27 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00116 : INFO)
**** Inside the function : [clCompAppProvTxnEnd] ****
Mon Jul 14 19:07:28 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00123 : INFO)
csa104CompI0: Hello World! (count = 1)
Mon Jul 14 19:07:29 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00124 : INFO)
csa104CompI0: Hello World! (count = 2)
Mon Jul 14 19:07:30 2008 (SCNodeI0.21202 : csa104CompEO.---.---.00125 : INFO)
csa104CompI0: Hello World! (count = 3)
</pre></code>
|}

<li>In the SAFplus Platform Console return to the Slot 1 context by entering <code>end</code> until it prints the Slot 1 prompt: <code>cli[Test:SCNodeI0]-></code>.
<code><pre>
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]->
</pre></code>

<li>Now set the context to the COR server using the following command:
<code><pre>
cli[Test:SCNodeI0]-> setc corServer_SCNodeI0
</pre></code>

<li>Then, dump the object tree:
<code><pre>
cli[Test:SCNodeI0:COR]-> objTreeShow
</pre></code>

You should see something like the following. There may be extra entries, but you should at least see an entry where <code>ClassName = CLASS_CSA104RES_PROV_MS0</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
cli[Test:SCNodeI0:COR]-> objtreeshow

Objects (Instance Tree):
[0] ClassName=Chassis ClassId=0x10001 inst=0 [flgs=0x508]
[0] ClassName=SCNodeRes ClassId=0x10007 inst=0 [flgs=0x508]
*[3] ClassName=CLASS_SCNODERES_PROV_MSO ClassId=0x10009 inst=0 [flgs=0x508]
[0] ClassName=csa104Res ClassId=0x10002 inst=0 [flgs=0x508]
*[3] ClassName=CLASS_CSA104RES_PROV_MSO ClassId=0x10003 inst=0 [flgs=0x508]

</pre></code>
|}

<li>Next, dump the <code>CLASS_CSA104RES_PROV_MS</code> object with:
<code><pre>
cli[Test:SCNodeI0:COR]-> objectShow \Chassis:0\csa104Res:0 3
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
Showing Object
ClCorMOId:[Svc: 3] (/).(10001:0000).(10002:0000):

[Class:0x10003] Object
{
[CSA104RES_COUNTER ] [0x0002] = [431]
[CSA104RES_DELTA_T ] [0x0003] = [1000]
}
</pre></code>
|}

The 3 is the service ID of the object and is the value in brackets next to the asterisk on the <code>ClassName=CLASS_CSA104RES_PROV_MSO</code> line.

<li>Now, set the delta_t attribute to 10000 instead of 1000 with:
<code><pre>
cli[Test:SCNodeI0:COR]-> attrSet \Chassis:0\csa104Res:0 3 null 3 -1 10000
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
Execution Result : Passed
</pre></code>
|}

You should see lines like the following in the logs for csa104:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa104CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 19:15:59 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04230 : INFO)
csa104CompI0: The delta time is now [10000]
Mon Jul 14 19:15:59 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04232 : INFO)
Inside the function clcsa104CompCSA104RESProvObjectEnd
Mon Jul 14 19:15:59 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04241 : INFO)
**** Inside the function : [clCompAppProvTxnEnd] ****
Mon Jul 14 19:15:59 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04248 : INFO)
csa104CompI0: Hello World! (count = 510)
Mon Jul 14 19:16:09 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04249 : INFO)
csa104CompI0: Hello World! (count = 511)
Mon Jul 14 19:16:09 2008 (SCNodeI0.21202 : csa104CompEO.---.---.04254 : INFO)
**** Inside the function : [clCompAppProvTxnStart] ****
</pre></code>
|}

indicating that the component has received the updated value of delta_t

You should also notice that the lines in the log are now being printed with a 10 second interval between lines.

To confirm that the value of delta_t was updated you could dump the <code>CLASS_CSA104RES_PROV_MS</code> object with:
<code><pre>
cli[Test:SCNodeI0:COR]-> objectShow \Chassis:0\csa104Res:0 3
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| SAFplus Platform Console
|-
|<code><pre>
Showing Object
ClCorMOId:[Svc: 3] (/).(10001:0000).(10002:0000):

[Class:0x10003] Object
{
[CSA104RES_COUNTER ] [0x0002] = [523]
[CSA104RES_DELTA_T ] [0x0003] = [10000]
}
</pre></code>
|}

<li>To end the example first change the state of csa104SGI0 to LockAssignment.
<code><pre>
cli[Test:SCNodeI0:COR]-> end
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa104SGI0
</pre></code>

<li>Then change the state to LockInstantiation.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa104SGI0
</pre></code>

<li>Then close the SAFplus Platform Console session.
<code><pre>
cli[Test:SCNodeI0:CPM]-> end
cli[Test:SCNodeI0]-> end
cli[Test]-> bye
</pre></code>

</ol>

===Summary and References===

We've seen how to:
*Create a simple ProvOm class.
*Use callbacks to the class's update method to update variables in the application at runtime.
*Use the SAFplus Platform Console to cause the classes update method to be invoked.

For further reading :
*Clovis SAFplus Platform User Guide: sections on COR,
*clProvOmApi.h
*clOmObjectManage.h
*clOmApi.h

Doc:latest/evalguide/csa103

2010-08-27T03:16:33Z

Senthilk:

==csa103 Checkpointing==

===Objective===

csa103 demonstrates how to use the Clovis Checkpoint service to provide basic failure recovery. csa103 builds on csa102.

===What Will You Learn===

*how to initialize the checkpoint client library,
*how to create a checkpoint and open a checkpoint,
*how to create a section in the checkpoint
*how to save data to the checkpoint section and read data from the checkpoint section.

===The Code===

The code can be found within the following directory
<project-area_dir>/eval/src/app/csa103Comp

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClCompAppInitialize()

...

if ((rc = checkpoint_initialize()) != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed [0x%x] to initialize checkpoint",
appname, rc);
return rc;
}
if ((rc = checkpoint_read_seq(&seq)) != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed [0x%x] to read checkpoint",
appname, rc);
checkpoint_finalize();
return rc;
}
#ifdef CL_INST
if ((rc = clDataTapInit(DATA_TAP_DEFAULT_FLAGS, 103)) != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: Failed [0x%x] to initialize data tap",
appname, rc);
}
#endif

</pre></code>
|}

The above software in <code>clCompAppMain.c</code> is new to csa103. The call to <code>checkpoint_initialize</code> is pretty straightforward. This function discussed in detail later within this section. The call to <code>checkpoint_read_seq</code> is also pretty straightforward. It reads the current sequence value from the checkpoint (at this point it should be zero) and loads it into the variable: <code>seq</code>. It is important to note the call to <code>checkpont_finalize</code> if the call to <code>checkpoint_read_seq</code> does not return <code>CL_OK</code>. This call closes the checkpoint and cleanly finalizes the checkpoint library. We'll look more at <code>checkpoint_read_seq</code> and <code>checkpoint_finalize</code> later.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
/* Checkpoint new sequence number */
rc = checkpoint_write_seq(seq);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: ERROR: Checkpoint write failed. Exiting.", appname);
break;
}
</pre></code>
|}

The rest of the csa103's main loop is the same as the main loop in csa102, but the seven lines above are new. Here we write the new value of the checkpoint variable to the checkpoint section and print and error if this fails. We'll look closer at <code>checkpoint_write_seq</code> later.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClRcT
clCompAppAMFCSISet(
ClInvocationT invocation,
const ClNameT *compName,
ClAmsHAStateT haState,
ClAmsCSIDescriptorT csiDescriptor)
{
/*
* ---BEGIN_APPLICATION_CODE---
*/
ClCharT compname[100]={0};

/*
* ---END_APPLICATION_CODE---
*/

/*
* Print information about the CSI Set
*/
strncpy(compname, compName->value, compName->length);

clprintf (CL_LOG_SEV_INFO, "Component [%s] : PID [%d]. CSI Set Received",
compname, (int)mypid);

clCompAppAMFPrintCSI(csiDescriptor, haState);

/*
Take appropriate action based on state
*/

switch ( haState )
{
case CL_AMS_HA_STATE_ACTIVE:
{
/*
AMF has requested application to take the active HA state
for the CSI.
*/

/*
---BEGIN_APPLICATION_CODE---
*/
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
clprintf(CL_LOG_SEV_INFO,"%s: Active state requested from state %d",
appname, ha_state);

checkpoint_replica_activate();
if (ha_state == CL_AMS_HA_STATE_STANDBY)
{
/* Read checkpoint, make our replica the active replica */
clprintf(CL_LOG_SEV_INFO,"%s reading checkpoint", appname);
checkpoint_read_seq(&seq);
clprintf(CL_LOG_SEV_INFO,"%s read checkpoint: seq = %u", appname, seq);
}

ha_state = CL_AMS_HA_STATE_ACTIVE;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

case CL_AMS_HA_STATE_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO," Standby state requested from state %d",ha_state);

ha_state = CL_AMS_HA_STATE_STANDBY;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
case CL_AMS_HA_STATE_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"%s: QUIESCED", appname);
ha_state = haState;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

case CL_AMS_HA_STATE_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"%s: QUIESCING", appname);
ha_state = haState;

/*
* ---END_APPLICATION_CODE---
*/

clCpmCSIQuiescingComplete(cpmHandle, invocation, CL_OK);
break;
}
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
default:
{
break;
}
}

return CL_OK;
}
</pre></code>
|}

Now looking at csa103's implementation of <code>clCompAppAMFCSISet</code>, we see that rather than just a few cases, we handle several cases: <code>QUIESCING</code>, <code>QUIESCED</code>, <code>ACTIVE</code>, and <code>STANDBY</code>. In each state, the global variable <code>ha_state</code> to the new_state value that is passed in is set. This is similar to csa102, except that we add the feature that in the <code>CL_AMS_HA_STATE_ACTIVE</code> case if our previous state was <code>CL_AMS_HA_STATE_STANDBY</code> we read the sequence from the checkpoint so that the main loop will pick it up.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
checkpoint_initialize()
{
ClRcT rc = CL_OK;
ClVersionT ckpt_version = {'B', 1, 1};
ClNameT ckpt_name = { strlen(CKPT_NAME), CKPT_NAME };
ClUint32T seq_no;
ClCkptCheckpointCreationAttributesT create_atts = {
.creationFlags = CL_CKPT_WR_ACTIVE_REPLICA |
CL_CKPT_CHECKPOINT_COLLOCATED,
.checkpointSize = 2 * sizeof(ClUint32T), // two sections of 4 bytes.
.retentionDuration = (ClTimeT)0,
.maxSections = 2, // two sections
.maxSectionSize = sizeof(ClUint32T),
.maxSectionIdSize = (ClSizeT)64
};

ClCkptSectionCreationAttributesT section_atts = {
.sectionId = &ckpt_sid,
.expirationTime = CL_TIME_END
};

clprintf(CL_LOG_SEV_INFO,"%s: checkpoint_initialize", appname);
/* Initialize checkpointing service instance */
rc = clCkptInitialize(&ckpt_svc_handle, /* Checkpoint service handle */
NULL, /* Optional callbacks table */
&ckpt_version); /* Required verison number */
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: ERROR: Failed to initialize checkpoint service",
appname);
return rc;
}
clprintf(CL_LOG_SEV_INFO,"%s: Checkpoint service initialized (handle=0x%llx)",
appname, ckpt_svc_handle);
</pre></code>
|}

Here is <code>checkpoint_initialize</code>. Here we initialize the <code>ClNameT</code> structure that holds the name of the checkpoint to be opened/created with the line: <code>ClNameT ckpt_name = { strlen(CKPT_NAME), CKPT_NAME };</code>. We then define a set of attributes to associate with the checkpoint when creating that checkpoint. The <code>creationFlags</code> includes <code>CL_CKPT_WR_ACTIVE_REPLICA</code>. This means that the checkpoint to be created will be asynchronous, or once active server updation is completed, the call returns to the application, all other replica updates happens parallel. <code>CheckpointSize</code> is set to the sizeof a 32 bit unsigned integer, which is the sequence number we print in the main loop. The <code>retentionDuration</code> is the time that the checkpoint service will keep the checkpoint in store after the last client has closed the checkpoint. <code>MaxSections</code> is 2 as this checkpoint will be used to store two sections. <code>MaxSectionSize</code> is the set to the sizeof a 32 bit unsigned integer, as application stores only unsigned integer. And <code>maxSectionIdSize</code> is 64 bytes.

We next use <code>ClCkptSectionCreationAttributesT section_atts</code> to define the creation attributes for the sole section of the checkpoint. The <code>sectionId</code> is just the name of the section along with the number of bytes in the name. The <code>expirationTime</code> is set to <code>CL_TIME_END</code> to imply that the section is never deleted automatically if the checkpoint itself still remains.

The call to <code>clCkptInitialize</code> has to be called before any other checkpoint functions. The <code>ckpt_svc_handle</code> is where the handle is returned. The handle must be passed to some future checkpoint api calls, namely the <code>clCkptCheckpointOpen</code> and <code>clCkptFinalize</code> calls. The callbacks table is passed as <code>NULL</code> which implies that our application doesn't provide any callbacks. Finally the <code>ckpt_version</code> identifies what version of the api this application is written to.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
//
// Create the checkpoint for read and write.
rc = clCkptCheckpointOpen(ckpt_svc_handle, // Service handle
&ckpt_name, // Checkpoint name
&create_atts, // Optional creation attr.
(CL_CKPT_CHECKPOINT_READ |
CL_CKPT_CHECKPOINT_WRITE |
CL_CKPT_CHECKPOINT_CREATE),
(ClTimeT)-1, // No timeout
&ckpt_handle); // Checkpoint handle
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: ERROR: Failed [0x%x] to open checkpoint",
appname, rc);
(void)clCkptFinalize(ckpt_svc_handle);
return rc;
}
clprintf(CL_LOG_SEV_INFO,"%s: Checkpoint opened (handle=0x%llx)", appname, ckpt_handle);
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
/*
* Try to create a section so that updates can operate by overwriting
* the section over and over again.
* If subsequent processes come through here, they will fail to create
* the section. That is OK, even though it will cause an error message
* If the section create fails because the section is already there, then
* read the sequence number
*/
// Put data in network byte order
seq_no = htonl(seq);

// Creating the section
checkpoint_replica_activate();
rc = clCkptSectionCreate(ckpt_handle, // Checkpoint handle
&section_atts, // Section attributes
(ClUint8T*)&seq_no, // Initial data
(ClSizeT)sizeof(seq_no)); // Size of data
if (rc != CL_OK && (CL_GET_ERROR_CODE(rc) != CL_ERR_ALREADY_EXIST))
{
clprintf(CL_LOG_SEV_ERROR,"%s: ERROR: Failed to create checkpoint section", appname);
(void)clCkptCheckpointClose(ckpt_handle);
(void)clCkptFinalize(ckpt_svc_handle);
return rc;
}
else if (rc != CL_OK && (CL_GET_ERROR_CODE(rc) == CL_ERR_ALREADY_EXIST))
{
rc = checkpoint_read_seq(&seq);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: ERROR: Failed [0x%x] to read checkpoint section",
appname, rc);
(void)clCkptCheckpointClose(ckpt_handle);
(void)clCkptFinalize(ckpt_svc_handle);
return rc;
}
}
else
{
clprintf(CL_LOG_SEV_INFO,"%s: Section created", appname);
}

return rc;
}
</pre></code>
|}

With <code>rc = clCkptCheckpointOpen</code> we attempt to open the specified checkpoint. When <code>checkpoint_initialize</code> is called the checkpoint may or may not exist. We attempt to open the checkpoint for READ/WRITE access.

Next we check if we created the checkpoint and then we need to create the section with a call to <code>clCkptSectionCreate</code>. We pass the checkpoint handle obtained from <code>clCkptCheckpointOpen</code>, the section attributes declared earlier, and the address of the initial value along with the size in bytes of the initial value.

We convert the initial value to network byte order by the code <code>seq_no = htonl(seq)</code>, before passing it to <code>clCkptSectionCreate</code>.

If we do not create the section, then we read the current value in the checkpoint into our global seq variable.

Note that whenever we return an error return code from the function that we have either not opened the checkpoint/initialized the checkpoint service, or we have closed the checkpoint and finalized the checkpoint service with calls to <code>clCkptCheckpointClose</code> and <code>clCkptFinalize</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
checkpoint_finalize(void)
{
ClRcT rc;

rc = clCkptCheckpointClose(ckpt_handle);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: failed: [0x%x] to close checkpoint handle 0x%llx",
appname, rc, ckpt_handle);
}
rc = clCkptFinalize(ckpt_svc_handle);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"%s: failed: [0x%x] to finalize checkpoint",
appname, rc);
}
return CL_OK;
}
</pre></code>
|}

The above code snippet presents <code>checkpoint_finalize</code>. It's quite simple. First it closes the checkpoint handle with a call to <code>clCkptCheckpointClose</code>. Next it finalizes the checkpoint library with a call to <code>clCkptFinalize</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
checkpoint_write_seq(ClUint32T seq)
{
ClRcT rc = CL_OK;
ClUint32T seq_no;

/* Putting data in network byte order */
seq_no = htonl(seq);

/* Write checkpoint */
rc = clCkptSectionOverwrite(ckpt_handle,
&ckpt_sid,
&seq_no,
sizeof(ClUint32T));
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"Failed [0x%x] to write to section", rc);
}
else
{
/*
* Synchronize the checkpoint to all the replicas.
*/
rc = clCkptCheckpointSynchronize(ckpt_handle, CL_TIME_END );
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"Failed [0x%x] to synchronize the checkpoint", rc);
}
}

return rc;
}
</pre></code>
|}

With <code>checkpoint_write_seq</code> we first convert the sequence number passed into network byte order. Then we pass it to <code>clCKptSectionOverwrite</code> which writes it to the checkpoint section created in <code>checkpoint_initialize</code>.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
static ClRcT
checkpoint_read_seq(ClUint32T *seq)
{
ClRcT rc = CL_OK;
ClUint32T err_idx; /* Error index in ioVector */
ClUint32T seq_no = 0xffffffff;
ClCkptIOVectorElementT iov = {
.sectionId = ckpt_sid,
.dataBuffer = (ClPtrT)&seq_no,
.dataSize = sizeof(ClUint32T),
.dataOffset = (ClOffsetT)0,
.readSize = sizeof(ClUint32T)
};

rc = clCkptCheckpointRead(ckpt_handle, &iov, 1, &err_idx);
if (rc != CL_OK)
{
clprintf(CL_LOG_SEV_ERROR,"Error: [0x%x] from checkpoint read, err_idx = %u",
rc, err_idx);
}

/* FIXME: How to process this err_idx? */
*seq = ntohl(seq_no);

return rc;
}

</pre></code>
|}

With <code>checkpoint_read_seq</code> we initialize <code>seq_no</code> to all ones just so it will be more obvious if the <code>clCkptCheckpointRead</code> call fails and the value of <code>seq_no</code> doesn't get overwritten. Then, we set up the <code>iov</code> variable. We set the <code>sectionID</code> field to <code>ckpt_sid</code> which is the id of the section created in <code>checkpoint_initialize</code>. The <code>dataBuffer</code> gets set to the address of the <code>seq_no</code> variable which is where we want the checkpoint data loaded. The <code>dataSize</code> field is set to the the size of the <code>seq_no</code> variable. <code>DataOfset</code> is set to zero since the sequence number is the only thing stored in the section, so it resides at the front of the section. <code>readSize</code> is set to the size of the sequence number variable.

Within <code>checkpoint_read_seq</code> we pass the iovector to <code>clCkptCheckpointRead</code> along with the <code>ckpt_handle</code>, the constant 1, and the address of the <code>err_idx</code> variable. The constant 1 is the number of elements in the array of <code>ClCkptIOVectorElementT structs</code> that we're passing. That is, we're passing the address of a single <code>ClCkptIOVectorElementT struct</code>. The <code>err_idx</code> will hold the index in that array where <code>clCkptCheckpointRead</code> found an error. That is, if there is going to be an error, it will be at index 0 since we're only passing on entry in the <code>iovector</code>.

===csa203===

csa203 demonstrates the usage of SA Forum's Checkpointing service. This sample application does not deviate functionally from csa103. The code differences are due to using SA Forum data types (structures) and APIs , as presented in the following two tables. (Note we have not repeated data types and APIs covered previously.)

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum Data Types with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum Data Types
!OpenClovis Data Types
|-
|SaCkptHandleT
|ClCkptSvcHdlT
|-
|SaCkptHandleT
|ClCkptHdlT
|-
|SaCkptSectionIdT
|ClCkptSectionIdT
|-
|SaCkptCheckpointCreationAttributesT
|ClCkptCheckpointCreationAttributesT
|-
|SaCkptSectionCreationAttributesT
|ClCkptSectionCreationAttributesT
|-
|SaCkptIOVectorElementT
|ClCkptIOVectorElementT
|}

{| cellspacing="0" border="1" align="center"
|+align="bottom"| '''SA Forum APIs with the SAFplus Platform equivalent'''
|- style="color:black;background-color:#ffffaa;" align="center"
!SA Forum APIs
!OpenClovis APIs
|-
|saCkptInitialize
|clCkptInitialize
|-
|saCkptCheckpointOpen
|clCkptCheckpointOpen
|-
|saCkptSectionCreate
|clCkptSectionCreate
|-
|saCkptCheckpointClose
|clCkptCheckpointClose
|-
|saCkptFinalize
|clCkptFinalize
|-
|saCkptSectionOverwrite
|clCkptSectionOverwrite
|-
|saCkptCheckpointSynchronize
|clCkptCheckpointSynchronize
|-
|saCkptCheckpointRead
|clCkptCheckpointRead
|}

===How to Run csa103 and What to Observe===

This sample application can run on all Runtime Hardware Setups. The following, lists which node <code>csa103compI*</code> runs on.
<ul>
<li>'''Runtime Hardware Setup 1.1 and 2.1'''
 csa103compI0 and csa103compI1 will run upon the single node.
<li>'''Runtime Hardware Setup 1.2 and 2.2'''
 csa103compI0 runs on PayloadNodeI0 and csa103compI1 runs on PayloadNodeI1
<li>'''Runtime Hardware Setup 1.3 and 2.3'''
 csa103compI2 and csa103compI3 run on SCNodeI0 and SCNodeI1 respectively. csa103compI0 and csa103compI1 run on PayloadNodeI0 and PayloadNodeI1 respectively.
 In the four node set up SCNodeI0 and SCNodeI1 output data via <code>/root/asp/var/log/csa103CompI2</code> and <code>/root/asp/var/log/csa103CompI3</code> respectively. Therefore in this case follow the below instructions replacing csa103CompI0 and csa103compI1 with csa103compI2 and csa103compI3 respectively.
</ul>

We run csa103 very much the same way we run any of the rest of the sample applications: with the SAFplus Platform Console.

<ol>
<li>First, on the active System Controller move it to state LockAssignment with (Unlock csa203SGI0 instead of csa103SGI0 to run csa203)
<code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa103SGI0
</pre></code>

The following output is given when you run <code>tail -f</code> on the csa103 log files. For example:
<code><pre>
# tail -f /root/asp/var/log/csa103CompI0.log
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00030 : INFO)
Component [csa103CompI0] : PID [15238]. Initializing
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00031 : INFO)
IOC Address : 0x1
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00032 : INFO)
IOC Port : 0x81
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00033 : INFO)
csa103: Instantiated as component instance csa103CompI0.
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00034 : INFO)
csa103CompI0: Waiting for CSI assignment...
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00035 : INFO)
csa103CompI0: Waiting for CSI assignment...
Mon Jul 14 00:01:09 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00036 : INFO)
csa103CompI0: checkpoint_initialize
Mon Jul 14 00:01:10 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00043 : INFO)
csa103CompI0: Checkpoint service initialized (handle=0x1)
Mon Jul 14 00:01:10 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00045 : INFO)
csa103CompI0: Checkpoint opened (handle=0x2)
</pre></code>
|}

<code><pre>
# tail -f /root/asp/var/log/csa103CompI1.log
</pre></code>

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00030 : INFO)
Component [csa103CompI1] : PID [15234]. Initializing
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00031 : INFO)
IOC Address : 0x1
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00032 : INFO)
IOC Port : 0x80
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00033 : INFO)
csa103: Instantiated as component instance csa103CompI1.
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00034 : INFO)
csa103CompI1: Waiting for CSI assignment...
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00035 : INFO)
csa103CompI1: Waiting for CSI assignment...
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00036 : INFO)
csa103CompI1: checkpoint_initialize
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00043 : INFO)
csa103CompI1: Checkpoint service initialized (handle=0x1)
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00045 : INFO)
csa103CompI1: Checkpoint opened (handle=0x2)
Mon Jul 14 00:01:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00053 : INFO)
csa103CompI1: Section created
</pre></code>
|}

<li>Then, unlock the application by running
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa103SGI0
</pre></code>

In the application log files, you should see

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 00:09:08 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00058 : INFO)
Standby state requested from state 0
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 00:09:08 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00064 : INFO)
csa103CompI1: Active state requested from state 0
Mon Jul 14 00:09:09 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00065 : INFO)
csa103CompI1: Hello World! (seq=0)
Mon Jul 14 00:09:10 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00066 : INFO)
csa103CompI1: Hello World! (seq=1)
Mon Jul 14 00:09:11 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00067 : INFO)
csa103CompI1: Hello World! (seq=2)
Mon Jul 14 00:09:12 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00068 : INFO)
csa103CompI1: Hello World! (seq=3)
Mon Jul 14 00:09:13 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00069 : INFO)
csa103CompI1: Hello World! (seq=4)
</pre></code>
|}

<li>Next, find the active csa103 process, the one that's printing the Hello World lines and kill it. To find the process ID issue the following command from a bash shell.
<code><pre>
# ps -eaf | grep csa103
</pre></code>
This should produce an output that looks similar to the following.
root 17830 15663 0 14:21 ? 00:00:00 csa103Comp -p
root 17839 15663 0 14:21 ? 00:00:00 csa103Comp -p
root 18558 16145 0 14:32 pts/4 00:00:00 grep csa103
Notice the two entries that end with csa103Comp -p. These are our two component processes. The first one is usually the active process. This is the one that we will kill. In this case the process ID is 17830. So to kill the active component you issue the command:

# kill -9 17830

[[File:OpenClovis_Note.png]]If this step does not result in the active component being killed then it is likely that the standby component was killed. In this case simply try killing the other process.

After killing the active component you should see lines in the log files like the following:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 00:16:43 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00515 : INFO)
csa103CompI1: Hello World! (seq=452)
Mon Jul 14 00:16:44 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00516 : INFO)
csa103CompI1: Hello World! (seq=453)
Mon Jul 14 00:16:45 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00517 : INFO)
csa103CompI1: Hello World! (seq=454)
Mon Jul 14 00:16:46 2008 (SCNodeI0.15234 : csa103CompEO.---.---.00518 : INFO)
csa103CompI1: Hello World! (seq=455)
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /var/log/csa103CompI0Log.latest
|-
|<code><pre>
Mon Jul 14 00:16:48 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00065 : INFO)
csa103CompI0: Active state requested from state 2
Mon Jul 14 00:16:48 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00066 : INFO)
csa103CompI0 reading checkpoint
Mon Jul 14 00:16:48 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00067 : INFO)
csa103CompI0 read checkpoint: seq = 456
Mon Jul 14 00:16:49 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00068 : INFO)
csa103CompI0: Hello World! (seq=456)
Mon Jul 14 00:16:50 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00069 : INFO)
csa103CompI0: Hello World! (seq=457)
Mon Jul 14 00:16:51 2008 (SCNodeI0.15238 : csa103CompEO.---.---.00070 : INFO)
csa103CompI0: Hello World! (seq=458)
</pre></code>
|}

Where we can see CompI1 printing 455 and then dieing, where upon CompI0 gets the notice to take over processing, reads the checkpoint and then takes over with seq=456 and so on.

Then, in the CompI1 log file we see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 00:16:49 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00044 : INFO)
csa103: Instantiated as component instance csa103CompI1.
Mon Jul 14 00:16:49 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00045 : INFO)
csa103CompI1: Waiting for CSI assignment...
Mon Jul 14 00:16:49 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00046 : INFO)
csa103CompI1: Waiting for CSI assignment...
Mon Jul 14 00:16:49 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00047 : INFO)
csa103CompI1: checkpoint_initialize
Mon Jul 14 00:16:50 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00054 : INFO)
csa103CompI1: Checkpoint service initialized (handle=0x1)
Mon Jul 14 00:16:50 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00056 : INFO)
csa103CompI1: Checkpoint opened (handle=0x2)
</pre></code>
|}

That is the component that had been killed being restarted.

CompI0 is moving along just fine, and we see CompI1 come back up. If we then kill CompI0 we see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa103CompI1Log.latest
|-
|<code><pre>
Mon Jul 14 00:29:44 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00065 : INFO)
csa103CompI1: Active state requested from state 2
Mon Jul 14 00:29:44 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00066 : INFO)
csa103CompI1 reading checkpoint
Mon Jul 14 00:29:44 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00067 : INFO)
csa103CompI1 read checkpoint: seq = 1225
Mon Jul 14 00:29:45 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00068 : INFO)
csa103CompI1: Hello World! (seq=1225)
Mon Jul 14 00:29:46 2008 (SCNodeI0.15553 : csa103CompEO.---.---.00069 : INFO)
csa103CompI1: Hello World! (seq=1226)
</pre></code>
|}

Where we can see the CompI0 process die, and CompI1 process read the sequence number from the checkpoint and then take over from where CompI0 left off.

<li>To stop csa103 use the following SAFplus Platform Console command.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa103SGI0
</pre></code>

<li>Now change the state of csa103SGI0 to LockInstantiation and close the SAFplus Platform Console.
<code><pre>
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa103SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
</pre></code>
</ol>

===Additional Tests for Runtime Hardware Setup 1.3 and 2.3===

Now repeat the experiment till the stage before we kill the active process and follow these steps.

'''Step A'''
<ol>
<li>Stop SAFplus Platform on SCNodeI0 using <code>/etc/init.d/asp stop</code>. Observer the logs <code>/root/asp/var/log/csa103CompI3Log.latest</code> on SCNodeI1. This will become active and start printing the hello world logs as above.
Note in this case active System Controller SCNode1 is still aware of PayloadNodeI0 and PayloadNodeI1.
<li>Start looking at the logs for <code>/root/asp/var/log/csa103CompI0Log.latest</code> in PayloadNodeI0. This will print the standby logs as above.
<li>Stop SAFplus Platform on PayloadNodeI0 and start observing the logs on PayloadNodeI1 in <code>/root/asp/var/log/csa103CompI1Log.latest</code> for standby.
In this case, you can see, via the active System Controller logs that PayloadNodeI0 is not active whilst PayloadNodeI1 is.
</ol>

'''Step B''' For Hardware Setup 1.3 only
#Repeat A with the slight exception that the blade running SCNodeI0 is yanked out(<code>/etc/init.d/asp zap</code>) instead of gracefully shutting down SAFplus Platform in step 1.

===Summary and References===
We've seen :

*how to use Clovis' checkpoint service to save some program state and recover that state from a separate process
*how to initialize the client checkpoint library
*how to create and open checkpoints
*how to create and use sections in an opened checkpoint

Further information can be found within the following: ''OpenClovis API Reference Guide''.

Doc:latest/evalguide/csa102

2010-08-27T03:15:54Z

Senthilk:

==csa102 Redundancy and Failover==

===Objective===

This sample demonstrates basic HA (High Availability) and SU (Service Unit) fail-over functionality. The application has two components, both processing the same workload as csa101, that is, repeatedly printing "Hello World". The difference, however, is that in this case there is now an active component and a standby component, with only the active component performing the printing function.

csa102 is quite similar to csa101, and this section will discuss the areas in which they deviate.

===What you will learn===

*Keeping track of HA states and how to respond to callbacks requesting HA state changes.

===Code===

The code can be found within the following directory
<project-area_dir>/eval/src/app/csa102Comp

This sample component is implemented in a single C module that is quite similar to the csa101 module. We will discuss the additions in detail.

We define a static variable to keep track of the component's HA state as:
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.h
|-
|<code><pre>
#define STRING_HA_STATE(S) \
( ((S) == CL_AMS_HA_STATE_ACTIVE) ? "Active" : \
((S) == CL_AMS_HA_STATE_STANDBY) ? "Standby" : \
((S) == CL_AMS_HA_STATE_QUIESCED) ? "Quiesced" : \
((S) == CL_AMS_HA_STATE_QUIESCING) ? "Quiescing" : \
((S) == CL_AMS_HA_STATE_NONE) ? "None" : \
"Unknown" )
</pre></code>
|}

This is subsequently used to control the processing of this component's workload.

As with csa101, the <code>clCompAppAMFCSISet()</code> function is called to set the component's HA state, and the following block of code assigns this requested state to the component, while verbosely detailing this process:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
clCompAppAMFCSISet()

switch ( haState )
{
case CL_AMS_HA_STATE_ACTIVE:
{
/*
* AMF has requested application to take the active HA state
* for the CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa102: ACTIVE state requested; activating service\n");
running = 1;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

case CL_AMS_HA_STATE_STANDBY:
{
/*
* AMF has requested application to take the standby HA state
* for this CSI.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa102: New state is not the ACTIVE; deactivating service\n");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
case CL_AMS_HA_STATE_QUIESCED:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active or quiescing HA state. The application
* must stop work associated with the CSI immediately.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa102: Acknowledging new state\n");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

clCpmResponse(cpmHandle, invocation, CL_OK);
break;
}

case CL_AMS_HA_STATE_QUIESCING:
{
/*
* AMF has requested application to quiesce the CSI currently
* assigned the active HA state. The application must stop work
* associated with the CSI gracefully and not accept any new
* workloads while the work is being terminated.
*/

/*
* ---BEGIN_APPLICATION_CODE---
*/

clprintf(CL_LOG_SEV_INFO,"csa102: Signaling completion of QUIESCING\n");
running = 0;

/*
* ---END_APPLICATION_CODE---
*/

clCpmCSIQuiescingComplete(cpmHandle, invocation, CL_OK);
break;
}

default:
{
break;
}
}

</pre></code>
|}

It is worth noting that the <code>running</code> variable, as used by csa101 is not modified here. Instead, the <code>ha_state</code> variable is used to control the component's workload processing, as displayed in the main worker loop:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffccaa;" align="center"| clCompAppMain.c
|-
|<code><pre>
ClCompAppInitialize()

while (!exiting)
{
if (running)
{
clprintf(CL_LOG_SEV_INFO,"csa102: Hello World! %s\n", show_progress());
}
sleep(1);
}

</pre></code>
|}

It is also worth noting that the <code>running</code> variable is still used to control the worker loop as in csa101, but it is only controlled by requests to change the EO (Executable Object) state, not the HA state of the component.

===How to Run csa102 and What to Observe===

As with the csa101 example we will use the SAFplus Platform Console to manipulate the administrative state of the csa102 service group.

<ol>
<li>Start the SAFplus Platform Console<code><pre>
# cd /root/asp/bin
# ./asp_console</pre></code>

<li>Then put the csa102SGI0 service group into lock assignment state using the following commands.<code><pre>
cli[Test]-> setc 1
cli[Test:SCNodeI0]-> setc cpm
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
</pre></code>

Because example 102 has two components there will be two application log files to view. These are <code>/root/asp/var/log/csa102CompI0Log.latest</code> and <code>/root/asp/var/log/csa102CompI1Log.latest</code>. Viewing these application logs using the <code>tail -f</code>, you should see the following.

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00029 : INFO)
Component [csa102CompI0] : PID [13418]. Initializing

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00030 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00031 : INFO)
IOC Port : 0x80

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00032 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:38:17 2008 (SCNodeI0.13418 : csa102CompEO.---.---.00033 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| //root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00028 : INFO)
Component [csa102CompI1] : PID [13422]. Initializing

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00029 : INFO)
IOC Address : 0x1

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00030 : INFO)
IOC Port : 0x81

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00031 : INFO)
csa102: Instantiated as component instance csa102CompI1.

Sun Jul 13 22:38:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00032 : INFO)
csa102CompI1: Waiting for CSI assignment...
</pre></code>
|}

<li>Next, unlock the service group using the following SAFplus Platform Console command.
<code><pre>
# cli[Test:SCNodeI0:CPM]-> amsUnlock sg csa102SGI0
</pre></code>
and in the /var/log/csa102CompI*.log files we should see:

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! .
</pre></code>
|}

{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 22:43:00 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00043 : INFO)
csa102: New state is not the ACTIVE; deactivating service
</pre></code>
|}

These can be watched in a separate terminal window using <code>tail -f</code>. csa102CompI0 is the active component in this case, and csa102CompI1 is the standby. Consequently, the "Hello world!" lines appear in csa102CompI0.log and not in csa102CompI1.log. They will continue to be logged to that file until the HA state of that component changes, for example, when the process logging those lines is killed. In the mean time the standby component: csa102CompI1 just waits until it is told that it should take over the workload.
</ol>

'''Changing the HA state of the Client/Server'''

The easiest way to test component fail-over is to kill the process associated with the active component using the <code>kill</code> command. For this you need to know the process ID of the active component. To find the process ID issue the following command from a bash shell.
# ps -eaf | grep csa102
This should produce an output that looks similar to the following.
root 15872 15663 0 13:49 ? 00:00:01 csa102Comp -p
root 16328 15663 0 13:56 ? 00:00:00 csa102Comp -p
root 17304 16145 0 14:11 pts/4 00:00:00 grep csa102
Notice the two entries that end with <code>csa102Comp -p</code>. These are our two component processes. The first one is usually the active process. This is the one that we will kill. In this case the process ID is 15872. So to kill the active component you issue the command:
# kill -9 15872
[[File:OpenClovis_Note.png]]If this step does not result in the active component being killed then it is likely that the standby component was killed. In this case simply try killing the other process.

After executing the <code>kill</code> command you can see in the csa102CompI1 application that the standby component is now active.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI1Log.latest
|-
|<code><pre>
Sun Jul 13 23:00:18 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00487 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:19 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00488 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:20 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00489 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:21 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00490 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:22 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00491 : INFO)
csa102: Hello World! .

Sun Jul 13 23:00:23 2008 (SCNodeI0.13422 : csa102CompEO.---.---.00492 : INFO)
csa102: Hello World! . .
</pre></code>
|}

This indicates that the standby component has taken over for the failed active component.

Looking in the csa102CompI0 application log you can see that this component was killed and has been restarted. Since csa102CompI1 took over as the active component this component now goes into the standby state.
{| cellspacing="0" cellpadding = "0" border="0" align = "center" width="680"
! style="color:black;background-color:#ffffaa;" align="center"| /root/asp/var/log/csa102CompI0Log.latest
|-
|<code><pre>
Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00040 : INFO)
Component [csa102CompI0] : PID [13712]. Initializing

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00041 : INFO)
IOC Address : 0x1

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00042 : INFO)
IOC Port : 0x80

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00043 : INFO)
csa102: Instantiated as component instance csa102CompI0.

Sun Jul 13 22:53:02 2008 (SCNodeI0.13712 : csa102CompEO.---.---.00044 : INFO)
csa102CompI0: Waiting for CSI assignment...
</pre></code>
|}

You can continue to observe this failover by alternately killing the active component.

To stop csa102 using the SAFplus Platform Console.
cli[Test:SCNodeI0:CPM]-> amsLockAssignment sg csa102SGI0
Successfully changed state of csa102SGI0 to LockAssignment
cli[Test:SCNodeI0:CPM]-> amsLockInstantiation sg csa102SGI0
cli[Test:SCNodeI0:CPM] -> end
cli[Test:SCNodeI0] -> end
cli[Test] -> bye
Successfully changed state of csa102SGI0 to LockInstantiation and exit.

===Summary===

This Sample Application has covered basic HA and failover, with changing the state of a component to active and standby.

Doc:latest/evalguide/csa

2010-08-27T03:15:02Z

Senthilk:

==Sample Applications==

Each sample application demonstrates a different feature of SAFplus Platform, by showing particular APIs and their usage. Some of the features demonstrated are Checkpointing, Provisioning, Component Failover, Event Subscription and Publication. These are itemized further within Table
[[#Table_Clovis_Sample_Applications|Clovis Sample Applications]].

The numbering of the application follows a general guideline. csa101 through csa113 are designed to demonstrate one particular feature of SAFplus Platform at a time. In addition higher numbered sample application tend to build on concepts introduced in lower numbered applications.

The sample applications are located within:
<project-area_dir>/eval/src/app

===SA Forum Compliance===

Adherence to standards is a critical requirement for Next Generation Network deployments. The Service Availability Forum (SA Forum) is the primary standards body in the context of High Availability Middleware and enjoys the participation of over 95% of Tier 1 TEMs. OpenClovis has been actively participating in the forum and helping to drive the emerging Hardware Platform Interface (HPI) and Application Interface Specification (AIS) standards based on its experience.

As a result of the close involvement of OpenClovis with the SA Forum, the OpenClovis product is aligned with the SA Forum standards which specifies a Highly Available (HA) Applications Framework. The framework defines various services such as Availability Management Framework (AMF), Checkpointing, Group Membership and Event Services.

In this chapter we also introduce a SA Forum compliant variance of the Clovis Sample Applications, using SA Forum APIs rather than OpenClovis APIs. These sample applications are labeled as the 200 series and are functionally equivalent to the Clovis Sample Application 100 series. The main difference is in using SA Forum APIs rather than OpenClovis APIs. For example csa101 has a SA Forum functionally equivalent, labeled csa201, where the only real differences are in function names, eg. <code>clCpmClientInitialize</code> and <code>clCpmComponentNameGet</code> have the SA Forum equivalent <code>saAmfInitialize</code> and <code>saAmfComponentNameGet</code>.

Since SA Forum does not cover various services provided by SAFplus Platform we will limit sample applications to only those services which SA Forum has defined.

The SA Forum equivalent sample applications are located within:
<project-area_dir>/eval/src/app

===Clovis Sample Applications===

The following table provides a brief descriptions of the sample applications found within this Evaluation Guide. For a detailed description of how to create and build csa101 using OpenClovis IDE and OpenClovis SAFplus Platform, see the ''OpenClovis Sample Application Tutorial''.



{| border="1" cellpadding="20" cellspacing="0"
|+align="bottom" | '''Clovis Sample Applications'''
|- style="background-color:#ffffcc;"
|App.Ref.
|Scope
|Description
|-
|csa101
|Basic component management
|Periodic Hello World message, can be suspended/resumed, started/shutdown/killed from CPM via the SAFplus Platform Console.
|-
|csa102
|Basic redundancy and failover
|csa101 plus capable of starting one active and one standby instances. Only active prints messages. Once active is killed (emulating a crash or by a manual switch-over), standby becomes active and print messages.
|-
|csa103
|Failover and checkpointing
|csa102 plus a incremented sequence number (SN) is printed with each message. The SN is checkpointed to standby, so standby continues from where the active left off.
|-
|csa104
|Basic app. manageability
|csa103 plus the frequency of the print is configurable at run-time via a managed attribute. This attribute is exposed by both the SAFplus Platform Console as well as SNMP, and the MIB is provided for this.
|-
|csa105
|Alarm Managment
|Demonstrates how provisioning and alarm libraries work together to achieve a simple software alarm management, and how COR change notification is utilized.
|-
|csa112
|Event Subscription
|Demonstrates how to use Clovis' event service to subscribe to events.
|-
|csa113
|Event Publisher
|how to publish events using Clovis' Event Manager API
|}

===Starting and Stopping SAFplus Platform===

====Starting SAFplus Platform====

To start SAFplus Platform on System Controller node.
<ol>
<li>Open a shell.
<li>ssh into the System Controller node as root.
<li>once logged in, at /root run the following commands
<code><pre>
# cd asp
# etc/init.d/asp start
</pre></code>
</ol>

[[File:OpenClovis_Note.png]] If SAFplus Platform fails to start properly it could be due to the machine's firewall being enabled. SAFplus Platform will not run properly with an enabled firewall. See the ''Environment Related Observation'' section of the ''OpenClovis Release Notes'' for more information.

[[File:OpenClovis_Note.png]] Only one System Controller can run in an active state, on a subnet at one time.

Repeat steps 1 to 3, for Payload Node 1 and 2, if any.

At this point, we don't have any applications running on these blades. They are available, but not started. We can start/stop the sample applications by Unlocking/Locking the Service Group (this is SA Forum terminology) corresponding to each application using the OpenClovis SAFplus Platform Console. This method is described further within Section [[Doc:Evalguide/csa102#How to Run csa102 and What to Observe|How to Run csa102 and What to Observe]]. The start/stop mechanism is to allow us to run 1 application at a time, so we are not flooded with the output from all the applications, all intermixed.

As the reader progresses through this chapter, each application will be discussed, various code snippets will be highlighted to explain SAFplus Platform capabilities, and you will then be given the commands to start that particular sample running, allowing you to examine the output from the sample.

[[File:OpenClovis_Note.png]] By default SCNode0, SCNode1, PayloadNode0 and PayloadNode1 are configured (see target.conf) to use the eth0 ethernet interface. Within each of the nodes this configuration information is stored within the following two files.
*<code>/root/asp/etc/clGmsConfig.xml</code>
*<code>/root/asp/etc/asp.conf</code>

This is not always the case, for example on one of your nodes you may want to switch to eth1. If you would like to do so without changing target.conf and rebuilding the images and redeploying then use your favourite editor, eg vi, to replace the occurrence of eth0 with the appropriate form, e.g. eth1 in these two files.

====Stopping SAFplus Platform====

To stop SAFplus Platform on the System Controller
<ol>

<li>Open a shell.

<li>ssh into the System Controller node as root.

<li>once logged in, at /root run the following command
<code><pre>
# cd asp
# etc/init.d/asp stop
</pre></code>

</ol>

As mentioned within Section [[#Starting SAFplus|Starting SAFplus]], repeat steps 1 to 3, for the Payload nodes, if any. The steps clean up the SAFplus Platform processes and *.db files.

===Sample Application Output===

Purely to ease the output from the collection of Sample Applications, Clovis has used an approach to logging output with the use of printf(). These files are output with the aid of the "ev" library and the ev.h header file. The header file is located within the below directory.
<code><pre>
<project-area_dir>/eval/src/app/ev
</pre></code>

Doc:latest/evalguide/build

2010-08-27T03:14:21Z

Senthilk:

==Building the Evaluation System and Deploying Runtime Images==

This chapter logically follows from the Installation Guide where we installed the OpenClovis SAFplus Platform SDK. The following sections use the term <code>'''<install_dir>'''</code> to refer to the directory in which the SAFplus Platform SDK was installed. By default, this directory is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. The following sections describe how to build the evaluation model and deploy the runtime images so that we can run them and observe their behavior.

===Building the Target Images===

This section describes the steps to:
* Create a project area
* Modify OpenClovis sample applications
* Build SAFplus Platform and the Evaluation System
* Setup a configuration file to run any of the six Hardware Setups 1.1 to 2.3
* Create the target image.

====Creating a Project Area====

To work with the OpenClovis SDK Evaluation System, you will need to use the example project area provided with the SDK. A project area is designed to hold multiple models which share the SAFplus Platform source tree within the SDK installation.

<ol>
<li>If you have write access to the examples area of the <code> <install_dir> </code> you can simply use this as you project area. In this case your <code>'''<project_area>'''</code> would be <code>'''<install_dir>/sdk-3.0/src/examples'''</code>.

<li>If you do not have write access to <code>'''<install_dir>/sdk-3.0/src/examples'''</code> create a new directory and copy the evaluation system model to it. For example:
<code><pre>
$ mkdir <new_project_area>
$ cp -r <install_dir>/sdk-3.0/src/examples/eval \
<new_project_area>/.
</pre></code>
In this case your <code>'''<project_area>'''</code> would be <code>'''<new_project_area>'''</code>.
</ol>

In either case your <code>'''<project_area>'''</code> should have the following directory structure:
<code><pre>
<project_area>
|ide_workspace
|+eval
| |+build
| | |+local
| | | |-Makefile
| |+src
| | |+app
| | |+config
| | |+doc
| | |-target.conf
| |-Makefile
|-Makefile
</pre></code>

====Modifying the Clovis Sample Applications====

We have provided the option to modify and rebuild the supplied sample applications.

<ol>
<li> Modifying sample application code as you see fit:

 The Clovis Sample Application's are located in:
<code> '''<project_area>/eval/src/app''' </code>

 The source files for the sample application components csa101comp to csa113comp are listed here. Make the necessary alteration to the csa files.

<li>Build the single/distributed target images, as discussed below.
</ol>

====Building SAFplus Platform and the Evaluation System====

The next step is to build both SAFplus Platform and the evaluation model in the existing project area.
<ol>
<li>Configure the eval model for building by running the following:
<code><pre>
$ cd <project_area>
$ <install_dir>/sdk-3.0/src/SAFplus/configure \
--with-model-name=eval --with-asp-build
</pre></code>

This will configure the eval model for deployment on the local machine. In order to crossbuild this model for deployment on a non-native target supported by the <crossbuild> toolchain, run:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure \
--with-model-name=eval --with-asp-build \
--with-cross-build=<crossbuild>
</pre></code>

It is possible to configure the model to be built for multiple targets by issuing as many <code>configure</code> commands as necessary. Each run sets up a target-specific build location at <code><project_area>/eval/build</code>.

If this model is to be deployed on an ATCA-based system with OpenHPI-based shelf management, enable Chassis Management with:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure \
--with-model-name=eval --with-asp-build \
--with-cross-build=<crossbuild> --with-cm-build=openhpi
</pre></code>

For a complete list of options to <code>configure</code>, including a list of available crossbuild toolchains, run:
<code><pre>
$ <install_dir>/sdk-3.0/src/SAFplus/configure --help
</pre></code>

If the necessary crossbuild toolchain does not exist, then you must install it by downloading it adjacent to the OpenClovis SDK installer and re-running install.sh.

The configure step prepares the project area to build the eval model, with the following directory structure:
<code><pre>
<project_area>
|ide_workspace
|+eval
| |+build
| | |+local
| | | |-Makefile
| | |+<crossbuild>
| | | |-Makefile
| |+src
| | |+app
| | |+config
| | |+doc
| | |-target.conf
| |+target
| |-Makefile
|-Makefile
</pre></code>

<li>Build the configured model by issuing <code>make</code> in <code>'''<project_area>/eval'''</code>:
<code><pre>
$ cd <project_area>/eval
$ make
</pre></code>

This will build the eval model for all the targets it has been configured to build. In order to do a target-specific build, issue <code>make</code> from the target-specific build location. e.g. for a local build:
<code><pre>
$ cd <project_area>/eval/build/local
$ make
</pre></code>
For a target supported by the <crossbuild> toolchain:
<code><pre>
$ cd <project_area>/eval/build/<crossbuild>
$ make
</pre></code>

For a complete list of options to <code>make</code>, run:
<code><pre>
$ make help
</pre></code>

The model source is located at <code>'''<project_area>/eval/src'''</code>. If any changes are made to this, rebuild the model by issuing another <code>make</code> from either the target-specific build location or the top project area directory.
</ol>

====Configuration File - target.conf====
Now that the code has been built we are almost ready to build images for deployment to our hardware. But first we must define the target system's configuration so that we build the correct images. A model's target system configuration is specified using a configuration file - <code>target.conf</code>. It is located at <code><project_area>/eval/src/target.conf</code>. Open this file using your favorite editor (e.g. <code>vi</code>):
<code><pre>
$ vi <project_area>/eval/src/target.conf
</pre></code>

This file specifies a number of parameters that need to be defined for a given run-time target:
<ol>
<li>'''TRAP_IP''' (Mandatory): Specifies where the SNMP SubAgent should send traps at runtime. If you do not have an SNMP SubAgent in your model specify '''127.0.0.1''' as the value. e.g.:
<code><pre>
TRAP_IP=127.0.0.1
</pre></code>
<li>'''CMM_IP''' (Mandatory if deployed on an ATCA chassis): Specifies the IP address of the target system's chassis management module or shelf manager. If you are running Hardware Setup 2.1, 2.2 or 2.3 involving PC(s)/Laptop(s) then do not define this variable. ATCA chassis Example:
<code><pre>
CMM_IP=169.254.1.2
</pre></code>
<li>'''CMM_USERNAME''' and '''CMM_PASSWORD''' (Mandatory if deployed on an ATCA chassis): Specifies the username and password required for the OpenClovis SAFplus Platform Chassis Manager to connect to the target system's chassis management module. e.g.:
<code><pre>
CMM_USERNAME=root
CMM_PASSWORD=password
</pre></code>
<li>'''INSTALL_PREREQUISITES=YES|NO''' (Mandatory): Specifies whether the target images will include 3rd party runtime prerequisites or not. Say '''YES''' if the target nodes do not meet the target host requirements specified in the Installation section of this document. e.g.:
<code><pre>
INSTALL_PREREQUISITES=YES
</pre></code>
<li>'''INSTANTIATE_IMAGES=YES|NO''' (Mandatory): Specifies whether <code>make images</code> will generate node-instance specific images instead of only generating node-type specific images. This option is a development optimization for advanced users of OpenClovis SDK. If unsure, say '''YES'''. e.g.:
<code><pre>
INSTANTIATE_IMAGES=YES
</pre></code>
<li>'''CREATE_TARBALLS=YES|NO''' (Mandatory): Specifies whether the node-instance specific images created will be packaged into tarballs for deployment onto the target system. If unsure, say '''YES'''. e.g.:
<code><pre>
CREATE_TARBALLS=YES
</pre></code>
<li>'''TIPC_NETID''' (Mandatory): Specifies a unique identifier used by TIPC to set up interprocess communication across the deployed OpenClovis SAFplus Platform cluster. This is an unsigned 32-bit integer, and must be unique for every model that is deployed. e.g.:
<code><pre>
TIPC_NETID=1337
</pre></code>
<li>'''Node Instance Details''': These specify the node-instance specific parameters required for deploying the model. For each node in the model there is a corresponding entry in the file:
<ol>
<li>'''SLOT_<node instance name>''' (Mandatory): Specifies which slot the node is located in. The first slot is slot 1 -- DO NOT USE SLOT NUMBER 0, it is invalid. When deployed to an ATCA chassis, the physical slot in which the blade is actually installed will override this value. When deployed to regular (non-ATCA) systems, this is a logical slot and must be unique for every node in the cluster. e.g.:
<code><pre>
SLOT_SCNodeI0=1
</pre></code>
<li>'''LINK_<node instance name>''' (Optional): Specifies the ethernet interface used by the node for OpenClovis SAFplus Platform communication with the rest of the cluster. If unspecified, this defaults to <code>eth0</code>. e.g.:
<code><pre>
LINK_SCNodeI0=eth0
</pre></code>
<li>'''ARCH_<node instance name>''' (Optional if '''ARCH''' is specified): Specifies the target architecture of the node as a combination of machine architecture (MACH) and linux kernel version. This is only required on a per-node basis if the target cluster has heterogeneous architectures across the nodes. If it is a homogeneous cluster, a single '''ARCH''' parameter (described below) will suffice. e.g.:
<code><pre>
ARCH_SCNodeI0=i386/linux-2.6.14
</pre></code>
<li>'''ARCH''' (Optional if node-specific '''ARCH_''' parameters are specified): Specifies the target architecture of all nodes in a homogeneous cluster as a combination of machine architecture (MACH) and linux kernel version. Note: The build process automatically populates this variable based on the last target the model is built for.e.g.:
<code><pre>
ARCH=i386/linux-2.6.14
</pre></code>
</ol>
For example, if we have a three-node cluster with the following details:
{| border="0" cellpadding="3" align="center" width="600"
|+ align="bottom" | '''Example Node Instance Detail'''
|- style="color:#ffffff; background:#549cc6"
!style="color:#66b154; background:#09477c"| Node Name
!style="color:#66b154; background:#09477c"| Slot Number
!style="color:#66b154; background:#09477c"| Link Interface
!style="color:#66b154; background:#09477c"| Architecture
|- style="color:#ffffff; background:#549cc6"
|SCNodeI0
|1
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI0
|3
|eth0
|i386/linux-2.6.14
|- style="color:#ffffff; background:#549cc6"
|PayloadNodeI1
|4
|eth1
|ppc/linux-2.6.9
|}
we would specify the node instance details as:
<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4

LINK_SCNodeI0=eth0
LINK_PayloadNodeI0=eth0
LINK_PayloadNodeI1=eth1

ARCH_SCNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI0=i386/linux-2.6.14
ARCH_PayloadNodeI1=ppc/linux-2.6.9
</pre></code>
</ol>

=====Evaluation Kit 'Node Instance Details' Examples=====
The 'Node Instance Details' of your <code>target.conf</code> file will be different depending on the hardware setup you are using for your evaluation. Below are some example settings for the various hardware setups.

<ol><li>If you are using single node case as in Hardware Setup 1.1 or 2.1, either using one blade or PC, you set up similar to the following configuration details. Change the slot number accordingly.

<code><pre>
SLOT_SCNodeI0=1
</pre></code>

<li>If you wish to set up a 3 node distributed system, as in Hardware Setup 1.2 or 2.2, your <code>target.conf</code> file may be set up similar to the following configuration details. Again change the slot numbers accordingly.

<code><pre>
SLOT_SCNodeI0=1
SLOT_PayloadNodeI0=2
SLOT_PayloadNodeI1=3
</pre></code>

<li>If you are setting up a 4 node distributed system, as in Hardware Setup 1.3 or 2.3, you would use a configuration that is similar to the following details.

<code><pre>
SLOT_SCNodeI0=1
SLOT_SCNodeI1=2
SLOT_PayloadNodeI0=3
SLOT_PayloadNodeI1=4
</pre></code>
</ol>

====Building Single/Distributed Target Image(s)====

This section describes how to build target images for particular Hardware Setups. In essence we provide two types of target image, the System Controller or Payload Node. The images are built with the <code>'''make images'''</code> command:
$ cd <project_area>/eval
$ make images

If <code>target.conf</code> has been configured to instantiate images and create tarballs as recommended, these are populated at <project_area>/target/eval/images. Each node-specific image is provided as a directory containing the run-time files (binaries, libraries, prerequisites, and configuration files) as well as a tarball with the same content. e.g. For a model containing three nodes: <code>SCNodeI0</code>, <code>PayloadNodeI0</code> and <code>PayloadNodeI1</code>, the following are the files and directories generated for deployment on the run-time system.
<code><pre>
<project_area>
|+target
|+<model>
|+images
|+SCNodeI0
| |+bin
| |+etc
| |+lib
| |+var
|-SCNodeI0.tgz
|+PayloadNodeI0
|-PayloadNodeI0.tgz
|+PayloadNodeI1
|-PayloadNodeI1.tgz
</pre></code>

===Content of Target Images===

====Content of Single Node Setup====

If you chose to create a single node setup then the following directory structure is created.
Note it is not the exhaustive directory structure but instead highlights directories and files of importance.

<code><pre>
<project_area>target/eval/images/
|-target
|
|-eval
| |images
| | |-generic
| | | |+bin
| | | |+etc
| | | |+lib
| | | |+modules
| | | |+share
| | |
| | |-SCNodeI0
| | | |+bin
| | | |+etc
| | | |+lib
| | | |+modules
| | | |+share
| | |
| | |-SCNodeI0.tgz
</pre></code>

The images directory contains everything required to deploy SAFplus Platform on the chosen runtime setup. In this case, a generic node image and one created specifically for SCNodeI0 are created, both containing the following:
<ul>
<li><code>'''bin'''</code>
 contains executable binaries and scripts, such as asp_amf, asp_console and csa101.

<li><code>'''etc'''</code>
 contains XML and text configuration files for SAFplus Platform and third-party tools, as well as an init.d style script to start/stop SAFplus Platform

<li><code>'''lib'''</code>
 libraries, including 3rd party dependencies, required by the sample applications

<li><code>'''modules'''</code>
 kernel modules (ioc, alarm)

<li><code>'''share'''</code>
 contains snmp & mib information
</ul>

'''SCNodeI0'''

Contains the System Controller image to be used for the single node case. This image is to be copied to the target platform.

====Content of 3 Node Distributed Setup====

If we are building the distributed Evaluation System, additional images for PayloadNode0 and PayloadNode1 are now utilized and this is represented within the content of the directory structure. (When compared to the single node set up, the bold directories/files represent the difference in file structure).

<code><pre>
<project_area>target/eval/images/
|-target
|
|-eval
| |images
| | |+generic
| | |
| | |-PayloadNodeI0
| | | |+bin
| | | |+etc
| | | |+lib
| | | |+modules
| | | |+share
| | |-PayloadNodeI0.tgz
| | |
| | |-PayloadNodeI1
| | | |+bin
| | | |+etc
| | | |+lib
| | | |+modules
| | | |+share
| | |-PayloadNodeI1.tgz
| | |
| | |+SCNodeI0
| | |-SCNodeI0.tgz
</pre></code>

'''PayloadNode0 & PayloadNode1'''

These additional directories are required for a distributed setup and have a similar structure to SCNodeI0. <code>PayloadNodeI0.tgz</code> and <code>PayloadNodeI1.tgz</code> are the corresponding zipped tar images that are to be copied to the target Payload nodes.
 

There is nothing special about which node should be the System Controller verses a Payload Node, or which node should be Payload Node 0 verses Payload Node 1. You may copy any tar image to any node -- the contents of the tar image will make the node assume the role. The only exception is, of course, an environment that contains different hardware, for example, an Intel-based machine and a PowerPC based machine. In that case you need to define your ARCH variables correctly (see above) and deploy images only to matching hardware.

====Content of 4 Node Distributed Setup====

If we are building the 4 node distributed Evaluation System, the additional image SCNodeI1 is now created and this is represented within the content of the directory structure. (When compared to the 3 node distributed set up, the bold directories/files represent the difference in file structure)

<code><pre>
<project_area>target/eval/images/
|-target
|-eval
| |images
| | |+generic
| | |
| | |+PayloadNodeI0
| | |-PayloadNodeI0.tgz
| | |+PayloadNodeI1
| | |-PayloadNodeI1.tgz
| | |+SCNodeI0
| | |-SCNodeI0.tgz
| | |
| | |-SCNodeI1
| | | |+bin
| | | |+etc
| | | |+lib
| | | |+modules
| | | |+share
| | |
| | |-SCNodeI1.tgz
</pre></code>

'''SCNodeI1'''

These additional directories are required for a distributed setup and have a similar structure to SCNodeI0. SCNodeI1.tgz is the corresponding zipped tar image that needs to be copied to the second System Controller.

===Runtime Software Installation===

The hardware setups require steps to copy the runtime images from the Development Machine to the Runtime target machine(s). The following describe the necessary steps required to copy runtime images to the desired target(s).

====Installing SCNodeI0====
<ol>

<li>On the Development Machine locate the target images
<code><pre>
$ cd <project_area>/target/eval/images
</pre></code>

<li>Copy the zipped tar System Controller image to the desired target.
<code><pre>
$ scp SCNodeI0.tgz root@<SystemController IPAddress>:/root/
</pre></code>
Enter password.
<code><pre>
# ssh root@<SystemController IPAddress>
</pre></code>
Enter password
<code><pre>
# cd /root
# mkdir asp
# cd asp
# tar xzvf ../SCNodeI0.tgz
</pre></code>
This unzips and extracts the contents of <code>SCNodeI0.tgz</code> within <code>/root/asp</code>. The System Controller is now installed on the target.

[[File:OpenClovis_Note.png]] This step is necessary even if the System Controller and Management Machine are the same PC (As in Runtime Hardware Setup 2.1)

If you are setting up a 4 node distributed setup, as in 'Runtime Hardware Setup 1.3.' repeat the above steps, replacing the IP address with SCNodeI1's and securely copying <code>SCNodeI1.tgz</code>.
</ol>

====Installing PayloadNode0 and PayloadNode1====

Perform the following, if the distributed Hardware Setup 1.2, 1.3, 2.2 and 2.3 is chosen:
<ol>
<li>On the Development machine locate the Target images
<code><pre>
$ cd <project_area>/target/eval/images
</pre></code>

<li>Copy the zipped tar PayloadNode0 image to the desired target.
<code><pre>
$ scp PayloadNodeI0.tgz root@<PayloadNode0 IPAddress>:/root/
</pre></code>
Enter password.

<code><pre>
# ssh root@<PayloadNode0 IPAddress>
</pre></code>
Enter password

<code><pre>
# cd /root
# mkdir asp
# cd asp
# tar xzvf ../PayloadNodeI0.tgz
</pre></code>

This unzips and extracts the contents of <code>PayloadNodeI0.tgz</code> within <code>/root/asp</code>
The PayloadNode0 is now installed on its target.
For PayloadNode1 repeat the above 2 steps, replacing the IP address with PayloadNode1's and securely copying <code>PayloadNode1.tgz</code>.
</ol>

===Summary and Next Steps===

This chapter covers a number of possible hardware configurations and the steps required to build and install the target images. Chapter [[Doc:Evalguide/csa#Sample Applications|Sample Applications]], covers all the Evaluation applications that can be run. For each Sample Application, a description on its objective, what you will learn, key areas of code, how to run it, sample output and conclusion is provided.

Doc:latest/evalguide/setup

2010-08-27T03:12:43Z

Senthilk:

==Runtime Hardware Setup==

As SAFplus Platform will run on an environment which consists of chassis, blades, switch fabrics and shelf managers, we have created Runtime Hardware Setup 1.1, 1.2 and 1.3. If this equipment is not available we suggest using a similar environment where PCs/laptops can be used to replace the chassis and blades, see Runtime Hardware setup 2.1, 2.2 and 2.3.

'''Management Station Machine'''

The Management Machine allows users to launch the Evaluation System on the target environment, enabling them to remotely control SAFplus Platform (via ssh), start and stop sample applications and monitor output.

'''System Controller'''

One or more System Controllers are required within our target environment. For further information on the role of a System Controller see the Clovis SAFplus Platform User Guide.

'''Payload Node'''

Two Payload Nodes are required for our Evaluation System to demonstrate multi node SAFplus Platform functionality. This is required for Runtime Setup 1.2, 1.3, 2.2 and 2.3.

===Runtime Hardware Setup 1.1===

This is the simple chassis, blade setup. Where one blade/node is present and acts as the System controller. Within the Runtime Hardware Setup 1.1, the following equipment is used.
*1 ATCA Chassis
*1 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module (CMM)
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.1'''
|- style="background-color:lightgray;"
|
|System Controller
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.0.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|
|}

[[File:OpenClovis_Note.png]] The IP addresses here are examples. The end user is able to use his/her IP address. The necessary changes have to be made to <code>target.conf</code>. (See Section [[Doc:Evalguide/build#Configuration File - target.conf| Configuration File - target.conf]])

The following diagram shows how the above equipment has been interconnected.

[[File:eval_HwSetup1-1.png|500px|frame|center|'''Runtime Hardware Setup 1.1''']]

===Runtime Hardware Setup 1.2===

This is the chassis and blade setup, where three blades/nodes are present that act as the System Controller and two Payload Nodes. Within the Runtime Hardware Setup 1.2, the following equipment is used:
*1 ATCA Chassis
*3 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|2.6
|2.6
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|
|}

[[File:eval_HwSetup1-2.png|frame|center|'''Runtime Hardware Setup 1.2''']]

===Runtime Hardware Setup 1.3===

This four blade setup, requires two System Controllers and two Payload Nodes. The following equipment is used:
*1 ATCA Chassis
*4 x Intel MPCBL0001N04 Blades.
*1 ATCA Chassis Management Module
*1 ATCA Switch Fabric
*1 PC Management Station

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 1.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|2.6
|2.6
|2.6
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|-
|style="background-color:lightgray;"|Chassis Slot
|1
|2
|3
|4
|
|}

[[File:eval_HwSetup1-3.png|frame|center|'''Runtime Hardware Setup 1.3''']]

===Runtime Hardware Setup 2.1===

If chassis, blades and switch fabrics are not available and you wish to run the single node setup, then the target environment can be emulated by Runtime Hardware Setup 2.1. This is the simplest set up and requires only one PC/laptop to act as the Development Machine, Management Machine and System Controller.

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.1'''
|- style="background-color:lightgray;"
|
|System Controller
|-
|style="background-color:lightgray;"|OS
| Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|}

[[File:eval_HwSetup2-1.png|frame|center|'''Runtime Hardware Setup 2.1''']]

===Runtime Hardware Setup 2.2===

If chassis, blades and switch fabrics are not available, then the target environment can be emulated by Runtime Hardware Setup 2.2. Below is a list of the required hardware:

*'''4 PCs/Laptops'''

As shown in Figure [[#Runtime Hardware Setup 2.2|Runtime Hardware Setup 2.2]], these will represent:
*1 Management Station Machine
*1 System Controller node
*2 Payload Nodes (PCs/Laptops)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.2'''
|- style="background-color:lightgray;"
|
|System Controller
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|2.6
|2.6
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}


[[File:eval_HwSetup2-2.png|frame|center|'''Runtime Hardware Setup 2.2''']]

===Runtime Hardware Setup 2.3===

If four PCs are available then the target environment can be emulated by Runtime Hardware Setup 2.3. Below is a list of the required hardware:
*'''4 PCs/Laptops'''

These will represent:
*1 Management Station Machine
*2 System Controller node
*2 Payload Nodes (PCs/Laptops)
*1 switch

{| border="1" cellpadding="10" cellspacing="0" align="center"
|+align="bottom" | '''Runtime Hardware Setup 2.3'''
|- style="background-color:lightgray;"
|
|System Controller0
|System Controller1
|Payload Node0
|Payload Node1
|Management Station
|-
|style="background-color:lightgray;"|OS
|Linux
|Linux
|Linux
|Linux
|Linux
|-
|style="background-color:lightgray;"|Kernel V
|2.6
|2.6
|2.6
|2.6
|2.6
|-
|style="background-color:lightgray;"|eth0
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|192.168.30.X
|}

[[File:eval_HwSetup2-3.png|frame|center|'''Runtime Hardware Setup 2.3''']]

===Summary and Next Steps===

This chapter has laid out the various hardware setups available to run our sample applications. Once you have chosen the set up that you wish to try and have all the hardware in place, correctly interlinked, the next step is to install the run time targets. This is discussed within the following chapter.

Doc:latest/evalguide/prerequisites

2010-08-27T03:11:58Z

Senthilk:

==Hardware and Software Prerequisites==

The OpenClovis SAFplus Platform SDK allows the modeller to define exactly what kind of hardware configuration a model runs on. This Evaluation Model has been set up to allow a variety of hardware configurations. You should match your hardware as best as possible with one of the configurations described below.

This chapter initially summarizes the configurations you may recreate, followed by a description of the hardware and software specifications.

The hardware set up you wish to choose depends upon two factors:
*whether you wish to use ATCA blades or PCs/laptops
*number of PCs/laptops/blades you have available

The following table helps you decide which setup you can recreate. For example, if you wish to use an ATCA chassis and have 3 blades available, then you may wish to create Hardware Setup 1.2.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Hardware Setups'''
!style="background-color:lightgray;"|
!style="background-color:lightgray;" colspan="3"| Hardware Setup
|- style="background-color:lightgray;"
|
|Single Node
|3 Node - Distributed
|4 Node - Distributed
|-
|style="background-color:lightgray;"|Chassis/Blades
|Hardware Setup 1.1
|Hardware Setup 1.2
|Hardware Setup 1.3
|-
|style="background-color:lightgray;"|Pcs/Laptops
|Hardware Setup 2.1
|Hardware Setup 2.2
|Hardware Setup 2.3
|}

[[File:OpenClovis_Note.png]] The word Node here represents either a PC, laptop or blade.

===Development Environment===

The Development Machine is the primary machine where the SAFplus Platform SDK and Evaluation System is installed and built. As discussed within this document, the development machine plays an important role in moving System Controller and Payload Node images to the runtime environment.

'''Development Machine'''

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Development Machine Environment'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Development Machine
|PC or Laptop
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
| Linux Distribution (Ubuntu 7.04 preferred)
|}

[[File:OpenClovis_Note.png]] Although a distinction is made throughout this document to separate the two functions of the Development Machine and Management Station Machine, they can in fact be the same PC/Laptop.

===Runtime Environment===

A distinction is made between the Development and Runtime Environment as SAFplus Platform will most likely run within an environment made up of chassis, blades, shelf managers, switches etc. and be monitored remotely. Hence we have attempted to make this Evaluation System simulate the environment it will be used in, as represented in Runtime Hardware Setup 1.1, 1.2 and 1.3 (see Chapter [[Doc:evalguide/setup#Runtime Hardware Setup| Runtime Hardware Setup]]). An alternative setup is also provided, using PCs, as discussed in Runtime Hardware Setup 2.1, 2.2 and 2.3 (again see Chapter [[Doc:evalguide/setup#Runtime Hardware Setup| Runtime Hardware Setup]]).

====Runtime Setup 1.1, 1.2 and 1.3====

Runtime Hardware Setup 1.1, 1.2 or 1.3 requires a Chassis and 1, 3 or 4 blade(s) respectively and one PC or laptop to act as the Management Station Machine. Below is listed the equipment required.

=====Chassis=====

ATCA chassis with a Shelf Manager.

=====Management Station Machine=====

A Management Station is necessary for Runtime Hardware Setup 1.1, 1.2 and 1.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Management Station Environment'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Development Station Machine
|PC or Laptop
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
|
|}

[[File:OpenClovis_Note.png]] It is possible to use a single PC/laptop as both host for the development and management machines. Virtual machine environments can also be used with some limitations to the hardware exercises.

=====System Controller=====

Runtime Hardware Setup 1.1 and 1.2 required one System Controller.

Runtime Hardware Setup 1.3 requires two System Controllers.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''System Controller'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|System Controller
|ATCA Intel (MPCBL0001) Blade
 Hard Disk - 10 GB or more
 RAM - 512 MB or more
| Linux Distribution (Ubuntu 7.04 preferred)
|}

=====Payload (Blades) Node=====

Two Payload nodes are necessary for Runtime Hardware Setup 1.2 and 1.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Payload Nodes'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Two Payload Blades
|ATCA Intel (MPCBL0001) Blade
 Hard Disk - 10 GB or more
 RAM - 512 MB or more
| Linux Distribution (Ubuntu 7.04 preferred)
|}

=====Switch=====

10/100Mbps or Gigabit Ethernet switch.

See Chapter [[Doc:evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]] for further installation details.

====Runtime Setup 2.1, 2.2 and 2.3====

Runtime Hardware Setup 2 is a simpler hardware set up, only requiring PC(s)/laptop(s) and a switch. Runtime Hardware Setup 2.1, 2.2 or 2.3 requires 1, 3 or 4 PC(s) or laptop(s) respectively. In addition a PC or laptop is needed to act as the Management Station Machine. Below is listed the equipment required.

=====Management Station Machine=====

One Management Station is necessary for Runtime Hardware Setup 2.1, 2.2 and 2.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Development Management Machine'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Management/Development Station Machine
|PC or Laptop
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or better)
| Linux Distribution (Ubuntu 7.04 preferred)
|}

[[File:OpenClovis_Note.png]] It is possible to use a single PC as the development machine, management machine and simultaneously as the target for a single node. Distributed node exercises will require a second machine. Virtual machine environments can also be used with some limitations to the hardware exercises.

=====System Controller=====

Runtime Hardware Setup 1.1 and 1.2 required one System Controller.

Runtime Hardware Setup 1.3 requires two System Controllers.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''System Controller'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|System Controller
|PC or Laptop
 Hard disk - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or Better)
| Linux Distribution (Ubuntu 7.04 preferred)
|}

=====Payload Node=====

Two Payload PCs /laptops are required for Runtime Hardware Setup 2.2 and 2.3.

{| border="1" cellpadding="10" cellspacing="0"
|+align="bottom" | '''Payload Nodes'''
|- style="background-color:lightgray;"
|
|Hardware
|Software
|-
|style="background-color:lightgray;"|Two Payload Nodes
|PC or Laptop
 HD - 10 GB or more
 RAM - 512 MB or more
 Processor - Intel Pentium II (or Better)
| Linux Distribution (Ubuntu 7.04 preferred)
|}

=====Switch=====

10/100 Mbps or Gigabit ethernet switch.

See Chapter [[Doc:evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]] for further runtime installation details.

===Summary===

This chapter provided a list of the equipment required for the development and runtime environment. See Chapter [[Doc:evalguide/setup#Runtime Hardware Setup|Runtime Hardware Setup]], for further information concerning setting up the hardware environment. This is followed by Chapter [[Doc:evalguide/build#Building the Evaluation System and Deploying Runtime Images| Building the Evaluation System and Deploying Runtime Images]], which provides information concerning the installation of target images onto the runtime environment.

Doc:latest/evalguide/scope

2010-08-27T03:11:11Z

Senthilk:

==Objectives and Scope==

===Objectives===

The Clovis Evaluation System's objective is to provide an evaluation software package that can be used to learn more about OpenClovis SAFplus Platform SDK. By the end of the evaluation the user will gain a better understanding of:
*The scope of the product. The sample applications are not a comprehensive tour of all OpenClovis SAFplus Platform features but do cover the ones most commonly used.
*The usage patterns associated with the product
*The product's quality and usability

===Scope===

To help users gain a better understanding of our product this Evaluation System User Guide introduces the SAFplus Platform runtime sample applications. To cover these areas of interest this document encompasses the following:

*'''Chapter 2''': Covers the necessary HW & SW required
*'''Chapter 3''': Presents the Hardware Setups possible with PC(s)/Laptop(s) or ATCA equipment.
*'''Chapter 4''': Covers the steps to configure the software for the runtime environments on which to run the sample applications and provides steps to install the target images from the Development Machine.
*'''Chapter 5''': Provides instructions on running the SAFplus Platform and the sample applications. For each sample application a description is provided that explains its purpose, highlights key blocks of code, shows how to run it on the cluster, and describes what to observe.


[[File:eval_Contents_new.png|frame|center| '''Content of OpenClovis Evaluation System User Guide''' ]]

 

== Headline text ==

Doc:latest/evalguide/preface

2010-08-27T03:10:21Z

Senthilk:

=='''Preface'''==

 To help users gain a better understanding of our product the ''OpenClovis Evaluation System User Guide'' introduces sample applications that utilise the OpenClovis Application Services Platform (SAFplus Platform). It provides all the required information to configure and run the sample applications (or "models") packaged within the Evaluation System. This document also provides a good understanding of OpenClovis SAFplus Platform functionality.

This document does not cover the creation of the models through the OpenClovis IDE. For a detailed description of how to create the first example model in the OpenClovis IDE see the '''OpenClovis Sample Application Tutorial''' document.

===Audience===

 The ''OpenClovis Evaluation System User Guide'' is intended for individuals who wish to gain an understanding of the OpenClovis SAFplus Platform. If you wish to run this Evaluation System this document assumes you have installed the OpenClovis SAFplus Platform by following the installation steps found within the ''OpenClovis Installation Guide''.

===Documentation Conventions===

 This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.

{| border="1" cellpadding="5"
|- style="background:#cdd6e6"
!style="background:#d3e3ff"| Notation
!style="background:#d3e3ff"| Description

|-
|style="background:#ffccaa" | <code><pre>Code</pre></code>
|This font denotes the C code provided in various examples. This font denotes function and variable names

|-
|style="background:#ffffaa" | <code><pre>Output</pre></code>
|Terminal Output

|-
|style="color:blue" | Cross reference
|This font denotes a hyperlink. You can click on the hyperlink text to access the reference location, which can be either a section within the guide or a URL link. A cross reference refers to a section name and accesses the first page of that section.

|-
| <code>Filenames</code>, <code><DIR></code>
| Files names, Directory paths

|-
|<code>$ Commands ''group_identifier''</code>
| Commands to be run from a shell. Italic text indicate an argument. This can be replaced with your desired value.
|}

====Definitions====
 Throughout this document the term "node" is used generically to refer to either a PC, laptop or ATCA blade. Several nodes all running the OpenClovis SAFplus Platform combine to form one tightly coupled distributed computing environment called a "cluster". The number and configuration of these nodes and the applications that are running on them together form the "system model", or just "model". In summary the term "SAFplus Platform" denotes the common OpenClovis programs and libraries running on all nodes in the cluster, while the term "model" denotes all of the user applications.

 [[File:OpenClovis_Note.png]]This indicates the presence of notes or annotations, related to the context of the document.
 [[File:OpenClovis_Caution.png]]This indicates that certain precautionary measures must be taken before performing a particular task.
 [[File:OpenClovis_Info.png]]This indicates that additional information is provided to you.

===Related Documents===

 For additional information about OpenClovis products, refer to the following guides:

* '''OpenClovis Release Notes''' provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It contains the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.

* '''OpenClovis SA Forum Compliance''' describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.

* '''OpenClovis Installation Guide''' provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.

* '''OpenClovis Sample Application Tutorial''' provides the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the OpenClovis offering.

* '''OpenClovis SDK User Guide''' provides information about OpenClovis Application Service Platform (SAFplus Platform) architecture, various OpenClovis SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the OpenClovis SAFplus Platform code to build your custom application.

* '''OpenClovis IDE User Guide''' describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform platform. This guide helps you to understand how to use the various features of the IDE to build the application.

* '''OpenClovis Log Tool User Guide''' provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the <code>.log</code> files and filter them to view the required entries.

* '''OpenClovis API Reference Guide''' is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.

* '''OpenClovis SAFplus Platform Console Reference Guide''' provides details about managing applications built on OpenClovis SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

* '''Clovis Sample Application (csa) source code''' For all sample applications provided with this Evaluation System, their source code has been provided within: <code><install_dir>/sdk-3.0/src/examples/eval/src/app/</code>

* '''Service Availability Forum (SAF)''' - http://www.saforum.org/home/ Further SA Forum information can be found by clicking '''Specifications''' -> '''Download Specifications'''. Here you will be presented with a number of documents. Further information concerning Components, Service Instances, Service Groups, Component Service Instances can be found within the document '<code>SA Forum Specification Overview Document</code>'.

When the SDK is installed, these documents can be found within

<code><install_dir>/sdk-3.0/doc</code>

As mentioned previously in the ''OpenClovis Installation Guide''. The default directory for installation is <code>/opt/clovis</code> for root installation and <code>$HOME/clovis</code> for non root users. Throughout this document we will use <code><install_dir></code> to refer to the installation directory.

===References to Linux Distributions===

 Throughout this document we refer constantly to the Linux Distribution (distro) or similar. Our SDK works on Ubuntu 7.04, and is known to work on a wide range of Linux 2.6 distributions. We are committed to supporting any Linux distribution that our customers require.

===OpenClovis Online Technical Support===

 OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum.

===Documentation Feedback===

 We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Post your feedback on documentation at: http://www.openclovis.org/forum.