10. VxWorks 5.5.1 — OpenSplice Getting Started Guide

### Navigation

- index
- next |
- previous |
- OpenSplice Getting Started Guide »

# 10. VxWorks 5.5.1

This chapter provides a brief description of how to deploy Vortex OpenSplice on VxWorks 5.5.1.

## 10.1. VxWorks and Tornado

This chapter provides a brief description of how to build the kernel and the supplied examples, and how to run those examples, using VxWorks 5.5.1 and the Tornado ‘front end’. For more information about VxWorks 5.5.1 and Tornado, please refer to WindRiver’s documentation.

  NOTE: The examples given here assume that a Solaris-hosted system is being used, and that Vortex OpenSplice is installed in `/usr/local/vxworks5.5.1`.

## 10.2. Building a VxWorks Kernel

Required modules

The following modules are the core system components needed to build the Vortex OpenSplice runtime. Please refer to WindRiver’s documentation for additional information describing how VxWorks kernels can be built.

- Operating system components
  - POSIX components
    - POSIX timers
    - POSIX threads
  - File System and Disk Utilities
    - File System and Disk Utilities

Additional modules

The modules listed below are optional but are useful for HDE (Host Development Environment) development. These modules are required if deploying from the Tornado front end:

- Development tool components
  - WDB agent components
    - WDB agent services
  - WDB target server file system
    - symbol table components
- Platform-specific Information
  - synchronize host and target symbol tables
  - target shell components
    - target shell

## 10.3. Scenarios for Building the OpenSplice Examples

There are two scenarios included for building and deploying the OpenSplice examples.

- You can build one DKM (Downloadable Kernel Module) containing the example, OpenSplice, and all of its required services and support libraries, as well as a default configuration file. (This is the recommended approach.)
- Alternatively, separate DKMs are supplied for each of the OpenSplice libraries and services, and each example can be built as a separate DKM (containing only the example), which we refer to as ‘AppOnly’ style.

## 10.4. The OpenSplice Examples (All linked in one complete DKM - recommended)

To build the standalone C PingPong example

