VxWorks 7 SDK Guide: Build, Run, and Debug RTPs and DKMs

VxWorks 7 SDK Guide: Build, Run, and Debug RTPs and DKMs

📘 Introduction

#

The VxWorks 7 Software Development Kit (SDK) provides the tools required to develop, compile, debug, and test applications for a configured VxWorks platform. Application developers typically work with Real-Time Processes (RTPs), Downloadable Kernel Modules (DKMs), and shared libraries built against a specific VxWorks Source Build (VSB) and VxWorks Image Project (VIP).

The SDK includes cross-compilers, headers, libraries, debugging utilities, build tools, example projects, and platform-specific documentation. It supports conventional command-line workflows using Make and CMake, as well as graphical development through Visual Studio Code.

This guide covers the essential application development workflow, from initializing the SDK environment to compiling applications, connecting to a target, debugging runtime behavior, and testing with QEMU.

For a complementary overview of project configuration, see the VxWorks Build Guide: VSB, VIP, RTP, and DKM Configuration. It explains how the platform and application build layers fit together.

RTP vs. DKM

#

VxWorks supports different application execution models. Choosing the appropriate model affects memory isolation, access to kernel services, deployment, and the consequences of an application failure.

Real-Time Process (RTP)

An RTP runs in user space, with its own process environment and protected address space when the platform configuration supports the required protection mechanisms. RTPs are appropriate for most application-level functionality because faults can be isolated from the kernel and other processes.

RTP executables use the .vxe extension. They can be loaded from a target filesystem, such as RomFS, NFS, or an SD card, or transferred directly through the WRDBG debugging connection.

Downloadable Kernel Module (DKM)

A DKM runs in kernel space and can interact directly with kernel services and supported hardware resources. This makes DKMs appropriate for device drivers, low-level system extensions, and functionality that requires kernel-level access.

DKM builds typically produce .out object modules. These modules can be statically linked into a VxWorks image or dynamically loaded from a filesystem or through WRDBG.

Because DKMs execute in kernel space, an invalid memory access, synchronization defect, or other programming error can destabilize the entire system. Prefer RTPs when kernel-level access is unnecessary.

🧰 Prerequisites and SDK Setup

#

Before building applications, prepare the host development environment and obtain an SDK generated for the target platform.

Required Tools

#

The development environment typically requires:

• A compatible Python installation for the SDK utilities.
• A generated VxWorks 7 SDK supplied by the platform developer.
• The SDK’s cross-compiler and associated libraries.
• Make and, for CMake projects, a compatible CMake installation.
• WRDBG for target connection, loading, and debugging.
• A compatible VxWorks target or supported QEMU environment.

The original SDK workflow specifies Python 3.6 or later. However, the appropriate Python version depends on the installed SDK and bundled tools. Verify compatibility with your specific release before changing the host environment.

On Ubuntu or another Debian-based Linux distribution, Python can be installed with:

sudo apt-get update
sudo apt-get install python3 python3-pip

Where the SDK requires additional Python packages, install them in accordance with its documentation. A virtual environment can help isolate project dependencies from system Python packages.

On Windows, install a compatible Python release from the official Python downloads page and enable the option to add Python to PATH if appropriate for your installation.

SDK Directory Structure

#

A generated SDK commonly follows a structure similar to the following. Directory names may vary depending on the selected BSP, VSB architecture, host operating system, and build timestamp.

WRSDK_VXWORKS-7_<VIP_NAME>_<VSB_ARCH>_<HOST_TYPE>_<TIMESTAMP>/
├── bsps/
│   └── <BSP_NAME>/
│       ├── boot/vxWorks
│       ├── uboot/
│       │   ├── uVxWorks
│       │   └── vxWorks.bin
│       └── readme/
│           └── readme.md
├── toolkit/
│   ├── wind_sdk_env.linux
│   ├── wind_sdk_env.bat
│   ├── host_tools/
│   ├── wrdbg_tools/
│   ├── sdk_tools/
│   │   └── qemu/
│   ├── bin/
│   ├── compilers/
│   ├── include/
│   └── license/
├── artifacts/
│   ├── <VIP_PROFILE>.cdf
│   └── vsb.config
├── examples/
└── docs/
    └── resources/
        └── vxworks-7/

