XSCT Commands

The Xilinx® Software Command-Line tool allows you to create complete Vitis workspaces, investigate the hardware and software, debug and run the project, all from the command line.

XSCT commands are broadly classified into the following categories. The commands in each category are described subsequently.

TIP:
  • Help for each of the commands can be viewed by running help <command> or <command> -help in the XSCT console. All the available XSCT commands can be listed by running help commands.
  • You can use Ctrl+C to terminate long running commands like fpga or elf download or for/while loops.
  • You can terminate XSCT by pressing Ctrl+C twice in succession.
  • Windows style paths are supported when the path is enclosed within curly brackets {}.

Target Connection Management

The following is a list of connections commands:

connect

Connect to the hw_server/TCF agent.

Syntax

connect [options]

Allows users to connect to a server, list connections or switch between connections.

Options

Option Description
-host <host name/ip> Name/IP address of the host machine
-port <port num> TCP port number
-url <url> URL description of the hw_server/TCF agent
-list List open connections
-set <channel-id> Set active connection
-new Create a new connection, even one exist to the same url
-xvc-url <url> Open Xilinx Virtual Cable connection
-symbols Launch symbol server to enable source level debugging for remote connections

Returns

The return value depends on the options used.

-port, -host, -url, -new: <channel-id> of the new connection or error if the connection fails

-list: list of open channels or nothing when there are no open channels

-set: nothing

Example(s)

connect -host localhost -port 3121

Connect to the hw_server/TCF agent on host localhost and port 3121.

connect -url tcp:localhost:3121

Identical to previous example.

disconnect

Disconnect from the hw_server/TCF agent.

Syntax

disconnect

Disconnect from active channel.

disconnect <channel-id>

Disconnect from specified channel.

Returns

Nothing, if the connection is closed. Error string, if invalid channel-id is specified.

targets

List targets or switch between targets.

Syntax

targets [options]

List available targets.

targets <target id>

Select <target id> as active target.

Options

Option Description
-set Set current target to entry single entry in list. This is useful in comibination with -filter option. An error will be generate if list is empty or contains more than one entry.
-regexp Use regexp for filter matching
-nocase Use case insensitive filter matching
-filter <filter-expression> Specify filter expression to control which targets are included in list based on its properties. Filter expressions are similar to Tcl expr syntax. Target properties are references by name, while Tcl variables are accessed using the $ syntax, string must be quoted. Operators ==, !=, <=, >=, <, >, && and || are supported as well as (). There operators behave like Tcl expr operators. String matching operator =~ and !~ match lhs string with rhs pattern using either regexp or string match.
-target-properties Returns a Tcl list of dict's containing target properties.
-index <index> Include targets based on jtag scan chain position. This is identical to specifying -filter {jtag_device_index==<index>}.
-timeout <sec> Poll until the targets specified by filter option are found on the scan chain, or until timeout. This option is valid only with filter option. The timeout value is in seconds. Default timeout is 3 seconds

Returns

The return value depends on the options used.

<none>: Targets list when no options are used.

-filter: Filtered targets list.

-target-properties: Tcl list consisting of target properties.

An error is returned when target selection fails.

Example(s)

targets

List all targets.

targets -filter {name =~ "ARM*#1"}

List targets with name starting with "ARM" and ending with "#1".

targets 2

Set target with id 2 as the current target.

targets -set -filter {name =~ "ARM*#1"}

Set current target to target with name starting with "ARM" and ending with "#1".

targets -set -filter {name =~ "MicroBlaze*"} -index 0

Set current target to target with name starting with "MicroBlaze" and which is on 1st Jtag Device.

gdbremote connect

Connect to GDB remote server.

Syntax

gdbremote connect [options] server

Connect to a GDB remote server, for example qemu. A special client named tcfgdbclient is used to connect to remote GDB server.

Options

Option Description
-architecture <name> Specify default architecture is remote server does not provide it.

Returns

Nothing, if the connection is successful. Error string, if the connection failed.

gdbremote disconnect

Disconnect from GDB remote server.

Syntax

gdbremote disconnect [target-id]

Disconnect from GDB remote server, for example qemu.

Returns

Nothing, if the connection is close. Error string, if there is no active connection.

Target Registers

The following is a list of registers commands:

rrd

Read register for active target.

Syntax

rrd [options] [reg]

Read registers or register definitions. For a processor core target, processor core register can be read. For a target representing a group of processor cores, system registers or IOU registers can be read.

Options

Option Description
-defs Read register definitions instead of values
-no-bits Does not show bit fields along with register values. By default, bit fields are shown, when available

Returns

Register names and values, or register definitions if successful. Error string, if the registers cannot be read or if an invalid register is specified.

Example(s)

rrd

Read top level registers or groups.

rrd r0

Read register r0.

rrd usr r8

Read register r8 in group usr.

rwr

Write to register

Syntax

rwr <reg> <value>

Write the <value> to active target register specified by <reg> For a processor core target, processor core register can be written to. For a target representing a group of processor cores, system registers or IOU registers can be written.

Returns

Nothing, if successful. Error string, if an invalid register is specified or the register cannot be written.

Example(s)

rwr r8 0x0

Write 0x0 to register r8.

rwr usr r8 0x0

Write 0x0 to register r8 in group usr.

Program Execution

The following is a list of running commands:

state

Display the current state of the target.

Syntax

state

Return the current execution state of target.

stop

Stop active target.

Syntax

stop

Suspend execution of active target.

Returns

Nothing, if the target is suspended. Error string, if the target is already stopped or cannot be stopped.

An information message is printed on the console when the target is suspended.

con

Resume active target.

Syntax

con [options]

Resume execution of active target.

Options

Option Description
-addr <address> Resume execution from address specified by <address>
-block Block until the target stops or a timeout is reached
-timeout <sec> Timeout value in seconds

Returns

Nothing, if the target is resumed. Error string, if the target is already running or cannot be resumed or does not halt within timeout, after being resumed.

An information message is printed on the console when the target is resumed.

Example(s)

con -addr 0x100000

Resume execution of the active target from address 0x100000.

con -block

Resume execution of the active target and wait until the target stops.

con -block -timeout 5

Resume execution of the active target and wait until the target stops or until the 5 sec timeout is reached.

stp

Step into a line of source code.

Syntax

stp [count]

Resume execution of the active target until control reaches instruction that belongs to different line of source code. If a function is called, stop at first line of the function code. Error is returned if line number information not available. If <count> is greater than 1, repeat <count> times. Default value of count is 1.

Returns

Nothing, if the target has single stepped. Error string, if the target is already running or cannot be resumed.

An information message is printed on the console when the target stops at the next address.

nxt

Step over a line of source code.

Syntax

nxt [count]

Resume execution of the active target until control reaches instruction that belongs to a different line of source code, but runs any functions called at full speed. Error is returned if line number information not available. If <count> is greater than 1, repeat <count> times. Default value of count is 1.

Returns

Nothing, if the target has stepped to the next source line. Error string, if the target is already running or cannot be resumed.

An information message is printed on the console when the target stops at the next address.

stpi

Execute a machine instruction.

Syntax

stpi [count]

Execute a single machine instruction. If instruction is function call, stop at first instruction of the function code If <count> is greater than 1, repeat <count> times. Default value of count is 1.

Returns

Nothing, if the target has single stepped. Error if the target is already running or cannot be resumed.

An information message is printed on the console when the target stops at the next address.

nxti

Step over a machine instruction.

Syntax

nxti [count]

Step over a single machine instruction. If instruction is function call, execution continues until control returns from the function. If <count> is greater than 1, repeat <count> times. Default value of count is 1.

Returns

Nothing, if the target has stepped to the next address. Error string, if the target is already running or cannot be resumed.

An information message is printed on the console when the target stops at the next address.

stpout

Step out from current function.

Syntax

stpout [count]

Resume execution of current target until control returns from current function. If <count> is greater than 1, repeat <count> times. Default value of count is 1.

Returns

Nothing, if the target has stepped out of the current function. Error if the target is already running or cannot be resumed.

An information message is printed on the console when the target stops at the next address.

dis

Disassemble Instructions.

Syntax

dis <address> [num]

Disassemble <num> instructions at address specified by <address>. The keyword "pc" can be used to disassemble instructions at current PC. Default value for <num> is 1.

Returns

Disassembled instructions if successful. Error string, if the target instructions cannot be read.

Example(s)

dis

Disassemble an instruction at the current PC value.

dis pc 2

Disassemble two instructions at the current PC value.

dis 0x0 2

Disassemble two instructions at address 0x0.

print

Get or set the value of an expression.

Syntax

print [options] [expression]

Get or set the value of an expression specified by <expression>. The <expression> can include constants, local/global variables, CPU registers, or any operator, but pre-processor macros defined through #define are not supported. CPU registers can be specified in the format {$r1}, where r1 is the register name. Elements of a complex data types like a structure can be accessed through '.' operator. For example, var1.int_type refers to int_type element in var1 struct. Array elements can be accessed through their indices. For example, array1[0] refers to the element at index 0 in array1.

Options

Option Description
-add <expression> Add the <expression> to auto expression list. The values or definitions of the expressions in auto expression list are displayed when expression name is not specified. Frequently used expressions should be added to the auto expression list.
-defs [expression] Return the expression definitions like address, type, size and RW flags. Not all definitions are available for all the expressions. For example, address is available only for variables and not when the expression includes an operator.
-dict [expression] Return the result in Tcl dict format, with variable names as dict keys and variable values as dict values. For complex data like structures, names are in the form of parent.child.
-remove [expression] Remove the expression from auto expression list. Only expressions previously added to the list through -add option can be removed. When the expression name is not specified, all the expressions in the auto expression list are removed.
-set <expression> Set the value of a variable. It is not possible to set the value of an expression which includes constants or operators.

Returns

The return value depends on the options used.

<none> or -add: Expression value(s)

-defs: Expression definition(s)

-remove or -set: Nothing

Error string, if expression value cannot be read or set.

Example(s)

print Int_Glob

Return the value of variable Int_Glob.

print -a Microseconds

Add the variable Microseconds to auto expression list and return its value.

print -a Int_Glob*2 + 1

Add the expression (Int_Glob*2 + 1) to auto expression list and return its value.

print tmp_var.var1.int_type

Return the value of int_type element in var1 struct, where var1 is a member of tmp_var struct.

print tmp_var.var1.array1[0]

Return the value of the element at index 0 in array array1. array1 is a member of var1 struct, which is in turn a member of tmp_var struct.

print

Return the values of all the expressions in auto expression list.

print -defs

Return the definitions of all the expressions in auto expression list.

print -set Int_Glob 23

Set the value of the variable Int_Glob to 23.

print -remove Microseconds

Remove the expression Microseconds from auto expression list.

print {r1}

Return the value of CPU register r1.

locals

Get or set the value of a local variable.

Syntax

locals [options] [variable-name [variable-value]]

Get or set the value of a variable specified by <variable-name>. When variable name and value are not specified, values of all the local variables are returned. Elements of a complex data types like a structure can be accessed through '.' operator. For example, var1.int_type refers to int_type element in var1 struct. Array elements can be accessed through their indices. For example, array1[0] refers to the element at index 0 in array1.

Options

Option Description
-defs Return the variable definitions like address, type, size and RW flags.
-dict [expression] Return the result in Tcl dict format, with variable names as dict keys and variable values as dict values. For complex data like structures, names are in the form of parent.child.

Returns

The return value depends on the options used.

<none>: Variable value(s)

-defs: Variable definition(s)

Nothing, when variable value is set. Error string, if variable value cannot be read or set.

Example(s)

locals Int_Loc

Return the value of the local variable Int_Loc.

locals

Return the values of all the local variables in the current stack frame.

locals -defs

Return definitions of all the local variables in the current stack frame.

locals Int_Loc 23

Set the value of the local variable Int_Loc to 23.

locals tmp_var.var1.int_type

