想给开源雷达提第一个 PR？先读懂那套“协议先行“的协作规矩

想给开源雷达提第一个 PR？先读懂那套"协议先行"的协作规矩

【免费下载链接】PLFM_RADAROpen-source, low-cost 10.5 GHz PLFM phased array RADAR system项目地址: https://gitcode.com/GitHub_Trending/pl/PLFM_RADAR

PLFM_RADAR（AERIS-10）是一个从零开源的 10.5 GHz 相控阵雷达项目：FPGA 里跑着脉冲压缩、多普勒 FFT、MTI 和 CFAR，STM32 管着频率综合、波束成形和电源时序，Python GUI 负责回放与可视化。这样一个横跨 Verilog、C/C++、Python 三层、动辄牵扯射频硬件的仓库，任何改动都可能让"主机发的指令"和"FPGA 认的指令"悄悄分道扬镳。仓库里那句反复出现的标语很能说明问题：FPGA RTL（radar_system_top.v）是 opcode 值、位宽、复位默认值、合法范围的唯一事实来源，其他所有层都必须向它对齐。

这篇文章想解决一个具体问题：作为新手，你的第一个 PR 该从哪下手，以及为什么这个仓库对"协议对齐"近乎偏执——理解了这套规矩，你的 PR 才不会在第一轮 CI 就被打回来。

五类最小可运行任务，怎么挑

社区对 PLFM_RADAR 的贡献路径做过比较系统的梳理（CSDN 贡献指南 的实际规定，可以归纳出五类"最小可运行任务"，每一类都有明确的验证闭环：

判断"哪一类适合你"有两个硬标准：一是不碰硬件也能跑通，二是改动有明确的对错判定。对第一次接触雷达信号链的新手，最友好的入口其实是后两类——跨层契约测试和 FPGA 回归测试，因为它们的判定标准完全由代码决定，不需要你拥有一台能烧录的雷达。

选任务还有个隐藏技巧：翻docs/implementation-log.html和测试目录里的test_bug*.c文件（如 9_Firmware/9_1_Microcontroller/tests/test_bug13_dac2_adc_buffer_mismatch.c），能看出维护者重视什么——ADC 缓冲区读写错位、SPI 片选不翻转、定时器变量命名冲突这类"只有对抗性测试才抓得到"的 bug。修复一个已被注释标出"FIXED"的历史 bug，远不如你主动为某个模块补一条对抗性测试更有价值。

环境搭建与 iverilog 仿真：先让 CI 在你本地跑绿

PLFM_RADAR 的 CI 由四个任务组成（见 CONTRIBUTING.md 的 checklist）：Python 与 lint、MCU 单元测试、FPGA 回归、跨层契约测试。提交 PR 前必须全部在本地通过，否则维护者不会看。

依赖安装有一条硬性安全红线

由于供应链攻击风险，仓库明确规定所有包安装必须带sfw安全前缀：Python 用sfw uv pip install，Node 用sfw npm install，Rust 用sfw cargo。这是 README 之外的强制项，第一次装环境的人最容易在这翻车——直接裸跑pip install会被认为不合规。

FPGA 侧：iverilog 就是你的"穷人头号工具"

FPGA 改动不需要 Vivado 也能验证。仓库把 RTL 仿真完全押在开源工具链上：iverilog编译、vvp运行、testbench 里显式输出[PASS]/[FAIL]标记。整个回归由 9_Firmware/9_2_FPGA/run_regression.sh 串起来，分五个阶段：

• Phase 0 Lint：先用iverilog -Wall编译全部生产 RTL，再叠加正则静态检查，专抓"iverilog 能放过但 Vivado 会报错"的模式——比如 case 语句缺default（Vivado SYNTH-6 推断锁存器）、位选越界、端口位宽不匹配。这一步的注释写得很直白：这些是 Vivado 级错误，lint 不过就不许进 Vivado。
• Phase 1 改动模块单元测试：CIC 抽取器、Chirp 控制器、Doppler 处理器、CFAR、MTI 等模块各自独立跑 testbench。
• Phase 2 集成测试：DDC 链路（NCO→CIC→FIR）、真实数据 golden hex 与 RTL 逐位比对（精确匹配，--quick模式下跳过长测试）。
• Phase 3/4 信号处理与基础设施单元测试：FFT 引擎、NCO、FIR、CDC 模块、USB 数据接口、雷达模式控制器。

跑法很简单：

cd 9_Firmware/9_2_FPGA bash run_regression.sh # 完整五阶段 bash run_regression.sh --quick # 跳过 golden 与系统级长测试

测试里有几条仓库级约定，写 testbench 时必须遵守：每写完@(posedge clk)后要加#1延迟再驱动 DUT 输入；wr_full是在DEPTH+1次写入后才拉高，而不是DEPTH次——这类细节全是历史踩坑的产物，违反任何一条都可能让时序出现微妙竞争。

三层验证都要过

Python 侧要求ruff零 lint 错误；MCU 侧在9_Firmware/9_1_Microcontroller/tests下make clean && make，用的是 cpputest 风格的主机侧单元测试，把 STM32 外设 mock 掉后跑逻辑；跨层契约测试单独一个命令。四样全绿，你的 PR 才算有了"入场券"。

