Skip to main content

VxWorks

Protecting a VxWorks Image Project (VIP) with RunSafe Protect wraps the VIP build so the generated vxWorks kernel image is randomized at load time. No application source changes are required.

Supported Environment​

This guide applies to:

  • Windows 10 or Windows 11 build hosts
  • VxWorks 6.9
  • Wind River Workbench or command-line VIP builds using the GNU toolchain
  • x86, x86_64, and PowerPC 32-bit targets

For other configurations, contact support@runsafesecurity.com.

Prerequisites​

Before beginning, ensure that:

  • The VIP builds successfully without RunSafe Protect.
  • The VIP root contains .wrproject, .wrmakefile, and Makefile.mk.
  • Python 3 is installed. Workbench injects a python3 pre-build step; command-line workflows may use python or python3.
  • You have the RunSafe Protect VxWorks packages for your target. If you do not have those files, contact support@runsafesecurity.com.

Install RunSafe Protect​

RunSafe Protect for VxWorks is delivered as a combined Windows host package:

RunSafeProtect_VxWorks_<version>.zip

Extract the archive so that RunSafe Protect is installed at:

C:\Runsafe

The resulting layout should include:

C:\Runsafe\lfr\scripts\runsafe_install.py
C:\Runsafe\lfr\scripts\rs_build_prep.py
C:\Runsafe\lfr\libx86\
C:\Runsafe\lfr\libx86_64\
C:\Runsafe\lfr\libppc\

The install path is fixed. TrapLinker and the integration scripts expect tools, scripts, and target libraries under C:\Runsafe\lfr.

Do not put RunSafe wrapper scripts ahead of the real Wind River compiler or linker on PATH except through the VIP integration described below.

Integrate a Workbench Project​

Run the installer once, passing the root directory of the VIP:

python C:\Runsafe\lfr\scripts\runsafe_install.py C:\path\to\your\vip

The installer:

  • Verifies that the directory is a VIP.
  • Saves the original .wrmakefile as .wrmakefile_backup.
  • Adds a Workbench pre_build step that runs rs_build_prep.py before each build.
  • Creates the object blocklist file objs.rdb used during linking.

After installation, perform a clean rebuild from Workbench.

Integrate a Command-Line or Generated VIP​

Note: It is recommended to add the install steps to your build script or CI so they are done automatically for each build.

For projects created or refreshed with vxproj, run the installer once after checking out or generating the project:

python C:\Runsafe\lfr\scripts\runsafe_install.py C:\path\to\your\vip

Before each build, run the preparation script from the VIP root:

cd C:\path\to\your\vip
python C:\Runsafe\lfr\scripts\rs_build_prep.py

Then build the VIP normally, for example:

wrenv.exe -p vxworks-6.9 make clean
wrenv.exe -p vxworks-6.9 make

The preparation script updates the generated compiler and linker commands so they pass through RunSafe Protect. Randomization is linked into the kernel image and runs at kernel entry; you do not need to add _TRaP_lfr_run() calls to usrAppInit.c.

Build and Deploy​

Clean and rebuild the VIP using your normal Workbench or command-line process.

The protected output image is typically:

<vip-root>\default\vxWorks

Deploy it using your existing simulator, bootloader, or board. No separate RandoLib installation is required on the target; the runtime is linked into the image.

Verify the Integration​

Use the readelf supplied by your VxWorks / Wind River toolchain:

<target-readelf> -SWh path/to/vxWorks

A protected VxWorks image should contain RunSafe-generated sections, including:

.textforrando
.lfr.heap

Boot the image and confirm that the system reaches normal application startup.

Further run-time verification can be performed by dumping function addresses between runs with:

-> d <function>
NOTE: memory values are displayed in hexadecimal.
0x<address>: <function instructions>

For general verification concepts, see Verify Integration.

Troubleshooting​

.wrmakefile does not exist​

Ensure the installer was given the VIP root rather than its default output directory or another parent directory.

.wrmakefile_backup is present​

The installer has already been run for this project. Do not delete or overwrite the backup unless you intend to restore and reintegrate the project.

Unsupported compiler or target configuration​

Confirm that the VIP uses a supported GNU compiler and architecture. Contact support for configurations outside the supported environment listed above.

RunSafe sections are missing​

Confirm that:

  • RunSafe Protect was extracted to C:\Runsafe.
  • The pre-build preparation step ran successfully.
  • The generated Makefile.mk wraps CC and LD with lfr-helper.
  • The project was cleaned before rebuilding.

If the issue continues, send the complete build log, VxWorks version, target architecture, and Workbench version to support@runsafesecurity.com.