12. VxWorks 6.x Kernel Mode

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

12.1. VxWorks Kernel Requirements

The VxWorks kernel required to support Vortex OpenSplice on VxWorks 6.x is built using the development kernel configuration profile with the additional posix thread components enabled. A kernel based on this requirement can be built within Workbench, by starting the Workbench GUI and choosing File > New > VxWorks Image Project.

12.2. Deploying Vortex OpenSplice

Type a name for the project then select the appropriate Board Support Package and Tool Chain (for example pcPentium4 and gnu).

Leave all of the kernel options to be used blank except for the SMP option, which must match the Vortex OpenSplice build you are working with.

caution
The SMP option must only be checked for SMP builds of OpenSplice.

On the Configuration Profile dialog choose PROFILE_DEVELOPMENT from the drop-down list.

Once the kernel configuration project has been generated, the additional required functionality can be enabled:

  • POSIX threads (INCLUDE_POSIX_PTHREADS)
  • built-in symbol table (INCLUDE_STANDALONE_SYM_TBL)
  • synchronize host and target symbol tables
  • target shell components
    • target shell

To successfully complete the C++ examples you will also require

  • C++ components > standard library (FOLDER_CPLUS_STDLIB)

Note that the Workbench GUI should be used to enable these components so that dependent components are automatically added to the project.

12.2.1. Special notes for this platform

caution
If any kernel tasks which will call onto OpenSplice API’s are to be created before ospl_spliced is started then the user must ensure that the function os_procInstallHook (which takes no parameters) is called before they are started. There only needs to be one call to os_procInstallHook; however, mutiple calls are harmless.

12.3. OpenSplice Examples

ADLINK provides the pingpong example both for C and C++ that are described in the Examples section. These example are provided in the form of Workbench projects which can be easily built and then deployed on to the target hardware in a similar process to that described above.

Each project contains a README file briefly explaining the example and the parameters required to run it.

12.3.1. Importing Example Projects into Workbench

The example projects can be imported into Workbench by choosing File > Import... > General > Existing Projects into Workspace.

In the Import Projects dialog, browse to the examples directory of the OpenSplice installation. Select the required projects for importing from the list that Workbench has detected.

Ensure that the Copy projects into workspace box is un-checked.

12.3.2. Building Example Projects with Workbench

Projects in a workspace can be built individually or as a group.

  • Build a single project by selecting it and then clicking Project > Build Project.
  • Build all projects in the current workspace by clicking Project > Build All.

12.5. Running the Examples (Alternative scenario, with multiple DKMs – ‘AppOnly’ style)

caution
Loading separate DKMs is not recommended by ADLINK.
info cpp
NOTE: There are no C++ examples provided for the AppOnly style and there is no libdcpssacpp.out DKM because VxWorks only supports C++ modules that are self-contained. However, it should still be possible to link your C++ application with the libdcpssacpp.a, and then load the complete DKM after the other OpenSplice DKMs.

12.5.1. The C pingpong example

c

Step 1

Right-click on wb_sac_pingpong_kernel_app_only for the C example or wb_sacpp_pingpong_kernel_app_only for C++, then choose Rebuild Project.

Step 2

Next configure the targets to use the target server filesystem, mapped on the target as /tgtsvr (use different host directories for each target).

Step 3

Copy the ospl.xml file from the distribution to the target server directories, and adjust for your desired configuration.

Step 4

Copy all the services from the bin directory in the distribution to the target server directories (for example, spliced.out, networking.out, etc.).

To run the examples on two targets, start the OpenSplice daemons on each target.

Step 5

Open a Host Shell (windsh) connection to each board, and in the C mode shell enter:

cd "<path to opensplice distribution>"
ld 1,0,"lib/libddscore.out"
ld 1,0,"bin/ospl.out"
os_putenv("OSPL_URI=file:///tgtsvr/ospl.xml")
os_putenv("OSPL_LOGPATH=/tgtsvr")
os_putenv("PATH=/tgtsvr/")
ospl("start")

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

cd "<path to opensplice distribution>"
ld 1,0,"lib/libddscore.out"
ld 1,0,"lib/libddsrrstorage.out"
ld 1,0,"lib/libcmxml.out"
ld 1,0,"bin/ospl.out"
os_putenv("OSPL_URI=file:///tgtsvr/ospl.xml")
os_putenv("OSPL_LOGPATH=/tgtsvr")
os_putenv("PATH=/tgtsvr/")
ospl("start")

Step 6

To load and run the examples:

c
For the C example:
ld 1,0,"lib/libdcpsgapi.out"
ld 1,0,"lib/libdcpssac.out"
cd "examples/dcps/PingPong/c/standalone"
ld 1,0,"sac_pingpong_kernel_app_only.out"

Step 7

Open a new Host Shell connection to one board and run:

pong "PongRead PongWrite"

Step 8

Open another new Host Shell on the other board and run:

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"

12.5.2. Running the examples on one target

Proceed as described in the section above, but make all windsh connections to one board, and only load and run ospl once.

12.5.2.1. 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 DKMs (Downloadable Kernel Modules) 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 pre-loading the symbols for the services that are required by OpenSplice.

On startup, OpenSplice will attempt to locate the entry point symbols for the services and invoke them. This removes the need for the dynamic loading of the DKMs providing the symbols, and can equate to a quicker deployment. Otherwise, OpenSplice will dynamically load the service DKMs.

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

cd "<path to opensplice distribution>"
ld 1,0,"lib/libddscore.out"
ld 1,0,"bin/ospl.out"
ld 1,0,"bin/spliced.out"
ld 1,0,"bin/networking.out"
ld 1,0,"bin/durability.out"
os_putenv("OSPL_URI=file:///tgtsvr/ospl.xml")
os_putenv("PATH=/tgtsvr/bin")
os_putenv("OSPL_LOGPATH=/tgtsvr")
ospl("start")

The ospl-info.log file records whether entry point symbols were pre-loaded, or a DKM has been loaded.

12.5.2.2. Notes

info

In this scenario osplconf2c has been used with the -x and -d options to create an empty configuraion which allows dynamic loading. The resulting object has been included in the supplied libddsos.out. If desired, the end user could create a new libddsos.out 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 using a file URI. (See Overriding OpenSplice configuration at runtime.)

12.5.3. 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 -e "OSPL_LOGPATH=/xxx/yyy" option if you wanted the logs to be placed in /xxx/yyy.

osplconf2c is run automatically by the example projects.

12.5.3.1. 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"

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

12.5.3.2. The osplconf2c command

Usage

osplconf2c -h

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

Options

-h, -?
List available command line arguments and give brief reminders of their functions.
-u <URI>
Identifies 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"