Setting Up the Vitis Debugger Extension in Visual Studio Code - Setting Up the Vitis Debugger Extension in Visual Studio Code - 2026.1 English - UG1400

Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400)
Document_ID
UG1400
Release_Date
2026-07-31
Version
2026.1 English

This topic describes how to install the Vitis debugger extension for Visual Studio Code, configure a Target Communication Framework (TCF) connection to the target, and start a debug session.

Important: In Vitis 2026.1, the Vitis debugger extension for Visual Studio Code ships at the Internal software delivery milestone. The feature is validated for internal use and is not recommended for production customer flows. For a production-supported debug experience, use the Vitis Unified IDE.

Before You Begin

  • Install Vitis 2026.1 with the debugger component selected.
  • Install Visual Studio Code on the host machine.
  • Build the application that you want to debug. Have the executable (.elf) and any required symbol files available on the host.
  • For bare-metal targets, have the PDI or bitstream, the FSBL, and the device initialization script available. See Bare-Metal Targets at the end of this topic.
  • Confirm physical or network connectivity to the target hardware, or to the QEMU instance for emulation.

Install the Vitis Debugger Extension

  1. Launch the Vitis installer.
  2. Select the Vitis debugger extension for Visual Studio Code in the components list.
  3. Complete the installation. The installer provisions the extension so that it integrates with the Vitis debugging infrastructure.
  4. Open Visual Studio Code and confirm that the Vitis debugger extension appears in the Extensions view.

Configure the Target Communication Framework Connection

The extension supports the three TCF connection types listed in the following table. Choose the type that matches your target.

Table 1. Target Communication Framework Connection Types
Connection Type Target Notes
hw_server Bare-metal application on physical hardware Connect to a board running hw_server. Requires extensive targetSetup configuration. See Bare-Metal Targets at the end of this topic.
Linux TCF Agent Embedded Linux application on physical hardware Connect to the TCF agent running on the target operating system.
QEMU Emulation Connect to a QEMU instance running on the host or a remote machine.

To configure a connection:

  1. In Visual Studio Code, open the workspace that contains the application sources to debug.
  2. Open the extension settings and locate the Target Communication Framework configuration.
  3. Select the connection type for your target: hw_server, Linux TCF Agent, or QEMU.
  4. Enter the host name or IP address and the port for the selected connection type.
  5. Save the configuration.

Start a Debug Session

  1. In Visual Studio Code, open the Debug view.
  2. Select the launch configuration that targets the Vitis debugger.
  3. Specify the path to the application executable (.elf).
  4. Start the debug session. The extension connects to the target through the configured TCF connection and stops at the program entry point or at the first breakpoint.
  5. Use the standard Visual Studio Code debug controls to set breakpoints, step, inspect registers and variables, navigate the call stack, and switch threads.
Note: Debug session settings apply only to the active session. The extension does not modify project files or application binaries.

Bare-Metal Targets

Bare-metal debug through the Visual Studio Code extension requires extensive targetSetup configuration, including the PDI or bitstream, the FSBL, and device initialization. You must supply and maintain these artifacts manually through the extension settings.

For bare-metal workflows that depend on hardware setup, target programming, or project-integrated debugging, use the Vitis Unified IDE instead. The Vitis Unified IDE manages target configuration, programming, and the debug session as a single integrated flow.