Products Support Documentation Download
Wind River VxWorks 6.x using Project Files

Introduction

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

  • A Quick Overview of VxWorks
  • Task Priorities
  • How to Compile a VxWorks Kernel for RDM
  • How to compile RDM for VxWorks
  • How to Develop an Application for VxWorks Using RDM

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.

The GNU Toolkit can be used to compile objects that meet the above requirements. To prevent linking against the C library, we use the option "-nostdlib". To prevent ld from trying to produce an executable and instead produce a relocatable file, option "-r" is 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

Please consult README-task-priorities.

How to compile a VxWorks Kernel for RDM

This section describes how to build a VxWorks image using WorkBench targeting VxWorks 6.9. The description her is for RDM using VxWorks kernel modules or VxWorks RTP.

Start WorkBench as follows:

$ .../wrenv.sh -p vxworks-6.9     c:> .../wrenv.bat -p vxworks-6.9
$ .../startWorkbench.sh           c:> .../startWorkbench.bat

You need WorkBench to create a VxWorks image. Select "File" -> "New" -> "VxWorks Image Project". Select "Wind River VxWorks 6.9" as the target operating system. While clicking "Next>" an number of times do the following selections as they come up. Select "System Image" as the build type. Enter a project name. Select a board support package that matches your hardware and select "gnu" as the tool chain. Select "PROFILE_DEVELOPMENT". Click "Finish".

Open the Application Development perspective. In the Project Explorer, click the triangle to the left of the project name, double click "Kernel Configuration," and make sure to include the following components below. Right click on "File System and Disk Utilities" and "POSIX ftruncate," one at a time, and select "Include". Below we have included the HRFS file systems. The DOS file system is included by the profile selected above.

"operating system components"
 -> "IO system components"
     -> "Highly Reliable File System Components" -> Include
 -> "POSIX components"
     -> "POSIX ftruncate" -> Include
 -> "kernel components"
     -> "kernel scheduler selection"
         -> "POSIX thread scheduler in RTPs"

You may also want to increase the maximum number of open files. We have increased this to 255 in RDM. Select "Default Max Open Files (DosFs)" and "max # open files in the system," one at a time. Click in the last column to change the value. This is how these components are laid out for a VxWorks 6.9 project:

"operating system components"
 -> "IO system components"
     -> "IO Subsystem Components"
         -> "Basic IO System"
             -> "max # open files in the system" -> 255
     -> "dosFs File System Components"
         -> "dosfs File System Main Module (dosFs2)
             -> "Default Max Open Files (DodFs) -> 255
     -> "Highly Reliable File System Components"
         -> "Highly Reliable File System"
             -> "Default Max Open Files"   255
 -> "Real Time Process Components"
     -> "RTP"
         -> "Number of entries in an RTP fd table"  255

If you are using the C++ API include C++ compiler support:

"C++ Components"
 -> "C++ compiler support routines"

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.

In the Project Explorer, double click "usrAppInit.c" to edit the file. Include the following code for creating an dosFS or HRFS RAM file system:

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <hrFsLib.h> 
#include <dosFsLib.h>
#include <xbdPartition.h>
#include <xbdRamDisk.h>

#define BLOCKSIZE 512

typedef enum {
   NO_FS = 0,
   RAM_DOS_FS,
   RAM_HR_FS
} MY_FS;

struct {
    MY_FS fs;
    char *devname;
    unsigned int disksize;
} disk[]= {
    {RAM_HR_FS, "/ram", 0x8000000}, /* 128 MB */
    {RAM_DOS_FS, "/ram2", 0x8000000}, /* 128 MB */
    {NO_FS, NULL, 0}
};

STATUS fsSetup (void) {
    STATUS error;
    device_t xbd;
    unsigned int i;
    for (i= 0; disk[i].fs; i++) {
        /* Create a RAM disk. */
        xbd = xbdRamDiskDevCreate (BLOCKSIZE,  disk[i].disksize, 0, disk[i].devname);
        if (xbd == NULLDEV) {
            printf("Failed to create RAM disk. errno = 0x%x\n", errno);
            return (ERROR);
        }
        /*
         * Format the RAM disk.
         */
        switch (disk[i].fs) {
        case RAM_DOS_FS:
            error = dosFsVolFormat (disk[i].devname, DOS_OPT_BLANK, 0);
            break;
        case RAM_HR_FS:
            error = hrfsFormat (disk[i].devname, 0ll, 0, 10000);
            break;
        }
        if (error != OK) {
            printf("Failed to format RAM disk. errno = 0x%x\n", errno);
            return (ERROR);
        }
        printf ("%s now ready for use.\n", disk[i].devname);
    }
    return (OK);
}

