Debugging TI C2000 with the C2Prog GDB Server

A JTAG debug server and Lua scripting client for scripted tests, CI, and AI assistants

C2Prog includes a GDB server, c2p-gdb-server, and a scripting client, c2p-gdb. The server attaches to a TI C2000™ target through a JTAG debug probe and responds to the standard GDB Remote Serial Protocol on a TCP port. The client runs Lua scripts against it. The client also reads the ELF file of the application, so a script can name a variable or a source line. Together they let you inspect and control a C28x or C29x MCU from a shell, a build pipeline, or an AI assistant.

Starting the server

Here is an example for starting the GDB server:

c2p-gdb-server --ccs-base-path=<ccs_base> --non-intrusive 28P650DK9,DK8,DK7,DK6,SK7,SK6_JTAG xds110

The --ccs-base-path argument points the server at the TI EmuPack, which supplies the probe drivers. This may be either the EmuPack that the C2Prog installer installs, or the ccs_base directory of a Code Composer Studio or UniFlash installation. C2Prog uses the same path for JTAG programming, so c2p-cli get ccs-base-path prints the path your installation is already configured with. An AI assistant with the C2Prog agentic interface registered can also report the configured path and set it for you on request.

The last two arguments in the example above specify the target configuration and the debug probe. If the server does not recognize a target name, it prints every configuration available.

When several probes of the same type are connected, you must add the serial number to distinguish them: xds110:CL850001. On a multi-core F29x device, --core selects the CPU, for example CPU3 with --core=3. Once the server is listening, it writes a single JSON ready record to standard output with the port it bound to.

The assistant can report what is attached as well:

Which debug probes are attached to this machine?

The reply lists the connection ports it detects, with the serial number of each JTAG probe:

  - [jtag] xds110  (serial 00001234)  XDS110 Embed with CMSIS-DAP
      port options: xds110, xds110-2w

Two port options are offered for every XDS110, because detecting the probe does not reveal how the debug header of the board is wired. xds110 is 4-wire JTAG and xds110-2w is 2-pin cJTAG. The serial ports of the machine are listed too, including the probe’s own virtual COM port.

With --non-intrusive, the server attaches without halting the target, so the embedded application keeps running. Without it, the server halts the target when it attaches.

The target keeps its state for as long as the server stays attached, so one client can disconnect and the next one connecting will find the target where it was left. When the server exits, the probe releases the target, so a halted CPU runs again.

Scripting with c2p-gdb

GDB client scripts are written in plain Lua with a gdb table for target access. The following example reads the latched reset causes of an F29x device without stopping it:

local resc = gdb.read_memory(0x30200040, 1, 4)[1]
print('RESC 0x%08X' % resc)

This one runs to an interrupt service routine and reports the program counter and a global variable. The addresses come from the .map file, or from the symbols of the application (see below):

local isr    = 0x00082A10   -- adcA1ISR
local sample = 0x0000C010   -- a global variable
if gdb.run_to(isr, 1000) then
  print('PC     0x%08X' % gdb.read_register('PC'))
  print('sample %d' % gdb.read_memory(sample, 1, 2)[1])
end
gdb.remote_command('resume')

The client runs a script file against the server, on the port the server reported:

c2p-gdb script --port 3334 isr_check.lua

On C28x devices, addresses are 16-bit word addresses, as the .map file prints them. The width is the number of bytes per value, 2 or 4. On C29x devices, addresses are byte addresses.

The API covers memory and register access, registers by name (PC, ACC, XAR0 on C28x), halt, step, continue, reset, breakpoints, and the server’s monitor commands. The scripts folder of the installation holds ready-made recipes. For example, status_28x.lua reports the part identification registers and the lock state of each code security zone. watch_28x.lua samples a variable while the application runs. Each recipe states in its header whether it is read-only and otherwise which halts, resets and writes it performs.

Symbols of the application

The linker records every variable and function of the application, with its address, in the symbol table of the ELF file. The symbols command lists them:

c2p-gdb symbols --filter Ramfuncs my_firmware.out

Each row of the output shows the address, the size, the kind, the binding, the name and, for a file compiled with debug information, the type. Addresses and sizes are in addressable units of the target, so they read as the .map file prints them. The symbols command reads the ELF file alone and needs no debug probe and no GDB server.

Scripts can access the same symbols through the --elf option. gdb.symbol reports one symbol with its address and its size. gdb.read_symbol takes the path of a variable, a member of a structure or an element of an array, and decodes the value by its type. gdb.read_symbol can also read a single bit field of a register in TI’s device headers. gdb.run_to_line runs to a line of a source file instead of an address. gdb.where reports the function, the source file and the line where a halted target stopped:

print('kp  %f' % gdb.read_symbol('controlParams.kp'))
print('TSS %d' % gdb.read_symbol('CpuTimer0Regs.TCR.bit.TSS'))
if gdb.run_to_line('motor.c', 120, 5000) then
  print('at  %s' % gdb.where().function)
