AURIX ADS, Flasher, and TriCore debug

Use this guide on the Windows machine that holds your AURIX project and Infineon tools, with the probe attached. You can:

Turn an AURIX Development Studio (ADS) iLLD project into a CMake build with build.cmd and flash.cmd wrappers. See Prepare the project and tools.
Program the built HEX file with AURIX Flasher and check that the target starts. See Program and verify startup.
Halt, set breakpoints, step, and read state on TriCore cores from a hardware script. See Debug TriCore over TCF.

If your project already has a working build workflow, you can record its commands directly in EMBEDDER.md instead.

AURIX setup and debugging run only on Windows, because ADS, Infineon DAS, and the AURIX debug agent are Windows-only. On macOS or Linux, AURIX project setup isn’t offered, and debugging reports that it requires Windows. The Infineon tools are separate downloads under Infineon’s own licence terms; Embedder doesn’t bundle them.

Prepare the project and tools

Install ADS and CMake. Setup uses Ninja when it’s installed and otherwise falls back to the make tool that ships with ADS. You can use an external TriCore GCC, such as HighTec, but ADS is still required for its build utilities.
Confirm that the project root contains .cproject and an extracted, non-empty Libraries/iLLD/ folder. If the library is missing, right-click the project in ADS and select Add iLLD.
Check the build configuration in .cproject. Setup copies the CPU, optimization, debug, define, and linker settings from the External-GCC Debug configuration, or from Release if there’s no Debug one. TC2xx and TC3xx projects without an External-GCC configuration use the device family’s default CPU flag. TC4xx projects must have an External-GCC configuration and a GCC linker script; supply the script if the project doesn’t contain one.
Move any outputs you need out of build/, and review existing CMake files and wrappers before you continue.

Setup overwrites CMakeLists.txt, cmake/aurix-tricore-toolchain.cmake, init_stubs.c, build.cmd, and flash.cmd in the project root. It can also copy a linker script into the project root. When it builds, it first deletes the build/ folder.

Setup finds ADS under C:\Infineon\AURIX-Studio-* and picks the newest full edition. It skips the free limited edition unless you give its path. For a nonstandard location, give absolute Windows paths to the project, the ADS installation, the compiler folder, and any linker script, or set AURIX_STUDIO_ROOT to the ADS installation. An external compiler folder must contain tricore-elf-gcc.exe, tricore-elf-objcopy.exe, tricore-elf-size.exe, tricore-elf-ar.exe, and tricore-elf-ranlib.exe. If you don’t supply a linker script, setup uses the one .cproject names, then a GCC linker script already in the project root, then copies the device’s default script from ADS into the project. TC4xx has no default script to copy.

Generate and check the build

Ask Embedder to prepare the project, in Act or Debug mode:

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.

Approve the setup when Embedder asks. The result reports the detected device, the tools it used, and each file it wrote or kept. If CMake isn’t installed yet, setup still writes the files and warns you; install CMake before you build. Check the generated CMakeLists.txt, cmake/aurix-tricore-toolchain.cmake, build.cmd, and flash.cmd. Verify that the build succeeds for the intended CPU. A successful build produces build/app.hex for programming and build/app.elf, a debug build with symbols, for debugging. To build again from the project folder on that machine:

.\build.cmd

.\build.cmd clean removes CMake build outputs. Other arguments pass through to the CMake build.

Configure AURIX Flasher

Install the AURIX Flasher Software Tool separately on the Windows machine connected to the target. Setup looks for AURIXFlasher.exe in this order:

A path you give during setup (the executable or its folder).
The AURIX_FLASHER_PATH environment variable, set before you start Embedder.
The newest C:\Infineon\AURIXFlasher* folder.
Your PATH.

If you give a path, or set AURIX_FLASHER_PATH, and the executable isn’t there, setup stops with AURIXFlasher.exe not found. Correct the path and run setup again. If setup doesn’t find the flasher anywhere, it still writes flash.cmd with a placeholder FLASHER line. Install the flasher, then repeat setup with its path or edit that line to the full path of AURIXFlasher.exe. Until then, flash.cmd stops with a message asking for the path. It also stops if build/app.hex doesn’t exist. flash.cmd runs AURIX Flasher on build/app.hex with the flasher’s default erase, program, verify, and start steps. Arguments after flash.cmd pass through to the flasher. Confirm the connected board, the programming connection, and these settings before you use it. Setup doesn’t establish compatibility with every AURIX board or probe.

Program and verify startup

Connect and power the intended target according to its board instructions. Close other programming or debugger sessions.
Confirm that build/app.hex comes from a successful build for that target and that flash.cmd points at the flasher installed on this machine.

Ask Embedder to run the configured command and check the result:

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 replaces firmware and changes what the target runs. Check the flasher result and the expected startup behavior separately. A successful command exit doesn’t prove the application booted. See Flashing firmware for capture timing and boot checks. These wrappers run on the Windows machine attached to the target. The bridge flashing workflow is a separate path, and selecting a bridge doesn’t make these machine-specific wrappers portable.

Keep the project commands

If the project has no EMBEDDER.md, setup creates a starter file with build_command = ./build.cmd. It adds flash_command = ./flash.cmd only when it found the flasher; otherwise the line is commented out until you configure flash.cmd. Setup never changes an existing EMBEDDER.md, so add these commands yourself after you verify them. The generated CMake files and wrappers contain paths from this workstation. Keep them out of commits and run setup again on each machine. 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. Setup isn’t available in Plan mode.
Missing iLLD: extract the library into Libraries/iLLD/. An empty folder isn’t enough.
Several device folders under Libraries/iLLD/: setup can’t tell which device to target unless the project folder name includes it. Keep only the target device’s folder.
TC4xx configuration rejected: add an External-GCC configuration in ADS, and give a GCC linker script.
Unknown CPU setting: the ADS release is newer than this version of Embedder supports. Update Embedder.
ADS not found, or only the limited edition installed: give the absolute installation path or set AURIX_STUDIO_ROOT. Give the path explicitly to use the limited edition.
Compiler not found in ADS: give the folder that contains tricore-elf-gcc.exe and the other TriCore GCC tools.
cmake.exe not found: install CMake and add it to PATH, or install it under C:\Program Files\CMake.
Flasher path not configured: install AURIX Flasher and set the FLASHER line in flash.cmd before programming.
HEX file missing: fix the build and confirm build/app.hex before you retry.
Programming succeeds but no boot: check the flasher’s start and reset settings, board power, and firmware output before you assume another flash is needed.

Debug TriCore over TCF

Use the aurix.* helpers in a hardware script to debug TriCore targets. Embedder’s GDB integration doesn’t support TriCore, so gdb.* helpers don’t apply. Embedder works through Infineon’s AURIX debug agent, aurix-debugger.exe, which reaches the target through Infineon DAS. Save scripts in .embedder/hardware/ and run them as described in Hardware scripts.

Requirements

Windows, with the probe attached to the same machine. AURIX debugging isn’t available through a remote hardware bridge.
Infineon DAS, a free download that needs no licence. Embedder looks for it under C:\Program Files\DAS64 and similar folders; set DAS_HOME if you installed it elsewhere. The DAS tray service must be running.
The AURIX debug agent. Embedder uses one from ADS or another local install, or downloads one with your permission. See Find or download the debug agent.
The board’s debug connection over USB, such as its on-board DAP or miniWiggler.
An ELF built with symbols that matches the firmware on the target, such as the build/app.elf that project setup produces. Without it, Embedder can’t resolve source lines or globals.

Find or download the debug agent

aurix.connect() tries each agent it finds, in this order, and keeps the first one that connects and loads the ELF:

