kernel_loader.h

Go to the documentation of this file.

// Copyright (c) 2024-2026 Lux Industries Inc.
// SPDX-License-Identifier: BSD-3-Clause-Eco
//
// Kernel Loader - Generic GPU kernel loading and caching infrastructure
//
// Provides unified interface for loading GPU kernels from:
//   - Embedded strings (build-time compiled)
//   - Source files (runtime compiled)
//   - Binary blobs (pre-compiled .metallib, PTX, SPIR-V)
//
// Supports kernel variants keyed by (name, dtype, size) tuples.
 
#ifndef LUX_GPU_KERNEL_LOADER_H
#define LUX_GPU_KERNEL_LOADER_H
 
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
// =============================================================================
// Kernel Types
// =============================================================================
 
typedef enum {
    LUX_KERNEL_SOURCE_EMBEDDED = 0,  // Embedded as string constant
    LUX_KERNEL_SOURCE_FILE = 1,      // Load from file path
    LUX_KERNEL_SOURCE_BINARY = 2,    // Pre-compiled binary blob
} LuxKernelSourceType;
 
typedef enum {
    LUX_KERNEL_LANG_METAL = 0,
    LUX_KERNEL_LANG_CUDA = 1,
    LUX_KERNEL_LANG_PTX = 2,
    LUX_KERNEL_LANG_WGSL = 3,
    LUX_KERNEL_LANG_SPIRV = 4,
} LuxKernelLanguage;
 
// Kernel variant key for caching
typedef struct {
    const char* name;       // Kernel function name
    uint32_t dtype;         // Data type (LuxDtype)
    uint32_t size_hint;     // Size variant (0 = default)
    uint32_t flags;         // Additional flags
} LuxKernelVariant;
 
// Kernel source descriptor
typedef struct {
    LuxKernelSourceType type;
    LuxKernelLanguage lang;
    const char* source;         // Source string or file path
    size_t source_len;          // Length (0 = null-terminated)
    const void* binary;         // Binary data (for BINARY type)
    size_t binary_len;
    const char* entry_point;    // Entry function name
    const char* compile_opts;   // Compiler options (nullable)
} LuxKernelSource;
 
// Opaque kernel handle
typedef struct LuxKernel LuxKernel;
 
// Kernel cache (opaque)
typedef struct LuxKernelCache LuxKernelCache;
 
// =============================================================================
// Kernel Registry (embedded kernels)
// =============================================================================
 
// Embedded kernel entry (generated at build time)
typedef struct {
    const char* name;           // Kernel family name (e.g., "binary_add")
    const char* entry_point;    // Entry function name
    LuxKernelLanguage lang;
    const char* source;         // Embedded source string
    size_t source_len;
    const void* binary;         // Pre-compiled binary (nullable)
    size_t binary_len;
} LuxEmbeddedKernel;
 
// Registry of all embedded kernels (generated by CMake)
typedef struct {
    const char* backend;            // "metal", "cuda", "webgpu"
    const LuxEmbeddedKernel* kernels;
    size_t count;
} LuxKernelRegistry;
 
// Get embedded kernel registry for backend
const LuxKernelRegistry* lux_kernel_registry_get(const char* backend);
 
// Find kernel by name in registry
const LuxEmbeddedKernel* lux_kernel_registry_find(
    const LuxKernelRegistry* registry,
    const char* name
);
 
// =============================================================================
// Kernel Cache API
// =============================================================================
 
// Create kernel cache
LuxKernelCache* lux_kernel_cache_create(void);
 
// Destroy kernel cache
void lux_kernel_cache_destroy(LuxKernelCache* cache);
 
// Get cached kernel by variant
LuxKernel* lux_kernel_cache_get(
    LuxKernelCache* cache,
    const LuxKernelVariant* variant
);
 
// Store kernel in cache
void lux_kernel_cache_put(
    LuxKernelCache* cache,
    const LuxKernelVariant* variant,
    LuxKernel* kernel
);
 
// Clear all cached kernels
void lux_kernel_cache_clear(LuxKernelCache* cache);
 
// Get cache statistics
void lux_kernel_cache_stats(
    LuxKernelCache* cache,
    size_t* count,
    size_t* memory_bytes
);
 
// =============================================================================
// Kernel Loader API (backend-specific implementations)
// =============================================================================
 
// Compile kernel from source
LuxKernel* lux_kernel_compile(
    void* device_context,   // Backend-specific device
    const LuxKernelSource* source
);
 
// Load kernel from binary
LuxKernel* lux_kernel_load_binary(
    void* device_context,
    const void* binary,
    size_t binary_len,
    const char* entry_point
);
 
// Destroy kernel
void lux_kernel_destroy(LuxKernel* kernel);
 
// Get kernel entry point name
const char* lux_kernel_entry_point(LuxKernel* kernel);
 
// =============================================================================
// Utility Macros for Embedded Kernels
// =============================================================================
 
// Declare embedded kernel (used in generated headers)
#define LUX_DECLARE_KERNEL(name, lang) \
    extern const char lux_kernel_##name##_source[]; \
    extern const size_t lux_kernel_##name##_source_len;
 
// Define embedded kernel source
#define LUX_DEFINE_KERNEL(name, source_str) \
    const char lux_kernel_##name##_source[] = source_str; \
    const size_t lux_kernel_##name##_source_len = sizeof(lux_kernel_##name##_source) - 1;
 
// Kernel registry entry
#define LUX_KERNEL_ENTRY(name, entry, lang) \
    { #name, entry, lang, lux_kernel_##name##_source, lux_kernel_##name##_source_len, NULL, 0 }
 
// Binary kernel registry entry
#define LUX_KERNEL_ENTRY_BINARY(name, entry, lang, bin, bin_len) \
    { #name, entry, lang, NULL, 0, bin, bin_len }
 
#ifdef __cplusplus
}
#endif
 
#endif // LUX_GPU_KERNEL_LOADER_H