Developing Shared Libraries for the cRIO-901x and Other VxWorks Targets

Overview

LabVIEW Real-Time users can use their own shared libraries to interface with C/C++ code. The GNU tool chain distributed with VxWorks can compile shared libraries for controllers running Wind River VxWorks, including the CompactRIO 901x and 907x series. The shared libraries can be accessed through the Call Library Node similarly to other LabVIEW platforms.
This document describes developing VxWorks-compatible shared libraries using either a licensed copy of the VxWorks development environment, or a standalone copy of the free GNU tool chain.
This document assumes development experience with both the VxWorks and LabVIEW Real-Time environments.

1. Obtaining the GNU Toolchain

You can obtain the GNU tool chain for VxWorks either by purchasing a VxWorks development license from Wind River or by downloading the redistributable GNU tool chain attached to this document. Purchasing VxWorks enables you to use the Wind River Workbench IDE, featuring source code-level debugging and build management. The redistributable GNU tool chain downloadable here offers debugging only at the assembly code level, and you must use the included GNU Make to build binaries.

Note: NI LabVIEW Real-Time 8.5, LabVIEW Real-Time 8.6, and LabVIEW 2009 Real-Time install version 6.3 of the VxWorks OS to compatible targets. LabVIEW Real-Time 8.20 installs version 6.1 of the VxWorks OS to compatible targets. All builds should be targeted to corresponding versions and use corresponding header files. As new versions of LabVIEW Real-Time become available, different versions of VxWorks may be installed and may require you to rebuild your libraries. Refer to the readme file for LabVIEW Real-Time to find the corresponding VxWorks OS version.

2. Important Notes about Compiling

Microsoft OS Support. Microsoft Windows Vista and Windows 7 are not supported for version 6.1 or 6.3 of VxWorks.

ABI Incompatibility. Shared libraries compiled for VxWorks controllers are completely incompatible with those compiled for other controllers, and vice versa.

Alignment changes. PowerPC-based controllers, including the cRIO-901x series, use 4-byte alignment for all numbers, arrays, pointers, clusters, and handles. This can cause incompatibilities with the binary file formats of some existing Real-Time shared libraries, or with data passed to and from LabVIEW. Consult the Passing Variably-Sized Data to CINs section of Calling Code Written in Text-Based Programming Languages in the LabVIEW Help for more information.

LabVIEW can only call C functions. The Windows host cannot directly look up symbols in VxWorks-compiled shared libraries. As a result, it cannot call symbols with C++ linkage. All functions called from LabVIEW must have extern “C” linkage.

The Win32 API is not available. VxWorks does not support Windows API calls. Replace them, if possible, with ISO C or C++ calls. If you have a full license for VxWorks, the complete OS API is made available to you; consult the VxWorks documentation for additional details.

Incompatibilities between the GNU tool chain and the Microsoft Visual C++ tool chain. Code compiled using the Microsoft Visual C++ compiler may not immediately compile in GCC. Follow the guidelines for cross-platform development and consult the GNU Compiler Collection documentation.

Avoid duplicate symbol names between shared libraries. VxWorks places all global symbols in the same symbol namespace. If two libraries are loaded with the same global symbol, a warning is displayed, but the load succeeds. This may cause a silent failure if a third library is loaded that expects to reference a symbol from one module, but is linked against another library. To avoid this issue, keep as many symbols marked local (static) as possible, and prefix the remaining symbols with a unique identifier.

Strict aliasing optimizations can introduce bugs in your code. The use of strict aliasing optimizations, through the use of “-Os”, “-O2” or higher optimizations, or “-fstrict-aliasing,” is highly discouraged. Use the “-fno-strict-aliasing” compiler flag for all optimized builds.

Autodownloading is not supported. LabVIEW will not download a shared library to a VxWorks target if it is referenced by a VI and does not already exist on the target. The library must be sent via FTP to the appropriate folder on the target.

