Modelsim TCL 常用命令大全你需要掌握Modelsim中高频使用的TCL命令这些命令是实现仿真自动化、工程管理、仿真控制和调试的核心下面按使用场景分类梳理附带说明和实用示例方便直接套用。TL;DR 速查表下面是最常用的 10 个 TCL 命令速查每行给出命令、一句话功能说明和最小可用示例方便快速上手命令功能说明最小可用示例vlib创建新的仿真库vlib workvmap将仿真库映射到指定别名vmap work workvcom编译 VHDL 文件vcom -93 -work work ./src/top.vhdvlog编译 Verilog/SystemVerilog 文件vlog -sv -work work ./src/top.svvsim加载顶层模块启动仿真器vsim -voptargsacc -t 1ps work.topforce给指定信号强制赋值设置激励force /top/clk 0 0ns 1 5ns -repeat 10nsrun运行指定时长的仿真run 1usadd wave将指定信号添加到波形窗口add wave /top/*radix设置信号的显示进制radix hex /top/doutsource执行指定的 TCL 脚本文件source ./run_sim.tcl一、 工程与库管理命令基础必备这类命令用于创建、编译、管理Modelsim的仿真库和设计文件是仿真前的准备工作。1. 仿真库创建与映射vlib lib_name创建新的仿真库用于存放编译后的设计文件示例vlib work创建默认工作库work最常用vmap lib_alias lib_path将仿真库映射到指定别名关联库名与实际路径示例vmap work work将work库映射到当前路径的work文件夹默认配置vdel删除仿真库或库中的编译文件示例1vdel -all删除当前work库中所有编译文件重新编译前常用示例2vdel -lib work *效果同上精准删除work库内所有内容2. 设计文件编译vcom options vhdl_file编译VHDL文件支持.vhd/.vhdl后缀常用选项-93/-2008指定VHDL标准版本-work lib_name指定编译后存放的库默认work示例vcom -93 -work work ./src/top.vhd以VHDL93标准编译top.vhd到work库vlog options verilog_file编译Verilog/SystemVerilog文件支持.v/.sv后缀常用选项-sv指定编译SystemVerilog文件-work lib_name指定目标库-f file_list批量编译文件通过文件列表指定待编译文件示例1vlog -sv -work work ./src/top.sv编译SystemVerilog文件到work库示例2vlog -f file_list.txt批量编译file_list.txt中列出的所有Verilog文件二、 仿真环境配置与启动命令这类命令用于加载设计、配置仿真参数并启动仿真器是进入仿真环节的关键。1. 启动仿真器核心命令vsim options top_module加载顶层设计模块启动Modelsim仿真器常用核心选项高频使用-voptargsacc保留所有信号的调试可见性极其重要避免仿真后无法查看内部模块信号-t time_unit设置仿真时间精度如1ps、1ns、10ns-lib lib_name指定顶层模块所在的库默认work-do tcl_script启动仿真后自动执行指定的TCL脚本自动化仿真常用示例vsim -voptargsacc -t 1ps work.top加载work库中的top模块保留调试信息时间精度1ps2. 仿真信号赋值与参数配置set var_name value定义仿真变量或设置Modelsim环境参数示例1set sim_time 1000ns定义仿真时长变量示例2set TopLevelModule top定义顶层模块名变量方便脚本复用force signal_path value time1 value2 time2 ...给指定信号强制赋值用于设置激励、初始状态常用格式单次赋值force /top/rst_n 0 0ns; force /top/rst_n 1 100nsrst_n信号0ns为低100ns后拉高周期性赋值force /top/clk 0 0ns 1 5ns -repeat 10nsclk信号周期10ns高低电平各5ns三、 仿真运行控制命令这类命令用于控制仿真的运行、暂停、重启等是调试过程中高频操作的命令。run time运行指定时长的仿真核心运行命令示例1run 1us运行1微秒仿真示例2run $sim_time运行之前定义的sim_time时长示例3run -all运行仿真直到自然结束无后续激励或遇到stop/stop/stop/finishstop暂停当前仿真保留当前仿真状态可后续继续runrestart重启仿真恢复到vsim启动后的初始状态可加选项-f强制重启quit退出Modelsim仿真器可加选项-sim仅退出仿真不关闭Modelsim软件-force强制退出step单步仿真按仿真事件逐步运行调试精细逻辑时使用类似软件调试的“单步执行”四、 波形窗口与调试命令这类命令用于管理波形窗口、查看信号状态是仿真调试的核心工具。1. 波形窗口操作add wave signal_path将指定信号添加到波形窗口调试必备示例1add wave /top/*添加top模块下所有顶层信号到波形窗口示例2add wave /top/inst_module/*添加top模块下inst_module子模块的所有信号示例3add wave -noupdate /top/clk /top/rst_n /top/din /top/dout批量添加指定信号-noupdate避免实时刷新提升效率configure wave配置波形窗口显示属性如信号进制、显示格式示例configure wave -signalnamewidth 1 -timelineunits ns设置信号名宽度1时间轴单位为nsradix format signal_path设置信号的显示进制波形窗口/信号窗口通用常用格式binary二进制、hex十六进制最常用、decimal十进制、unsigned无符号十进制示例radix hex /top/dout将dout信号设置为十六进制显示view wave打开波形窗口若未自动打开时使用同理可打开其他窗口view signals信号窗口、view source代码窗口2. 信号查询与监视examine signal_path简写ex查看当前仿真时刻指定信号的取值示例ex /top/dout查看dout信号当前值示例ex -radix hex /top/dout以十六进制查看dout值watch signal_path监视指定信号当信号值发生变化时自动暂停仿真调试信号跳变问题常用示例watch /top/error_flag当error_flag信号值变化时仿真自动暂停五、 文件操作与自动化脚本命令这类命令用于实现仿真流程的自动化通过编写TCL脚本批量执行操作提升仿真效率。cd path切换当前工作目录示例cd ./sim切换到当前路径下的sim文件夹pwd查看当前工作目录确认路径是否正确ls列出当前目录下的文件和文件夹open file_path mode打开文件用于读写仿真日志、激励文件等示例set fp [open sim_log.txt w]以写入模式打开sim_log.txt返回文件句柄fpputs target content输出内容到控制台或文件示例1puts 仿真开始执行...在Modelsim控制台输出信息示例2puts $fp 仿真时长1us将信息写入到fp对应的sim_log.txt文件close file_handle关闭已打开的文件示例close $fp关闭文件句柄fp对应的文件source tcl_script执行指定的TCL脚本文件批量执行命令、自动化仿真核心示例source ./run_sim.tcl执行当前目录下的run_sim.tcl自动化仿真脚本六、 常用辅助命令help command查看指定命令的详细用法不懂命令时的查询工具示例help vsim查看vsim命令的所有选项和说明echo content在控制台输出内容与puts功能类似更简洁示例echo 编译完成准备启动仿真...if {condition} {commands} else {commands}TCL条件判断自动化脚本中用于分支逻辑示例if {[file exists work]} {vdel -all} else {vlib work}判断work库是否存在存在则删除不存在则创建foreach var list {commands}TCL循环命令批量处理文件、信号等示例foreach file [list a.v b.v c.v] {vlog $file}批量编译列表中的3个Verilog文件命令索引表下表按字母顺序汇总全文涉及的全部 TCL 命令包含所属分类、功能简述与示例命令方便快速查找定位。命令所属分类功能简述示例命令add wave波形窗口与调试将指定信号添加到波形窗口add wave /top/*cd文件操作与自动化切换当前工作目录cd ./simclose文件操作与自动化关闭已打开的文件close $fpconfigure wave波形窗口与调试配置波形窗口显示属性configure wave -signalnamewidth 1 -timelineunits nsecho常用辅助在控制台输出内容更简洁echo 编译完成examine波形窗口与调试查看当前仿真时刻指定信号的取值ex /top/doutforce仿真环境配置与启动给指定信号强制赋值设置激励force /top/clk 0 0ns 1 5ns -repeat 10nsforeach常用辅助TCL 循环命令批量处理foreach file [list a.v b.v] {vlog $file}help常用辅助查看指定命令的详细用法help vsimif常用辅助TCL 条件判断分支逻辑if {[file exists work]} {vdel -all} else {vlib work}ls文件操作与自动化列出当前目录下的文件和文件夹lsopen文件操作与自动化打开文件读写日志、激励文件set fp [open sim_log.txt w]puts文件操作与自动化输出内容到控制台或文件puts $fp 仿真时长1uspwd文件操作与自动化查看当前工作目录pwdquit仿真运行控制退出 Modelsim 仿真器quit -simradix波形窗口与调试设置信号的显示进制radix hex /top/doutrestart仿真运行控制重启仿真恢复到初始状态restart -frun仿真运行控制运行指定时长的仿真run 1usset仿真环境配置与启动定义仿真变量或设置环境参数set sim_time 1000nssource文件操作与自动化执行指定的 TCL 脚本文件source ./run_sim.tclstep仿真运行控制单步仿真按事件逐步运行stepstop仿真运行控制暂停当前仿真stopvcom工程与库管理编译 VHDL 文件vcom -93 -work work ./src/top.vhdvdel工程与库管理删除仿真库或库中的编译文件vdel -allview波形窗口与调试打开指定窗口波形/信号/代码view wavevlib工程与库管理创建新的仿真库vlib workvlog工程与库管理编译 Verilog/SystemVerilog 文件vlog -sv -work work ./src/top.svvmap工程与库管理将仿真库映射到指定别名vmap work workvsim仿真环境配置与启动加载顶层模块启动仿真器vsim -voptargsacc -t 1ps work.topwatch波形窗口与调试监视信号变化并自动暂停仿真watch /top/error_flag总结Modelsim TCL常用命令可归纳为5大核心场景方便快速记忆和调用库与文件管理vlib、vmap、vcom、vlog、vdel仿真启动与配置vsim、set、force仿真运行控制run、stop、restart、quit调试与波形操作add wave、radix、examine、watch自动化脚本source、open、puts、if、foreach通过组合这些命令编写TCL脚本可实现从编译、仿真到波形保存、日志输出的全流程自动化大幅提升FPGA/IC仿真效率。命令速查对比表对比命令适用场景典型用法示例vcomvsvlogvcom编译 VHDL 文件vlog编译 Verilog/SystemVerilog 文件vcom -93 -work work ./src/top.vhdvlog -sv -work work ./src/top.svrunvssteprun按指定时长连续运行仿真step按仿真事件单步执行适合精细调试run 1usstepexaminevswatchexamine主动查询信号当前值watch监视信号变化并自动暂停仿真ex /top/doutwatch /top/error_flag命令索引表下表按字母顺序汇总全文涉及的全部 TCL 命令包含所属分类、功能简述与示例命令方便快速查找定位。命令所属分类功能简述示例命令add wave波形窗口与调试将指定信号添加到波形窗口add wave /top/*cd文件操作与自动化切换当前工作目录cd ./simclose文件操作与自动化关闭已打开的文件close $fpconfigure wave波形窗口与调试配置波形窗口显示属性configure wave -signalnamewidth 1 -timelineunits nsecho常用辅助在控制台输出内容更简洁echo 编译完成examine波形窗口与调试查看当前仿真时刻指定信号的取值ex /top/doutforce仿真环境配置与启动给指定信号强制赋值设置激励force /top/clk 0 0ns 1 5ns -repeat 10nsforeach常用辅助TCL 循环命令批量处理foreach file [list a.v b.v] {vlog $file}help常用辅助查看指定命令的详细用法help vsimif常用辅助TCL 条件判断分支逻辑if {[file exists work]} {vdel -all} else {vlib work}ls文件操作与自动化列出当前目录下的文件和文件夹lsopen文件操作与自动化打开文件读写日志、激励文件set fp [open sim_log.txt w]puts文件操作与自动化输出内容到控制台或文件puts $fp 仿真时长1uspwd文件操作与自动化查看当前工作目录pwdquit仿真运行控制退出 Modelsim 仿真器quit -simradix波形窗口与调试设置信号的显示进制radix hex /top/doutrestart仿真运行控制重启仿真恢复到初始状态restart -frun仿真运行控制运行指定时长的仿真run 1usset仿真环境配置与启动定义仿真变量或设置环境参数set sim_time 1000nssource文件操作与自动化执行指定的 TCL 脚本文件source ./run_sim.tclstep仿真运行控制单步仿真按事件逐步运行stepstop仿真运行控制暂停当前仿真stopvcom工程与库管理编译 VHDL 文件vcom -93 -work work ./src/top.vhdvdel工程与库管理删除仿真库或库中的编译文件vdel -allview波形窗口与调试打开指定窗口波形/信号/代码view wavevlib工程与库管理创建新的仿真库vlib workvlog工程与库管理编译 Verilog/SystemVerilog 文件vlog -sv -work work ./src/top.svvmap工程与库管理将仿真库映射到指定别名vmap work workvsim仿真环境配置与启动加载顶层模块启动仿真器vsim -voptargsacc -t 1ps work.topwatch波形窗口与调试监视信号变化并自动暂停仿真watch /top/error_flag|putsvsecho|puts可输出到控制台或文件更灵活echo仅输出到控制台更简洁 |puts $fp 仿真时长1usecho 编译完成|自动化仿真脚本实战示例下面是一个完整的自动化仿真 TCL 脚本覆盖从创建库、编译文件、启动仿真、添加波形、运行仿真到保存波形、退出仿真的全流程可直接保存为run_sim.tcl并通过source ./run_sim.tcl执行# # 自动化仿真脚本 run_sim.tcl # 功能完成从建库、编译到仿真、保存波形的全流程 # # 1. 创建仿真库若已存在则先删除重建保证干净环境 if {[file exists work]} { vdel -all } else { vlib work } # 2. 编译设计文件VHDL 与 Verilog 混合工程示例 vcom -93 -work work ./src/top.vhd ;# 编译 VHDL 顶层模块 vlog -sv -work work ./src/tb_top.sv ;# 编译 SystemVerilog 测试平台 # 3. 启动仿真器加载顶层测试平台保留全部信号调试可见性 vsim -voptargsacc -t 1ps work.tb_top # 4. 添加需要观察的波形信号 add wave -noupdate /tb_top/clk add wave -noupdate /tb_top/rst_n add wave -noupdate /tb_top/din add wave -noupdate /tb_top/dout # 5. 设置信号显示进制十六进制便于查看数据总线 radix hex /tb_top/dout # 6. 运行仿真指定时长此处运行 10us run 10us # 7. 保存波形文件供后续查看或回归对比 write format wave -window .waveform ./sim_result.wlf # 8. 输出仿真完成提示并退出仿真保留 Modelsim 主界面 puts 仿真完成波形已保存至 sim_result.wlf quit -simVerilog 工程专用脚本示例下面是一个针对纯 Verilog 工程的完整自动化仿真 TCL 脚本覆盖从创建库、编译、启动仿真、添加波形、运行到保存波形的全流程可直接保存为run_verilog.tcl并通过source ./run_verilog.tcl执行# # Verilog 工程自动化仿真脚本 run_verilog.tcl # 功能完成从建库、编译到仿真、保存波形的全流程 # # 1. 创建仿真库若已存在则先删除重建保证干净环境 if {[file exists work]} { vdel -all } else { vlib work } # 2. 编译 Verilog 设计文件与测试平台纯 Verilog 工程 vlog -work work ./src/top.v ;# 编译 Verilog 顶层设计模块 vlog -work work ./src/tb_top.v ;# 编译 Verilog 测试平台 # 3. 启动仿真器加载顶层测试平台保留全部信号调试可见性 vsim -voptargsacc -t 1ns work.tb_top # 4. 添加需要观察的波形信号 add wave -noupdate /tb_top/clk add wave -noupdate /tb_top/rst_n add wave -noupdate /tb_top/din add wave -noupdate /tb_top/dout # 5. 设置信号显示进制十六进制便于查看数据总线 radix hex /tb_top/dout # 6. 运行仿真指定时长此处运行 10us run 10us # 7. 保存波形文件供后续查看或回归对比 write format wave -window .waveform ./verilog_result.wlf # 8. 输出仿真完成提示并退出仿真保留 Modelsim 主界面 **Verilog 脚本要点说明** - **第 2 步**纯 Verilog 工程只需用 vlog 编译无需 vcom设计文件与测试平台分别编译顺序上先编译设计模块再编译测试平台。 - **第 3 步**vsim -voptargsacc 保留所有内部信号可见性-t 1ns 设置时间精度为 1nsVerilog 工程常用加载测试平台 tb_top。 - **第 4 步**add wave -noupdate 批量添加待观察信号-noupdate 避免实时刷新提升效率。 - **第 5 步**radix hex 将数据总线以十六进制显示便于阅读。 - **第 6 步**run 10us 运行 10 微秒仿真。 - **第 7 步**write format wave 将波形保存为 .wlf 文件便于后续打开查看或回归对比。 - **第 8 步**puts 输出提示信息quit -sim 仅退出仿真而不关闭 Modelsim 主界面。 puts Verilog 仿真完成波形已保存至 verilog_result.wlf quit -simVHDL 工程专用脚本示例下面是一个针对纯 VHDL 工程的完整自动化仿真 TCL 脚本覆盖从创建库、编译、启动仿真、添加波形、运行到保存波形的全流程可直接保存为run_vhdl.tcl并通过source ./run_vhdl.tcl执行# # VHDL 工程自动化仿真脚本 run_vhdl.tcl # 功能完成从建库、编译到仿真、保存波形的全流程 # # 1. 创建仿真库若已存在则先删除重建保证干净环境 if {[file exists work]} { vdel -all } else { vlib work } # 2. 编译 VHDL 设计文件与测试平台纯 VHDL 工程 vcom -2008 -work work ./src/top.vhd ;# 编译 VHDL 顶层设计模块VHDL-2008 标准 vcom -2008 -work work ./src/tb_top.vhd ;# 编译 VHDL 测试平台 # 3. 启动仿真器加载顶层测试平台保留全部信号调试可见性 vsim -voptargsacc -t 1ps work.tb_top # 4. 添加需要观察的波形信号 add wave -noupdate /tb_top/clk add wave -noupdate /tb_top/rst_n add wave -noupdate /tb_top/din add wave -noupdate /tb_top/dout # 5. 设置信号显示进制十六进制便于查看数据总线 radix hex /tb_top/dout # 6. 运行仿真指定时长此处运行 10us run 10us # 7. 保存波形文件供后续查看或回归对比 write format wave -window .waveform ./vhdl_result.wlf # 8. 输出仿真完成提示并退出仿真保留 Modelsim 主界面 puts VHDL 仿真完成波形已保存至 vhdl_result.wlf quit -simVHDL 脚本要点说明第 2 步纯 VHDL 工程只需用vcom编译无需vlog设计文件与测试平台分别编译顺序上先编译设计模块再编译测试平台。-2008指定 VHDL-2008 标准若代码使用 VHDL-93 语法可改为-93。第 3 步vsim -voptargsacc保留所有内部信号可见性-t 1ps设置时间精度为 1psVHDL 工程常用与 Verilog 工程的 1ns 不同加载测试平台tb_top。第 4 步add wave -noupdate批量添加待观察信号-noupdate避免实时刷新提升效率。第 5 步radix hex将数据总线以十六进制显示便于阅读。第 6 步run 10us运行 10 微秒仿真。第 7 步write format wave将波形保存为.wlf文件便于后续打开查看或回归对比。第 8 步puts输出提示信息quit -sim仅退出仿真而不关闭 Modelsim 主界面。VHDL 与 Verilog 脚本的 3 个关键差异点编译命令不同VHDL 工程使用vcom编译如vcom -2008 -work work ./src/top.vhdVerilog 工程使用vlog编译如vlog -work work ./src/top.v。两者不能混用且 VHDL 编译需通过-93/-2008显式指定语言标准版本而 Verilog 编译仅在 SystemVerilog 文件时才需加-sv选项。时间精度设置不同VHDL 工程vsim常用-t 1ps皮秒级精度适配 VHDL 中常见的时间单位声明Verilog 工程常用-t 1ns纳秒级精度与 Verilog 的timescale习惯更匹配。两者都需与设计内部的时间单位保持一致避免仿真时间换算偏差。信号路径写法不同VHDL 测试平台中信号路径同样以/tb_top/信号名形式书写如/tb_top/dout与 Verilog 一致但 VHDL 中信号名区分大小写且常使用下划线命名如rst_n、data_out而 Verilog 信号名不区分大小写。此外VHDL 中访问子模块信号时路径层级写法与 Verilog 相同但需注意 VHDL 的实体/结构体层级在波形窗口中的显示方式略有差异。常见报错与排查在实际使用中Modelsim 的 TCL 命令常因库缺失、语法错误、信号不可见等问题报错。下面整理 4 类高频报错给出典型错误信息、原因分析和解决命令帮助快速定位问题。1. 库不存在vlib / vmap 相关典型错误信息# ** Error: (vcom-66) Cannot find library work. # ** Error: (vmap-7) Cannot open work for reading.原因分析未先创建仿真库或当前工作目录与库路径不一致导致编译/仿真时找不到目标库。解决命令# 先创建并映射默认工作库 vlib work vmap work work # 若库已存在但内容损坏可删除重建 vdel -all vlib work2. 编译语法错误vcom / vlog 相关典型错误信息# ** Error: (vcom-1136) Unknown identifier clk. # ** Error: (vlog-1306) syntax error near module.原因分析代码本身存在语法错误或编译时指定的 VHDL/Verilog 标准版本与代码不匹配如用 VHDL-2008 语法却以-93编译。解决命令# 先定位错误行号再修正源码 vcom -2008 -work work ./src/top.vhd ;# 改用 VHDL-2008 标准重新编译 vlog -sv -work work ./src/top.sv ;# 确认 SystemVerilog 文件加了 -sv 选项 # 编译前先查看帮助确认选项用法 help vcom help vlog3. 信号不可见vsim / add wave 相关典型错误信息# ** Error: (vsim-3033) /tb_top/internal_sig Instantiation of dut failed. # ** Warning: (vsim-3017) /tb_top/dut/clk is not visible.原因分析启动仿真时未加-voptargsacc导致内部模块信号被优化掉无法在波形窗口查看。解决命令# 重新启动仿真保留所有信号调试可见性 vsim -voptargsacc -t 1ps work.tb_top # 若仍不可见可尝试关闭优化后重启 vsim -voptargsacc -novopt work.tb_top4. 仿真卡死 / 长时间无响应run 相关典型错误信息# 仿真长时间停在某一时刻波形不再更新 # ** Note: (vsim-3585) Simulation is running...原因分析常见于时钟或激励未正确终止run -all后仿真无限循环或force设置的时钟周期过小导致事件过多。关于时钟激励的补充说明时钟是仿真中最核心的激励信号其配置是否合理直接影响仿真能否正常结束。使用force设置时钟时需重点把握以下三点周期与占空比force /tb_top/clk 0 0ns 1 5ns -repeat 10ns表示时钟周期为 10ns其中低电平 0ns~5ns、高电平 5ns~10ns占空比 50%。若占空比非 50%如0 0ns 1 3ns -repeat 10ns需确认设计对高低电平宽度的要求避免建立/保持时间违例。时间单位匹配force中的时间值需与vsim -t设置的时间精度一致。若精度为 1ps而时钟周期写成-repeat 10nsModelsim 会自动换算但建议统一使用同一单位如全部用 ns避免因单位混用导致周期偏差。时钟与复位配合复位信号通常先拉低一段时间再拉高确保设计进入确定状态后再启动时钟。例如force /tb_top/rst_n 0 0ns force /tb_top/rst_n 1 100ns force /tb_top/clk 0 0ns 1 5ns -repeat 10ns这样设计在 0~100ns 内保持复位100ns 后时钟开始驱动逻辑仿真行为更可控。解决命令# 先暂停仿真检查当前时刻与信号状态 stop examine /tb_top/clk # 改用指定时长运行避免无限循环 run 10us # 若确认激励有问题重启仿真并修正时钟/复位激励 restart -f force /tb_top/clk 0 0ns 1 5ns -repeat 10ns run 10us排查小结遇到报错时先看错误码如vcom-66、vsim-3033再用help command确认命令选项最后按「建库 → 编译 → 启动 → 运行」的顺序逐环节定位即可快速解决问题。