xmake 的配置参数

Verilua 的 HVL/WAL 场景下的工程管理使用的是 xmake，因此在 xmake 中支持多种可配置的参数，下面将对其进行说明。

用户可以使用 xmake 来编写灵活多样的 xmake.lua 文件来构建工程，具体可以参考 xmake 官方文档

概览

这一页介绍 Verilua 在 xmake.lua 中常用的配置项，以及它们分别影响什么。

必需配置

这些配置必须在 xmake.lua 中对应的 target 里设置，否则构建或运行时会报错。

启用 Verilua

对应配置：add_rules("verilua")

对于所有的 HVL/WAL 场景下的工程，都需要在 xmake 的 target 中添加这一句配置，否则将无法正常使用 Verilua。

选择仿真后端

对应配置：add_toolchains(<toolchain>)

添加具体的仿真器（Verilua 中称为仿真后端（Backend））。

对于 HVL 场景，目前 <toolchain> 的可选值为 @verilator、@iverilog、@vcs、 @xcelium，分别对应了开源的 Verilator、开源的 Icarus Verilog、商业的 Synopsys VCS、Cadence Xcelium 等仿真器。
对于 WAL 场景，目前 <toolchain> 的可选值为 @wave_vpi，wave_vpi 是 Verilua 开发的一个用于仿真波形的仿真后端，目前支持的波形格式为: VCD、FST、FSDB。

添加输入文件

对应配置：add_files(...)

添加需要进行仿真的文件，可以在一个语句中同时添加多个文件，也可以分为多个语句来添加多个文件。add_files 支持 xmake 的通配符（glob）写法，便于批量添加源文件。

对于 HVL 场景，可以是 Verilog/SystemVerilog 文件，以及需要参与工程管理的 Lua 文件。

xmake.lua
target("test", function()
    add_rules("verilua")
    add_toolchains("@verilator")
    add_files("src/main.sv")
    add_files("src/other.v")
    add_files("rtl/**/*.sv")  -- 通配符：递归添加 rtl 目录下所有 .sv 文件

    -- ...
end)

对于 WAL 场景，可以是波形文件，以及需要复用的 Lua 文件。

xmake.lua
target("test", function()
    add_rules("verilua")
    add_toolchains("@wave_vpi")
    add_files("./test.vcd")

    -- ...
end)

此时 add_files 只能添加一个波形文件

set_values("verilua.lua_main", ...) 指向的 Lua 入口脚本不需要额外添加到 add_files(...) 中。

移除输入文件

对应配置：remove_files(...)

从 add_files 已添加的文件列表中移除指定文件，支持与 add_files 相同的通配符（glob）写法。

add_files("src/*.sv")
remove_files("src/test.sv")            -- 移除单个文件
remove_files("src/wip_*.sv")           -- 通配符批量移除
remove_files("src/subdir/*.sv")         -- 移除 subdir 下所有 .sv

指定顶层模块

对应配置：set_values("verilua.top", <top module name>)

设置 DUT 顶层模块的名称。对于 HVL/WAL 场景，这个参数必须设置。

HVL 场景：设置为实际的顶层 DUT 名称（如 Design、Counter），Verilua 会据此生成 testbench 并自动将运行期 cfg.top 设为 testbench 顶层名。
WAL 场景：根据波形文件的层次结构设置，详见下方说明

例如在这个例子中我们顶层 DUT 模块的名称是 Design，因此可以这么设置：set_values("verilua.top", "Design")。

指定 Lua 入口脚本

对应配置：set_values("verilua.lua_main", <lua main file>)

设置仿真时候执行的 lua 主脚本文件，对于 HVL/WAL 场景，这个参数必须设置，例如在这个例子中我们的 lua 主脚本文件是 LuaMain.lua，因此可以这么设置：set_values("verilua.lua_main", "LuaMain.lua")。

<lua main file> 是一个具体的文件，可以包含路径。

该入口脚本由 verilua.lua_main 单独指定，不需要再放进 add_files(...)。

顶层模块的设置指南