从 PR 规范到跨层契约测试：真正的核心规矩

PR 流程本身就有讲究

CONTRIBUTING.md 的规定很明确：fork 后从develop分支切 topic 分支，main只放生产发布——也就是说 PR 的目标永远是develop，不是main。同时提交前要git diff --check清掉空白错误，且不得把生成物（Vivado 工程、bitstream、构建日志）提交进版本控制。仓库根目录的 README 还专门写了文件落位政策：发布报告放docs/，仿真输出放5_Simulations/generated/，FPGA 产物放9_Firmware/9_2_FPGA/reports/。

更有意思的是 AI 使用政策：AI 可以辅助写代码，但提交者必须对 AI 产出的每一行负全责、必须通读、必须本地跑完全部 CI——"代码库的质量不能依赖 agent，而必须依赖推送代码的维护者本人"。这意味着你的 PR 里不能出现"AI 生成的、自己看不懂"的代码。

协议先行：三层之间的唯一对齐锚点

回到开头那句话。雷达系统里 Python GUI、Verilog RTL、STM32 固件要共享同一套接口语义，最危险的情况不是某一层写错，而是两层同时写错、且互相印证——普通的"两边对比"测试永远发现不了这种错误。跨层契约测试的解法是引入独立转写的事实来源（ground truth）。

看 9_Firmware/tests/cross_layer/test_cross_layer_contract.py 顶部的注释，它把验证分成三层：

• Tier 1 静态契约解析：用正则分别解析 Python 的radar_protocol.py、Verilog 的radar_system_top.v与usb_data_interface*.v、C 的RadarSettings.cpp和main.cpp，从源码里"发现"各层实际实现的 opcode、位宽、复位默认值，再与手工转写的事实表（GROUND_TRUTH_OPCODES，包含 opcode 对应的寄存器名和位宽）比对。测试断言里专门留了一句：发现不在事实表中的 Python opcode，就是"幻影 opcode"——历史上出过0x06事件；status_words[0]还踩过 37 位截断的坑。
• Tier 2 Verilog 协同仿真：用 iverilog 编译运行 9_Firmware/tests/cross_layer/tb_cross_layer_ft2232h.v，该 testbench 做三组练习：把所有 opcode 从主机侧打给 FPGA 的命令回环、注入已知距离/多普勒/CFAR 值后抓 11 字节数据包、置位全部状态输入后抓 26 字节状态包，输出字节再由 Python 解析器做往返校验。
• Tier 3 C 桩执行：用 9_Firmware/tests/cross_layer/stm32_settings_stub.cpp 把真实的RadarSettings::parseFromUSB()编译成独立可执行文件，Python 生成二进制 settings 包喂给它，比对每个字段解析结果。

这套设计的关键在于"各层与独立事实源对齐，而不是各层彼此对齐"——正如文件注释所说："目标是发现未知 bug，而不是仅仅检查两层是否一致（因为两层可能同时是错的）。"

一个具体的对照：11 字节数据包协议

从 9_Firmware/9_3_GUI/radar_protocol.py 可以看到协议最直观的样子。上行（FPGA→主机）数据包固定 11 字节：

[0xAA] [range_q 2B] [range_i 2B] [dop_re 2B] [dop_im 2B] [det 1B] [0x55]

状态包以0xBB开头共 26 字节，下行命令则是{opcode, addr, value_hi, value_lo}四字节顺序接收。opcode 枚举从RADAR_MODE=0x01到STATUS_REQUEST=0xFF，注释里直接引用了radar_system_top.v的 case 表作为唯一依据。契约测试做的事，就是反复确认这份枚举、Verilog 的case (usb_cmd_opcode)分支、以及 C 固件的解析逻辑三者没有分叉。

三个可以立刻上手的行动点

1. 装环境时记得sfw前缀，然后跑一遍cd 9_Firmware/9_2_FPGA && bash run_regression.sh。第一次看到五阶段全绿的输出，你对"可验证"的理解会比读十篇文档都深。
2. 读 9_Firmware/tests/cross_layer/contract_parser.py：它是"协议先行"哲学的浓缩——解析器不定义期望值，而是去发现各层实际实现了什么，再跟事实源对撞。理解了它，你就理解了为什么这个仓库的 PR 评审会卡在协议对齐上。
3. 挑一个最不起眼的模块（比如edge_detector.v或range_bin_decimator.v），为它补一条"对抗性测试"——测试 must 主动尝试破坏代码，比如复位中途打断、边界输入、意外序列。这正是仓库明确要求的 testbench 最低标准。

最后回到协作的本质：这个仓库的 PR 欢迎标识是PRs Welcome，但欢迎的是"把规矩当真的人"。协议先行不是维护者的洁癖，而是雷达这种软硬一体系统的生存策略——19,000 个 star 背后，是"每个贡献者都能在本地证明自己改对了"的工程文化。你的第一个 PR 不必大，但务必让 CI 替你说话。

【免费下载链接】PLFM_RADAROpen-source, low-cost 10.5 GHz PLFM phased array RADAR system项目地址: https://gitcode.com/GitHub_Trending/pl/PLFM_RADAR