Craton Shield

vs-ffi-auto

Part of Craton Shield Auto | Architecture

Warning — C ABI crate. This crate exposes a stable C ABI. Cargo's semver only covers the Rust API. The C ABI is tracked separately via the packed VS_ABI_VERSION constant (see vs_auto.h and ABI.md at the workspace root). A patch-level Rust release MAY bump VS_ABI_VERSION (e.g. fixing a field-layout bug); downstream C consumers MUST query vs_auto_abi_version() at init and refuse to dispatch on a major-version mismatch.

Automotive C-compatible FFI bindings for Craton Shield.

Overview

Provides a stable C ABI for integrating Craton Shield automotive modules into existing ECU software written in C/C++. Designed for ISO 26262 compliant integration with legacy automotive toolchains.

Note: This crate requires std (for Mutex, catch_unwind, and monotonic timestamps). It targets Linux/QNX gateway ECUs, not bare-metal Cortex-M.

Features

  • C-compatible function exports with catch_unwind for panic safety
  • Null pointer and alignment validation on all inputs
  • CAN ID (11/29-bit) and DLC validation
  • Token-bucket rate limiting for CAN frame ingestion
  • Produces both staticlib and cdylib outputs
  • production feature flag gates a real cryptographic backend via C callbacks

See core/docs/feature-flags.md for the full workspace feature reference.

Building

# Development / testing (uses stub crypto — zero security)
cargo build -p vs-ffi-auto
cargo test -p vs-ffi-auto

# Production (requires caller-supplied crypto callbacks)
cargo build --release -p vs-ffi-auto --features production

Production Integration

In production builds (--features production), the platform must be initialized with a VsCryptoCallbacks struct that provides real cryptographic operations (typically backed by an HSM driver):

#include "vs_auto.h"

static VsCryptoCallbacks my_callbacks = {
    // Mandatory ABI canaries — the init function rejects the struct with
    // VS_ERR_INVALID_ARG unless BOTH of these are set exactly as shown.
    .magic                 = VS_CRYPTO_CALLBACKS_MAGIC,
    .crypto_callbacks_size = sizeof(VsCryptoCallbacks),

    .context       = &my_hsm_driver,
    .sha256        = my_sha256,
    .hmac_sha256   = my_hmac_sha256,
    .random_bytes  = my_rng,
    // ... all other callbacks
};

VsResult r = vs_auto_platform_init_with_crypto(&my_callbacks);

magic and crypto_callbacks_size are not optional: vs_auto_platform_init_with_crypto validates both before dispatching through any callback and returns VS_ERR_INVALID_ARG if either is missing or wrong.

In non-production builds, vs_auto_platform_init() (no arguments) uses a stub provider suitable for testing only.

License

Apache-2.0. See LICENSE.