This document is intended to be used by an Application Developer who intends to write and test software solutions running in a VxWorks Real-time Operating System environment.
VxWorks supports several types of applications, including Downloadable Kernel Modules (DKMs), Real-Time Processes (RTPs), and shared libraries.
RTP - An executable application that runs in user-space as a process. An RTP runs in its own environment and cannot directly interact with other resources not mapped on to it.
DKM - An application that runs in kernel-mode as tasks, with full access to the system hardware.
Shared Library - A package of software components that reside in user-space and which can be accessed by multiple applications.
This Software Development Kit (SDK) provides the Application Developer with the tools necessary to compile, debug, and test new software solutions.
The instructions in this guide reference Linux commands using a Ubuntu 18.04 installation or a Windows 10 installation. If you are using a different operating system distribution, the command formats may not be the same.
Required: A VxWorks SDK produced from a VxWorks-7 installation.
Optional: Python
Python is used by the helper script provided to start a QEMU virtual target. If you do not require QEMU, then you can skip this prerequisite.
Python 3.8 is packaged with an SDK that has been produced from a VxWorks release version SR650 or later.
Alternately, if you need to install python, use the steps below.
Python 3.6+
Linux
sudo apt-get install <PYTHON_EXECUTABLE> && <PYTHON_EXECUTABLE> -m pip install -U pip
Example:
sudo apt-get install python3 && python3 -m pip install -U pip
Windows
Download the Python support for Windows and ensure Add Python to PATH is selected when installing.
Optional: QEMU
An installation of QEMU may be provided with your VxWorks SDK. Alternatively, QEMU may be installed directly by the Application Developer for debugging applications, provided that the supplied VxWorks image executes correctly with an available QEMU model. See the QEMU Guide for details on installing and configuring QEMU.
The SDK package provides two options for application development. A command-line interface can be used or the Visual Studio Code (VSCode) IDE can be used. See the getting started link below for details on setting up VSCode for use with a VxWorks SDK.
Visual Studio Code Getting Started
To create a project from VSCode you will need to have a workspace opened and the VSCode plug-in configured to reference your SDK location. Right-click in the workspace folder and select the project type you would like to create from the options as shown below:
An edit box will appear where you can enter the name of your project. VScode will automatically create a folder, a top-level C file (with "Hello World" code) and a Makefile for the project you created.
NOTE: From this dialog you are able to create C-code projects that use traditional makefiles, Cmake tooling, or a Rust-language project (if supported by your VxWorks SDK).
CMake Support CMake is an open-source, cross-platform family of tools which can be used with the SDK to build, test and package software.
The VxWorks SDK Generator includes full integration with CMake, allowing the user to easily build large and complex projects with minimal effort.
If the generated VxWorks SDK was built with CMake enabled, when you source the SDK environment, you will automatically have access to CMake. There is no need to download, install and configure Cmake separately. With VxWorks CMake, you can build existing CMake examples that are included in the generated SDK, or you can create your own projects.
Open a terminal window and create the project folder you wouild like to use, for example:
Linux
> mkdir /home/myuserid/my-vxworks-project
Windows
> mkdir \Users\myuserid\my-vxworks-project
Create a C-source file in your project folder.
Option 1: Project uses Traditional Makefile builds
Linux
> cp <my-sdk-location>/examples/makefiles/<Project-type>/generic_<project-type>_makefile <my-vxworks-project-folder>/Makefile
Windows
> copy <my-sdk-location>\examples\makefiles\RTP\generic_rtp_makefile <my-vxworks-project-folder>\Makefile
Option 2: Project uses CMake Toolchain builds
4a. You will need to create the CmakeLists.txt file in your project folder
4b. You will need to copy the toolchain.cmake that corresponds to your project type from the SDK.
Linux
> cp <my-sdk-location>/Cmakefiles/<Project type>/<Project-type>_toolchain.cmake <Project-folder>/toolchain.cmake
Windows
> copy <my-sdk-location>\Cmakefiles\<Project type>\<Project-type>_toolchain.cmake <Project-folder>\toolchain.cmake
Your project is ready to be built and executed with the SDK-included VxWorks RTOS image.
To build an existing applicaton using the VSCode extension, right-click on the project you wish to build and select "Build Project" or "Build Cmake Project" from the menu that appears.
To build an existing application from the command-line, open terminal and enter the project folder.
Build a traditional Makefile project
Linux or Windows
> cd <project-folder>
> make
2. Build a Cmake Project
Linux or Windows
> cd <project-folder>
> cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake .
To run/debug an application, an instance of the VxWorks image supplied with SDK must be running either on target hardware or in a QEMU session. Note: A representative QEMU-compliant VxWorks image is included with an SDK that is built for x86, ARM, and PPC target architectures. By default the QEMU start-up commands provided will start the emulated image and not the one created by the Platform Developer. See the boot guide for more details on starting a target with the desired VxWorks image.
Note: You can use the "useGenericQemu" setting in the launch.json to run a default QEMU-enabled image using the same architecture as the target SDK VxWorks image. To execute your SDK VxWorks image, use the command-line "startqemu.py" utility with the "-b" option, or boot the target image on Simics or the target hardware. The target VxWorks image may not work with QEMU.
Create a debug configuration (if one does not yet exist).
2a. Select the Debug tool, shown by triangle icon with a small bug in the lower left corner as shown in the image below.
2b. Click on "create a launch.json file"
2c. Select the "wrdbg" profile from the drop-down list of available debug configuration options.
2d. The launch.json configuration file will appear, similar to the image below.
To run or debug an RTP, you need to update two fields in the "Debug RTP" section. The "target" name (use the .vxe file name for your application) and the project folder, change the "cwd" location in the RTP section to your project folder name.
For other options, see the section: VSCode Debug Configuration Settings.
Note: The only difference between the "Run" project configuration and the "Debug" configuration, is the value set for the "noDebug" parameter in that section. The "noDebug" parameter indicates that breakpoints cannot be set, so the application will run unaffected by the debug agents.
You can add debugging configurations with different default settings by clicking on the drop-down box in the Debug window as shown below.
After clicking on "Add Config" for your workspace the list of options below will appear in your launch.json file.
Choose one of the options that is prefixed with "WRDBG".
To run/debug an application, select the configuration you want to use from the drop-down list in step 4) and press the green ▷ button to start the debugging session.
The VSCode interface provides a range of debugging features allowing you to add breakpoints, step-in and out of functions, view symbols, stack traces, process states, etc. Refer to the debugging section of the VxWorks SDK VSCode Guide for more information.
Boot VxWorks on the target hardware or emulate the machine using QEMU.
For details about booting targets see the VxWorksSDK Boot Guide
From a shell terminal, set up the SDK environment and then launch the Wind River Debug utility (wrdbg).
Linux
> cd <my-sdk-location>/toolkit
> source wind_sdk_env.linux
> wrdbg
Windows
> cd <my-sdk-location>\toolkit
> wind_sdk_env.bat
> wrdbg
Note: when you start wrdbg in Windows, you may see the dialog below as the it relies on an included python interpreter. Select "Allow Access" to continue using wrdbg.
Connect to the target hardware or virtual machine using the wrdbg shell. Whether the VxWorks image is running on hardware or in an emulator, the debug connection is always via a network port, so the connection command is identical, other than the IP address used. Port 1534 is the default port used by the VxWorks debug agent processes.
target connect vxworks7:TCP:<TARGET_IP_ADDRESS>:1534 -kernel <PATH_TO_VXWORKS_IMAGE>
Example:
target connect vxworks7:TCP:10.10.10.5:1534 -kernel ~/SDK/bsps/ti_sitara_a8_2_0_1_0/boot/vxWorks
Using the wrdbg shell, load the application onto the target hardware or virtual machine and start the process. Using the path and executable file name from the above create/build steps, the following commands will launch the application. RTPs will have a .vxe file extension and DKMs will have a .out extension.
For an RTP
file <Project-folder>/<project-name>.vxe
Example:
> file <my-sdk-location>/examples/hello_world/RTP/hello_world.vxe
For a DKM
module load <Project-folder>/<project-name>.out
task create <FUNCTION>
Example:
> module load <my-sdk-location>/examples/hello_world/DKM/hello_world.out
> task create startHelloWorld
Once the application is loaded, it is ready to be debugged.
For information on the wrdbg utility and the commands available, see the WRDBG Reference Guide.
If you do not have access to this guide contact Wind River: www.windriver.com/support
The debug configurations provided are pre-set to enable execution of DKM applications or RTP applications from VSCode using the debugger. The available parameters are described below and shown to be either required or optional. Optional settings have a default behaviour.
REQUIRED:
OPTIONAL:
<sdk-location>/bsps/<bsp-name>/bootCopyright (C) 05 06 2020 Wind River Systems, Inc.