This extension is provided on the Visual Studio Marketplace for use with a VxWorks SDK Project.
Usage of this extension is dependent on having a VxWorks SDK available on the host machine.
This extension allows developers to debug VxWorks based applications from the Visual Studio Code interface.
This guide is intended to be used by an Application Developer who needs to use the VxWorks SDK to write and test software solutions.
A VxWorks SDK package 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.
For this extension to function it requires the path of the your VxWorks SDK Project.
Navigate to the extensions tab and select the cog wheel for the VxWorks SDK, then select 'Extension Settings'.
Set this path to match the location where the SDK exists on your machine.
To create your first workspace:
Select File -> Open Folder and browse to the location you would like to place your VxWorks Application projects.
To make the folder a VSCode Workspace, use File -> Save Workspace As... and give the workspace a name.
You can now create, build and debug application projects in the workspace you have created. Any projects created while this workspace is active will be placed within the workspace folder.
Right clicking on this workspace will give you options to create VxWorks projects in this directory:
Run and Debug with VsCode
Boot VxWorks on the target hardware or emulate the machine using QEMU.
Note: You can use the "startGenericQemu" 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.
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.
Though the VxWorks SDK extension is capable of creating, compiling, and debugging applications, it still remains a work-in-progress and should be treated as such. The following gif shows an RTP debugging scenario, using configurations as explained in Run/Debug with VSCode
Here is a walkthrough of the debugging process using the VsCode Extension.
Create an RTP project - To create an RTP project using 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.
To build the created RTP using the VSCode extension, right-click on the project you wish to build and select "Build Project" from the menu that appears.
After a successful build you can see the rtp.vxe in the same project folder.
Refer to Run/Debug with VSCode for creating a launch configuration for the rtp project created above.
For further debugging we need a hardware target or to launch the VxWorks image in QEMU.
Add some breakpoints in rtp.c and launch the debug configuration as created in step 4. The following snapshot shows an example of hitting the breakpoint.
From this point you can add more breakpoints in methods and see them hitting. The following snapshot shows an example of hitting the breakpoint within an example API call.
The following features are supported by the extension:
- Loading Symbol files for RTPs, DKMs, and Shared Libraries
- Connecting To the Target specified with IP
- Running the RTP/DKM on target
- Set Multiple Breakpoints
- Thread Info
- Stack Info
- Variable Info
- Multithreaded support
The extension development is a work-in-progress and will be updated as additional capabilities are available.
VSCode Debug Configuration Settings
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.
- sdkPath: (string) Set the local path to SDK.
- cwd: (string) Path of project.
- target: (string) Path of executable.
- targetType: (string) Specifies the target type of the VxWorks executable (RTP or DKM). This is technically NOT required if your 'target' argument has a valid extension suffixed to it (.vxe for RTPs and .out for DKMs).
- startGenericQemu: (boolean) Enable automatically starting a generic QEMU image for each debug session. Default: False
- stopQemu: (boolean) Choose if QEMU instance should be terminated after debugging session has completed. Default: False
- noDebug: (boolean) Turn off the debugging features and only execute the application. Default: False
- targetIp: (string) Set IP address of target board. Default: localhost
- vxWorksKernelImage: (string) Set the local path of VxWorks kernel image. Default: SDK target image in
- dkmEntrypoint: (string) Set the name of the dkm function that will be the debugging entry point. Default: none, required parameter for DKMs
- debugger_args: (array) Additional arguments to pass to GDB. These are functionally executable arguments so the option and the value must be separate values. E.g ["-ip", "xxx.xxx.xxx.xxx"]
- -debug: Enable debug output at the interpreter level.
- gdbpath: (string) Path to the gdb executable or the command if in PATH.
- This should not be changed as it points to the WindRiver wrdbg utility by default. Any other GDB-equivalent utility will not be able to debug or run RTPs and DKMs in a VxWorks environment.
- arguments: (string) Arguments to append after the executable. You can also use pipes.
- terminal: (string) Leave this field undefined to keep program output in the VSCode console at the bottom. If this is set to empty string the program will spawn in a new console using x-terminal-emulator on Linux, otherwise with the specified terminal. On Windows setting this to an empty string spawns the program in a console, but no other console is supported.
- env: (object) Environment overriding the gdb (and in turn also the process) environment.
- valuesFormatting: (string) Set the way of showing variable values. 'disabled' - show value as is, 'parseText' - parse debuggers output text into structure, 'prettyPrinters' - enable debuggers custom pretty-printers if there are any.
- autorun: (array) GDB commands to run when starting to debug.
Though the VSCode extension is capable of creating, compiling, and debugging applications, enhanced debugging features are in development and will be added to the extension as they become available.
Below are some of the known limitations of the extension:
- The debug output is redirected to the serial console when debugging a DKM
- The debugger will not function properly if any source files have spaces in their path.
Copyright (c) 2020, Wind River Systems, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN