Platform Notes

Use this appendix when you need to answer platform questions: what Linux configurations are qualified, how installed-package validation is established, and what is currently supported on ARM64 and what remains a qualification lane.

This is not part of the shortest bring-up path. Read it when the real question becomes support boundary, qualification boundary, deployment risk, or target platform scope.

Read it in two passes: support boundary first, then the smallest validation or acceptance lane that matches the claim you need to make.

For integration work, this appendix usually answers one of these questions:

• is this host/platform combination inside the current support boundary
• what installed-package shape has already been validated
• what additional qualification is still the customer's responsibility, especially for RT/HIL

Read the status words in this appendix literally:

• supported means part of the current RC delivery and support boundary
• qualified means TDSE release validation has exercised that slice, often as an optional feature or lane
• roadmap means planned or actively explored, but not part of the current RC commitment
• customer qualification means the evaluation package may be usable there, but the final proof still belongs to the host program, target machine, or deployment process

Use the next two boundary chapters together with this one:

• use Plugin System when deployment risk becomes ABI, manifest, routing, or plugin-health evidence
• use Element Reference when deployment risk becomes source-deck coverage, unsupported directives, or netlist subset drift

Linux Support Scope

What Is Covered

Current x86_64 Linux qualification covers this complete TDSE release set:

• Runtime library, pack consumption, model create, lifecycle, step execution, and diagnostics
• Runtime Builder transforms and pack write (libtdse)
• TDSE Circuit with the reviewed OpenBLAS/LAPACK dense CPU provider
• CLI (tdse binary) and Profiler
• BLAS acceleration via OpenBLAS and LAPACK
• Telemetry with optional OpenSSL HTTPS export
• pkg-config and CMake package metadata
• relocatable Linux tar.gz package form for the qualified host profile

Optional accelerator stacks that require separate qualification:

• CUDA Circuit and CUDA Runtime backend (technical build and functional paths are validated; formal product qualification remains pending)
• Intel oneMKL BLAS backend and MKL Pardiso sparse solver

Platform Support Matrix

Supported Host Configuration

Current standard Linux support target is:

The Linux package builder selects only the technical payloads required by the contracted composition and groups them into that one package. For example, a Runtime-only package does not contain Circuit headers, libraries, plugins, or metadata. Internal CMake component names are never Linux package names.

The vendored Linux OpenBLAS lane uses OpenBLAS 0.3.34 with LP64 LAPACK/LAPACKE integrated into libopenblas.so. The current binary is built on Ubuntu 22.04 with DYNAMIC_ARCH + TARGET=GENERIC common code (runtime kernel dispatch across all x86-64 generations, including CPUs without AVX-512) and requires glibc >= 2.35. It is built with NOFORTRAN=1, retaining the complete C/f2c LAPACK/LAPACKE surface without requiring a host libgfortran.so.5 package. A host pkg-config OpenBLAS or separate LAPACKE development package cannot replace this provider in a TDSE package build. The complete installation also carries the OpenSSL crypto link/runtime closure used by Runtime authorization and TDSE Circuit, so customer CMake and pkg-config consumption does not require an OpenSSL development package. Release evidence records the approved OpenSSL version and SHA-256 of every bundled crypto artifact. Linux release archives are additionally compiled and executed in a minimal Ubuntu container where OpenBLAS, LAPACKE, and OpenSSL development packages are absent.

The qualified Linux runtime/CLI composition sets TDSE_LINUX_STATIC_CXX_RUNTIME=ON. CMake applies -static-libstdc++ -static-libgcc to the shared runtime and customer-facing CLI link steps, records the setting in the installed identity, and the profiler bundle validator rejects TDSE ELF artifacts that still directly declare libstdc++.so.6 or libgcc_s.so.1. This removes the TDSE binaries' dependence on the target image's C++ runtime symbol versions. The provider gate separately limits OpenBLAS to baseline glibc/loader dependencies, so a minimal supported image needs neither C++ nor Fortran runtime packages.

