A watchpoint is a type of breakpoint. You can use watchpoints to stop the execution of a core when the value at an address changes. These are useful in determining the place where the value changes. For example, a variable value can be overwritten unexpectedly, which can break the program flow. Watchpoints help in detecting such cases.
AI Engine architecture supports read/write watchpoints. This means a watchpoint is triggered on a read or write access, or both (based on your configuration).
Each AI Engine tile supports two watchpoints per memory bank. Each non‑boundary AI Engine core accesses memory banks in adjacent tiles. A core can use up to eight watchpoints. Because memory banks are shared, available watchpoints per core depend on current bank usage. If one core uses all shared watchpoints, other cores cannot use them. The debugger tracks watchpoint allocation per bank and reports an error when no unused watchpoints remain.
- To add a watchpoint in the Vitis Unified IDE, locate the WATCH window in the bottom left side. Hover your mouse on that window and click the Add Expression (+) command.
- You can enter the memory address or the variable name of interest. Values
in the watchpoints can appear as "not available" if you select a core other than
the core you created the watchpoint for. For example, if you created watchpoints
by selecting the core in the debug view, the updated values only appear for that
particular core. For all other cores, the watchpoint values appear as "not
available."
- You can edit, copy, and remove one or all watchpoints by right-clicking on any watchpoint.
Triggering of Watchpoints
A watchpoint triggers on a read access or write access, or both, based on how the watchpoint was configured. A triggered watchpoint causes the core to stop at the instruction that accessed the address. The debugger detects the core stopped because of the watchpoint and reports the event.
- Watchpoints work on hardware only, not AI Engine system C models.
- Memory banks are shared. Do not add watchpoints for a core in a specific bank, if another core uses both the watchpoints from that bank.
- Do not set watchpoints for memory addresses that fall in unused tiles or
memory banks. Setting watchpoints to unused tiles can cause AXI errors. You
can find used AI Engine and memory tiles
at
Work/aie/active_cores.json. - Watchpoints trigger for memory accesses in the full 16-byte aligned address range.
- The debugger uses two broadcast channels to handle watchpoint events. When enabling watchpoints during debug, ensure there are no conflicts in using these two broadcast channels.