本页说明从工程初始化、器件型号选择、HDL 库导入、文件清单管理，到使用 Xilinx Vivado 或 Efinix Efinity 完成硬件综合、实现与比特流生成的完整流程。构建完成后，请参考 HARD 下载与固化 将产物烧录至开发板。

章节快速导航：器件选择补全 · 硬件代码复用 (HDL 库) · 文件清单管理 (Filelist) · Xilinx 工程创建与构建 · Efinix 工程创建与构建

工程初始化

1. 在 VS Code 中用 文件 → 打开文件夹 打开工程根目录。
2. 执行 TOOL Options → Create Project Configuration，输入工程名并选择 xilinx 或 efinity。已有 .vscode/property.json 时直接编辑配置，不必重新创建。
3. 命令生成 .vscode/property.json、prj/ 及标准 user/ 目录。将设计源码放入 user/src、testbench 放入 user/sim、板级约束放入 user/data。
4. 将初始 device: "none" 换成真实器件，在 Architecture 中设置设计与仿真顶层；顶层填模块名，不是文件名。
5. 按需配置 工具链路径，核对源码依赖、时钟和引脚后再构建。

新建工程演示见 启用与最小配置。ch01–ch06 连续使用同一示例工程 demo_project（器件为 xc7z010clg400-1，设计顶层为 demo_board，仿真顶层为 demo_tb）。

---

1. 器件选择补全

在 .vscode/property.json 中设置 toolChain（"xilinx" 或 "efinity"）后，将光标置于 device 字符串内，输入前缀或按 Ctrl+Space 即可触发分级补全（无需本机预装厂商软件）：

1. 选择器件家族前缀（如 xc7a、xc7z、Ti）。
2. 选择具体芯片型号。
3. 选择封装类型。
4. 选择速度等级，完成完整芯片型号输入。

toolChain 取值	内置器件候选库来源
"xilinx"	涵盖 Vivado 2022.2 支持的 41 个系列/变体、共 4,131 个真实器件型号
"efinity"	涵盖 Efinity June 2024 支持的 Trion 与 Titanium 系列、共 360 个器件型号

器件型号说明

• device 仍支持手动输入任意型号字符串；实际能否综合与生成比特流取决于本机安装的厂商工具版本与器件支持包。
• JTAG 扫描识别出的芯片系列名不含封装与速度等级，配置 device 时请务必对照开发板原理图填写完整型号（如 xc7z010clg400-1）。

---

2. 硬件代码复用 (HDL 库)

Digital IDE 提供内置公共 HDL 库（common）与自定义共享库（custom）机制，便于跨工程复用模块源码。导入库成员会将引用写入 property.json 的 library 字段（源码保留在原库目录，不复制到当前工程）。

操作演示：导入公共库并例化模块

以下视频演示从 Architecture 标题栏打开库浏览器，导入 common → Basic → Math → FixedPoint 下的 accuml.v，确认 src 中出现 accuml，再通过 TOOL Options → Instantiate Module 选择该模块并在光标处插入例化模板，将 WIDTH 设为 16 并连接 clock、reset、clr、add_sub、D 和 Q 端口：

导入与使用步骤

1. 打开库浏览器：点击 Architecture 标题栏右上角的库导入按钮（Import HDL Libraries (References)），或在命令面板执行同名命令。
2. 选择库来源：
   • common：扩展内置的公共 HDL 库（如需覆盖路径可配置 digital-ide.lib.common.path）。
   • custom：用户维护的共享 HDL 源码库（读取 digital-ide.lib.custom.path；未配置时可临时选择本地目录）。
3. 浏览并导入模块：按 Enter 进入子目录（选择 ... 返回上级），找到目标文件或目录后点击其右侧的导入按钮（已导入项可再次点击移除引用），按 Esc 退出。
4. 在代码中例化模块：导入操作仅添加工程源码依赖；随后可在编辑器中输入模块名使用自动补全，或点击 TOOL Options → Instantiate Module 插入例化模板并连接端口。

本次导入后，.vscode/property.json 中会新增如下引用记录（合并到已有配置，不要覆盖器件与顶层等字段）：

{
  "library": {
    "state": "remote",
    "hardware": {
      "common": ["Basic/Math/FixedPoint/accuml.v"],
      "custom": []
    }
  }
}

库管理注意事项

• library.state: "remote" 表示引用外部库路径（无需联网），修改共享库中的源文件会同步影响所有引用该文件的工程。
• 团队协作共享工程时，建议各成员统一配置 digital-ide.lib.custom.path 并使用相对路径引用，避免将个人机器的绝对路径写入 property.json。

---

3. 文件清单管理 (Filelist)

支持将工程模块依赖导出为 .f 文件清单，或将已有的 .f / .fl / .filelist 清单导入到当前工程配置中。

操作演示：导入文件清单

以下视频演示查看 sources.f、按 F1 执行 Digital-IDE: import filelist，以及导入后自动更新 files.src、宏定义（filelist.defines）、头文件目录（filelist.includeDirs）、来源清单（filelist.sources）与 Architecture 结构树：

导出与导入操作

• 导出文件清单 (export filelist)：
  • 在 Architecture 中右键目标模块选择 export filelist，以该模块为依赖起点导出 .f 文件（若直接从命令面板执行，则导出整个工作区范围的文件清单）。
• 导入文件清单 (import filelist)：
  • 在命令面板执行 import filelist 并选择 .f、.fl 或 .filelist 文件。
  • 插件会将解析出的源文件路径、宏定义和 +incdir+ 目录合并写入 property.json 的 files 与 filelist 字段，并在 Output 中报告无法解析的条目。
  • 清单中的相对路径以 .f 文件所在目录为基准。本例将 rtl/sample_counter.v 加入 files.src，将 include 加入 filelist.includeDirs，将 DEMO_MODE: "1" 加入 filelist.defines，并在 filelist.sources 记录 sources.f；Architecture 随后出现 sample_counter。

---

4. Xilinx 工程创建与构建

准备工程输入

纯 FPGA 示例：

{
  "toolChain": "xilinx",
  "prjName": { "PL": "demo" },
  "device": "xc7a35tftg256-1",
  "srcTop": "top",
  "simTop": "top_tb",
  "soc": { "core": "none" }
}

标准目录下可以省略 arch。自定义布局时，完整设置设计、仿真、数据及软件目录，避免编辑器扫描范围和厂商构建输入不一致。

输入	放在哪里 / 如何配置
设计 HDL	user/src，其他位置的文件通过 arch 或 files.src 指定。
引脚与时序约束	user/data 中的 XDC，按板卡原理图设置管脚、电平和时钟。
HDL 库	用 硬件代码复用 加入公共库或自定义库引用。
厂商 IP / BD	默认 user/ip、user/bd；自定义封装 IP 仓库使用 IP_REPO。
Vivado 程序	在设置中填写 digital-ide.prj.vivado.install.path，推荐 bin 目录或完整程序路径。

已有 Vivado 工程应先备份，再使用扩展提供的转换入口迁移并核对工程输入，详见 工程界面导览。

启动、同步与构建

顺序	HARD Options 入口	完成后检查什么
1	Launch	创建/打开厂商工程，导入源码、约束、IP、BD 和库；等待会话显示 Ready。
2	Refresh（输入发生变化时）	将当前配置和工程输入同步到 Vivado。
3	Build	执行综合、实现与比特流生成；检查每个阶段状态。
按需	Build → Synth / Impl / BitStream	分阶段定位综合、布局布线或产物生成问题；前一阶段产物必须有效。
按需	Simulate → CLI / GUI	运行厂商工程仿真；它与快速交互仿真是两个入口。
结束	Exit	结束当前工程会话。

在 Output → Digital-IDE Hardware 中可查看实际工作目录、调用命令与日志输出。新增源文件、库或约束后，请先点击 Refresh 同步，再执行 Build。

Xilinx 全流程：工具链校验到 SRAM 下载

本片使用 Digital-IDE 0.5 和 Vivado 2022.2，在前几章逐步完成的 demo_project 上演示最小 Xilinx 工程目录核对、Launch、Refresh、综合、实现、比特流生成、可视化构建报告及板卡 SRAM 下载（工具链路径配置与校验见 工具链路径配置，Flash 固化配置见 HARD 下载与固化）。构建等待已缩短。示例顶层 demo_board 使用内部配置时钟 STARTUPE2/CFGMCLK。

阶段	正常完成的标志	还要分析什么
Refresh	会话 Ready，源码、约束、IP 已同步到 Vivado 工程。	确认新增源码、约束和 IP 均已导入工程。
Synth	synth_design completed successfully，生成综合检查点。	检查 Errors、Critical Warnings 与普通 Warnings。
Impl	route_design completed successfully；All user specified timing constraints are met。	核对 routed 报告与时序约束覆盖。本例 WNS 8.378 ns、WHS 0.155 ns、TNS/THS 0，失败端点均为 0。
BitStream	write_bitstream completed successfully，工程根目录出现新的 demo_project.bit。	本例 routed DRC 有 2 条警告、0 个错误：ZPS7-1（纯 PL 示例未启用 PS7）与 RTSTAT-10（计数输出未连接外部引脚）。生成后建议逐条核对 DRC 提示。
Program → SRAM	hardware/program: completed；状态寄存器回读 DONE=1、INIT_B=1、CRC_ERROR=0。	确认 FPGA 配置完成，并结合开发板外设验证功能（如需掉电保留，请继续执行 Flash 固化）。

示例器件为 xc7z010clg400-1。由于 JTAG 扫描仅识别芯片系列名，配置 device 时请对照开发板原理图填写包含封装与速度等级的完整型号，并在 XDC 文件中配置对应的时钟、管脚和电平约束。

配置和修改 Xilinx IP

toolChain 为 xilinx 时，点击 HARD Options → IP Catalog 打开 Xilinx IP 配置页（命令面板对应 Digital IDE: Configure Xilinx IP）。

1. 先设置 device 与 Vivado 路径，在 HARD 执行 Launch 并等待 Ready，后续的 IP 配置与生成将直接复用该会话。
2. 点击 IP Catalog，读取已安装 Vivado 的目录，按名称或 VLNV 搜索；IP_REPO 中的自定义仓库也会加入目录。
3. 选择 IP，填写模块名和参数，点击 校验并更新参数（Verify and update parameters）。选项、范围和联动值以 Vivado 校验结果为准；修改 ILA/VIO 探针数后也要重新校验。
4. 选择输出父目录，再点击 Generate IP。默认父目录为源码目录同级的 ip（标准工程下为 user/ip）。生成完成后可查看 父目录/模块名/模块名.xci 及 .veo / .vho 例化模板。
5. 在 HDL 中连接实例，再构建工程。新 IP 会直接加入当前 Vivado 会话；外部输出目录需要加入可发现的工程输入，才能在重启后再次导入。

修改已有 IP 时，在 Architecture 点击对应 IP/XCI。模块名和输出位置保持固定；先校验，再点击 保存并重新生成。预览使用临时副本；保存前会检测 XCI 是否被外部修改。锁定 IP 的版本升级仍需在 Vivado 中完成。

生成要求会话空闲、Ready，且器件和工程一致。已有同名目录不会被覆盖。取消生成、关闭正在生成的页面，或已有 IP 保存失败时，会停止 HARD 会话并清理/恢复相应文件，需要重新 Launch；取消参数预览只会停止预览任务。

IP 配置页的支持范围

配置页使用 HTML 重建参数控件，支持分页、分组、表格、布尔值、下拉选项以及部分动态图表。它跟随 VS Code 主题，参数检查仍交给已安装的 Vivado，不需要传输厂商桌面画面。

ILA/VIO 的探针表和位宽示意、Binary Counter 的分页已适配。对于包含复杂专用向导的 IP（如 Clocking Wizard、PS7），配置面板会列出当前支持的可配置参数范围。

目录查询与参数预览复用独立的 Vivado 预览进程；实际生成使用已经 Launch 的 HARD 会话。目录缓存为 5 分钟，修改仓库后可主动刷新；关闭或空闲 2 分钟会释放预览进程。首次加载复杂 IP 仍需要等待，耗时和错误见 Hardware 输出。IP 许可证仍由本机 Vivado 检查。

Xilinx IP 配置与生成演示

演示从展开 HARD Options 并执行 Launch 开始，待会话 Ready 后点击 IP Catalog 打开配置页，搜索并选择 xlconstant。

将模块名设为 step_constant、CONST_WIDTH 设为 16、CONST_VAL 保持 1；校验后生成 user/ip/step_constant/step_constant.xci。视频先查看 .veo 模板，再在 demo_top.v 输入 step_c，选择 step_constant · module instantiation 并按 Enter 插入例化，将 dout 连接到 16 位同名信号。最后在 Architecture 中核对 u_top 下的 step_constant。Vivado 启动与 IP 目录读取等待已缩短。

生成的 IP 包装文件若出现时标或厂商依赖相关的编辑器诊断，可结合 Vivado 的生成与综合日志排查。

检查构建报告和产物

将鼠标移到 Build / Synth / Impl 行，点击图表图标 查看构建报告。页面展示当前 Vivado 工程的资源占用、时序裕量、功耗和 DRC 汇总，并支持打开原始报告文件。

当前流程将供下载使用的比特流写到工程根目录的 <prjName.PL>.bit。以 Output 和本次实际产物为准，确认生成时间及设计一致，再进入下载步骤。

包含处理器的设计在生成比特流时会自动导出硬件交接文件（默认目录为 user/sdk/data），后续软件开发步骤见 SDK 构建与处理器调试。

---

5. Efinix 工程创建与构建

Efinix 是厂商名称，Efinity 是软件名称；配置统一使用 toolChain: "efinity"。

{
  "toolChain": "efinity",
  "prjName": { "PL": "demo" },
  "device": "Ti180J484C4",
  "srcTop": "top",
  "simTop": "top_tb",
  "soc": { "core": "none" }
}