Return the value of int_type element in var1 struct, where var1 is a member of tmp_var struct.

locals tmp_var.var1.array1[0]

Return the value of the element at index 0 in array array1. array1 is a member of var1 struct, which is in turn a member of tmp_var struct.

backtrace

Stack back trace.

Syntax

backtrace

Return stack trace for current target. Target must be stopped. Use debug information for best result.

Returns

Stack Trace, if successful. Error string, if Stack Trace cannot be read from the target.

profile

Configure and run the GNU profiler.

Syntax

profile [options]

Configure and run the GNU profiler. The profiling needs to enabled while building bsp and application to be profiled.

Options

Option Description
-freq <sampling-freq> Sampling frequency.
-scratchaddr <addr> Scratch memory for storing the profiling related data. It needs to be assigned carefully, as it should not overlap with the program sections.
-out <file-name> Name of the output file for writing the profiling data. This option also runs the profiler and collects the data. If file name is not specified, profiling data is written to gmon.out.

Returns

Depends on options used.

-scratchaddr, -freq: Returns nothing on successful configuration. Error string, in case of error.

-out: Returns nothing, and generates a file. Error string, in case of error.

Example(s)

profile -freq 10000 -scratchaddr 0

Configure the profiler with a sampling frequency of 10000 and scratch memory at 0x0.

profile -out testgmon.out

Output the profile data in testgmon.out.

mbprofile

Configure and run the MB profiler.

Syntax

mbprofile [options]

Configure and run the MB profiler, a non-intrusive profiler for profiling the application running on MB. The output file is generated in gmon.out format. The results can be viewed using gprof editor. In case of cycle count, an annotated disassembly file is also generated clearly marking time taken for execution of instructions.

Options

Option Description
-low <addr> Low address of the profiling address range.
-high <addr> High address of the profiling address range.
-freq <value> Microblaze clock frequency in Hz. Default is 100MHz.
-count-instr Count no. of executed instructions. By default no. of clock cycles of executed instructions are counted.
-cumulate Cumulative profiling. Profiling without clearing the profiling buffers.
-start Enable and start profiling.
-stop Disable/stop profiling.
-out <filename> Output profiling data to file. <filename> Name of the output file for writing the profiling data. If file name is not specified, profiling data is written to gmon.out.

Returns

Depends on options used. -low, -high, -freq, -count-instr, -start, -cumulate Returns nothing on successful configuration. Error string, in case of error.

-stop: Returns nothing, and generates a file. Error string, in case of error.

Example(s)

mbprofile -low 0x0 -high 0x3FFF

Configure the mb-profiler with address range 0x0 to 0x3FFF for profiling to count the clock cycles of executed instructions.

mbprofile -start

Enable and start profiling.

mbprofile -stop -out testgmon.out

Output the profile data in testgmon.out.

mbprofile -count-instr

Configure the mb-profiler to profile for entire program address range to count no. of instructions executed.

mbtrace

Configure and run MB trace.

Syntax

mbtrace [options]

Configure and run MB program and event trace for tracing the application running on MB. The output is the disassembly of the executed program.

Options

Option Description
-start Enable and start trace. After starting trace the execution of the program is captured for later output.
-stop Stop and output trace.
-con Execute the command and output trace.
Note: The -con option is only available with embedded trace.
-stp
-nxt
-out <filename> Output trace data to a file. <filename> Name of the output file for writing the trace data. If not specified, data is output to standard output.
-level <level> Set the trace level to "full", "flow", "event", or "cycles". If not specified, "flow" is used.
-halt Set to halt program execution when the trace buffer is full. If not specified, trace is stopped but program execution continues.
-save Set to enable capture of load and get instruction new data value.
-low <addr> Set low and high address of the external trace buffer address range. The address range must indicate an unused accessible memory space. Only used with external trace.
-high <addr>
-format <format> Set external trace data format to "mdm", "ftm", or "tpiu". If format is not specified, "mdm" is used. The "ftm" and "tpiu" formats are output by Zynq-7000 PS. Only used with external trace.

Returns

Depends on options used. -start, -out, -level, -halt -save, -low, -high, -format Returns nothing on successful configuration. Error string, in case of error.

-stop, -con, -stp, -nxt: Returns nothing, and outputs trace data to a file or standard output. Error string, in case of error.

Example(s)

mbtrace -start

Enable and start trace.

mbtrace -start -level full -halt

Enable and start trace, configuring to save complete trace instead of only program flow and to halt execution when trace buffer is full.

mbtrace -stop

Stop trace and output data to standard output.

mbtrace -stop -out trace.out

Stop trace and output data to trace.out.

mbtrace -con -out trace.out

Continue execution and output data to trace.out.

Target Memory

The following is a list of memory commands:

mrd

Memory Read

Syntax

mrd [options] <address> [num]

Read <num> data values from the active target's memory address specified by <address>.

Options

Option Description
-force Overwrite access protection. By default accesses to reserved and invalid address ranges are blocked.
-size <access-size> <access-size> can be one of the values below: b = Bytes accesses h = Half-word accesses w = Word accesses d = Double-word accesses Default access size is w Address will be aligned to access-size before reading memory, if '-unaligned-access' option is not used. For targets which do not support double-word access, debugger uses 2 word accesses. If number of data values to be read is more than 1, then debugger selects appropriate access size. For example, 1. mrd -size b 0x0 4 Debugger accesses one word from the memory, displays 4 bytes. 2. mrd -size b 0x0 3 Debugger accesses one half-word and one byte from the memory, displays 3 bytes. 3. mrd 0x0 3 Debugger accesses 3 words from the memory and displays 3 words.
-value Return a Tcl list of values, instead of displaying the result on console.
-bin Return data read from the target in binary format.
-file <file-name> Write binary data read from the target to <file-name>.
-address-space <name> Access specified memory space instead default memory space of current target. For ARM DAP targets, address spaces DPR, APR and AP<n> can be used to access DP Registers, AP Registers and MEM-AP addresses, respectively. For backwards compatibility -arm-dap and -arm-ap options can be used as shorthand for "-address-space APR" and "-address-space AP<n>", respectively. The APR address range is 0x0 - 0xfffc, where the higher 8 bits select an AP and lower 8 bits are the register address for that AP.
-unaligned-access Memory address is not aligned to access size, before performing a read operation. Support for unaligned accesses is target architecture dependent. If this option is not specified, addresses are automatically aligned to access size.

Note(s)

  • Select a APU target to access ARM DAP and MEM-AP address space.

Returns

Memory addresses and data in requested format, if successful. Error string, if the target memory cannot be read.

Example(s)

mrd 0x0

Read a word at 0x0.

mrd 0x0 10

Read 10 words at 0x0.

mrd -value 0x0 10

Read 10 words at 0x0 and return a Tcl list of values.

mrd -size b 0x1 3

Read 3 bytes at address 0x1.

mrd -size h 0x2 2

Read 2 half-words at address 0x2.

mrd -bin -file mem.bin 0 100

Read 100 words at address 0x0 and write the binary data to mem.bin.

mrd -address-space APR 0x100

Read APB-AP CSW on Zynq. The higher 8 bits (0x1) select the APB-AP and lower 8 bits (0x0) is the address of CSW.

mrd -address-space APR 0x04

Read AHB-AP TAR on Zynq. The higher 8 bits (0x0) select the AHB-AP and lower 8 bits (0x4) is the address of TAR.

mrd -address-space AP1 0x80090088

Read address 0x80090088 on DAP APB-AP. 0x80090088 corresponds to DBGDSCR register of Cortex-A9#0, on Zynq AP 1 selects the APB-AP.

mrd -address-space AP0 0xe000d000

Read address 0xe000d000 on DAP AHB-AP. 0xe000d000 corresponds to QSPI device on Zynq AP 0 selects the AHB-AP.

mwr

Memory Write.

Syntax

mwr [options] <address> <values> [num]

Write <num> data values from list of <values> to active target memory address specified by <address>. If <num> is not specified, all the <values> from the list are written sequentially from the address specifed by <address> If <num> is greater than the size of the <values> list, the last word in the list is filled at the remaining address locations.

mwr [options] -bin -file <file-name> <address> [num]

Read <num> data values from a binary file and write to active target memory address specified by <address>. If <num> is not specified, all the data from the file is written sequentially from the address specifed by <address>.

Options

Option Description
-force Overwrite access protection. By default accesses to reserved and invalid address ranges are blocked.
-bypass-cache-sync Do not flush/invalidate CPU caches during memory write. Without this option, debugger flushes/invalidates caches to make sure caches are in sync.
-size <access-size> <access-size> can be one of the values below: b = Bytes accesses h = Half-word accesses w = Word accesses d = Double-word accesses Default access size is w. Address will be aligned to accesss-size before writing to memory, if '-unaligned-access' option is not used. If target does not support double-word access, the debugger uses 2 word accesses. If number of data values to be written is more than 1, then debugger selects appropriate access size. For example, 1. mwr -size b 0x0 {0x0 0x13 0x45 0x56} Debugger writes one word to the memory, combining 4 bytes. 2. mwr -size b 0x0 {0x0 0x13 0x45} Debugger writes one half-word and one byte to the memory, combining the 3 bytes. 3. mwr 0x0 {0x0 0x13 0x45} Debugger writes 3 words to the memory.
-bin Read binary data from a file and write it to target address space.
-file <file-name> File from which binary data is read to write to target address space.
-address-space <name> Access specified memory space instead default memory space of current target. For ARM DAP targets, address spaces DPR, APR and AP<n> can be used to access DP Registers, AP Registers and MEM-AP addresses, respectively. For backwards compatibility -arm-dap and -arm-ap options can be used as shorthand for "-address-space APR" and "-address-space AP<n>", respectively. The APR address range is 0x0 - 0xfffc, where the higher 8 bits select an AP and lower 8 bits are the register address for that AP.
-unaligned-accesses Memory address is not aligned to access size, before performing a write operation. Support for unaligned accesses is target architecture dependent. If this option is not specified, addresses are automatically aligned to access size.

Note(s)

  • Select a APU target to access ARM DAP and MEM-AP address space.

Returns

Nothing, if successful. Error string, if the target memory cannot be written.

Example(s)

mwr 0x0 0x1234

Write 0x1234 to address 0x0.

mwr 0x0 {0x12 0x23 0x34 0x45}

Write 4 words from the list of values to address 0x0.

mwr 0x0 {0x12 0x23 0x34 0x45} 10

Write 4 words from the list of values to address 0x0 and fill the last word from the list at remaining 6 address locations.

mwr -size b 0x1 {0x1 0x2 0x3} 3

write 3 bytes from the list at address 0x1.

mwr -size h 0x2 {0x1234 0x5678} 2

write 2 half-words from the list at address 0x2.

mwr -bin -file mem.bin 0 100

Read 100 words from binary file mem.bin and write the data at target address 0x0.

mwr -arm-dap 0x100 0x80000042

Write 0x80000042 to APB-AP CSW on Zynq The higher 8 bits (0x1) select the APB-AP and lower 8 bits (0x0) is the address of CSW.

mwr -arm-dap 0x04 0xf8000120

Write 0xf8000120 to AHB-AP TAR on Zynq The higher 8 bits (0x0) select the AHB-AP and lower 8 bits (0x4) is the address of TAR.

mwr -arm-ap 1 0x80090088 0x03186003

Write 0x03186003 to address 0x80090088 on DAP APB-AP 0x80090088 corresponds to DBGDSCR register of Cortex-A9#0, on Zynq AP 1 selects the APB-AP.

mwr -arm-ap 0 0xe000d000 0x80020001

Write 0x80020001 to address 0xe000d000 on DAP AHB-AP 0xe000d000 corresponds to QSPI device on Zynq AP 0 selects the AHB-AP.

osa

Configure OS awareness for a symbol file.

Syntax

osa -file <file-name> [options]

Configure OS awareness for the symbol file <file-name> specified. If no symbol file is specifed and only one symbol file exists in target's memory map, then that symbol file is used. If no symbol file is specifed and multiple symbol files exist in target's memory map, then an error is thrown.

