program_hw_devices - 2023.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
UG835
Release Date
2023-05-16
Version
2023.1 English

Program hardware devices

Syntax

program_hw_devices [‑key <arg>] [‑clear] [‑skip_program_keys]
    [‑skip_program_rsa] [‑user_efuse <arg>] [‑user_efuse_128 <arg>]
    [‑control_efuse <arg>] [‑security_efuse <arg>] [‑only_export_efuse]
    [‑svf_file <arg>] [‑efuse_export_file <arg>] [‑disable_eos_check]
    [‑skip_reset] [‑force] [‑append] [‑type <arg>] [‑mpsoc_reset <arg>]
    [‑quiet] [‑verbose] [<hw_device>...]

Returns

Hardware devices

Usage

Name Description
[-key] key option value for encryption programming: efuse,bbr,none
[-clear] clear bbr registers, only valid for bbr
[-skip_program_keys] skip programming keys specified in NKY file, if any
[-skip_program_rsa] skip programming RSA key specified in NKY file, if any
[-user_efuse] hex user fuse value for encryption programming
[-user_efuse_128] hex user fuse 128 bit value for encryption programming
[-control_efuse] hex control fuse value for encryption programming
[-security_efuse] hex security fuse value for encryption programming
[-only_export_efuse] do not program eFUSE; just export settings to efuse_export_file
[-svf_file] svf file used to program device
[-efuse_export_file] output file to store programmed eFUSE settings
[-disable_eos_check] Disables End of Startup check after programming
[-skip_reset] Skips resetting the device before programming
[-force] overwrites svf file and creates empty file
[-append] append to svf file
[-type] bitstream file type to be used for programming: bit,bin,rbt
[-mpsoc_reset] System reset MPSoC device before programming: yes, no, auto
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
[<hw_device>] list of hardware devices Default: current hardware device

Categories

Hardware

Description

Program the specified hardware device object or objects on the open hardware target of the current hardware server.

To access a Xilinx® FPGA through the Hardware Manager, you must use the following Tcl command sequence:

  1. open_hw - Opens the Hardware Manager in the Vivado® Design Suite.
  2. connect_hw_server - Makes a connection to a local or remote Vivado hardware server application.
  3. current_hw_target - Defines the hardware target of the connected server.
  4. open_hw_target - Opens a connection to the hardware target.
  5. current_hw_device - Specifies the Xilinx FPGA to use for programming and debugging.

After connecting to the target hardware device, you must associate the bitstream file (.bit, .rbt, .bin) from the design with the device, using the set_property command:

set_property PROGRAM.FILE {C:/Data/design.bit} [current_hw_device]

For debug purposes, you can also associate a probes file (.ltx) with the device using the PROBES.FILE property:

set_property PROBES.FILE {C:/Data/debug_nets.ltx} [current_hw_device]

Once the programming file has been associated with the hardware device, you can program the hardware device using the program_hw_devices command, and debug the device using any of a number of Hardware Manager Tcl commands. To interactively debug the device open the Hardware Manager in the Vivado Design Suite IDE.

You can also program an encrypted bitstream into the specified hw_device. This requires the implemented design to have encryption properties assigned prior to generating the bitstream with the write_bitstream command. You can add ENCRYPTION properties to the design most easily using the Encryption page of the Edit Device Properties dialog box in the Vivado IDE. Refer to the Vivado Design Suite User Guide: Programming and Debugging (UG908) for more information on the Edit Device Properties dialog box.

Programming a device for an encrypted bitstream is a two-step process that requires running program_hw_devices once to program the encryption key into the BBR or eFUSE registers, and a second time to program the encrypted bitstream into the device:

program_hw_devices -key bbr [current_hw_device]
program_hw_device [current_hw_device]
CAUTION:
eFUSEs are one-time programmable cells on the hardware device, used to store the factory-programmed Device DNA, AES-GCM encryption key, and user specified values. Refer to the UltraScale Architecture Configuration (UG570) or 7 Series FPGAs Configuration User Guide (UG470) for more information on eFUSE registers.