At the prompt, `cd` to examples/dcps/PingPong/c/standalone/` and run `make`.

### 10.4.1. Note about the example projects

The example builds by linking the object produced by compiling the output of `osplconf2c` along with the example application, the `splice` deamon, and services enabled in the configuration XML, into one single downloadable kernel module.

Users producing their own application could of course decide to link the object and library files into a monolithic kernel image instead.

### 10.4.2. The osplconf2c tool

`osplconf2c` is required for example and user applications.

`osplconf2c` is a tool which processes the OpenSplice configuration XML, and produces a source file to be compiled and linked into the final image. It contains the data from the XML file, as well as any environment variables that you require to configure OpenSplice and references to the symbols for the entry points of the OpenSplice services.

Environment variables can be added using the `-e` option. For example, you would use the option `-e "OSPL_LOGPATH=/xxx/yyy"` if you wanted the logs to be placed in `/xxx/yyy`.

The example `makefiles` runs `osplconf2c` automatically.

## 10.5. Overriding OpenSplice configuration at runtime

You can override the OpenSplice configuration XML provided to `osplconf2c` at runtime by specifying the URI of a file when starting `ospl_spliced` on the target. For example:

    ospl_spliced "file:///tgtsvr/ospl.xml"

It should be noted, however, that the `osplconf2c` will have generated references to the symbols for the services which are specified in the xml file when it started, and only those services may be used in the new configuration, as other services will not be included in the image. As an exception to this, if the `-d` option is specified then dynamic loading is supported, and DKMs for additional services will be automatically loaded; DKMs for any required ‘libraries’ must be pre-loaded by the user.

  NOTE: Symbol table support will be required in the kernel if the `-d` option is used. Without the `-d` option it should still be possible to statically link OpenSplice with a kernel even if symbol table support is not included, for example for final deployment.

## 10.6. Running the Examples

If you included the additional modules listed above (see Building a VxWorks Kernel) in the kernel, deployment is done via the target server setup from the Tornado shell connection.

## 10.7. Background

All Vortex OpenSplice tools or services have unique entry points. These entry points all take a string; the string is parsed into the necessary arguments and passed on.

To start `ospl` on a Unix system, the command would be:

    ospl start file:///ospl.xml

and on VxWorks:

    ospl "start file:///ospl.xml"

Note that the arguments are separated by spaces.

Other commands:

    ospl -> ospl(char *)
    spliced -> ospl_spliced(char *)
    networking -> ospl_networking(char *)
    durability -> ospl_durability(char *)
    cmsoap -> ospl_cmsoap(char *)
    mmstat -> ospl_mmstat(char *)
    shmdump -> ospl_shmdump(char *)

The standard ‘main’ equivalent entry points are:

    ospl -> ospl_unique_main(int argc, char ** argv)
    spliced -> ospl_spliced_unique_main(int argc, char ** argv)
    networking -> ospl_networking_unique_main(int argc, char ** argv)
    durability -> ospl_durability_unique_main(int argc, char ** argv)
    cmsoap -> ospl_cmsoap_unique_main(int argc, char ** argv)
    mmstat -> ospl_mmstat_unique_main(int argc, char ** argv)
    shmdump -> ospl_shmdump_unique_main(int argc, char ** argv)

You can use the standard `argv argc` version entry when you need to use arguments with embedded spaces. For example, for `ospl` you would use:

    osplArgs = malloc(12)
    *osplArgs = "ospl"
    *(osplArgs+4) = "start"
    *(osplArgs+8) = "file:///tgtsvr/etc/config/ospl.xml"
    ospl_unique_main (2, osplArgs)

## 10.8. How to start spliced and related services

For the example below the target server filesystem must be mounted as `/tgtsvr` on the target.

To start the `spliced` service and other additional OpenSplice services open a windsh and enter the following commands.

    cd "$OSPL_HOME/examples/dcps/PingPong/c/standalone"
    ld 1,0,"sac_pingpong_kernel.out"
    ospl_spliced

Note that `spliced` will block when invoked by `ospl_spliced` so open a new windsh to run the following Pong command:

    pong ("PongRead PongWrite")

After the Pong application has started you can open another windsh and start Ping. However, if you are running the Ping application on another target board you must load and start `spliced` on that target also, as described above.

    ping("100 100 m PongRead PongWrite")
    ping("100 100 q PongRead PongWrite")
    ping("100 100 s PongRead PongWrite")
    ping("100 100 b PongRead PongWrite")
    ping("100 100 f PongRead PongWrite")
    ping("1 10 t PongRead PongWrite")

The `ospl-info.log` file can be inspected to check the deployment has been successful. By default, this is written to the `/tgtsvr` directory.

The `moduleShow` command can be used within the VxWorks shell to see that the service modules have loaded, and the `i` command should show that tasks have started for these services.

## 10.9. The osplconf2c command

Usage

    osplconf2c -h

    osplconf2c [-d [-x]] [-u <URI>] [-e <env=var> ]... [-o <file>]

Options

`-h, -?`
  List available command line arguments and give brief reminders of their functions.
`-u <URI>`
  Specifies the configuration file to use (default: `${OSPL_URI}`).
`-o <file>`
  Name of the generated file.
`-e <env=var>`
  Environment setting for configuration of OpenSplice; e.g. `-e "OSPL_LOGPATH=/xxx/yyy"`.
`-d`
  Enable dynamic loading.
`-x`
  Exclude xml.

## 10.10. The OpenSplice Examples (Alternative scenario, with multiple DKMs)

  Loading separate DKMs is not recommended by ADLINK.

Note about the example projects

Please ensure that any services called by a configuration XML contain an explicit path reference within the command tag; for example:

> `<Command>/tgtsvr/networking</Command>`

### 10.10.1. To build the standalone C pingpong example

At the prompt, `cd` to `examples/dcps/PingPong/c/standalone/` and run

    make -f Makefile\_AppOnly

### 10.10.2. How to start spliced and related services

To start the `spliced` service and other additional OpenSplice services, load the core OpenSplice shared library that is needed by all Vortex OpenSplice applications, and then the `ospl` utility symbols. This can be done using a VxWorks shell on as many boards as needed. The `ospl` entry point can then be invoked to start OpenSplice.

    cd "$OSPL_HOME"
    ld 1,0,"lib/libddscore.so"
    ld 1,0,"bin/ospl"
    os_putenv("OSPL_URI=file:///tgtsvr/etc/config/ospl.xml")
    ospl("start")

  Please note that in order to deploy the cmsoap service for use with the Vortex OpenSplice Tuner, it must be configured in `ospl.xml` and the libraries named `libcmxml.so` and `libddsrrstorage.so` must be pre-loaded:

    ld 1,0,"lib/libddscore.so"
    ld 1,0,"lib/libddsrrstorage.so"
    ld 1,0,"lib/libcmxml.so"
    ld 1,0,"bin/ospl"
    os_putenv("OSPL_URI=file:///tgtsvr/etc/config/ospl.xml")
    os_putenv("PATH=/tgtsvr/bin")
    ospl("start")

#### 10.10.2.1. To run the C PingPong example from winsh

After the `spliced` and related services have started, you can start Pong:

    cd "$OSPL_HOME"
    ld 1,0,"lib/libdcpsgapi.so"
    ld 1,0,"lib/libdcpssac.so"
    cd "examples/dcps/PingPong/c/standalone"
    ld 1,0,"sac_pingpong_kernel_app_only.out"
    pong("PongRead PongWrite")

After the Pong application has started you can open another windsh and start Ping. However, if you are running the Ping application on another target board you must load and start `spliced` on that target also, as described above.

    ping("100 100 m PongRead PongWrite")
    ping("100 100 q PongRead PongWrite")
    ping("100 100 s PongRead PongWrite")
    ping("100 100 b PongRead PongWrite")
    ping("100 100 f PongRead PongWrite")
    ping("1 10 t PongRead PongWrite")

The `ospl-info.log` file can be inspected to check the deployment has been successful. By default, this is written to the `/tgtsvr` directory.

The `moduleShow` command can be used within the VxWorks shell to see that the service modules have loaded, and the `i` command should show that tasks have started for these services.

### 10.10.3. Load-time Optimisation: pre-loading OpenSplice Service Symbols

Loading `spliced` and its services may take some time if done exactly as described above. This is because the service Downloadable Kernel Modules (DKM) and entry points are dynamically loaded as required by OpenSplice.

  It has been noted that the deployment may be slower when the symbols are dynamically loaded from the Target Server File System. However, it is possible to improve deployment times by optionally pre-loading service symbols that are known to be deployed by OpenSplice.

In this case OpenSplice will attempt to locate the entry point symbols for the services and invoke those that are already available. This removes the need for the dynamic loading of such symbols and can equate to a quicker deployment. When the entry point symbols are not yet available ( i.e. services have not been pre-loaded), OpenSplice will dynamically load the services as usual.

For example, for an OpenSplice system that will deploy `spliced` with the networking and durability services, the following commands could be used:

    cd "$OSPL_HOME"
    ld 1,0,"lib/libddscore.so"
    ld 1,0,"bin/ospl"
    ld 1,0,"bin/spliced"
    ld 1,0,"bin/networking"
    ld 1,0,"bin/durability"
    os_putenv("OSPL_URI=file:///tgtsvr/etc/config/ospl.xml")
    os_putenv("PATH=/tgtsvr/bin")
    ospl("start")

The `ospl-info.log` file describes whether entry point symbols are resolved having been pre-loaded, or the usual dynamic symbol loading is required.

### 10.10.4. Notes

In this scenario `osplcon2c` has been used with the `-x` and `-d` options to create an empty configuraion which allows dynamic loading, and the resulting object has been included in the provided `libddsos.so`.

If desired the end user could create a new `libddsos.so` based on `libddsos.a` and a generated file from `osplconf2c` without the `-x` option, in order to statically link some services but also allow dynamic loading of others if the built-in xml is later overridden with a file URI. (See Overriding OpenSplice configuration at runtime.)

### Navigation

- index
- next |
- previous |
- OpenSplice Getting Started Guide »