工程配置详解

3705 字约 12 分钟

2025-01-08

property.json 是工程的说明文件，保存器件、顶层、目录、依赖和厂商参数。文件位于工程根目录的 .vscode/property.json；创建与构建步骤见工程创建构建，本页用于查询具体字段。

修改配置前先了解

字段名区分大小写，支持 JSONC 注释和尾随逗号，不允许重复键。
property.json 保存工程信息；本机程序路径放在 VS Code 设置中，见工具链路径配置。
当前 Schema 要求 toolChain、soc、device。自动生成的 device: "none" 需要换成真实器件，才能执行厂商构建。
表中的默认值描述字段省略时的处理，不表示这些值会自动写回文件。只修改需要调整的字段，保留已有工程配置。

先看常用示例，再按任务查询：名称与顶层、目录、文件成员、HDL 库、filelist、处理器、Flash 和 Efinity 专用字段。旧字段集中列在末尾，便于迁移已有工程。

常用配置示例

下面展示纯 FPGA 工程的常用结构。器件、工程名、顶层和目录需要与实际设计对应；未使用的 files、library、filelist 可以省略，标准目录下也可省略整个 arch。

{
  "toolChain": "xilinx",
  "prjName": { "PL": "demo" },
  "device": "xc7a35tftg256-1",
  "srcTop": "top",
  "simTop": "top_tb",
  "arch": {
    "prjPath": "prj",
    "hardware": {
      "src": "user/src",
      "sim": "user/sim",
      "data": "user/data"
    },
    "software": {
      "src": "user/sdk",
      "data": "user/sdk/data"
    }
  },
  "files": { "src": [], "sim": [], "exclude": [], "scanIp": true },
  "library": {
    "state": "remote",
    "hardware": { "common": [], "custom": [] }
  },
  "IP_REPO": [],
  "filelist": { "sources": [], "includeDirs": [], "defines": {} },
  "soc": { "core": "none" }
}

顶层填 HDL 中的模块名或 entity 名，例如 top，不要填 top.v 或文件路径。工程名称与 HDL 名称独立，重命名工程不会同步重命名模块。

教程视频 ch01–ch04 在同一个 demo_project 上逐步完善配置：ch01 初始化工程配置，ch02 设置器件 xc7z010clg400-1 与顶层模块 demo_board / demo_tb，ch03 添加公共库 Basic/Math/FixedPoint/accuml.v，ch04 导入 filelist 源码与宏定义。

工具链、名称与顶层

字段	类型与取值	含义及实际作用
`toolChain`	字符串：`xilinx`、`efinity`	选择厂商工程流程、器件补全库和构建适配器，分别对应 Vivado 与 Efinity。
`prjName`	对象	保存硬件与软件工程名。
`prjName.PL`	非空字符串	硬件工程名，如 `demo` 对应 Vivado 的 `demo.xpr`。生成时使用输入的名称，加载时缺省回退为 `template`，不必与 HDL 顶层同名。
`prjName.PS`	字符串，可省略	Xilinx 软件工作区名称，参与软件输出目录及首个应用命名。SOFT 流程省略时使用 PL 名；纯 FPGA 工程通常不用填写。
`device`	字符串	完整 FPGA 型号，影响综合、布局布线和厂商 IP。包含实际封装、速度等级等信息，不能使用开发板昵称；`none` 或空值不能用于厂商构建。
`srcTop`	字符串，可省略	设计顶层模块或 entity，用于设计层次和硬件综合。未指定时由相应流程解析/选择；多个候选时建议明确填写。
`simTop`	字符串，可省略	工程仿真顶层，通常是 testbench，与 `srcTop` 分别设置。快速仿真或 Netlist 以该次选择的模块为入口。
`simRuntime`	字符串，如 `"1000ns"`、`"all"`	Xilinx 后端扩展字段，传给 Vivado/XSim 的 `xsim.simulate.runtime`。省略时保留 Vivado 默认值；不控制快速交互仿真的时长。`all` 需要 testbench 能自行结束。

simRuntime 已由后端读取，但尚未列入基础 Schema 的字段补全。

目录结构 arch

arch 是目录配置对象，arch.hardware 和 arch.software 分别组织硬件、软件目录。下表默认值适用于已创建配置且省略整个 arch 的标准工程。

