FPGA 进阶 36：RTL 复用与参数化——写一次、配 N 次

本文是 fpga/ 进阶层第 40 篇。参数化思维贯穿全系列：FIFO、异步 FIFO、BRAM 都该是可配置模块。打包 IP 后在块设计 IPI里复用；自检方法见高级 Testbench。

本文要回答的问题

• parameter/localparam 怎么组织？为什么别用 `define？
• generate for/if 生成硬件的正确姿势？
• 参数化模块怎么防呆、怎么验证多配置？
• 成熟模块怎么打包 IP 给团队？

一、参数化三件套

module sync_fifo #(
  parameter WIDTH = 8,            // 数据位宽, 可覆盖
  parameter DEPTH = 16,           // 深度(须为 2 的幂)
  parameter              // 功能开关
  localparam AW = $clog2(DEPTH)   // 派生: 地址位宽, 外部不可改
)(
  input  wire             clk,
  input  wire             rst_n,
  input  wire             wr_en,
  input  wire [WIDTH-1:0] wr_data,
  input  wire             rd_en,
  output wire [WIDTH-1:0] rd_data,
  output wire             full,
  output wire             empty
);
  // 参数防呆: 非法配置仿真期直接报错
  initial begin
    if (DEPTH < 2 || (DEPTH & (DEPTH-1)) != 0)
      $error("DEPTH must be power of 2 and >= 2");
  end

  reg [WIDTH-1:0] mem [0:DEPTH-1];
  reg [AW:0]      wr_ptr, rd_ptr;   // 多 1 位做满/空判断
  // ... 读写逻辑 ...
endmodule

例化时命名传参（不用 defparam）：

sync_fifo #(.WIDTH(32), .DEPTH(256)) u_fifo ( ... );

二、generate：按参数生成硬件

// 例1: N 级同步器阵列——空间复制
genvar i;
generate
  for (i = 0; i < STAGES; i++) begin : g_sync
    always @(posedge clk or negedge rst_n)
      if (!rst_n) sync_q[i] <= 1'b0;
      else        sync_q[i] <= (i==0) ? d_in : sync_q[i-1];
  end
endgenerate

// 例2: 条件例化——带不带 FIFO 两种实现
generate
  if (USE_FIFO) begin : g_with_fifo
    async_fifo #(.WIDTH(W), .DEPTH(16)) u_fifo ( ... );
  end else begin : g_passthrough
    assign out_data = in_data;  // 直连
  end
endgenerate

结构	用途
generate for（genvar）	静态展开 N 份硬件：寄存器阵列、总线切片、多通道
generate if	按参数选实现：功能开关、资源选型（BRAM/分布式）
always for	同一块逻辑内重复赋值（组合逻辑、归约运算）

三、工程化清单

1. 魔数清零：位宽/深度/阈值全参数化，派生量用 localparam；
2. 默认可用：默认参数开箱即用，例化不传参也合法；
3. 防呆断言：参数非法（DEPTH 非 2 幂、WIDTH≤0）仿真即 $error；
4. 位宽一致：端口和内部信号引用参数，改参数全联动，杜绝隐式截断；
5. 参数化 TB：testbench 共享参数，回归多组配置（8/16/32bit、浅/深 FIFO）；
6. 文档头：模块功能、参数表、时序图、例化示例写在注释里；
7. 版本：入库带 changelog，破坏性改参数升版本。

四、打包成 Vivado IP（IP Packager）

1. 模块工程里 Tools → Create and Package New IP；
2. 工具识别接口：AXI/AXI-Stream/clock/reset 加接口元数据（块设计里才能自动连线、出地址映射）；
3. 参数暴露到 GUI：选哪些参数用户可配、给范围和默认值；
4. 加 XDC 约束模板、例化模板、文档链接；
5. 打包到团队 IP repository，块设计中像官方 IP 一样调用；
6. 后续维护走 IP 版本号与升级流程（与工程/IP 版本管理篇衔接）。

常见坑对照

坑	后果	正确做法
魔数散落 always	改位宽漏改多处	全参数化 + localparam 派生
`define 当参数	全局污染、实例不可配	parameter 模块级配置
generate 块不命名	仿真层次混乱	begin: g_name
参数改了 TB 没改	验证的是旧配置	TB 共享参数、多配置回归
DEPTH 非 2 幂无检查	满空逻辑错	initial/generate 断言
位宽硬编码 [7:0]	换参数后截断	[WIDTH-1:0]
复制粘贴改模块	分支越来越多修不动	generate-if 功能开关

相关与延伸

应用范例：FIFO 设计、异步 FIFO、BRAM 存储。 复用后：块设计 IPI、高级 Testbench 多配置回归；工程版本管理见后续《工程与 IP 版本管理》。

一句话总结

RTL 复用的核心是"写一次、参数配 N 次"：位宽/深度/阈值/功能开关全部 parameter 化（外部可覆盖），派生量用 localparam（如 AW=$clog2(DEPTH)），魔数和 `define 全局宏都是维护陷阱。generate-for 在综合前静态展开成 N 份物理硬件（同步器阵列、多通道、寄存器堆），generate-if 按参数选实现（带/不带 FIFO、BRAM/分布式 RAM），always 里的 for 只是同一逻辑内的重复赋值。工程化：默认参数开箱即用、非法参数 initial/generate 断言防呆、位宽全部从参数派生、testbench 共享参数做多配置回归。成熟模块按 rtl/sim/tcl/doc 入库，或用 IP Packager 打包（识别 AXI/时钟/复位接口元数据、参数暴露到 GUI、带 XDC 模板）发布到团队 IP 仓库，在块设计里像官方 IP 一样复用。