这一篇在干嘛？
这是《TD User Guide》总览三连的第 1 篇，覆盖原书第 1~3 章：先把 TD 软件的全局地图画出来——一个工程从新建到出比特流要经过哪些环节，再手把手走一遍工程管理与 IP 生成。后续两篇：第 2 篇讲约束、编译流程与时序报告，第 3 篇讲仿真下载、调试工具与报错排查。
TD 全景：一条龙覆盖设计全流程
TD（TangDynasty）是安路 FPGA 的官方一体化开发环境，地位相当于 Xilinx 的 Vivado + Intel 的 Quartus。对移远大赛用的 EG4S20（Eagle 系列）来说，从 RTL 代码到板上运行的完整链条全部在 TD 里完成，不需要装第二套工具。
启动 TD 后先选一个 workspace（工作区）目录，之后所有工程的默认路径、界面布局都记在这里。主界面最核心的是 Design Flow 流程窗口：它把整个开发流程画成一列按钮，从上到下依次是综合（Synthesize）、优化（Syn Opt / Optimize Gate）、物理优化（Phy Opt / Optimize Routing）、布局布线（Place & Route）、位流生成（Bitstream Generation）等，每个按钮左键单击执行、右键还有更多选项。编译到哪一步、成功失败，都通过这列按钮的状态标和下方 Message / Tcl Console 窗口反馈。
学习方法
把 Design Flow 这列按钮当成”进度条”：你写的每行 Verilog、每条约束，最终都要顺着这条流水线变成比特流。哪一步卡住，就去查那一步对应的章节——这正是这套总览笔记的编排顺序。
一个典型工程的完整生命周期是：
新建工程 → 添加 RTL 源文件 → (生成/添加 IP) → 添加约束(引脚+时序)
→ 综合 → 布局布线 → 查看时序报告 → 功能/时序仿真 → 生成位流 → 下载调试
工程管理：新建工程、源文件与顶层
新建工程
菜单 File → New Project 打开向导（对应下图），依次填写：
- 工程名与路径：路径不要含中文和空格，否则后续 tcl 脚本容易出幺蛾子；
- 工程类型：RTL 工程选 “RTL Project”；只有网表要跑布局布线的场景选门级工程；
- 器件选择：在 Part 选择页按 Family = Eagle、Device = EG4S20、Package = BG256 逐级选到大赛器件；
- 语言与仿真器：HDL 选 Verilog，仿真器可先保持默认（第 3 篇讲仿真）。
工程建好后，左侧 Project Manager 会列出 Sources（设计文件）、Constrains（约束文件）、Simulation（仿真文件）等分组，右键分组即可 Add Sources 添加文件。向导支持从别的工程批量导入，也支持直接拖拽文件进来。
设顶层与文件管理
多模块工程一定要把最顶层的模块设为 Top：在 Sources 里右键目标文件 → Set As Top，顶层文件图标会变化。顶层选错是新手最常见的问题——综合时报”端口悬空”或者压根不报错但逻辑被整体优化掉，往往就是顶层指错了。
语言模板与编辑器
TD 内置代码编辑器带语法高亮、代码补全和例化模板。菜单 Edit → Language Templates 打开语言模板浏览器，里面有 Verilog 常用结构、器件原语（Primitive）的例化骨架，双击即可插入当前文件。写 always 块、例化 IP 时很省事。
导出 Tcl：让工程可复现
工程管理里最值得养成习惯的一招是 导出 Tcl 脚本（File → Export → Tcl）。它会把工程的器件型号、源文件列表、约束引用等全部生成一条条 tcl 命令。换电脑、进版本库、交给队友时，不用拷整个工程目录，只拷源码 + 这份 tcl 就能一键重建工程。这也是后面所有界面操作（约束、编译选项）的”文本化”途径：凡是在界面上能点的，最终都能落到 tcl 上。
常见坑：
① 工程路径含中文/空格 → 综合、IP 生成随机报错，一律用纯英文短路径； ② 顶层没 Set As Top → 逻辑像”消失”了一样，资源占用为 0； ③ 只拷贝 .al 项目文件给队友 → 别人打开全路径报错，正确做法是导出 Tcl + 源码； ④ 源文件加了但忘了勾选加入当前工程 → 文件躺在磁盘上，编译器看不见。
IP 生成器：IP Catalog 与常用 IP 配置
手写 PLL、BRAM 这类专用资源的行为模型既低效又不可综合，正确做法是用 TD 的 IP 生成器：菜单 Tools → IP Compiler（IP Catalog）打开目录窗口，左侧按功能分类，右侧双击具体 IP 新建实例。
EG4S20 上常用的几类：
| 类别 | IP | 用途 |
|---|---|---|
| 时钟 | PLL | 从板载晶振分出系统所需的各路时钟 |
| 存储器 | ERAM / FIFO / DRAM | 片上块RAM、同步FIFO、分布式RAM |
| 运算 | Divider / CORDIC / DSP | 除法、三角函数、乘累加 |
| 接口 | LVDS7_1 / TEMAC | 高速串行接口、以太网 MAC |
| 校验 | CRC | 通信数据校验 |
以最常用的 PLL 为例：双击新建后进入配置页，第一步设输入时钟频率（EG4S20 开发板常见 50 MHz），第二步逐路配置输出时钟——每一路可独立设频率、相位偏移、占空比，软件会实时校验该频率组合能否实现，配置好一路勾选一路。确认后生成 .v 设计文件、.xco 配置文件和例化模板，把例化模板贴进顶层模块、接上时钟复位就能用。
ERAM（Embedded RAM）是写图像行缓存、乒乓缓冲的主力：配置页选单口/双口模式、设数据位宽与深度（注意不要超过 EG4S20 的 ERAM 总量，Design Summary 里能看到用了几成）、按需勾选输出寄存器以改善时序。FIFO IP 的思路相同，多一个几乎空/几乎满（AF/AE）阈值配置。
生成的 IP 一律以文件形式挂在工程 Sources 的 IP 分组下，和手写 Verilog 地位平等，可以随时双击 .xco 重新打开配置页修改。IP 引脚与内部行为以生成出的 .v 文件和手册为准，别凭记忆猜端口。
常见坑：
① PLL 输出频率超出器件范围或不整除 → 配置页报红也不细看，编译才炸； ② ERAM 深度位宽超器件总量 → 布局布线阶段才失败，白白浪费一轮编译； ③ 例化 IP 时端口顺序靠猜 → 一定从生成的例化模板复制； ④ 修改 IP 配置后忘了重新综合 → 顶层和 IP 行为不一致，仿真对、上板错。
通关标准：
① 能 5 分钟内新建一个指向 EG4S20BG256 的工程并添加自己的 Verilog 顶层； ② 会用 Language Templates 快速插入例化骨架，且顶层永远是 Set As Top 后的那个文件； ③ 能用 IP Catalog 生成一个 50 MHz → 自定义频率的 PLL 和一块 ERAM，并在顶层例化通过综合。
为什么工程路径不能有中文和空格？
TD 的不少流程（IP 生成、Tcl 脚本导出、命令行综合）会把路径直接拼进脚本和日志。中文在部分环节存在编码转换问题，空格会破坏按空格分词的命令行参数，二者都可能造成”随机”失败。纯英文短路径是最省心的做法。
[!question]- 导出 Tcl 有什么实际用处？
它把工程的全部”装配信息”（器件、源文件、约束引用）变成纯文本。进 Git 只需要源码 + Tcl；换机器用 Tcl 重建工程；而且任何界面选项都能在 Tcl 里找到对应命令，是排查”我到底改了什么设置”的依据。
[!question]- IP 生成的 .xco 和 .v 各是什么角色？
.xco 保存 IP 的全部配置参数，双击可重新打开配置页修改；.v 是按参数展开后的设计文件，参与综合仿真。改配置要动 .xco（通过界面），不要手改 .v。
[!question]- PLL 配置页里相位和占空比什么时候需要改？
默认 0° / 50% 够用。需要多相采样（如 ISERDES 前的对齐时钟）、或给输出 DDR 接口生成奇数占空比时钟时才调。每改一路都要看软件的可行性校验结果。