HVL 场景：verilua.top 应始终填写 DUT 顶层模块名称：

set_values("verilua.top", "Design")  -- 始终指定 DUT 名称

Verilua 会自动生成 testbench（默认名 tb_top）并例化该 DUT。运行期 Lua 侧的 cfg.top 会被自动映射为 tb_top（即信号层次的根节点），无需手动设置。

WAL 场景：verilua.top 应该设置为波形文件中的顶层模块名称。这取决于波形是如何生成的：

场景 1：波形由 Verilua 的 HVL 仿真生成

如果波形文件是通过 Verilua 的 HVL 仿真生成的（如 WAL 示例中的 gen_wave）， Verilua 会自动使用 testbench_gen 生成 tb_top 模块，波形文件的顶层是 tb_top：

set_values("verilua.top", "tb_top")

这样可以访问：

Testbench 信号（时钟、复位等）
导出的 DUT 端口
通过层次路径访问 DUT 内部信号（如 tb_top.uut.count_reg）

场景 2：波形直接来自 RTL（无 testbench 层）

如果波形文件是直接从 RTL 编译生成的（不通过 Verilua，没有 testbench）， verilua.top 应该指向实际的 RTL 顶层模块：

set_values("verilua.top", "top")  -- 或者你的实际顶层模块名

如何确定应该使用哪个值？

查看波形文件： 在波形查看器（如 GTKWave、Verdi）中打开波形文件，查看顶层模块名称
查看信号路径： 如果信号路径包含 tb_top. 前缀，则应使用 verilua.top = "tb_top"
参考生成方式：
- 通过 Verilua 的 HVL 仿真生成 → 通常包含 tb_top 层次
- 直接用仿真器编译 RTL（不经过 Verilua）→ 通常是实际的模块名

`testbench_gen` 配置

传递额外的 `testbench_gen` 参数

对应配置：set_values("verilua.tb_gen_flags", <flags for testbench_gen>) / add_values("verilua.tb_gen_flags", "<flags for testbench_gen>")

设置需要传递给 testbench_gen 的额外参数，具体支持的 flags 可以参考这里的介绍。

xmake 中 set_values 和 add_values 的区别

set_values(<key>, <value>) 对 <key> 进行单次赋值，调用多次 set_values 时，会覆盖之前的值，一个 set_values 只能有一个 <value>；

set_values("key", "value1") -- "key" = "value1"
set_values("key", "value2") -- "key" = "value2", the previous value "value1" is overwritten

add_values(<key>, <value> ...) 对 <key> 进行多次赋值，调用多次 add_values 时，会合并之前的值，一个 add_values 可以有多个 <value>。

add_values("key", "value1") -- "key" = "value1"
add_values("key", "value2") -- "key" = {"value1", "value2"}, the previous value "value1" is merged

-- equivalent to

set_values("key", "value1", "value2")

也可以参考 xmake 文档中此处的说明。

控制内部时钟生成

对应配置：set_values("verilua.no_internal_clock", "1")

禁用自动时钟生成，适用于需要自定义时钟的场景。此时需在主 Lua 文件中手动生成时钟信号。

示例：

xmake.lua
target("my_test", function()
    add_rules("verilua")
    add_toolchains("@verilator")
    set_values("verilua.top", "Top")
    set_values("verilua.lua_main", "main.lua")
    add_files("Top.v")
    set_values("verilua.no_internal_clock", "1") -- 禁用自动时钟生成
end)

对应的 main.lua 需手动生成时钟信号：

main.lua
fork {
    clock_gen_task = function()
        local clock = dut.clock:chdl()
        while true do
            clock:set(1)
            await_time_ns(2)
            clock:set(0)
            await_time_ns(2)
        end
    end,

    another_task = function()
        -- ...
    end
}

仿真运行配置

添加编译参数

对应配置：set_values("<sim>.flags", <flags used in compilation>) / add_values("<sim>.flags", "<flags used in compilation>")

用来添加需要传递给仿真器进行编译的额外参数，具体支持的 flags 可以与使用的仿真器相关。

