Deploy RDM Embedded Database on VxWorks

Raima Releases RDM v14.1 embedded database with support for VxWorks.

Raima provides an enterprise caliber database with a small footprint, perfectly designed for the Wind River® VxWorks® real-time operating system and Wind River Linux. In this release, clients will find a new set of features which will enable IoT and IIoT applications that need performance within self-maintained applications.

These instructions are for RDM targeting VxWorks 7 and later using VxWorks kernel modules or VxWorks RTP. In the following we will explains these topics:

• A Quick Overview of VxWorks
• Task Priorities for RDM on Real Time OSs
• How to Do a VxWorks Source Build
• How to Compile a VxWorks Kernel for RDM
• How to Compile a VxWorks Bootloader
• How to Develop an Application for VxWorks Using RDM
• Native Build for the Host Development Platform

A Quick Overview of VxWorks

#

VxWorks Kernel Modules

VxWorks kernel modules do not use ordinary executables as most other operating systems do. Instead, they use relocatable objects which can be compiled into the kernel or loaded during run time on a running target. The VxWorks loader is just a runtime link loader which is capable of both loading and unloading these objects on a running VxWorks kernel. For this to work, these relocatable files must fulfill some important requirements:

• The C library must not be linked in
• Startup code must not be linked in
• Unresolved symbols in these relocatable files must either be entry points into VxWorks, entry points into libraries already loaded or entry points that are not used during execution.
• No PIC (position independent code) should be used.

Applications can be prepared for execution on the target in principally two ways:

• Compile the application without linking against any library. On the target, we load RDM libraries and then the application.
• Compile the application by linking against RDM libraries. On the target, we load our linked application.

With the first approach, it is possible to load more than one application that uses the same library. The second approach does not have that capability, but it is more convenient by only having to load one module.

VxWorks RTP

VxWorks Real Time Processes (RTPs) are running executables. With a Memory Management Unit (MMU) each of these processes run in their own address space protected from other processes and the kernel. The executables can be absolutely linked or relocatable.

Hardware without a MMU or where the MMU have been disable will run each RTP with its own region of virtual memory. In this mode, there is no protection between the RTPs and the kernel, but since no MMU need to be updated context switching is faster.

In any case, each process can contain several tasks similar to the kernel. It is the tasks within the RTPs that are scheduled and not the RTPs themselves. The RTPs communicate with the kernel through operating system calls.

Task Priorities for RDM on Real Time OSs

#

RDM is implemented using one or more tasks under VxWorks. How many tasks are required depends on how RDM is used.

The tfs_embed configuration has one server task (assuming “threaded” is specified) and one vacuum task. The server task will initialize the TFS, spawn a connection task for each client, and perform some cleanup upon termination.

Each of these tasks can run at the same or different priority levels. A higher priority task (lower numerical value under VxWorks) is guaranteed to run before a lower priority task (higher numerical value under VxWorks) if the higher priority task is ready to run. Assigning priorities is crucial for proper operation of the system. Incorrectly assigned priorities can lead to starvation, resource exhaustion, or unresponsive systems. There is also often a trade-off between these objectives which make the priority assignment even more difficult.

For a system consisting of one producer and one consumer where we optimize for responsiveness of the producer, the producer is assigned a higher priority than the consumer. This may, under certain conditions, exhaust resources and starve the consumer. The consumer is assigned a higher priority than the producer if we instead want to minimize the amount of resources used and protect against starvation. This will, however, make the producer less responsive. There is therefore, often a trade-off among responsiveness of a system, resource allocation, and starvation. Exactly how this plays out depends on the application, and how priorities should be assigned depends on your requirements.

In general, the priorities of RDM tasks are set by giving priority to the consumer. This minimizes the amount of resource used but may result in less responsive systems. These priorities are defined in include/pspvxworks.h. You may change these priorities based on your requirements. If you are new to real-time system programming and wish to familiarize yourself with this or rate-monotonic scheduling, you may want to consider reading the article “What Every Engineer Needs To Know About Rate-Monotonic Scheduling: A Tutorial” by Janusz Zalewski.