Order	Source
1	`connect(agent_path=...)` or the `AURIX_BIN_DIR` environment variable. When either is set, only that agent is used.
2	The agent Embedder downloaded earlier, if any
3	AURIX Development Studio installs, newest first. When `AURIX_STUDIO_ROOT` is set, only that installation is searched.
4	Infineon’s AURIX TCF debugger extension installed in VS Code or a compatible editor
5	`aurix-debugger.exe` on your `PATH`

The connect result reports the agent it used as agent_source and agent_path. When no agent is installed at all, Embedder asks Download the AURIX TCF debug agent? before it downloads anything. The prompt names the files, their source, the download size, and the folder they go into, and notes that they’re Infineon-owned tools under Infineon’s own licences. Approve it to continue. Embedder saves the tools under ~/.embedder/tools/aurix/. The downloaded agent is version 1.53, the version Embedder is tested with. Some ADS releases ship a newer agent that can connect but can’t load the ELF, so source breakpoints never bind. Embedder skips an agent like that and tries the next one. If the only agent installed is one of these, Embedder doesn’t offer the download, and connecting fails with No usable AURIX TCF agent. Set AURIX_BIN_DIR to a folder with a working agent, or pass agent_path.

Connect and set a breakpoint

Call aurix.connect() first, then set breakpoints and control execution. Most calls return a dict, so scripts can print results as JSON. aurix.eval() returns the value as a string, aurix.read_memory() returns bytes, and the listing helpers return lists.

.embedder/hardware/tricore_boot_check.py

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"])},
}))

aurix.connect(elf, device=None, entry='core0_main', core=0, svd=None, timeout_seconds=30.0, agent_path=None) starts the agent, loads the ELF’s symbols, and halts the target:

Argument	Effect
`elf`	Required. A relative path resolves from the project root.
`device`	Target to use when several are connected. `aurix.devices()` lists them.
`entry`	Function the boot core halts at. If the target is already past it, Embedder halts it where it is and returns `entry_reached: False`. Pass `entry=None` to attach without halting.
`core`	Index of the boot core
`svd`	Optional SVD file for peripheral register names
`timeout_seconds`	How long to wait for the connection
`agent_path`	Agent to use instead of the discovered one

Connecting attaches to the firmware already on the target. Program it with AURIX Flasher first.

Check image_check in the connect result before you trust anything else. When image_check["matches"] is False, the target is running different firmware from the ELF, and symbols, lines, and variables still resolve against code that isn’t executing. Reflash and reconnect. image_check is None when Embedder couldn’t compare the image, so test for that before you read matches.

The other helpers cover breakpoints, run control, and state:

Helpers	Use
`aurix.breakpoint(file, line, condition=None)`, `aurix.breakpoint_at(address, condition=None, cores=None)`	Set a source or address breakpoint. Always check `planted`: a breakpoint that didn’t bind never fires, and the next continue times out.
`aurix.breakpoints()`, `aurix.remove_breakpoint(id)`, `aurix.clear_breakpoints()`	List and remove breakpoints
`aurix.continue_until_break(timeout_seconds=15.0, core=None)`	Resume and wait for a stop. Returns `ok`, `timed_out`, and `stop` with `core`, `pc`, `reason`, `hit_breakpoint`, and `suspended_cores`.
`aurix.interrupt(core=None)`	Halt the target
`aurix.step`, `aurix.next`, `aurix.finish`, `aurix.step_instruction`	Step into, step over, step out, or step one instruction. Each takes `timeout_seconds=15.0` and returns the same result as `continue_until_break`.
`aurix.reset(core=None, type=None, halt=True)`, `aurix.reset_types(core=None)`	Reset the target and list the reset types it supports
`aurix.stack(core=None, depth=20)`	Read the call stack. Each frame has an `id` you can pass to `eval`.
`aurix.eval(expression, core=None, frame=None)`, `aurix.set_variable(...)`	Read a C expression as a formatted string, or write an integer or pointer variable
`aurix.read_memory`, `aurix.write_memory`	Read or write memory
`aurix.read_register`, `aurix.read_registers`, `aurix.write_register`	Read or write registers
`aurix.disassemble`, `aurix.find_symbol`	Disassemble code or name the symbol at an address
`aurix.cores()`, `aurix.devices()`	List cores with their state, or the targets DAS can see
`aurix.is_connected()`	Check whether the session is still connected

