在 Verilog 中，(* keep_hierarchy="yes" *) 是一个 层次保留属性，用于指示综合工具保持模块的层次结构，不将其展平或优化到其他模块中。

一、作用与含义

这个属性强制要求工具：

• 保持层次：防止模块边界被打破

• 禁止展平：阻止模块被合并到父模块中

• 独立优化：在每个模块内部独立进行优化

• 便于调试：保持与原始RTL相同的层次结构

二、语法格式

// 用于模块定义
(* keep_hierarchy = "yes" *)
module my_module (...);

// 用于模块实例（某些工具）
(* keep_hierarchy = "yes" *)
module_name instance_name (...);

三、使用场景

1. 保护IP核和子模块

(* keep_hierarchy = "yes" *)
module dsp_multiplier (
    input [15:0] a,
    input [15:0] b,
    output [31:0] p
);
    // DSP48E1 或其他专用硬件的映射
    assign p = a * b;
endmodule

module top_design (
    input [15:0] data_a,
    input [15:0] data_b, 
    output [31:0] result
);

// 这个实例的层次结构会被保留
dsp_multiplier u_mult (
    .a(data_a),
    .b(data_b),
    .p(result)
);

endmodule

2. 保持功能模块的独立性

(* keep_hierarchy = "yes" *)
module fifo_controller (
    input clk,
    input rst_n,
    input wr_en,
    input rd_en,
    input [7:0] data_in,
    output [7:0] data_out,
    output full,
    output empty
);
    
    reg [7:0] mem [0:15];
    reg [3:0] wr_ptr, rd_ptr;
    reg [4:0] count;
    
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            wr_ptr <= 0;
            rd_ptr <= 0;
            count <= 0;
        end else begin
            // FIFO 控制逻辑...
        end
    end
    
    assign full = (count == 16);
    assign empty = (count == 0);
    
endmodule

3. 分层设计中的关键模块

(* keep_hierarchy = "yes" *)
module aes_encryption_round (
    input [127:0] data_in,
    input [127:0] round_key,
    output [127:0] data_out
);
    
    wire [127:0] sub_bytes_out;
    wire [127:0] shift_rows_out;
    wire [127:0] mix_columns_out;
    
    // AES 轮函数...
    sub_bytes u_sub (.data_in(data_in), .data_out(sub_bytes_out));
    shift_rows u_shift (.data_in(sub_bytes_out), .data_out(shift_rows_out));
    mix_columns u_mix (.data_in(shift_rows_out), .data_out(mix_columns_out));
    
    assign data_out = mix_columns_out ^ round_key;
    
endmodule

四、完整的实际示例

// 通信接收机分层设计
(* keep_hierarchy = "yes" *)
module synchronizer (
    input clk,
    input rst_n,
    input async_signal,
    output sync_signal
);
    
    reg sync_reg1, sync_reg2;
    
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            sync_reg1 <= 1'b0;
            sync_reg2 <= 1'b0;
        end else begin
            sync_reg1 <= async_signal;
            sync_reg2 <= sync_reg1;
        end
    end
    
    assign sync_signal = sync_reg2;
    
endmodule

(* keep_hierarchy = "yes" *)
module deserializer (
    input clk,
    input serial_data,
    output [7:0] parallel_data
);
    
    reg [7:0] shift_reg;
    
    always @(posedge clk) begin
        shift_reg <= {shift_reg[6:0], serial_data};
    end
    
    assign parallel_data = shift_reg;
    
endmodule

module uart_receiver (
    input clk,
    input rst_n,
    input rx_data,
    output [7:0] received_data,
    output data_valid
);
    
    wire synchronized_rx;
    
    // 这些子模块的层次结构会被保留
    synchronizer u_sync (
        .clk(clk),
        .rst_n(rst_n),
        .async_signal(rx_data),
        .sync_signal(synchronized_rx)
    );
    
    deserializer u_deser (
        .clk(clk),
        .serial_data(synchronized_rx),
        .parallel_data(received_data)
    );
    
    // 其他控制逻辑...
    
endmodule

五、应用场景详解

1. 便于时序约束

(* keep_hierarchy = "yes" *)
module clock_domain_crossing (
    input src_clk,
    input dst_clk,
    input [31:0] src_data,
    output [31:0] dst_data
);
    
    // CDC 逻辑...
    // 保持层次便于添加跨时钟域约束
    
endmodule

2. 模块复用和团队协作

(* keep_hierarchy = "yes" *)
module eth_mac_controller (
    input clk_125m,
    input rst_n,
    input [7:0] tx_data,
    output [7:0] rx_data,
    // 其他以太网MAC接口...
);
    
    // 以太网MAC控制器实现
    // 保持层次便于在不同项目中复用
    
endmodule

3. 物理规划保留

(* keep_hierarchy = "yes" *)
module ddr_phy_interface (
    input mem_clk,
    input [63:0] write_data,
    output [63:0] read_data
);
    
    // DDR物理层接口
    // 保持层次便于物理布局规划
    
endmodule

六、相关属性对比

属性	描述	作用层次
keep_hierarchy="yes"	保持模块层次结构	模块级别
dont_touch="true"	禁止优化逻辑	模块、实例、信号级别
black_box="true"	视为黑盒	模块级别
buffer_type="none"	禁止插入缓冲器	端口级别

七、工具特定语法

1. Xilinx Vivado

(* keep_hierarchy = "yes" *)        // 推荐写法
(* keep_hierarchy = "soft" *)       // 软约束，允许在必要时展平
(* keep_hierarchy = "no" *)         // 允许展平（默认行为）

2. Synopsys Design Compiler

(* syn_hier = "hard" *)             // 硬层次保留
(* syn_hier = "soft" *)             // 软层次保留

八、多属性组合使用

(* keep_hierarchy = "yes", dont_touch = "true" *)
module critical_submodule (
    input clk,
    input [15:0] data_in,
    output [15:0] data_out
);
    // 既保持层次又禁止优化
    // ...
endmodule

九、注意事项

1. 性能影响：过度使用可能影响综合优化效果

2. 面积代价：可能阻止跨模块优化，增加资源使用

3. 时序考虑：保持层次可能影响时序优化

4. 调试优势：显著改善调试和分析的便利性

十、典型工作流程

// 1. 在关键模块定义时添加属性
(* keep_hierarchy = "yes" *)
module algorithm_core (...);

// 2. 综合时工具保持模块边界
// 3. 实现阶段维持层次结构
// 4. 便于模块级时序约束和物理规划

十一、实际工程应用

// 大型SoC设计中的层次保留
(* keep_hierarchy = "yes" *)
module cpu_core (
    input clk,
    input rst_n,
    input [31:0] instruction,
    output [31:0] result
);

(* keep_hierarchy = "yes" *)  
module dma_controller (
    input clk,
    input [31:0] src_addr,
    input [31:0] dst_addr
);

module soc_top (
    input system_clk,
    input system_rst_n
);
    
    cpu_core u_cpu (.clk(system_clk), .rst_n(system_rst_n), ...);
    dma_controller u_dma (.clk(system_clk), ...);
    // 其他模块...
    
endmodule

这个属性在以下情况下特别有用：

• 大型分层设计项目

• IP核集成和复用

• 跨团队协作开发

• 需要模块级时序约束的设计

• 物理规划驱动的设计

• 调试和分析复杂系统