简介：这份PDF是Synopsys于2021年9月发布的HAPS原型验证平台调试工具官方用户手册，面向使用HAPS平台进行硬件原型设计与验证的工程师，尤其是需要掌握protocompiler debugger的中高级调试人员。手册系统讲解断点设置、内存查看与修改、信号变化跟踪、执行流程分析等核心调试功能，并涵盖错误处理、性能优化与调试技巧等实践内容，可帮助读者在原型验证阶段快速定位设计问题、提升调试效率。资源包共1个PDF文件，大小约2.31MB，单文件结构便于直接检索与查阅。目前已有785人学习，适合正在使用或计划上手HAPS平台调试工具的硬件工程师作为案头参考。

1. 拿到一份 150 页的 HAPS 调试手册，先别急着翻目录

FPGA 原型验证做到一定规模，最让人头疼的不是综合跑不通，而是板子跑起来了、波形却抓不到——信号在片内飞，逻辑分析仪接不进去，只能靠 LED 和串口打印猜。HAPS 平台配套的 Prototyping Debugger 就是冲着这个场景来的：它把 IICE（Integrated Instrumentation and Communication Engine）硬件探针嵌进设计里，让你在 PC 端设断点、设观察点、抓采样、看波形，相当于给原型板装了一套片内逻辑分析仪。这份 2021 年 9 月的用户手册，覆盖了从 Instrumentor 插桩、Debugger 启动、Deep Trace Debug 深存储抓取，到板级 bring-up 自检命令、IICE 状态机触发、GUI 面板操作和 Tcl 脚本自动化的完整链路。适合正在用 HAPS 做大规模 SoC 原型、需要定位偶发时序问题的验证工程师；也适合刚接手 HAPS 流程、被一堆haps子命令和 idc 文件搞晕的新人。下面按“这份文档怎么落地”拆开讲。

2. 插桩到调试的完整链路：idc 文件是怎么生成的

HAPS 调试不是打开软件就能抓信号，它有一条硬性的前置链路：先插桩、再编译、最后调试。手册第 1 章开篇就点明，Debugger 与 Instrumentor、ProtoCompiler 是强绑定的，跳过前两步，Debugger 里连设计都打不开。这条链路里最容易翻车的是插桩阶段——信号选多了资源爆掉，选少了关键节点抓不到，idc 文件生成后改一次就要重跑一遍综合，时间成本很高。

2.1 Instrumentor 插桩与 idc 约束文件

Instrumentor 的作用是把你关心的 RTL 信号标记出来，生成一份 instrumentation design constraints（idc）文件。这份文件本质上是“我要看哪些信号、在什么层次、用什么采样深度”的声明，ProtoCompiler 读它来决定 IICE 资源怎么分配。常见做法是在 RTL 里用属性或者单独的约束文件指定信号路径，Instrumentor 扫描后输出 idc。这里有个血泪经验：信号路径必须写全层次，用通配符虽然方便，但容易把整个总线都卷进来，一个*data*可能让 IICE 资源直接告急。

插桩阶段的核心参数是采样深度和信号位宽。深度决定你能往回看多少个时钟周期，位宽决定每个采样点占多少存储。两者相乘就是 IICE 的存储开销，超过板卡容量，ProtoCompiler 会在编译阶段报资源不足。我一般会先按“最关心的 20 个信号、深度 1024”起步，跑通后再逐步加，而不是一上来就全量插桩。

# 典型插桩流程（命令名以实际安装为准，此处示意调用顺序） # 1. 准备信号约束，列出需要观测的层次化信号 cat > debug_signals.txt <<'EOF' top.u_dut.u_ctrl.state top.u_dut.u_ctrl.cnt top.u_dut.u_arb.grant EOF # 2. 调用 Instrumentor 生成 idc 文件 instrumentor -design top.v -signals debug_signals.txt -out top.idc # 3. 用 ProtoCompiler 带 idc 编译，生成可调试的位流 protocompiler -design top.v -idc top.idc -board haps80 -out ./build

上面三步里，第一步的信号清单是人工维护的核心资产，建议纳入版本管理；第二步的-out指定 idc 输出路径，后续 ProtoCompiler 通过-idc引用；第三步的-board必须和实际板卡型号一致，板型填错会导致 IICE 资源映射对不上，Debugger 启动时报“找不到调试核”。编译完成后，输出目录里会带一份调试数据库，Debugger 打开设计时读的就是它。

2.2 Debugger 启动与设计加载

Debugger 启动前有两个硬前提：ProtoCompiler 编译已经带 idc 完成，且目标板卡通过通信接口（UMRBus 或以太网）可达。手册第 5 章专门讲了通信连接，实际排错时八成的“连不上”都出在通信层，而不是调试逻辑本身。启动后第一步是 Open Design，指向编译输出目录，Debugger 会解析里面的调试数据库，把可观测信号树加载到 Hierarchy Browser。

