极客工场

Appearance

共 4,045 字预计阅读约 13 分钟

Vivado part not installed 报错：Coretcl 2-106 指定器件找不到的排查与修复 ​

更新时间：2026-11-13。报错排查篇，属于 FPGA 入门排错簇。create_project -part 指定一个本机器件库里不存在的 part 时，Vivado 会先吐一条 WARNING: [Device 21-436] No parts matched，紧接着抛 ERROR: [Coretcl 2-106] Specified part could not be found.，工程建不起来。这组报错与 RTL 代码无关，问题出在「脚本里写的 part」和「这台机器装了哪些器件支持」对不上。Vivado 建工程的标准流程见 Vivado 工程上手，器件家族与工具世代的背景见 厂商与器件家族。

首屏答案：先用 get_parts -quiet <part> 探一下本机器件库，再用 llength 把返回值变成 0 或 1 的读数；在本文的 Vivado 2017.4 实测里，空查询仍会打印 Device 21-436 警告，所以 -quiet 不能当成“压掉警告”的开关。随后用同家族模式查询（如 get_parts xc7a*）区分两种性质：同家族其它 part 查得到、唯独这一颗查不到，是 part 字符串或速度等级写错；整个家族前缀都查不到，是器件包没装或工具世代不支持（例如 Spartan-6 只能用 ISE，Vivado 不支持这一世代）。修复只有两条正路：在安装器里加装对应家族的器件支持，或者把 -part 改成本机已安装的器件。本文在 Windows 上的 Vivado 2017.4 batch mode 实测：指定未安装的 xc6slx9-tqg144-2 时 get_parts 匹配数为 0、建工程被 Coretcl 2-106 终止；改用本机已安装的 xc7a35tcpg236-1 后匹配数为 1、工程一次创建成功。

本文要回答的问题 ​

  • WARNING: [Device 21-436] No parts matched 和 ERROR: [Coretcl 2-106] Specified part could not be found. 各自在说什么，为什么总是前后脚出现？
  • get_parts 返回 0 之后，怎么进一步判断是 part 名拼写错了，还是整个器件包压根没装？
  • part 名称 xc7a35tcpg236-1 这一串每一段代表什么，速度等级写错会不会也报这个错？
  • 为什么 xc6slx9 这种器件无法通过在 Vivado 里加装器件包解决，只能回到 ISE 工具链？
  • 网传的 current_part 命令为什么在 Vivado 2017.4 里直接报 invalid command，正确的当前工程器件查询写法是什么？

排查的整体分诊路径如下，从一句报错逐层收窄到具体根因：

part 找不到的分诊漏斗：从建工程失败收窄到器件库不匹配

读这张漏斗抓住一个要点：前两层只回答「本机有没有这颗料」，第三层的同家族查询才是分水岭——它决定了你要去翻数据手册改字符串，还是去启动安装器补器件包，甚至换工具世代。

一、报错原文与现象 ​

复现脚本不读任何 RTL，只做两件事：先 get_parts -quiet xc6slx9-tqg144-2 看本机库有没有这颗料，再用 catch 包住 create_project ... -part xc6slx9-tqg144-2 尝试建工程，把失败信息完整打出来。Windows 主机上 PowerShell 驱动 Vivado 2017.4 batch mode 的真实输出如下：

指定未安装的 xc6slx9-tqg144-2：查询 0 匹配，建工程被 Coretcl 2-106 终止

读这段输出抓四个关键点。第一，GET_PARTS_MATCH 0 是脚本自己打的探针读数：llength [get_parts -quiet ...] 返回 0，说明本机器件库里没有任何与该字符串匹配的 part。第二，紧随其后的 WARNING: [Device 21-436] No parts matched 'xc6slx9-tqg144-2' 是 Vivado 对同一次空查询的官方警告，注意它只是 WARNING，本身不中断流程。第三，create_project 被 catch 接住后打印 MISSING_PART_RESULT FAILED，错误正文是 ERROR: [Coretcl 2-106] Specified part could not be found.——这才是硬失败，工程没有建成。第四，因为错误被 catch 兜住，脚本走完了自己的分支并正常 exit，批处理进程没有异常中断；如果去掉 catch 裸跑 create_project，Tcl 会在这一行直接报错停住，后面的命令全部不执行，batch 脚本的退出码也会变成非零，退出码语义见 Vivado 批处理退出码非零速查。