Options

Option Description
-disable Disable OS awareness for a symbol file. If this option is not specified, OS awareness is enabled.
-fast-exec Enable fast process start. New processes will not be tracked for debug and are not visible in the debug targets view.
-fast-step Enable fast stepping. Only the current process will be re-synced after stepping. All other processes will not be re-synced when this flag is turned on.

Note(s)

  • fast-exec and fast-step options are not valid with disable option.

Returns

Nothing, if OSA is configured successfully. Error, if ambiguous options are specified.

Example(s)

osa -file <symbol-file> -fast-step -fast-exec

Enable OSA for <symbole-file> and turn on fast-exec and fast-step modes.

osa -disable -file <symbol-file>

Disable OSA for <symbol-file>.

memmap

Modify Memory Map.

Syntax

memmap <options>

Add/remove a memory map entry for the active target.

Options

Option Description
-addr <memory-address> Address of the memory region that should be added/removed from the target's memory map.
-size <memory-size> Size of the memory region.
-flags <protection-flags> Protection flags for the memory region. <protection-flags> can be a bitwise OR of the values below: 0x1 = Read access is allowed 0x2 = Write access is allowed 0x4 = Instruction fetch access is allowed Default value of <protection-flags> is 0x3 (Read/Write Access).
-list List the memory regions added to the active target's memory map.
-clear Specify whether the memory region should be removed from the target's memory map.
-relocate-section-map <addr> Relocate the address map of the program sections to <addr>. This option should be used when the code is self-relocating, so that the debugger can find the debug symbol info for the code. <addr> is the relative address, to which all the program sections are relocated.
-osa Enable OS awareness for the symbol file. Fast process start and fast stepping options are turned off by default. These options can be enabled using the osa command. See "help osa" for more details.
-properties <dict> Specify advanced memory map properties.
-meta-data <dict> Specify meta-data of advanced memory map properties.

Note(s)

  • Only the memory regions previously added through memmap command can be removed.

Returns

Nothing, while setting the memory map, or list of memory maps when -list option is used.

Example(s)

memmap -addr 0xfc000000 -size 0x1000 -flags 3

Add the memory region 0xfc000000 - 0xfc000fff to target's memory map Read/Write accesses are allowed to this region.

memmap -addr 0xfc000000 -clear

Remove the previously added memory region at 0xfc000000 from target's memory map.

Target Download FPGA/BINARY

The following is a list of download commands:

dow

Download ELF and binary file to target.

Syntax

dow [options] <file>

Download ELF file <file> to active target.

dow -data <file> <addr>

Download binary file <file> to active target address specified by <addr>.

Options

Option Description
-clear Clear uninitialized data (bss).
-keepsym Keep previously downloaded elfs in the list of symbol files. Default behavior is to clear the old symbol files while downloading an elf.
-force Overwrite access protection. By default accesses to reserved and invalid address ranges are blocked.
-bypass-cache-sync Do not flush/invalidate CPU caches during elf download. Without this option, debugger flushes/invalidates caches to make sure caches are in sync.
-relocate-section-map <addr> Relocate the address map of the program sections to <addr>. This option should be used when the code is self-relocating, so that the debugger can find debug symbol info for the code. <addr> is the relative address, to which all the program sections are relocated.
-vaddr Use vaddr from the elf program headers while downloading the elf. This option is valid only for elf files.

Returns

Nothing.

verify

Verify if ELF/binary file is downloaded correctly to target.

Syntax

verify [options] <file>

Verify if the ELF file <file> is downloaded correctly to active target.

verify -data <file> <addr>

Verify if the binary file <file> is downloaded correctly to active target address specified by <addr>.

Options

Option Description
-force Overwrite access protection. By default accesses to reserved and invalid address ranges are blocked.
-vaddr Use vaddr from the elf program headers while verifying the elf data. This option is valid only for elf files.

Returns

Nothing, if successful. Error string, if the memory address cannot be accessed or if there is a mismatch.

fpga

Configure FPGA.

Syntax

fpga <bitstream-file>

Configure FPGA with given bitstream.

fpga [options]

Configure FPGA with bitstream specified options, or read FPGA state.

Options

Option Description
-file <bitstream-file> Specify file containing bitstream.
-partial Configure FPGA without first clearing current configuration. This options should be used while configuring partial bitstreams created before 2014.3 or any partial bitstreams in binary format.
-no-revision-check Disable bitstream vs silicon revision revision compatibility check.
-skip-compatibility-check Disable bitstream vs FPGA device compatibility check.
-state Return whether the FPGA is configured.
-config-status Return configuration status.
-ir-status Return IR capture status.
-boot-status Return boot history status.
-timer-status Return watchdog timer status.
-cor0-status Return configuration option 0 status.
-cor1-status Return configuration option 1 status.
-wbstar-status Return warm boot start address status.

Note(s)

  • If no target is selected or if the current target is not a supported FPGA device, and only one supported FPGA device is found in the targets list, then this device will be configured.

Returns

Depends on options used.

-file, -partial: Nothing, if fpga is configured, or an error if the configuration failed.

One of the other options Configutation value.

Target Reset

The following is a list of reset commands:

rst

Target Reset.

Syntax

rst [options]

Reset the active target.

Options

Option Description
-processor Reset the active processor target.
-cores Reset the active processor group. This reset type is supported only on Zynq. A processor group is defined as a set of processors and on-chip peripherals like OCM.
-system Reset the active System.
-srst Generate system reset for active target. With JTAG this is done by generating a pulse on the SRST pin on the JTAG cable assocated with the active target.
-por Generate power on reset for active target. With JTAG this is done by generating a pulse on the POR pin on the JTAG cable assocated with the active target.
-ps Generate PS only reset on Zynq MP. This is supported only through MicroBlaze PMU target.

Returns

Nothing, if reset if successful. Error string, if reset is unsupported.

Target Breakpoints/Watchpoints

The following is a list of breakpoints commands:

bpadd

Set a Breakpoint/Watchpoint.

Syntax

bpadd <options>

Set a software or hardware breakpoint at address, function or <file>:<line>, or set a read/write watchpoint, or set a cross-trigger breakpoint.

Options

Option Description
-addr <breakpoint-address> Specify the address at which the Breakpoint should be set.
-file <file-name> Specify the <file-name> in which the Breakpoint should be set.
-line <line-number> Specify the <line-number> within the file, where Breakpoint should be set.
-type <breakpoint-type> Specify the Breakpoint type <breakpoint-type> can be one of the values below: auto = Auto - Breakpoint type is chosen by the hw_server/TCF agent. This is the default type hw = Hardware Breakpoint sw = Software Breakpoint
-mode <breakpoint-mode> Specify the access mode that will trigger the breakpoint. <breakpoint-mode> can be a bitwise OR of the values below: 0x1 = Triggered by a read from the breakpoint location 0x2 = Triggered by a write to the breakpoint location 0x4 = Triggered by an instruction execution at the breakpoint location This is the default for Line and Address breakpoints 0x8 = Triggered by a data change (not an explicit write) at the breakpoint location
-enable <mode> Specify initial enablement state of breakpoint. When <mode> is 0 the breakpoint is disabled, otherwise the breakpoint is enabled. The default is enabled.
-ct-input <list> -ct-output <list> Specify input and output cross triggers. <list> is a list of numbers identifying the cross trigger pin. For Zynq 0-7 is CTI for core 0, 8-15 is CTI for core 1, 16-23 is CTI ETB and TPIU, and 24-31 is CTI for FTM.
-skip-on-step <value> Specify the trigger behaviour on stepping. This option is only applicable for cross trigger breakpoints and when DBGACK is used as breakpoint input. 0 = trigger every time core is stopped (default). 1 = supress trigger on stepping over a code breakpoint. 2 = supress trigger on any kind of stepping.
-properties <dict> Specify advanced breakpoint properties.
-meta-data <dict> Specify meta-data of advanced breakpoint properties.
-target-id <id> Specify a target id for which the breakpoint should be set. A breakpoint can be set for all the targets by specifying the <id> as "all". If this option is not used, then the breakpoint is set for the active target selected through targets command. If there is no active target, then the breakpoint is set for all targets.

Note(s)

  • Breakpoints can be set in XSDB before connecting to the hw_server/TCF agent. If there is an active target when a Breakpoint is set, the Breakpoint will be enabled only for that active target. If there is no active target, the Breakpoint will be enabled for all the targets. target-id option can be used to set a breakpoint for a specific target, or all targets. An address breakpoint or a file:line breakpoint can also be set without the options -addr, -file or -line. For address breakpoints, specify the address as an argument, after all other options. For file:line breakpoints, specify the file name and line number in the format <file>:<line>, as an argument, after all other options.

Returns

Breakpoint id or an error if invalid target id is specified.

Example(s)

bpadd -addr 0x100000

Set a Breakpoint at address 0x100000. Breakpoint type is chosen by the hw_server/TCF agent.

bpadd -addr &main

Set a function Breakpoint at main. Breakpoint type is chosen by the hw_server/TCF agent.

bpadd -file test.c -line 23 -type hw

Set a Hardware Breakpoint at test.c:23.

bpadd -target-id all 0x100

Set a breakpoint for all targets, at address 0x100.

bpadd -target-id 2 test.c:23

Set a breakpoint for target 2, at line 23 in test.c.

bpadd -addr &fooVar -type hw -mode 0x3

Set a Read_Write Watchpoint on variable fooVar.

bpadd -ct-input 0 -ct-output 8

Set a cross trigger to stop Zynq core 1 when core 0 stops.

bpremove

Remove Breakpoints/Watchpoints.

Syntax

bpremove <id-list> | -all

Remove the Breakpoints/Watchpoints specified by <id-list> or remove all the breakpoints when \"-all\" option is used.

Options

Option Description
-all Remove all breakpoints.

Returns

Nothing, if the breakpoint is removed successfully. Error string, if the breakpoint specified by <id> is not set.

Example(s)

bpremove 0

Remove Breakpoint 0.

bpremove 1 2

Remove Breakpoints 1 and 2.

bpremove -all

Remove all Breakpoints.

bpenable

Enable Breakpoints/Watchpoints.

Syntax

bpenable <id-list> | -all

Enable the Breakpoints/Watchpoints specified by <id-list> or enable all the breakpoints when \"-all\" option is used.

Options

Option Description
-all Enable all breakpoints.

Returns

Nothing, if the breakpoint is enabled successfully. Error string, if the breakpoint specified by <id> is not set.

Example(s)

bpenable 0

Enable Breakpoint 0.

bpenable 1 2

Enable Breakpoints 1 and 2.

bpenable -all

Enable all Breakpoints.

bpdisable

Disable Breakpoints/Watchpoints.

Syntax

bpdisable <id-list> | -all

Disable the Breakpoints/Watchpoints specified by <id-list> or disable all the breakpoints when \"-all\" option is used.

Options

Option Description
-all Disable all breakpoints.

Returns

Nothing, if the breakpoint is disabled successfully. Error string, if the breakpoint specified by <id> is not set.

Example(s)

bpdisable 0

Disable Breakpoint 0.

bpdisable 1 2

Disable Breakpoints 1 and 2.

bpdisable -all

Disable all Breakpoints.

bplist

List Breakpoints/Watchpoints.

Syntax

bplist

List all the Beakpoints/Watchpoints along with brief status for each Breakpoint and the target on which it is set.

Returns

List of breakpoints.

bpstatus

Print Breakpoint/Watchpoint status.

Syntax

bpstatus <id>

Print the status of a Breakpoint/Watchpoint specified by <id>. Status includes the target information for which the Breakpoint is active and also Breakpoint hitcount or error message.

Options

None

Returns

Breakpoint status, if the breakpoint exists. Error string, if the breakpoint specified by <id> is not set.

JTAG UART

The following is a list of streams commands:

jtagterminal

