Cross-Compiling HDF5 .so Libraries for NI cRIO Linux RT

Problem Statement

A LabVIEW HDF5 interface such as h5labview ships with a Windows DLL and a set of VIs whose Call Library Function Nodes (CLFNs) bind to that DLL. Moving those VIs to a CompactRIO controller running NI Linux Real-Time does not work by copying the DLL: the controller runs Linux, and the binary must be rebuilt as an ELF shared object (.so) for the controller's CPU architecture.

The work splits into four distinct tasks, and each one can fail independently:

1. Compile every C/C++ source file in the library to an object file (.o) for the target architecture.
2. Link the full set of objects into a single shared object (.so) — the Linux equivalent of a Windows DLL. A single .o is not sufficient.
3. Install the .so (and any dependency libraries such as zlib or szip that HDF5 was configured against) onto the cRIO.
4. Review every VI in the toolkit so its CLFN library path, function name, calling convention, and parameter types match what the rebuilt .so actually exports.

Match the Binary to the Controller Architecture

cRIO controllers running NI Linux Real-Time fall into two incompatible binary families. Build for the wrong one and the shared object will not load at all.

A cRIO-9056 belongs to the 905x group, so it takes the 64-bit Intel x86 build. If the deployed system later mixes a 906x chassis into the fleet, you must maintain and deploy two separately compiled .so files and select at deployment time.

Toolchain Option A — NI Linux RT Cross-Compile SDK

NI publishes cross-compilation documentation for NI Linux RT targets at https://nilrt-docs.ni.com/cross_compile/cross_compile_index.html. The general flow described there remains the standard starting point. Expect minor drift: Linux tooling, glibc versions, and SDK packaging move continuously, so the exact package names and script paths may differ slightly from the document.

Typical sequence on a Linux build host:

1. Download and install the SDK matching your NI Linux RT version and the target architecture (ARM or x86-64). Do not mix an SDK from one NI Linux RT release with a controller imaged to a different release — glibc and libstdc++ symbol versioning is the usual failure point.
2. Source the SDK environment script so CC, CXX, CFLAGS, LDFLAGS, and SYSROOT point at the cross toolchain.
3. Configure the HDF5 source tree for cross-compilation, enabling shared libraries and disabling anything that requires running test binaries on the host.
4. Build, then repeat for the LabVIEW-side wrapper sources that expose the HDF5 API to the CLFNs.

. /usr/local/oecore-x86_64/environment-setup-<target>

# HDF5 core library
./configure --host=$CROSS_TARGET --prefix=/usr/local \
            --enable-shared --disable-static \
            --disable-tests --disable-tools
make -j$(nproc)
make DESTDIR=$PWD/stage install

# Wrapper layer: one .o per source file, then one .so
$CC $CFLAGS -fPIC -c src/*.c
$CC -shared -o libh5lv.so *.o -L stage/usr/local/lib -lhdf5 -lz

file libh5lv.so
readelf -d libh5lv.so | grep NEEDED

Cross-compiling is the reproducible option: it scripts cleanly into CI and produces the same binary every build. Its cost is the up-front effort of getting the SDK, sysroot, and autotools/CMake cross settings consistent.

Toolchain Option B — Native Build in a VM from the Recovery ISO

A practical alternative that has been used successfully: install the NI Linux RT compiler environment inside a VirtualBox virtual machine created from the cRIO recovery ISO, then compile natively inside that environment. Because the VM runs the same distribution and libc as the controller, the sysroot problem disappears — headers, library versions, and ABI match by construction.

The VM route is the faster path to a first working binary on an x86-based controller such as the cRIO-9056. Keep the cross-compile SDK in mind for the ARM 906x variant and for automated builds later.

Deploy and Bind from LabVIEW

1. Copy the .so and its dependencies to the controller over SSH/SFTP into a persistent directory on the target's writable filesystem.
2. Ensure the dynamic loader can find it — either place it in a directory already on the loader search path and refresh the cache with ldconfig, or set an explicit path. Verify with ldd /path/libh5lv.so; every NEEDED entry must resolve, with no "not found" lines.
3. Set the CLFN library name in the VIs to the Linux name (libh5lv.so) rather than the Windows DLL name. Use the platform-conditional library path or an environment-appropriate constant so the same VI hierarchy still runs on Windows.
4. Confirm calling convention. On Linux RT there is no stdcall; the CLFN must be set to the C calling convention.
5. Re-check every parameter: pointer-sized integers, struct alignment, string handling (C string vs LabVIEW handle), and array passing. A 32-bit-era wrapper written for a Windows DLL frequently mis-declares pointer parameters on a 64-bit Linux target.

Verification Sequence

1. Toolchain sanity: build and run a trivial "hello world" executable on the controller first. If that does not run, no amount of HDF5 debugging will help.
2. Load test: run ldd on the target, then call one trivial exported function (for example a library version query) from a scratch VI.
3. Function-by-function: validate exported entry points incrementally rather than deploying the whole toolkit at once. Bringing up the first handful of functions cleanly is a strong indicator the ABI and build configuration are correct.
4. Round-trip data check: write a small dataset on the controller, transfer the file to a workstation, and read it with an independent HDF5 reader to confirm layout, datatype, and endianness.
5. Soak test: run continuous acquisition and file writes for hours and monitor memory on the target. Handle leaks in HDF5 wrappers show up as slow RSS growth, not as immediate errors.

Risk-Reduction Fallback: Stream to the Host, Write HDF5 There

Porting a large C library to a real-time target is open-ended work with an uncertain schedule. A defensible interim architecture is to keep the file-format dependency off the controller entirely:

• The cRIO acquires and buffers data, then streams it to the Windows GUI PC over a network transport (network streams, TCP, or your existing messaging layer).
• The Windows application writes the HDF5 file using the already-working Windows DLL build.
• The cRIO retains local buffering to ride through short network outages, sized from your acquisition rate and worst-case outage duration.

This removes the port from the project critical path, lets the acquisition system go live, and leaves the cross-compiled .so as an optimization to be dropped in later once it passes the verification sequence above. The main trade-off is that logging then depends on network availability and host uptime, so size the on-controller buffer deliberately rather than by default.

Common Failure Modes