还有一个容易误读的细节：两条信息指向的是同一次失败的两个阶段，不是两个独立毛病。21-436 是「查询阶段没查到」的提醒，2-106 是「拿着空结果去建工程」的硬失败，修一个根因两条一起消失。

二、两条报错的分工：一个管查询，一个管建工程 ​

把两条信息按触发命令、级别和语义拆开，差异就清楚了：

对比维度Device 21-436Coretcl 2-106
完整文本No parts matched '<part>'Specified part could not be found.
级别WARNING，不中断脚本ERROR，建工程动作失败
触发命令get_parts 这类器件查询create_project -part（或 set_part）
语义本机器件库中无匹配项指定 part 无法作为工程器件使用
排查角色探针读数，告诉你库的状态失败定论，工程无法继续
单独出现时可以只警告不失败（查询本来就允许为空）通常可追溯到一次无匹配的 part 解析或查询

理解这张表的关键是不要把 -quiet 理解成“静默开关”。本文坏例脚本执行的是 llength [get_parts -quiet xc6slx9-tqg144-2]，真实日志仍紧接着输出 WARNING: [Device 21-436]；它在 Vivado 2017.4 这次实测中的价值，是让脚本拿到可计数的空返回，再用 llength 把「有没有」变成 0 或 1 的数字读数。换版本或换命令时，应以本机 help get_parts 和实测输出为准。而 create_project -part 必须拿到一个真实存在的 part 对象才能建工程，拿不到就会触发 2-106。所以排查时不要被 ERROR 吓到去翻工程目录，先用查询命令把库的状态问清楚。

顺带区分一个同族「not found」报错：[Vivado 12-163] Module not found 针对的是 RTL 模块或文件找不到，发生在综合期，和器件库完全是两个子系统。Vivado part not installed 报错发生在建工程阶段、工程还没有任何源码的时候，两者从时间点上就能分开，模块类报错的排查见 Vivado 模块找不到报错怎么排查。

三、part 名称怎么读：六段结构与三类「找不到」 ​

要判断字符串对不对，先得会读 part 名。以修复时改用的 xc7a35tcpg236-1 为例：

字段段取值含义
前缀xcXilinx 商用器件统一前缀
代次77 系列；6s 表示 Spartan-6，vc 表示 Versal
家族aArtix-7；同族还有 k（Kintex）、v（Virtex）、z（Zynq）
容量35t约 35k 逻辑单元量级，t 为标准型后缀
封装与引脚cpg236CSP BGA 封装、236 个引脚；tqg144 即 TQFP、144 脚
速度等级-1-1 为最慢、成本最低档；另有 -2、-3，-2L 为低电压低功耗档

每一段都必须和数据手册、板卡丝印对上；只要组合出的完整 part 不存在于本机器件库，整体查询就是 0。实测中用三个「问题 part」做探针，覆盖三类性质不同的根因，三者 get_parts 读数都是 0，但出路完全不同：

探针 part本机查询结果根因性质正确出路
xc6slx9-tqg144-2MATCH 0，2074 条已装清单中无任何 Spartan-6工具世代不支持：Spartan-6 属 ISE 世代，Vivado 从未收录改装 ISE，Vivado 加包无解
xcvc1902-vsva2197-2MP-SMATCH 0新家族缺失：Versal 需要新版 Vivado 并加装 Versal 器件支持升级工具版本并在安装器中勾选 Versal
xc7a999tcsg324-1MATCH 0，但同家族 xc7a* 能查到大量真实器件字符串错误：7 系列命名格式合法，但 999 这个容量编号不存在对照数据手册改成真实编号（如 xc7a35t、xc7a100t）
xc7a35tcpg236-1MATCH 1本机已安装，建工程成功本篇修复采用