Start/Stop Jtag based hyper-terminal.

Syntax

jtagterminal [options]

Start/Stop a Jtag based hyper-terminal to communicate with ARM DCC or MDM UART interface.

Options

Option Description
-start Start the Jtag Uart terminal. This is the default option.
-stop Stop the Jtag Uart terminal.
-socket Return the socket port number, instead of starting the terminal. External terminal programs can be used to connect to this port.

Note(s)

  • Select a MDM or ARM/MicroBlaze processor target before runnning this command.

Returns

Socket port number.

readjtaguart

Start/Stop reading from Jtag Uart.

Syntax

readjtaguart [options]

Start/Stop reading from the ARM DCC or MDM Uart Tx interface. Jtag Uart output can be printed on stdout or redirected to a file.

Options

Option Description
-start Start reading the Jtag Uart output.
-stop Stop reading the Jtag Uart output.
-handle <file-handle> Specify the file handle to which the data should be redirected. If no file handle is given, data is printed on stdout.

Note(s)

  • Select a MDM or ARM/MicroBlaze processor target before runnning this command.
  • While running a script in non-interactive mode, output from Jtag uart may not be written to the log, until "readjtaguart -stop" is used.

Returns

Nothing, if successful. Error string, if data cannot be read from the Jtag Uart.

Example(s)

readjtaguart

Start reading from the Jtag Uart and print the output on stdout. set fp [open test.log w]; readjtaguart -start -handle $fp Start reading from the Jtag Uart and print the output to test.log.

readjtaguart -stop

Stop reading from the Jtag Uart.

Miscellaneous

loadhw

Load a Vivado HW design.

Syntax

loadhw [options]

Load a Vivado HW design, and set the memory map for the current target. If the current target is a parent for a group of processors, memory map is set for all its child processors. If current target is a processor, memory map is set for all the child processors of it's parent. This command returns the HW design object.

Options

Option Description
-hw HW design file.
-list Return a list of open designs for the targets.
-mem-ranges [list {start1 end1} {start2 end2}] List of memory ranges from which the memory map should be set. Memory map is not set for the addresses outside these ranges. If this option is not specified, then memory map is set for all the addresses in the hardware design.

Returns

Design object, if the HW design is loaded and memory map is set successfully. Error string, if the HW design cannot be opened.

Example(s)

targets -filter {name =~ "APU"}; loadhw design.xsa Load the HW design named design.xsa and set memory map for all the child processors of APU target. targets -filter {name =~ "xc7z045"}; loadhw design.xsa Load the HW design named design.xsa and set memory map for all the child processors for which xc7z045 is the parent.

unloadhw

Unload a Vivado HW design.

Syntax

unloadhw

Close the Vivado HW design which was opened during loadhw command, and clear the memory map for the current target. If the current target is a parent for a group of processors, memory map is cleared for all its child processors. If the current target is a processor, memory map is cleared for all the child processors of it's parent. This command does not clear memory map explicitly set by users.

Returns

Nothing.

mdm_drwr

Write to MDM Debug Register.

Syntax

mdm_drwr [options] <cmd> <data> <bitlen>

Write to MDM Debug Register. cmd is 8-bit MDM command to access a Debug Register. data is the register value and bitlen is the register width.

Options

Option Description
-target-id <id> Specify a target id representing MicroBlaze Debug Module or MicroBlaze instance to access. If this option is not used and -user is not specified, then the current target is used.
-user <bscan number> Specify user bscan port number.

Returns

Nothing, if successful.

Example(s)

mdm_drwr 8 0x40 8

Write to MDM Break/Reset Control Reg.

mb_drwr

Write to MicroBlaze Debug Register.

Syntax

mb_drwr [options] <cmd> <data> <bitlen>

Write to MicroBlaze Debug Register available on MDM. cmd is 8-bit MDM command to access a Debug Register. data is the register value and bitlen is the register width.

Options

Option Description
-target-id <id> Specify a target id representing MicroBlaze instance to access. If this option is not used and -user is not specified, then the current target is used.
-user <bscan number> Specify user bscan port number.
-which <instance> Specify MicroBlaze instance number.

Returns

Nothing, if successful.

Example(s)

mb_drwr 1 0x282 10

Write to MB Control Reg.

mdm_drrd

Read from MDM Debug Register.

Syntax

mdm_drrd [options] <cmd> <bitlen>

Read a MDM Debug Register. cmd is 8-bit MDM command to access a Debug Register and bitlen is the register width. Returns hex register value.

Options

Option Description
-target-id <id> Specify a target id representing MicroBlaze Debug Module or MicroBlaze instance to access. If this option is not used and
-user is not specified, then the current target is used.
-user <bscan number> Specify user bscan port number.

Returns

Register value, if successful.

Example(s)

mdm_drrd 0 32

Read XMDC ID Reg.

mb_drrd

Read from MicroBlaze Debug Register.

Syntax

mb_drrd [options] <cmd> <bitlen>

Read a MicroBlaze Debug Register available on MDM. cmd is 8-bit MDM command to access a Debug Register. bitlen is the register width. Returns hex register value.

Options

Option Description
-target-id <id> Specify a target id representing MicroBlaze instance to access. If this option is not used and -user is not specified, then the current target is used.
-user <bscan number> Specify user bscan port number.
-which <instance> Specify MicroBlaze instance number.

Returns

Register value, if successful.

Example(s)

mb_drrd 3 28

Read MB Status Reg.

configparams

List, get or set configuration parameters.

Syntax

configparams <options>

List name and description for available configuration parameters. Configuration parameters can be global or connection specific, therefore the list of available configuration parameters and their value may change depending on current connection.

configparams <options> <name>

Get configuration parameter value(s).

configparams <options> <name> <value>

Set configuration parameter value.

Options

Option Description
-all Include values for all contexts in result.
-context [context] Specify context of value to get or set. The default context is "" which represet the global default. Not all options support context specific values.
-target-id <id> Specify target id or value to get or set. This is an alternative to the -context option.

Returns

Depends on the arguments specified.

<none>: List of parameters and description of each parameter.

<parameter name>: Parameter value or error, if unsupported parameter is specified.

<parameter name> <parameter value>: Nothing if the value is set, or error, if unsupported parameter is specified.

Example(s)

configparams force-mem-accesses 1

Disable access protection for dow, mrd, and mwr commands.

configparams vitis-launch-timeout 100

Change the Vitis launch timeout to 100 seconds, used for running Vitis batch mode commands.

version

Get Vitis or TCF server version.

Syntax

version [options]

Get Vitis or TCF server version. When no option is specified, Vitis build version is returned.

Options

Option Description
-server Get the TCF server build version, for the active connection.

Returns

Vitis or TCF Server version, on success. Error string, if server version is requested when there is no connection.

xsdbserver start

Start XSDB command server.

Syntax

xsdbserver start [options]

Start XSDB command server listener. XSDB command server allows external processes to connect to XSDB to evaluate commands. The XSDB server reads commands from the connected socket one line at the time. After evaluation, a line is sent back starting with 'okay' or 'error' followed by the result or error as a backslash quoted string.

Options

Option Description
-host <addr> Limits the network interface on which to listen for incomming connections.
-port <port> Specifies port to listen on. If this option is not specified or if the port is zero then a dynamically allocated port number is used.

Returns

Server details are disaplayed on the console if server is started. successfully, or error string, if a server has been already started.

Example(s)

xsdbserver start

Start XSDB server listener using dynamically allocated port.

xsdbserver start -host localhost -port 2000

Start XSDB server listener using port 2000 and only allow incomming connections on this host.

xsdbserver stop

Stop XSDB command server.

Syntax

xsdbserver stop

Stop XSDB command server listener and disconnect connected client if any.

Returns

Nothing, if the server is closed successfully. Error string, if the server has not been started already.

xsdbserver disconnect

Disconnect active XSDB server connection.

Syntax

xsdbserver disconnect

Disconnect current XSDB server connection.

Returns

Nothing, if the connection is closed. Error string, if there is no active connection.

xsdbserver version

Return XSDB command server version

Syntax

xsdbserver version

Return XSDB command server protocol version.

Returns

Server version if there is an active connection. Error string, if there is no active connection.

JTAG Access

jtag targets

List JTAG targets or switch between JTAG targets.

Syntax

jtag targets

List available JTAG targets.

jtag targets <target id>

Select <target id> as active JTAG target.

Options

Option Description
-set Set current target to entry single entry in list. This is useful in comibination with -filter option. An error will be generate if list is empty or contains more than one entry.
-regexp Use regexp for filter matching.
-nocase Use case insensitive filter matching.
-filter <filter-expression> Specify filter expression to control which targets are included in list based on its properties. Filter expressions are similar to Tcl expr syntax. Target properties are references by name, while Tcl variables are accessed using the $ syntax, string must be quoted. Operators ==, !=, <=, >=, <, >, && and || are supported as well as (). There operators behave like Tcl expr operators. String matching operator =~ and !~ match lhs string with rhs pattern using either regexp or string match.
-target-properties Returns a Tcl list of dictionaries containing target properties.
-open Open all targets in list. List can be shorted by specifying target-ids and using filters.
-close Close all targets in list. List can be shorted by specifying target-ids and using filters.
-timeout <sec> Poll until the targets specified by filter option are found on the scan chain, or until timeout. This option is valid only with filter option. The timeout value is in seconds. Default timeout is 3 seconds.

Returns

The return value depends on the options used.

<none>: Jtag targets list when no options are used.

-filter: Filtered jtag targets list.

-target-properties: Tcl list consisting of jtag target properties.

An error is returned when jtag target selection fails.

Example(s)

jtag targets

List all targets.

jtag targets -filter {name == "arm_dap"}

List targets with name "arm_dap".

jtag targets 2

Set target with id 2 as the current target.

jtag targets -set -filter {name =~ "arm*"}

Set current target to target with name starting with "arm".

jtag targets -set -filter {level == 0}

List Jtag cables.

jtag sequence

Create JTAG sequence object.

Syntax

jtag sequence

Create JTAG sequence object.

Description

The jtag sequence command creates a new sequence object. After creation the sequence is empty. The following sequence object commands are available:

sequence state new-state [count]

Move JTAG state machine to <new-state> and then generate <count> JTAG clocks. If <clock> is given and <new-state> is not a looping state (RESET, IDLE, IRSHIFT, IRPAUSE, DRSHIFT or DRPAUSE) then state machine will move towards RESET state.

sequence irshift [options] [bits [data]]

sequence drshift [options] bits [data] Shift data in IRSHIFT or DRSHIFT state. Data is either given as the last argument or if -tdi option is given then data will be all zeros or all ones depending on the argument given to -tdi. The <bits> and <data> arguments are not used for irshift when the -register option is specified. Available options: -register <name> Select instruction register by name. This option is only supported for irshift. -tdi <value> TDI value to use for all clocks in SHIFT state. -binary Format of <data> is binary, for example data from a file or from binary format. -integer Format of <data> is an integer. The least significant bit of data is shifted first. -bits Format of <data> is a binary text string. The first bit in the string is shifted first. -hex Format of <data> is a hexadecimal text string. The least significant bit of the first byte in the string is shifted first. -capture Cature TDO data during shift and return from sequence run command. -state <new-state> State to enter after shift is complete. The default is RESET.

sequence delay usec

Generate delay between sequence commands. No JTAG clocks will be generated during the delay. The delay is guaranteed to be at least <usec> microseconds, but can be longer for cables that do not support delays without generating JTAG clocks.

sequence get_pin pin

Get value of <pin>. Supported pins is cable specific.

sequence set_pin pin value

Set value of <pin> to <value>. Supported pins is cable specific.

sequence atomic enable

Set or clear atomic sequences. This is useful to creating sequences that are guaranteed to run with precise timing or fail. Atomic sequences should be as short as possible to minimize the risk of failure.

sequence run [options]

