update_clock_routing - 2023.2 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
Release Date
2023.2 English

Update clock routing on global clocks if they are modified after placement


update_clock_routing [‑pin <args>] [‑net <args>] [‑quiet] [‑verbose]


Name Description
[-pin] A single pin (pin should be already unrouted)
[-net] A single net (net should be already unrouted)
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution




The update_clock_routing command is an advanced command used for manually updating the routing structures of all global clocks in designs targeting the UltraScale architecture. The command operates on all global clocks in a design, not individual clocks.

Due to a more flexible clocking architecture, AMD Versal adaptive SoC, AMD UltraScale™, and AMD UltraScale+™ designs require a two-step process for routing global clocks. First the Vivado™ placer assigns the routing resources required to route the global clocks from the clock source to the destination clock regions (CLOCK_ROOT or USER_CLOCK_ROOT). Next the Vivado router fills in the routing gaps on the clock nets. In between these two steps the resulting structures are called gap trees: each global clock net has its base routing resources assigned but with large routing gaps where no routing resources have been assigned.

After gap trees are constructed, the router optimally routes the remaining clock network to all leaf-level primitives to fill in the routing gaps. During an implementation run the global clock routing is handled automatically. However in cases where the clock tree has been changed after implementation, by modifying the USER_CLOCK_ROOT property on a clock net for instance, the Vivado tool may need the update_clock_routing command to properly rebuild the gap trees and fill in the routing gaps.

Examples of this include:

  • Moving the clock root of a global clock.
  • Adding or moving loads of a global clock into a clock region not yet occupied by the global clock, then running timing analysis on the updated design.


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


The following example updates the USER_CLOCK_ROOT property on the specified clock nets, unroutes the nets, and then updates the clock routing:

set_property USER_CLOCK_ROOT X1Y0 [get_nets {clk1 clk2}]
route_design -unroute -nets [get_nets {clk1 clk2}]
Important: The unroute command is needed to clean out existing clock routing on the clock nets before updating the clock routing.