字段	类型 / 标准默认值	含义及实际作用
`arch.prjPath`	字符串，`prj`	厂商工程与中间产物的基础目录。Vivado 通常使用其下的 `xilinx/`，Efinity 使用 `efinity/`；Vivado 路径已以 `xilinx` 结尾时不重复追加。
`arch.hardware.src`	字符串，`user/src`	扫描设计 HDL 的目录，用于设计文件发现与分类。
`arch.hardware.sim`	字符串，`user/sim`	扫描 testbench 等仿真 HDL 的目录。
`arch.hardware.data`	字符串，`user/data`	约束与工程数据目录，如 XDC。Efinity 还从其下的 `rust/` 读取 `efinity.defaults.toml` 和 `pins.toml`。
`arch.software.src`	字符串，`user/sdk`	软件工作区基础目录；Xilinx SOFT 通常再建立以 PS 或 PL 名命名的子目录。
`arch.software.data`	字符串，`user/sdk/data`	软件工程使用的硬件描述目录，Xilinx SOFT 从中查找 `.hdf` / `.xsa`。

相对路径以工作区根目录为基准，也支持绝对路径。Windows JSON 路径建议使用 /，反斜杠需要转义。通用后端支持以下变量：

变量	展开结果
`${workspace}`	当前工程工作区根目录。
`${plname}`	`prjName.PL`，缺省回退为 `template`。
`${psname}`	`prjName.PS`，变量展开时缺省回退为 `template`；与 SOFT 工作区名称回退为 PL 名的规则不同。

自定义 arch 时建议完整填写上述目录。加载器只在整个 arch 缺失时补入标准结构；部分 arch 缺失 src / sim 时，HDL 扫描可能回退到整个工作区，而厂商构建仍有各自的默认目录，造成扫描与构建范围不一致。

Xilinx IP 和 BD 默认位于设计源码目录的同级 ip/、bd/，标准结构中即 user/ip/、user/bd/。当前配置没有 arch.hardware.ip 或 arch.hardware.bd 字段。

文件成员 files

files 在目录扫描结果上补充或排除文件，不替代 arch 扫描。

字段	类型 / 默认行为	含义及实际作用
`files.src`	字符串数组，默认无附加项	显式添加设计 HDL 路径，如扫描目录之外的 `shared/reset_sync.sv`。
`files.sim`	字符串数组，默认无附加项	显式添加仿真 HDL 路径，如 `tests/top_tb.sv`。
`files.exclude`	字符串数组，默认无额外排除	按归一化路径从扫描及显式添加的工程源文件中排除指定文件。不是 gitignore 通配符，不删除磁盘源码，也不代替移除 `library` 中的引用。
`files.scanIp`	布尔值，默认 `true`	控制 HDL 索引是否扫描 Xilinx IP/BD 生成目录。大型工程可设 `false` 降低解析量；导入 Vivado 工程时会写入 `false`。不等于从 Vivado 工程删除 IP/BD。

普通相对路径以工作区为基准。需要按目录或通配符忽略扫描时使用 .dideignore，并保留工程依赖的包、头文件和库。

HDL 库 library 与厂商 IP

library 描述 HDL 库引用，library.hardware 分组保存公共库和自定义库成员。厂商封装 IP 仓库使用独立的 IP_REPO 字段。

字段	类型 / 默认行为	含义及实际作用
`library.state`	`"remote"` / `"local"`，缺省 `"remote"`	选择库解析模式。`remote` 优先复用公共/插件库，也可由配置好的库提供器解析包；`local` 使用本地路径，不执行远程包解析。名称不表示必须联网，也不自动复制源码到工程。侧栏导入当前写入 `remote`。
`library.hardware.common`	字符串数组，默认空	公共 HDL 库文件或目录，相对路径以公共库根目录为基准；`remote` 还可交由已配置的提供器解析。只列出工程需要的成员。
`library.hardware.custom`	字符串数组，默认空	自定义 HDL 库文件或目录。绝对路径直接使用；相对路径优先基于 `digital-ide.lib.custom.path`，未配置根目录时基于工作区。目录引用会发现其中的 HDL 文件。
`IP_REPO`	字符串数组，默认空	Xilinx 自定义封装 IP 仓库目录，相对工作区解析，供 IP 目录查询和 Vivado 工程加载使用。不是普通 HDL 文件清单或 Vivado 安装路径。