Run JTAG operations in sequence for the currently selected jtag target. This command will return the result from shift commands using -capture option and from get_pin commands. Available options: -binary Format return value(s) as binary. The first bit shifted out is the least significant bit in the first byte returned. -integer Format return values(s) as integer. The first bit shifted out is the least significant bit of the integer. -bits Format return value(s) as binary text string. The first bit shifted out is the first character in the string. -hex Format return value(s) as hexadecimal text string. The first bit shifted out is the least significant bit of the first byte of the in the string. -single Combine all return values as a single piece of data. Without this option the return value is a list with one entry for every shift with -capture and every get_pin.

sequence clear

Remove all commands from sequence.

sequence delete

Delete sequence.

Returns

Jtag sequence object.

Example(s)

set seqname [jtag sequence] $seqname state RESET $seqname drshift -capture -tdi 0 256 set result [$seqname run] $seqname delete

jtag device_properties

Get/set device properties.

Syntax

jtag device_properties idcode

Get JTAG device properties associated with <idcode>.

jtag device_properties key value ...

Set JTAG device properties.

Returns

Jtag device properties for the given idcode, or nothing, if the idcode is unknown.

Example(s)

jtag device_properties 0x4ba00477

Return Tcl dict containing device properties for idcode 0x4ba00477.

jtag device_properties {idcode 0x4ba00477 mask 0xffffffff name dap irlen 4}

Set device properties for idcode 0x4ba00477.

jtag lock

Lock JTAG scan chain.

Syntax

jtag lock [timeout]

Lock JTAG scan chain containing current JTAG target. DESCRIPTION Wait for scan chain lock to be available and then lock it. If <timeout> is specified the wait time is limited to <timeout> milliseconds. The JTAG lock prevents other clients from performing any JTAG shifts or state changes on the scan chain. Other scan chains can be used in parallel. The jtag run_sequence command will ensure that all commands in the sequence are performed in order so the use of jtag lock is only needed when multiple jtag run_sequence commands needs to be done without interruption.

Note(s)

  • A client should avoid locking more than one scan chain since this can cause dead-lock.

Returns

Nothing.

jtag unlock

Unlock JTAG scan chain.

Syntax

jtag unlock

Unlock JTAG scan chain containing current JTAG target.

Returns

Nothing.

jtag claim

Claim JTAG device.

Syntax

jtag claim <mask>

Set claim mask for current JTAG device. DESCRIPTION This command will attept to set the claim mask for the current JTAG device. If any set bits in <mask> are already set in the claim mask, then this command will return error "already claimed".

The claim mask allow clients to negotiate control over JTAG devices. This is different from jtag lock in that 1) it is specific to a device in the scan chain, and 2) any clients can perform JTAG operations while the claim is in effect.

Note(s)

  • Currently claim is used to disable the hw_server debugger from controlling microprocessors on ARM DAP devices and FPGA devices containing Microblaze processors.

Returns

Nothing.

jtag disclaim

Disclaim JTAG device.

Syntax

jtag disclaim <mask>

Clear claim mask for current JTAG device.

Returns

Nothing.

jtag frequency

Get/set JTAG frequency.

Syntax

jtag frequency

Get JTAG clock frequency for current scan chain.

jtag frequency -list

Get list of supported JTAG clock frequencies for current scan chain.

jtag frequency <frequency>

Set JTAG clock frequency for current scan chain. This frequency is persistent as long as the hw_server is running, and is reset to the default value when a new hw_server is started.

Returns

Current Jtag frequency, if no arguments are specified, or if Jtag frequency is successfully set. Supported Jtag frequencies, if -list option is used. Error string, if invalid frequency is specified or frequency cannot be set.

jtag skew

Get/set JTAG skew.

Syntax

jtag skew

Get JTAG clock skew for current scan chain.

jtag skew <clock-skew>

Set JTAG clock skew for current scan chain.

Note(s)

  • Clock skew property is not supported by some Jtag cables.

Returns

Current Jtag clock skew, if no arguments are specified, or if Jtag skew is successfully set. Error string, if invalid skew is specified or skew cannot be set.

jtag servers

List, open or close JTAG servers.

Syntax

jtag servers [options]

List, open, and close JTAG servers. JTAG servers are use to implement support for different types of JTAG cables. An open JTAG server will enumberate or connect to available JTAG ports.

Options

Option Description
-list List opened servers. This is the default if no other option is given.
-format List format of supported server strings.
-open <server> Specifies server to open.
-close <server> Specifies server to close.

Returns

Depends on the options specified

<none>, -list: List of open Jtag servers.

-format: List of supported Jtag servers.

-close: Nothing if the server is closed, or an error string, if invalid server is specified.

Example(s)

jtag servers

List opened servers and number of associated ports.

jtag servers -open xilinx-xvc:localhost:10200

Connect to XVC server on host localhost port 10200

jtag servers -close xilinx-xvc:localhost:10200

Close XVC server for host localhost port 10200

Target File System

tfile open

Open file

Syntax

tfile open <path>

Open specified file

Returns

File handle

tfile close

Close file handle

Syntax

tfile close <handle>

Close specified file handle

Returns

tfile read

Read file handle

Syntax

tfile read <handle>

Read from specified file handle

Options

Option Description
-offset <seek> File offset to read from

Returns

Read data

tfile write

Write file handle

Syntax

tfile write <handle>

Write to specified file handle

Options

Option Description
-offset <seek> File offset to write to

Returns

tfile stat

Get file attributes from path

Syntax

tfile stat <handle>

Get file attributes for <path>

Returns

File attributes

tfile lstat

Get link file attributes from path

Syntax

tfile lstat <path>

Get link file attributes for <path>

Returns

Link file attributes

tfile fstat

Get file attributes from handle

Syntax

tfile fstat <handle>

Get file attributes for <handle>

Returns

File attributes

tfile setstat

Set file attributes for path

Syntax

tfile setstat <path> <attributes>

Set file attributes for <path>

Returns

File attributes

tfile fsetstat

Set file attributes for handle

Syntax

tfile fsetstat <handle> <attributes>

Set file attributes for <handle>

Returns

File attributes

tfile remove

Remove path

Syntax

tfile remove <path>

Remove <path>

Returns

tfile rmdir

Remove directory

Syntax

tfile rmdir <path>

Remove directory <path>

Returns

tfile mkdir

Create directory

Syntax

tfile mkdir <path>

Make directory <path>

Returns

tfile realpath

Get real path

Syntax

tfile realpath <path>

Get real path of <path>

Returns

Real path

tfile rename

Rename path

Syntax

tfile rename <old path> <new path>

Rename file or directory

Returns

tfile readlink

Read symbolic link

Syntax

tfile readlink <path>

Read link file

Returns

Target path

tfile symlink

Create symbolic link

Syntax

tfile symlink <old path> <new path>

Symlink file or directory

Returns

tfile opendir

Open directory

Syntax

tfile opendir <path>

Open directory <path>

Returns

File handle

tfile readdir

Read directory

Syntax

tfile readdir <file handle>

Read directory

Returns

File handle

tfile copy

Copy target file

Syntax

tfile copy <src> <dest>

Copy file <src> to <dest>

Returns

Copy file locally on target

tfile user

Get user attributes

Syntax

tfile user

Get user attributes

Returns

User information

tfile roots

Get file system roots

Syntax

tfile roots

Get file system roots

Returns

List of file system roots

tfile ls

List directory contents

Syntax

tfile ls <path>

List directory content

Returns

Directory content

SVF Operations

The following is a list of svf commands:

svf config

Configure options for SVF file

Syntax

svf config [options]

Configure and generate SVF file.

Options

Options Description
-scan-chain <list of idcode-irlength pairs> List of idcode-irlength pairs. This can be obtained from xsdb command - jtag targets
-device-index <index> This is used to select device in the jtag scan chain.
-cpu-index <processor core> Specify the cpu-index to generate the SVF file. For A53#0 - A53#3 on ZynqMP, use cpu-index 0 -3 For R5#0 - R5#1 on ZynqMP, use cpu-index 4 -5 For A9#0 - A9#1 on Zynq, use cpu-index 0 -1 If multiple MicroBlaze processors are connected to MDM, select the specific MicroBlaze index for execution.
-out <filename> Output SVF file.
-delay <tcks> Delay in ticks between AP writes.
-linkdap Generate SVF for linking DAP to the jtag chain for ZynqMP Silicon versions 2.0 and above.
-bscan <user port> This is used to specify user bscan port to which MDM is connected.
-mb-chunksize <size in bytes> This used to specify the chunk size in bytes for each transaction while downloading. Supported only for Microblaze processors.

Returns

Nothing

Example(s)

svf config -scan-chain {0x14738093 12 0x5ba00477 4} -device-index 1  -cpu-index 0 -out "test.svf"

This creates a SVF file with name test.svf for core A53#0

svf config -scan-chain {0x14738093 12 0x5ba00477 4} -device-index 0  -bscan pmu -cpu-index 0 -out "test.svf"

This creates a SVF file with name test.svf for PMU MB

svf config -scan-chain {0x23651093 6} -device-index 0 -cpu-index 0  -bscan user1 -out "test.svf"

This creates a SVF file with name test.svf for MB connected to MDM on bscan USER1

svf generate

Generate recorded SVF file

Syntax

svf generate

Generate SVF file in the path specified in the config command.

Options

None

Returns

If successful, this command returns nothing. Otherwise it returns an error.

Example(s)

svf generate

svf mwr

Record memory write to SVF file

Syntax

svf mwr <address> <value>

Write <value> to the memory address specified by <address>.

Options

None

Returns

If successful, this command returns nothing. Otherwise it returns an error.

Example(s)

svf mwr 0xffff0000 0x14000000

svf dow

Record elf download to SVF file

Syntax

svf dow <elf file>

Record downloading of elf file <elf file> to the memory.

svf dow -data <file> <addr>

Record downloading of binary file <file> to the memory.

Options

None

Returns

If successful, this command returns nothing. Otherwise it returns an error.

Example(s)

svf dow "fsbl.elf"

Record downloading of elf file fsbl.elf.

svf dow -data "data.bin" 0x1000

Record downloading of binary file data.bin to the address 0x1000.

svf stop

Record stopping of core to SVF file

Syntax

svf stop

Record suspending execution of current target to SVF file.

Options

None

Returns

Nothing

Example(s)

svf stop

svf con

Record resuming of core to SVF file

Syntax

svf con

Record resuming the execution of active target to SVF file.

Options

None

Returns

Nothing

Example(s)

svf con

svf delay

Record delay in tcks to SVF file

Syntax

svf delay <delay in tcks>

Record delay in tcks to SVF file.

Options

None

Returns

Nothing

Example(s)

svf delay 1000

Delay of 1000 tcks is added to the SVF file.

Device Configuration System

The following is a list of device commands:

device program

Program PDI/BIT

Syntax

device program <file>

Program PDI or BIT file into device device.
Note: If no target is selected or if the current target is not a configurable device, and only one supported device is found in the targets list, then this device will be configured. Otherwise, users will have to select a device using targets command.

Returns

Nothing, if device is configured, or an error if the configuration failed.

device status

Return JTAG Register Status

Syntax

device status <options> <jtag-register-name>

Return device JTAG Register status or list of available registers if no name is given

Options

Option Description
-jreg-name <jtag-register-name> Specify jtag register name to read. This is the default option, so register name can be directly specified as an argument without using this option.
-hex Format the return data in hexadecimal.

Returns

Status report

Vitis Projects

getaddrmap

Get the address ranges of IP connected to processor.

Syntax

getaddrmap <hw spec file> <processor-instance>

Return the address ranges of all the IP connected to the processor in a tabular format, along with details like size and access flags of all IP.

Options

None

Returns

If successful, this command returns the output of IPs and ranges. Otherwise it returns an error.

Example(s)

getaddrmap system.xsa ps7_cortexa9_0

Return the address map of peripherals connected to ps7_cortexa9_0. system.xsa is the hw specification file exported from Vivado.

getperipherals

Get a list of all peripherals in the HW design

