report_bd_diffs - 2023.2 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
Release Date
2023.2 English

Report differences between two block designs. Note this TCL command may compare bus-interface parameters from IP .xit files that are not reported in the stand-alone diffbd executable.


report_bd_diffs [‑format <arg>] [‑file <arg>] [‑open_html] [‑brief]
    [‑strict] [‑fast] [‑return_string] [‑depth <arg>] [‑crossprobe]
    [‑repository <arg>] [‑take_snapshot] [‑diff_snapshot] [‑quiet]
    [‑verbose] <design1> <design2>


0 if no functional differences, >0 if different, -1 on error.


Name Description
[-format] Format: html or text Default: text
[-file] Optional output file name. *.htm* implies HTML format
[-open_html] Open HTML report in a browser. Sets format to HTML
[-brief] Output only whether files differ. Don't write report
[-strict] Non-functional changes are treated as functional changes
[-fast] Read BD JSON directly instead of creating in-memory BDs when possible. Will not compare Bus-Interface parameters from .XIT files (same as stand-alone diffbd)
[-return_string] (Text only) Return the report as a string
[-depth] HTML Display Depth for equal items. Used to limit HTML file size. Does not affect not-equal items. Implies HTML format. Default: 4
[-crossprobe] Enable links on HTML report to select Vivado objects. Implies open_html
[-repository] User repository for designs on disk
[-take_snapshot] Take a snapshot of the current block design
[-diff_snapshot] Compare the current block design against a snapshot
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
<design1> Name or file path of first block design to compare
<design2> Name or file path of second block design to compare




Analyze and report the difference between two block design files (.bd).

Tip: There is also a standalone version of this command, diffbd, that can be run from the command line. You can find out more information about this command by typing diffbd -h from the command line. Refer to the Vivado Design Suite User Guide: Designing IP Subsystems using IP Integrator (UG994) for more informaiton.

This command performs a non-graphical comparison of two block designs to let you compare revisions of a block design from within revision control systems. Block designs must be specified as BD objects, as returned by current_bd_design, or get_bd_designs commands. The design objects can have the same name, but be returned from different .bd files. An error will be returned if the BD objects refer to the same design.

The differences reported include additions, or changes to the IP in use in the block diagram, changes to design properties or parameters, changes to the design hierarchy, changes to connectivity, and changes memory addressing.

This command returns the difference report for the two block designs specified, or returns an error if it fails.


-format [ text | html ] - (Optional) Specifies the format of the difference report as either text, or HTML. Unless the -file option is specified, text format returns the report to the Tcl console by default, and HTML format writes the report to diff.html in the current working directory. The default format is text.

-file <arg> - (Optional) Write the difference report into the specified file. Using a file suffix of .htm implies an HTML output, unless the -format option specifies text.

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.

-open_html - (Optional) Opens the specified HTML report in the default web browser. This option implies a report format of HTML, and cannot be used with -format text.

Note: This option does not support the Internet Explorer or Edge web browsers. You can open the HTML report in these browsers after generation, but the tool will not open them automatically.

-brief - (Optional) Returns a brief message indicating whether the two designs differ, but does not detail how they may differ. Can be used as a pre-check for scripting purposes.

-strict - (Optional) Examines and reports all changes as functional changes, returning a value of 0 if there are no changes. Functional changes have to do with the design itself: objects, connections, parameters. Non-functional changes have to do with the metadata of the BD, such as tool version, and do not result in a difference in functionality in the design. By default only functional changes are reported as differences. However, the use of -strict reports any changes in the difference report.

-fast - (Optional) Perform a quick compare by reading the BD JSON files directly rather than opening in-memory block designs.

-return_string - (Optional) Directs the output to a Tcl string rather than to the standard output. The Tcl string can be captured by a variable definition and parsed or otherwise processed.

Note: This argument cannot be used with the -file option.

-depth <arg> - (Optional) Specifies the depth of the design hiearchy to report when the designs are equal, or matching. Note that any differences in the design will always be reported regardless of this option.

-crossprobe - (Optional) Add cross-probing links to the HTML report format. This allows items from the report to be selected from an open block design. This implies the HTML format and -open_html. This option cannot be used with -format text.

-repository <arg> - (Optional) Specify an IP repository for block designs that include IP from outside the Xilinx™ IP catalog. The location of the IP repository is needed to resolve any references to non-standard IP used in the design.

-take_snapshot - (Optional) Take an in-memory snapshot of the current open block design. This option does not require design names, or additional options.

-diff_snapshot - (Optional) Compare the current open block design against a previous in-memory snapshot of the block design. This lets you see what changes have been made to the block design since the snapshot was taken.

-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.

<design1> - (Optional) specify a block design to diff with a second block design. The block design can be specified by current_bd_design, or get_bd_designs Tcl commands; or can be specified by path and file name.

Note: If the path is not specified with the file name, the file will be looked for in the current project, or the current working directory.

<design2> - (Optional) specify a block design to diff with the first block design. The block design can be specified by current_bd_design, or get_bd_designs Tcl commands; or can be specified by path and file name.


The following example compares the two specified block designs, one from a file path, the second from the current open block design, and creates and opens an HTML report format with the specified depth:

report_bd_diffs C:/Data/ [current_bd_design] \
-file C:/Data/diffs5.htm -open_html -depth 5

The following example takes a snapshot of the current open block design:

report_bd_diffs -take_snapshot