配置环节要关注采样缓冲区和触发位置。采样缓冲区大小受 IICE 实际分配限制，设太大软件会拒绝；触发位置决定缓冲区里“触发点之前”和“之后”各占多少比例，默认居中，抓偶发问题一般把触发点往后挪，让触发前的现场多留一些。这一步的参数在 GUI 的 Setup Panel 里改，也可以通过 Tcl 脚本批量设置，后面第 6 章会展开。

2.3 断点、观察点与采样压缩

断点（Breakpoint）和观察点（Watchpoint）是两种不同的触发语义：断点看条件成立即停，观察点看信号值变化或匹配特定值。手册第 4 章把这两类归到 IICE 硬件描述里，说明它们最终都落到硬件比较器上，所以数量受 IICE 比较器资源限制，不是想设多少设多少。多个断点同时激活时，触发逻辑是“或”关系，任何一个命中都会停，这点在排查多条件问题时要注意，别以为设了三个断点就能抓“三个同时成立”。

采样压缩（Compressing Sample Data）是省存储的手段：当信号长时间不变时，只存变化点而不是每个时钟都存。开启后同样深度能覆盖更长的时间窗，代价是回放时时间轴不是等间隔的，看波形要留意压缩标记。我一般在对“偶发、间隔长”的问题上用压缩，对“连续高速”的问题上关压缩，保证每个周期都有采样。

3. Deep Trace Debug 与板级 bring-up：抓得深、查得清

普通 IICE 采样受片内存储限制，深度有限。Deep Trace Debug（DTD）把采样数据往板载 DDR3 或外部存储里灌，换来数量级更大的抓取深度，代价是配置更复杂、对硬件版本有要求。这一章把 DTD 的存储配置和板级自检命令放在一起讲，因为实际项目里这两件事经常连着做：板子刚回来先跑 bring-up 自检确认硬件没问题，再上 DTD 抓深存储。

3.1 DTD 存储配置与多 FPGA 场景

手册第 2 章把 DTD 分成两类运行方式：基于 DDR3 内存的，和基于多 FPGA DTD 模块的。前者适合单板大深度抓取，后者适合多片 FPGA 协同的原型系统，采样数据分散在各片的 DTD 模块里，查看时要在 Debugger 里做跨片对齐。配置 DTD 前必须先跑硬件配置校验（Verifying the Hardware Configuration），确认 DDR3 训练通过、DTD 模块被正确识别，否则抓出来的数据是错的，而且错得很隐蔽——波形看着有，但和实际逻辑对不上。

DTD 的关键参数是采样深度和存储分区。DDR3 容量大，但被多个用途共享，分配给 DTD 的区间要在配置里显式划定，划小了抓不够，划大了影响其他功能。多 FPGA 场景还要注意各片 DTD 的触发同步，触发信号要跨片分发，否则各片各抓各的，时间戳对不齐。常见做法是选一片做主触发源，其余片配置为从触发，主片命中后广播触发事件。

# DTD 配置示意（Tcl 脚本方式，参数名以实际版本为准） # 指定 DTD 使用 DDR3 存储，划分采样区间 dtd configure -memory ddr3 -base 0x40000000 -size 256MB # 设置采样深度与触发位置（触发点靠后，多留触发前现场） dtd set -depth 1048576 -trigger_pos 0.8 # 多 FPGA：本片为主触发，其余片从触发 dtd trigger -mode master -broadcast on

这段脚本里，-base和-size划定 DDR3 给 DTD 的区间，必须和板级内存映射一致，填错会踩到别的功能区域；-depth是采样点数，受-size约束；-trigger_pos 0.8表示触发点位于缓冲区 80% 处，前面留 80% 的历史现场，适合抓“问题发生前发生了什么”；-mode master配合-broadcast on解决多片同步。跑完 DTD 后，用 Viewing Captured Deep Trace Debug Samples 把数据导回 Debugger 查看，导出过程可能耗时较长，深度越大越慢，别在导出时反复点，容易把会话搞挂。

3.2 板级 bring-up 自检命令清单

手册第 3 章是一份很实用的板级自检命令表，板子刚回来或者怀疑硬件问题时，按这张表跑一遍能快速定位是板子坏还是设计错。这些命令通过haps工具调用，覆盖时钟、连接、电气、速率、DDR4、互联、线缆、回环、LED/按键、复位、SPI Flash、UMR 等检查项。下面挑几个高频的列出来，参数和用途对照手册整理：