这张表就是「拼写错」和「器件包未安装」不能混为一谈的原因：同样是 MATCH 0，第三行的 Artix-7 家族在本机活得好好的，错的是单个编号；前两行则是整个家族在本机库中缺席，再怎么改封装后缀和速度等级都不会有结果。判断动作用一条模式查询即可完成：

tcl
# 精确探针：这一颗在不在
llength [get_parts -quiet xc7a999tcsg324-1]
# 家族探针：这个家族在不在（支持通配模式）
llength [get_parts -quiet xc7a*]

第一条返回 0、第二条返回一个很大的数字，就是「单颗写错」；两条都返回 0，才是「家族没装或世代不对」。速度等级写错（比如把 -1 写成不存在的 -9）归在第一类：家族和封装都在，仅末段非法，改对末段即可。

四、定位流程与一个真实的命令坑 ​

把完整排查路径画成决策图，颜色按角色区分：红是报错与根因，蓝是排查动作，橙是修复动作，绿是通过态，紫是防复发沉淀。

fpga/beginner/ts-vivado-part-not-installed.md D2 示意图

读这张图抓住主干「精确探针 → 家族探针 → 分流修复」。大多数人一看到 2-106 就去重装 Vivado，实际上先走两个查询命令，十秒钟就能判断该不该动安装器：返回 1 的绿色分支说明器件没问题，要查的是工程目录残留或脚本里别处的参数；只有走到红色家族缺席分支，启动安装器才有意义。

这里记录一个真实的命令坑。排查中曾按网上资料在 Tcl 里写 current_part 想查询当前工程器件，Vivado 2017.4 直接回 invalid command name "current_part"，脚本在该行中断——这个版本根本没有这条命令。正确写法是查工程对象的 PART 属性：

tcl
# 错误写法：Vivado 2017.4 无此命令，报 invalid command name "current_part"
current_part

# 正确写法：从当前工程对象读 PART 属性
get_property PART [current_project]

修复轮脚本用的就是正确写法，建工程成功后回读出 xc7a35tcpg236-1，证明工程实际绑定的器件与 -part 参数一致。换机器或换版本时，这类版本差异要以本机 help 输出和实测为准，不要把新版本文档里的命令想当然套到旧版本上。

五、修复与对照：改用已安装 part 后一次建成功 ​

本机这份 Vivado 2017.4 安装时勾选了 Artix-7 等免费器件支持，导出的全量清单共 2074 个 part，其中精确包含 xc7a35tcpg236-1，而任何 xc6slx9 条目都是零条。既然复现目的是验证「part 在库即可建工程」，修复轮把 -part 换成 xc7a35tcpg236-1，其余流程不变：

改用已安装的 xc7a35tcpg236-1：查询 1 匹配，工程创建并回读 PART 属性成功

对照两轮输出有三处硬差异。其一，探针读数从 GET_PARTS_MATCH 0 翻成 GET_PARTS_MATCH 1，这是修复成立的前提——器件库里确实存在这颗料。其二，21-436 警告整条消失，因为查询不再为空。其三，create_project 走成功分支，打印 INSTALLED_PART_CREATED xc7a35tcpg236-1，这行字由 get_property PART [current_project] 回读产生，既证明工程建成，也证明绑定的器件就是参数指定的那颗。

如果场景不允许换 part——比如板卡上焊死的就是某颗特定器件——那就要走另一条修复路：打开 Xilinx Unified Installer，在 Vivado 的器件支持勾选页里把对应家族（Spartan-6 除外，它只能回 ISE）勾上安装。注意两件事：一是 WebPACK 免费授权只覆盖部分中小容量器件，大容量 Kintex/Virtex 或 Versal 即便装了包也会卡在授权检查，授权类报错的处置见 Vivado license checkout failed 排查；二是安装器本身要能启动、安装路径要可写，工具链安装与环境问题见 FPGA 开发板与工具链怎么选。

判断「真修好」的标志也记一下：get_parts 匹配数为 1、建工程无 2-106、get_property PART 回读值与参数一致，三者同时满足才算闭环；只看脚本没报错不够，被 catch 兜住的失败同样会让进程安静退出。

