vivado-tcl

name	vivado-tcl
description	当用户想要生成、编写或执行 Vivado/Vitis TCL 脚本用于 FPGA 设计流程时使用此技能。包括创建项目、运行综合/实现、编程设备、使用 IP Integrator 块设计、插入调试核、管理约束、仿真以及任何 Vivado 自动化任务。当用户提及 Vivado、Vitis、FPGA、硬件设计的 TCL 脚本、比特流生成、XDC 约束、ILA/VIO 调试或任何 Xilinx/AMD FPGA 工具链任务时触发。此技能生成并执行 TCL——它不分析 Vivado 输出或报告。对于调试策略和调试核配置决策使用 vivado-debug，对于时序分析使用 vivado-analysis。

Vivado TCL 脚本生成指南

概述

此技能生成 Vivado TCL 脚本并通过 vivado -mode batch 执行。它涵盖完整的 FPGA 设计流程：项目创建、综合、实现、比特流生成、硬件编程、IP 集成、调试和仿真。完整命令参考请参阅 REFERENCE.md。

关键规则

1. 禁止混合使用工程模式和非工程模式命令——它们是不兼容的流程
2. 工程模式：使用 create_project、add_files、launch_runs、wait_on_run、open_run
3. 非工程模式：使用 read_verilog、synth_design、opt_design、place_design、route_design
4. 如果上下文不明显，始终询问用户想要哪种模式
5. 此技能仅生成/执行 TCL——不要尝试解析或分析 Vivado 报告或日志

执行模型

如何运行 TCL 脚本

# 批处理模式（推荐用于自动化）
vivado -mode batch -source <script.tcl>

# 带参数
vivado -mode batch -source script.tcl -tclargs "ARG1=value1"

# 交互式 TCL shell
vivado -mode tcl

关键输出文件

• vivado.log — 完整会话日志
• vivado.jou — TCL 命令日志（可重用为脚本）
• *.dcp — 设计检查点（设计状态的快照）
• *.bit — 比特流文件
• *.xsa — Vitis 硬件平台
• *.ltx — 调试探针文件

快速参考：工程模式流程

# 1. 创建项目
create_project <name> <dir> -part <part>

# 2. 添加源文件
add_files {./src/top.v ./src/sub.v}
add_files -fileset constrs_1 ./constraints/timing.xdc
update_compile_order -fileset sources_1

# 3. 综合
launch_runs synth_1
wait_on_run synth_1

# 4. 打开综合结果并生成报告
open_run synth_1 -name netlist_1
report_timing_summary -file syn_timing.rpt
report_power -file syn_power.rpt

# 5. 实现 + 比特流
launch_runs impl_1 -to_step write_bitstream
wait_on_run impl_1

# 6. 报告
open_run impl_1
report_timing_summary -file imp_timing.rpt
report_utilization -file imp_util.rpt
report_power -file imp_power.rpt

快速参考：非工程模式流程

# 0. 设置
set outputDir ./output
file mkdir $outputDir

# 1. 读取源文件
read_verilog {./src/top.v ./src/sub.v}
read_xdc ./constraints/timing.xdc

# 2. 综合
synth_design -top <top_module> -part <part>
write_checkpoint -force $outputDir/post_synth.dcp
report_timing_summary -file $outputDir/post_synth_timing.rpt

# 3. 实现
opt_design
place_design
# 可选：phys_opt_design
route_design
write_checkpoint -force $outputDir/post_route.dcp

# 4. 报告
report_timing_summary -file $outputDir/post_route_timing.rpt
report_utilization -file $outputDir/post_route_util.rpt
report_power -file $outputDir/post_route_power.rpt
report_drc -file $outputDir/post_route_drc.rpt

# 5. 生成比特流
write_bitstream -force $outputDir/top.bit

IP Integrator（块设计）

# 创建块设计
create_bd_design "system"

# 添加 IP 核
create_bd_cell -type ip -vlnv xilinx.com:ip:<ip_name>:<version> <instance>

# 运行自动化（AXI 连接、外部端口）
apply_bd_automation -rule xilinx.com:bd_rule:processing_system7 \
    -config {make_external "FIXED_IO, DDR"} [get_bd_cells ps7_0]
apply_bd_automation -rule xilinx.com:bd_rule:axi4 \
    -config {Master "/ps7_0/M_AXI_GP0"} [get_bd_intf_pins peripheral/S_AXI]

# 验证、保存、生成包装器
assign_bd_address
validate_bd_design
save_bd_design
make_wrapper -files [get_files system.bd] -top

# 导出到 Vitis
write_hw_platform -fixed -include_bit -force ./system_wrapper.xsa

硬件编程

open_hw_manager
connect_hw_server -url localhost:3121
open_hw_target

current_hw_device [get_hw_devices <device>]
set_property PROGRAM.FILE {<bitstream>.bit} [current_hw_device]
set_property PROBES.FILE {<probes>.ltx} [current_hw_device]
program_hw_devices [current_hw_device]

close_hw_target
disconnect_hw_server
close_hw_manager

调试核插入（ILA）

# 综合后，实现前
open_run synth_1

# 创建 ILA
create_debug_core u_ila_0 ila
set_property C_DATA_DEPTH 1024 [get_debug_cores u_ila_0]

# 连接时钟
set_property port_width 1 [get_debug_ports u_ila_0/clk]
connect_debug_port u_ila_0/clk [get_nets clk]

# 添加探针
set_property port_width <width> [get_debug_ports u_ila_0/probe0]
connect_debug_port u_ila_0/probe0 [get_nets {<signal_list>}]

# 实现并写入探针
implement_debug_core
write_debug_probes -force ./output/top.ltx

TCL 语法技巧

对象查询

get_cells -hierarchical -filter "lib_cell =~ FD*"
get_pins -of [get_cells inst_1]
get_nets -of [get_pins inst_1/D]
get_property loc [get_cells inst_1]
set_property loc SLICE_X1Y27 [get_cells inst_1]

总线索引

add_wave {bus[4]}       ;# 大括号用于方括号
add_wave bus(4)         ;# 圆括号也可以工作

错误处理

if {[catch {<command>} result]} {
    puts "Error: $result"
}

工作流程指南

1. 始终先将 TCL 写入 .tcl 文件，然后使用 vivado -mode batch -source 执行
2. 为输出目录包含 file mkdir 以避免错误
3. 在非工程模式的关键阶段使用 write_checkpoint 以便恢复
4. 在综合后和布线后添加 report_timing_summary ——时序收敛至关重要
5. 在写命令上使用 -force 以允许重新运行而无需手动清理
6. 对于 IP Integrator 流程，始终在继续之前执行 validate_bd_design
7. 编程硬件时，始终在编程前检查设备连接

常见器件型号（示例）

系列	器件示例
Kintex-7	xc7k70tfbg484-2
Zynq-7000	xc7z020clg484-1
Artix-7	xc7a35tcpg236-1
Kintex UltraScale+	xcku5p-ffvb676-2-e
Zynq UltraScale+	xczu9eg-ffvb1156-2-e
Versal	xcvm1802-vsva2197-2MP-e-S