创建工程配置

使用 File → Open Folder 打开工程根目录，选择 TOOL Options → Create Project Configuration 或 Generate property.json，输入工程名并选择工具链。配置生成到 .vscode/property.json；已有文件时直接修改对应字段，普通生成命令不会覆盖它。

property.json 保存可共享的工程信息，包括器件、顶层、源码目录、库和软件应用；本机工具安装路径建议放在用户或远程设置中，需要工程覆盖时使用 .vscode/settings.json，详见 工具链路径配置。Remote SSH 下使用远程主机的路径。

文件支持 JSONC 注释和尾随逗号，字段名区分大小写，不允许重复键。当前 Schema 要求 toolChain、soc、device；生成器还会写入 prjName.PL。生成时的 device: "none" 只是占位，执行厂商构建前必须换成实际器件。运行时默认值不会自动写回文件。

常用配置示例

下面展示纯 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 名称独立，重命名工程不会同步重命名模块。

工具链、名称与顶层

字段	类型与取值	含义及实际作用
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 安装路径。

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

文件列表元数据 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"]
  }
}

此片段不会把前面的 Artix-7 示例自动变成 Zynq 工程；器件与 .hdf / .xsa 必须来自实际设计。首个应用使用软件工作区名，后续应用按模板生成名称。见 SDK 构建与处理器调试。

持久化烧写 flash

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

字段	类型 / 默认行为	含义及实际作用
flash	字符串或对象，可省略	字符串为 get_cfgmem_parts 返回的完整型号；对象可以指定额外选项。描述板上的配置 Flash，区别于 FPGA 的 device。
flash.part	非空字符串，对象形式必填	Vivado 配置存储器型号，如 w25q128fv-spi-x1_x2_x4，必须匹配实际芯片与工具支持的型号。
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
  }
}

以上仅为字段示例，不代表你的板卡型号。省略接口与容量覆盖时，由烧写流程结合配置存储器型号处理。

Efinity 扩展字段

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

字段	类型 / 默认行为	含义及实际作用
efinity	对象，可省略	Efinity 专用参数容器。
efinity.top	字符串，可省略	顶层优先级：efinity.top → srcTop → 旧字段 top → prjName.PL。通常只设置 srcTop，避免两处顶层冲突。
efinity.family	字符串，可省略	器件系列，省略时从 device 推断；显式值必须匹配器件和工具。
efinity.timingModel	字符串，可省略	时序模型/速度等级，优先于从 device 拆出的等级，仍未指定时回退为 C4。必须按实际器件选择。

旧字段与兼容写法

字段	当前处理方式
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 的全部字段，并补充后端实际读取的扩展和兼容字段。

确认工程可用

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

如需 AI 读取或配置当前工程，先按 安装 dide-mcp 接入客户端；该页提供无需填写、直接复制即可使用的安装提示词。

工程管理操作 · 器件逐级补全 · 文件列表