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


bpadd <addr>/<func>/<line>
bpremove <num>/-all


print <var>
rrd  # print registers

  • No labels