Advanced Options - 2021.2 English

Vivado Design Suite User Guide: Programming and Debugging

Document ID
UG908
Release Date
2021-10-22
Version
2021.2 English
Table 1. Advanced Option
Option Purpose
detect-ir-length

Disable detecting the IR detect length during scan chain discovery.

This option is used to start up the hw_server with additional devices added to its device table. By default the hw_serverstarts with a preset list of devices that are compiled in from the XICOM SQL jtag master table. These settings can be overridden or extended using the this set device-info-file option. The file that is specified is a .csv file that ignores lines that start with a "#".

This is how you specify a .csv file at hw_server start-up:

hw_server -e "set device-info-file my_file.csv"

The .cvs file is formatted as shown below (hw_server_device_info_file.csv):

############################################################
# File: hw_server_device_info_file.csv
# Description:
# This is a sample jtag ID table. This file can be used to define
# additional devices to be detected by the hw_server application.
#
# In this file empty lines, lines with spaces, and lines that begin
# with the '#' character will be ignored.
#
# The format of this file is as follows:
#
# ROW 1: fields
# The standard JTAG id fields are "idcode,mask,irlen,name"
# ROW 2: field types
# For each field specified in ROW 1, the type is used to
# interpret the field data read per device. The types
# accepted are "i" for integer and "s" for string. If
# you use the standard fields on ROW 1 then you should
# use "i,i,i,s" in ROW 2 to set the fields idcode,mask
# irlength to integer and name as string
#
# To use this table you start hw_server with the following
# command line arguments:
#
# hw_server -e "set device-info-file <file>"
#
# Where <file> is replaced with this filename.
############################################################
idcode,mask,irlen,name
i,i,i,s
167784595,268435455,10,chipscope_soft_tap
device-info-file Sets a default device file .csv to be used
max-jtag-devices

Increases the max number of devices that can be detected in a scan chain. Default is 32.

This option is used to start up the hw_serverwith the ability to detect more than the default number of devices in a scan chain. The default value for this setting is 32. A user can increase this value for longer jtag chains. Note that increasing this number slows down the device discovery process, which in turn can slow down cable access. Therefore, it is only for systems with large device counts should a user increase this value.

This is how to specify the option at hw_server start-up:
hw_server -e "set max-jtag-devices 64"
xdb-user-bscan

Sets which bscan will be used to scan for xsdb cores.

This option is used to start the hw_server scanning a for xsdb master cores on alternate bscans. By default, hw_server will scan user 1 and 3 bscans. With this option you can launch hw_serverand have it look for bscans on different bscan user slots.

This is how to specify the option at hw_server start-up:
hw_server -e "set xsdb-user-bscan 1,2,3,4"

The arguments to this parameter specify the list of parameters. The list will be a comma separated list ranging from 1-4. The minimum number specified is 1 element in the list and the maximum is 4.

mdm-detect-bscan-mask

Sets which bscan will be used to scan for mdm cores.

This option is used to start the hw_server scanning a for MicroBlaze™ master cores on alternate bscans. By default hw_server will scan user 2 bscan. With this option the user can launch hw_server and have it look for MicroBlaze on different bscan user slots.

This is how to specify the option at hw_server start-up:
hw_server -e "set mdm-detect-bscan-mask 2"

The bitmask is for any FPGA or ACAP discovered by hw_server. Here are some examples of common bitmask settings:

 Mask Value        BSCAN Scanned

  0                 none

  1                 User1

  3                 User1, User2

  7                 User1, User2, User3

  f                 User1, User2, User3, User4

always-open-jtag

Forces hw_server to open up all targets at start up.

When hw_server starts by default no cables are initialized. When the first connection is initiated the cables will be discovered and opened. This discovery period takes a couple of seconds to several minutes depending on the system. Once fully initialized the cables are read and devices discovered.

In some cases, it is necessary to have the cables discovered and ready to be used. For instance when setting up a linux system as a board server, it may be desirable to have the cables always initialized and ready to serve connections. For these cases you can use the always-open-jtag option to force the cables to open.