Syntax

getperipherals <xsa> <processor-instance>

Return the list of all the peripherals in the hardware design, along with version and type. If [processor-instance] is specified, return only a list of slave peripherals connected to that processor.

Options

None

Returns

If successful, this command returns the list of peripherals. Otherwise it returns an error.

Example(s)

getperipherals system.xsa

Return a list of peripherals in the hardware design.

getperipherals system.xsa ps7_cortexa9_0

Return a list of peripherals connected to processor ps7_cortexa9_0 in the hardware design.

repo

Get, set, or modify software repositories

Syntax

repo [OPTIONS]

Get/set the software repositories path currently used. This command is used to scan the repositories, to get the list of OS/libs/drivers/apps from repository.

Options

Option Description
-set <path-list> Set the repository path and load all the software cores available. Multiple repository paths can be specified as Tcl list.
-get Get the repository path(s).
-scan Scan the repositories. Used this option to scan the repositories, when some changes are done.
-os Return a list of all the OS from the repositories.
-libs Return a list of all the libs from the repositories.
-drivers Return a list of all the drivers from the repositories.
-apps Return a list of all the applications from the repositories.
-add-platforms <platform-name> Add the platform specified by <platform-name> to the repository.

Returns

Depends on the OPTIONS specified.

-scan, -set: Returns nothing.

-get: Returns the current repository path.

-os, -libs, -drivers, -apps: Returns the list of OS/libs/drivers/apps respectively.

Example(s)

repo -set <repo-path>

Set the repository path to the path specified by <repo-path>.

repo -os

Return a list of OS from the repo.

repo -libs

Return a list of libraries from the repo.

platform

Create, configure, list, and report platforms

Syntax

platform <sub-command> [options]

Create a platform project, or perform various other operations on the platform project, based on <sub-command> specified. Following sub-commands are supported. active - Set or return the active platform. clean - Clean platform. config - Configure the properties of a platform. create - Create/define a platform. fsbl - Specify extra compiler/linker flags for fsbl. generate - Build the platform. list - List all the platforms in workspace. pmufw - Specify extra compiler/linker flags for pmufw. report - Report the details of a platform. read - Read the platform settings from a file. remove - Delete the platform. write - Save the platform settings to a file. Type "help" followed by "platform sub-command", or "platform sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command. Refer to sub-command help for details.

Example(s)

Refer to sub-command help for details.

platform active

Set/Get active platform

Syntax

platform active [platform-name]

Set or get the active platform. If platform-name is specified, it is made as active platform, otherwise the name of active platform is returned. If no active platform exists, this command returns an empty string.

Options

None

Returns

Empty string, if a platform is set as active or no active platform exists. Platform name, when active platform is read.

Example(s)
platform active

Return the name of the active platform.

platform active zc702_platform

Set zc702_platform as active platform.

platform clean

Clean Platform

Syntax

platform clean

Clean the active platform in the workspace. This will clean all the components in platform like fsbl, pmufw etc.

Options

None

Returns

Nothing. Build log will be printed on the console.

Example(s)

platform active zcu102

platform clean

Set zcu102 as active platform and clean it.

platform config

Configure the active platform

Syntax

platform config [options]

Configure the properties of active platform.

Options
Option Description
-desc <description> Add a Brief description about the platform.
-updatehw <hw-spec> Update the platform to use a new hardware specification file specified by <hw-spec>.
-samples <samples-dir> Make the application template specified in <samples-dir>, part of the platform. This option can only be used for acceleratable application. "repo -apps <platform-name>" can be used to list the application templates available for the given platform-name.
-make-local Make the referenced SW components local to the platform.
-fsbl-target <processor-type> Processor-type for which the existing fsbl has to be re-generated. This option is valid only for ZU+.
-create-boot-bsp Generate boot components for the platform.
-remove-boot-bsp Remove all the boot components generated during platform creation.
-fsbl-elf <fsbl.elf> Prebuilt fsbl.elf to be used as boot component when "remove-boot-bsp" option is specified.
-pmufw-elf <pmufw.elf> Prebuilt pmufw.elf to be used as boot component when "remove-boot-bsp" option is specified.
Returns

Empty string, if the platform is configured successfully. Error string, if no platform is active or if the platform cannot be configured.

Example(s)

platform active zc702

platform config -desc "ZC702 with memory test application"

-samples /home/user/newDir Make zc702 as active platform, configure the description of the platform and make samples in /home/user/newDir part of the platform.

platform config -updatehw /home/user/newdesign.xsa

Updates the platform project with the new xsa.

platform create

Create a new platform

Syntax

platform create [options]

Create a new platform by importing hardware definition file. Platform can also be created from pre-defined hw platforms. Supported pre-defined platforms are zc702, zcu102, zc706 and zed.

Options
Option Description
-name <software-platform name> Name of the software platform to be generated.
-desc <description> Brief description about the software platform.
-hw <handoff-file> Hardware description file to be used to create the platform.
-out <output-directory> The directory where the software platform needs to be created. If the workspace is set, this option is not needed as the platform will be created in workspace. If the workspace is not set and this option is not specified, then platform will be generated in current working directory.
-prebuilt Mark the platform to be built from already built sw artifacts. This option should be used only if you have existig software platform artifacts.
-proc <processor> The processor to be used; the tool will create default domain.
-samples <samples-directory> Make the samples in <samples-directory>, part of the platform.
-os <os> The os to be used; the tool will create default domain. This works in combination with -proc option.
-xpfm <platform-path> Existing platform from which the projects have to be imported and made part of the current platform.
-no-boot-bsp Mark the platform to build without generating boot components.
Returns

Empty string, if the platform is created successfully. Error string, if the platform cannot be created.

Example(s)
platform create -name "zcu102_test" -hw zcu102

Defines a software platform for a pre-defined hardware desciption file.

platform create -name "zcu102_test" -hw zcu102 -proc psu_cortexa53_0 -os standalone

Defines a software platform for a pre-defined hardware desciption file. Create a default domain with standalone os running on psu_cortexa53_0.

platform create -xpfm /path/zc702.xpfm

This will create a platform project for the platform pointed by the xpfm file.

platform create -name "ZC702Test" -hw /path/zc702.xsa

Defines a software platform for a hardware desciption file.

platform fsbl

Configure fsbl

Syntax

platform fsbl

Configure extra compiler and linker flags for fsbl.

Options
Option Description
-extra-compiler-flags <flags> Set extra compiler flags for fsbl to the flags specified by <flags>.
-extra-linker-flags <flags> Set extra linker flags for fsbl to the flags specified by <flags>.
-report Return a table of extra compiler and linker flags set for fsbl.
Returns

Empty string, if the flag is set successfully. Error string, if the flag cannot be set.

Example(s)
platform fsbl -extra-compiler-flags "-DFSBL_DEBUG_INFO"

Add -DFSBL_DEBUG_INFO to the compiler options, while building the fsbl application.

platform fsbl -report

Return table of extra compiler and extra linker flags that are set.

platform generate

Build a platform

Syntax

platform generate

Build the active platform and add it to the repository. The platform must be created through platform create command, and must be selected as active platform before building.

Options
Option Description
-domains <domain-list> List of domains which need to be built and added to the repository. Without this option, all the domains that are part of the plafform are built.
Returns

Empty string, if the platform is generated successfully. Error string, if the platform cannot be built.

Example(s)
platform generate

Build the active platform and add it to repository.

platform generate -domains a53_standalone,r5_standalone

Build only a53_standalone,r5_standalone domains and add it to the repository.

platform list

List the platforms

Syntax

List the platforms in the workspace and repository.

Options

None

Returns

List of platforms, or "No active platform present" string if no platforms exist.

Example(s)
platform list

Return a list of all the platforms in the workspace and repository.

platform pmufw

Configure pmufw

Syntax

platform pmufw

Configure pmufw to build with extra compiler and linker flags.

Options
Option Description
-extra-compiler-flags <value> Set extra compiler flag for pmufw with the provided value.
-extra-linker-flags <value> Set extra linker flag for pmufw with the provided value.
-report Return the list of the flags set to pmufw.
Returns

Empty string, if the flag is set successfully. Error string, if the flag cannot be set.

Example(s)
platform pmufw -extra-compiler-flags "-DDEBUG_INFO"

Add -DDEBUG_INFO to the compiler options, while building the pmufw application.

platform read

Read from the platform file

Syntax

platform read [platform-file]

Read platform settings from the platform file and makes it available for edit. Platform file gets created during the creation of platform itself and it contains all details of platform like hw specification file, processor information etc

Options

None

Returns

Empty string, if the platform is read successfully. Error string, if the platform file cannot be read.

Example(s)
platform read <platform.spr>

Reads the platform from the platform.spr file.

platform remove

Delete a platform

Syntax

platform remove <platform-name>

Delete the given platform. If platform-name is not specified, active platform is deleted.

Options

None

Returns

Empty string, if the platform is deleted successfully. Error string, if the platform cannot be deleted.

Example(s)
platform remove zc702

Removes zc702 platform from the disk.

platform report

Report the details of a platform

Syntax

platform report [platform-name]

Return details like domains, processors, etc. created in a platform. If platform-name is not specified, details of the active platform are returned.

Options

None

Returns

Table with details of platform, or error string if no platforms exist.

Example(s)
platform report

Return a table with details of the active platform.

platform write

Write platform settings to a file

Syntax

platform write

Writes the platform settings to platform.spr file. It can be read back using "platform read" command.

Options

None

Returns

Empty string, if the platform settings are written successfully. Error string, if the platform settings cannot be written.

Example(s)
platform write

Writes platform to platform.spr file.

domain

Create, configure, list and report domains

Syntax

domain <sub-command> [options]

Create a domain, or perform various other operations on the domain, based on <sub-command> specified. Following sub-commands are supported. active - Set/Get the active domain. config - Configure the properties of a domain. create - Create a domain in the active platform. list - List all the domains in active platform. report - Report the details of a domain. remove - Delete a domain. Type "help" followed by "app sub-command", or "app sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command. Refer to sub-command help for details.

Example(s)

Refer to sub-command help for details.

domain active

Set/Get the active domain

Syntax

domain active [domain-name]

Set or get the active domain. If domain-name is specified, it is made as active domain, otherwise the name of active domain is returned. If no active domain exists, this command returns an empty string.

Options

None

Returns

Empty string, if a domain is set as active or no active domain exists. Domain name, when active domain is read.

Example(s)
domain active

Return the name of the active domain .

domain active test_domain

Set test_domain as active domain.

domain active

Set/Get the active domain

Syntax

domain active [domain-name]

Set or get the active domain. If domain-name is specified, it is made as active domain, otherwise the name of active domain is returned. If no active domain exists, this command returns an empty string.

Options

None

Returns

Empty string, if a domain is set as active or no active domain exists. Domain name, when active domain is read.

Example(s)
domain active

Return the name of the active domain .

domain active test_domain

Set test_domain as active domain.

domain config

Configure the active domain

Syntax

domain config [options]

Configure the properties of active domain.

Options
Option Description
-display-name <display name> Display name of the domain.
-desc <description> Brief description about the domain.
-image <location> For domain with Linux as OS, use pre-built Linux images from this directory, while creating the PetaLinux project. This option is valid only for Linux domains.
-sw-repo <repositories-list> List of repositories to be used to pick software components like drivers and libraries while generating this domain. Repository list should be a tcl list of software repository paths.
-mss <mss-file> Use mss from specified by <mss-file>, instead of generating mss file for the domain.
-prebuilt-data <directory-name> Pre-generated hardware data specified in directory-name will be used for building user applications that do not contain accelerators. This will reduce the build time.
-readme <file-name> Add README file for the domain, with boot instructions, etc.
-inc-path <include-path> Additional include path which should be added while building the application created for this domain.
-lib-path <library-path> Additional library search path which should be added to the linker settings of the application created for this domain.
-sysroot <sysroot-dir> The Linux sysroot directory that should be added to the platform. This sysroot will be consumed during application build.
-boot <boot-dir> Directory to generate components after Linux image build.
-bif <file-name> Bif file used to create boot image for Linux boot.
-qemu-args <file-name> File with all PS QEMU args listed. This is used to start PS QEMU.
-pmuqemu-args <file-name> File with all PMC QEMU args listed. This is used to start PMU QEMU.
-pmcqemu-args <file-name> File with all pmcqemu args listed. This is used to start pmcqemu.
-qemu-data <data-dir> Directory which has all the files listed in file-name provided as part of qemu-args and pmuqemu-args options.
Returns

