KEEP_HIERARCHY - KEEP_HIERARCHY - 2025.2 English - UG912

Vivado Design Suite Properties Reference Guide (UG912)
Document ID
UG912
Release Date
2025-11-20
Version
2025.2 English

KEEP_HIERARCHY overrides the default hierarchy preservation that is determined by the value of the synth_design -flatten_hierarchy command option. The default value of this option is rebuilt, which instructs the synthesis tool to flatten the hierarchy, optimize the design and then rebuild the design hierarchy. This is good for design optimizations and debugging.

The KEEP_HIERARCHY property directs the tool to either retain a hierarchy so that optimization does not occur across the hierarchy boundary or flatten the hierarchy so that optimization can occur. Typically keeping hierarchy is useful for assisting floorplanning, analysis, and debugging. Flattening hierarchy can improve optimizations, resulting in a smaller design with fewer logic levels. Setting the KEEP_HIERARCHY value to SOFT behaves similar to TRUE but allows constant propagation across the hierarchical boundary. It is recommend to use SOFT instead of TRUE where the design allows.

Recommended: To avoid the negative effects when using KEEP_HIERARCHY, register all outputs of a module instance in which a KEEP_HIERARCHY is attached. KEEP_HIERARCHY=SOFT is preferred over KEEP_HIERARCHY=TRUE as it allows for constant propagation while still preserving hierarchy.

If KEEP_HIERARCHY constraint should not be used on modules that describe the control logic of 3-state outputs and I/O buffers. It can be applied to the module or architecture level or the instance.

Architecture Support
All architectures.
Applicable Objects
Hierarchical modules (get_cells)
Values
  • TRUE: Preserves the hierarchy by not allowing optimization across the hierarchy boundary.
  • FALSE: Allows optimization across the hierarchy.
  • SOFT: Keeps the hierarchy but allows constant propagation across the boundary.

Syntax

Verilog Syntax

Place the Verilog attribute immediately before the user hierarchy instantiation:

(* KEEP_HIERARCHY = "{TRUE|FALSE|SOFT}" *)

Verilog Syntax Example:

// Preserve the hierarchy of instance CLK1_rst_sync (* KEEP_HIERARCHY = "TRUE" *) reset_sync #(
.STAGES(5)
) CLK1_rst_sync (
.RST_IN(RST | ~LOCKED),
.CLK(clk1_100mhz),
.RST_OUT(rst_clk1)
);

On Module:

(* keep_hierarchy = "yes" *) module bottom (in1, in2, in3, in4, out1, out2);

On Instance:

(* keep_hierarchy = "yes" *)bottom u0 (.in1(in1), .in2(in2), .out1(temp1));
VHDL Syntax

Declare the VHDL attribute as follows:

attribute KEEP_HIERARCHY : string;

Specify the VHDL attribute as follows:

attribute KEEP_HIERACHRY of name: label is "{TRUE|FALSE|SOFT}";

Where name is the instance name of a user defined instance.

VHDL Syntax Example:

attribute KEEP_HIERARCHY : string;
-- Preserve the hierarchy of instance CLK1_rst_sync attribute KEEP_HIERARCHY of CLK1_rst_sync: label is "TRUE";
…
CLK1_rst_sync : reset_sync PORT MAP (
RST_IN => RST_LOCKED,
CLK => clk1_100mhz, RST_OUT	=> rst_clk1
);

On a module:

attribute keep_hierarchy : string;
attribute keep_hierarchy of beh : architecture is "yes";

On an instance:

attribute keep_hierarchy : string;
attribute keep_hierarchy of u0 : label is "yes";
XDC Syntax
set_property KEEP_HIERARCHY {TRUE|FALSE|SOFT} [get_cells instance_name]

Where instance_name is a hierarchical module.

XDC Syntax Example:

# Preserve the hierarchy of instance CLK1_rst_sync 
set_property KEEP_HIERARCHY TRUE [get_cells CLK1_rst_sync]

Affected Steps

  • Synthesis
Related reference