这些命令大多有公共参数（Common Parameters for Bring-up Utilities），比如指定板卡槽位、日志输出路径、详细级别。跑自检时建议加详细日志，出问题时日志就是黑匣子。haps boardstatus可以一次性看板卡整体状态，haps prog负责位流下载，haps setvcc/haps setclk调电压和时钟，haps clear清状态，haps confscr管配置脚本，haps tssgen生成时序，haps hstdm_report出 HSTDM 报告。这些工具命令是 bring-up 阶段的后悔药，板子行为诡异时先跑一遍再怀疑设计。

# bring-up 自检典型顺序（命令与参数以实际安装版本为准） haps boardstatus -board haps80 -slot 1 # 先看整体状态 haps clock_check -board haps80 -slot 1 -verbose # 时钟是根基，先查 haps con_check -board haps80 -slot 1 # 再查连接 haps DDR4_selftest -board haps80 -slot 1 -loops 3 # 内存多跑几轮 haps reset_check -board haps80 -slot 1 # 复位网络 haps spi_flash_memory_check -board haps80 -slot 1 # Flash 读写

顺序上先查时钟再查连接，是因为时钟不对后面全白搭；DDR4 自检多跑几轮（-loops）是为了抓偶发错误，单轮通过不代表稳定；-verbose打开详细输出，失败时能看到具体哪个通道、哪个引脚出问题。每条命令失败后先看日志里的具体通道号，再对照板卡原理图定位，别一上来就换板子。

4. IICE 硬件描述：断点、观察点与状态机触发怎么配

IICE 是 HAPS 调试的硬件底座，断点、观察点、采样、复杂计数器、状态机触发全都跑在它上面。理解它的资源模型，才能解释“为什么断点设不下去”“为什么触发条件写了不生效”。手册第 4 章把 IICE 拆成断点/观察点块、采样块、复杂计数器、状态机触发几部分，这一章按“资源怎么分、条件怎么写、状态机怎么搭”来讲。

4.1 断点与观察点的资源模型

断点和观察点最终都映射到 IICE 里的硬件比较器。每个比较器能比较一定位宽的信号，多个比较器可以组合成更宽的比较或更复杂的条件。资源有限意味着：你不能同时设几十个断点，也不能对超宽总线做全位比较。常见做法是把宽总线拆成“关键字段比较”，比如只比较地址高位和有效位，而不是 64 位全比。

多个断点/观察点同时激活时，触发是“或”语义，任一命中即停。如果你要的是“A 成立且 B 成立”，那得用状态机触发或者复杂计数器，而不是简单堆断点。这个语义差异是新手最容易踩的坑：设了三个断点以为能抓三者同时发生，结果第一个命中就停了，还以为是工具 bug。

4.2 复杂计数器与状态机触发

复杂计数器（Complex Counter）用来做“事件计数到 N 再触发”，比如“总线出现 100 次非法访问后停”。创建时指定计数事件（哪个信号、什么条件算一次）和阈值，调试时计数器实时累加，到阈值触发采样。手册里还提到可以临时禁用计数器（Disabling the Counter），用于调试计数器本身逻辑是否正确——先禁用看计数是否按预期增长，再启用做触发，这个自检习惯能省不少时间。

状态机触发（State Machine Triggering）是进阶玩法：把多个条件按状态迁移组织起来，实现“先看到 A，再看到 B，最后看到 C 才触发”的序列检测。手册区分了简单触发和高级触发两种模式，高级模式配 State-Machine Editor 画状态图，支持多状态、多迁移条件。状态机的每个状态可以挂断点/观察点条件，迁移可以带计数或延时。实际项目里抓“握手超时”“协议违例”这类时序问题，状态机触发比单点断点好用得多，因为它能表达“顺序”。

# 状态机触发示意：等待 start 有效 -> 计数 8 拍内未见 ack -> 触发 # 状态定义与迁移（伪代码风格，具体 API 以实际版本为准） sm create -name hs_timeout sm state add IDLE sm state add WAIT_ACK sm state add TRIGGER # IDLE: start 拉高进入 WAIT_ACK sm transition add -from IDLE -to WAIT_ACK -when {start == 1} # WAIT_ACK: ack 出现则回 IDLE；计数满 8 拍仍无 ack 则进 TRIGGER sm transition add -from WAIT_ACK -to IDLE -when {ack == 1} sm transition add -from WAIT_ACK -to TRIGGER -when {counter >= 8} # TRIGGER 状态触发采样 sm trigger -state TRIGGER -action capture

这段示意里，-when是迁移条件表达式，信号名对应插桩时选中的信号；counter是状态内计数器，用来表达“等了多久”；-action capture表示进入该状态即触发采样。实际写的时候条件表达式要严格对应信号位宽，拿 1 位信号和多位常量比较会报类型不匹配。状态机配好后建议先用简单场景验证迁移路径，再上真实激励，否则状态卡死时很难判断是设计问题还是触发配置问题。

