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.

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

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

caution
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

c

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")
caution
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

c

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.

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