Module Native_plugin.Backend

Native Backend - implements BACKEND

val name : string
val version : int * int * int
val is_available : unit -> bool
module Device : sig ... end

Device management

module Stream : sig ... end

Async execution streams / command queues

module Memory : sig ... end

GPU memory allocation and transfer

module Event : sig ... end

Timing events

module Kernel : sig ... end

Kernel compilation and execution

module Async : Spoc_framework.Framework_sig.ASYNC with type device := Device.t and type stream := Stream.t and type event := Event.t and type 'a buffer := 'a Memory.buffer

Ranged / stream-ordered transfers, pinned host memory and inter-stream ordering (see ASYNC). Backends that do not provide them use Async_refused.

val enable_profiling : unit -> unit
val disable_profiling : unit -> unit

The execution model this backend uses

val generate_source : ?block:Spoc_framework.Framework_sig.dims -> ?soa_params:string list -> Sarek_ir_types.kernel -> string option

Generate source code from Sarek IR (for JIT backends). Returns None for Direct/Custom backends.

  • parameter block

    Optional block dimensions (required for Vulkan/GLSL which embeds workgroup size in shader)

  • parameter soa_params

    Names of custom (record) vector parameters to lower as Structure-of-Arrays: each expands to N per-leaf base pointers + one shared length instead of a single packed AoS pointer (the #260 PTX emitter ABI). Honoured only by the CUDA/PTX backend. A backend that cannot honour it must REFUSE a non-empty list rather than ignore it — see Sarek_backend_error.Backend_error.reject_soa_params, which the five source-generating backends without an SoA lowering (CUDA/C, HIP, OpenCL, Vulkan, Metal) call — because emitting AoS source for an SoA argument list is an ABI mismatch that no compiler catches, and what happens next is per backend: rejected at bind or launch on OpenCL and Vulkan; on CUDA/C, HIP and Metal nothing compares the expanded list against the compiled kernel, so the positional shift goes unchecked (backlog-214; Sarek_backend_error.Backend_error.reject_soa_params carries the per-backend detail). The backends that return None unconditionally (Native, Interpreter, WebGPU) generate no source at all and so do not carry that refusal. Defaults to [] (all AoS), so existing callers are byte-identical.

Execute a kernel directly (for Direct/Custom backends). JIT backends should raise an error if this is called. The backend chooses which component to use:

  • Direct backends (Native): use native_fn
  • Custom backends (Interpreter): use ir
  • parameter native_fn

    Pre-compiled OCaml function (from PPX)

  • parameter ir

    Sarek IR kernel (for interpretation)

  • parameter block

    Block dimensions

  • parameter grid

    Grid dimensions

  • parameter args

    Kernel arguments - fully typed

Backend-specific intrinsic registry

External Kernel Execution

val supported_source_langs : Spoc_framework.Framework_sig.source_lang list

List of source languages this backend supports

val run_source : source:string -> lang:Spoc_framework.Framework_sig.source_lang -> kernel_name:string -> block:Spoc_framework.Framework_sig.dims -> grid:Spoc_framework.Framework_sig.dims -> shared_mem:int -> Spoc_framework.Framework_sig.run_source_arg list -> unit

Execute an external kernel from source code.

  • parameter source

    The kernel source code (CUDA/OpenCL/PTX string)

  • parameter lang

    The source language

  • parameter kernel_name

    The name of the kernel function to execute

  • parameter block

    Block dimensions

  • parameter grid

    Grid dimensions

  • parameter shared_mem

    Shared memory size in bytes

  • parameter args

    Kernel arguments as run_source_arg list

  • raises Failure

    if source language is not supported

Kernel Args Wrapping

Type-safe wrapping/unwrapping of backend-specific kernel args into the extensible kargs type. Each backend extends kargs with its own variant.

Wrap this backend's kernel args into a kargs variant

val unwrap_kargs : Spoc_framework.Framework_sig.kargs -> Kernel.args option

Unwrap kargs to this backend's kernel args. Returns None if wrong backend.

Streams and events across module unpackings

val unwrap_event : Spoc_framework.Framework_sig.event_ref -> Event.t option
val run_source_on_stream : stream:Stream.t -> source:string -> lang:Spoc_framework.Framework_sig.source_lang -> kernel_name:string -> block:Spoc_framework.Framework_sig.dims -> grid:Spoc_framework.Framework_sig.dims -> shared_mem:int -> Spoc_framework.Framework_sig.run_source_arg list -> unit

run_source enqueued on stream instead of the default stream. The call may return before the kernel has run. Backends whose async_support.stream_launch is false refuse with Feature_not_supported; Direct/Custom backends (Native, Interpreter) are never called through this entry point — their launches are synchronous.