Plugin System

Use this chapter when you need to deploy, validate, or troubleshoot TDSE solver plugins in a packaged environment. Each plugin is a shared library (.so on Linux, .dll on Windows) that the host loads at runtime to execute transient and AC simulations.

If your PoC stays on the default CPU path and you do not need manifest, deployment, or ABI decisions yet, you can defer this chapter until deployment planning. Come here when the question becomes compatibility, routing, signing, or plugin-health evidence.

Use the surrounding boundary chapters with it:

• use Platform Notes for the broader host, package, and qualification boundary
• use Element Reference when the deployment risk is really netlist coverage rather than plugin loading

Architecture

Three simulation engine plugins are provided:

Plugin	Binary name	Solver family
CPU Dense	libtdse_sim_cpu_dense.so	LAPACK, LU
CPU Sparse	libtdse_sim_cpu_sparse.so	KLU, MKL Pardiso
CUDA	libtdse_sim_cuda.so	CUDA dense, CUDA sparse

The host selects the correct plugin automatically based on the requested solver backend. Each plugin exports a standard entry point tdse_plugin_get_info() that returns ABI metadata and a function table.

ABI Version

The plugin ABI is versioned. The current version is 1.1.

The host accepts plugins with the same major version and the same or older minor version. A v1.0 plugin loads on a v1.1 host; a v1.2 plugin is rejected by a v1.1 host.

The ABI contract and compatibility policy are documented in the SDK headers and the Plugin ABI Evolution Guide shipped with the evaluation package.

Deployment Layout

/opt/tdse/
  lib/
    plugins/
      sim/
        libtdse_sim_cpu_dense.so
        libtdse_sim_cpu_sparse.so
        libtdse_sim_cuda.so
        plugin_manifest.json

Plugins and their manifest must live together in the plugins/sim/ directory. Do not rearrange or flatten this layout.

Plugin Manifest

The manifest (plugin_manifest.json) maps logical plugin names to on-disk binaries and carries integrity metadata:

{
  "schema_version": 1,
  "plugins": [
    {
      "name": "sim_cpu_dense",
      "kind": "sim",
      "abi_major": 1,
      "abi_minor": 1,
      "path": "libtdse_sim_cpu_dense.so",
      "sha256": "a1b2c3d4..."
    }
  ],
  "signature": "<base64 Ed25519 signature>"
}

• path is resolved relative to the manifest directory.
• sha256 is mandatory. The loader computes the hash of the on-disk binary before loading and rejects mismatches.
• signature is an optional Ed25519 signature over the manifest payload. When a public key is configured, the signature is verified at load time.

Environment Variables

Variable	Purpose
TDSE_PLUGIN_MANIFEST	Path to plugin_manifest.json. Required in production.
TDSE_PLUGIN_STRICT_MODE	Set to 1 for production. Requires manifest and disables fallback directory probing.
TDSE_PLUGIN_DIR	Directory containing plugin .so files. Optional; use only for controlled evaluation or non-manifest deployments.
TDSE_PLUGIN_PUBLIC_KEY_HEX	64-char hex Ed25519 public key for manifest signature verification.

Manifest Signing

The manifest can carry an Ed25519 signature. Signing and verification use the signing utility shipped with the SDK evaluation package:

# Generate a key pair
python3 tools/tdse_sign_manifest.py --generate-key-pair

# Sign the manifest in place
python3 tools/tdse_sign_manifest.py --sign manifest.json --private-key key.priv --in-place

# Verify
python3 tools/tdse_sign_manifest.py --verify manifest.json --public-key <hex-key>

When a public key is configured (via TDSE_PLUGIN_PUBLIC_KEY_HEX or the build-time TDSE_PLUGIN_PUBLIC_KEY), the loader verifies the signature before consuming manifest entries. Unsigned or tampered manifests are rejected.

See the Plugin Deployment Guide shipped with the evaluation package for the detailed signing workflow and key management expectations.

Production Configuration

For a packaged deployment, start with this configuration:

export TDSE_PLUGIN_MANIFEST=/opt/tdse/lib/plugins/sim/plugin_manifest.json
export TDSE_PLUGIN_STRICT_MODE=1
export TDSE_PLUGIN_PUBLIC_KEY_HEX=<64-hex-chars>

In strict mode:

• The host loads plugins only from the manifest.
• Fallback directory probing and relative directory scans are rejected.
• Manifest integrity (sha256) and authenticity (signature) are enforced.

This is the recommended baseline whenever you are shipping TDSE outside a local evaluation sandbox or controlled validation environment.

Health Check

Each plugin exports a health check function. Use tdse_plugin_doctor to inspect all installed plugins:

TDSE_PLUGIN_MANIFEST=/opt/tdse/lib/plugins/sim/plugin_manifest.json \
  tdse_plugin_doctor

The doctor reports for each plugin:

• ABI version and host compatibility
• Health status (ok, cuda_partial, cuda_unavailable)
• Manifest entry match and sha256 verification
• Struct size and vtable presence

Treat these health values as operational readiness signals, not performance claims. For example, ok means the plugin loaded compatibly under the current policy; it does not by itself prove throughput, WCET, or target-machine qualification.

Expected health status values:

• ok — plugin is fully operational
• cuda_unavailable — no CUDA runtime or driver detected
• cuda_partial — only some CUDA backends available
• dense_unavailable — dense CPU solver backend not available
• klu_unavailable — KLU sparse solver library not available
• mkl_unavailable — MKL Pardiso sparse solver not available
• sparse_unavailable — no sparse solver backends available

Monitoring

Plugin execution metrics are available through the host API (snapshot_metrics()). Tracked counters include:

• Load success and failure counts, with failure category
• Per-call-kind simulation counts (transient, AC matrix, AC probe)
• Total steps completed and frequency points processed
• Error count and last error code
• Backend switch count
• Session duration

Load failures are classified into stable categories ([file_not_found], [abi_mismatch], [hash_mismatch], [manifest_invalid]) for machine parsing from logs.

Compatibility

The plugin ABI uses struct_size versioning for forward-compatible field additions:

• New fields are appended to the end of config structs.
• The host checks struct_size before accessing new fields.
• Defaults for missing fields are safe (zero, null, off).

This means a MINOR ABI bump does not break existing plugins. Plugin authors should recompile to advertise the new version, but old binaries continue to work.

External Compatibility Contract

For packaged deployments, the practical compatibility promises are:

• plugin load compatibility follows the major/minor ABI rule described above
• extensible plugin-facing config, info, and diagnostics structs grow through struct_size; intentionally frozen payloads are documented as exceptions
• manifest integrity checks and documented health / failure classifications are stable operational behavior, not optional debugging extras
• install-tree plugin consumption is exercised through smoke and compatibility tests, not only ad hoc local loading

That means customers should treat manifest validation, ABI compatibility, documented health states, and documented failure classes as part of the supported contract surface. Use tdse_plugin_doctor as the first field diagnostic for those signals, while its human-readable presentation may evolve.

Troubleshooting

"No simulation engine plugin loaded"

Check TDSE_PLUGIN_MANIFEST or TDSE_PLUGIN_DIR. Run tdse_plugin_doctor to see detailed diagnostic output. Common causes:

• ABI version mismatch: the plugin was compiled against a different SDK version. The error message includes the plugin and host ABI versions.
• Manifest sha256 mismatch: the on-disk binary does not match the manifest. Rebuild or update the manifest.
• Missing entry point: the .so file does not export tdse_plugin_get_info. Check with nm -D.

Plugin loads but simulation fails with UNSUPPORTED

The loaded plugin does not support the requested solver backend. The host automatically loads the correct plugin for a given backend; check that the manifest includes the required plugin entry.

CUDA plugin reports cuda_unavailable

The CUDA toolkit or compatible driver is not installed, or the CUDA runtime libraries are not on the library path. Verify with tdse_plugin_doctor.