Directory restrictions. Shared libraries for use by LabVIEW VIs must exist in either the ni-rt/ or the ni-rt/system/ directory. Paths specified in the Call Library Node will be ignored.

Use –mlongcall for all compiles. This option allows function calls between modules separated by more than 32MB of memory and is required for correct shared library linkage. If you do not use –mlongcall, you may see console errors of the form “Relocation value does not fit in 24 bits.” and the library will fail to load.

DllMain() is not supported for library initialization. One workaround is to place initialization and shutdown code in static global constructors and destructors. Alternatively, consult the VxWorks Application Programmer’s Guide for information on the _WRS_CONSTRUCTOR macro, which you can use to initialize libraries.

3. Compiling with GNU Make

If you are using the redistributable GNU tool chain attached to this document, you can compile your projects using GNU Make. Use the following makefile as a template to construct the makefile for your project.

# These variables control the compiler and linker flags. Change them as

4. Compiling with Wind River Workbench

Launch Wind River Workbench, the main VxWorks application IDE. The following splash screen appears the first time you launch Wind River Workbench.

Select Start to continue.

Select Workbench to display the Wind River Workbench window.

You must create a new Wind River Workbench project to build a VxWorks Kernel Library. Select File » New » VxWorks Downloadable Kernel Module Project to create a new project.

Enter a unique name for the project using the Project name text box. Click the Next button until you arrive at the Build Specs page. Click the Deselect All button and the select PPC603gnu. Click the Finish button.

In the IDE, select File » Import to open the Import dialog box. Select File system from the import source list and then click the Next button.

Browse to your tutorial source code directory and select the library.cpp and library.h files. These files are the included sample code for the example library. Click Finish to import the source code into your new project.

5. Downloading and Executing Shared Library Code

Use an FTP program to upload your built library to the ni-rt/system directory on the target. Your library is now ready to use from within LabVIEW VIs.

LabVIEW VIs call shared libraries on a VxWorks controller using the Call Library Function node, the same way they call libraries on other Real-Time targets. However, because the LabVIEW development environment cannot read the library information in VxWorks shared libraries, the Call Library Function node must be configured blindly, without parsed symbol lists. (You can work around this limitation by configuring the node to use a Win32 build of the same library. The VxWorks library will be used on the target.) Note that the Calling Convention configuration parameter is ignored.

Turn the CONSOLE OUT DIP switch on the controller to the ON position and reboot the controller. The terminal will display output and diagnostics during the boot process. When it is finished, the message “Welcome to LabVIEW Real-Time” will print.

Loading LVRT...

Welcome to LabVIEW Real-Time 8.2.1

For more information about using the console, consult the VxWorks Kernel Programmer’s Guide.

CPU exceptions include crashes and breakpoints. By default, CPU exceptions trigger a reboot of the controller. You must disable the exception handler in order to set breakpoints or to debug a task that has crashed. There are two ways to disable the exception handler.

Editing the INI file to Disable the Exception Handler

Adding the following text to the ni-rt.ini file on the controller will disable exceptions until the text is removed:

[debug]
InstallExceptionHandlers=false

Using the Serial Console to Disable the Exception Handler

If you use the following procedure, the exception handler will be re-enabled on the next reboot.

Reboot the controller and the following text should appear, along with a countdown:

The console can print debug statements compiled into the library, and can set breakpoints at functional scope. Execution debugging can be performed at assembly code scope. No licensing is required to use this functionality.

Here is a brief summary of the commands you can use through the console to debug shared libraries. Please consult the VxWorks documentation for more details.

7. Debugging with Wind River Workbench

The techniques described in this section require the Wind River Workbench, which can be obtained from and is supported by Wind River. You must disable the CPU exception handler before debugging. Refer to the Disabling the CPU Exception Handler section of this document.

Configuring the Target Server

The target server is a process running on the host that sends debugging commands to the target. You can use the target server for source-level debugging and to download shared libraries. By default, the CompactRIO controller is not configured to receive and process debugging commands from the target server, but you can configure it to do so as follows:

Boot the controller with the serial console enabled. Refer to the Configuring the Serial Console section of this document.

When booting is complete, run the following command in the serial console:

The shared library must be loaded on the target, and the target server must have loaded its symbols from the local library copy. (The icon representing the library should have an “S” on it, and the symbols should be reported as loaded.)

Breakpoints can be set from the console or from the source code view. To set a source code breakpoint, right-click on the left bar of the view and select “Add Global Line Breakpoint.”

The target console will report when a breakpoint is hit. To debug at the breakpoint location, locate the stopped task in the Process tree of the target server connection, right-click it, and select Attach to Process.

The Debug menu is now populated with a full set of debugging commands.

For additional information, refer to the Wind River Workbench User’s Guide.

As far as Windows 7 support is concerned,
throwing your cRIO in the trash is certainly
a very drastic measure. Installing VirtualBox
and a Windows XP image instead seems a much
more practical solution, if you can't get the
toolchain to work out of the box on a newer
Windows system.

you need a toolchain gccdist_vxworks6.3_gcc3.4.4.zip - Jul 10, 2012

By
Seyong, National Instruments Korea.

http://zone.ni.com/devzone/cda/epd/p/id/6462
you must rename the
folder "c:\gccdist\supplemental"
to "c:\gccdist\supp"

Instructions for Windows 7 x64 - Nov 11, 2011

By
Marshall, SAIC.

You can in fact use the vxworks gcc build
tools here on windows 7 x64. If you run the
tools as is, it will build eventually but
will throw errors repeatedly concerning
sh.exe. This is because the build tools use
winZsh which is not compatible with win 7
x64. The easiest way to fix this is to
install cygwin (be sure to include make and
other build tools when installing). Once
installed create a setup-gcc.sh in
gccdist\supp with these contents:
export GCCPATH='C:\gccdist'
export GPATH=/cygdrive/c/gccdist
export
PATH=$GPATH/WindRiver/gnu/3.4.4-vxworks-6.3/x86-win32/bin:$PATH
export
WIND_BASE="$GCCPATH\\WindRiver\\vxworks-6.3"
export
WIND_USR="$GCCPATH\\WindRiver\\vxworks-6.3\\target"
export WIND_HOME="$GCCPATH\\WindRiver"
export
WIND_LIC_PROXY="$GCCPATH\\WindRiver\\setup\\x86-win32\\bin"
export
LM_LICENSE_FILE="$GCCPATH\\supp\\zwrsLicense.lic"
from cygwin, source the file (i.e. source
setup-gcc.sh) then run make from the example
directory.

- Oct 25, 2011

By
mkm mkm, University of manchester.

I am trying to use the supplied make file to build a
static library (.a) which I need to build the require
shared library but it fails. What modification is
required in the make file to generate a correct (.a)
static library.

Win7 X64 compatability - Aug 30, 2011

I need a version of this compiler that works
with Win7 x64. I have compiled using the
normal veristand target but the VX-works is
not functional for me at this time. Is there a
version coming out soon so I don't have to
throw my cRIO in the trash?

There are no problems in using LabVIEW manager functions - Jul 26, 2011

By
Rolf Kalbermatter, CIT Engineering Nederland BV.

I'm not sure what the previous comment really
wants to do. If he meant to hint at any
impossibility to call LabVIEW manager
functions then he should try again. There is
no need to link in explicitedly any labview.a
or something like under Windows since the elf
loader will resolve any dynamic symbols
automatically just as under any modern Unix
variant. However there are no documented TCP
symbols available in there and if you talk
about the platform libraries, then well you
should consult the VxWorks documentation.

Calling LabVIEW RT libraries - May 31, 2010

I can't find any information on using the
LabVIEW RT shared libriries from my
own shared library.
It must be possible (like on the PC) to
use the LabVIEW types and resources
(like TCP).
/Jan