> ## 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.

# XMOS xTAG and xgdb debugging

> Load or attach to an XMOS application and inspect its tiles, threads, and execution.

Use XMOS XTC Tools with an xTAG to debug an xcore board. The debugger uses the application's `.xe` artifact. For simulated execution without a board, see [XMOS xsim](/debug-mode/xsim).

## Prepare

1. Install XMOS XTC Tools for the host, including `xrun`, `xgdbserver`, and `xgdb`; persistent flash programming also requires `xflash`. Connect and power the board and xTAG.
2. Make XTC Tools visible to Embedder. Normal vendor locations and `PATH` are searched; for a custom installation, set `EMBEDDER_XTC_PATH` to the XTC root or its `bin` directory before launching Embedder.
3. Build the application's `.xe` file with debug information. Identify its exact path and the intended xTAG adapter ID.
4. Run `/debug` and ask Embedder to check XTC readiness and list the attached xTAGs. Resolve an in-use or invalid-firmware adapter before connecting.

## Select the application and target

Put the target selection in `.embedder/xmos.json`:

```json theme={"system"}
{
  "xe": "bin/app.xe",
  "target": "hardware",
  "adapterId": "YOUR_XTAG_ID",
  "xscope": "auto"
}
```

Replace `bin/app.xe` with the project-relative artifact path and `YOUR_XTAG_ID` with the ID reported for the intended adapter. With several adapters attached, specify the ID rather than relying on discovery. Old XMOS launch and adapter settings in `EMBEDDER.md` do not configure this selection.

## Load and inspect

```text theme={"system"}
Use the xTAG selected in .embedder/xmos.json. Start an XMOS debug run with
bin/app.xe, load the application, and stop at main. List the tiles and
threads, then show the current stack on the tile running the UART task.
```

A normal hardware debug connection requests a target reset, loads the `.xe`, and attempts to run to `main`. Loading the debug application is separate from programming persistent boot flash.

You can ask for tile selection, breakpoints, stepping, threads, registers, memory, and stack frames. State the tile when investigating code that runs across tiles; a stop on one tile does not by itself describe the others.

### Live and real-time applications

<Warning>
  xgdb is all-stop. Connecting, an interrupt, a breakpoint hit, and a run-control timeout each halt every logical core on every tile until the next resume. While the chip is halted, USB stops answering the host and the host drops the device. I²S, TDM, and other port-driven streams also stop, so an external codec loses sync. Any value or host-side result captured across a stop comes from a restarted stream.
</Warning>

xgdb cannot set breakpoints or read registers, memory, or expressions while the target runs. Every read needs a stop. On hardware that serves USB or audio, choose the observation by what must keep running:

* **Live values in a running stream** such as samples, levels, or counters: use [xSCOPE](/debug-mode/xscope) probes, which send values off the chip while it keeps running.
* **Configuration after init** such as codec registers or PLL settings: stop once after init, read the values, then re-run the image before starting a host test.
* **An exact block of consecutive samples:** fill a capture buffer in firmware, then attach once and read it after it fills.

Do not loop breakpoints in a sample loop, a USB endpoint task, or an audio callback to collect values. On the [xsim simulator](/debug-mode/xsim), a stop is harmless because no host or codec is waiting.

For repeatable work, the [hardware-script](/debug-mode/hardware-scripts) connection helper is `gdb.xmos_connect(...)`. It accepts `xe`, `adapter_id`, `simulator`, `xscope`, `sim_args`, `run_to_main`, `attach`, and `no_halt`.

## Program persistent boot flash

1. Build the `.xe` for the exact board and its boot-flash layout. Confirm `"target": "hardware"` and the intended `adapterId` in `.embedder/xmos.json`.
2. Identify any board-specific `.xn` target file and boot-partition size required by the project's established flashing procedure. Supply these in your request when needed; do not guess a partition size.
3. Stop the active debugger or xSCOPE run, then request programming through `xflash`:

```text theme={"system"}
Program bin/app.xe into boot flash through the hardware xTAG selected in
.embedder/xmos.json. Use the project's verified flash settings. Report the
xflash result without launching an xSCOPE capture afterward.
```

Replace the artifact path with your build output. Embedder releases its active xTAG sessions and runs `xflash --force`; this replaces flash contents. The default programming timeout is ten minutes. A successful result means `xflash` exited successfully; it does not establish that the board booted the new image.

4. After programming succeeds, power-cycle the board according to its instructions, then check a boot indicator or an independent output such as UART. Verify the firmware's expected startup behavior before starting another debug or xSCOPE run.

A fresh xSCOPE capture after flashing runs the `.xe` again from RAM. Its output can confirm that RAM run, but cannot establish boot from flash. If `"target": "simulator"` is selected, the same flash request reloads the simulator and does not program a physical board. See [flashing firmware](/debug-mode/flashing) for other targets.

## Attach to an existing run

Request attach-only to avoid loading the application and the normal hardware reset request. Also disable run-to-main explicitly. In a script, use `attach=True` and `run_to_main=False` with the matching `.xe`.

On XMOS, `no_halt=True` requests a continue after connection. It is not a promise that the target was never stopped, and it can resume a previously halted fault. State whether the target must remain halted or may continue, and follow the [attachment precautions](/debug-mode/gdb#attach-to-a-running-target). Attaching halts every tile even without a load, so it interrupts live USB and audio streams. See [live and real-time applications](#live-and-real-time-applications).

## Read output and finish

Use the [xSCOPE Monitor](/debug-mode/xscope) for application output. A Monitor connection matching an active xgdbserver session can reuse that session's console. Check which application and target the view is following before treating output as evidence.

When finished, ask Embedder to disconnect and state whether execution should continue. A debugger connection opened inside a hardware script is disconnected when that script is cleaned up.

## Troubleshoot

* **XTC Tools not found:** check the installation and `EMBEDDER_XTC_PATH`, then reopen Embedder.
* **No usable xTAG:** check power, USB access, adapter firmware, and competing XTC/IDE sessions.
* **Several adapters match:** set `adapterId` to the intended adapter's ID.
* **No `.xe` found or wrong symbols:** build the application and correct the `xe` path.
* **Breakpoint or variable unavailable:** check the selected tile, symbol information, and compiler optimization.
* **xgdbserver reports `Xcore N is not enabled`:** the debugger's own reset does not clear this state. Power-cycle the board, then retry the connection.
* **A simulated run was selected accidentally:** set `target` to `hardware` and verify the adapter before restarting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.