Both x86 providers use NUM_THREADS=512 and GEMM_MULTITHREAD_THRESHOLD=0; Linux additionally uses BIGNUMA=1 because upstream requires it for Linux x86_64 builds above the regular 256-CPU limit. The 512 value is compile-time capacity, not a default thread request. The zero threshold removes the fixed-size dispatch gate while the host-configured provider thread cap still applies. TDSE therefore skips the otherwise applicable prepare-time threshold-crossing zero-padding probe and records provider_thread_threshold_disabled on both platforms.

The x86 providers are both built from the same official OpenBLAS 0.3.34 source archive. Linux is built on the glibc 2.35 baseline. Windows is built with the MSYS2 UCRT64 MinGW-w64 toolchain, statically links its non-system toolchain runtime components, and uses VS2022 x64 lib.exe to generate the MSVC import library. The exact release commit, input hashes, build options, toolchain evidence, notices, and provider artifact hashes are recorded in the provider receipt and third_party/openblas/source-manifest.json.

OpenBLAS classifies using a MinGW-built DLL from Visual Studio as dynamic-link-only and not thoroughly tested. TDSE narrows and qualifies that boundary to the x64 CBLAS C ABI used by the Runtime; it does not promise the MinGW provider as a general MSVC ABI for Fortran or complex LAPACK calls. The provider gate includes an MSVC link/load/DGEMV executable plus independent FP32/FP64 GEMV/GEMM, import-closure, and TDSE Runtime tests.

On Linux, reproduce a candidate from the pinned source archive:

python tools/release/build_openblas_provider.py \
  --target linux \
  --output-root build/openblas-provider-linux \
  --jobs 4

When building from a Windows checkout under WSL2, use that WSL2-built candidate root for development verification only when the WSL distribution is on the supported glibc build baseline. The pinned Linux provider currently requires building on glibc <= 2.35 (Ubuntu 22.04). Git may also materialize the tracked Linux symlinks as text files when core.symlinks=false; a qualified WSL2 build must use real provider symlinks (or a native Linux checkout), never those text placeholders.

On Windows, reproduce the source-built provider with MSYS2 UCRT64 MinGW-w64 and the VS2022 x64 import-library tool available:

python tools/release/prepare_openblas_toolchain.py `
  --mode online `
  --cache-dir build/msys2-ucrt64-toolchain

python tools/release/build_openblas_provider.py `
  --target windows `
  --output-root build/openblas-provider-windows `
  --source-cache third_party/openblas/archive/0.3.34/OpenBLAS-0.3.34.tar.gz `
  --force
python tools/release/verify_openblas_msvc_abi.py `
  --provider-root build/openblas-provider-windows `
  --build-dir build/openblas-provider-windows-msvc-smoke

The package closure is controlled by third_party/openblas/toolchain-lock.json; the workflow does not use rolling pacman -S installation. Use --mode offline with a verified cache for a network-isolated build, or --mode verify-only to check the installed toolchain without changing MSYS2. The prep entry point performs one explicit pacman -U transaction only after all locked archives pass their lowercase SHA-256 checks. The builder verifies the same lock and the pinned VS2022 x64 lib.exe before make; missing provenance fails closed.

The builder verifies the archive and candidate provider, and it does not replace the approved delivery provider or trust anchors. There is no TDSE-specific DLL/SO rename or SONAME patch; the Windows MSVC import library is generated from the built DLL's exports. These artifacts require a separate qualification review. x86 CMake builds use the TDSE OpenBLAS root by default. The public CPU_BLAS path and profiler fail closed when a valid OpenBLAS provider is not loaded; they never fall back silently to a host reference loop or another backend.

The following are not covered by the standard support scope:

• musl-based distributions
• Apple Silicon macOS native runtime inside the Linux support claim; macOS ARM64 has a separate roadmap lane below
• non-Ubuntu ARM distributions unless separately qualified
• redistribution of an unqualified statically linked TDSE composition as a substitute for the supported shared package; the qualified runtime/CLI's internal static GCC runtime linkage is part of the supported package
• Intel oneMKL BLAS backend (requires separate MKL installation and qualification)

Configurations outside this table may still work but are not covered by the standard support scope unless documented in a release note.

Validation Coverage