The primary directories serve different purposes:

• bsps/ contains platform-specific boot files and BSP documentation.
• toolkit/ contains host utilities, cross-compilers, headers, libraries, and debugging tools.
• artifacts/ may include configuration files needed to reproduce or rebuild the platform.
• examples/ contains sample applications and build templates.
• docs/ contains API references, BSP documentation, and other development resources.

The generated SDK should match the VSB, VIP, architecture, and target configuration against which the application will be built.

Initialize the SDK Environment

#

The SDK environment script configures the host shell so that the appropriate compiler, utilities, and libraries can be found.

On Linux, open a shell in the SDK’s root directory and run:

source toolkit/wind_sdk_env.linux

On Windows, open a suitable command prompt and run:

toolkit\wind_sdk_env.bat

Use the SDK-specific environment script rather than manually assembling a toolchain path from unrelated installations. This reduces the risk of accidentally selecting an incompatible compiler or host utility.

After initialization, verify that the required compiler and debugging utilities are available:

echo "$CC"

On Windows Command Prompt, use:

echo %CC%

If the compiler variable is not defined as expected, inspect the environment script and verify the SDK installation before proceeding.

🏗️ Build Applications from the Command Line

#

The SDK supports conventional C and C++ development workflows. Developers can use provided Makefiles, write their own build rules, or integrate the SDK toolchain with CMake.

Example Makefiles are commonly available under examples/makefiles.

Compile an RTP

#

An RTP executable typically has a .vxe extension.

With a project Makefile, navigate to the RTP project directory and run:

make

For a simple application that does not require a Makefile, compile it directly using the SDK-provided compiler.

On Linux:

$CC rtp.c -o rtp.vxe -static

On Windows:

%CC% rtp.c -o rtp.vxe -static

Replace rtp.c with the actual source file and adjust the source list and link configuration if the application contains multiple files or external dependencies.

The -static option requests static linking where supported by the toolchain and runtime configuration. Verify the linking requirements of your application and target SDK before using it.

Compile a DKM

#

DKMs use a kernel-module build configuration and normally produce a .out file.

With an appropriate project Makefile:

make

For a simple source file, compile with the SDK’s DKM option.

On Linux:

$CC -dkm dkm.c -o dkm.out

On Windows:

%CC% -dkm dkm.c -o dkm.out

The -dkm option instructs the toolchain to compile the source using the appropriate downloadable kernel module settings.

A DKM’s dependencies and ABI must match the target kernel configuration. Do not assume that an ordinary user-space object file can be loaded into the kernel simply by changing its filename extension.

For further details on build specifications and project configuration, consult the VxWorks VSB, VIP, RTP, and DKM build guide.

Build a CMake-Based RTP

#

CMake is useful when an application has multiple source files, external dependencies, or a more complex build graph.

The SDK provides CMake support files in examples/cmakefiles, including:

• Preload.cmake
• vxsdk_toolchain.cmake

Copy the required files into the CMake project directory and create a CMakeLists.txt describing the application’s sources, dependencies, and output.

A minimal workflow is:

cmake -DCMAKE_TOOLCHAIN_FILE=vxsdk_toolchain.cmake .
make

The toolchain file configures CMake to use the SDK’s cross-compilation environment rather than the host’s native compiler.

For larger projects, specify the required CMake version, source files, include paths, and libraries explicitly. Confirm that the generated build links against the libraries provided for the target architecture and execution model.

After the build completes, verify that the expected .vxe artifact was produced.

▶️ Run and Debug Applications with WRDBG

#

WRDBG provides a command-line interface for connecting to a target and managing application loading and debugging.

Before loading an application, establish a debugging connection to the VxWorks target or supported virtual machine.

Connect to the Target

#

Start WRDBG from the initialized SDK environment:

wrdbg

Connect using the target’s configured TCP debugging endpoint and the corresponding kernel image:

target connect vxworks7:TCP:<TARGET_IP>:1534 -kernel <PATH_TO_VXWORKS_IMAGE>

For example:

target connect vxworks7:TCP:10.10.10.5:1534 -kernel ~/SDK/bsps/ti_sitara/boot/vxWorks

Replace the example IP address and image path with the values appropriate for your target.