库成员保留在原位置，移除引用不删除文件。操作方式见硬件代码复用。

文件列表元数据 filelist

filelist 记录导入 .f 等文件列表时保留的信息；实际 HDL 成员写入 files.src 或 files.sim。

字段	类型 / 默认行为	含义及实际作用
`filelist.sources`	字符串数组，默认空	来源文件列表路径，包括导入时解析到的嵌套列表。不是 HDL 文件数组；只改这里不会自动重新导入源码。
`filelist.includeDirs`	字符串数组，默认空	头文件搜索目录，如 `user/src/include`，相对工作区解析。供后端解析及使用该元数据的流程查找 include 文件，不是 HDL 库条目。
`filelist.defines`	对象，默认空	宏名到值的映射。字符串表示带值宏，`null` 表示只定义宏名，不表示取消定义。数值也应写成字符串。

以下片段定义 DATA_WIDTH=32 和无值宏 SIMULATION，可合并到已有配置：

{
  "filelist": {
    "sources": ["rtl.f"],
    "includeDirs": ["user/src/include"],
    "defines": { "DATA_WIDTH": "32", "SIMULATION": null }
  }
}

来源 .f 清单更新后，可重新执行导入命令同步变更，详见文件清单管理。

软件系统 soc

soc 描述处理器与软件应用。纯 FPGA 工程保留 {"core":"none"} 即可；软件开发还需要匹配的硬件描述和 XSCT/Vitis。

字段	类型 / 默认行为	含义及实际作用
`soc.core`	字符串，生成时 `"none"`	目标处理器。当前补全提供 `none`、`cortexM3`、`microblaze`、`ps7_cortexa9_0`、`ps7_cortexa9_1`、`psu_cortexr5`、`psu_cortexa53`。`none` 表示纯 FPGA；SOFT 优先从硬件描述识别处理器，再回退到此字段。
`soc.os`	字符串，SOFT 缺省 `"standalone"`	系统/BSP 类型：`standalone`、`linux`、`xilkernel`、`freertos10_xilinx`。可用组合取决于处理器、应用模板和厂商版本。
`soc.app`	字符串或非空、不重复的字符串数组；缺省 `"Hello World"`	厂商应用模板，如 `Hello World`、`Empty Application`、`lwIP Echo Server`、`FreeRTOS Hello World`。数组表示多个应用，不是已有源码路径或自定义应用名称。
`soc.bd`	字符串，建议省略	旧版 BD 模板字段，Schema 保留 `zynq_default`、`m3_xIP_default`、`MicroBlaze_default`、`PCIe_Test`。当前加载器保留此值，但构建流程未消费它来创建 BD；需要实际 `.bd` 文件及对应操作。

已有匹配 Zynq 硬件描述的工程可以合并以下片段：

{
  "prjName": { "PL": "demo", "PS": "demo_sdk" },
  "soc": {
    "core": "ps7_cortexa9_0",
    "os": "standalone",
    "app": ["Hello World", "Empty Application"]
  }
}

首个应用使用软件工作区名，后续应用按模板名自动生成工程目录，详见 SDK 构建与处理器调试。

持久化烧写 flash

flash 用于 Xilinx 配置存储器烧写，普通综合和 FPGA 易失性下载不必填写。可以使用型号字符串或对象；仅填写配置不会自动烧写硬件。

字段	类型 / 默认行为	含义及实际作用
`flash`	字符串或对象，可省略	字符串为 `get_cfgmem_parts` 返回的完整型号；对象可以指定额外选项。描述板上的配置 Flash，区别于 FPGA 的 `device`。
`flash.part`	非空字符串，对象形式必填	Vivado 配置存储器型号，必须匹配实际芯片与当前器件支持的型号：纯 PL 器件如 `w25q128fv-spi-x1_x2_x4`，Zynq-7000（如 xc7z010）用 QSPI 型号如 `w25q128fv-qspi-x4-single`。
`flash.interface`	字符串，可省略	覆盖 `write_cfgmem` 接口：`SPIx1`、`SPIx2`、`SPIx4`、`SPIx8`、`BPIx8`、`BPIx16`，按板级连接选择。
`flash.sizeMB`	正整数，可省略	容量覆盖，单位 MBytes，不是 Mbits；128 Mbit 对应 16 MB。
`flash.format`	`"mcs"` / `"bin"`，默认 `"mcs"`	生成的配置存储器镜像格式。
`flash.verify`	布尔值，默认 `true`	是否在 Flash 烧写流程中启用校验。