通过 器件选择补全 选择目标开发板对应的真实器件型号（含封装与速度等级），并在数据目录配置对应的引脚绑定与 SDC 时序约束。

先选择执行模式

模式	设置	当前支持
原版 Efinity	digital-ide.efinity.install.path 指向原版安装根目录	Launch / Refresh 生成工程 XML、ISF、SDC，并调用 Interface Designer。后续综合和布局布线在原版 Efinity 中完成。
自包含 package	原版路径留空，digital-ide.prj.efinix.package.path 指向有效 package 根目录	由后端执行综合、布局布线和产物生成；使用 package 内的工具及器件资源。

原版路径非空时优先选择原版模式，即使同时配置了 package。 想使用 package 模式，需要在有效设置范围内将原版路径清空。原版模式目前不会执行 HARD Build、SRAM 或 FLASH，也不会在这些操作失败后自动切换到 package。

原版模式：生成并打开厂商工程

1. 安装 Efinity，配置其根目录，检查该目录下的 bin/efinity 与 bin/efx_run 可用。
2. 设置工程的名称、器件、设计顶层和源码目录，确保至少有一个设计 HDL 文件。
3. 在数据目录准备 rust/efinity.defaults.toml 与 rust/pins.toml。前者保存接口/电气默认设置，后者保存板级资源和引脚绑定；端口名称需要与 HDL 顶层一致。时序约束使用 SDC。
4. 运行 HARD → Launch。后端读取当前工程输入，生成 prj/efinity/<工程名>.xml、.isf、.sdc、.sources.json，再调用原版 Interface Designer 生成 .peri.xml。
5. 在 Output 核对生成路径和 Interface Designer 结果。使用原版 Efinity 打开生成的 XML 工程，继续综合、布局布线和产物生成。需要硬件写入时使用该模式支持的厂商工具操作。
6. 修改源码、接口默认值或引脚后运行 Refresh，重新检查生成结果，再继续厂商构建。

若缺少 TOML 配置文件或引脚绑定有误导致 Launch 报错，请根据 Output 日志修正配置后重新执行 Refresh。

package 模式：在扩展内构建

1. 在受支持的主机上准备完整有效的 package。当前 package 后端资源为 Linux 工具；目录中的 bin、lib、arch、res 必须匹配，不能只复制几个程序。
2. 清空原版安装路径，设置 package 根目录；确认器件资源和版本校验通过。
3. 配置 property.json、RTL 和 SDC。需要接口生成时准备 user/data/rust/design.toml，或用 efinity.interfaceConfig 指向实际接口配置；已有接口产物也必须匹配当前器件和设计。
4. Launch 校验工程和 package，输入变化后用 Refresh 更新。再执行 Build，或依次执行 Synth → Impl → BitStream。
5. 在默认的 prj/efinity/outflow 检查 <工程名>.bit / .hex 及报告，以操作结果和本次实际文件为准。

各阶段分别对应 efx_map（综合）、efx_pnr（布局布线）与 efx_pgm（生成编程镜像文件）。当前 package 后端暂不提供 HARD 的厂商 GUI 和厂商仿真入口，testbench 仿真请使用 快速与交互仿真。

原版模式和 package 模式的输入、工具和生成步骤不同。切换模式前先备份并隔离旧产物，避免把另一模式的输出当成当前结果。package 模式的下载与固化还有器件族和连接要求，见 HARD 下载与固化。

---

6. 构建失败常见问题排查

现象	检查与处理方向
综合报错找不到模块、package 或 `include 文件	检查 arch 源码目录配置、srcTop 顶层名、library 库引用、filelist.includeDirs 头文件路径及宏定义。
DRC 报错 UCIO-1（未约束 IO 管脚）	对照开发板原理图在 user/data/ 的 XDC 文件中补齐所有顶层端口的引脚位置（PACKAGE_PIN）和电平标准（IOSTANDARD）。
Xilinx IP 提示 locked 或版本不匹配	检查当前 Vivado 版本、IP 版本与目标 device 型号是否一致，必要时在 Vivado 中升级 IP。
Efinity 提示当前操作不支持	确认当前处于原版 Efinity 模式还是 package 模式：原版模式仅负责 Launch/Refresh 生成工程，综合与烧录需在原版软件或切换到 package 模式执行。
日志打印了 .bit 路径但任务显示 failed	在 Output → Digital-IDE Hardware 中向上查找最早出现的 ERROR 行，并核对产物文件的实际修改时间，切勿将历史遗留的旧 .bit 文件当作本次构建结果。

相关文档

• 工程界面导览
• 工程配置详解 (property.json)
• HARD 下载与固化
• SDK 构建与处理器调试