Each TDSE Linux RC is validated on the supported host profile through installed-package consumption, release-build checks, threading stress tests, long-duration soak tests, and install/package smoke checks. The archive consumer smoke disables host BLAS and OpenSSL package discovery and rejects absolute external library paths in installed CMake or pkg-config exports. Additional release-engineering lanes may use broader internal coverage, but the customer-visible claim is anchored to the delivered package on the qualified host profile.

Supported Usage

A supported Linux deployment means the application consumes the shipped package through pkg-config or CMake exports, validates packs before model create, uses the standard create-diagnostics flow, runs CLI and Profiler commands cleanly on the qualified host profile, and passes the included tests for the current release.

Runtime Requirements

The Linux runtime expects one handle per execution thread, no same-handle concurrent step entry, and validated pack bytes as input. TDSE Circuit (circuit-domain circuit), Builder, and CLI are fully supported on Linux. A qualified installed CUDA package requires a compatible NVIDIA driver. Building CUDA support from source or compiling CUDA host code requires the supported CUDA Toolkit.

Reporting Issues

When reporting a Linux TDSE Runtime issue, please collect:

• package version
• package format used
• tdse pack validate --json <pack.bin> output
• tdse_model_create_diagnostics_t
• tdse_model_info(...)
• tdse_model_state_info(...)
• tdse_model_last_error_info(...)
• compiler, distro, and glibc baseline

Issue Categories

The following are treated as product defects: a qualified configuration regresses on unchanged inputs, install or export smoke fails on the supported host profile, or tdse_model_create(...) fails with a previously qualified pack.

The following are outside the standard support scope and may require a separate qualification agreement: unsupported distros or host classes (musl, non-Ubuntu ARM), optional dependency stacks outside the current scope, or same-handle concurrent stepping.

---

macOS ARM64 Roadmap Boundary

macOS ARM64 is not part of the current Windows or Linux delivery boundary. The source contains ordinary Apple-platform conditionals, but this repository has no active macOS package workflow, self-hosted runner lane, signed candidate, or formal qualification evidence. Source portability must not be reported as product or package support.

Adding native macOS ARM64 support requires an Apple Silicon runner, a complete package and installed-consumer lane, dependency and ABI verification, signing, and release qualification. Until those independent steps pass, no macOS ARM64 customer package is supported.

---

Linux/WSL Validation Guide

This section summarizes the Linux validation lanes used to establish RC confidence. It is release-validation context, not the primary path for a closed-source SDK evaluation package.

Supported Workflow