/******************************************************************************
*
* usrAppInit - initialize the users application
*/ 

void usrAppInit (void) {
#ifdef  USER_APPL_INIT
    USER_APPL_INIT;     /* for backwards compatibility */
#endif

    /* add application specific code here */
    fsSetup ();
}

A RAM file system is needed unless you use some other hardware with a file system on it. If you are using the simulator, we would strongly encourage you to use a RAM file system instead of the host file system.

Select the project in the Project Explorer and select "Project" -> "Build Project." The VxWorks image will show up as default/vxWorks under the location for the project.

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. We usually compile in a hook like this:

-DPSP_STARTUP_HOOK="chdir(\"/ram\");"

This will change the current working directory. This is most convenient when we launch this from WorkBench. WorkBench does not give you the option of specifying a current working directory. It must always be set programmatically unless you are using a target shell.

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.

How to Compile RDM for VxWorks

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 README-unix-configure.txt and README-unix-make.txt. Pay special attention to that you need to provide the command line option –enable-vxworks-project-files or –enable-vxworks-rtp-project-files when running configure for the VxWorks project files to be configured.

Native build for Windows

Please follow the steps outlined in Windows Development Host.

Cross Compiled Build for VxWorks

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 can now do a cross compiled build for VxWorks kernel modules or VxWorks RTP.

Start WorkBench:

$.../startWorkbench.sh           c:> .../startWorkbench.bat

Create a work space. We recommend that you locate the workspace at target/vxworks relative to the top source directory. If you did an out of source build on GNU/Linux or OS X, you will want to use the location relative to the top build directory. This directory will be the root directory for all the project files.

Next, import the RDM project files into your work space:

File->Import

Then select Existing Projects into Workspace:

General->"Existing Projects into Workspace"

and click Next.

Select the root directory by browsing to:

"target/vxworks" for VxWorks Kernel modules

or

"target/vxworks-rtp" for VxWorks RTP

relative to the top source directory. If you did an out of source build on GNU/Linux or OS X, you will need to specify the directory relative to the top build directory.

Click Finish:

Finish

You should now have one project file for each example, tutorial, and library. The project files for all the examples and the tutorials have build target references to the libraries, so if you do not wish to wait for everything to build, you can choose to build one example.

Running an Example on the Target

Make sure you have built a kernel, have booted your target with it, have access to the console on the target or a debug connection from your host development host, and have built at least one example as described in previous sections.

Please also note that if you are launching the example through a debug connection, you may want to compile with this define:

-DPSP_STARTUP_HOOK="chdir(\"/ram\");"

to change the current working directory to a location where you have a file system. The above assumes a RAM file system under /ram as described in the section for building a VxWorks kernel above.

VxWorks Kernel Modules

As an example, when the bomExample has been loaded on the target, it can be launched interactively as follows from the console:

-> bom
...

Enter number of levels: 3

Enter number of members per level: 3

...
  total rolled up cost =      27.00
...

->

If you want to run it without any interaction, you can launch it as follows:

bom "-m", "3", "-l", "3"

VxWorks RTP

As an example, run the bomExample as follows:

-> rtpSp "/path/to/bomExample.vxe"
...

Enter number of levels: 3

Enter number of members per level: 3

...
  total rolled up cost =      27.00
...

->

If you want to run it without any interaction, you can launch it as follows:

-> rtpSp "/path/to/bomExample.vxe  -m 3 -l 3"

Some additional Notes

A workspace with project files that also include the RDM tests requires more virtual memory for WorkBench. Please start WorkBench as follows:

/opt/vxworks-6.8/startWorkbench.sh  -vmargs -Xmx2048m

Setting up the environment in a standard shell on UNIX can be done as follows:

$ eval `wrenv.sh -p vxworks-6.9 -o print_env -f sh`