The target must be running, the debugging service must be available, and the host must have network access to the configured endpoint. Confirm the correct transport, port, and connection requirements in the target’s BSP documentation.

Run an RTP

#

After connecting to the target, load the RTP executable using the file command:

file <PATH_TO_RTP_APP>
run

For example:

file ~/SDK/examples/hello_world/RTP/hello_world.vxe
run

The first command identifies the executable, and run starts it under the debugging connection.

If the application fails to load, verify that the file exists, the binary was built for the target architecture, the selected runtime configuration is compatible, and the target has the required resources and libraries.

Load a DKM

#

DKMs are loaded as kernel modules rather than started as independent user-space processes.

From WRDBG, run:

module load <PATH_TO_DKM_APP>

For example:

module load ~/SDK/examples/hello_world/DKM/hello_world.out

After loading the module, use the VxWorks shell or the configured serial or virtual console to verify that its expected symbols are present.

For an example function named startHelloWorld, the shell can run:

lkup "startHelloWorld"

If the expected symbol is found, invoke it through the target shell according to the application’s entry-point design.

This distinction is important: loading a DKM does not necessarily execute its application-level functionality automatically. The module must expose an appropriate entry point, and the startup procedure must follow the DKM’s design.

Debug RTPs and DKMs

#

To debug an RTP, connect to the target and load the .vxe application through WRDBG:

file ~/SDK/examples/hello_world/RTP/hello_world.vxe

Set breakpoints, inspect variables, and control execution using the debugger commands available in the installed version.

For a DKM, load the module before debugging the relevant kernel-level function:

module load ~/SDK/examples/hello_world/DKM/hello_world.out
task create startHelloWorld

Use the command sequence appropriate to the module’s entry-point design and debugging configuration.

For command syntax and additional debugger capabilities, refer to the WRDBG Debug Shell Reference Guide.

🧑‍💻 Develop Applications with Visual Studio Code

#

Visual Studio Code provides an alternative to the command-line workflow through project templates, integrated build commands, and debugger configurations.

The VxWorks extension supports creation and development of RTP, DKM, and CMake-based RTP projects.

Create an RTP or DKM Project

#

After opening the SDK workspace in Visual Studio Code, use the Explorer context menu to create a new project.

For a conventional application, select one of the available options:

• New VxWorks Real Time Process
• New VxWorks Downloadable Kernel Module
• New VxWorks CMake Project

Project creation uses the configured SDK and its available templates to establish the basic source files and build configuration.

Build the Application

#

For RTP and DKM projects, right-click the project and select Build Project.

For a CMake project, select Build CMake Project.

Inspect the build output to confirm that compilation succeeded and the expected executable was generated.

If the extension does not detect the SDK correctly, verify that the project is open in the correct SDK directory and that the relevant environment and target configuration are available.

Debug from Visual Studio Code

#

The extension provides debugger launch options appropriate to the application type.

RTP debugging

Select the Launch RTP configuration and start debugging. The debugger loads the user-space executable and provides access to breakpoints, execution control, and variable inspection.

DKM debugging

Select Launch DKM and start debugging. Depending on the configuration, execution stops at main() initially or at another configured entry point.

For DKMs, verify that the target image and module are compatible. Kernel-level debugging requires additional care because a module defect can affect other tasks or the entire system.

Use VS Code with Containers

#

Container-based development can help isolate SDK dependencies and make the build environment more reproducible.

The documented workflow requires a Linux SDK. On a Windows host, Windows Subsystem for Linux (WSL) can provide the Linux environment.

Install the appropriate Visual Studio Code remote-development extensions, including the container extension and, where needed, the WSL extension.

Reopen the SDK folder in container mode.

The container must have access to the SDK and all dependencies required by the selected cross-compilation toolchain.

🖥️ Boot a VxWorks Target with Hardware or QEMU

#

Applications need a running VxWorks system that matches the SDK configuration. The target can be physical hardware or a compatible virtual machine, depending on BSP support.

Boot Physical Hardware

#

When using a hardware target, follow the BSP-specific README and boot instructions provided in the SDK.

Confirm that the target firmware, VxWorks image, network setup, and debugging configuration match the SDK. Different board families may require distinct boot parameters or connection procedures.

