libtsffs.so: incompatibility between Simics 6/7

[Wenzel]

Build for Simics 6.0.185
Run Simics 7.70.0

Failed to load module 'tsffs' ('/home/mtarral/simics/simics-tsffs-6.1.7/linux64/lib/libtsffs.so'): "/home/mtarral/simics/simics-tsffs-6.1.7/linux64/lib/libtsffs.so: undefined symbol: VT_save_micro_checkpoint"

Build for Simics 7.70.0
Run Simics 6.0.185

Failed to load module 'tsffs' ('/home/mtarral/simics/simics-6.0.185/../simics-tsffs-6.1.7/linux64/lib/libtsffs.so'): "/home/mtarral/simics/simics-6.0.185/../simics-tsffs-6.1.7/linux64/lib/libtsffs.so: undefined symbol: SIM_take_snapshot, version SIMICS_7000"

[Wenzel]

Root cause analysis

libtsffs.so is ABI-locked to the Simics major version it was compiled against. A binary built for Simics 6 cannot load on Simics 7 and vice-versa. The two error messages are the two directions of the same problem:

Built for	Run on	Missing symbol	Why
6.0.185	7.70.0	VT_save_micro_checkpoint	Micro-checkpoint API (from libvtutils.so) was removed in Simics 7
7.70.0	6.0.185	SIM_take_snapshot, version SIMICS_7000	The snapshot API (versioned @SIMICS_7000) does not exist in Simics 6

Why it happens (by construction)

Two layers:

1. build.rs → simics-build-utils (emit_cfg_directives) reads SIMICS_BASE (or ISPM) and emits a cfg like simics_version="6" or simics_version="7".

2. src/lib.rs then compiles one of two mutually exclusive code paths behind that cfg:

   • #[cfg(simics_version = "6")] → save_micro_checkpoint / restore_micro_checkpoint / discard_future → links VT_save_micro_checkpoint etc. from libvtutils.so
   • #[cfg(simics_version = "7")] → save_snapshot / restore_snapshot → links SIM_take_snapshot@SIMICS_7000 from libsimics-common.so

These functions are statically declared extern "C" and resolved at module-load (dlopen) time, so the missing-symbol failure fires before any TSFFS code runs — there is nothing to catch it from inside the module. The entire simics binding crate is compiled per-version this way, not just these two calls.

Is a fix possible?

Yes, depending on scope:

1. By design (no code change). A given libtsffs.so must run on the Simics major version it was built for. Release artifacts are per-version. For most users the answer is: build/run matching versions.

2. Better UX (small, safe fix). The cryptic loader error cannot be trapped inside the module, but it can be guarded earlier: add a base-version check at the Simics-script / loader level (compare the running base version against the version the module was built for, baked in via env!/version_base) and abort with a clear message before load-module tsffs. Low risk; turns a confusing crash into an actionable error.

3. A true universal binary (one .so for both 6 and 7). Technically possible but invasive — not a small fix. It would require:

• Runtime symbol resolution (dlsym(RTLD_DEFAULT, ...)) instead of static linking, calling whichever symbol is non-NULL, so there is no undefined-symbol-at-load.
• Handling symbol versioning (SIM_take_snapshot@SIMICS_7000).
• Compiling both code paths unconditionally and dispatching at runtime — but the two snapshot APIs have incompatible signatures and semantics (micro-checkpoint index + discard_future vs. named snapshots), so both must be carried.
• This fights the whole simics-rs binding design, which is version-locked at build time across the entire crate, not just these calls.

Recommendation

Keep building per-version; implement option 2 (a loud, clear version-mismatch guard) for usability. Option 3 is feasible engineering but a real project with upstream binding implications, only worth it if shipping a single binary across both major versions is a hard requirement.