VxWorks SDK - Visual Studio Code Guide

Table of Contents

• About
• Visual Studio Code for VxWorks SDK
• VxWorks SDK Debugging with VSCode
  • Run/Debug with VSCode
  • VSCode Supported Features
  • VSCode Debug Configuration Settings
• Known Limitations

About

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. Make sure you have satisfied the prerequisites as specified in the Application Developer Guide

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.

Visual Studio Code for VxWorks SDK

To get started, you will need to have Visual Studio Code IDE installed for your operating system from the link below.

Visual Studio Code Download

After the installation is complete, launch VSCode and install the VxWorks SDK extension from the Visual Studio Marketplace using the link below.

VxWorks SDK Extension for VSCode

The VxWorks SDK extension supports several project types. To get started using the extension, you will need to reference you SDK from the extension settings.

Browse to the VxWorks SDK Support extension in your VSCode Extension listing.

Left-click on the settings "gear icon" and choose "Extension Settings".

The extension allows the SDK to be referenced on a user or workspace basis. For now, add the top-level location of your SDK to both.

If you do not already have a VSCode workspace set-up, do the following.

1. Select File->Open Folder, and browse to the location you would like to place your VxWorks Application projects.

2. To make the folder a VSCode Workspace, use File->Save Workspace As... and give the workspace a name.

3. 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.

VxWorks SDK Debugging with VSCode

VxWorks SDK extension uses VSCode's built-in debugger to accelerate editing, compiling and debug loop.

Run and Debug with VSCode

1. Boot VxWorks on the target hardware or emulate the machine using QEMU. See the boot guide for more details on starting a target with the desired VxWorks image.

VxWorks SDK Boot Guide

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.

1. 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.

   

2. 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.

3. 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".

4. 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.

5. 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.

VSCode Supported Features

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 debugging process using VsCode Extension.

1. 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.

1. 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.

1. After a successful build you can see the rtp.vxe in the same project folder.

2. Refer to Run/Debug with VSCode for creating a launch configuration for the rtp project created above.

1. For further debugging we need a hardware target or to launch the VxWorks image in QEMU. See the VxWorks SDK Boot Guide for more details on starting a target with the desired VxWorks image.

2. 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.

1. 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 * Stepping * Continue * 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.

• REQUIRED:

  • 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).

• OPTIONAL:

  • 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 <sdk-location>/bsps/<bsp-name>/boot
  • 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.

Known Limitations

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) 05 06 2020 Wind River Systems, Inc.