By default this is the setting at start up (no argument needs to be passed in):
hw_server -e "set always-open-jtag 0"
To force opening the cable, pass in this argument as shown below:
hw_server -e "set always-open-jtag 1"
auto-open-servers

Opens a cable server with specific parameters., used for XVC cable opening.

This option is a debug option used to automatically open an XVC cable connection, and to control which types of USB cables hw_server should detect. The argument to the auto-open-servers parameter is a comma separated list of fields. Each field is a colon separated list of sub-fields where the first sub-field is the type and the remaining sub-fields are type specific. For the xilinx-xvc type the sub-fields are host and port. The default value for auto-open-servers is "*" which indicates that hw_server should detect all types of cables that it can. Cables types that require parameters, like XVC, are not covered by "*".

This is how to specify the option at hw_server start-up:

hw_server -e "set auto-open-servers     xilinx-xvc:localhost:10200"

To open up two servers you would use:

hw_server -e "set auto-open-servers     xilinx-xvc:localhost:10200,xilinx-xvc:localhost:10210"

To open up two XVC servers in addition to the all USB based cables you would use:

hw_server -e "set auto-open-servers     *:xilinx-xvc:localhost:10200,xilinx-xvc:localhost:10210"
auto-open-ports

Controls automatic open of ports (cables or scan chains).

This option is used to control the automatic open of JTAG scan chains. The argument to the auto-open-ports parameter is a boolean value, 1 indicating that all known JTAG scan chains should automatically be opened and 0 indicating that clients will open select JTAG scan chains. The default value is 1. Setting this to 0 is useful for example, when multiple JTAG scan chains are connected to a single host and different instances of hw_server are used to access each scan chain.

This is how to specify the option at hw_server start-up:

hw_server -e "set auto-open-ports 0"
xvc-timeout

Changes the XVC timeout value to help debug XVC servers.

This option is a debug option used to increase the timeout period needed for an XVC transaction to terminate. The argument to the xvc-timeout parameter is a time in seconds. A value of 0 will disable timeout and thus wait indefinitely.

This is how you specify the option at hw_server start-up:

hw_server -e "set xvc-timeout 100"
xvc-servers

Start XVC servers for cables.

This option is used make hw_server start XVC servers for specified JTAG cables. The argument to the xvc-servers parameter is a comma (,) separated list of XVC server descriptions. Each XVC server description is a colon (:) separated list containing the cable identification, XVC server host name or number and port number. The cable identification is the manufacturer name and a unique identifier separated by slash (/) characters. The cable identification may be a subset of the full cable identification and the host name may be empty. If it is empty, it indicates that the server should listen for incoming connections on all network interfaces.

See processor-debug-claim for how to avoid interference when both XVC client and XVC server are debuggers of the same device types and XVC locking mode is used.

This is how to specify the option at hw_server start-up:

hw_server -e "set xvc-servers 210203356596A:localhost:3000"

Note that you will still have to connect to this hw_server instance first to initialize the cable interface. If you do not connect to the cable you will see a message like the following:

TCF 19:11:02.417: XVC open port failed: Cannot find
JTAG cable matching 210203A0314DA

To have the XVC cable automatically opened and locked to XVC add the always-open-jtag option as shown below:

hw_server -e 'set xvc-servers 210203A0314DA:xcoatslab-9:3122' -e
'set always-open-jtag 1'
xvc-packet-len

Change max package length of XVC servers.

This option controls the XVC package length returned by XVC servers started using the xvc-servers option. Current default package length is 16000, however this may change in newer versions.

This is how to specify the option at hw_server start-up:

hw_server -e "set xvc-servers 210203356596A:localhost:3000"     -e "set xvc-packet-len 1000"
xvc-version

Change XVC protocol version of XVC servers.

This is a debug option that can be used together with xvc-servers to control which XVC protocol version is exposed to XVC clients. The current default protocol version is 1.1, however this may change if new versions of the XVC protocol are defined.

This is how to specify the option at hw_server start-up:

hw_server -e "set xvc-servers 210203356596A:localhost:3000"     -e "set xvc-version 1.0"
xvc-capabilities