A breakpoint condition is evaluated by Embedder after each hit, not on the target. Every false hit stops and resumes the target, so a condition in a hot loop looks like a hang. Use an unconditional breakpoint and check values with aurix.eval() instead. When a run-control call times out, Embedder halts the target and returns timed_out: True with halted_by_timeout: True, so you can inspect where it stopped. If the debug agent stops responding, the result reports server_restarted or disconnected instead.

Cores, not threads

AURIX exposes cores, not threads. Core IDs look like S0.D0.C0. Every operation takes an optional core=. When you leave it out, Embedder uses a halted core, so single-core scripts don’t need it. A breakpoint halts every core. stop["core"] is the core Embedder reports as the cause, and stop["suspended_cores"] lists every halted core. When a specific core matters, read its stack explicitly.

What the helpers can’t do

Embedder reports an error in a script’s diagnostics when the script calls one of these:

Not available	Use instead
Data watchpoints (`watch`, `watchpoint`)	A breakpoint at each write site. Watchpoints would never trigger on AURIX.
`load_file` or `flash`	AURIX Flasher before you connect
`execute` (GDB commands)	`eval`, `read_memory`, `write_memory`, or `write_register`
`threads` or `tasks`	`aurix.cores()`. There is no RTOS task awareness.
Listing local variables	`aurix.eval("name", frame=frames[0]["id"])` for each variable

The helpers also have no RTT or ITM capture.

Finish the session

An AURIX session holds DAS and the probe while it’s open. End scripts with aurix.disconnect(). Embedder also disconnects the session when the script that opened it finishes, including after an error.

Troubleshoot debugging

Requires Windows: run Embedder on the Windows machine attached to the target.
Not available through a remote hardware bridge: run Embedder on the Windows machine with the probe, in a session that doesn’t use a bridge.
Infineon DAS is required: install DAS, or set DAS_HOME to its installation folder, then retry.
No AURIX target detected: connect the board’s DAP or miniWiggler over USB and confirm the DAS tray service is running.
Multiple AURIX targets are connected: pass device= with one of the names the error lists.
No usable AURIX TCF agent: the error lists each agent Embedder tried. Set AURIX_BIN_DIR to a folder whose aurix-debugger.exe works, or remove the override so Embedder tries the other agents it finds.
Breakpoint not planted: check the file name and line, confirm the line contains code, and check image_check.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

AURIX ADS, Flasher, and TriCore debug

Prepare the project and tools

Generate and check the build

Configure AURIX Flasher

Program and verify startup

Keep the project commands

Troubleshoot

Debug TriCore over TCF

Requirements

Find or download the debug agent

Connect and set a breakpoint

Cores, not threads

What the helpers can’t do

Finish the session

Troubleshoot debugging

​Prepare the project and tools

​Generate and check the build

​Configure AURIX Flasher

​Program and verify startup

​Keep the project commands

​Troubleshoot

​Debug TriCore over TCF

​Requirements

​Find or download the debug agent

​Connect and set a breakpoint

​Cores, not threads

​What the helpers can’t do

​Finish the session

​Troubleshoot debugging

Prepare the project and tools

Generate and check the build

Configure AURIX Flasher

Program and verify startup

Keep the project commands

Troubleshoot

Debug TriCore over TCF

Requirements

Find or download the debug agent

Connect and set a breakpoint

Cores, not threads

What the helpers can’t do

Finish the session

Troubleshoot debugging