> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TI CCS and XDS debugging

> Debug C2000/C28x firmware with an installed Code Composer Studio setup and XDS probe.

Embedder can use Code Composer Studio (CCS) scripting to debug C2000/C28x firmware. Supported probe selections are XDS110, XDS100v1, XDS100v2, and XDS100v3. The installed TI target definitions and drivers must support the exact device and probe.

## Prepare CCS

1. Install CCS with the scripting tools, target database, and drivers for your probe and device. The host needs the appropriate vendor installation; Embedder does not supply CCS.
2. Connect and power the target. Close other CCS sessions using the probe.
3. Build a debug artifact that CCS can load, such as an ELF-format `.out` file, with matching symbols.
4. Identify a TI-authored `.ccxml` target configuration for the board. For a multicore device, record the intended core name from that configuration.
5. Run `/debug` and ask Embedder to check the installation, exact probe version, target configuration, and device before connecting.

Provide the CCS installation root and `.ccxml` path in your request when discovery is ambiguous. You can also set `EMBEDDER_CCS_ROOT`, `EMBEDDER_CCS_CCXML`, `EMBEDDER_CCS_PROBE`, and `EMBEDDER_CCS_DEVICE` in the environment that launches Embedder. Use an absolute path for the environment's `.ccxml` value.

Embedder reuses the resolved project configuration from `.embedder/ccs.json`. If you change boards or probes, provide the new device, probe, and `.ccxml` explicitly so a previous selection is not mistaken for the current setup.

## Program and debug

```text theme={"system"}
Use CCS with targetConfigs/board.ccxml and the connected XDS110.
Load and verify build/app.out, run to main, and read the PC and registers.
Confirm the configured device and core before connecting.
```

Replace both paths and the probe with your actual setup. A normal connection loads the program and attempts to stop at `main`. You can request breakpoints, run/interrupt, stepping, register and memory reads, and expression evaluation.

For a repeatable check, save a [hardware script](/debug-mode/hardware-scripts) under `.embedder/hardware/`:

```python theme={"system"}
gdb.ccs_connect(
    elf="build/app.out",
    ccxml="targetConfigs/board.ccxml",
    probe="xds110",
    run_to_main=True,
)
print(gdb.read_registers())
```

The example programs the target. Replace its values before asking Embedder to run it. The script's debugger connection is disconnected during cleanup.

## Attach and capability differences

For existing firmware, request attach-only with the matching artifact. This loads symbols without loading the program. Request no-halt separately to avoid Embedder's explicit interrupt after attachment; the TI connection sequence can still affect execution.

CCS handles a programming connection with no-halt differently from J-Link and OpenOCD: it loads the program, then requests execution. Do not use no-halt as a substitute for attach-only.

XDS110 uses the modern CCS scripting path. XDS100v1 uses legacy DSS; XDS100v2 and v3 depend on the installed CCS version. **Stack and frame inspection are unavailable in legacy DSS sessions.** Use supported register, memory, and expression queries there, or a compatible modern CCS setup when call-stack inspection is required.

`gdb.execute()`, `gdb.threads()`, and `gdb.tasks()` are unavailable in direct CCS sessions. Do not start a GDB server before `gdb.ccs_connect()`.

On C28x, memory addresses are target-native word addresses. The requested read size and returned data remain byte-based; each 16-bit word is serialized little-endian and the result is trimmed to the requested byte count.

## Troubleshoot

* **Missing scripting runner or TI files:** repair the CCS installation and ensure its probe connection, device, and C28x driver definitions are installed.
* **Generic XDS100 is ambiguous:** specify `xds100v1`, `xds100v2`, or `xds100v3`, or supply the matching `.ccxml`.
* **Multiple target configurations match:** pass the intended `.ccxml` explicitly.
* **Configuration conflicts with the requested device:** use the correct TI configuration rather than forcing mismatched values.
* **Automatic target configuration is unavailable:** supply a TI-authored `.ccxml`, especially for routed or CLA configurations with XDS100v1.
* **Stack query is unsupported:** check whether the session uses legacy DSS.