• WSL tests and validation gates must run from the distribution's native ext4 filesystem. Source, build, working, and temporary paths under /mnt/* are rejected before configuration or pytest collection because DrvFS/9P metadata I/O can turn a seconds-long gate into a timeout.
• From a Windows checkout, use scripts/run_in_wsl_ext4.sh -- <command...>. The runner incrementally synchronizes the working tree to a dedicated directory under ~/.cache/tdse/wsl-ext4-workspaces, preserves ext4 build directories, and executes the command from the corresponding native WSL working directory. It uses independent shallow Git metadata and excludes host-local ignored data such as .tdse-deps, artifacts, builds, and tool caches. Only the tracked tree plus non-ignored working changes are staged, so the executing test process has no Git-object dependency on /mnt/*.
• A normal non-test build may still read a Windows checkout. This policy is for tests, benchmarks, and validation gates whose time or result can be distorted by /mnt/* filesystem behavior.
• For normal customer evaluation, stay on the installed-package path from Installation and Getting Started (SDK source: docs/getting-started.md).
• RC qualification evidence is organized into default, extended, and release validation lanes.
• Escalate from default to extended when the question becomes install-tree or package consumption.
• Escalate to release when the question becomes release-candidate confidence or support evidence.

CTest Tiers

The Linux release process treats validation as lanes with different purposes. Use the smallest lane that answers your current question.

Use default unless you are explicitly validating an install tree, a package artifact, or a release candidate.

Prerequisites

These lanes depend on the TDSE release-validation environment. Closed-source RC consumers do not need to reproduce them just to evaluate the installed TDSE package package.

Install And Package Layout

Linux installs are intentionally prefix-relative.

In a standard Linux install under /opt/tdse, the important paths are:

• /opt/tdse/bin/tdse
• /opt/tdse/lib/libtdse.so
• /opt/tdse/lib/pkgconfig/tdse.pc
• /opt/tdse/lib/cmake/tdse/
• /opt/tdse/share/tdse/tdse_linux_installation.json
• /opt/tdse/share/tdse/tdse_runtime_sdk_variant.json

When TDSE Circuit is included, the same installation additionally contains:

• /opt/tdse/lib/libtdse_circuit.a
• /opt/tdse/share/tdse/tdse_sdk_variant.json

When the installation identity's technical_components list also includes simulation_plugins, it additionally contains:

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

The CUDA simulation plugin is present only when both the GPU Add-on and simulation_plugins are included as a technical component. The CUDA/cuDSS runtime closure follows the GPU Add-on independently of the optional plugin payload:

• /opt/tdse/lib/plugins/sim/libtdse_sim_cuda.so

The FPGA Add-on includes the TDSE host adapter in the same installation. XRT, the board driver, platform firmware, and the qualified xclbin remain host or accelerator-platform prerequisites and are not copied into the TDSE prefix. Release builds accept XRT headers, link library, and runtime only when they resolve under one recorded provider root; deployment qualification must then prove the exact XRT/device/xclbin combination on the target host.

Use the installed CMake package:

cmake -S <consumer-source> \
  -B build/package-consumer-cpu \
  -DCMAKE_PREFIX_PATH=/opt/tdse
cmake --build build/package-consumer-cpu --parallel 4
LD_LIBRARY_PATH=/opt/tdse/lib:${LD_LIBRARY_PATH} \
  build/package-consumer-cpu/<consumer-binary>

find_package(tdse CONFIG REQUIRED) is valid for both Runtime-only and Runtime + Circuit installations. The available imported targets reflect the contracted composition; the package name does not change.

Use the installed pkg-config package:

export PKG_CONFIG_PATH=/opt/tdse/lib/pkgconfig:${PKG_CONFIG_PATH}
c++ -std=c++20 app.cpp -o app $(pkg-config --cflags --libs tdse)

Likewise, tdse is the only installed pkg-config name. Its Libs field already reflects the installed Runtime or Runtime + Circuit composition; hardware Add-ons are private runtime-loaded modules and never add customer link flags.

Linux Package Targets

The repository currently produces one complete relocatable tar.gz installation. The archive is checked for relocation, and its installed pkg-config/CMake metadata is checked through downstream consumers. DEB and RPM are future packaging formats, not current release outputs; they cannot be claimed until their payload and clean-host gates exist.

Acceptance Shapes

The release process validates more than one package-consumption shape. From a customer-handbook perspective, the important ones are:

Use the smallest acceptance shape that matches the support claim you need to make. Do not infer clean-host or full-feature release confidence from a same-host default build alone.

This is why the handbook points you to installed-package examples instead of relying on same-host validation alone: the install tree itself is part of the supported surface.

Notes

• The default configuration is the supported day-to-day Linux baseline.
• RC consumers should treat the installed package as the supported surface. Engineering-only validation lanes may explain how confidence was established, but they are not required reading for first evaluation.

Troubleshooting

• Missing compiler or linker tools: Install build-essential.
• pkg-config consumer cannot find TDSE: Add <prefix>/lib/pkgconfig to PKG_CONFIG_PATH before building the downstream app.
• CMake configure succeeds but runtime install smoke cannot find shared libraries: Re-run the release team's extended Linux validation lane; that lane already sets the needed runtime environment for its smoke checks.
• A customer requests DEB or RPM: Use the promoted tar.gz installation; native DEB/RPM production is not yet an implemented release path.
• Stale build state after large branch changes: Clean the local build directory and configure again.
• You need ARM64 details: Start with the ARM64/AArch64 support section below.

Linux ARM64 / AArch64 Support Boundary

Current Status

TDSE Runtime and its OpenBLAS provider are natively qualified on Linux AArch64. The repository contains the approved ARM64 provider receipt and binary built from the same pinned OpenBLAS 0.3.34 source and TDSE patch as the x86_64 provider. Native AWS Graviton validation on Ubuntu 22.04 covered the full SDK build, ABI checks, runtime, and stress tests. The formal AArch64 tar.gz package and customer real-time-host acceptance remain separate package/host qualification activities.

Qualified Runtime Feature Set

The qualified ARM64 runtime slice includes:

• Runtime (including the Builder APIs), TDSE Circuit, CLI, Profiler, and telemetry binaries built against the architecture-matched bundled TDSE OpenBLAS provider installation.
• The shared KLU closure when the Circuit composition is separately qualified; MKL PARDISO remains disabled unless its own qualification is completed.
• Architecture-specific feature and sanitizer evidence from the actual ARM64 host.

The provider is approved and bundled. A formal ARM64 tarball still needs its normal clean-install and installed-consumer gates before that package format is released; native runtime/provider qualification does not waive those package gates.

Formal build-feature JSON reports AArch64 host capability as cpu_supports_neon, cpu_supports_sve, and cpu_supported_simd_width_bits. It intentionally does not expose the compile state or selected ISA of TDSE's internal diagnostic kernels, because those fields do not describe the OpenBLAS implementation used by the supported CPU path. Low-level per-model diagnostics remain available for internal kernel qualification. The existing public cpu_simd_avx2 and cpu_simd_avx512 backend entries remain unavailable on ARM.

Not part of the current ARM64 delivery claim:

• formal ARM64 tar.gz package gates
• native macOS ARM64 packages
• Windows ARM64 packages
• CUDA or FPGA/XRT acceleration on ARM
• non-glibc Linux distributions
• non-Ubuntu ARM distro package semantics unless separately qualified

ARM64 Validation Lane

ARM64 is not part of the repository's GitHub-hosted matrix. On a prepared Ubuntu 22.04-or-newer AArch64 host, the normal build automatically selects the bundled provider. The provider keeps the same installed names and receipt schema as x86_64; the ELF payload is necessarily native AArch64 machine code:

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build python3

cmake -S . -B build-arm64-release -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=ON \
  -DTDSE_RUNTIME_PROVIDER_POLICY=qualified_bundled

cmake --build build-arm64-release --parallel 4
ctest --test-dir build-arm64-release --output-on-failure
python3 tools/release/check_sdk_install_smoke.py \
  --build-dir build-arm64-release --config Release

Then capture the architecture-specific feature report:

python3 tools/validation/runtime/check_arm_runtime_features.py \
  --out-dir build-arm64-release/arm-evidence \
  --backend-caps-exe build-arm64-release/tdse_backend_caps
python3 tools/validation/runtime/collect_arm_sve_evidence.py \
  --out-dir build-arm64-release/arm-evidence \
  --backend-caps-exe build-arm64-release/tdse_backend_caps \
  --require-aarch64
python3 tools/validation/runtime/check_arm_cuda_feasibility.py \
  --out-dir build-arm64-release/arm-cuda-feasibility

These commands prove only the observed host/build. CUDA-on-ARM, sanitizer, package-format, and formal qualification runs require external ARM hardware and release infrastructure. The SDK repository intentionally does not contain a cloud-runner workflow or claim those lanes from an x86 build.

Linux POWER / RTDS Boundary

Linux ppc64le uses the same public headers, tdse::runtime customer target, libtdse.so installed name, profiler command, 48-case matrix, and report schema. The provider builder selects a POWER8 common-code baseline with DYNAMIC_ARCH=1; OpenBLAS then selects POWER8/POWER9/POWER10 kernels at startup where the compiler and processor support them. OpenBLAS's optimized POWER pthread alternative is not substituted: the provider uses its supported OpenMP path and records that fact in the same receipt field.

An RTDS NovaCor deployment is a separate no-OS product build. It keeps the same TDSE C API and logical library identity, but a Linux ELF cannot run on a target with no Linux loader. Promotion therefore requires the partner's POWER9 compiler/sysroot, static provider closure, startup-only initialization, and on-target timing evidence. A Linux POWER9 VM proves source and ABI portability only; it is not presented as NovaCor qualification.

---

Real-Time and HIL Deployment

Use this section when TDSE must meet a real-time or hardware-in-the-loop timing budget, not just run correctly offline.

Keep the host/TDSE boundary simple in real-time deployments:

• the host owns the wall-clock scheduler, solver sequencing, and any external I/O or device synchronization
• TDSE exchanges model data only at step boundaries through tdse_step_begin(...), tdse_step_op(...), tdse_step_hr(...), tdse_step_ir(...), tdse_step_commit(...), and optional tdse_step_dr(...)
• a practical HIL integration usually treats primary as the host-to-TDSE input vector and op / hr / ir / dr as TDSE-to-host outputs used inside the host's accepted-step policy

For most teams, RT/HIL readiness is a three-lane progression:

Step-Loop Timing Budget

In a real-time simulation, each time step must complete within a fixed wall-clock budget. For TDSE, the per-step cost depends on:

Worst-Case Execution Time (WCET)

For real-time certification, measure WCET under these conditions:

1. Use the production provider, thread contract, affinity, and logging settings; deterministic mode does not eliminate scheduling jitter
2. Run the worst-case model configuration (largest np, nh in the deployment)
3. Measure over at least 10,000 consecutive steps
4. Record the maximum observed step time plus a safety margin (recommended: 20% margin)

The step-loop APIs with the highest individual latency are:

• tdse_step_hr(): proportional to (nh - 1) * nq * np (convolution over delayed history taps)
• tdse_step_commit(): proportional to nq * np for the committed direct-response matrix-vector product, plus state advancement
• tdse_step_op(): proportional to nq * np to copy the instantaneous operator; fetch and cache it when operator conditions change rather than treating it as a per-step factorization

Multi-Rate Coupling Time Budget

When coupling TDSE with an EMT solver at a different time step:

EMT step (e.g., 50 us):
├─ TDSE sub-steps: EMT_dt / TDSE_dt steps
│  ├─ each TDSE step: begin + hr + ir + commit
│  ├─ refresh and cache op only when operator conditions change
│  └─ per-step budget: EMT_dt / N_substeps
└─ remaining budget: host EMT solve + overhead

Example: EMT step = 50 μs, TDSE model_dt = 1 μs → 50 TDSE sub-steps per EMT step. Each TDSE sub-step must complete in under 50 μs / 50 = 1 μs (minus host overhead).

Deterministic Logging Metadata

Deterministic mode is a context-local logging setting, not a real-time execution mode. Enable it only when the host wants stable diagnostic metadata:

tdse_ext_context_t* ext = tdse_ext_context_create();
tdse_ext_context_set_deterministic_mode(ext, 1);
tdse_model_create_options_t options = tdse_model_create_options_init();
options.context = ext;
tdse_model_create(pack_data, pack_size, &options, &diag, &model);

This normalizes timestamps and process-local correlation/model/request IDs in runtime log events. It does not change device selection, OpenBLAS/provider threads, CPU affinity, NUMA policy, scheduler behavior, or numerical reduction order. It does not provide bitwise cross-platform reproducibility and does not replace host-level WCET measurement, scheduler tuning, or target-machine qualification.

HIL Integration Patterns

For hardware-in-the-loop deployments:

1. Dedicated core allocation. Pin the TDSE worker thread to dedicated CPU cores. Use OS affinity APIs (pthread_setaffinity_np on Linux, SetThreadAffinityMask on Windows).

2. Pre-allocate all resources. Create all model handles before the real-time loop starts. No dynamic allocation during stepping.

3. Avoid OS interference. Isolate CPU cores from the OS scheduler (Linux isolcpus boot parameter) for the lowest jitter.

4. Monitor guard metrics. In real-time, continuous monitoring is essential. Poll tdse_ext_context_get_runtime_guard_metrics() on the model's extension context periodically (e.g., every 1000 steps) and log any threshold crossing.

5. Plan for graceful degradation. If a step exceeds its budget, the host must decide whether to skip the commit (reject the trial) or accept the latency overrun. TDSE's trial/commit separation supports both strategies.