{
  "flash": {
    "part": "w25q128fv-spi-x1_x2_x4",
    "interface": "SPIx4",
    "sizeMB": 16,
    "format": "mcs",
    "verify": true
  }
}

省略 interface 与 sizeMB 时，烧写流程会根据所选配置存储器型号自动采用默认参数。

Efinity 扩展字段

以下由当前 Efinity 后端读取，基础 Schema 尚未列入补全，仅用于 toolChain: "efinity" 的工程。

字段	类型 / 默认行为	含义及实际作用
`efinity`	对象，可省略	Efinity 专用参数容器。
`efinity.top`	字符串，可省略	顶层优先级：`efinity.top` → `srcTop` → 旧字段 `top` → `prjName.PL`。通常只设置 `srcTop`，避免两处顶层冲突。
`efinity.family`	字符串，可省略	器件系列，省略时从 `device` 推断；显式值必须匹配器件和工具。
`efinity.timingModel`	字符串，可省略	时序模型/速度等级，优先于从 `device` 拆出的等级，仍未指定时回退为 `C4`。必须按实际器件选择。
`efinity.projectXml`	路径字符串，可省略	package 模式使用的工程 XML；未配置时检查 `prj/efinity/<工程名>.xml`（具体位置跟随 `arch.prjPath`）。
`efinity.interfaceConfig`	路径字符串，可省略	package 模式的接口设计 TOML。未配置时检查数据目录下的 `rust/design.toml`；原版模式使用固定的 `rust/efinity.defaults.toml` 与 `rust/pins.toml`。
`efinity.interfaceCsv`	路径字符串，可省略	package 模式的接口 CSV 输入；未配置时检查当前 outflow 中的 `<工程名>.interface.csv`。
`efinity.logicalPeripheryFile`	路径字符串，可省略	package 模式的逻辑外围 LPF 输入；未配置时检查当前 outflow 中的 `<工程名>.lpf`。
`efinity.optionRegisterIni`	路径字符串，可省略	package 模式的选项寄存器 INI 输入；未配置时检查当前 outflow 中的 `<工程名>_or.ini`。

这些扩展路径相对工程根目录解析，也可使用绝对路径。接口配置应与当前器件和设计匹配，不能仅靠填写某个产物路径替代接口生成。两种 Efinity 模式的选择和操作范围见工程创建构建。

旧字段与兼容写法

字段	当前处理方式
`enableShowLog`	Schema 保留的布尔字段，标注默认 `false`，旧含义是编译时显示日志。当前扩展和后端未读取它，不应依赖此字段控制日志显示；查看 Output 即可。
`simulationRuntime`	`simRuntime` 的兼容别名，同时存在时优先读取非空 `simRuntime`。
`top`	Efinity 顶层兼容字段，优先级低于 `efinity.top` 和 `srcTop`。
`program.flash`、`programmer.flash`、`configuration.flash`	Xilinx 旧 Flash 配置位置。按 `flash` → `program.flash` → `programmer.flash` → `configuration.flash` 使用第一个存在的字段；新配置统一用 `flash`。
`flash.model`、`flash.cfgmemPart`、`flash.cfgmem_part`	`flash.part` 的兼容名称，新配置用 `part`。
`flash.size_mb`、`flash.size`	`flash.sizeMB` 的兼容名称，同样以 MBytes 为单位，新配置用 `sizeMB`。

本页涵盖当前 Schema 的全部标准字段以及后端实际读取的扩展和兼容字段。

确认工程可用

保存配置，检查语法和类型错误。
展开 Architecture，核对 src、sim、库及模块实例，需要时刷新结构树。
核对设计/仿真顶层；右键设置顶层只修改对应字段，无需重建配置。
配置工具链路径配置，执行 TOOL Options → Validate Configured Toolchains。只检查显式配置且非空的路径，绿色勾表示可执行文件可运行且版本被识别。
在 Output 核对实际器件、顶层、目录和命令，再执行快速仿真或工程创建构建。

如需 AI 读取或配置当前工程，先按安装 dide-mcp 接入客户端，并参考 AI Agent 与 dide-mcp 工具详解查看全部工具用法。

工程界面导览 · 工程创建构建 · 模块网表查看