Skip to main content

特殊环境变量

Verilua 支持通过环境变量来控制其行为和配置。所有环境变量都是可选的，如果不设置，Verilua 会使用合理的默认值。环境变量可以在 shell 中永久设置（通过 export，仅当前 shell 有效），也可以在每次命令前临时指定，两者灵活搭配。

tip

环境变量的优先级通常高于配置文件中的同名设置，但具体规则请参考各变量的说明。

变量概览​

变量名简要说明
SIM指定使用的仿真器类型
SEED设置仿真随机种子
PRJ_DIR指定项目根目录
PRJ_TOP额外 Lua 搜索路径根
VL_DUT_TOP指定设计的顶层模块名称
VL_LUA_SCRIPT指定 Lua 主脚本文件
VL_POST_INIT_SCRIPTinit.lua 之后、主脚本之前执行的 post-init（文件路径或 Lua 源码）
VL_DEBUG启用 Verilua debug 输出
VL_QUIET静默模式，禁用日志输出
VL_LOG_LEVEL日志级别下限
VL_PERF_TIME启用性能时间统计
VL_ACC_LUA_TIME启用 libverilua 侧 Lua 执行时间统计（lua_time_taken / lua_overhead）
VL_RESOLVE_X_AS_ZERO四态后端数值读按位清除 x/z；默认开启
VL_WAVEFORM_FILEWAL/wave_vpi 波形文件路径
VL_HIERARCHY_CACHE_FILE层级缓存文件路径
VL_PRINT_HIER_STYLE层级打印样式
VL_NOSIM_BUILDnosim 构建路径标记
VL_CFG_FILE用户配置文件路径
VL_TARGET_NAME当前 xmake target 名称（rule 自动注入）
VL_BUILD_DIR当前 target 构建目录绝对路径（rule 自动注入）
VL_BUNDLE_KEY_HEX编译 libverilua 时注入的打包密钥（64 hex 为裸密钥，否则 SHA-256；仅构建）
VERILUA_HOMEVerilua 安装根路径

核心环境变量​

SIM (可选，需谨慎使用)​

指定使用的仿真器类型。此变量应与编译时使用的仿真器保持一致，否则可能导致运行时错误。

  • 默认值：自动检测（通过 vpiml）
  • 可选值：
    • verilator – Verilator 仿真器
    • vcs – Synopsys VCS 仿真器
    • xcelium – Cadence Xcelium 仿真器
    • iverilog – Icarus Verilog 仿真器
    • wave_vpi – Verilua 波形分析后端（WAL 模式）
    • nosim – Verilua 的 slang 后端，只做 elaborate 与 signal_db 生成，不仿真
  • 优先级：cfg.simulator 配置文件 > SIM 环境变量 > 自动检测
  • 相关配置影响：
    • 设置 cfg.simulator 值
    • 当值为 wave_vpi 时，自动设置 cfg.is_wal = true
    • 当值为其他仿真器且设置了 cfg.is_hse = true 时，为 HSE 模式
    • cfg.is_hse 和 cfg.is_wal 不能同时为 true
  • 示例： 
    # 临时指定（仅本次命令生效）
    SIM=vcs xmake run -P . <target_name>
    SIM=verilator xmake build -P . <target_name> && SIM=verilator xmake run -P . <target_name>

    # 永久设置（当前 shell 及子进程有效）
    export SIM=iverilog
    xmake build -P . <target_name>
    xmake run -P . <target_name>

VL_LUA_SCRIPT (可选)​

指定 Lua 主脚本文件。通常由 xmake 配置 verilua.lua_main 设置，也可通过此环境变量覆盖。

  • 默认值：由 verilua.lua_main 决定
  • 示例： 
    VL_LUA_SCRIPT=/path/to/main.lua xmake run -P . <target_name>

VL_CFG_FILE (可选)​

用户配置文件路径（相对或绝对）。未设置时不加载用户配置。配置文件所在目录由 dirname(VL_CFG_FILE) 推导并加入 package.path。

  • 默认值：未设置（xmake 运行时会注入生成的 verilua_cfg.lua）
  • 示例： 
    VL_CFG_FILE=/path/to/mysim_config.lua xmake run -P . <target_name>
    export VL_CFG_FILE=./mysim_config.lua

VL_TARGET_NAME (可选，xmake rule 自动注入)​

当前 xmake target 的名称（target:name()）。由 verilua xmake rule 写入 runenvs，因此：

  • xmake run 时 Lua 可通过 os.getenv("VL_TARGET_NAME") 读取
  • 构建目录下的 setvars.sh / run.sh 也会 export 同名变量