How to Do a VxWorks Source Build

#

The first step before compiling a VxWorks Kernel or compiling RDM for VxWorks is to set up a VxWorks Source Build (VSB). Set up the VxWorks environment as follows, where {WindRiver} is the location of the VxWorks 7 host installation:

$ {WindRiver}/wrenv.sh -p vxworks-7

Or,

c:> {WindRiver}/wrenv.exe -p vxworks-7

You can use Workbench to set up a VxWorks Source Build. However in the following we will use the command line.

After you have installed RDM, locate the appropriate target directory for your platform. In the following we assume you are using vxworks7-x86_32_core.

$ cd {targetdir}/target/vxworks7-x86_32_core

where {targetdir} is the location where RDM have been installed. In this directory you find a number of files. Consult setup.sh and make sure that the following two environment variables have been set as documented in this script:

LM_LICENSE_FILE
WIND_HOME

wrenv.sh that you ran first will set the second environment variable. The script uses a number of other environment variables. Some of them are relevant for the VxWorks Source Build while other variables are needed for later steps. Please consult this script for further details.

When you are satisfied with the content of setup.sh run the script as follows:

$ sh ./setup.sh --vsb

VSB for other targets

A VSB for other targets can also be set up. This is only applicable with a RDM source package.

In the source for RDM, create a target directory under target similar to target/vxworks7-x86_32_core for VxWorks downloadable kernel modules (DKM) or a target directory like target/vxworks7-rtp-x86_32_core for VxWorks real time processes (RTP). Edit the files to matches the target directory and the desired target platform. Edit the setup.sh according to the instructions in that file.

When you are satisfied with the content of setup.sh run the scrip as follows:

$ sh ./setup.sh --vsb

And then:

$ sh ./setup.sh --template

to generate the template needed for building RDM in later steps.

How to Compile a VxWorks Kernel for RDM

#

The next step is to build a VxWorks Kernel or A VxWorks Image Project (VIP) targeting VxWorks 7. The description here is for RDM using VxWorks kernel modules or VxWorks RTP.

Make sure you have followed the instruction above for setting up and building a VxWorks Source Build (VSB) unless you are using one of the VxWorks prebuilt targets.

Set up the VxWorks environment as follows, where {targetdir} is the location of the VxWorks 7 install:

$ {targetdir}/wrenv.sh -p vxworks-7     c:> {targetdir}/wrenv.bat -p vxworks-7

You can use Workbench to set up a VxWorks Image Project. However in the following we will use the command line similar to previous section.

Assuming you also have set LM_LICENSE_FILE, run the commands below. Here we assume you are using the vxworks7-x86_32_core target:

$ cd {targetdir}/target/vxworks7-x86_32_core
$ sh ./setup.sh --vip

where {targetdir} is the location of the RDM install. You can do this build in any directory as long as you specify the path to the setup script.

The script above sets up a RAM file system under /ram0. You may want to use some other persistent storage. The details for this will depend on your hardware and is beyond the scope of this document.

You may also want to include other components depending on how you do your development, debugging, QA, or deployment. This is beyond the scope of this document.

How to Compile a VxWorks Bootloader

#

This is a VIP similar to a VxWorks kernel except that it is set up to boot another VxWorks Kernel. Follow the instructions above but instead run the setup.sh script as follows:

$ sh ./setup.sh --bootapp

If you are using this on a host where you for example have Linux installed using Grub2 to boot you can install the above boot loader as follows.

Start by copying the above bootloader to a file system available to Grub2:

$ sudo cp bootapp_.../default/vxWorks /boot/BootApp

Add the following file to Grub2’s configuration:

$ cat >07_BootApp <<-EOF
exec tail -n +3 $0
# This file provides an easy way to add custom menu entries.  Simply type the
# menu entries you want to add after this comment.  Be careful not to change
# the 'exec tail' line above.

