Skip to content

xmake 的配置参数

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

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

必要参数

必要参数为必须在 xmake.lua 中对应的 target 添加的，否则进行编译的时候会报错。

  1. add_rules("verilua")

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

  2. add_toolchains(<toolchain>)

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

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

  3. add_files(...)

    添加需要进行仿真的文件，可以在一个语句中同时添加多个文件，也可以分为多个语句来添加多个文件。

    • 对于 HVL 场景，可以是 Verilog/SystemVerilog 文件、Lua 文件。
      xmake.lua
      target("test", function()
    add_rules("verilua")
    add_toolchains("@verilator")
    add_files("src/main.sv", "src/main.lua")
    add_files("src/other.v")

    -- ...
end)

    • 对于 WAL 场景，可以是波形文件、Lua文件。

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

    -- ...
end)

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

  4. set_values("cfg.top", <top module name>)

    设置此时的顶层 DUT 的模块名称，对于 HVL/WAL 场景，这个参数必须设置，例如在这个例子 中我们顶层 DUT 模块的名称是 Design，因此可以这么设置：set_values("cfg.top", "Design")。

  5. set_values("cfg.lua_main", <lua main file>)

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

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

可选参数

  1. set_values("cfg.user_cfg", <user cfg file>)

    设置用户自定义的配置文件，这个配置文件是一个 Lua 脚本，格式如下所示：

    my_cfg.lua
    1
2
3
4
5
6
    local cfg = {}

cfg.value1 = 123
cfg.value2 = "hello"

return cfg

    重点在于这个 Lua 脚本要返回一个 key-value 格式的 table。

    当用户在 xmake.lua 中设置了这个配置文件的时候（set_values("cfg.user_cfg", "my_cfg.lua")），那么在仿真进行的时候，可以通过全局变量 cfg 获取到这个 table 中的值，例如：

    main.lua
    1
2
3
4
5
6
7
8
9
    fork {
    function ()
        print("cfg.value1 => ", cfg.value1)
        print("cfg.value2 => ", cfg.value2)

        assert(cfg.value1 == 123)
        assert(cfg.value2 == "hello")
    end
}

  2. set_values("cfg.tb_gen_flags", <flags for testbench_gen>) / add_values("cfg.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 文档中此处的说明。

  3. set_values("<sim>.flags", <flags used in compilation>) / add_values("<sim>.flags", "<flags used in compilation>")

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

    注意

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

  4. 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。
    • 对于 WAL 场景，这一设置不起作用。

  5. 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。
    • 对于 WAL 场景，这一设置不起作用。

    run_prefix 和 run_flags 的位置区别

    <run_prefix> <binary> <run_flags>

  6. set_values("cfg.build_dir_name", <build directory name>)

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

    构建目录生成的位置

    默认情况下为：./build/<simulator>/<top module name>，如果使用了 set_values("cfg.build_dir_name", "SomeName")，那么会使用用户自定义的名称：./build/<simulator>/SomeName。不过请注意，./build/<simulator> 是必须存在的，不支持更改。

  7. set_values("cfg.build_dir_path", <build directory path>)

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

    set_values("cfg.build_dir_path", "/tmp/builds")
    最终构建目录为 <build_dir_path>/<build_dir_name>，如未设置 build_dir_name，则默认为顶层模块名。

  8. set_values("cfg.version_required", "<version constraint>")

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

    set_values("cfg.version_required", ">=1.0.0")
    构建时会自动校验当前 Verilua 版本是否满足要求。

  9. set_values("cfg.no_internal_clock", "1")

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

    示例：

    xmake.lua
    target("my_test", function()
    add_rules("verilua")
    add_toolchains("@verilator")
    set_values("cfg.top", "Top")
    set_values("cfg.lua_main", "main.lua")
    add_files("Top.v", "main.lua")
    set_values("cfg.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(2)
            clock:set(0)
            await_time(2)
        end
    end,

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