Scoped Queries Guidelines - 2023.2 English

Vivado Design Suite User Guide: Using Constraints (UG903)

Document ID
Release Date
2023.2 English

For this flow to work smoothly, the XDC constraints must be written so that the effects of the constraints stay local to the IP or sub-module instance. The Vivado tools can set the scope of queries to a specific level of the hierarchy as seen previously in Constraints Scoping. When developing constraints for an IP or a sub-level module, you must understand the behavior of the query commands:

  • Cell/net/pin objects queries are limited to the scoped instance and its sub-levels:
    • get_cells/get_nets/get_pins <name pattern>
    • The NAME property of the object shows the full hierarchical path of the object relative to the top-level and not just the scoped instance. If you use the -filter option of the get_* commands on the NAME property, you must use the glob string match operator and provide a pattern that starts with a *. For example:
      get_nets -hierarchical -filter {NAME =~ *clk}
  • get_ports returns a top-level port if the port of the block/IP is directly connected to a top-level port. Otherwise, get_ports returns a hierarchical pin.
  • Netlist helper commands are also scoped:
    • all_ffs, all_latches, all_rams, all_registers, all_dsps, all_hsios return only instances included in the current instance.
  • IO helper commands cannot be used at all in a scoped XDC:
    • all_inputs, all_outputs
  • Clock commands are not scoped and returns all timing clocks of your design.
    • get_clocks, all_clocks
  • Top-level and local clock objects can be queried by probing the netlist with get_clocks -of_objects.
    • Retrieve a clock entering the current instance by using get_clocks -of_objects [get_ports <interfacePinName>].
    • Retrieve a clock automatically generated inside the current instance by using get_clocks -of_objects [get_pins <instName/outPin>], where instName is a clock generator instance.
  • Querying any object in the design is possible using the -of_objects option:
    • Example: get_pins -leaf -of_objects [get_nets local_net]
  • Queries are supported for top-level ports connected to the current instance interface nets:
    get_ports -of_objects [get_nets <scoped_instance_net>]
  • Queries of IP/sub-module interface pins are not allowed:
    • get_pins clk returns an error.
  • Path tracing commands are also scoped:
    • all_fanin/all_fanout traverses the scoped design and stops at its boundary.
  • Use get_cells/get_pins/get_nets with the most specific pattern instead of using the all_registers command with the -clock option to query all the cells connected to a particular clock. The returned list can be very large while only a few objects need to be constrained. This can impact the runtime negatively.