Start QEMU

#

Some SDKs include QEMU-based emulation support for testing without physical hardware.

From an initialized SDK environment, a documented example command is:

startqemu.py --smp 2 --m 512 -b

Here, --smp 2 requests two virtual CPUs, while --m 512 specifies a memory allocation of 512 MB for the emulator. The -b option and available arguments depend on the SDK’s startqemu.py wrapper.

Alternatively, start the SDK-provided QEMU utility directly:

python toolkit/sdk_tools/qemu/startqemu.py

Consult the tool’s help output and the BSP documentation for the options supported by your target configuration.

QEMU is useful for initial functional testing, build verification, and debugger familiarization. However, emulation results do not replace timing measurements on physical hardware when precise real-time performance is required.

🔬 Inline Assembly in VxWorks Applications

#

The SDK supports assembly code where the selected compiler and target architecture permit it. Inline assembly is useful for processor-specific operations, specialized instructions, and low-level optimization.

However, inline assembly is architecture-specific. Code that compiles for an x86 target will not necessarily compile or execute on an Arm target.

x86 Assembly Example

#

The following example illustrates a simple x86 register-to-register instruction:

#include "vxWorks.h"

void exampleX86(void)
{
    __asm("mov ax, bx");
}

This example is appropriate only for a compatible x86 compiler mode and target. It is not portable C and must not be used unchanged for an Arm build.

Arm Assembly Example

#

The following example illustrates Arm-style assembly syntax:

#include "vxWorks.h"

void exampleArm(void)
{
    __asm("mov r3, #0");
}

The instruction syntax and register names depend on the selected Arm execution state and toolchain. AArch64, for example, uses different general-purpose register names from 32-bit Arm.

When writing inline assembly, follow the compiler’s supported syntax and constraints. Consider whether the assembly modifies registers or condition flags, accesses memory, or interacts with compiler-generated code. Prefer intrinsics or ordinary C/C++ where they provide an equivalent capability with better portability and optimization opportunities.

⚠️ Known Limitations and Troubleshooting

#

Debugging Processes Remain After a Session

#

Some SDK debugging workflows may leave host-side helper processes, such as wrpython2.7 or TCF-server, running after a session ends.

If the tools fail to start or appear to conflict with a previous debugging session, inspect the relevant processes and clean up only those associated with the terminated session. Avoid terminating shared system processes indiscriminately.

WRDBG Does Not Handle Interactive Application Input

#

WRDBG is primarily a debugging interface rather than a general-purpose interactive terminal.

Applications that read from standard input or require terminal interaction may not behave as expected when launched through WRDBG alone. Use the target’s serial or virtual console for interactive input when the BSP and application configuration support it.

The Application Does Not Load

#

Check the following:

• The SDK matches the target architecture and configured VSB/VIP.
• RTPs use the appropriate .vxe output and DKMs use the appropriate .out module.
• The target is running the expected VxWorks image.
• The debugging connection is established and authorized.
• The application has the required libraries, symbols, and runtime support.
• The build completed without unresolved references or incompatible toolchain settings.

VS Code Builds Differ from Command-Line Builds

#

Different shells may use different environment variables or toolchain versions.

Initialize the correct SDK environment before building and verify that VS Code is using the intended SDK directory. For reproducible results, keep compiler versions, target settings, build options, and dependency versions consistent between development environments.

✅ Conclusion

#

The VxWorks 7 SDK provides a flexible development workflow for building, running, and debugging embedded applications. RTPs offer user-space isolation for most application logic, while DKMs provide kernel-level capabilities for drivers and other low-level extensions.

The essential workflow is straightforward: initialize the SDK environment, compile the correct application type, connect to a compatible target, and use WRDBG or Visual Studio Code to load and debug the resulting binary. QEMU can accelerate early testing when an appropriate emulation configuration is available.

For maintainable and reliable development, ensure that the SDK, VSB, VIP, target architecture, and debugging configuration are aligned. Prefer RTPs when kernel access is unnecessary, use DKMs only when the application requires kernel-level integration, and validate real-time behavior on the intended deployment hardware.

A disciplined build and debugging workflow provides a strong foundation for developing robust VxWorks applications across embedded devices, industrial systems, and other real-time platforms.