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

# AURIX ADS, Flasher, and TriCore debug

> Prepare an ADS/iLLD project for Windows CLI builds, configure AURIX Flasher, and debug TriCore targets from hardware scripts over TCF.

Embedder can prepare CMake builds and `build.cmd` / `flash.cmd` wrappers for an AURIX Development Studio project, and can drive Infineon's `aurix-debugger.exe` from a hardware script to debug TriCore targets. Run project setup with Embedder on the **Windows machine that contains the project and tools**. Other existing AURIX build workflows can still be recorded directly in [EMBEDDER.md](/core-concepts/embedder-md).

For TriCore debugging, jump to [Debug TriCore over TCF](#debug-tricore-over-tcf).

## Prepare the project and tools

1. Install ADS and CMake. You can provide a compatible external TriCore GCC toolchain directory, but ADS is still required for its build utilities. Ninja is preferred when installed; the build wrapper can use ADS make instead.
2. Confirm that the project contains `.cproject` and an extracted, nonempty `Libraries/iLLD/` directory. In ADS, use **Add iLLD** if the library is missing.
3. Check that the project has a usable External-GCC configuration with the target CPU and linker settings. Setup prefers an External-GCC Debug configuration and falls back to Release. For TC4xx, a recognized target CPU setting is required; supply a valid GCC linker script if the project does not already contain one.
4. Save any needed outputs outside `build/`: setup's verification build deletes that directory. Review existing CMake files and build/flash wrappers before proceeding, because setup replaces its generated files.

For a nonstandard installation or project location, provide absolute Windows paths to the project, ADS installation, compiler directory, and any supplied linker script. If only the limited ADS edition is installed, provide its installation path explicitly during setup.

## Generate and check the build

Ask Embedder to prepare the project and review the proposed setup changes:

```text theme={"system"}
Prepare this ADS/iLLD project for CLI builds on Windows. Check .cproject,
the extracted iLLD, compiler, and target linker script. Generate the build
and flash wrappers, then build the target without flashing it. Report
missing tools or configuration before proceeding.
```

Check the generated CMake configuration, `cmake/aurix-tricore-toolchain.cmake`, `build.cmd`, and `flash.cmd`. Verify that the build succeeds for the intended CPU and produces **`build/app.hex`**. From the project directory on that Windows host, the generated build command is:

```powershell theme={"system"}
.\build.cmd
```

`build.cmd clean` cleans CMake build outputs. Keep needed artifacts elsewhere before cleaning or repeating setup's verification build.

## Configure AURIX Flasher

Install the **AURIX Flasher Software Tool** separately on the Windows machine connected to the target. Provide the absolute path to `AURIXFlasher.exe` during setup when it is not discovered automatically. You can also set `AURIX_FLASHER_PATH` before launching Embedder.

Setup can produce `flash.cmd` before the flasher is installed. If its `FLASHER` line still contains a placeholder, supply the installed executable path and repeat setup, or set that line to the full path. The wrapper refuses to flash until the path is configured and `build/app.hex` exists.

The wrapper invokes the installed AURIX Flasher with that HEX file and passes through additional command arguments. Confirm the connected board, programming connection, and the installed flasher's erase, program, verification, and start settings before using it. Setup does not establish compatibility with every AURIX board or probe.

## Program and verify startup

1. Connect and power the intended target using its board instructions. Close competing programming or debugger sessions.
2. Confirm that `build/app.hex` is the successful build for that target and that `flash.cmd` uses the installed flasher on this machine.
3. Ask Embedder to run the configured command and check the programming result:

   ```text theme={"system"}
   Use the configured flash.cmd to program build/app.hex on the confirmed
   local AURIX target. Report the flasher result, then check the firmware's
   expected boot indicator or UART output. Do not change programming settings
   or choose another connected target to bypass an error.
   ```

Programming can replace firmware and change target execution. Confirm the flasher's result and the expected startup behavior separately; a successful command exit does not prove that the application booted correctly. See [Flashing firmware](/debug-mode/flashing) for capture timing and boot checks.

This is a Windows command workflow using the tools installed on the target's host. The artifact-only [bridge flashing workflow](/debug-mode/flashing#flash-through-a-bridge) is a separate programming path; selecting a bridge does not make these machine-specific wrappers portable.

## Keep the project commands

Record the verified build and flash commands in `EMBEDDER.md`. Setup creates a starter file only when one is absent; it does not update an existing file. If the flasher path was unresolved, add or enable the flash command only after configuring and checking it.

Generated build and flash files contain workstation paths. Regenerate them on another machine and keep them out of commits. Keep the project's source configuration, target details, and expected boot checks available for that setup.

## Troubleshoot

* **Setup unavailable:** run Embedder on Windows with local access to the project and ADS tools.
* **Missing iLLD:** extract the library into `Libraries/iLLD/`; an empty directory is insufficient.
* **External-GCC or TC4xx configuration rejected:** correct the CPU configuration and provide the intended GCC linker script.
* **ADS not found:** provide its absolute installation path, including when selecting the limited edition explicitly.
* **Flasher path unconfigured:** install AURIX Flasher and set the wrapper's executable path before programming.
* **HEX file missing:** fix the build and confirm `build/app.hex` before retrying.
* **Programming succeeds but no boot:** check the flasher's start/reset settings, board power, and firmware output without assuming another flash is necessary.

## Debug TriCore over TCF

Embedder uses the TCF backend for TriCore debugging. Its managed [GDB](/debug-mode/gdb) path does not support TriCore; use the `aurix.*` helpers for an AURIX target.

Instead, Embedder speaks TCF (Target Communication Framework) directly to Infineon's `aurix-debugger.exe`, which reaches the target through DAS and MCD. A hardware script in `.embedder/hardware/` calls an `aurix.*` helper object that mirrors what the `gdb.*` helper offers on other targets.

### Requirements

* **Windows only.** DAS, MCD, and the agent do not run elsewhere.
* **Infineon DAS installed** (free download from `infineon.com/DAS`). The agent reaches the target through it.
* Either an AURIX Development Studio install (which bundles the agent) or Embedder's managed agent (see below).
* An ELF built with symbols. Without the ELF the agent cannot resolve source lines or globals.

### The agent Embedder uses

`aurix.connect()` walks every install it can find and keeps the first that reaches a working session with symbols loaded. Discovery order is: an explicit `agent_path=` argument, the `AURIX_BIN_DIR` environment variable, an AURIX Studio plugin tree, a VS Code AURIX TCF Debugger extension install, then `PATH`. The install actually used is reported as `agent_source` and `agent_path` in the connect result.

When no local install is found, Embedder can provision a pinned agent 1.53 into `~/.embedder/tools/aurix/` on demand. The download only happens after an explicit consent prompt that names the source, and each downloaded file is verified against a recorded SHA-256. Nothing is bundled into the Embedder binary. Infineon binaries (`aurix-debugger.exe`, `lsmcdd.exe`, `mcdxdas.dll`) are located, not redistributed.

Agent 1.53 is pinned deliberately. Newer builds (1.58 and 1.62) start and reach the target, but they never answer `MemoryMap.set` when it carries an ELF, so no source breakpoint can bind. Override the discovered choice with `AURIX_BIN_DIR` or `connect(agent_path=...)` when needed.

### Connect and set a breakpoint

Call `aurix.connect()` first, then use source or address breakpoints and run control. Every call returns a plain dict, so hardware scripts can print results as JSON.

```python .embedder/hardware/tricore_boot_check.py theme={"system"}
import json

aurix.connect(elf="build/App.elf", entry="core0_main", core=0)

bp = aurix.breakpoint("Cpu0_Main.c", 82)
if not bp["planted"]:
    raise RuntimeError(f"breakpoint did not bind: {bp.get('plant_error')}")

r = aurix.continue_until_break(timeout_seconds=15)
if r["timed_out"]:
    raise RuntimeError("target never reached the breakpoint")

frames = aurix.stack()["frames"]
counter = aurix.eval("g_counter")
aurix.disconnect()

print(json.dumps({
    "success": True,
    "summary": f"hit {frames[0]['file']}:{frames[0]['line']} with g_counter={counter}",
    "data": {"pc": r["stop"]["pc"], "cores_halted": len(r["stop"]["suspended_cores"])},
}))
```

Key call notes:

* **`aurix.connect(elf, device=None, entry='core0_main', core=0, svd=None, flash=False, timeout_seconds=30.0, agent_path=None)`** spawns the agent, registers the ELF for symbols and lines, and halts the target. `flash=True` programs the ELF at launch; the default attaches to whatever is on the target. Check `image_check["matches"]` in the reply before trusting anything. When it is `false`, the running firmware differs from the ELF, and symbols will resolve confidently against code that is not executing.
* **`aurix.breakpoint(file, line, condition=None)`** returns `{id, planted, plant_error?, ...}`. Always check `planted`; a breakpoint that did not bind never fires and the next continue simply times out. `condition` is evaluated in the harness (round-tripped stop → eval → resume), so avoid conditions in hot loops.
* **`aurix.continue_until_break(timeout_seconds=15.0, core=None)`** returns `{ok, timed_out, stop}` where `stop` includes `core`, `pc`, `reason`, `hit_breakpoint`, and `suspended_cores`. On timeout the target stays halted for inspection.
* **`aurix.eval(expression, core=None, frame=None)`**, **`aurix.read_memory` / `aurix.write_memory`**, **`aurix.read_register` / `aurix.read_registers` / `aurix.write_register`**, **`aurix.disassemble`**, **`aurix.find_symbol`**, and **`aurix.step` / `aurix.next` / `aurix.finish` / `aurix.step_instruction`** cover state inspection and single stepping.

### Cores, not threads

A TC397 has six cores with ids like `S0.D0.C0`. Every operation takes an optional `core=`; omitted, it uses the core that last stopped, so single-core scripts never mention it. A single breakpoint halts every core: `stop["core"]` is the elected primary and `stop["suspended_cores"]` is the full list. When you care about a specific core, read its stack explicitly rather than trusting the primary.

### What this backend refuses

`aurix.validate()` returns diagnostics that hard-refuse operations the TCF path cannot perform, so scripts fail loudly instead of silently no-oping:

* **No watchpoints.** The MCD layer ignores TCF `AccessMode`, so a data watchpoint would never trigger. Break at each write site instead.
* **No `load_file` or `execute`.** There is no GDB command line. Flash with AURIX Flasher (or `connect(flash=True)`), and use `eval` / `read_memory` / `write_register` in place of ad-hoc GDB commands.
* **No threads or RTOS tasks.** Use `aurix.cores()`.
* **No locals enumeration.** Read locals one at a time with `aurix.eval("name", frame=frames[0]["id"])`.
* **No RTT or ITM through this backend.** The AURIX TCF helper does not expose either transport.

### Session cleanup and the hardware queue

An AURIX debug session holds DAS while it runs. The hardware queue and probe-release paths now see AURIX sessions the same way they see GDB sessions. A script that leaves an agent running blocks the next debug session on the same probe. End cleanly with `aurix.disconnect()`, and check `/hardware-queue` before starting a conflicting operation.

### Verified target

The `aurix.*` helper is verified end-to-end on a `KIT_A2G_TC375_LITE` (3-core TC375, agent 1.53, MCD 1.14.9 over DAS): entry halt, source breakpoint with bind confirmation, all-core stop reporting, stack trace with line mapping, global evaluation, memory read, register read including groups, TriCore disassembly, symbol lookup, single step, and teardown. See [Hardware scripts](/debug-mode/hardware-scripts) for how to run and profile a script.