Skip to main content
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.

​
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:
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

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 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:
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.
  1. 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 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.

​
Read output and finish

Use the xSCOPE Monitor 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.
Last modified on September 12, 2026