Skip to content

Releases

v0.15.0

Choose a tag to compare

@hesheng01 hesheng01 released this 18 Oct 08:40

Changed

  • rel_eval 正式更名为上游写法 reval(旧名不再兼容;expr@offset 语法糖不变)。
  • set 移除, set! 成为唯一赋值写法(直接对已定义变量赋值,词法穿透共享 cell;不再支持
    (set (x 1) (y 2)) 多对赋值)。
  • count/step / find/step 移除(与 count/find 完全重叠:统一引擎与逐拍回退现在共用
    "索引空间=实际读值波形"的同一规则,不再需要两组算子)。

Removed

  • 与上游 WAL 对齐的功能清理:save(CSV 导出)、parse、require、import、call、
    repl(算子形式)、fold/signal、trim-trace、new-trace、dump-trace、timescale、
    assert-eq、set。保留 eval-file(上游核心文件加载)、reval/@、groups/scopes、宏系统、
    谓词、print/printf、timeframe、for/list 等上游核心与波形核心算子。
    替代:assert-eq 用脚本 (if ... (exit 1));count/step→count;find/step→find;
    import/require→eval-file;fold/signal→find + map/sum 组合。

Changed

  • fmt-time 更名为 beat:(beat t) 返回人类可读时间串;(beat t "clk") 返回整数拍号
    (首个上升沿 = 第 0 拍,首沿之前 = -1)。旧名 fmt-time 不再兼容(调用报未知算子)。
  • 拍号显示模式 WAL_BEAT_CLK=<clk[,clk2]>:设置后 at / getwave / wave / edges / search
    的时间输出改为时钟拍号 —— 单时钟输出整数,多时钟每个时钟一对 ("clk名" 拍号)(分开显示、不合并);
    多波形按"实际会读值的那条波形"解析时钟;配置的时钟无法唯一解析或没有上升沿时明确报错并整体回退
    到绝对时间;首个上升沿之前显示 -1(首次出现时给一行提示)。

Removed

  • save 算子(CSV 导出):移除无人使用的波形 CSV 导出能力;需要导出的场景请用其他工具。

