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

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

## 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.
* **A simulated run was selected accidentally:** set `target` to `hardware` and verify the adapter before restarting.