Empty string, if the domain is configured successfully. Error string, if no domain is active or if the domain cannot be configured.

Example(s)
domain config -display-name zc702_MemoryTest

-desc "Memory test application for Zynq" -prebuilt-data /home/user/build_dir/ Configure display name, description, and set prebuilt-data directory for the active domain.

domain config -image "/home/user/linux_image/"

Create PetaLinux project from pre-built Linux image. domain -inc-path /path/include/ -lib-path /path/lib/ Adds include and library search paths to the domain's application build settings.

domain create

Create a new domain

Syntax

domain create [options]

Create a new domain in active platform.

Options
Option Description
-name <domain-name> Name of the domain.
-display-name <display_name> The name to be displayed in the report for the domain.
-desc <description> Brief description about the domain.
-proc <processor> Processor core to be used for creating the domain. For SMP Linux, this can be a Tcl list of processor cores.
-os <os> OS type. Default type is standalone.
-support-app <app-name> Create a domain with BSP settings needed for application specified by <app-name>. This option is valid only for standalone domains. "repo -apps" command can be used to list the available application.
-auto-generate-linux Generate the Linux artifacts automatically.
-image <location> For domain with Linux as OS, use pre-built Linux images from this directory, while creating the PetaLinux project. This option is valid only for Linux domains.
-sysroot <sysroot-dir> The linux sysroot directory that should be added to the platform. This sysroot will be consumed during application build.
Returns

Empty string, if the domain is created successfully. Error string, if the domain cannot be created.

Example(s)
domain create -name "ZUdomain" -os standalone -proc psu_cortexa53_0

-support-app {Hello World} Create a standalone domain and configure settings needed for "Hello World" template application.

domain create -name "SMPLinux" -os linux

-proc {ps7_cortexa9_0 ps7_cortexa9_1} Create a Linux domain named SMPLinux for processor cores ps7_cortexa9_0 ps7_cortexa9_1 in the active platform.

domain list

List domains

Syntax

domain list

List domains in the active platform.

Options

None

Returns

List of domains in the active platform, or empty string if no domains exist.

Example(s)

platform active platform1

domain list

Display all the domain created in platform1.

domain remove

Delete a domain

Syntax

domain remove [domain-name]

Delete a domain from active platform. If domain-name is not specified, active domain is deleted.

Options

None

Returns

Empty string, if the domain is deleted successfully. Error string, if the domain deletion fails.

Example(s)
domain remove test_domain

Removes test_domin from the active platform.

domain report

Report the details of a domain

Syntax

domain report [domain-name]

Return details like platform, processor core, OS, etc. of a domain. If domain-name is not specified, details of the active domain are reported.

Options

None

Returns

Table with details of a domain, if domain-name or active domain exists. Error string, if active domain does not exist and domain-name is not specified.

Example(s)
domain report

Return a table with details of the active domain.

bsp

Configure bsp settings of baremetal domain

Syntax

bsp <sub-command> [options]

Configure the bsp settings which includes library, driver and OS version of a active domain, based on <sub-command> specified. Following sub-commands are supported. config - Modify the configurable parameters of bsp settings. getdrivers - List IP instance and it's driver. getlibs - List the libraries from bsp settings. getos - List os details from bsp settings. listparams - List the configurable parameters of os/proc/library. regenerate - Regenerate BSP sources. removelib - Remove library from bsp settings. setdriver - Sets the driver for the given IP instance. setlib - Sets the given library. setosversion - Sets version for the given os. Type "help" followed by "bsp sub-command", or "bsp sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command. Refer to sub-command help for details.

Example(s)

Refer to sub-command help for details.

bsp config

configure parameters of bsp settings

Syntax

bsp config <param> <value>

Set/Get/Append value to the configurable parameters. If <param> and <value> are not specified, returns the details of all configurable parameters of processor, os, or all libraries in BSP. If <param> is specified and <value> value is not specified, return the value of the parameter. If <param> and <value> are specified, set the value of parameter. Use "bsp list-params <-os/-proc/-driver>" to know configurable parameters of OS/processor/driver.

Options
Option Description
-append <param> <value> Append the given value to the parameter.
Returns

Nothing, if the parameter is set/Appended successfully. Current value of the paramter if <value> is not specified. Error string, if the parameter cannot be set/Appended.

Example(s)
bsp config -append extra_compiler_flags "-pg"

Append -pg to extra_compiler_flags.

bsp config stdin

Return the current value of stdin.

bsp config stdin ps7_uart_1

Set stdin to ps7_uart_1 .

bsp getdrivers

list drivers

Syntax

bsp getdrivers

Return the list of drivers assigned to IP in bsp.

Options

None

Returns

Table with IP, it's corresponding driver and driver version. Empty string, if there are no IP's.

Example(s)
bsp getdrivers

Return the list of IP's and it's driver.

bsp getlibs

list libraries added in the bsp settings

Syntax

bsp getlibs

Display list of libraries added in the bsp settings.

Options

None

Returns

List of library/(ies). Empty string, if there are no library added.

Example(s)
bsp getlibs

Return the list of libraries added in bsp settings of active domain.

bsp getos

Display os details from bsp settings

Syntax

bsp getos

Displays the current OS and it's version.

Options

None

Returns

OS name and it's version.

Example(s)
bsp getos

Return OS name and version from the bsp settings of the active domain.

bsp listparams

List the configurable parameters of the bsp

Syntax

bsp listparams <option>

List the configurable parameters of the <option>.

Options
Option Description
-lib <lib-name> Return the configurable parameters of Library in BSP.
-os Return the configurable parameters of OS in BSP.
-proc Return the configurable parameters of processor in BSP.
Returns

parameter names, empty string, if no parameter exist.

Example(s)
bsp listparams -os

List all the configurable parameters of OS in the bsp settings.

bsp regenerate

Regenerate BSP sources.

Syntax

bsp regenerate

Regenerate the sources with the modifications made to BSP.

Options

None

Returns

Nothing, if the bsp is generated successfully. Error string, if the bsp cannot be generated.

Example(s)
bsp regenerate

Regenerate the BSP sources with the changes done in the BSP settings.

bsp removelib

Remove library from bsp settings

Syntax

bsp removelib -name <lib-name>

Remove the library from bsp settings of the active domain.

Options
Option Description
-name <lib-name> Library to be removed from bsp settings.
Returns

Nothing, if the library is removed successfully. Error string, if the library cannot be removed.

Example(s)
bsp removelib -name xilffs

Remove xilffs library from bsp settings.

bsp setdriver

Set the driver to IP

Syntax

bsp setdriver [options]

Set specified driver to the IP core in bsp settings of active domain.

Options
Option Description
-driver <driver-name> Driver to be assigned to an IP.
-ip <ip-name> IP instance for which the driver has to be added.
-ver <version> Driver version.
Returns

Nothing, if the driver is set successfully. Error string, if the driver cannot be set.

Example(s)
bsp setdriver -ip ps7_uart_1 -driver generic -ver 2.0

Set the generic driver for the ps7_uart_1 IP instance for the bsp.

bsp setlib

Adds the library to the bsp settings

Syntax

bsp setlib [options]

Add the library to the bsp settings of active domain.

Options
Option Description
-name <lib-name> Library to be added to the bsp settings.
-ver <version> Library version.
Returns

Nothing, if the library is set successfully. Error string, if the library cannot be set.

Example(s)
bsp setlib -name xilffs

Add the xilffs library to the bsp settings.

bsp setosversion

Set the OS version

Syntax

bsp setosversion [options]

Set OS version in the bsp settings of active domain. Latest version is added by default.

Options
Option Description
-ver <version> OS version.
Returns

Nothing, if the OS version is set successfully. Error string, if the OS version cannot be set.

Example(s)
bsp setosversion -ver 6.6

Set the OS version 6.6 in bsp settings of the active domain.

library

Library project management

Syntax

library <sub-command> [options]

Create a library project, or perform various other operations on the library project, based on <sub-command> specified. Following sub-commands are supported. build - Build the library project. clean - Clean the library project. create - Create a library project. list - List all the library projects in workspace. remove - Delete the library project. report - Report the details of the library project. Type "help" followed by "library sub-command", or "library sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command.

Example(s)

See sub-command help for examples.

library build

Build library project

Syntax

library build -name <project-name>

Build the library project specified by <project-name> in the workspace. "-name" switch is optional, so <project-name> can be specified directly, without using -name.

Options
Option Description
-name <project-name> Name of the library project to be built.
Returns

Nothing, if the library project is built successfully. Error string, if the library project build fails.

Example(s)
library build -name lib1

Build lib1 library project.

library clean

Clean library project

Syntax

library clean -name <project-name>

Clean the library project specified by <project-name> in the workspace. "-name" switch is optional, so <project-name> can be specified directly, without using -name.

Options
Option Description
-name <project-name> Name of the library project to be clean built.
Returns

Nothing, if the library project is cleaned successfully. Error string, if the library project build clean fails.

Example(s)
library clean -name lib1

Clean lib1 library project.

library create

Create a library project

Syntax

library create -name <project-name> -type <library-type> -platform <platform>

-domain <domain> -sysproj <system-project> Create a library project using an existing platform, and domain. If <platform>, <domain>, and <sys-config> are not specified, then active platform and domain are used for Creating library project. For creating library project and adding them to existing system project, refer to next use case.

library create -name <project-name> -type <library-type> -sysproj <system-project>

-domain <domain> Create a library project for domain specified by <domain> and add it to system project specified by <system-project>. If <system-project> exists, platform corresponding to this system project are used for creating the library project. If <domain> is not specified, then active domain is used.

Options
Option Description
-name <project-name> Project name that should be created.
-type <library-type> <library-type> can be 'static' or 'shared'
-platform <platform-name> Name of the platform. Use "repo -platforms" to list available pre-defined platforms.
-domain <domain-name> Name of the domain. Use "platform report <platform-name>" to list the available domains in a platform.
-sysproj <system-project> Name of the system project. Use "sysproj list" to know the available system projects in the workspace.
Returns

Nothing, if the library project is created successfully. Error string, if the library project creation fails.

Example(s)
library create -name lib1 -type static -platform zcu102 -domain a53_standalone

Create a static library project with name 'lib1', for the platform zcu102, which has a domain named a53_standalone domain.

library create -name lib2 -type shared -sysproj test_system -domain test_domain

Create shared library project with name 'lib2' and add it to system project test_system.

library list

List library projects

Syntax

List all library projects in the workspace.

Options

None

Returns

List of library projects in the workspace. If no library projects exist, an empty string is returned.

Example(s)
library list

Lists all the library projects in the workspace.

library remove

Delete library project

Syntax

library remove [options] <project-name>

Delete a library project from the workspace.

Options

None

Returns

Nothing, if the library project is deleted successfully. Error string, if the library project deletion fails.

Example(s)
library remove lib1

Removes lib1 from workspace.

library report

Report details of the library project

Syntax

library report <project-name>

Return details like platform, domain etc. of the library project.

Options

None

Returns

Details of the library project, or error string, if library project does not exist.

Example(s)

app report lib1 Return all the details of library lib1.

setws

Set vitis workspace

Syntax

setws [OPTIONS] [path]

Set vitis workspace to <path>, for creating projects. If <path> does not exist, then the directory is created. If <path> is not specified, then current directory is used.

Options