Added

  • 波形指标与统计算子(延迟/吞吐/分布): median / percentile / stddev / stats /
    histogram(纯数值列表)与 latency / ipc(波形侧配对)。
    (stats (latency (rising "req") (rising "ack"))) 这种组合就是"握手延迟分布"的完整答案。
    语义写死在 docs/waveform-metrics.md:latency 用原生时间单位、默认 FIFO 配对
    (#restart 让新 start 作废未配对的旧 start)、配不上的两端丢弃、边沿口径与查询引擎一致
    (x→1 是 changes 不是 rising);两个波形算子只在时间域取变更列, 不建索引空间 ——
    千万时间戳的大波形上不会触发"全文件物化时间线"。闸:tests/metrics_test.rs(手算期望值)。
  • FSDB 时间线的并行/集群预计算: 新增两个正式子命令 ——
    wal-rust fsdb-timeline-map <file> <shard> <shards> <out.part>(算一片)与
    wal-rust fsdb-timeline-merge <file> <part>...(归并 → 安装 .ftl)。
    集群上用 scripts/lsf_fsdb_prewarm.sh <file.fsdb> [shards] 一条命令提交/等待/归并
    (bsub -n 1 × N, 无 LSF 时 --local 本机并发, --dry-run 只打印提交命令)。
    WAL_FSDB_TL_JOBS 支持 auto(= min(额度, 8))。
    归并产物与单进程写出的 .ftl 逐字节一致(单测 + 真机 cmp 双重验证), 分片怎么切、
    归并顺序如何都不影响结果。
  • bsub -n N + stdin 会话: scripts/lsf_wal_run.sh <wave> <probes.wal> [slots]
    把 wal-rust --stdin -l wave < probes.wal(一次加载、多探针)提交成 bsub -n N
    (--queue/--wall/--wait/--dry-run, 默认加 -R "span[hosts=1]")。
  • -j N|auto / --jobs: 一个波形的并行度(默认 auto, 不需要 LSF 也能用 —— 单机就是多核)。
    默认 = min(可用额度, 8), 额度优先取 bsub -n 分配的 slot 数, 否则核数;
    小波形自动退回单进程(WAL_FSDB_TL_MIN_MB 默认 32MB, 或信号数 ≥ 16384), 因为每个
    worker 各有一次 NPI 初始化开销;-j 1 强制单进程, 显式数字一律照办。VCD 侧同步按该数建
    线程池。实测(200 万时间戳夹具, 冷缓存): 默认(小文件)39.1s / -j 8 21.0s。
  • scripts/bench_fsdb.sh(make bench-fsdb FSDB=x.fsdb [SIG=tb.clk]): FSDB 查询基准,
    冷建/暖查询/只加载分开计时并追加到 bench/perf-history.csv; CI perf 阶段在设了
    WAL_FSDB_BENCH=<file.fsdb> 时自动跑(判据: 暖查询应接近"只加载")。

Changed

  • 大波形的并行冷建不再需要人工配环境变量: 波形文件 ≥ WAL_FSDB_WALK_SCAN_MB(默认 128MB)时,
    每个 fsdb-timeline-map worker 自动启用"边走边扫"(WAL_FSDB_WALK_SCAN=1), 并在多分片下
    自动选切分层(WAL_FSDB_SCOPE_SPLIT 留空/auto): 在"子树数 ≥ 分片数"的层里取每 worker
    认领的子树数最接近 256
    (WAL_FSDB_SCOPE_TARGET_PER_WORKER)的那层。于是直接
    make fsdb-prewarm FSDB=big.fsdb SHARDS=8 LOCAL=1 就是内存安全且接近最优的那条路 ——
    以前必须自己 export WAL_FSDB_WALK_SCAN=1 WAL_FSDB_SCOPE_SPLIT=5, 忘了就会让 8 个 worker
    各走整棵树。小文件行为不变;想回到旧口径: WAL_FSDB_WALK_SCAN=0、
    WAL_FSDB_SCOPE_SPLIT=0|off, 显式数字仍然照办(想固定层做 A/B 就用它)。
    • 甜点 256 是真实波形上量出来的(321MB / 1796 万信号, 同机同天, 端到端
      make fsdb-prewarm SHARDS=8 LOCAL=1): depth4(42 棵/worker) 668s、
      depth5(265 棵) 636s、depth8(4595 棵) 760s。depth8 的信号数其实是三档里
      最均衡的(每片恰好 ≈12.3%, 即"完美平衡"), 但每 worker 要认领 4595 棵树 ——
      真正决定耗时的是变更密度(时钟类信号每条 13 万次变化, 逻辑信号常常几次),
      均匀切信号数不等于均匀切工作量。所以选层用"目标棵数"而不是"按信号数算均衡度"。
    • 统计"每层多少棵子树、每棵多大"要一次只数数的树遍历(这份 1796 万信号波形 ~44s,
      NPI 驻留 ~10GB): 8 路并发走这一遍会 OOM —— 首版实测 8 个 worker 同时统计时 NPI 直接
      SIGSEGV([fhdb][fatal] Can not get user data 刷屏)。现在用 flock 串行化:
      第一个 worker 走一遍并把结果写进 <cache>/<file_identity>-v1.fscope
      (魔术字 WSCP2 + 每层子树数与每棵子树大小, 原子 rename), 其余 worker 在锁上等 ~44s 后
      直接命中, 之后的每次运行 0 代价。缓存目录不可写时不猜也不走树, 直接按最深一层分片
      (子树最小 = 每 worker 最省内存; 而"不切分"意味着每个 worker 走整棵树)。
      自动选中的层 WAL_DEBUG_FSDB=1 会打印。闸: 单测比对选层规则、缓存往返(含文件身份失效)。
    • 归并产物与分片口径无关: depth4 / depth5 / depth8 三条口径的 .ftl 都是
      md5 ca1cb095…(320,204 个时间点, 460,014 B) —— 自动选层换了口径也不会动产物。

Performance

  • FSDB 加载: 名字索引的哈希改为并行计算, 索引段 5.2s → ≈1.0s(真波形实测)。
    把加载拆开看(WAL_DEBUG_FSDB=1 的分段时戳, 336MB / 1796 万信号):

    阶段 之前 现在 说明
    NPI init+open(+文件属性) 4.4s 4.4s NPI 自己的账, 每个进程一次
    名字就位(.fnames 解出 17.96M 个名字) 4.7~6.2s 4.7~6.2s 未改动;区间来自页缓存冷热
    名字索引建完(哈希 → 下标) 5.20s 0.94~1.34s 2.85GB 名字的 FNV 哈希改 rayon 并行(插表仍是随机写, 不并行)
    合计 ≈15.8s ≈10.5s --stdin 一次加载;之后每个探针 ≈0
    • 索引段是相邻两次会话测的(5.20s → 0.94s / 1.34s), 同机同文件;
      整段墙钟受页缓存影响会在 10.5s ~ 14.8s 之间跳(同一二进制), 比数字前先看机器状态。
    • 两个负结果(都实测过、都没有采用, 记下来免得下次再试):
      ① 逐名 from_utf8 校验换成 unchecked 只从 4.69s 变 4.84s(噪声级);
      ② .fnames 改 mmap + decode_tree_into 就地解码, 相邻两次 4.70s vs 4.69s —— 收益在噪声里,
      却多一个"缓存文件被并发截断 → SIGBUS"的风险, 所以保持流式解码。
    • 名字解码剩下的 ~4.7s 要靠缓存格式 v3(偏移表 → 并行解码 / 零拷贝 arena)才能再压;
      那是我们自己的格式, 不需要动 FSDB。
  • 大波形时间线: 按 scope 子树的多进程并行(以及一个靠"三种分片对拍"抓到的真 bug)。
    WAL_FSDB_SCOPE_SPLIT=<depth> 让每个 worker 只走自己那几棵子树 —— NPI 遍历期内存随子树
    下降(实测每 worker 2.8~3.9GB, 而单 walker 是 ~12GB), 于是 8 路并行在这台 27GB 机器上
    可行。选层靠一次标定遍历(WAL_FSDB_SCOPE_STATS=<depth>): 这份 core 级设计 depth1/2 都只有
    1 个子树(切了等于没切), depth3 = 7 棵, depth4 = 334 棵(最大 13.7%)。

    • ⚠️ 抓到的 bug: 用了 scope 分片后我仍然按"信号下标 % N"过滤信号, 两套分片口径叠加
      导致每个 worker 丢掉自己子树里 7/8 的信号 —— 表现是"三条分片合并出来的时间线并集少了
      43 个时间点"。是"不同分片口径必须产出同一并集"这条对拍(而不是单测)抓到的, 已修:
      scope 分片时信号级轮转自动关闭。
    • 实测(1796 万信号真波形): depth5/8 片 494s、depth4/8 片 570s(单 walker 外推 2700s),
      每 worker 4
      8GB; 合并后 .ftl 装好, 暖查询 11.4s / 6.35GB(之前 20 分钟跑不完的那条)。
    • 正确性: depth3/7、depth4/8、depth5/8 三种独立分片口径的并集逐点相同(320,204 个时间点)。
  • 大波形的时间线冷建换路: "边走边扫"。常规路径在这类波形上要么先按名字把句柄一个个
    解析出来(实测 550µs/个 → 18M 信号 ≈ 2.75 小时), 要么把 18M 句柄全攒着(NPI 遍历期
    自己涨到 ~10GB)。新路径"走到一批信号就扫一批、扫完丢句柄"(timeline_by_walk_split):
    不建名字表、不攒句柄数组, 峰值内存与信号总数解耦。

    • 信号数 ≥ WAL_FSDB_WALK_SCAN_MIN(默认 2,000,000)自动启用, WAL_FSDB_WALK_SCAN=0 关闭;
    • 产物与常规 worker 逐字节相同(cal1m 上 cmp 验证);
    • 1796 万信号真波形实测: 1/8 分片(约 224 万信号)369s / 11.9GB, 产出 318,809 个时间点
      —— 单 walker 全量按此线性外推 ~45 分钟(每变更记录 ~1.45µs 是 NPI 的硬成本, 换路只
      免掉了"按名字解析 18M 次句柄"的那两小时, 并没有免掉逐条扫描);
    • 另支持按 scope 子树分片(WAL_FSDB_SCOPE_SPLIT=<depth>)以便多进程并行时内存随
      子树大小下降; 这份设计只有一个顶层 scope 切不动, 留给别的设计。
  • 真波形的时间线冷建: 代价量化 + "只取句柄"的 worker。在 1796 万信号 / 4377 万时间戳的
    core 级波形上把"整文件过一遍"拆开量: iter.start() 装载 ≈0.2µs/条、iter.next() 逐条
    ≈1.25µs/条 → ≈1.45µs / 变更记录(代价跟"记录条数"走, 不跟信号数走 —— 时钟类信号
    独占大头, 单个 adapter clk 就 130,590 次变化)。块大小有甜点(65536 最好, 4096 慢 35%,
    262144 更慢), iter_next(time&) 单参数重载不提速(开销在 NPI 内部逐条处理)。
    暖路径的句柄解析是致命项: .fnames 命中时句柄按名字懒解析, 实测 550µs/信号
    (18M 信号 ≈ 2.75 小时) → 新增 WAL_FSDB_HANDLES_ONLY=1(时间线 worker 默认开):
    跳过名字 arena/索引/scope, 走树只留句柄, handle_of 归零, 代价变成一次树遍历(~41s)。
    WAL_DEBUG_FSDB=1 多了"时间线扫描剖析"一行(handle_of / add / start / next×N / 时间点),
    下一轮的优化目标(按 scope 边走边扫 / 直接读 FSDB 全局时间表)在 bench/RESULTS.md 里记着。

  • 真实 core 级波形(321MB / 1796 万信号 / 162 万 scope): 加载内存砍半、名字表不再物化。
    实测(本机原生读, VCS X-2025.06-SP2 写的文件): 冷加载 66.9s/17.8GB → 52.9s/13.6GB;
    暖加载 13.5s/11.0GB → 10.1s/6.35GB;(length (SIGNALS)) 11.3GB → 6.35GB。三处改动:
    ① .fnames 缓存升 v2: 定长 48B header 带"信号数 / 名字总字节 / scope 数 / scope 总字节",
    读侧一次精确 reserve(老口径按 n*32 猜 + 翻倍增长: 2.85GB 名字字节会涨到 4.6GB 容量,
    最后一次扩容旧新两份同时驻留 ≈7GB);
    ② 冷路径边遍历边流式写 .fnames: 遍历期间内存里不攒 arena, 走完按精确容量解码回来;
    顺带把"先拼 3.2GB Vec 再落盘"改成流式(指纹 seek 回填)。缓存不可写或流式失败 → 自动
    回退内存 arena(重走一遍树), 绝不影响"能不能读波形";
    ③ (length (SIGNALS)) 不再物化整表: 新增 Trace::signal_count()/signal_at()(FSDB/VCD
    都是 O(1)/O(名长)), 求值器给 (length (SIGNALS)) 加快路, CLI sigs 按下标懒遍历 ——
    1796 万信号上少背一张 ≈4.8GB 的 Vec<String>。(SIGNALS) 整表语义不变。
    WAL_DEBUG_FSDB=1 现在按 open 后 / 名字就位 / 索引建完三段打印 RSS, 便于定位内存大头。

  • FSDB 时间线冷建 @ 400 万信号: 112s → 14.2s(单进程) / 69.6s → 12.1s(8 路)。
    病根不是"把数据过一遍", 而是 npiFsdbTimeBasedVcIter::start() 的每块固定开销
    100140ms
    (与块内信号数、文件数据量都无关: 19 信号/200 万时间戳夹具上 18 块比 1 块
    多 2.45s;4M 信号夹具上 977 块比 16 块多 98s) —— 400 万信号按老的 4096/块切 = 977 次
    start = 100s 纯开销
    。现在默认块大小随信号数放大 clamp(signals/64, 4096, 65536)
    (总块数 ≈64 封顶;并行 worker 也按文件总信号数定块, 否则每片 50 万信号又变 122 块),
    WAL_FSDB_CHUNK 仍可显式覆盖做 A/B。峰值 RSS 不变(1.5~2.0GB)。

  • 时间线 .ftl 的落盘判据不再只看点数: FSDB 冷建代价 ≈ 信号数 × 每信号开销(~3.5µs),
    与时间点数几乎无关 —— "400 万信号 / 200 个时间点"点数 <256 曾因此每个新进程都重建一次
    (75.6s/次, hit 与 cold 一样慢)。现在"本次建了 ≥150ms"也算数(并行/单进程共用同一
    判据), 暖查询 75.6s → 4.9s(15.6×);电平计数冷查询 75.6s → 21.2s。数字与复现记在
    bench/RESULTS.md。

  • 4M 信号的"名字路径"实测与两处修补: 加了离线基准
    cargo test --release --lib -- --ignored --nocapture fsdb_name_path_4m(不需要波形文件,
    直接造 400 万名字走 encode/decode/建索引/叶子排序), 一跑就露出两个问题:
    ① 叶子名排序 3.5s: 比较器里现算 rsplitn('.') → 每个名字被重复扫描 O(log N) 次;
    改成"先一遍预计算叶子 (偏移,长度), 排序只比字节切片"后 0.36s(9.8×);
    ② .fnames 缓存要额外背 207MB: 改成从文件流式解码进 arena(decode_tree_file),
    多花 ~70ms 换掉 207MB 峰值; 截断/损坏仍当未命中回退走 NPI 树(真波形上验过)。
    4M 信号名字路径现状: encode 56ms → 207MB; 流式 decode 127ms; 建索引 558ms; 叶子排序 360ms;
    内存 arena 199MB + spans 30MB + 索引 96MB + 叶子序 15MB ≈ 340MB(改动前 ≈1.1GB)。
    数字与复现命令记在 bench/RESULTS.md。

  • FSDB 名字存储改 arena + 开放寻址索引(4M 信号级的头号开销): 改动前同一份名字在
    进程里存了四遍(Sig.name 叶子名 / Sig.full 全名 / sig_names[] / HashMap<String,_>
    的键), 微基准口径 280B/信号 → 4M 信号 ≈ 1.1GB;现在名字进连续 arena(每信号只多
    8B 的 (偏移,长度))、索引只存 64 位哈希 + 下标, 73B/信号 → 4M 信号 ≈ 0.3GB(省 74%)。
    读/写 .fnames 缓存也改成直接对 arena 编解码, 省掉 4M 信号下两次几百 MB 的瞬时峰值。
    闸: trace::name_store::per_signal_bytes_stay_small(同时打印新旧口径)。

  • 批处理里按申请的 slot 自动并行冷建: bsub -n N 会导出 LSB_DJOB_NUMPROC, wal-rust
    现在按它(其次 LSB_MCPU_HOSTS, 再其次核数)决定时间线 worker 数(封顶 8), 不用再手设
    WAL_FSDB_TL_JOBS;只在检测到批处理变量时才这样(...

Read more

v0.14.26

Choose a tag to compare

@hesheng01 hesheng01 released this 21 Sep 07:23

Performance

  • 名字解析不再每次求值克隆整张名字表(188 万信号 FSDB 上的致命项)。裸符号求值走
    "自动解析信号名", 它调用 traces.signals(), 而 FsdbTrace::signals() 返回
    sig_names.clone() —— 统一引擎在每个边界都重新求值条件, 于是 O(N)×边界数:
    现场表现为"get 名字解析慢到 3 分钟不出结果"。改为调用后端 resolve_name
    (索引式 + 缓存)。实测(200k 信号 VCD, 5 个裸符号的 || 条件):
    逐拍 117.3s → 8.2s(14×), 引擎路径 0.27s → 0.06s, 结果一致。

  • FSDB 短名解析加叶子名排序索引(leaf_order, 只存 u32, O(log N) 查找, 首次用时懒建):
    此前每个不同拼写的短名都要线性扫全部信号名(188 万 → 几十~几百毫秒/次)。

  • scripts/fsdb_vcd_quickcheck.sh <fsdb> <vcd> [sig…]: 一分钟内回答"两份波形是不是同一份仿真"
    —— ① 信号集(数量/同名交集/各自独有) ② 索引空间长度 ③ 典型信号的边沿/电平/变更计数,
    逐项 ✅/❌ 并给出"是不是 fsdb2vcd 匹配问题"的结论。

  • scripts/bench_name_resolution.sh [信号数] [时间戳数]: 名字解析/裸符号求值的可复跑基准
    (引擎 / 逐拍 / 字符串对照三条路径), 专门盯"O(N) 每次求值"回归。

Internal

  • CI 的 perf 阶段接入名字解析基准(>240s 判退化);AGENTS.md 增加硬约束"求值热路径禁止 signals()"。

v0.14.25

Choose a tag to compare

@hesheng01 hesheng01 released this 21 Sep 06:32

Fixed

  • 裸信号符号做电平比较会静默错值: (= clk 1) / (! rst) 这类手册在教的写法被判成
    "不引用信号", 于是常量折叠在索引 0 求值一次套用到全部索引 ——
    (count (= clk 1)) → 20、(count (= clk 0)) → 0、(count (< clk 1)) → 0(真值都是 10)。
    现在裸符号(既不是变量、又能被已加载波形解析)一律算作信号引用, 引擎与纯逐拍对拍一致;
    变量条件((= x 1))的常量折叠不受影响。回归: matrix_bare_signal_symbols_count_correctly。
  • wal-rust run -c <表达式> 不再要求同时给 <FILE>(给了 FILE 时 -c 优先);
    两个都不给时报错并给出用法(退出码 2)。
  • --help 里 "125 named operators" 更正为 146(实际注册数), 并加单元测试守门:
    帮助文案与注册表不一致就红。
  • 文档门禁的测试数口径改为 cargo 口径(2×单元 + 集成), 不再把 295 误报成 223。
  • cargo build --release 零告警(此前 37 条): 清掉未用 import/赋值与死代码,
    旧的手写 FST 读器(src/fst/reader.rs, 查询路径已改用 wellen)整体标注 #![allow(dead_code)]
    并说明保留原因, 不再淹没真实告警。

Internal

  • scripts/release.sh: ssh 推送失败时回退到 gh 的 HTTPS 凭据, 并刷新 origin/main 跟踪引用。

v0.14.21

Choose a tag to compare

@hesheng01 hesheng01 released this 21 Sep 04:08

Fixed

  • CLI 一次性表达式里"多顶层形式"被当成函数调用(静默错值): parse_expr 把程序交给
    eval_list 时, 若首元素求值成 Closure/Macro 就走 IIFE 分支、把其余顶层形式当作实参 ——
    (define add5 ((fn (n) (fn (x) (+ x n))) 5)) (add5 3) 答 13(应为 8);
    defun 返回闭包报 Arity error;(twice (print "hi")) 打印 4 次(应 2 次);
    macroexpand 会连带求值。现在多顶层形式显式包成 (list ...), 按书写顺序求值。
    (脚本模式与 --stdin 逐条求值本来就不受影响, 所以只在"命令行一把梭"时踩到。)
    回归: matrix_cli_multiform_program_forms。
  • 词法: 1e3 / 1.5e3 / 1.5E-3 等科学计数法现在被识别(此前拆成 1 + 符号 e3,
    报 "Undefined symbol: e3");#timeout(合法分组符号 #name)不再被拆成 #t + imeout
    (此前报 "Undefined symbol: imeout"), 找不到组时给明确语义错误。
    回归: matrix_lexer_scientific_and_sharp_symbols。
  • 变参宏(defmacro/defunm 单个符号作参数表)只绑到第一个实参: 例如
    (defunm m args (length args)) (m 1 2 3) 报 length expects list or string(应为 3)。
    根因是构造宏对象时漏置 variadic 标志;顺带修掉 defunm 把 body 多包一层列表的问题
    ((defunm m args (length args)) 曾返回 (3) 而不是 3)。
    回归: matrix_variadic_macros_bind_all_args。
  • (sample-at s idx) 浮点索引不再静默截断: (sample-at s 4.5) 曾取索引 4 的值, 现在明确报错
    (整数除法用 (div a b))。回归: matrix_sample_at_rejects_float_index。

Changed

  • test_samples/verify_vcd.wal 从"只打印不断言"改为断言式自检: 9 项检查, 任一不成立即退出码 1。
  • tests/fsdb_diff.rs 的两个 Verdi 门改为 #[ignore = "需要 Verdi/NPI…"]: 没 Verdi 时如实显示
    ignored 而不是"5 passed"(以前是静默 return, 造成门禁跑过的假象);有样本时
    make gates 会自动 --include-ignored 真跑。

Added

  • (下一次发版前在这里写;分类见文件头)

v0.14.17

Choose a tag to compare

@hesheng01 hesheng01 released this 20 Sep 14:12

Added

  • 工程外壳: LICENSE(MIT/Apache-2.0)、CHANGELOG、CONTRIBUTING、SECURITY、issue/PR 模板、
    rust-toolchain.toml、.editorconfig、.gitattributes。
  • 本地 CI: make ci(scripts/ci.sh)—— 环境自检 / 文档一致性 / fmt / clippy / build / test /
    语义冻结闸 / 打包冒烟 / 性能冒烟, 本机与 GitHub Actions 跑同一份脚本;失败的阶段会给出日志路径与复跑命令。
  • 文档一致性检查(python3 scripts/check_docs.py, CI 的 docs 阶段): 本地路径引用是否还存在、
    docs/README.md 索引是否收录全部文档、文档里声称的测试数是否与实际一致、面向当前用户的文档是否还在讲旧版本。
  • 发版脚本 scripts/release.sh(make release VERSION=x.y.z): 校验工作区/分支/tag/CHANGELOG →
    跑本地 CI → glibc 2.17 交叉构建 → 推送 → 创建 release;make release-dry 可演练。
  • CI 徽章与文档地图: README 重写为项目门面(安装/上手/速查/口径/架构/性能),docs/README.md 作为文档唯一入口。
  • 历史归档目录 docs/history/ 与"历史文档不追改"的约定(带横幅的文档, 其过时路径由 CI 降级为提示)。

Fixed

  • (slice x start end) 在 start >= end 时崩溃: (slice (list 0 1 2 3 4 5 6 7) 3 0) 直接
    panic(slice index starts at 3 but ends at 0);字符串分支还会错取((slice "hello" 3 1) → "lo")。
    现在按空区间返回 ()/""。回归: matrix_slice_reversed_range_is_empty。
  • 含 % 的源码里中文被双重编码(mojibake): % 归一化(% → mod )的实现逐字节
    push(b as char),把 UTF-8 的多字节序列映射成 Latin-1 —— 于是 (printf "信号: %s\n" 42)
    打印 ä¿¡å·: 42,而不带 % 的中文正常(所以长期没被发现)。现在按字节切片拷贝原串。
    回归: matrix_percent_normalize_keeps_utf8(同时冻结 (% a b) ≡ (mod a b) 与 %% 行为)。
  • 多文件/缓存/打包相关的三处修复见 [0.14.8] 与 [0.14.9]。

Changed

  • Cargo.lock 纳入版本控制(二进制项目需要可复现构建)。
  • 仓库根目录清理: 散落的实验脚本归位(examples/wal/、bench/、test_samples/),
    删掉无人引用的 verify.sh(旧的工程结构检查, 已被 make ci 取代)、
    误命名的 analysis(内容其实是个 VCD 夹具)、以及已废弃的 C++ 垫片
    src/trace/fsdb_shim/(404 行, 纯 Rust FFI 取代后无人引用;垫片源码见历史提交 b993d8c)。
  • test_samples/ 重写为真正能跑的脚本: 旧入口引用了两个不存在的 .wal 与不存在的
    test_data/, 必然失败;现在自包含脚本直接跑, 需要波形的脚本用 -l/WAVE= 提供。

Docs

  • 全量文档审计(93 条: 断链 15 / 版本过时 8 / 与实现不符 31 / 已完成却写成 TODO 8 / 自相矛盾 15 /
    重复 6 / 结构 10)并逐条修复: 见 docs/README.md 的状态约定与 CHANGELOG 下方各版本条目。
  • 重点纠正的事实错误: 0 是假值(README 原写"0 为真")、多文件同名信号先 -l 的为准
    (README 原写"以后加载的为准")、count/find 是逐索引语义(迁移文档原写"变化点采样")、
    FSDB 自 0.14.x 起已支持(复盘文档仍写"被拒绝")、TS 返回的是 INDEX 而非时间戳、
    手册里 22 个"标准库宏"其实未随 wal-rust 发布(std/ 不存在)、(signals) 等小写形式不存在(只认大写)。
  • docs/README.md: 10 篇文档的索引(性质/状态/读者);新增文档必须登记。
  • 手册 MOC 修正(补 8.3、锚点错位)、convert 从"现存操作符"移除、&&/|| 返回值更正为 true/false。

v0.14.9 — 相对路径 FSDB 也落缓存

Choose a tag to compare

@hesheng01 hesheng01 released this 17 Sep 07:05

修复: 相对路径加载 FSDB 不写缓存(每次查询重扫全文件)

NPI 沙箱会把 CWD 切到 <cache>/npi/ 下, 而缓存 key 需要 stat 波形文件本身。
FsdbTrace::load 之前只把绝对路径喂给 NPI, 自己存的仍是用户给的相对路径 ——
沙箱里 stat 不到 → cache_path() 一律返回 None → 一个缓存文件都不写:
用 -l design.fsdb(最常见的写法)时, 每次查询都要重付一遍全文件扫描
(全局时间线 = 所有信号变更时间的并集), 大 FSDB 上是分钟级。

现在 trace 内统一记绝对路径(canonicalize 失败才退回原样), NPI open 与缓存 key
用同一个路径。VM 实测: 修复前缓存目录为空, 修复后 .fnames 落盘。

新增回归 tests/fsdb_diff.rs::fsdb_cache_written_for_relative_path(需 Verdi 环境,
没 Verdi 自动跳过)。

建议升级到本版后再做一次同前的对照测量(VCD 与 FSDB 请都用相对路径与绝对路径各跑一遍)。

v0.14.8 — 多文件选源/索引空间、缓存 key、SIGXFSZ

Choose a tag to compare

@hesheng01 hesheng01 released this 17 Sep 06:57

修复: 多文件加载、缓存陈旧命中、缓存写超限

1. 多文件同时加载: 选源确定化 + 索引空间收口

  • 选源随机 —— TraceContainer 原用 HashMap 存 trace, 每个进程迭代顺序不同:
    两条波形都有同名信号时(同一设计导出两份是常态), 同一条命令会在两条波形之间
    随机挑一条,结果与耗时都不可复现。现在按加载顺序迭代(order: Vec<TraceId>):
    先 -l 的先算。同时禁止跨波形合并索引集合(索引是各自的变更排名),
    取值/取索引路径统一 first-match。
  • 索引空间被无关波形污染 —— 时间优先后端(FSDB)的 max_index 等于一次全文件扫描
    (全局时间线 = 所有信号变更时间的并集), 而统一引擎原先对所有已加载 trace 取
    max_index 最大值。现在索引空间只由实际会读值的波形决定; 不引用信号的查询
    (常量条件/INDEX/TS)取主波形(第一条 -l)。逐拍回退与统一引擎同一规则,
    INDEX/TS 读"正在被推进的那条 trace"。

2. 缓存 key 加 ctime + inode(陈旧命中)

原 key = basename+size+mtime, 内容指纹只覆盖首尾 64KB —— 反复生成同名波形时
"同一秒内等长改写"会让 size/mtime 都不变, 中段改写又躲过指纹, 热查询直接返回旧列。
现在统一用 file_identity(basename+len+mtime+ctime+inode); 首尾指纹保留作第二道防线。
.wcol/.cols(VCD)与 .fnames/.ftl(FSDB)一致。

3. 缓存写超限不再杀进程

ulimit -f / 磁盘满时写缓存会收到 SIGXFSZ(默认 terminate + core, rc=153)。
现在启动即忽略该信号, 写失败降级为"不写缓存"并只提示一次, 结果与退出码不受影响。

验证

  • 单文件语义逐条不变: scripts/diff_find.sh 门 ALL MATCH; 矩阵 51 项全绿。
  • 新增回归: matrix_multitrace_source_is_load_order、
    matrix_multitrace_index_space_follows_query、
    matrix_sidecar_stale_content_same_size_mtime、
    matrix_cache_write_over_limit_degrades(后两个已验证"去掉修复即失败")。

二进制要求 glibc ≥ 2.17(CentOS 7 / RHEL 7 / Ubuntu 16.04+)。

v0.14.7 — FSDB 直读(Verdi NPI)+ 性能优化

Choose a tag to compare

@hesheng01 hesheng01 released this 17 Sep 02:08

FSDB 直读(借 Verdi NPI)+ 一轮系统性的性能优化

不逆向 FSDB、不做格式转换:运行期 dlopen 正版 Verdi 的 NPI 读库 libNPI.so,
纯 Rust FFI(Itanium mangled 符号),构建期不依赖 Verdi,缺库时明确报错并保持
VCD/FST 通路完全不受影响。本版把 FSDB 通路从"能读"做到了"好用"。

新增

  • -l x.fsdb 直接查询(count/find/getwave/at/initial/sigs/topsig …),
    与 VCD/FST 后端同一套语义与同一套引擎。
  • 语义与 VCD 逐条对齐:规则 A(t0 初值快照不算 INDEX)、同索引最后写入胜出、
    首变化前取初值;Changed 在索引 0 的"无前驱"特例也精确复刻。
  • 名字树/全局时间线落盘缓存(.wal-rust-cache/*.fnames、*.ftl,原子写、指纹校验),
    跨进程复用。
  • WAL_FSDB_TL_JOBS=N:冷构建全局时间线时用 N 个 worker 并行(轮转分片)。
    ⚠️ 每个 worker 各占一个 Verdi 许可。

性能(内网 174MB FSDB 实测)

查询 旧 本版
(count (rising clk)) >300s 超时 / 17GB 1.4s
(count (= (get tvalid) 1)) — 0.27s
(count (changes tdata_i)) — 0.25s
(count (is-x tdata_i)) 394s / 4GB 0.25s / 126MB
冷建全局时间线 400s 175s(TL_JOBS=4)

热查询(缓存命中)全部亚秒~1.5s;边沿/初值/getwave/at 这类查询只读被查询的信号。

修复

  • VCD 别名:同一个 idcode 在多个 scope 被引用 = 同一个 net —— 修前
    (initial 别名) 丢初值、(count (changes 别名)) 少算、topsig 里别名消失。
  • 缓存路径曾被 NPI 的 chdir 沙箱吃掉(文件"写了却不见了")。
  • 回归矩阵的一个测试竞态(并行测试改 WAL_CACHE* 进程级 env)。

验证

  • FSDB↔VCD 同源差分门(tests/fsdb_diff.rs,环境变量开启):179 信号 × 406 索引全等。
  • 内网全算子对拍(边沿/变化/x/电平/getwave):零分歧(820965 / 11793 / 1060269 / 846848 …)。
  • 宿主 cargo test 14 个目标全绿;缓存编解码/分片覆盖有专门单测。

二进制

wal-rust(x86_64,glibc ≥ 2.17;CentOS 7 / RHEL 7 / Ubuntu 16.04+ 可直接跑)。
FSDB 需要目标机装有 Verdi:export VERDI_HOME=/path/to/verdi 即可(不必手工设
LD_LIBRARY_PATH);许可在 npi_fsdb_open 时 checkout。

v0.13.4

Choose a tag to compare

@hesheng01 hesheng01 released this 11 Sep 07:18

v0.13.4 — 内测 §13.1 落地:确认"样本 vs 初值"口径 + 修 (at s T) 回退 + 新增 (initial s)

内测第四轮报告把这条标为"唯一可能需要与 wal 开发确认设计意图的项"。结论:口径本身是对的,但底下藏着一个真 bug。

1. 口径确认(已写进权威文档 docs/4-state-semantics.md §0.1)

样本(变更点)= # 段的值行;$dumpvars 快照不是样本,而是"索引 0 之前的持值"。

波形形态 (get s)@索引0 (getwave s) (initial s)
只有 $dumpvars、之后从不变 快照值 空 快照值
$dumpvars + 第一个时间戳又写了 s 那次写入(last-write-wins) 那次写入 快照值
第一个时间戳晚于 0、s 更晚才变 第一个时间戳的值 那次变化 快照值
没有初值条目 x 按变化 x

所以"只有初值、不再变化 → getwave 为空"是预期,不是丢数据;t0 状态用 (get s)/(at s 0)/(initial s) 读。内测"a_valid@0=0 是首变化巧合"的修正也成立。

2. 实体 bug:(at s T) 在首变化之前取错了值

回退分支读的是 signal_value(sig, 0) —— 那是**索引 0(第一个时间戳)**的值,而非 t0 快照。首时间戳 >0 时索引 0 属于那个时间戳:

夹具: $dumpvars 写 s=10, 唯一时间戳 #1000 写 s=3
修前:  (at s 0) = (0 3)      (at s 500) = (0 3)
修后:  (at s 0) = (0 10)     (at s 500) = (0 10)     (at s 1000) = (1000 3)

首时间戳正好是 0 的波形上该 bug 不可见,所以一直没暴露。

3. 新算子 (initial "sig")

直接给 $dumpvars 快照原值(含 x/z;没有初值条目 → x),与"索引 0 的值"区分开 —— 内测在索引 0 看到 x 时无法判断是"没有快照"还是"快照就是 x",现在可以判了。Trace trait 增 initial_value(VCD 走紧凑初值存储;FST 无 dumpvars 概念 → x,与 §0 口径一致)。

门禁

矩阵 45/45(新增 matrix_dumpvars_sample_model)、全量测试四套、fuzz 三闸(N=120)、diff_find ALL MATCH。

二进制为 glibc ≥ 2.17 构建(CentOS 7 / RHEL 7 / Ubuntu 16.04+ 可用)。

v0.13.3

Choose a tag to compare

@hesheng01 hesheng01 released this 11 Sep 03:54

v0.13.3 — 内测报告 §9.5 缺口修复:退出码可判 + B10 + 语法糖 + 位宽/溢出

1. 退出码(报告里唯一"不可用"级)—— 现在 CI 可判

  • 脚本错误 / assert-eq 失败 → 退出码 1(默认仍"遇错继续执行", 后续行照跑, 末尾打印 wal-rust: N error(s), M assertion failure(s) in <script>);
  • --halt-on-error → 第一处错误即停, 退出码 1;
  • (exit N) → 以前在脚本里完全不生效(脚本继续跑且 rc=0), 表达式模式还会打印 error: exit:0 并 rc=1; 现在三种模式都立刻停止并返回 N;
  • --stdin 会话: 有探针报错/断言失败 → 退出码 1, 结果照旧按序打到 stdout, 不打断会话;
  • REPL 不受影响。

2. B10 round-trip 丢初值(根因在读者)

$dumpvars 快照扫描按"试 ID 长度 + 要求 ID 前是空格"推断, 于是未分隔的向量行 b1010s1(自家 writer 与 VCS/Icarus 都会产出)全被拒 → 宽>1 的纯初值信号读回来变 x。改为与主扫描共用同一套拆分规则(空格/制表/无分隔/CRLF)+ 哈希后字节复核。.fst 输出被拒是既定契约(本次只订正 --help 里含糊的措辞)。

3. 文档承诺的 #name / ~scope / expr@offset 其实是坏的

expr_from_node 的 "symbol" 分支直接返回原文, 把 symbol = choice(base_symbol, scoped_symbol, grouped_symbol) 压平, 后三个分支永远不可达; @ 也没进 is_anon_token。现在 #clk ≡ (resolve-group 'clk)、~top ≡ (in-scope top)、x@1 ≡ (rel_eval x 1)(旧版 (in-group "top." #clk) 报 Undefined symbol: #clk)。

4. 宽向量静默截断 + i64 溢出

  • 干净向量先看有效位长度: >63 位 → 返回位串, 不再静默丢高位(1024-bit 只置 MSB 的信号以前读出来是 0, (= (get s) 0) 为真);≤63 位仍是整数(128bit 信号的小值 255/128 语义不变);
  • + - * div % sum abs 全部 checked:溢出、(div MIN -1) 明确报错, release/debug 行为一致(以前 release 静默回绕成负数);
  • 位串参与 >= 时给出实际位串并指明出路((= ...) 或 (string->int "..."))。

5. 文档/可用性

  • (help) 总览补 exit/assert-eq/defmacro/defunm/macroexpand/gensym 与语法糖;(help <topic>) 未命中时回落 DOCS(以前 (help "defmacro") 说没有、(doc "defmacro") 却有);
  • DOCS 新增 dump-trace/defsig/defmacro/macroexpand/gensym/defunm/exit/e;assert-eq 条目写明退出码;
  • README 新增 Macros 一节(示例已逐条跑过)+ 退出码约定 + find-sig 通配 + 多文件同名取舍;
  • 手册 §1.8 macroexpand 的错例(when 不是宏)已换;
  • find-sig / CLI sigs 支持 *(任意串)?(单字符), 无通配仍是子串(向后兼容), 通配按 *pattern* 子串语义。

门禁

矩阵 44/44(新增 6 项:退出码 7 场景、未分隔 dumpvars、宽信号 round-trip、语法糖、宽位/溢出、find-sig 通配)、fuzz 三闸(N=120)、diff_find ALL MATCH;基线逐值一致(77629 / 92871 / 1168)。

二进制为 glibc ≥ 2.17 构建(CentOS 7 / RHEL 7 / Ubuntu 16.04+ 可用)。