Change XVC capabilities of XVC servers.

This is a debug option that can be used together with xvc-servers to control which capabilities are exposed to XVC clients. Current default capabilities are locking, status, and state-aware, however additional capabilities may be added in future versions. This option has no effect if xvc-version is set to 1.0.

This is how to specify the option at hw_server start-up:

hw_server -e "set xvc-servers 210203356596A:localhost:3000"
-e "set xvc-capabilities status,state-aware"
processor-debug-claim

Automatically claim select device types to prevent debugger from using them.

This option is used to prevent hw_server debugger from using selected device types for debugging. The argument gives to this option is a bit mask. By default, hw_server uses all known device types for debugging. Bit number meaning

   Bit       Device Type

  0           Arm DAP

  1          MPSoC

  2          FPGA or ACAP

This option is useful for example when starting XVC server using xvc-servers with an XVC client that is a debugger of one or more of the above devices, or when hw_server connects to an XVC server that is a debugger of one or more of the above devices. In both cases this is only relevant when using the locking capability since that allows time sharing between the debuggers.

This is how to specify the option at hw_server start-up:

hw_server -e "set processor-debug-claim 2"
jtag-poll-delay

Delay in uS. Default 50000.

This option is a polling option used to reduce the JTAG polling frequency. The JTAG polling frequency is the smallest period taken between JTAG poll operations. The default and smallest value is 50,000 uS. The argument to the jtag-poll-delay parameter is a number in uS.

help

Displays hw_server "e" options

This option is used to display all the available "e" options for hw_server.

This is how to specify the option at hw_server start-up:

hw_server -e help
show-all

Shows all options passed set in hw_serv.

This option is used to display all the "e" option settings for hw_server.

This is how you specify the option at hw_server start-up:

hw_server -e show-all
jtag-default-frequency

Sets default frequency for all cables.

This option sets the default JTAG TCK frequency. The jtag-default-frequency parameter is a number in Hz.

This is how to specify the option at hw_server start-up:

hw_server -e "set jtag-default-frequency 5000000"
jtag-port-filter

Set JTAG port filter.

This option is used to control JTAG port filtering. When it is set, hw_server ignores JTAG ports that do not match the filter. The argument to this parameter is a comma separated list of complete or partial port identifiers. A port identifier is a string of the form <manufacturer>/<productid>/<serial><port>. The filter matches when any of the port filter's strings can be found anywhere in the port identifier string.

This parameter is useful when running multiple instances of hw_server on the same host to specify which cable should be handled by which hw_server.

This is how to specify the option at hw_server start-up:

hw_server -e "set jtag-port-filter     Xilinx/DLC10/0000128f515601"

Another example filtering any Xilinx DLC9 or DLC10 cable while having the hw_server start on port 3122:

hw_server -stcp::3122 -e "set jtag-port-filter DLC9,DLC10"
bscan-switch-user-mask

Enables bscan switch.

This option is used to control the bscan switch detection.

This is how to specify the option at hw_server start-up:

hw_server -e "set bscan-switch-user-mask <user-bit-mask>"
jtag-port-devices

Sets JTAG port device list.

This option is used to specify a static list of devices for a JTAG scan chain. When this is specified hw_server does not read the IDCODE registers to detect devices on the scan chain. This is useful when a scan chain contains devices that do not conform to the IEEE 1149.1 specification. The value given to this parameter is a comma separated list of IDCODE values in the same order as the devices on the scan chain.

This is how to specify the option at hw_server start-up:

hw_server -e "set jtag-port-devices 0xe970203f,0x03632093"
max-ir-length

Enables devices in JTAG chain whose ir length is greater than 64 bits.

This option is used to start up the hw_server with the ability to enable ir lengths greater than 64 bits. The default value for this setting is 64. A user can increase this value for devices in the JTAG chains whose ir length is wide (for example, 93). Note that increasing this number will slow down the device discovery process which in turn can slow down cable access. Therefore, only for systems with long ir lengths device counts should a user increase this value.

This is how to specify the option at hw_server start-up:

hw_server -e "set max-ir-length 93"