end

This script reads symbols, so the invocation names the ELF file with --elf:

c2p-gdb script --port 3334 --elf my_firmware.out line_check.lua

gdb.write_symbol writes a value by the same path and takes the width and the byte order from the debug information. A path can specify a global or a file-static variable. The client is not able to read the local variables of a stack frame.

gdb.backtrace lists the function a halted target stopped in, the function that called it, and so on. Each entry in the list is a frame, with its own function, source file and line. The frames are read from the return addresses that the processor recorded on the stack. An interrupt handler does not end the list, so the frames of the interrupted code follow the frames of the handler. The recipes stack_28x.lua and stack_29h85x.lua halt a device and report its frames.

Running the server for a single call

The c2p-gdb option --server-cmd starts the server for the duration of a single client call. The --single option in the example below makes the server exit once the session closes. Reading the part ID of an F28P65x, for example, is one line:

c2p-gdb script --json --server-cmd="c2p-gdb-server --ccs-base-path=<ccs_base> --single --non-intrusive 28P650DK9,DK8,DK7,DK6,SK7,SK6_JTAG xds110" -e "gdb.emit(gdb.read_memory(0x5D00A, 1, 4))"

The client waits for the server’s ready record. The call begins as soon as the server is listening. One attach of this kind takes one to three seconds, depending on the probe and the device. A build step or an AI assistant can therefore obtain one result from a single command, without starting or stopping a server. The target resumes when the server closes at the end of such a one-shot call.

Breakpoints

On F28x devices, a breakpoint in RAM is set by patching the trap instruction ESTOP0 over the instruction at the breakpoint address. For a breakpoint in flash, the server configures one of the CPU’s address comparators instead.

The first two comparators come from the C28x CPU’s own analysis unit. On an F28x device that carries an ERAD, the Embedded Real-time Analysis and Diagnostic module, the server configures a free ERAD comparator for every further breakpoint, which raises the number of breakpoints from two to ten. The F28002x, F28003x, F28004x, F2838x, F28P55x and F28P65x are among the devices with an ERAD. These are the same comparators that are used to implement watchpoints (see below).

On F29x devices, the TI debug driver implements no hardware breakpoints, so the server uses ERAD comparators. Every breakpoint uses one of the CPU’s eight comparators, in RAM as in flash, and application memory is never modified.

ERAD is also an application-visible peripheral, so the application may hold comparators of its own. The GDB server leaves those alone. The monitor status-json command reports the comparators in use and the ones still free.

A memory read at a patched address returns the original instruction, so a comparison against the programmed image still matches. Every patch and every comparator is released when the breakpoint or watchpoint is cleared, when the last client disconnects, and when the server shuts down, so nothing is left in the application. Breakpoints therefore do not survive a one-shot call.

Watchpoints

A watchpoint halts the target when it accesses a range of memory. A write watchpoint halts on a store, a read watchpoint on a load, and an access watchpoint on either. All three kinds work on F29x devices and on the F28x families that carry an ERAD. F28x devices without an ERAD report watchpoints as unsupported.

The following example finds out where in the code a variable is written. It halts the target, watches the four bytes of the variable for a store, and then reports the instruction that wrote them. gdb.symbol takes the address from the symbol table, so the call needs --elf:

local var = gdb.symbol('gVdc')   -- a global variable
gdb.remote_command('halt')
gdb.set_watchpoint(var.address, 4, 'write')
if gdb.cont(5000) then
  print('written by 0x%08X' % gdb.status().watch_pc)
end
gdb.clear_watchpoint(var.address, 4, 'write')

On F29x devices, watch_pc is the address of the accessing instruction. On F28x devices the ERAD records no such address, but the halted PC is close to the access. With --elf, the recipe watchwrite_29h85x.lua reports that instruction as a function and a source line.

Watchpoints consume ERAD comparators: one for a write, one for a read, two for a general access. On F29x devices these are taken from the same eight the breakpoints use. On F28x devices they are shared with any hardware breakpoint beyond the first two.

A watched range must be a power of two in length and aligned to that length. A float that the linker aligned to four bytes satisfies both. Four bytes at an address such as 0x200E0002 would be refused with an error, because that address is not a multiple of four. gdb.symbol reports the size of the variable as well. The recipe watchwrite_29h85x.lua watches that size when it is a power of two.

Opening the debug port of an F29x device

The F29x debug logic has one access port per CPU and two secure access ports (SEC-AP): one for the C29x CPUs and one for the HSM, the security processor of the device.

The security configuration active on the device can keep the CPU access ports closed. In SSU Mode 3, the mode in which the device enforces its security settings, four debug gates control JTAG access to the CPUs. A gate in password mode opens when a debugger presents that gate’s password over the C29 SEC-AP. While the C29 gate is closed, an attach to a CPU port fails with Connect:95.

The C29 SEC-AP is access port 1. Start the server on that port instead. The probe argument in the example below carries JSON, so the shell has to pass the double quotes through. A Unix shell does that with single quotes around the argument:

