1. 从一次交付翻车说起：为什么adf网表文件和黑匣子值得单独聊
前两年接手过一个工业控制板卡的项目，主控用的是紫光同创的Logos系列FPGA，逻辑规模不大，但交付节点卡得很死。项目做到后期，客户突然提了一个要求：核心算法模块要单独交付，源码不能给第三方团队，但对方又必须能把整个工程跑起来做系统联调。当时第一反应是"给个网表不就完了"，结果真上手才发现，紫光同创PDS（Pango Design Suite）这套工具链里，adf网表文件的使用和黑匣子（Black Box）设置，坑比想象中多得多——综合出来的adf文件直接丢进新工程，要么找不到模块，要么端口对不上，要么时序约束全丢，编译报错能刷满一屏。
这篇就围绕紫光同创FPGA的adf网表文件使用和黑匣子设置这个主题，把当时踩过的坑、后来摸索出来的稳定流程，以及一些工具文档里不会明说的细节，完整梳理一遍。核心关键词包括紫光同创、FPGA、adf网表文件、黑匣子、PDS，涉及的操作全部基于PDS工具链。
先说清楚这套东西解决什么问题。在FPGA项目协作中，经常遇到两种场景：一是IP保护，自己辛苦写的核心逻辑不想以源码形式交付；二是分工开发，A团队做算法模块，B团队做顶层集成和板级调试，两边不想互相暴露全部源码。这时候就需要把某个模块综合成网表文件（adf），在顶层工程里以黑匣子的形式例化调用。听起来简单，但adf网表不是Verilog源码，它携带的信息有限，端口定义、参数、时序约束这些都需要额外处理，稍不注意就会在集成阶段翻车。
适合读这篇的人：正在用紫光同创PDS做开发、需要做模块化交付或IP保护的工程师；刚接触adf网表、被黑匣子报错折腾过的朋友；以及想提前了解这套流程、避免项目后期返工的团队负责人。下面按实际操作顺序展开，从概念到流程到排错，尽量把每个"为什么"讲透。
2. adf网表到底是个什么东西：和源码、和edf的区别在哪
2.1 adf文件的本质与生成时机
adf是紫光同创PDS工具链中综合（Synthesis）阶段输出的网表文件格式，全称可以理解为一种描述逻辑连接关系的中间文件。它和Verilog源码最大的区别在于：源码描述的是"行为"，adf描述的是"结构"——综合器已经把always块、if-else这些行为级描述，映射成了LUT、触发器、BRAM、DSP等底层资源的连接关系。所以adf文件里没有可读的逻辑代码，只有网表。
生成adf的时机很关键。在PDS里，综合完成后会自动生成adf，位置一般在工程目录下的综合结果文件夹里。但要注意，默认综合输出的adf不一定适合直接给别人用，因为里面可能包含了综合器自动推断出的一些信息，端口命名也可能被优化过。我一般会专门为交付单独跑一次综合，并且在综合选项里做一些设置，保证输出的网表干净、端口明确。
这里有个容易混淆的点：adf和edf（EDIF网表）不是一回事。edf是通用的电子设计交换格式，很多工具链都支持；adf是紫光同创PDS体系内的格式，和PDS的版本、器件系列绑定得比较紧。用PDS打开adf没问题，但如果你想跨工具链用，那得走edf。实际项目里，只要上下游都用PDS，adf就够了，而且adf对紫光同创器件的适配性更好，资源映射更准确。
2.2 黑匣子机制：工具怎么"假装"知道这个模块
黑匣子的核心思路是：顶层工程在综合和实现时，遇到一个只有端口定义、没有内部逻辑的模块，工具不去管它内部是什么，只按照端口连接关系把它当成一个"盒子"来处理。这个盒子在最终生成比特流时，会被adf网表里的实际逻辑替换进去。
理解这个机制很重要，因为它决定了黑匣子模块的声明方式。你必须在顶层工程里提供一个"壳"——通常是一个Verilog文件，里面只有module声明和端口列表，没有内部逻辑。这个壳的端口必须和adf网表里的模块端口完全一致，包括端口名、位宽、方向。任何一处对不上，工具在链接阶段就会报错。
我见过最常见的错误就是端口名大小写不一致，或者位宽写错一位。Verilog本身对大小写敏感，而adf网表里的端口名是综合时确定的，如果你在壳文件里手写端口时打错一个字母，编译能过综合，但到实现阶段链接网表时就炸了。所以我的习惯是：壳文件的端口列表直接从adf网表的端口报告里复制，不手写。
2.3 为什么不用源码而用网表：保护与解耦的双重考量
有人会问，既然黑匣子这么麻烦，为什么不直接给源码？两个原因。第一是IP保护，核心算法是团队的心血，源码交付意味着逻辑完全暴露，后续维护和商务上都被动。第二是解耦，源码交付后，接收方可能改你的代码，改出问题还得你背锅；网表交付则明确了边界，你只对网表功能负责，对方怎么集成是对方的事。
但网表交付也有代价：调试困难。源码可以加ILA、可以单步仿真，网表基本是个黑盒，出问题只能看端口波形。所以我的经验是，交付网表的同时，一定要附带一份详细的端口时序说明和仿真模型，否则对方集成时会非常痛苦。这一点后面会专门讲。
3. 从源码到adf：生成网表前的准备工作与综合设置
3.1 模块划分：哪些逻辑适合做成网表
不是所有模块都适合做成adf网表。我的判断标准有三条：一是逻辑相对独立，对外接口清晰，不依赖顶层的大量内部信号；二是模块内部不含需要频繁修改的参数，因为网表里的参数化能力很弱；三是不含厂商特定的IP核，除非你确认对方工程里也有同样的IP。
举个反例：之前有个项目想把一个带PLL的时钟管理模块做成网表，结果对方工程里没有对应的PLL IP配置，链接时直接报找不到原语。后来改成把PLL留在顶层，只把PLL后面的处理逻辑做成网表，问题才解决。所以含厂商原语或IP的模块，做网表要格外谨慎，最好把IP部分剥离出来。
另外，模块的端口尽量用简单的wire类型，避免在端口上直接挂复杂的表达式。网表对端口的处理比较"死"，复杂的端口连接关系容易在链接时出问题。
3.2 综合选项里那几个必须改的设置
在PDS里对目标模块单独建工程做综合时，有几个选项需要特别关注。第一个是综合策略，建议选面积优先或默认，不要选性能优先，因为性能优先会做更多优化，可能改变端口或资源映射，给后续链接带来不确定性。第二个是保留层次结构（Keep Hierarchy），这个选项建议打开，它能让综合后的网表保留模块的层次，端口更清晰，链接时不容易出错。
第三个是输出文件格式，确认勾选adf输出。有些PDS版本默认只输出edf，需要手动勾adf。第四个是禁用IO缓冲插入，因为网表模块是内部逻辑，不需要IO buffer，如果综合时插了IO buffer，链接到顶层后会多出莫名其妙的端口。
还有一个细节：综合时的顶层模块名要和交付的模块名一致。如果综合时顶层叫top，交付时对方例化的模块叫my_core，那链接肯定失败。我一般会在综合前把模块名改成最终交付的名字，避免混淆。
3.3 生成后的自检：端口报告和资源报告怎么看
综合完成后，别急着把adf丢给别人，先自己检查两样东西。第一是端口报告，PDS会生成一个端口列表文件，里面列出了模块的所有输入输出端口、位宽、方向。把这个报告和你的壳文件端口逐一对照，确保完全一致。第二是资源报告，看看LUT、寄存器、BRAM的占用情况，确认没有异常膨胀——如果资源占用比预期高很多，可能是综合策略有问题，或者代码里有没预料到的逻辑被推断出来。
我还会做一件事：用生成的adf单独建一个测试工程，把壳文件加进去，跑一遍完整流程，确认能综合、能实现、能生成比特流。这一步相当于自测，能提前发现大部分链接问题。虽然多花半小时，但比交付后被对方追着问强得多。
4. 黑匣子工程的搭建：壳文件、约束和例化方式
4.1 壳文件怎么写才不出错
壳文件是黑匣子工程的入口，写法直接决定链接能否成功。标准写法是：module声明加端口列表，端口方向和位宽必须和adf网表一致，模块内部留空或者只写注释。不要在里面加任何逻辑，哪怕是一句assign都不要，否则综合器会认为这个模块有实现，可能不去链接网表。
端口列表的写法建议用ANSI风格，每个端口单独一行，方便对照。比如：
module my_core ( input wire clk, input wire rst_n, input wire [15:0] data_in, input wire data_valid, output wire [31:0] data_out, output wire data_ready ); // 黑匣子模块，内部逻辑由adf网表提供 endmodule注意端口名要和adf网表里完全一致。如果adf里的端口是data_i而不是data_in，那壳文件里也必须写data_i。我一般直接从端口报告里复制粘贴，避免手误。
还有一个坑：有些综合器会把常量端口或未连接端口优化掉，导致adf里的端口比源码少。如果发现端口对不上，回去检查综合设置，确认没有开启会优化端口的选项。
4.2 约束文件怎么处理：时序约束的传递问题
这是黑匣子流程里最容易被忽视的一环。adf网表里不包含时序约束，综合时你写的create_clock、set_input_delay这些约束，不会跟着网表走。所以顶层工程必须重新对这些端口施加约束，否则时序分析就是空的，实现结果可能完全不可靠。
我的做法是：在交付网表时，附一份约束模板，列出该模块所有端口需要的约束类型和推荐值。比如输入端口相对时钟的setup/hold要求，输出端口的最大延迟等。对方在顶层约束文件里把这些约束加上，才能保证时序正确。
如果模块内部有时钟域交叉或特殊时序要求，也要在文档里说明。网表是黑盒，对方看不到内部结构，只能靠你提供的约束信息来保证时序。这一点如果偷懒，后期调试会非常痛苦。
4.3 顶层例化：位置、命名和参数传递
在顶层工程里例化黑匣子模块，和例化普通模块写法一样，但有几个注意点。第一，例化时端口连接建议用命名连接（.port_name(signal)），不要用位置连接，因为位置连接一旦端口顺序有出入就全错，而且可读性差。第二，如果模块有参数，参数传递要谨慎，因为网表里的参数在综合时已经固定，顶层传参可能不生效，甚至导致链接错误。最好的做法是网表模块不带参数，需要配置的地方通过端口传入。
第三，例化的模块名必须和adf网表里的顶层模块名一致。如果adf里模块名是my_core，顶层例化时也得用my_core，不能改名。有些工程师习惯在例化时改个名字方便区分，但这在黑匣子流程里行不通。
第四，把adf文件和壳文件一起加入工程。PDS里添加文件时，adf作为网表文件加入，壳文件作为Verilog文件加入，工具会自动识别并链接。如果只加壳文件不加adf，综合能过但实现时会报找不到模块；只加adf不加壳文件，综合阶段就找不到模块声明。
5. 链接阶段的典型报错与排查链路
5.1 端口不匹配：从报错信息反推问题
链接阶段最常见的报错就是端口不匹配，报错信息一般会指出哪个端口对不上，是位宽问题还是方向问题。但有时候报错信息很模糊，只说"module not found"或"port mismatch"，不告诉你具体哪个端口。这时候排查思路是：先确认模块名一致，再逐一对照端口报告和壳文件。
我遇到过一次很隐蔽的情况：adf里的端口名是data_out[31:0]，壳文件里写的是data_out [31:0]，中间多了一个空格。Verilog本身对空格不敏感，但PDS的网表链接器在解析端口名时把空格也算进去了，导致匹配失败。后来把空格去掉就好了。这种问题看报错根本看不出来，只能靠仔细比对。
还有一个情况是端口方向搞反。比如adf里是output，壳文件里写成input，综合能过，链接时报方向冲突。所以对照端口报告时，方向也要逐一确认。
5.2 模块找不到：文件添加顺序和路径问题
"module not found"这个报错，八成是adf文件没加进工程，或者加进去了但路径不对。PDS添加网表文件时，要确认文件类型选的是网表而不是源码，否则工具可能不识别。另外，如果adf文件放在工程目录外，路径里有中文或空格，也可能导致找不到。建议把adf文件复制到工程目录下，用相对路径引用。
还有一种情况是模块名大小写问题。PDS在Windows下对文件名大小写不敏感，但网表内部的模块名是大小写敏感的。如果adf里模块名是My_Core，壳文件里写my_core，链接时就会找不到。所以模块名统一用小写，避免这类问题。
5.3 时序违例：黑匣子端口的约束缺失
时序违例在黑匣子工程里特别常见，因为adf网表不带约束，顶层如果忘了加端口约束，工具就按默认处理，结果时序全乱。典型表现是实现后时序报告里黑匣子端口相关的路径全是红色，setup或hold违例。
解决办法就是前面说的，在顶层约束文件里补上端口约束。如果不知道具体约束值，可以先按时钟周期的一半估算，跑一遍时序分析，再根据报告调整。另外，黑匣子内部的时序你控制不了，但可以通过约束端口的输入输出延迟，给内部逻辑留出足够的时序余量。
我一般会在约束文件里加一段注释，标明这些约束是给黑匣子模块的，方便后续维护。如果模块升级，约束也要同步更新。
6. 交付与协作：让对接方少走弯路的几个习惯
6.1 交付包里应该包含什么
交付adf网表时，不要只给一个adf文件。我的标准交付包包含五样东西：adf网表文件、壳文件（Verilog）、端口说明文档、约束模板、以及一个简单的仿真模型（如果有条件）。端口说明文档里列出每个端口的名称、位宽、方向、功能描述和时序要求；约束模板给出推荐的约束写法；仿真模型可以让对方在系统仿真时验证接口时序。
如果模块有复位要求或初始化序列，也要在文档里写清楚。网表是黑盒，对方不知道内部复位逻辑，如果复位时序不对，模块可能根本不工作。这一点在交付时说明白，能省掉大量来回沟通。
6.2 版本管理：adf和源码的对应关系
adf网表一旦生成，就和当时的源码版本绑定了。如果源码后续有修改，必须重新综合生成新的adf，不能混用。我习惯在adf文件名里带上版本号和日期，比如my_core_v1.2_20240510.adf，同时在交付文档里记录对应的源码版本号（Git commit ID）。这样后续追溯问题时，能快速定位到对应的源码。
另外，PDS的版本也要记录。不同版本的PDS生成的adf可能有兼容性问题，如果对方用的PDS版本和你不一样，链接时可能报奇怪的错误。最好约定统一使用某个版本的PDS，或者提前确认版本兼容性。
6.3 联调阶段的配合要点
联调阶段是最容易扯皮的时候。对方说你的网表有问题，你说对方的集成方式不对。为了避免这种情况，我一般会在交付时约定一个简单的验收测试：对方用你的网表跑一个最小系统，输入已知激励，看输出是否符合预期。这个测试通过后，再进入系统联调。
联调时如果出问题，先确认是接口问题还是内部逻辑问题。接口问题看端口波形，内部逻辑问题只能你这边配合排查。所以交付时留一个联系方式，联调阶段保持沟通，比事后互相甩锅强得多。
7. 几个容易被忽略的细节和我的实操心得
7.1 黑匣子模块的仿真怎么做
黑匣子在仿真时是个空模块，没有内部逻辑，仿真输出全是未知态。所以系统仿真时，要么用行为级模型替代黑匣子，要么在测试平台里对黑匣子端口做强制驱动。我的做法是：交付时附一个行为级仿真模型，功能和网表一致，但用Verilog写成可综合或可仿真的形式。对方在系统仿真时用这个模型，实际实现时用adf网表，两边接口一致，仿真结果有参考价值。
如果模块太复杂，行为级模型写起来费劲，至少也要提供一个端口时序模型，描述输入输出之间的时序关系，让对方能验证接口时序。
7.2 资源占用和时序的权衡
adf网表在链接到顶层后，资源占用会和单独综合时略有差异，因为顶层会做跨模块优化。有时候单独综合时资源够用，链接后却超了。这时候可以尝试调整顶层的综合策略，或者把黑匣子模块的边界约束得更明确，减少跨模块优化。
时序方面，黑匣子端口的约束如果给得太紧，可能导致顶层其他逻辑时序紧张；给得太松，又可能掩盖真实问题。我的经验是：先按模块单独综合时的时序报告，估算端口的时序余量，然后在顶层约束里留10%到20%的余量，跑一遍实现看报告，再微调。
7.3 从adf到edf：跨工具链的备选方案
虽然adf在PDS体系内很好用，但如果对接方用的不是PDS，或者项目要求通用格式，那就得用edf。PDS支持输出edf网表，但edf的兼容性和资源映射准确度不如adf。如果必须用edf，建议提前和对接方确认工具链版本和器件库，避免链接失败。
我的建议是：只要上下游都用PDS，优先用adf；如果跨工具链，提前做兼容性测试，别等到项目后期才发现问题。
7.4 一个真实项目的完整时间线
最后分享一个真实项目的时间线，供参考。项目是工业控制板卡，FPGA做电机控制算法。算法模块由A团队开发，顶层集成由B团队负责。A团队在项目中期开始准备网表交付：第一周做模块划分和综合设置，生成adf并自测；第二周写壳文件、端口文档和约束模板；第三周B团队集成，联调发现两个端口位宽不一致，修正后通过；第四周系统联调，补了一条时序约束，最终交付。整个过程大约四周，其中端口对齐和时序约束花了最多时间。
如果重来一次，我会在项目初期就约定好端口命名规范和约束模板，避免后期返工。另外，adf网表的自测环节不能省，哪怕多花半天，也比交付后被追着改强。
这套流程跑顺之后，后续几个项目都复用了同样的方法，基本没再出过大问题。核心就一句话：网表交付不是给个文件就完事，端口、约束、文档、自测，一个都不能少。