适合多 target 共用一份 main 时区分用例、命名日志/输出文件等。

  • 默认值：未走 xmake rule 时不设置；经 rule 构建/运行时为当前 target 名
  • 示例： 
    -- main.lua
    local target_name = os.getenv("VL_TARGET_NAME")
    print("running target:", target_name)

VL_BUILD_DIR (可选，xmake rule 自动注入)​

当前 target 的构建目录绝对路径（与 rule 计算的 build_dir 相同，通常为 ./build/<sim>/<top> 的绝对形式）。同样写入 runenvs，xmake run 与 setvars.sh / run.sh 都可见。

on_run 会 cd 到该目录，但脚本若需要稳定绝对路径（写日志/波形/产物），应读本变量而不是依赖 cwd。

  • 默认值：未走 xmake rule 时不设置；经 rule 构建/运行时为当前 target 的 build dir
  • 示例： 
    -- main.lua
    local build_dir = os.getenv("VL_BUILD_DIR")
    local log = build_dir .. "/case.log"

VL_POST_INIT_SCRIPT (可选)​

在 init.lua 加载完成、且 VL_DUT_TOP 自动补齐之后，主脚本 VL_LUA_SCRIPT 之前执行的可选 hook。 适合不改 main 的启动期注入；固定项目配置仍优先用 verilua.user_cfg / cfg。

  • 默认值：未设置则跳过

  • 值形态：

    • 若值为已存在的文件路径 → dofile 加载该文件
    • 否则 → 作为 Lua 源码字符串 执行（chunk 名 VL_POST_INIT_SCRIPT）

  • 空字符串：panic（不静默跳过）

  • 歧义：若源码字符串恰好等于当前工作目录下某个真实文件路径，会按文件执行；文件路径建议使用绝对路径

  • 典型用途：

    • 多用例共享的 bootstrap（改 package.path、公共 require、统一开关）
    • 临时调试补丁（多打日志、改 seed/flag），不污染 main
    • CI / 矩阵差异化：同一 main，不同 job 注入不同 post-init
    • 本地/客户侧覆写：上游固定 main，本地用 hook 塞路径或插件
    • xmake 侧固定注入：add_runenvs("VL_POST_INIT_SCRIPT", "...")（多行源码可用 [[]]；写入 setvars.sh 时 runenv 值会 shell quote）

  • 示例：

    # 文件模式
    VL_POST_INIT_SCRIPT=/path/to/post_init.lua xmake run -P . <target_name>

    # 源码字符串模式
    VL_POST_INIT_SCRIPT='print("post-init")' xmake run -P . <target_name>
    xmake.lua
    add_runenvs("VL_POST_INIT_SCRIPT", path.join(os.scriptdir(), "scripts", "common_bootstrap.lua"))

VL_DUT_TOP (可选)​

指定设计的顶层模块名称。若未设置，Verilua 会自动通过 VPI 接口获取第一个模块的名称作为顶层模块。

  • 默认值：自动获取
  • 对应 cfg 字段：cfg.top
  • 自动获取方式：通过 vpiml 遍历当前设计中的模块，取第一个模块的名称。
  • 示例： 
    # 临时指定
    VL_DUT_TOP=tb_top xmake run -P . <target_name>

    # 永久设置（当前 shell 有效）
    export VL_DUT_TOP=tb_top

PRJ_DIR (可选)​

指定项目根目录。Verilua 在加载依赖时会参考此路径。

  • 默认值：.（当前目录）
  • 对应 cfg 字段：cfg.prj_dir（运行时解析为绝对路径：相对路径按启动时的工作目录拼接，保证字段值无歧义、可直接用于路径拼接）
  • 示例： 
    # 临时指定
    PRJ_DIR=/path/to/project xmake run -P . <target_name>

    # 永久设置（当前 shell 有效）
    export PRJ_DIR=/path/to/project

SEED (可选)​

设置仿真随机种子，用于保证随机数序列的可重复性。

  • 默认值：1234
  • 对应 cfg 字段：cfg.seed
  • 优先级说明：环境变量 SEED 的优先级高于配置文件中的 cfg.seed，即如果同时设置，环境变量会覆盖配置文件的值。
  • 同时决定 DUT 侧随机数：SEED 也会被注入仿真器的运行参数，因此 RTL 里的 $urandom / $urandom_range 同样随 SEED 变化；各后端的注入参数见仿真后端默认参数。
  • 示例： 
    # 临时指定
    SEED=42 xmake run -P . <target_name>

    # 永久设置（当前 shell 有效）
    export SEED=42

调试与日志变量​

VL_DEBUG (可选)​