5. 避坑与排查：连不上、抓不到、对不齐

调试工具用不顺，九成不是工具本身的问题，而是链路某一环没对齐。下面几条是实际项目里反复出现的翻车点，按“现象 → 原因 → 解决”整理，遇到时按顺序排查能少走弯路。

5.1 常见问题排查清单

现象：Debugger 启动后 Open Design 报找不到调试核。原因通常是 ProtoCompiler 编译时没带 idc，或者板卡型号参数和实际硬件不一致，导致 IICE 映射对不上。解决：回查编译命令是否带-idc，-board是否和实际板型一致；用haps boardstatus确认板卡被正确识别，必要时重跑编译。

现象：断点设了但从不触发。原因多为条件表达式里的信号没被插桩，或者位宽/极性写反。解决：在 Hierarchy Browser 里确认该信号在可观测列表里；用简单条件（如单信号等于常量）先验证触发通路，再逐步加复杂条件；注意多断点是“或”语义，别把“与”需求写成多个断点。

现象：DTD 抓出来的波形和实际逻辑对不上。原因可能是 DDR3 训练未通过、DTD 存储区间和别的功能重叠，或多 FPGA 场景触发未同步。解决：先跑DDR4_selftest排除内存；核对 DTD 的-base/-size与板级内存映射；多片场景确认主从触发配置和跨片时间戳对齐。

现象：采样数据回放时间轴不均匀。原因是开了采样压缩，只存变化点。解决：确认是否开了压缩；对需要逐周期分析的场景关掉压缩重抓；看波形时留意压缩标记，别把“没变化”误读成“没采样”。

现象：板级自检命令跑一半失败，日志信息很少。原因多是没开详细输出，或失败发生在链路早期导致后续检查连锁失败。解决：加-verbose重跑；按“时钟 → 连接 → 内存 → 复位 → Flash”的顺序逐项排查，前一项不过不要往后跑，否则日志全是噪声。

提示：每次改插桩信号或 DTD 配置后，都要重新编译并重新校验硬件配置，跳过这步直接调试，抓到的数据不可信。

6. GUI 面板与 Tcl 脚本：把重复调试动作固化下来

Debugger 的 GUI 面板不少——Setup、Run、Search、RTL、Watchpoints、Breakpoints、Sampled Signals、Hierarchy Browser、Tcl Script Window——但真正决定效率的是 Tcl 脚本窗口。GUI 适合探索性调试，脚本适合把“每次都要做的一串动作”固化：打开设计、加载激活配置、设断点、跑、导出采样。手册第 6 章专门讲了执行脚本文件、保存和加载激活（Saving and Loading Activations）、跨触发（Cross Triggering）以及在不同机器上调试。

我一般会把一个项目的调试配置写成脚本，纳入版本管理，换人接手时直接跑脚本复现环境，而不是靠口头描述“你点那个面板第三个按钮”。下面是一个把常用动作串起来的脚本骨架：

# debug_session.tcl：一键恢复调试会话 # 1. 打开设计（指向 ProtoCompiler 输出目录） open_design ./build/top_debug_db # 2. 加载之前保存的激活配置（断点/观察点集合） load_activations ./cfg/top_activations.act # 3. 设置采样缓冲与触发位置 set_sample_buffer -size 65536 -trigger_pos 0.7 # 4. 启动运行，等待触发 run -timeout 60s # 5. 触发后导出采样，供离线分析 export_samples -format vcd -out ./wave/run_001.vcd

open_design指向的目录必须是带调试数据库的编译输出；load_activations读的是之前用 GUI 或脚本保存的激活文件，断点/观察点集合都在里面，这是省时间的关键；-trigger_pos 0.7让触发前现场占七成；run -timeout防止无限等待，超时后脚本继续往下走便于判断是没触发还是卡住；export_samples导出 VCD 后可以接外部波形工具做二次分析。跨触发（Cross Triggering）用于多板或多 FPGA 场景，一片触发后联动另一片抓取，配置时注意触发源和接收端的角色别搞反。

验证脚本是否可靠，我的习惯是拿一个已知会触发的简单激励跑一遍，确认从打开设计到导出波形的全链路通，再换真实激励。从那以后我每次接手新板卡或新设计，都强制先跑一遍 bring-up 自检加一个最小调试脚本，确认链路通了再上复杂触发配置——这个习惯帮我挡掉了太多“以为是设计 bug、其实是链路没通”的无效排查。希望帮到你。

本文还有配套的精品资源，点击获取