xsct/xsdb are software command-line tools of Xilinx Vivado/Vitis (there seems no difference in functionalities). As with other AMD tools, the scripting language for XSCT is based on the tools command language (Tcl). You can run XSCT commands interactively or script the commands for automation.
XSCT Commands - Xilinx Documentation
Notation: Commands led by $
runs in the terminal, while those led by xsct%
runs in xsct/xsdb. Lines starts with #
are comments.
Step 0. Launch xsct/xsdb
xsct/xsdb are bundled with Xilinx Vivado/Vitis. On a machine with these tools install (e.g. enzian-build/enzian-server), run the following commands:
$ source /opt/Xilinx/Vivado/2022.1/settings64.sh
$ DISPLAY=dummy xsdb
$ source /opt/Xilinx/Vitis/2022.1/settings64.sh
$ xsct
Step 1. Connect to hardware server
xsct/xsdb works as the frontend. It needs to connect to a hardware server to get access to devices.
# For machines/boards in the lab
xsct% connect -url TCP:enzian-server.ethz.ch:3121
# For machines in the cluster
xsct% connect -url TCP:enzian-gateway.ethz.ch:3121
For debugging purpose, add -symbols
option. It starts the symbol server so that addresses can be mapped to source files once symbols are loaded.
Step 2. Select a target
xsct/xsdb operates on a selected target.
List all targets
xsct% targets
1 PS TAP
2 PMU
3 PL
4 Legacy Debug Hub
5 PSU
6 RPU
7 Cortex-R5 #0 (No Power)
8 Cortex-R5 #1 (No Power)
9 APU
10 Cortex-A53 #0 (Running)
11 Cortex-A53 #1 (Reset)
12 Cortex-A53 #2 (Reset)
13 Cortex-A53 #3 (Reset)
As we can see, targets are in hierarchy.
Select a target by index
xsct% target 9
# Run targets again and you will see '*' beside target 9
Select a target by filtering
xsct/xsdb supports setting targets based on filtering. This is good for automation.
# == means exact match. Similarly, !=, <=, >=, <, > are supported.
xsct% targets -set -filter {name == "PSU"}
# =~ means pattern match. Simiarly, !~ is supported
xsct% targets -set -filter {target_ctx =~ "*210357A7CB97A*"}
# && and || are supported
xsct% targets -set -filter {jtag_cable_serial == "210357A7CB97A" && name == "PSU"}
If more than one targets match the filter, xsdb complains about it.
How to get those values of existing devices. When listing targets, the targets
command do not show all the information. Run the following commands instead:
# Get a full list of (human-unreadable) information
xsct% targets -target-properties
# Filtering is also supported there
xsct% targets -target-properties -filter {target_id == 10}
Step 3. Use xsdb/xsct
xsdb/xsct use the same Tcl language as Vivado/Vitas. It’s also possible to write commands in a file and execute it with xsdb/xsct from the shell directly.
Execute a Tcl script that contains commands
Inside xsct/xsdb:
xsct% source some_script.tcl
Or outside xsct/xsdb:
$ xsct some_script.tcl [args]
For example, the following tcl script targets a specific JTAG and loads a bitstream onto that FPGA, then target to the Microblaze core on that FPGA and load ELF to its local memory.
For the time writing: the target zuestoll 04 is on enzian-server so runing this on enzian build will result in something like "cannot find target XXXX"
(Do Not Execute Directly)
Control the execution
rst # reset
con # continue
stp/nxt # step/next
stpi/nxti # step/next instruction
Load Symbols
memmap -file /some/elf/file
Breakpoints
bpadd <addr>/<func>/<line>
bpremove <num>/-all
bplist
bpenable/bpdisable
Printing
print <var>
locals
rrd # print registers
bt