注意

对于 HVL 场景，目前 <sim> 可选值为 verilator、iverilog、vcs 、 xcelium。
对于 WAL 场景，这一设置不起作用。

添加运行参数

对应配置：set_values("<sim>.run_flags", <flags used at runtime>) / add_values("<sim>.run_flags", "<flags used at runtime>")

用来添加需要传递给编译后的二进制文件运行时的额外参数。例如 Verilator 编译得到的二进制文件通常叫 Vtb_top，则可以使用 set_values("verilator.run_flags", "--help") 来添加一个运行时参数，这样在 xmake 执行 run 的时候就会加上这个参数。运行仿真的时候等价于 Vtb_top --help。

注意

对于 HVL 场景，目前 <sim> 可选值为 verilator、iverilog、vcs、 xcelium。
对于 WAL 场景，这一设置不起作用。

添加运行前缀

对应配置：set_values("<sim>.run_prefix", <prefix flags used at runtime>) / add_values("<sim>.run_prefix", "<prefix flags used at runtime>")

用来添加需要传递给编译后的二进制文件运行时的额外前缀参数。例如 Verilator 编译得到的二进制文件通常叫 Vtb_top，则可以使用 set_values("verilator.run_prefix", "gdb --args") 来添加一个运行时前缀参数，这样在 xmake 执行 run 的时候就会加上这个参数。运行仿真的时候等价于 gdb --args Vtb_top。

注意

对于 HVL 场景，目前 <sim> 可选值为 verilator、iverilog、vcs、 xcelium。
对于 WAL 场景，这一设置不起作用。

run_prefix 和 run_flags 的位置区别

<run_prefix> <binary> <run_flags>

构建目录配置

设置构建目录名称

对应配置：set_values("verilua.build_dir_name", <build directory name>)

设置构建目录的名称，如果不设置，默认为 set_values("verilua.top", <top module name>) 的值。

构建目录生成的位置

默认情况下为：./build/<simulator>/<top module name>，如果使用了 set_values("verilua.build_dir_name", "SomeName")，那么会使用用户自定义的名称：./build/<simulator>/SomeName。这里的 ./ 默认表示当前工程中 xmake.lua 所在的目录；文档中的命令示例也默认在该目录下执行。

设置构建目录位置

对应配置：set_values("verilua.build_dir_path", <build directory path>)

设置构建目录的父路径。例如：

set_values("verilua.build_dir_path", "/tmp/builds")

最终构建目录为 <build_dir_path>/<build_dir_name>，如未设置 build_dir_name，则默认为顶层模块名。如果 verilua.build_dir_path 使用相对路径，则同样默认相对于当前工程中 xmake.lua 所在的目录解析。

其他配置

加载用户自定义配置

对应配置：set_values("verilua.user_cfg", <user cfg file>)

用于指定一个用户自定义 Lua 配置文件。

这个 Lua 文件需要返回一个 table；在运行期，这个 table 里的字段会被合并到全局变量 cfg 中。

常见误解

这里的 verilua.user_cfg 只是 xmake 配置项名，不代表运行期存在 cfg.user_cfg 这个字段。

完整的运行期行为说明见 global_configuration。

限制最低 Verilua 版本

对应配置：set_values("verilua.version_required", "<version constraint>")

指定最低 Verilua 版本要求。例如：

set_values("verilua.version_required", ">=1.0.0")

构建时会自动校验当前 Verilua 版本是否满足要求。

概览​

必需配置​

启用 Verilua​

选择仿真后端​

添加输入文件​

移除输入文件​

指定顶层模块​

指定 Lua 入口脚本​

顶层模块的设置指南​

testbench_gen 配置​

传递额外的 testbench_gen 参数​

控制内部时钟生成​

仿真运行配置​

添加编译参数​

添加运行参数​

添加运行前缀​

构建目录配置​

设置构建目录名称​

设置构建目录位置​

其他配置​

加载用户自定义配置​

限制最低 Verilua 版本​

相关文档​

概览