Watchpoints - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English

A watchpoint is a type of breakpoint. Watchpoints can be used 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. Because every AI Engine core (excluding tiles on boundaries) has access to memory banks in adjacent tiles, a maximum of eight watchpoints can be used per core. However, because the memory banks are shared, the number of available watchpoints per core depends on how many watchpoints are already used from the memory bank. For example, if a core uses all eight watchpoints from its four adjacent memory banks, the other cores which share those four memory banks cannot use watchpoints from the shared memory banks. Debugger keeps track of watchpoints that are allocated from each bank, and throws an error if there are no unused watchpoints in that tile.

  1. To add watch point in the Vitis IDE, locate the WATCH window in the bottom left side. Hover your mouse on that window and click on the Add Expression (+) command as highlighted below.
  2. You can enter the memory address or the variable name of interest. You can observe that the values in the watchpoints may appear as "not available", if you select a core other than the core for which the watch point is created. For example, if you created watch points by selecting the core in the debug view, the updated values are seen only for that particular core. For rest all other cores, the watch point values may appear as "not available."

  3. You can edit, copy and remove one or all watch points by right-clicking on any watch point.

Triggering of Watchpoints

A watchpoint is triggered on a read access or write access, or both, based on how the watchpoint is configured. A triggered watchpoint causes the core to stop at the instruction that accessed the address. Debugger detects the core has stopped because of the watchpoint and reports that the core has stopped because of a watchpoint.

  • Watchpoints work on hardware only. AI Engine system C model is not supported.
  • Memory banks are shared. It might not be possible to add watchpoints for a core in a specific bank, if another core uses both the watchpoints from that bank.
  • Watchpoints must not be set for memory addresses which fall in unused tiles/memory banks. Setting watchpoints to unused tiles can cause AXI errors. Used AI Engine and memory tiles can be found at Work/aie/active_cores.json.
  • Watchpoints are triggered for memory access in full 16-byte aligned address range.
  • Debugger uses two broadcast channels to handle watchpoint events. When enabling watchpoints during debug, ensure that there are no conflicts in using these two broadcast channels.