backend_plugin.h

Go to the documentation of this file.

// Copyright (c) 2024-2026 Lux Industries Inc.
// SPDX-License-Identifier: BSD-3-Clause-Eco
//
// Backend Plugin ABI - Stable C interface for runtime-loaded GPU backends
//
// Each backend shared library exports one symbol: lux_gpu_backend_init
// The core library dlopen()s backends and calls this to get the vtable.
//
// One vtbl, one cross-backend contract. Each plugin is self-contained — there
// is no parallel crypto vtbl, no extension struct. Crypto types live in
// <lux/gpu/crypto.h>. The curve enum lives in <lux/gpu.h> as LuxCurve.
 
#ifndef LUX_GPU_BACKEND_PLUGIN_H
#define LUX_GPU_BACKEND_PLUGIN_H
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
 
#include "lux/gpu/crypto.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
// =============================================================================
// ABI Version - bump on breaking changes
// =============================================================================
 
// ABI v5: FHE ops take explicit base_log; k=0 and degenerate gadgets are
// rejected with INVALID_ARGUMENT. CUDA/WGSL bootstrap+blind_rotate now run the
// canonical CPU PBS body via cpu_fhe_helpers.hpp (no more rotation-only fakes).
#define LUX_GPU_BACKEND_ABI_VERSION 5
 
// =============================================================================
// Forward declarations (opaque handles)
// =============================================================================
 
typedef struct LuxBackendContext LuxBackendContext;
typedef struct LuxBackendBuffer  LuxBackendBuffer;
 
// =============================================================================
// Error codes
// =============================================================================
 
typedef enum {
    LUX_BACKEND_OK                    = 0,
    LUX_BACKEND_ERROR_INVALID_ARGUMENT = 1,
    LUX_BACKEND_ERROR_OUT_OF_MEMORY    = 2,
    LUX_BACKEND_ERROR_NOT_SUPPORTED    = 3,
    LUX_BACKEND_ERROR_DEVICE_LOST      = 4,
    LUX_BACKEND_ERROR_INTERNAL         = 5,
} LuxBackendError;
 
typedef struct {
    const char* name;
    const char* vendor;
    uint64_t memory_total;
    uint64_t memory_available;
    int compute_units;
    int max_workgroup_size;
    bool is_discrete;
    bool is_unified_memory;
} LuxBackendDeviceInfo;
 
// =============================================================================
// Backend vtbl — the single cross-backend contract.
//
// Layout: lifecycle -> device info -> sync -> buffers -> tensor ops ->
// FHE/NTT -> crypto. No designated initializers required; missing trailing
// fields are nullptr by virtue of static zero-init in the plugin.
// =============================================================================
 