启用 Verilua 调试输出。设置后，代码中的 verilua_debug() 调用将输出调试信息。

  • 默认值：未启用
  • 使用效果：启用后会输出 verilua_debug() 调试信息
  • 性能影响：未设置时零开销（verilua_debug 为空函数）
  • 示例： 
    # 临时启用
    VL_DEBUG=1 xmake run -P . <target_name>

    # 永久启用（当前 shell 有效）
    export VL_DEBUG=1

VL_QUIET (可选)​

静默模式，禁用 Verilua 框架内部的日志输出。此模式不影响用户代码中的 print() 调用。

  • 默认值：未启用（正常输出日志）
  • 影响范围：
    • Logger 模块的所有方法：info()、debug()、warning()、error()、success()
    • 仿真结束时 Rust 层输出的统计信息表格（VERILUA STATISTIC），包含：
      • total_time_taken – 总耗时
      • lua_time_taken – Lua 执行耗时
      • lua_overhead – Lua 开销百分比
  • 注意：仅影响 Verilua 框架内部的 Logger 模块输出，用户代码中的 print() 函数不受影响（因为 Logger 模块使用的是局部的 print 变量，而用户代码使用的是全局 print 函数）。
  • 示例： 
    # 临时启用静默模式
    VL_QUIET=1 xmake run -P . <target_name>

    # 永久启用（当前 shell 有效）
    export VL_QUIET=1

VL_PERF_TIME (可选)​

启用性能时间统计。仿真结束时，Verilua 会输出任务级的耗时统计，帮助定位性能瓶颈。

  • 默认值：未启用
  • 示例： 
    # 临时启用
    VL_PERF_TIME=1 xmake run -P . <target_name>

    # 永久启用（当前 shell 有效）
    export VL_PERF_TIME=1

VL_ACC_LUA_TIME (可选)​

启用 libverilua（Rust 侧）的 Lua 时间统计。开启后，仿真结束统计表中的 lua_time_taken 与 lua_overhead 列显示进入 Lua 回调的累计耗时及占比；未设置时这两列显示 -- 并打印灰色提示。取代旧的编译期 cargo feature acc_time，无需重新编译即可切换。

  • 默认值：未启用
  • 取值：1 或 true 启用
  • 示例： 
    VL_ACC_LUA_TIME=1 xmake run -P . <target_name>

VL_RESOLVE_X_AS_ZERO (可选，4 状态后端)​

控制 4 状态后端（例如 iverilog、vcs、xcelium、wave_vpi）上的数值读遇到 x/z 时返回什么。VPI 的向量读按标准编码 4 状态值（ab: 00=0, 10=1, 11=X, 01=Z）：x 位在 aval 里也是 1，z 位是 0，只有 bval 标记这两者。开启这个开关后 Verilua 把这些位读成 0、其余位保留原值，避免测试读到看似正常的 1。1~32 bit 的读走 vpiIntVal，仿真器自身就按这个规则给值，不受开关影响。

iverilog 的字符串读（get_str / get_hex_str / get_bin_str / get_dec_str）也受此开关控制。

写入路径及其他后端的字符串读不受此开关影响，各 API 的返回格式见信号句柄（CallableHDL）。

  • 默认值：开启（未设置即开启）
  • 取值：只有 1 或 true 开启，其余取值（含 0、false、空串）关闭
  • 作用范围：数值读覆盖所有 4 状态后端（iverilog / vcs / xcelium / wave_vpi）；字符串转换仅限 iverilog。Verilator 是 2 状态，不读这个变量
  • 关闭后的行为：3364 bit 读、multi beat 读返回原始 aval（x 位读成 1、z 位读成 0）；132 bit 仍是按位 0，仿真器没有提供 x 信息；iverilog 字符串读保留原始未知值字符
  • 示例： 
    # 读原始 aval：x 位为 1、z 位为 0，而不是都读成 0
    VL_RESOLVE_X_AS_ZERO=0 SIM=iverilog xmake run -P . <target_name>
    VL_RESOLVE_X_AS_ZERO=0 SIM=vcs xmake run -P . <target_name>
  • 相关文档：信号句柄（CallableHDL）

VL_BUNDLE_KEY_HEX (可选，构建期)​

编译 libverilua 时写入 AES-256-GCM 密钥。运行时不读此变量。未设置则库能链，但不能打/解 .vlbc。不要提交仓库。

  • 默认值：未设置
  • 格式：64 个 hex → 裸密钥；其它非空字符串 → 整串 SHA-256（不截断）。多/少一个字符都是另一把钥匙
  • 范围：仅编译 libverilua。打包须在已加载该库的 Verilua 进程里做
  • 示例：VL_BUNDLE_KEY_HEX='口令' xmake run build_libverilua
  • 相关文档：加密打包验证组件（BundleToVlbc）

相关文档​