c2p-gdb-server --ccs-base-path=<ccs_base> 29H85xTU9,TU8-CPU1_JTAG 'xds110:{"ap":1}'

In a Windows command prompt, escape the inner quotes with a backslash instead:

c2p-gdb-server --ccs-base-path=<ccs_base> 29H85xTU9,TU8-CPU1_JTAG "xds110:{\"ap\":1}"

Then present the password and switch to CPU1:

gdb.remote_command('set debug-password 00112233445566778899AABBCCDDEEFF')
print(gdb.remote_command('get debugstatus'))
gdb.remote_command('set core 1')

The password is the 32 hex digits of debug.c29.password in the security configuration. The get debugstatus command applies it and returns the device’s DEBUG_ENABLE_STATUS register, whose bit 0 is set when the C29 gate is open. The server then stays attached to CPU1 for the next client connecting to it.

Machine-readable output

Every part of the toolchain can report back to its caller in a form a program can consume:

  • With --json, the client writes exactly one result document on standard output: either the value the script passed to gdb.emit, or an error message with a traceback for a script error.
  • Exit statuses name the failure class: 5 for a connection failure, 6 for a rejected target access, 7 for a script error.
  • monitor status-json returns the target state: running or halted, the patched breakpoints the server holds, and the comparators that are used and free.
  • The server accepts several connections. One of them can wait on a blocking continue while another reads memory from the running MCU.

A CI job can therefore test a change on real hardware. It flashes the firmware with c2p-cli, runs a script against the target and reads the outcome from the exit status.

Messages such as Connect:95 come from the debug probe or the target and pass through both tools unchanged. The manual lists error messages with their cause and the next step to take.

Working with an AI assistant

With the C2Prog agentic interface registered, an AI coding assistant can read status, memory, and registers without halting the target. It makes each query with one self-contained call and gets a JSON document back. A failure returns an exit status that says whether the probe, the target, or the script is at fault. The assistant can also hold a session open across several calls, which keeps the target halted where it stopped.

Prompts from everyday use:

Using C2Prog, read gVdc and gVdcFilt from the running F28P65x; the application is build/app.out.

The assistant looks both names up in the ELF file and reads each one. The raw reading comes back as 240.5 and the filter output as 240.0, decoded as the float that the debug information records. The application keeps running through both reads. A lookup reads the ELF file alone, so an assistant reports an address with no probe attached.

Halt at the control ISR at 0x08A120, read the EPWM1 time-base counter, period and both compare registers, then let the target run again.

The assistant holds a session open for this example. It runs to the address, reads the four registers one at a time, then resumes. The address is in flash, so the breakpoint comes from one of the ERAD comparators rather than from a patched ESTOP0. With the ELF file given, the assistant also reports the call frames of the halted CPU, each with its function and source line.

A prompt can also name a shipped recipe (script) instead of an address. This one ran against an F29H850TU LaunchPad:

/c2prog Run the startup status recipe on the F29 LaunchPad.

F29H85x startup status
  CPU              1 (access port 2)
  State            free-running
  RESC             0xC0000000
  Debugger latched true
  Boot mode        0x00000000
  RAMOPEN          0
  Reset cause      none latched

status_29h85x.lua reads the reset-cause register, the emulation boot mode and RAMOPEN. Its header declares it read-only. The free-running state shows that the application kept running through the read.

The /c2prog prefix selects the skill that the C2Prog installer registers in a Claude Code session.

One example from real use is the bring-up of a Modbus RTU driver on an F28P65x, where the driver was not answering on the bus. The assistant read the pin multiplexing registers one at a time and compared them against the pin map, then read GPBDAT twice: once with the bus idle, and once while the host adapter held a break condition.

idle    GPBDAT 0x12FFCFF9
break   GPBDAT 0x127FCFF9

Only bit 23 moved, which is GPIO55. The adapter was wired to the wrong pin. Both reads happened while the application kept running, with no scope and no UART console on the board.

The rest of a bring-up runs the same way: the assistant changes the code, builds and flashes it, then runs one script that goes to the point of interest and reads the peripheral registers back. The target runs again once that call ends, unless the assistant holds a session open across multiple operations.

Halting, resetting, stepping and writing change the state of the target. Your agent host can tell these apart from the reads and ask you before one runs.

Using C2Prog versus CCS for debugging

Standard GDB clients support neither the C28x nor the C29x architecture, so c2p-gdb includes its own reader for the ELF file of the application. That reader resolves global variables and source lines, but not the local variables of a stack frame. c2p-gdb steps by machine instruction, with no line-by-line stepping through C source. CCS covers debugging at that level. The C2Prog GDB tools are made for automated use, e.g. from a test script, a build pipeline or a coding assistant.


The Debugging Tools chapter of the C2Prog manual describes the server options, the monitor commands, and the full script API. The GDB tools ship with C2Prog and do not require a paid license.