Doc:latest/evalguide/build - Revision history

Prasad: /* Summary and Next Steps */

2014-11-10T05:21:41Z

‎Summary and Next Steps

Prasad: /* Building SAFplus Platform and the Evaluation System */

2014-11-10T04:47:12Z

‎Building SAFplus Platform and the Evaluation System

Prasad: /* Building SAFplus Platform and the Evaluation System */

2014-11-10T04:18:16Z

‎Building SAFplus Platform and the Evaluation System

Prasad: /* Creating a Project Area */

2014-11-10T03:06:50Z

‎Creating a Project Area

Bot: 2 revisions

2011-10-24T19:01:41Z

2 revisions

Pradeepac: /* Building the Evaluation System and Deploying Runtime Images */

2010-08-27T11:08:57Z

‎Building the Evaluation System and Deploying Runtime Images

Senthilk at 03:14, 27 August 2010

2010-08-27T03:14:21Z

New page

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

← Older revision		Revision as of 05:21, 10 November 2014
Line 504:		Line 504:
	===Summary and Next Steps===		===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.	+	This chapter covers a number of possible hardware configurations and the steps required to build and install the target images. Chapter [[Doc:latest/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.

@@ Line 18: / Line 18: @@
 <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-5.0/src/examples'''</code>.
+<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>/6.1/sdk/src/examples'''</code>.
-<li>If you do not have write access to <code>'''<install_dir>/sdk-5.0/src/examples'''</code> create a new directory and copy the evaluation system model to it. For example:
+<li>If you do not have write access to <code>'''<install_dir>/6.1/sdk/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-5.0/src/examples/eval \
+$ cp -r <install_dir>/6.1/sdk/src/examples/eval \
    <new_project_area>/.
 </pre></code>

@@ Line 73: / Line 73: @@
 </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:
+It is possible to use <code>prebuilt libraries</code> to <code>configure</code> eval model by running the following:
 <code><pre>
 $ <install_dir>/6.1/sdk/src/SAFplus/configure \

@@ Line 69: / Line 69: @@
 <code><pre>
 $ cd <project_area>
-$ <install_dir>/sdk-5.0/src/SAFplus/configure \
+$ <install_dir>/6.1/sdk/src/SAFplus/configure \
-   --with-model-name=eval --with-asp-build
+   --with-model-name=eval --with-safplus-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-5.0/src/SAFplus/configure \
+$ <install_dir>/6.1/sdk/src/SAFplus/configure \
-   --with-model-name=eval --with-asp-build \
+   --with-model-name=eval --with-safplus-build \
    --with-cross-build=<crossbuild>
 </pre></code>
@@ Line 84: / Line 84: @@
 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-5.0/src/SAFplus/configure \
+$ <install_dir>/6.1/sdk/src/SAFplus/configure \
-   --with-model-name=eval --with-asp-build \
+   --with-model-name=eval --with-safplus-build \
    --with-cross-build=<crossbuild> --with-cm-build=openhpi
 </pre></code>
@@ Line 91: / Line 91: @@
 For a complete list of options to <code>configure</code>, including a list of available crossbuild toolchains, run:
 <code><pre>
-$ <install_dir>/sdk-5.0/src/SAFplus/configure --help
+$ <install_dir>/6.1/sdk/src/SAFplus/configure --help
 </pre></code>