typedef struct lux_gpu_backend_vtbl {
    // -------- Lifecycle --------
    LuxBackendContext* (*create_context)(int device_index);
    void               (*destroy_context)(LuxBackendContext* ctx);
 
    // -------- Device info & sync --------
    LuxBackendError (*get_device_count)(int* count);
    LuxBackendError (*get_device_info)(LuxBackendContext* ctx, LuxBackendDeviceInfo* info);
    LuxBackendError (*sync)(LuxBackendContext* ctx);
 
    // -------- Buffer management --------
    LuxBackendBuffer* (*buffer_alloc)(LuxBackendContext* ctx, size_t bytes);
    LuxBackendBuffer* (*buffer_alloc_with_data)(LuxBackendContext* ctx, const void* data, size_t bytes);
    void              (*buffer_free)(LuxBackendContext* ctx, LuxBackendBuffer* buf);
    LuxBackendError   (*buffer_copy_to_host)(LuxBackendContext* ctx, LuxBackendBuffer* buf, void* dst, size_t bytes);
    LuxBackendError   (*buffer_copy_from_host)(LuxBackendContext* ctx, LuxBackendBuffer* buf, const void* src, size_t bytes);
    void*             (*buffer_get_host_ptr)(LuxBackendContext* ctx, LuxBackendBuffer* buf);
 
    // -------- Tensor ops (f32) --------
    LuxBackendError (*op_add_f32)(LuxBackendContext* ctx, LuxBackendBuffer* a, LuxBackendBuffer* b, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_sub_f32)(LuxBackendContext* ctx, LuxBackendBuffer* a, LuxBackendBuffer* b, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_mul_f32)(LuxBackendContext* ctx, LuxBackendBuffer* a, LuxBackendBuffer* b, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_div_f32)(LuxBackendContext* ctx, LuxBackendBuffer* a, LuxBackendBuffer* b, LuxBackendBuffer* out, size_t n);
 
    LuxBackendError (*op_matmul_f32)(LuxBackendContext* ctx, LuxBackendBuffer* a, LuxBackendBuffer* b, LuxBackendBuffer* out, int M, int K, int N);
    LuxBackendError (*op_transpose_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, int rows, int cols);
 
    LuxBackendError (*op_reduce_sum_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_reduce_max_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_reduce_min_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_reduce_mean_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_reduce_sum_axis_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t outer_size, size_t inner_size);
    LuxBackendError (*op_reduce_max_axis_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t outer_size, size_t inner_size);
 
    LuxBackendError (*op_softmax_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t batch_size, size_t dim);
    LuxBackendError (*op_log_softmax_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t batch_size, size_t dim);
 
    LuxBackendError (*op_exp_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_log_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_sqrt_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_neg_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_abs_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_tanh_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_sigmoid_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_relu_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
    LuxBackendError (*op_gelu_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, size_t n);
 
    LuxBackendError (*op_copy_f32)(LuxBackendContext* ctx, LuxBackendBuffer* src, LuxBackendBuffer* dst, size_t n);
 
    LuxBackendError (*op_layer_norm_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, LuxBackendBuffer* gamma, LuxBackendBuffer* beta, size_t batch_size, size_t dim, float eps);
    LuxBackendError (*op_rms_norm_f32)(LuxBackendContext* ctx, LuxBackendBuffer* in, LuxBackendBuffer* out, LuxBackendBuffer* weight, size_t batch_size, size_t dim, float eps);
 
    // -------- NTT (host-pointer interface; backend manages staging) --------
    LuxBackendError (*op_ntt_forward)(LuxBackendContext* ctx, uint64_t* data, size_t n, uint64_t modulus);
    LuxBackendError (*op_ntt_inverse)(LuxBackendContext* ctx, uint64_t* data, size_t n, uint64_t modulus);
 
    // -------- FHE (host-pointer interface; backend manages staging) --------
    LuxBackendError (*op_poly_mul)(
        LuxBackendContext* ctx,
        const uint64_t* a, const uint64_t* b, uint64_t* result,
        size_t n, uint64_t modulus
    );
 
    // TFHE-AP programmable bootstrap. BSK layout per input LWE coordinate:
    //   [n_lwe][(k+1)*l][k+1][N] uint64_t  (TRGSW row-major).
    // Gadget contract: B = 2^base_log; the caller MUST choose (l, base_log)
    // so that l × base_log ≤ log2(q). Otherwise q / B^l collapses to zero on
    // the bottom row and that gadget level encrypts only noise. Backends
    // reject l × base_log > 64 with INVALID_ARGUMENT.
    // k = 0 is rejected: lwe_out length is documented as k*N + 1 = 1 yet the
    // sample-extract writes N entries — silent OOB. INVALID_ARGUMENT instead.
    LuxBackendError (*op_tfhe_bootstrap)(
        LuxBackendContext* ctx,
        const uint64_t* lwe_in, uint64_t* lwe_out,
        const uint64_t* bsk, const uint64_t* test_poly,
        uint32_t n_lwe, uint32_t N, uint32_t k, uint32_t l,
        uint32_t base_log, uint64_t q
    );
 
    // TFHE keyswitch. KSK rows encode an LWE encryption (under the OUT key)
    // of  −s_{in_idx} · q / B^{level+1}  where B = 2^base_log and
    // s_{in_idx} is the IN secret-key coordinate. Accumulating
    // +digit · KSK[in_idx][level] over the signed-base-B decomposition of
    // lwe_in[in_idx] yields the keyswitched ciphertext under the OUT key.
    // Callers MUST follow this convention.
    LuxBackendError (*op_tfhe_keyswitch)(
        LuxBackendContext* ctx,
        const uint64_t* lwe_in, uint64_t* lwe_out,
        const uint64_t* ksk,
        uint32_t n_in, uint32_t n_out, uint32_t l, uint32_t base_log, uint64_t q
    );
 
    // AP-style blind rotation. Same gadget contract as op_tfhe_bootstrap.
    LuxBackendError (*op_blind_rotate)(
        LuxBackendContext* ctx,
        uint64_t* acc, const uint64_t* bsk, const uint64_t* lwe_a,
        uint32_t n_lwe, uint32_t N, uint32_t k, uint32_t l,
        uint32_t base_log, uint64_t q
    );
 
    // -------- Crypto: hashes --------
    LuxBackendError (*op_poseidon2_hash)(
        LuxBackendContext* ctx,
        const uint64_t* inputs, uint64_t* outputs,
        size_t rate, size_t num_hashes
    );
 
    LuxBackendError (*op_blake3_hash)(
        LuxBackendContext* ctx,
        const uint8_t* inputs, uint8_t* outputs,
        const size_t* input_lens, size_t num_hashes
    );
 
    LuxBackendError (*op_keccak256_hash)(
        LuxBackendContext* ctx,
        const uint8_t* inputs, uint8_t* outputs,
        const size_t* input_lens, size_t num_inputs
    );
 
    // -------- Crypto: BLS12-381 (G1 or G2 selected by is_g2) --------
    LuxBackendError (*op_bls12_381_add)(
        LuxBackendContext* ctx,
        const void* a, const void* b, void* out, size_t n, bool is_g2
    );
    LuxBackendError (*op_bls12_381_mul)(
        LuxBackendContext* ctx,
        const void* points, const void* scalars, void* out, size_t n, bool is_g2
    );
    LuxBackendError (*op_bls12_381_pairing)(
        LuxBackendContext* ctx,
        const void* g1_points, const void* g2_points, void* out, size_t n
    );
 
    // -------- Crypto: BN254 (G1 or G2 selected by is_g2) --------
    LuxBackendError (*op_bn254_add)(
        LuxBackendContext* ctx,
        const void* a, const void* b, void* out, size_t n, bool is_g2
    );
    LuxBackendError (*op_bn254_mul)(
        LuxBackendContext* ctx,
        const void* points, const void* scalars, void* out, size_t n, bool is_g2
    );
 
    // -------- Crypto: MSM (curve_type is LuxCurve from <lux/gpu.h>) --------
    LuxBackendError (*op_msm)(
        LuxBackendContext* ctx,
        const void* scalars, const void* points, void* result,
        size_t n, int curve_type
    );
 
    // -------- Crypto: KZG polynomial commitments --------
    LuxBackendError (*op_kzg_commit)(
        LuxBackendContext* ctx,
        const void* coeffs, const void* srs, void* commitment,
        size_t degree, int curve_type
    );
    LuxBackendError (*op_kzg_open)(
        LuxBackendContext* ctx,
        const void* coeffs, const void* srs, const void* point, void* proof,
        size_t degree, int curve_type
    );
    LuxBackendError (*op_kzg_verify)(
        LuxBackendContext* ctx,
        const void* commitment, const void* proof,
        const void* point, const void* value, const void* srs_g2,
        bool* result, int curve_type
    );
 
    // -------- Crypto: secp256k1 ecrecover (Ethereum) --------
    LuxBackendError (*op_ecrecover_batch)(
        LuxBackendContext* ctx,
        const void* signatures, void* addresses, size_t num_signatures
    );
 
    // -------- Crypto: Post-quantum signatures (FIPS 203/204/205) --------
    //
    // ML-DSA-65 (Dilithium3) batch verify. pubkeys: 1952B each, signatures:
    // 3293B each (variable, padded to fixed stride by caller), messages:
    // arbitrary pre-hashed digests (each entry is one msg with paired length).
    // results[i] = true iff verification succeeded.
    LuxBackendError (*op_mldsa_verify_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* pubkeys,
        const uint8_t* const* messages,
        const uint8_t* const* signatures,
        bool* results,
        size_t count
    );
 
    // ML-KEM-768 (Kyber768) batch decapsulation. secret_keys: 2400B each,
    // ciphertexts: 1088B each, shared_secrets: 32B each (output).
    LuxBackendError (*op_mlkem_decapsulate_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* secret_keys,
        const uint8_t* const* ciphertexts,
        uint8_t** shared_secrets,
        size_t count
    );
 
    // SLH-DSA (SPHINCS+) batch verify. SHA2-128f mode by convention: pubkeys
    // 32B, sigs ~17088B. results[i] = true iff verification succeeded.
    LuxBackendError (*op_slhdsa_verify_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* pubkeys,
        const uint8_t* const* messages,
        const uint8_t* const* signatures,
        bool* results,
        size_t count
    );
 
    // -------- Crypto: Threshold signature primitives --------
    //
    // Ringtail lattice-based threshold: per-party partial signing pass.
    // shares: 1024B each (per-party secret share), messages: 32B each,
    // partial_sigs: 1024B each (output). Returns NOT_SUPPORTED on backends
    // that do not implement the full ceremony pipeline.
    LuxBackendError (*op_ringtail_partial_sign_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* shares,
        const uint8_t* const* messages,
        uint8_t** partial_sigs,
        size_t count
    );
 
    // Ringtail threshold combine: merge `threshold` partial sigs into one
    // combined signature using Lagrange interpolation coefficients.
    LuxBackendError (*op_ringtail_combine_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* partial_sigs,
        const int32_t* lagrange_coeffs,
        uint8_t** combined_sigs,
        size_t threshold,
        size_t count
    );
 
    // FROST threshold Schnorr partial-signature verification. commitments:
    // 66B each, signatures: 32B each, pubkeys: 33B each, challenges: 32B
    // each (pre-computed c*lambda_i scalars).
    LuxBackendError (*op_frost_partial_verify_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* commitments,
        const uint8_t* const* signatures,
        const uint8_t* const* pubkeys,
        const uint8_t* const* challenges,
        bool* results,
        size_t count
    );
 
    // CGGMP21 threshold ECDSA partial-signing pass. Each entry packs:
    // k_share[32] || chi_share[32] || msg_hash[32] || gamma_share[32].
    // r_x is the x-coordinate of the combined nonce R shared across the
    // batch. partial_sigs[i] is the per-party sigma_i (32B).
    LuxBackendError (*op_cggmp21_partial_sign_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* inputs,
        const uint8_t* r_x,
        uint8_t** partial_sigs,
        size_t count
    );
 
    // -------- Crypto: Classical Schnorr (Ed25519 / sr25519) --------
    //
    // Ed25519 (RFC 8032) batch verify. Messages are 64-byte digests by
    // contract (host pre-hashes if larger; consumers must commit to a
    // fixed-width input). pubkeys: 32B each, signatures: 64B each,
    // results[i] = true iff verify(pk, msg, sig) succeeds.
    LuxBackendError (*op_ed25519_verify_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* pubkeys,
        const uint8_t* const* messages,
        const uint8_t* const* signatures,
        bool* results,
        size_t count
    );
 
    // sr25519 (Schnorrkel/Ristretto255) batch verify. Same shape and
    // 64-byte message contract as Ed25519, but uses the Substrate-style
    // schnorrkel transcript.
    LuxBackendError (*op_sr25519_verify_batch)(
        LuxBackendContext* ctx,
        const uint8_t* const* pubkeys,
        const uint8_t* const* messages,
        const uint8_t* const* signatures,
        bool* results,
        size_t count
    );
} lux_gpu_backend_vtbl;
 
// =============================================================================
// Backend Descriptor (returned by plugin init)
//
// vtbl_size is a hard-required cookie that lets the loader detect a plugin
// that lies about its abi_version while shipping a truncated vtable. Each
// plugin MUST set this to sizeof(lux_gpu_backend_vtbl) as compiled against
// THIS header. The loader MUST reject any plugin whose vtbl_size does not
// match the consumer's compile-time sizeof. This protects consumers from
// reading past the end of an undersized vtable and dispatching through a
// junk function pointer.
// =============================================================================
 
typedef struct {
    uint32_t                     abi_version;     // Must be LUX_GPU_BACKEND_ABI_VERSION
    uint32_t                     vtbl_size;       // Must equal sizeof(lux_gpu_backend_vtbl)
    const char*                  backend_name;    // "cpu" | "metal" | "cuda" | "webgpu"
    const char*                  backend_version; // e.g., "0.1.0"
    uint32_t                     capabilities;    // Bitmask of supported features
    const lux_gpu_backend_vtbl*  vtbl;
} lux_gpu_backend_desc;
 
// =============================================================================
// Capability flags (advisory, for feature gating in consumers)
// =============================================================================
 
#define LUX_CAP_TENSOR_OPS      (1u << 0)
#define LUX_CAP_MATMUL          (1u << 1)
#define LUX_CAP_NTT             (1u << 2)
#define LUX_CAP_MSM             (1u << 3)
#define LUX_CAP_UNIFIED_MEMORY  (1u << 4)
#define LUX_CAP_FHE             (1u << 5)
#define LUX_CAP_TFHE            (1u << 6)
#define LUX_CAP_REDUCE          (1u << 7)
#define LUX_CAP_SOFTMAX         (1u << 8)
#define LUX_CAP_UNARY           (1u << 9)
#define LUX_CAP_NORMALIZATION   (1u << 10)
#define LUX_CAP_BLS12_381       (1u << 11)
#define LUX_CAP_BN254           (1u << 12)
#define LUX_CAP_KZG             (1u << 13)
#define LUX_CAP_POSEIDON2       (1u << 14)
#define LUX_CAP_BLAKE3          (1u << 15)
#define LUX_CAP_KECCAK256       (1u << 16)
#define LUX_CAP_ECRECOVER       (1u << 17)
#define LUX_CAP_BLIND_ROTATE    (1u << 18)
#define LUX_CAP_POLY_MUL        (1u << 19)
#define LUX_CAP_MLDSA           (1u << 20)
#define LUX_CAP_MLKEM           (1u << 21)
#define LUX_CAP_SLHDSA          (1u << 22)
#define LUX_CAP_RINGTAIL        (1u << 23)
#define LUX_CAP_FROST           (1u << 24)
#define LUX_CAP_CGGMP21         (1u << 25)
#define LUX_CAP_ED25519         (1u << 26)
#define LUX_CAP_SR25519         (1u << 27)
 
// =============================================================================
// Plugin Entry Point
// =============================================================================
 
// Every backend shared library must export this symbol.
// Returns true on success, false if backend unavailable on this system.
typedef bool (*lux_gpu_backend_init_fn)(lux_gpu_backend_desc* out);
 
#define LUX_GPU_BACKEND_INIT_SYMBOL "lux_gpu_backend_init"
 
#ifdef _WIN32
#define LUX_GPU_BACKEND_EXPORT __declspec(dllexport)
#else
#define LUX_GPU_BACKEND_EXPORT __attribute__((visibility("default")))
#endif
 
#ifdef __cplusplus
#define LUX_GPU_DECLARE_BACKEND(init_func)                                     \
    extern "C" LUX_GPU_BACKEND_EXPORT bool                                     \
    lux_gpu_backend_init(lux_gpu_backend_desc* out) { return init_func(out); }
#else
#define LUX_GPU_DECLARE_BACKEND(init_func)                                     \
    LUX_GPU_BACKEND_EXPORT bool                                                \
    lux_gpu_backend_init(lux_gpu_backend_desc* out) { return init_func(out); }
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif // LUX_GPU_BACKEND_PLUGIN_H