Option Description
-switch <path> Close existing workspace and switch to new workspace.

Returns

Nothing if the workspace is set successfully. Error string, if the path specified is a file.

Example(s)

setws /tmp/wrk/wksp1

Set the current workspace to /tmp/wrk/wksp1.

setws -switch /tmp/wrk/wksp2

Close the current workspace and switch to new workspace /tmp/wrk/wksp2.

getws

Get vitis workspace

Syntax

getws

Return the current vitis workspace.

Returns

Current workspace.

app

Application project management

Syntax

app <sub-command> [options]

Create an application project, or perform various other operations on the application project, based on <sub-command> specified. Following sub-commands are supported. build - Build the application project. clean - Clean the application project. config - Configure C/C++ build settings of the application project. create - Create an application project. list - List all the application projects in workspace. remove - Delete the application project. report - Report the details of the application project. switch - Switch application project to refer another platform. Type "help" followed by "app sub-command", or "app sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command. Refer to sub-command help for details.

Example(s)

Please refer to sub-command help for examples.

app build

Build application

Syntax

app build -name <app-name>

Build the application specified by <app-name> in the workspace. "-name" switch is optional, so <app-name> can be specified directly, without using -name.

Options
Option Description
-name <app-name> Name of the application to be built.
Returns

Nothing. Build log will be printed on the console.

Example(s)
app build -name helloworld

Build helloworld application.

app clean

Clean application

Syntax

app clean -name <app-name>

Clean the application specified by <app-name> in the workspace. "-name" switch is optional, so <app-name> can be specified directly, without using -name.

Options
Option Description
-name <app-name> Name of the application to be clean built.
Returns

Nothing. Build log will be printed on the console.

Example(s)
app clean -name helloworld

Clean helloworld application.

app config

Configure C/C++ build settings of the application

Syntax

Configure C/C++ build settings for the specified application. Following settings can be configured for applications: assembler-flags : Miscellaneous flags for assembler build-config : Get/set build configuration compiler-misc : Compiler miscellaneous flags compiler-optimization : Optimization level define-compiler-symbols : Define symbols. Ex. MYSYMBOL include-path : Include path for header files libraries : Libraries to be added while linking library-search-path : Search path for the libraries added linker-misc : Linker miscellaneous flags linker-script : Linker script for linking undef-compiler-symbols : Undefine symbols. Ex. MYSYMBOL

app config -name <app-name> <param-name>

Get the value of configuration parameter <param-name> for the application specified by <app-name>.

app config [OPTIONS] -name <app-name> <param-name> <value>

Set/modify/remove the value of configuration parameter <param-name> for the application specified by <app-name>.

Options
Option Description
-name Name of the application.
-set Set the configuration parameter value to new <value>.
-get Get the configuration parameter value.
-add Append the new <value> to configuration parameter value. Add option is not supported for ,compiler-optimization
-info Displays more information like possible values and possible operations about the configuration parameter. A parameter name must be specified when this option is used.
-remove Remove <value> from the configuration parameter value. Remove option is not supported for assembler-flags, build-config, compiler-misc, compiler-optimization, linker-misc and linker-script.
Returns

Depends on the arguments specified. <none> List of parameters available for configuration and description of each parameter.

<parameter name>: Parameter value, or error, if unsupported parameter is specified.

<parameter name> <paramater value>: Nothing if the value is set successfully, or error, if unsupported parameter is specified.

Example(s)
app config -name test build-config

Return the current build configuration for the application named test.

app config -name test define-compiler-symbols FSBL_DEBUG_INFO

Add -DFSBL_DEBUG_INFO to the compiler options, while building the test application.

app config -name test -remove define-compiler-symbols FSBL_DEBUG_INFO

Remove -DFSBL_DEBUG_INFO from the compiler options, while building the test application.

app config -name test -set compiler-misc {-c -fmessage-length=0 -MT"$@"}

Set {-c -fmessage-length=0 -MT"$@"} as compiler miscellaneous flags for the test application.

app config -name test -append compiler-misc {-pg}

Add {-pg} to compiler miscellaneous flags for the test application.

app config -name test -info compiler-optimization

Display more information about possible values and default values for compiler optimization level.

app create

Create an application

Syntax

app create [options] -platform <platform> -domain <domain>

-sysproj <system-project> Create an application using an existing platform and domain, and add it to a system project. If <platform> and <domain> are not specified, then active platform and domain are used for creating the application. If <system-project> is not specified, then a system project is created with name appname_system. For creating applications and adding them to existing system project, refer to next use case. Supported options are: -name, -template.

app create [options] -sysproj <system-project> -domain <domain>

Create an application for domain specified by <domain> and add it to system project specified by <system-project>. If <system-project> exists, platform corresponding to this system project are used for creating the application. If <domain> is not specified, then active domain is used. Supported options are: -name, -template.

app create [options] -hw <hw-spec> -proc <proc-instance>

Create an application for processor core specified <proc-instance> in HW platform specified by <hw-spec>. Supported options are: -name, -template, -os, -lang.

Options
Option Description
-name <application-name> Name of the application to be created.
-platform <platform-name> Name of the platform. Use "repo -platforms" to list available pre-defined platforms.
-domain <domain-name> Name of the domain. Use "platform report <platform-name>" to list the available system configurations in a platform.
-hw <hw-spec> HW specification file exported from Vivado (XSA).
-sysproj <system-project> Name of the system project. Use "sysproj list" to know available system projects in the workspace.
-proc <processor> Processor core for which the application should be created.
-template <application template> Name of the template application. Default is "Hello World". Use "repo -apps" to list available template applications.
-os <os-name> OS type. Default type is standalone.
-lang <programming language> Programming language can be c or c++.
Returns

Nothing, if the application is created successfully. Error string, if the application creation fails.

Example(s)
app create -name test -platform zcu102 -domain a53_standalone

Create Hello World application named test, for the platform zcu102, with a domain named a53_standalone.

app create -name zqfsbl -hw zc702 -proc ps7_cortexa9_0 -os standalone

-template "Zynq FSBL" Create Zynq FSBL application named zqfsbl for ps7_cortexa9_0 processor core, in zc702 HW platform.

app create -name memtest -hw /path/zc702.xsa -proc ps7_cortexa9_0 -os standalone

-template "Memory Tests" Create Memory Test application named memtest for ps7_cortexa9_0 processor core, in zc702.xsa HW platform.

app create -name test -sysproj test_system -domain test_domain

Create Hello World application project with name test and add it to system project test_system.

app list

List applications

Syntax

app list

List all applications for in the workspace.

Options

None

Returns

List of applications in the workspace. If no applications exist, "No application exist" string is returned.

Example(s)
app list

Lists all the applications in the workspace.

app remove

Delete application

Syntax

app remove <app-name>

Delete an application from the workspace.

Options

None

Returns

Nothing, if the application is deleted successfully. Error string, if the application deletion fails.

Example(s)
app remove zynqapp

Removes zynqapp from workspace.

app report

Report details of the application

Syntax

app report <app-name>

Return details like platform, domain, processor core, OS, etc. of an application.

Options

None

Returns

Details of the application, or error string, if application does not exist.

Example(s)
app report test

Return all the details of application test.

app switch

Switch the application to use another domain/platform

Syntax

app switch -name <app-name> -platform <platform-name> -domain <domain-name>

Switch the application to use another platform and domain. If the domain name is not specified, application will be moved to the first domain which is created for the same processor as current domain. This option is supported if there is only one application under this platform.

app switch -name <app-name> -domain <domain-name>

Switch the application to use another domain within the same platform. New domain should be created for the same processor as current domain.

Options
Option Description
-name <application-name> Name of the application to be switched.
-platform <platform-name> Name of the new Platform. Use "platform -list" to list the available platforms.
-domain <domain-name> Name of the new domain. Use "domain -list" to list avaliable domain in the active platform.
Returns

Nothing if application is switched successfully, or error string, if given platform project does not exist or given platform project does not have valid domain.

Example(s)
app switch -name helloworld -platform zcu102

Switch the helloworld application to use zcu102 platform.

sysproj

System project management

Syntax

sysproj <sub-command> [options]

Build, list and report system project, based on <sub-command> specified. Following sub-commands are supported. build - Build the system project. clean - Clean the system project. list - List all system projects in workspace. remove - Delete the system project. report - Report the details of the system project. Type "help" followed by "sysproj sub-command", or "sysproj sub-command" followed by "-help" for more details.

Options

Depends on the sub-command. Refer to sub-command help for details.

Returns

Depends on the sub-command.

Example(s)

See sub-command help for examples.

sysproj build

Build system project

Syntax

sysproj build -name <sysproj-name>

Build the application specified by <sysproj-name> in the workspace. "-name" switch is optional, so <sysproj-name> can be specified directly, without using -name.

Options
Option Description
-name <sysproj-name> Name of the system project to be built.
Example(s)
sysproj build -name helloworld_system

Build the system project specified.

sysproj clean

Clean application

Syntax

sysproj clean -name <app-name>

Clean the application specified by <sysproj-name> in the workspace. "-name" switch is optional, so <sysproj-name> can be specified directly, without using -name.

Options
Option Description
-name <sysproj-name> Name of the application to be clean built.
Returns

Nothing, if the application is cleaned suceessfully. Error string, if the application build clean fails.

Example(s)
sysproj clean -name helloworld_system

Clean-build the system project specified.

sysproj list

List system projects

Syntax

sysproj list

List all system projects in the workspace.

Options

None

Returns

List of system projects in the workspace. If no system project exist, an empty string is returned.

Example(s)
sysproj list

List all system projects in the workspace.

sysproj remove

Delete system project

Syntax

sysproj remove [options]

Delete a system project from the workspace.

Options

None

Returns

Nothing, if the system project is deleted successfully. Error string, if the system project deletion fails.

Example(s)
sysproj remove test_system

Delete test_system from workspace.

sysproj report

Report details of the system project

Syntax

sysproj report <sysproj-name>

Return the details like platform, domain, etc. of a system project.

Options

None

Returns

Details of the system project, or error string, if system project does not exist.

Example(s)
sysproj report test_system

Return all the details of the system project test_system.

importprojects

Import projects to workspace

Syntax

importprojects <path>

Import all the vitis projects from <path> to workspace.

Returns

Nothing, if the projects are imported successfully. Error string, if project path is not specified or if the projects cannot be imported.

Example(s)

importprojects /tmp/wrk/wksp1/hello1

Import vitis project(s) into the current workspace.

importsources

Import sources to an application project.

Syntax

importsources [OPTIONS]

Import sources from a path to application project in workspace.

Options

Option Description
-name <project-name> Application Project to which the sources should be imported.
-path <source-path> Path from which the source files should be imported. If <source-path> is a file, it is imported to application project. If <source-path> is a directory, all the files/sub-directories from the <source-path> are imported to application project. All existing source files will be overwritten in the application, and new files will be copied. Linker script will not be copied to the application directory, unless -linker-script option is used.
-linker-script Copies the linker script as well.

Returns

Nothing, if the project sources are imported successfully. Error string, if invalid options are used or if the project sources cannot be read/imported.

Example(s)

importsources -name hello1 -path /tmp/wrk/wksp2/hello2

Import the 'hello2' project sources to 'hello1' application project without the linker script.

importsources -name hello1 -path /tmp/wrk/wksp2/hello2 -linker-script

Import the 'hello2' project sources to 'hello1' application project along with the linker script.

toolchain

Set or get toolchain used for building projects

Syntax

toolchain

Return a list of available toolchains and supported processor types.

toolchain <processor-type>

Get the current toolchain for <processor-type>.

toolchain <processor-type> <tool-chain>

Set the <toolchain> for <processor-type>. Any new projects created will use the new toolchain during build.

Returns

Depends on the arguments specified <none> List of available toolchains and supported processor types

<processor-type>: Current toolchain for processor-type

<processor-type> <tool-chain>: Nothing if the tool-chain is set, or error, if unsupported tool-chain is specified