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 togdb.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-jsonreturns 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
gVdcandgVdcFiltfrom the running F28P65x; the application isbuild/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.