readback_hw_cfgmem - 2024.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
Release Date
2024.1 English

Readback data from the hw_cfgmem object


readback_hw_cfgmem [‑checksum] [‑force] [‑all] [‑offset <arg>] ‑file <arg>
    [‑format <arg>] [‑datacount <arg>] [‑quiet] [‑verbose] [<hw_cfgmem>...]


Name Description
[-checksum] readback and calculate checksum; cannot be used with -file option
[-force] force write of file
[-all] specify readback of all memory locations
[-offset] memory offset value Default: 0x0
-file File to write readback to
[-format] File format of readback file
[-datacount] number of data units to readback Default: 0x0
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
[<hw_cfgmem>] list of hardware cfgmems Default: current hardware cfgmem




Read programming data off of the hardware configuration memory device, specified as a hw_cfgmem object.

This command reads back the memory configuration file data programmed into a flash memory device by the program_hw_cfgmem command and writes it to the specified file. The memory configuration file is created by the write_cfgmem command and combines the bitstream (.bit) file, and any specified data files, into the memory configuration file format.

Readback is the process of reading data from the configuration memory device to verify that the bitstream and any additional data files were properly programmed into the flash memory device.


-checksum - (Optional) Calculate a checksum for the bitstream from the device.

-force - (Optional) Force the overwriting of the specified file if one of the same name already exists.

-all - (Optional) Read back all the address locations on the configuration memory device.

Tip: By default only the addresses defined by the configuration memory file (PROGRAM.FILE) of the specified hw_cfgmem object will be read back, although this can be affected by the -offset and -datacount options.

-offset <arg> - (Optional) Memory address offset value to begin reading back from. The default offset address is 0x0.

-file <arg> - (Required) Write the data read back from the hw_cfgmem object to the specified file. The readback file is similar to the MCS file created by the write_cfgmem command. The filename suffix should be either .mcs or .bin to reflect the format of the contents.

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.

-format [ mcs | bin ] - (Optional) File format of the readback file to create. The default format is MCS.

-datacount <arg> - (Optional) Specify the number of bytes to read back. The default is to read all data starting from the address specified by the -offset option.

-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) Temporarily override any message limits and return all messages from this command.
Note: Message limits can be defined with the set_msg_config command.

<hw_cfgmem> - (Optional) The hw_cfgmem object to read the data back from. The hw_cfgmem must be specified as an object as returned by the get_hw_cfgmems or current_hw_cfgmem commands. If the hw_cfgmem is not specified, the current_hw_cfgmem will be used.


The following example creates a hw_cfgmem object associated with the current_hw_device; sets a property defining the memory configuration file (PROGRAM.FILE) previously created from the bitstream with the write_cfgmem command; sets other properties of the hw_cfgmem object for use during the readback process; and programs the current hw_device with the cfgmem bitstream:

create_hw_cfgmem -hw_device [current_hw_device] \
   [lindex [get_cfgmem_parts {n25q128-3.3v-spi-x1_x2_x4}] 0]
set cfgMem [current_hw_cfgmem]
set_property PROGRAM.FILE {C:/Data/config_n25q128.mcs} $cfgMem
set_property PROGRAM.ADDRESS_RANGE  {use_file} $cfgMem
set_property PROGRAM.BLANK_CHECK  1 $cfgMem
set_property PROGRAM.ERASE  1 $cfgMem
set_property PROGRAM.CFG_PROGRAM  1 $cfgMem
set_property PROGRAM.VERIFY  1 $cfgMem
create_hw_bitstream -hw_device [current_hw_device] \
   [get_property PROGRAM.HW_CFGMEM_BITFILE [current_hw_device]]
program_hw_devices [current_hw_device]
Note: The hw_cfgmem object is assigned to the Tcl variable $cfgMem.

The following example reads back the current hw_cfgmem object using the addresses defined in the object's PROGRAM.FILE property:

readback_hw_cfgmem -format mcs \
   -file C:/Data/design1.mcs [current_hw_cfgmem]

The following example reads back all the addresses from the current hw_cfgmem object, starting at address 0 and up to the maximum memory depth:

readback_hw_cfgmem -all -format mcs \
   -file C:/Data/design1.mcs [current_hw_cfgmem]

The following example reads back a select range of addresses from the current hw_cfgmem object:

readback_hw_cfgmem -offset 0x084 -datacount 100 -format mcs \
   -file C:/Data/design1.mcs [current_hw_cfgmem]