menuentry "VxWorks BootApp" {
multiboot /boot/BootApp sysbootline:fei(0,0)my_host:/home/my_user/workspace/vip_x86_32_core/default/vxWorks h=192.168.1.244 e=192.168.1.174 g=192.168.1.1 u=my_user pw=my_password f=0x8 tn=my_target
}
EOF

Edit the file where:

• fei(0,0) is the ethernet device
• my_host is the development host name
• The h parameter is the IP address of the host where you have a ftp server running (192.168.1.244)
• The e parameter is the IP address of the target board (192.168.1.174)
• The g parameter is the gateway (192.168.1.1)
• The u parameter is the ftp user (my_user)
• The pw parameter is the ftp password (my_password)
• The f parameter is the boot flags (0x8)
• The tn parameter is the target name (my_target)

Copy the configuration file, update grub, and halt the system:

$ sudo mv /etc/grub.d/07_BootApp
$ sudo update-grub
$ shutdown -h now

Power the target and it should now boot into VxWorks.

How to Develop an Application for VxWorks Using RDM

#

RDM examples written in C use the RDM_STARTUP_EXAMPLE macro. The argument to this macro must match the name of a named main function as shown below. The tims example uses this macro as follows:

int32_t EXTERNAL_FCN tims_main(
    int32_t argc,
    const char *const *argv)
{
    ...
}
RDM_STARTUP_EXAMPLE(tims)

You also have the option of compiling in a hook for the RDM_STARTUP_EXAMPLE. Compile in a hook like this:

-DPSP_STARTUP_HOOK=chdir("/ram0");

This will change the current working directory. This is most convenient when we launch this from WorkBench using a debug connection. WorkBench does not give you the option of specifying a current working directory for downloadable kernel modules. It must always be set programmatically.

Using VxWorks Kernel Modules

The RDM_STARTUP_EXAMPLE macro as used above expands to a function with the following signature (this signature matches the requirements for sp and taskSpawn):

int32_t tims(
    int32_t a1,
    int32_t a2,
    int32_t a3,
    int32_t a4,
    int32_t a5,
    int32_t a6,
    int32_t a7,
    int32_t a8,
    int32_t a9,
    int32_t a10);

Use this function as the entry point to the tims example. The tims example does not take any argument. You should therefore pass in 0 as the first and only argument to this function.

tims 0

This function takes care of initializing the RDM platform support layer (psp_init ()), builds up the argument list for the named main function, calls the named main function, and terminates the platform support layer (psp_term ()).

Examples and tools that do take arguments should have the arguments passed in as strings - one string for each parameter. You always need to pass in 0 after the last argument unless all ten arguments are specified.

Using VxWorks RTP The RDM_STARTUP_EXAMPLE macro as used above expands to a normal main function under VxWorks RTP. This is just like many other host operating systems.

Native Build for the Host Development Platform

#

Compiling RDM for VxWorks kernel modules consist of a native build for your host development platform and a cross compiled build for your VxWorks target.

Native Build for the Host Development Platform

Before you can compile RDM for VxWorks kernel modules or VxWorks RTP, you need a native build for your host development platform.

Native build for Linux

Please follow the steps outlined in Using “configure” and Using “make”. Pay special attention to that you need to provide the command line option –enable-vxworks7-project-files or –enable-vxworks7-rtp-project-files when running configure for the VxWorks project files to be configured.

Setting up project files for Wind River Workbench

Assuming you have done a native build for your host development platform using the configure script and make on UNIX or the Visual Studio project files on Windows, you are now ready to set up the project files for Wind River Workbench.

On GNU/Linux the following is relative to the top build directory. On Windows it is relative to the top source or install directory:

$ cd target/vxworks7-...
$ {wind_host}/workbench-4/wrtool -data . wrtool.txt
$ cd ../..

Cross Compiled Build for VxWorks Assuming you have set up the project files as explained above.

• Start WorkBench
• Select the target/vxworks7-… as the work space.

You should now have one project file for each example and tutorial that you can build and run on your target.