The program_hw_devices command can also generate a Serial Vector Format (SVF) file for in-system and remote programming of Xilinx devices. SVF is an industry standard file format that is used to describe JTAG chain operations by describing the information that needs to be shifted into the device chain. SVF files are ASCII files that can be written and modified in any text editor. Many third-party programming utilities can use the SVF file to program Xilinx devices in a JTAG chain.

This command returns a transcript of its actions, or returns an error if it fails.

Arguments

-key [ bbr | efuse ] - (Optional) Specify that the encryption key should be programmed into the battery-backed SRAM or the eFUSE registers of the specified hw device. The encryption key is defined in the encryption key (NKY or NKZ) file generated by the write_bitstream command for encrypted bit files, and is associated with the hw_bitstream object with the ENCRYPTION.FILE property. The key value is extracted from the file and is stored in the ENCRYPTION.KEY property of the hw_bitstream object associated with the hardware device.

Tip: The encryption properties of the bitstream must be defined prior to creating the bitstream with the write_bitstream command.

-clear - (Optional) Clear the encryption key from the currently programmed battery-backed SRAM (BBR). Use the -clear option with -key and with the hw_device to clear the encryption key from the BBR.

-user_efuse <arg> - (Optional) Specify a 32-bit value to program into the FUSE_USER eFUSE Register of the hw_device or devices.

-user_efuse_128 <arg> - (Optional) Specify a 128-bit value to program into the FUSE_USER eFUSE Register of the hw_device or devices.

-control_efuse <arg> - (Optional) Specify a value to program into the FUSE_CNTL eFUSE Register of the hw_device or devices. The specified value can be a 14 bit number for 7 series devices, or a 21 bit number for UltraScale™ devices.

-security_efuse <arg> - (Optional) Specify a 256-bit value to program into the security eFUSE Register of the hw_device or devices.

-only_export_efuse - (Optional) Do not program the eFUSE registers; just export the eFUSE settings to the file specified by -efuse_export_file. This lets you check the eFUSE programming for the device before committing it to the eFUSE registers.

-svf_file <arg> - (Optional) Create an SVF output file while programming the device. The SVF file can be used by third party tools, and also supports JTAG transaction tracing and improving Bullseye coverage. You can also generate an SVF file from a programmed hw_device using the write_hw_svf command.

Note: If the path is not specified as part of the file name, the file will be written into the current working directory, or the directory from which the tool was launched.

-efuse_export_file <arg> - (Optional) Specifies an output file (.nkz) to write the current eFUSE settings. If this option is not specified, the current eFUSE settings will be written to a file named export_<FUSE_DNA>.nkz, where <FUSE_DNA> is the DNA value from the device.

Note: If the path is not specified as part of the file name, the file will be written into the current working directory, or the directory from which the tool was launched.

-disable_eos_check - (Optional) Disables "End of Startup" (EOS) check after programming.

-force - (Optional) Overwrite the specified SVF file or eFUSE file if one already exists.

Tip: If -force is specified with -append, the -append option is ignored, and a new SVF file is created overwriting the existing file.

-append - (Optional) Append the SVF output to the specified file rather than overwriting it.

-type [ bit | bin | rbt ] - (Optional) Specifies the type of bitstream file as either a standard bitstream (.bit), a binary bitstream without header (.bin), or a raw bitstream which is an ASCII file (.rbt).

-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.
Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.

-verbose - (Optional) Displays the eFUSE register values of the programmed hw_device or devices.

<hw_device> - (Optional) One or more hw_device objects to program. The hw_device must be specified as an object as returned by the get_hw_devices command. If the device is not specified, the current_hw_device will be programmed.

Example

The following example sets the current hw_device object, then sets the PROGRAM.FILE property for the device, and programs the device:

current_hw_device [lindex [get_hw_devices] 0]
set_property PROGRAM.FILE {C:/Data/design.bit} [current_hw_device]
program_hw_devices [current_hw_device]

The following example programs the encryption key into the battery-backed RAM (BBR), and then programs the current hw_device:

program_hw_devices -key bbr [current_hw_device]
program_hw_devices [current_hw_device]

The following example writes an SVF file from the programmed device:

program_hw_devices -force -svf_file {C:/Data/test1.svf} [current_hw_device]

This example clears the BBR encryption key programming:

program_hw_devices -key bbr -clear [current_hw_device]