tc_runtime

tc_runtime provides CPU feature detection and capability proof tokens for x86 and AArch64. Callers use these tokens to select supported optimized backends. It is no_std unless its optional std feature is enabled, and supports Rust 1.85 and later.

It has no dependencies by default, on any target. Opting into aarch64 runtime detection with aarch64-detect adds cpufeatures, which in turn pulls in libc on Linux, Android, and Apple targets only. Neither requires std.

The x86 API mirrors the capabilities currently queried by Bouncy Castle's Org.BouncyCastle.Runtime.Intrinsics.X86 namespace. Every capability provides:

use tc_runtime::intrinsics::x86::{Aes, Avx2, Sse2};

if let Some(sse2) = Sse2::detect() {
    // Pass the proof token to an SSE2 backend.
    let _ = sse2;
}

assert_eq!(Aes::detect().is_some(), Aes::is_enabled());
assert_eq!(Avx2::detect().is_some(), Avx2::is_enabled());

The private field in each proof token prevents safe caller code from creating one without first performing detection.

The types remain available on every architecture, where is_enabled() returns false and detect() returns None. Off its own architecture a capability's is_enabled() is a const fn, so the caller's branch folds away at compile time and a portable selection costs nothing:

use tc_runtime::intrinsics::{aarch64, x86};

let backend = if x86::Pclmulqdq::detect().is_some() {
    "pclmulqdq"
} else if aarch64::Aes::detect().is_some() {
    "pmull"
} else {
    "portable"
};

x86 capabilities

AVX2 and the vector-width PCLMULQDQ checks include operating-system extended-state support; a CPU feature bit alone is not sufficient to execute those instructions safely.

aarch64 capabilities

aarch64 exposes no unprivileged feature-query instruction — the ID_AA64ISAR*_EL1 registers are readable only at EL1 — so runtime detection goes through the operating system rather than an equivalent of CPUID.

LLVM models aarch64 target features more coarsely than the individual Arm architectural features, so one capability can cover several of them:

There is deliberately no separate Pmull capability: Linux requires both the HWCAP_AES and HWCAP_PMULL bits, so a GHASH backend takes the Aes token. For the same reason a SHA-512 backend takes the Sha3 token.

Detection backends

A capability is available whenever the matching target_feature is enabled at compile time, because the compiler may then emit those instructions throughout the build. This floor applies whichever backend is selected, and costs nothing at run time. Several targets set most of these by default:

Runtime detection beyond that floor is a swappable backend:

No backend can probe Windows on ARM or bare-metal targets, which therefore rely on the compile-time floor alone; aarch64-detect buys them nothing. On aarch64-apple-darwin the floor already covers the features the backend would report, so it changes nothing there either. In practice the feature matters on Linux and Android.

Unlike the x86 module's use of CPUID, none of this requires std; a backend reaches the operating system directly.

Backends live in src/intrinsics/aarch64/backend.rs, behind a contract of one fn() -> bool per feature. Replacing one does not affect the public API.

Cargo features

Disabling optimized backends

Use these switches to exercise portable fallback paths in tests, or to temporarily avoid an optimized backend while investigating a defect. They control capability-based backend selection; they are not CPU tuning settings.

With std enabled, environment overrides let operators disable individual backends without rebuilding. Set them before starting the process, then restart the application. Detection results are cached: changing the environment of an already-running process is not a supported way to switch backends.

Cargo disable-* features apply at build time and require a rebuild. Both forms are listed below:

For example:

cargo build --features tc_runtime/disable-x86-avx2
cargo build --features tc_runtime/disable-x86-pclmulqdq
cargo build --features tc_runtime/disable-aarch64-aes

For an existing build with std enabled, set one or more of these variables in the service configuration or launching shell before restarting the application:

TC_DISABLE_X86_AVX2=1
TC_DISABLE_X86_PCLMULQDQ=1
TC_DISABLE_AARCH64_AES=1

The presence of a variable disables the matching capability regardless of its value. Results are cached, so changing an environment variable after the first check has no effect. The general PCLMULQDQ switch also disables its V256 and V512 capabilities.

There is currently no global disable switch. If the affected backend is unknown, set all applicable TC_DISABLE_* variables listed above before restarting. The application must provide portable fallbacks for the capabilities it uses.

These switches prevent callers from selecting the matching optimized backend; they do not guarantee that the Rust compiler emits no instructions belonging to that instruction set. In particular, SSE2 is part of the x86_64 baseline and NEON is part of the aarch64 baseline.