3. RTL设计可调试性规划

在AMD FPGA项目中，调试成本往往在时序收敛之后才真正暴露：当设计已经跑上板卡、ILA抓不到想要的波形、信号被综合优化掉、层级被拉平、命名混乱导致找不到观测点时，工程师只能反复改RTL、重跑综合实现，单次迭代可能消耗数小时。可调试性规划的核心思想，是把"将来要观测什么、从哪里观测、用什么核观测"提前到RTL编写阶段决定，让调试基础设施成为设计的一部分，而不是事后补丁。

调试信号预留：让观测点先存在

Vivado的综合与实现会 aggressively 优化掉无负载逻辑、常量传播、寄存器合并。一个内部状态机信号如果没有被输出端口或调试核引用，很可能在网表中直接消失，Mark Debug时提示"signal not found"。因此调试信号预留的第一步，是识别"关键可观测点"并保证它们不被优化。

典型需要预留的信号包括：状态机当前状态与下一状态、握手协议的valid/ready、FIFO的读写指针与空满标志、计数器溢出、CRC校验失败、跨时钟域同步器的两级输出、DDR/MIG的校准完成与错误标志、以及各模块的error/exception脉冲。对这些信号，推荐使用 (* keep = "true" *) 或 (* dont_touch = "true" *) 属性，或将其接入一个始终存在的调试观测寄存器组。

(* keep = "true" *) reg [3:0]  state_cur, state_nxt;
(* keep = "true" *) reg        rx_valid, rx_ready;
(* mark_debug = "true" *) reg [15:0] crc_err_cnt;

// 调试观测寄存器组：保证信号在网表中存活
(* keep = "true" *) reg [31:0] dbg_probe0;
always @(posedge clk) dbg_probe0 <= {state_cur, rx_valid, rx_ready, 16'd0} | crc_err_cnt;

需要注意，keep会阻止优化但会增加面积与布线压力，不应无差别地给所有信号加属性。建议按"调试优先级"分级：P0为必须观测（状态机、错误标志），P1为按需观测（数据通路中间值），P2为临时观测（仅在特定bug复现时启用）。P0信号常驻预留，P1/P2通过参数化宏在调试版本中打开。

层次化设计与调试边界

Vivado的Mark Debug与ILA插入都依赖层次结构。如果综合时使用了 -flatten_hierarchy full，模块边界消失，跨模块信号无法在综合后网表中按层次定位，调试核只能挂在顶层端口或已被拉平的内部节点上，可读性极差。推荐在调试阶段使用 -flatten_hierarchy none 或 rebuilt，保留关键模块边界。

层次化设计还应遵循"调试边界"原则：每个功能模块对外暴露一组标准调试接口，例如 dbg_state、dbg_err、dbg_cnt，由顶层统一汇聚到调试核。这样即使模块内部被优化，边界信号仍然可观测。下图给出一个典型的可调试性规划结构：左侧为RTL层次与预留信号，右侧为调试核插入位置与观测路径。

信号命名规范：让调试核里的名字可读

ILA波形窗口里如果出现 n_0、u_1、tmp_23，调试效率会急剧下降。命名规范的目标是让综合后网表中的信号名仍然可读、可搜索、可分组。推荐采用"模块前缀_功能_方向"结构，例如 rx_state_cur、tx_fifo_full、cdc_sync_ff2。方向后缀统一为 _i（输入）、_o（输出）、_r（寄存器）、_n（组合）。

对于调试核的probe命名，建议与RTL信号名保持一致，并在ILA IP配置中启用"probe name"而非默认 probe0。这样在波形中可以直接按 rx_state_cur 搜索，而不是逐个展开 probe0[3:0]。同时，同一模块的调试信号应集中声明，便于用 mark_debug 批量标记。

Mark Debug与调试核插入策略

Vivado提供两条主要路径：一是在RTL中直接写 (* mark_debug = "true" *)，综合后自动出现在Debug窗口中；二是在综合后网表中手动Mark Debug，再通过Set up Debug向导插入ILA。前者适合设计阶段就确定的P0信号，后者适合临时排查、不想改RTL的场景。

调试核插入策略需要权衡资源与观测能力。ILA的采样深度、probe数量、触发条件都会消耗BRAM和LUT。一个典型配置：采样深度1024、4个probe、每个probe 16位，约消耗2~4个BRAM36。如果同时插入多个ILA，资源可能挤占功能逻辑，导致时序恶化。推荐策略是：P0信号用一个ILA集中观测，P1信号按调试阶段分批插入，P2信号用VIO动态读写，避免一次性铺开。

一个可复用的调试规划检查表

可调试性规划不是额外负担，而是把调试从"事后救火"变成"设计内建能力"。当信号预留、层次边界、命名规范和调试核策略在RTL阶段就确定下来，后续的时序收敛与系统验证才能把精力集中在真正的功能问题上，而不是反复与工具优化和信号丢失作斗争。