update_macro - 2022.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
Release Date
2022.1 English

Update a macro


update_macro [‑absolute_grid] [‑quiet] [‑verbose] <macro> <rlocs>


Name Description
[-absolute_grid] Use absolute grid for relative locations
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
<macro> Macro to update
<rlocs> a list interleaved instances and site names




Populate a previously created macro with leaf cells and relative placements.

A macro is made up of primitive, or leaf-level logic cells, and their associated connections, positioned in a placement grid. The specified relative locations, or <rlocs>, can be based on a relative grid, or on an absolute grid, called an RPM_GRID. Refer to the Vivado Design Suite User Guide: Implementation (UG904) for more information on absolute and relative placement grids

A cell can only belong to a one macro. If you attempt to assign a leaf-level cell to multiple macros, the Vivado® tool will return an error. If you attempt to assign a non-primitive cell to a macro, the tool will return an error.

To change the contents of an existing macro, you must delete the macro with delete_macro, recreate it with create_macro, and update it with new contents. You cannot simply overwrite or modify an existing macro.


-absolute_grid - (Optional) Use to indicate that the <rlocs> are specified in the absolute RPM_GRID.

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

<macro> - (Required) Specify the name of the macro to update.

<rlocs> - (Required) Specify the leaf-cells to include in the macro, and their relative locations (RLOCs). When -absolute_grid is specified, the location is based on actual device coordinates instead of relative locations. The cells and RLOCs are specified as name-value pairs, with multiple leaf-cells and RLOCs assigned to a single macro as follows:
{cell0 XmYn cell1 XmYn ... cellN XmYn}
  • m = An integer representing the relative or absolute X coordinate of the preceding cell.
  • n = An integer representing the relative or absolute Y coordinate of the preceding cell.
  • Cell coordinates are relative to each other, unless the -absolute_grid option has been specified.
  • The relative coordinates are based on a theoretical array of Slices, located relative to each other.
  • The absolute coordinates are determined by the RPM_X and RPM_Y properties from actual Slices of the target device. These can be determined by the report_property command for selected sites.


The following example creates a macro named usbMacro0, sets the current instance to the usbEngine0/u0 module, assigns three cells to the macro, with a relative placement for each cell to have two of them placed inside the same Slice, and the third placed in a vertically adjacent Slice:
create_macro usbMacro0
current_instance usbEngine0/u0
update_macro usbMacro0 {rx_active_reg X0Y0 \
   rx_err_reg X0Y0 rx_valid_reg X0Y1}
The following example creates a macro named usbMacro1, assigns three cells to the macro using the hierarchical path to the leaf-cell, with absolute coordinates specified for the cells in the macro:
create_macro usbMacro1
set Site1 [get_sites SLICE_X8Y77]
set Site2 [get_sites SLICE_X9Y77]
set Site3 [get_sites SLICE_X8Y78]
set RPM1 X[get_property RPM_X $Site1]Y[get_property RPM_Y $Site1]
set RPM2 X[get_property RPM_X $Site2]Y[get_property RPM_Y $Site2]
set RPM3 X[get_property RPM_X $Site3]Y[get_property RPM_Y $Site3]
update_macro usbMacro1 -absolute_grid "usbEngine1/u0/rx_active_reg $RPM1 \
usbEngine1/u0/rx_err_reg $RPM2 usbEngine1/u0/rx_valid_reg $RPM3"
Note: In the prior example, notice the use of Tcl variables to capture the Sites of interest, and extract the RPM_X and RPM_Y properties of those sites for use in the update_macro command. Also notice the use of quotes ("") instead of curly braces ({}) in the update_macro command. This is to allow the Tcl shell to perform variable substitution of the command. Refer to the Vivado Design Suite User Guide: Using Tcl Scripting (UG894) for more information on variables and variable substitution.
This command reports the properties on the usbMacro1 macro to see the absolute grid coordinates assigned to the cells in the macro:
report_property -all [get_macros usbMacro1]