六、预防与排查清单 ​

  • 新机器先留一份器件清单：装好 Vivado 后跑一次 get_parts 把结果存档，写脚本前先 grep 清单，比建工程失败后回头查快得多。
  • part 字符串只认两个权威来源：板卡原理图/丝印上的完整型号，或厂商数据手册首页的订货型号；不从教程配图里手抄，手写最容易把封装段和速度等级抄串。
  • 看到 MATCH 0 先做家族探针再决定动作：同家族有货就改字符串，整个家族缺席才动安装器，Spartan-6 这类老器件直接换 ISE 思路。
  • 脚本用 catch + 探针读数代替裸奔：把 get_parts 匹配数打在日志里，CI 或批处理日志一眼可读；批处理整体排错见 Vivado 命令返回非零速查。
  • 命令名先在本机验证：current_part 这类在新版本资料里出现、旧版本不存在的命令，先 help 查一下再写进脚本，避免排查中引入新的报错。
  • 环境类报错先于工程类排查：vivado 命令本身找不到时，part 探针无从谈起，PATH 问题见 Vivado 命令不在 PATH 排查。

实验环境 ​

  • 机器/系统：Windows 主机 / PowerShell 批处理驱动，无 GUI 的 batch mode
  • 工具版本：Vivado 2017.4（SW Build 2086221），已安装 Artix-7 等 WebPACK 免费器件，全量清单 2074 个 part
  • 日期：2026-11-13
  • 完整命令：powershell -ExecutionPolicy Bypass -File run-vivado.ps1 -Tcl v13_err.tcl -Log err-part-missing.log（指定未安装的 xc6slx9-tqg144-2，复现 Device 21-436 + Coretcl 2-106）；powershell -ExecutionPolicy Bypass -File run-vivado.ps1 -Tcl v13_fix.tcl -Log fix-part-installed.log（改用 xc7a35tcpg236-1 验证修复）；另跑 list_parts.tcl 导出本机全部已安装 part 清单

代码获取 ​

复现用 Tcl 探针脚本、PowerShell 驱动脚本与原始日志在公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/vivado-part-not-installed。原始作业文件名为 v13_err.tcl、v13_fix.tcl，公开包按语义提供同名薄封装，实际内容分别转入 part_missing.tcl 与 part_installed.tcl；按目录内 README 在装有 Vivado 2017.4 的 Windows 机器上运行，即可重现「查询 0 匹配、建工程触发 Coretcl 2-106 → 换已安装 part 后查询 1 匹配、工程创建成功」的完整对照。list_parts.tcl 可导出本机器件清单用于核对，part_probe.tcl 用于复跑三类无匹配探针。

这一篇在知识体系里的位置 ​

本篇是 FPGA 入门排错簇中 Vivado 建工程阶段的一员，管的是「工程还没碰 RTL 就建不起来」的失败形态。建工程与完整设计流程的正常路径看 Vivado 工程上手 与 第一个 FPGA 工程；选器件时理解家族与工具世代的关系看 厂商与器件家族。同属 Vivado 报错簇的邻近篇目：源码层面的「找不到」看 Vivado 模块找不到报错怎么排查——Vivado part not installed 报错与它的分界线是「有无工程、报错 ID 是 Coretcl 还是综合器」；授权挡住器件看 license checkout failed 排查；命令环境问题看 Vivado 命令不在 PATH；脚本失败后的退出码语义看 批处理退出码非零速查。

总结 ​

Device 21-436 与 Coretcl 2-106 是同一次失败的两个阶段：前者是 get_parts 查询本机器件库无匹配的警告，后者是拿着不存在的 part 去 create_project 的硬失败；排查先用精确探针确认 MATCH 0，再用同家族模式查询把根因分成三类——家族世代不支持（Spartan-6 只能回 ISE）、器件包未安装（运行安装器补家族）、part 字符串或速度等级写错（对照数据手册改名）；修复要么加装器件支持，要么改用本机已安装器件，本篇改用 xc7a35tcpg236-1 后匹配数变 1、工程一次建成并由 get_property PART [current_project] 回读验证；切记 Vivado 2017.4 没有 current_part 命令，查当前工程器件只认 get_property PART [current_project]。