write_bitstream - 2021.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
UG835
Release Date
2021-06-16
Version
2021.1 English

Write a bitstream for the current design

Syntax

write_bitstream [‑force] [‑verbose] [‑raw_bitfile] [‑no_binary_bitfile]
    [‑mask_file] [‑readback_file] [‑logic_location_file] [‑bin_file]
    [‑reference_bitfile <arg>] [‑cell <arg>] [‑no_partial_bitfile] [‑quiet]
    <file>

Usage

Name Description
[-force] Overwrite existing file
[-verbose] Print write_bitstream options
[-raw_bitfile] Write raw bit file (.rbt)
[-no_binary_bitfile] Do not write binary bit file (.bit)
[-mask_file] Write mask file (.msk)
[-readback_file] Write readback files (.rbd, .msd)
[-logic_location_file] Write logic location file (.ll)
[-bin_file] Write binary bit file without header (.bin)
[-reference_bitfile] Reference bitfile to be used for generating partial bitstream
[-cell] Create only partial bitstream for named cell
[-no_partial_bitfile] Do not write partial bit files for a Dynamic Function eXchange design
[-quiet] Ignore command errors
<file> The name of the .bit file to generate

Categories

FileIO

Description

Writes a bitstream file for the current project. This command must be run on an Implemented Design. The bitstream written will be based on the open Implemented Design.

The files that can be generated by the write_bitstream command include the following:
  • Bit file: The binary bitstream file (.bit).
  • Raw (ASCII) Bit file: A raw bit file (.rbt) that contains the same information as the binary bitstream file, but is in ASCII format.
  • Mask file: A mask file (.msk) that has mask data in place of the configuration data in the bitstream file.
  • Logic Location file: An ASCII logic location file (.ll) that shows the bitstream position of latches, flip-flops, LUTs, Block RAMs, and I/O block inputs and outputs.
  • Bin file: A binary file (.bin) containing only the device programming data, without the header information found in the standard binary Bit file.
  • Reference Bit file: An incremental bitstream file containing only the differences from the current bitstream and a specified reference bitstream.
The Vivado tool can write a compressed bitstream, if you have enabled compression by setting the BITSTREAM.GENERAL.COMPRESS property on the implemented design. Refer to the Vivado Design Suite User Guide: Programming and Debugging (UG908) for more information on Device Configuration Properties. To enable compression use the following Tcl command:
set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]

The Vivado Design Suite can also write an encrypted bitstream to protect the intellectual property of the design in the bitstream. To create an encrypted bitstream you must first define the type of encryption to be used, and the encryption key. You can accomplish this 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.

You can also enable encryption by manually defining the appropriate properties on the implemented design as follows:
set_property BITSTREAM.ENCRYPTION.ENCRYPT YES [get_designs impl_1]
set_property BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT EFUSE [get_designs impl_1]
set_property BITSTREAM.ENCRYPTION.KEY0 8675309 [get_designs impl_1]
The properties associated with encryption include:
  • BITSTREAM.ENCRYPTION.ENCRYPT - Enables encryption when generating the bitstream with write_bitstream. This property accepts a value of YES or NO.
  • BITSTREAM.ENCRYPTION.ENCRYPTKEYSELECT - Specifies the method for storing the encryption key on the hardware device. The accepted values are BBRAM and EFUSE, referring to battery-backed SRAM or the eFUSE registers on the 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 User Guide (UG570) or 7 Series FPGAs Configuration User Guide (UG470) for more information on eFUSE registers.
  • BITSTREAM.ENCRYPTION.KEY0 - Specifies the encryption key to apply to the BBRAM, or the eFUSE FUSE_KEY registers on the device. The key can be specified as a 256 bit value, and will be required when accessing an encrypted bitstream to program, verify, or readback the hw_device.
    Tip: The write_bitstream command will write an NKY file of the same name as the bitstream file (with the .nky extension) when the BITSTREAM.ENCRYPTION.KEY0 property is specified. This encryption file can then be used in other designs by setting the BITSTREAM.ENCRYPTION.KEYFILE property.
  • BITSTREAM.ENCRYPTION.KEYFILE - Specifies an encryption key file (NKY or NKZ) as an alternative to setting the ENCRYPTION.KEY0 property. The specified encryption key file will be used during bitstream encryption.
    Important: If both the BITSTREAM.ENCRYPTION.KEY0 and BITSTREAM.ENCRYPTION.KEYFILE properties are defined, the tool will use the encryption key specified by the BITSTREAM.ENCRYPTION.KEY0 property and return a message to that effect.

Arguments

-force - (Optional) Force the overwrite of an existing bitstream file of the same name.

-verbose - (Optional) Print details of the options applied to the bitstream when running the write_bitsream command.

-raw_bitfile - (Optional) Write a raw bit file (.rbt) which contains the same information as the binary bitstream file, but is in ASCII format. The output file will be named <file>.rbt.

-no_binary_bitfile - (Optional) Do not write the binary bitstream file (.bit). Use this command when you want to generate the ASCII bitstream or mask file, or to generate a bitstream report, without also generating the binary bitstream file.

-mask_file - (Optional) Write a mask file (.msk), which has mask data where the configuration data is in the bitstream file. This file determines which bits in the bitstream should be compared to readback data for verification purposes. If a mask bit is 0, that bit should be verified against the bitstream data. If a mask bit is 1, that bit should not be verified. The output file will be named <file>.msk.

-readback_file - (Optional) Lets you perform the Readback function by creating the necessary readback files (.rbd, .msd).
  • .rbd - An ASCII file that contains only expected readback data, including pad words and frames. No commands are included.
  • .msd - An ASCII file that contains only mask information for verification, including pad words and frames. No commands are included.

-logic_location_file - (Optional) Creates an ASCII logic location file (.ll) that shows the bitstream position of latches, flip-flops, LUTs, Block RAMs, and I/O block inputs and outputs. Bits are referenced by frame and bit number in the location file to help you observe the contents of FPGA registers.

-bin_file - (Optional) Creates a binary file (.bin) containing only device programming data, without the header information found in the standard bitstream file (.bit).

-reference_bitfile <arg> - (Optional) Read a reference bitstream file, and output an incremental bitstream file containing only the differences from the specified reference file. This partial bitstream file can be used for incrementally programming an existing device with an updated design.

-cell <arg> - (Optional) Write a partial bitstream file for the specified cell or block level of the design hierarchy. The bitstream file will only include programming data for the specified cell or module.

-no_partial_bitfile - (Optional) Do not output a partial bit file for a Partial Reconfiguration module or design. Refer to the Vivado Design Suite User Guide: Dynamic Function eXchange (UG909) for more information on the PR flow.

-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.
<file> - (Required) The name of the bitstream file (.bit) to write. If you do not specify a file extension, the .bit extension will be added by the tool, but you cannot specify an extension other than .bit.
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.

Examples

The following example enables compression and writes a bitstream file of the specified name:
set_property BITSTREAM.GENERAL.COMPRESS TRUE [current_design]
write_bitstream design1.bit
The following example writes both the binary and ASCII forms of the bitstream:
write_bitstream -raw_bitfile C:/Data/design1
Note: The appropriate file extension will be added by the tool.