Verilator VCD/FST gotchas when writing your own waveform reader or converter (Verilator 5.05x)

Lessons from converting Verilator dumps of ~10 open RTL designs (CPUs, crypto cores, an AXI crossbar) to other formats, with a per-signal exact round-trip check:

1. Verilator's VCD strips leading zeros from vector values: a 70-bit signal can appear as b0 " or b1010 ". A reader must left-extend to the declared width per IEEE 1364 (pad with 0 if the first char is 1 or 0, otherwise with x/z). Forgetting this passes on narrow signals and breaks on wide ones. 2. Verilator emits at most one value per signal per timestep, so its dumps contain no same-timestamp glitches. If your format claims to preserve glitches, test that with a hand-written VCD (repeated #t, several changes of one id at one time). libfst's writer does keep same-time changes in order. 3. Name matching between Verilator VCD and Verilator native FST differs for arrays: in the FST, an element can be a var named a[3] inside a scope also named a (VCD: scope.a[3]). 2-D arrays (m[0][1]) need yet another rule. Match by hierarchical name and report unmatched handles, so they don't silently show up as empty signals. 4. Verilator 5.054's --trace-fst (new fstcpp writer) needs lz4.h and -llz4 at C++ build time. If only the runtime library exists (no -devel package, no root), point -CFLAGS at libfst's bundled lz4.h and -LDFLAGS -L at a dir holding a liblz4.so symlink to the system .so.1. 5. Building Verilator from source on a minimal RHEL-like box: make install fails without help2man (a stub that just creates the -o file works), and the verilator wrapper needs perl's FindBin (a 10-line shim in PERL5LIB works if you can't install perl-FindBin). 6. Size dumps by measuring bytes/cycle on a 200k-cycle run, then setting the cycle count; VCD rates ranged from ~130 B/cycle (small RV32I) to ~8 KB/cycle (VeeR EL2, full hierarchy). Check that the program doesn't end the simulation itself first: some SoC firmware calls $finish after its self-tests, so your cycle limit never applies. 7. zstd -T1 still uses an extra I/O thread (~150% CPU). Account for it if you report single-thread compression times. 8. Verify with an independent reader (e.g. a 100-line Python VCD parser, ~1 min/GB) hashing each signal's full raw event list (time + full-width value), not settled values, and compare every converted format against it.