CCStudio for VS Code debugs your target device using VS Code's standard debugging UI. This chapter covers what is specific to debugging TI devices with CCStudio: starting a debug session, the additional views (Memory, Disassembly, XPeripherals, xRTOS, and Live Watch), debug configuration settings, and known issues.

7.1. Debugging Basics

CCStudio for VS Code debugs your target device using the same Run and Debug view, breakpoints, stepping controls, Watch expressions, and Call Stack used for any other language or runtime in VS Code. If you are new to debugging in VS Code, see Debugging in the VS Code documentation for an introduction to these fundamentals.

7.2. How Debugging Works

Several pieces work together to debug a TI device from VS Code:

  • VS Code does not debug anything itself — it provides the Run and Debug UI (Variables, Watch, Call Stack, breakpoints, and so on) and talks to a debug extension using the standard Debug Adapter Protocol, the same way it does for any other language.

  • TI Cortex Debug is that debug extension (see Installation and Setup). It translates between VS Code and GDB, and is responsible for starting both GDB and OpenOCD and connecting them together. It does not talk to OpenOCD directly.

  • GDB is the actual debugger — it understands your program's executable file, sets breakpoints, and handles stepping and running. GDB has no knowledge of your specific TI device.

  • OpenOCD is GDB's "gdb-server": the piece that knows how to talk to your specific TI device over the debug probe (such as an XDS110). GDB asks OpenOCD to do anything that is device- or hardware-specific, such as flashing the device or setting a hardware breakpoint.

In short: VS Code talks to TI Cortex Debug, which drives GDB, which drives OpenOCD, which talks to your device over the debug probe. Knowing this chain can help make sense of debug output or error messages that come from GDB or OpenOCD rather than from CCStudio itself.

7.3. Starting a Debug Session

The Debug option described in the Working with Projects chapter can be used to start a debug session for the project. CCStudio builds the project, starts the debug session, and runs to main. If it can't detect your device, you're asked to select one.

An example of an active debug session appears as below:

_images/ccsvsc_debug-active-session.png

CCStudio saves the debug settings for each project and build configuration in your workspace's .vscode/launch.json, in a configuration named <project>:<configuration>. Settings you add to it yourself are kept the next time you debug.

7.4. The Run and Debug View

The Run and Debug view has several sub-panels. Variables, Watch, Call Stack, and Breakpoints are standard VS Code debug panels; see Debugging Basics for details. XPeripherals and Cortex Live Watch are added by the TI Cortex Debug extension, installed automatically as part of CCStudio for VS Code.

  • Variables: View Local/Global/Static variables and Core Registers.

  • Watch: Add and view custom expressions.

  • Call Stack: View the current call stack. For RTOS projects, thread level visibility is available — see Visualize Your RTOS below.

  • Breakpoints: View, add/remove, and configure breakpoints.

  • XPeripherals: View memory mapped registers (defined by device SVD files).

  • Cortex Live Watch: Add and view memory addresses and global variables in real-time. See Watch Variables While Running With Live Watch below.

Near the top is the target execution command toolbar for common target execution and debug actions such as Continue (Run), Step Over, Step In, Reset device, Restart, and Stop (terminate debug session). This toolbar is also standard VS Code debugging UI; see Debugging Basics for details.

While debugging, use the Memory and Disassembly views to inspect device memory and step through instructions alongside your source code. There is also a Debug Console.

7.5. Memory View

The Memory view is another integral part of the debugger that shows the contents of the target memory starting at a specified address and with various data formatting features.

_images/ccsvsc_debug-memory-view.png

It features viewing multiple hexadecimal data sizes (8- through 64-bits), and every memory position has a context-sensitive information box.

The top toolbar for the view has an icon to Show/Hide Symbols.

There are fields for:

  • Location: A textbox that allows inputting an address or symbol name to navigate to it

  • Format: Allows the user to change the format in which the memory is displayed

7.6. Disassembly View

The Disassembly view lets you step through disassembled instructions alongside your source code during a debug session.

_images/ccsvsc_debug-dissasm-view.png

The toolbar contains several functions:

  • Address box: This box allows inputting an address or a symbol name to navigate to it.

  • Goto current PC location: Moves the view to the Program Counter's current position.

  • Assembly Step Over: Similar as above, but jumps over subroutines or functions, running the internal code all at once.

  • Assembly Step Into: Executes a single assembly instruction, and jumps into subroutines or functions, allowing the user to run the internal code step-by-step.

7.7. Visualize Your RTOS

If your firmware runs an RTOS, open the xRTOS view in the Run and Debug side bar while the session is stopped. It shows the state of the RTOS, such as its tasks or threads, so you can see what is running and what is blocked.

_images/ccsvsc_debug-xrtos-view.png

7.7.1. Enable Thread-Level Debugging

By default, the debugger shows a single thread for the whole device. To debug at the thread (task) level, set the RTOS in your .vscode/launch.json debug configuration:

"rtos": "auto"

auto detects the RTOS from your firmware. If it isn't detected, set the name of your RTOS instead: FreeRTOS or Zephyr.

Then restart the debug session. Each RTOS task now appears as a thread in the Call Stack view, where you can select a task to see its call stack and inspect its local variables.

Your firmware must be built with the RTOS's debug support enabled so the debugger can read the task list. If no tasks appear, check your RTOS debug settings and confirm that the rtos value matches the RTOS your firmware uses.

7.8. Watch Variables While Running With Live Watch

Live Watch lets you monitor global and static variables while the target keeps running, without stopping at a breakpoint. It is off by default. To use it:

  1. Open your .vscode/launch.json and add liveWatch to your debug configuration:

    "liveWatch": {
    "enabled": true,
    "samplesPerSecond": 4
}

    samplesPerSecond sets how often variables are read, from 0 to 20.

  2. Start a debug session.

  3. Go to the Cortex Live Watch view in the Run and Debug side bar and click + to add an expression. You can also right-click a global or static variable in the Variables view and choose Add to Live Watch.

Optionally, change how often the Live Watch view refreshes with the ccs-openocd.liveWatchRefreshRate setting (in milliseconds, default 300). Avoid values below 250, which can slow down debugging.

Live Watch only works for global and static variables. If the view shows a hint to enable liveWatch, check your launch.json, then restart the debug session.