FPGA 入门 47：RTL 版本管理——Git 与可复现工程入门
更新时间：2026-09-12。本文是
fpga/入门层第 49 篇。前置：上板调试、IP 核怎么调、开源工具链/CI；时序确认见 时序报告。
本文要回答的问题
- 为什么「整个工程目录拷来拷去」必然走向混乱：绝对路径、IP 输出产物、机器相关状态分别埋在哪里？
- 一个 RTL 仓库的标准目录结构长什么样（rtl/tb/constraints/ip/scripts/docs/build）？各放什么？
- project 模式和 non-project 模式在自动化上的差异是什么？CI 里为什么通常选 non-project？
- 一个完整的 non-project tcl 从读源码到出比特流要经过哪些命令？失败在哪一步如何定位？
- IP 核、Block Design、第三方网表、仿真模型、MCS 文件这些「二进制或生成型资产」分别怎么管？
- 版本号注入、构建元数据、可追溯比特流如何做到「现场一块板子能反查到 commit、工具版本、约束版本」？
- 分支策略、代码评审、CI 检查（lint、仿真、综合、时序、资源红线）在 RTL 项目里怎么落地？
读完本文，你应当能把一个「压缩包传来传去」的课程工程，改造成 clone 后一条命令构建、任何人可复现、每次提交自动检查的工程化仓库，这也是从个人作业走向团队协作的分水岭。
一、提交什么 / 忽略什么
| 纳入 Git（源） | .gitignore 排除（产物） |
|---|---|
.v/.sv/.vhd RTL | Vivado .cache .runs .gen .hw .ip_user_files .Xil |
.xdc/.sdc 约束 | *.jou *.log *.str、巨大工程状态 |
| Testbench、仿真脚本 | Quartus db/ incremental_db/ output/ *.qws |
重建脚本 .tcl/Makefile/.sh | 生成的 .bit/.sof、临时文件 |
IP 配置 .xci/.xcix/.qsys/.bd | |
| README/文档、版本注入模板 |
# Vivado
*.cache/ *.runs/ *.gen/ *.hw/ *.ip_user_files/ .Xil/
*.jou *.log *.str *.bak
# Quartus
db/ incremental_db/ output/ *.qws *.jdi *.sof *.pof
# 产物
*.bit *.bin二、用 tcl 从源码一键重建（可复现）
# build.tcl（project mode 示意）
create_project myprj ./build -part xc7a35ticsg324-1L -force
add_files [glob ./rtl/*.v]
add_files -fileset constrs_1 ./constraints/top.xdc
import_ip ./ip/clk_wiz.xci
# non-project 模式：read_verilog/read_xdc -> synth_design
# -> opt/place/route_design -> write_bitstream
launch_runs impl_1 -to_step write_bitstream -jobs 4vivado -mode batch -source build.tcl # 干净环境一条命令出比特流原则：仓库存“源 + 脚本”，不存庞大工程目录；任何机器、固定工具版本都能重建。
三、IP / Block Design / 工具版本
- 提交
.xci/.xcix/.bd（配置即 Tcl），产物由工具重新生成；只提交生成结果会无法重建。 - README/CI 写死 Vivado/Quartus 版本；换版本要重生成 IP、重跑时序与上板。
- “IP 升级”单独成一次提交，不与功能改动混杂。
四、版本注入（现场可追溯）
HASH=$(git rev-parse --short HEAD)
echo "\`define GIT_HASH \"$HASH\"" > rtl/version.vh`include "version.vh"
// 上电经 UART/寄存器读出 GIT_HASH，立刻知道板子跑的哪一版（可加 dirty 标志）Git 实践：小步提交、清晰 message；feature 分支 + review；上板/发布打 tag；大文件用 Git LFS/制品库；比特流由 CI 产出并关联 commit。
六、为什么工程目录拷贝必然坏掉
Vivado/Quartus 的工程文件里混杂三类信息：设计意图（哪些 RTL、什么约束、什么器件）、工具状态（综合跑到哪一步、上次 GUI 打开的窗口位置、自动生成文件路径）、机器环境（IP 仓库的绝对路径、许可证服务器、临时目录）。只有第一类应该被版本管理。把整个工程目录拷给同事，等于同时复制了后两类，于是出现经典症状：别人打开工程提示 IP locked、找不到文件、综合结果不一致；Git 里几十 MB 的二进制状态每次都冲突；改了 RTL 但实际跑的是旧 runs 里的产物。正确的工程化思路来自软件行业多年前就解决的问题：仓库只存源和构建方法，所有产物都能被删除并一键重建。判断标准很简单：删掉整个 build 目录，运行一条命令能恢复到比特流，这个仓库就是健康的；如果做不到，说明某些「只有某台机器上存在的状态」还没有被显式化。
七、推荐仓库结构
project/
├── rtl/ 设计源码，按模块分子目录
├── sim/ testbench、仿真脚本、filelist
├── constraints/ xdc/sdc，板级与时序约束分开
├── ip/ 自研 IP 包装；厂商 IP 只提交 .xci/.bd
├── scripts/ build.tcl、sim.tcl、版本注入脚本
├── docs/ 架构图、时钟域、bring-up 记录
├── ci/ CI 配置
├── .gitignore
└── README.md 工具版本、构建命令、板卡型号几个组织原则：约束按用途拆文件（引脚 pin.xdc、时序 timing.xdc、调试 debug.xdc），不同板卡放不同子目录，顶层按目标板选择；filelist（.f）集中列源文件，仿真和综合读同一份，避免「仿真过了综合少文件」；脚本路径一律相对仓库根；README 第一屏写清「工具版本 + 三条命令（仿真、综合、下载）」，新人按它半小时跑通是仓库健康的验收标准。
八、两种构建模式与完整 tcl
Vivado 有两种自动化路线。Project 模式：tcl 创建工程、加文件、生成 runs，后台仍维护工程目录，适合大多数团队，write_project_tcl 可从现有 GUI 工程导出起点脚本，但要手工删掉机器相关行。Non-project 模式：不生成工程，直接 read_verilog/read_xdc、synth_design、opt_design、place_design、route_design、write_bitstream，每步产物是 checkpoint（.dcp），干净、快、适合 CI 和复杂流水线（可在布线后插入自定义报告、部分重配置等）。两种模式最终综合实现能力相同，区别在要不要工程状态文件。
一个最小 non-project 流程骨架（了解每步意图即可）：读 RTL 和 IP → read_xdc 约束 → synth_design 指定顶层和器件 → 检查综合日志和 latch 计数 → opt_design 优化 → place_design 布局 → route_design 布线 → report_timing_summary、report_utilization、report_power 各导出文件 → 时序必须满足才 write_bitstream，否则脚本 exit 非零让 CI 失败。Quartus 对应 quartus_map/fit/timed/as/stp 或 quartus_sh --flow。把「时序不满足即失败」固化成脚本红线，比指望每个人记得看报告可靠得多（指标含义见 时序报告 与 资源报告）。
九、IP、Block Design 与特殊资产的管理
- 定制 IP（.xci/.ip）：提交配置，构建时 generate_target 重建；不要把整个 IP 生成目录入库。
- Block Design（.bd）：本质是 Tcl 脚本，提交 .bd 或导出的 create_bd.tcl；复杂 BD 建议用 tcl 从头创建，代码评审能 diff。
- 厂商加密 IP/第三方网表：加密源或 .edf/.dcp 无法重建但体积小，可入库并在 README 记录授权和来源；大体积评估版放制品库。
- 系数/初始化文件：.mem/.coe/.hex 是设计数据，入库；生成它们的脚本也入库，保证改系数可追溯（见 FIR 滤波）。
- 比特流/MCS：不入库，作为 CI 制品与 commit 绑定归档（现场版本需要时从制品服务器取，见 比特流固化）。
- 数据手册 PDF：体积大且有版权，放内部知识库，仓库里只放链接。
十、版本注入：让每块板子自报家门
可追溯性要做到「板子插上串口，就知道它跑的是哪次提交」。做法：构建脚本先调 git 取短哈希、提交时间、dirty 标志（工作区有无未提交改动）、CI 构建号，生成 version.vh；RTL include 它或作为顶层参数；综合后这些字符串固化在 LUT 常量里，通过 UART 打印或 AXI 只读寄存器暴露。进一步把器件封装、板卡版本、构建工具版本一起注入，现场报障信息就完整了。注意生成文件不入库（每个人工作区哈希不同会造成永久 dirty），加入 .gitignore，由构建时生成。dirty 标志很重要：工程师私下改了一行就上板，如果没有这个标志，现场行为可能对应任何源码状态。
十一、分支、评审与提交纪律
小团队也值得遵守的最小流程：main 分支保持「随时可构建可上板」；功能开发开分支，小步提交，每个提交能独立通过仿真；合并前跑 code review，重点看跨时钟域、复位、约束、资源异常增长；上板验证通过的版本打 annotated tag（含板卡型号、验证人）。提交信息建议带类型前缀（feat/fix/sim/constraints/ip），正文写「为什么改」而不是「改了什么」（diff 自己会说改了什么）。约束改动和 RTL 改动尽量同提交，因为它们必须一起验证；时序例外（false_path 等）提交时必须在信息里写功能依据，这是评审重点（见 同步设计原则）。
十二、CI：把纪律变成流水线
FPGA CI 按耗时分层，每层在不同时机触发：①提交级（秒到几分钟）：Verilator lint、格式检查、纯 RTL 单元仿真，每次 push 都跑；②夜间级：全量回归仿真、覆盖率汇总；③周末或发布级：完整综合实现，检查时序必须满足、资源不超红线（对比基线自动 diff），产出比特流制品和报告归档。License 紧张时用浮动许可队列。仿真回归的黄金输出文件随仓库管理，数据激励可放 LFS。CI 通过的那一次构建产物才能打 tag、烧 Flash——这样「发布版本」不再依赖某个人的电脑状态（开源工具天然适合 CI，见 开源工具链；自动化检查体系见进阶 RTL lint、版本与 IP 管理 与专家 FPGA CI/CD）。
十三、个人仓库也要有的最小工程化
即使只是学习项目，从第一天就用工程化结构的回报极高：Git 管理、.gitignore、一个 sim 脚本和一个 build 脚本、README 记录板卡和工具版本、每个练习一个 tag。面试时打开你的 GitHub，评审人看到的是清晰的目录、一键复现的仿真、带时序数字的实验记录，这比「看过教程」有说服力得多。工程化的本质不是繁琐流程，而是让「正确做法」成为阻力最小的路径——当 lint、仿真、构建都是一条命令时，你自然会更频繁地验证，质量就这样积累出来。再强调一个容易被忽视的协作细节：约束文件的评审标准应该和 RTL 一样严格。很多团队 review Verilog 很认真，却对 XDC 的改动一扫而过，实际上一条错误的 false_path 可能让一整片路径完全不做时序检查，风险比一行普通代码大得多。建议把时序例外（false_path、multicycle、min/max delay）单独放一个文件，每条必须注释来源（手册章节、跨域结构名）和评审人，合并时必须有第二个人确认。这个小习惯能防住一大批「时序明明绿了板子还出错」的诡异事故。再补充一个关于「工程洁癖」和进度关系的常见疑问：学生阶段总觉得搭构建脚本、写 .gitignore、整理目录是在浪费做功能的时间。实际上这些投入第一次做确实要半天，但它立刻开始产生回报——换电脑不用重装一遍神秘工程、和同学合并不再互相覆盖文件、一周前的版本随时能构建、面试时仓库能直接点开演示。更重要的是，工程化能力本身就是 FPGA 岗位和业余爱好者的分界线：公司里的设计动辄几十个模块、几个人同时改、一个版本要交付给客户多年，没有可复现构建，规模一大就必然失控。把本文的最小实践从下一次作业开始坚持，半年后你回看自己最初的「整个文件夹压缩包」，会像回看没有缩进的代码一样不适应——这种不适应，就是工程素养长出来的声音。再补一个对团队负责人有用的视角：工程化基础设施的投入往往看起来不产生功能，但它决定团队规模扩大时的混乱速度。没有构建脚本，每多一个工程师，「在我机器上能跑」的沟通成本就多一分；有了 CI 和制品管理，新人第一周就能独立产出可烧录的版本。评估一个 FPGA 团队的成熟度，先看他们的仓库能不能一条命令构建、比特流能不能反查到 commit、时序失败会不会阻断合并——这三件事比用什么高端器件更说明问题。再给一个常见误区：很多人觉得「等项目大了再搞 CI」，实际上 CI 的价值在小项目时最大——那时规则简单、构建快、五分钟就能配好，却能从第一天养成提交必跑仿真的习惯。等项目大到「需要」CI 时，往往已经积累了大量历史包袱和对特定机器状态的依赖，改造成本高得多。工程化是少数「越早做越便宜」的事情。再给一个具体的最小实践：哪怕仓库里只有一个模块，今晚就建立 rtl、sim、constraints 三个目录，写一个 make sim 命令跑完仿真并返回成功失败码，写一个 README 说明工具版本和两条命令。这个骨架半小时能搭好，但它会成为你以后所有项目的模板——工程化不是大公司专利，它本质上只是把「下次还要做的事」写成脚本和约定。越早开始，你的注意力就越能留给真正难的设计问题。最后再讲一个提交粒度的经验：新手要么半年不提交、要么一个 commit 塞整个项目，正确的节奏是「一个可独立验证的改动一次提交」——修一个 CDC、加一个 testbench、改一条约束都可以独立成提交，每个提交都应该能通过仿真。这样一旦引入问题，git bisect 可以在几十次提交中几分钟定位到出错点；现场回溯时，也能清楚看到每个设计决策是在哪次改动中引入的。版本管理表面上在管文件，实际上在管「设计决策的历史」，理解这一点，你才会真正认真对待每一次 commit message。最后再给一个团队级建议：除了源代码和构建脚本，仿真激励、参考输出、系数文件、板级引脚表都应纳入版本管理；而大型数据手册、比特流制品、完整逻辑分析仪抓包放制品库并在 README 里留链接。仓库的目标不是保存一切，而是保存「重建设计所需的最小完整集合」。当一个新工程师 clone 仓库后，不需要问任何人、不翻聊天记录就能跑仿真、出比特流、知道烧到哪块板，工程化就算真正落地了。最后强调一个认知：FPGA 项目的构建产物昂贵（一次综合实现几十分钟到几小时），所以「在更早的阶段用更便宜的手段发现问题」是工程化的核心经济学——编辑器 lint 秒级发现语法问题、仿真分钟级发现功能问题、综合小时级才发现资源和时序问题。把检查尽量左移到快速阶段，CI 分层正是这一思想的落地。理解了这一点，你就理解了为什么成熟团队愿意花大量时间搭脚本和流水线：它们看起来不产生功能，却在项目尺度变大时决定团队的实际迭代速度。最后给一个落地建议：不要试图一次搭出完美的工程化体系。从「Git 加 .gitignore 加一条构建命令」三件套开始，稳定使用一两个月后再引入 CI，再往后才是制品管理和版本注入。每一步都等到当前流程真的疼了再自动化，工具会恰好解决真实问题；过早堆砌流程只会让小项目背上大公司的负担。工程化的目标始终是让正确的事变简单，而不是让简单的事变复杂。最后给一个检验仓库健康度的五分钟测试：在一台干净机器（或新容器）上 clone 仓库，只照 README 操作，计时看多久能跑通仿真、多久能产出比特流，中途是否需要问人。如果超过半天仍无法构建，说明「源+脚本」的集合还不完整，缺的可能是某个隐含依赖、未提交的 IP 配置或未写明的环境变量。定期做这个测试，仓库的可复现性才不会随项目老化而悄悄失效。最后给个人学习者一个提醒：不要觉得版本管理和 CI 是「上班以后才用得上的东西」。你在求职作品集里放一个能一条命令仿真和综合、每次提交自动跑测试、发布版本带 git 版本号的小项目，比多放一个功能炫但目录混乱的工程有说服力得多——雇主在其中看到的是可维护性和工程判断力，这正是区分「会写 RTL」和「能交付工程」的分水岭。把工程化习惯从学习阶段就建立起来，未来无论进入什么团队、接手什么规模的设计，你交付的都不会是一堆只有自己能看懂的源文件，而是一套任何人都能重建、验证、发布的工程资产。这就是 RTL 版本管理最终的价值。
十四、提交历史的考古学：blame、bisect 与回归定位
版本管理在日常开发时只体现为提交和推送，它真正的价值在「出了问题要回到过去」时才兑现。第一个场景是 git blame：当一行约束或一段 CDC 代码看起来莫名其妙时，逐行追溯它是在哪次提交、为了解决什么问题而引入的，能避免你把一个花了很大代价才修好的问题重新改回去。规则是看到可疑代码先 blame 再动手，尤其当提交信息写得清楚时，五分钟的考古能省下半天的重新踩坑。第二个场景是 git bisect：现场报告「上个季度的版本正常，现在的版本偶发丢帧」，中间隔着几十个提交时，人工逐个回退几乎不可行；bisect 用二分法，大约六七次构建就能在一百个提交里锁定第一个引入问题的版本，再看那次 diff，根因往往一目了然。用好 bisect 的前提正是每个提交都可独立构建、可运行测试——这也是为什么提交纪律不是形式主义。
第三个场景是版本回退和热修复分支。产品已经发往现场，主干却在开发新功能，这时要能从对应 tag 拉出修复分支，只最小化修改问题点、构建补丁版本，而不是把主干上半成品的新功能一起带给客户。这要求打 tag 的纪律：每次对外发布（包括只发给测试的版本）都打带日期和版本号的注解标签，标签和比特流制品一一对应。团队还要约定分支模型的最简版本：主干始终可发布，开发在分支进行，修复从 tag 拉分支再回合主干。模型不必复杂，三五个人的小团队用「主干加短分支」足够，但「随时能从任何一个现场版本重建并打上最小补丁」的能力必须具备，这是版本管理从事后记录升级为维护能力的标志。
十五、代码评审在硬件项目里的特殊清单
RTL 评审和软件评审看似都是读代码，但关注点清单不同，直接套用软件经验会漏掉硬件特有的致命问题。时钟和复位方面：每个模块是不是单时钟域，跨域信号有没有显式同步结构，复位是同步还是异步、释放是否经过同步，有没有用组合逻辑生成门控时钟。数据通路方面：位宽在每次运算后如何变化，加减两端的 Q 格式是否对齐，状态机是否有默认状态和未定义状态的逃逸路径，case 是否完整、有没有意外锁存。接口方面：握手信号是电平还是脉冲、跨模块时有没有被对方时钟正确采样，valid 和 ready 的先后关系是否和全设计统一。时序例外方面：每条 false_path 和 multicycle 有没有注释、能不能用波形证明、评审人是否确认——这一类要逐条过，因为单条错误就可能让整片逻辑失去检查。
评审流程上建议两个轻量实践。一是提交模板化：合并请求里固定写「改了什么、为什么、仿真结果、资源和时序数字、风险点」，评审人照着五项提问，评审质量立刻稳定下来。二是评审分两轮：第一轮只看架构和时钟复位结构（改动文件清单、模块框图），第二轮才逐行看实现；如果第一轮就发现跨域设计错误，逐行细看全是浪费。对纯学习的个人仓库，可以用「自我评审」模拟这个流程：提交前把 diff 打印出来，假设自己是评审人，按上面的硬件清单逐项质疑。坚持几十次之后，很多低级问题在写代码的当下就被你自己拦下了——评审清单最终会内化成写 RTL 时的实时自检。
十六、制品、发布与现场版本的闭环
源代码可追溯只完成了一半，另一半是「烧到现场设备里的每个比特流都能反查到确切的源码状态」。制品管理的最小实践是：CI 或本地构建发布版本时，自动把比特流、使用的约束、时序和资源报告、工具版本、完整的 commit 哈希打包成一个以版本号命名的压缩包，上传到团队共享存储而不是只留在构建机器上。文件名或包内清单里必须有 commit 哈希和构建时间，现场设备上报的版本号能直接对应到这个包。这样当客户报故障时，你能在几分钟内拿到与现场逐字节一致的比特流和它的全部构建上下文，而不是问一圈「那个版本是谁在谁的电脑上编的」。
发布还要有分级和记录的概念。开发版只给实验室、内测版给少量友好用户、正式发布版才进入产线，每一级都有对应的 tag 和变更说明。变更说明不需要长，但要回答三个问题：相对上一版改了什么、已知问题有哪些、升级后现场需要重新做哪些校准或配置。配合前文的版本注入，设备上电自报家门、仓库 tag、制品包、变更说明四者用同一个版本号串起来，就形成了从一行代码到一台现场设备的完整闭环。这个闭环平时看起来只是「规范」，一旦出现批量故障，它决定你是在一天内定位并精准召回受影响批次，还是在混乱中面对成百上千台无法区分版本的设备。工程化的所有投入，本质都是在为这种时刻购买确定性。而确定性恰恰是硬件产品区别于演示项目的根本属性：客户不会为你的开发速度喝彩，却会为一次无法解释的现场故障放弃整个平台。把版本、构建、制品、发布串成闭环，你交付的就不只是一个设计，而是一份多年后仍然有人能接手、能复现、能负责的承诺，这正是工程专业精神的落点。
五、常见坑对照
| 坑 | 后果 | 建议 |
|---|---|---|
| 提交整个 runs 工程 | 仓库巨大、冲突多 | 源 + tcl + .gitignore |
| 依赖 GUI 绝对路径 | 换机打不开 | 脚本化相对路径重建 |
| 漏提交 .xci/.bd | IP 丢失 | 提交 IP 配置 |
| 工具版本不一致 | IP 升级/结果漂移 | 写死版本、统一 CI |
| 现场不知哪版固件 | 无法定位回归 | git hash 注入可读 |
| 大二进制塞 Git | 克隆膨胀 | LFS/制品库存放 |
相关与延伸
上板配合：上板调试思路、比特流下载固化。 IP/脚本：IP 核怎么调、开源工具链与 CI；团队/CI 化深入见专家层（规划）。
一句话总结
RTL 工程化的核心是“仓库只存源和重建脚本、不存庞大产物”，用 Git + tcl 做到任何机器一键可复现。该提交 RTL、XDC/SDC、Testbench、构建脚本和 IP 配置（.xci/.bd），用 .gitignore 排除 Vivado 的 .runs/.cache 和 Quartus 的 db/output 及 .bit/.sof；可复现靠 write_project_tcl 或 non-project 脚本（read_verilog/read_xdc→synth→place/route→write_bitstream），vivado -mode batch 一条命令出比特流，适合 CI。IP 提交配置而非全部产物，写死并统一工具版本，换版本重生成 IP、重验时序。再把 git short hash 在构建时注入成可读 localparam，上电从 UART/寄存器读出；配合小步提交、feature 分支、上板打 tag、大文件走 LFS/制品库，现场任何问题都能回到确切源码版本复现——这正是从业余走到工程化的关键习惯。
上一篇：49 SPI 读取 ADC 入门（CPOL/CPHA/主控状态机） ｜ 下一篇：51 FPGA 岗位与学习路径（逻辑/接口/算法/原型） ｜ FPGA 系列目录