Backend abstraction layer for libsimcore execution engines. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "oakfield/field.h"
#include "oakfield/kernel_ir.h"

Include dependency graph for backend.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimKernelIRBinding
	Field binding made available to a compiled kernel. More...

struct	SimKernelIROutput
	Output specification emitted by a kernel. More...

struct	KernelIR
	KernelIR package describing the executable graph for a backend. More...

struct	SimBackend
	Runtime backend handle shared across implementations. More...

Typedefs
typedef enum SimBackendType	SimBackendType
	Identifies the concrete backend implementation in use.

typedef enum SimBackendFeature	SimBackendFeature
	Compute backend feature flags indicating supported capabilities.

typedef struct SimKernelIRBinding	SimKernelIRBinding
	Field binding made available to a compiled kernel.

typedef struct SimKernelIROutput	SimKernelIROutput
	Output specification emitted by a kernel.

typedef enum SimKernelComplexSemantics	SimKernelComplexSemantics
	Declares how complex-valued IR lanes should be interpreted by backends.

typedef struct KernelIR	KernelIR
	KernelIR package describing the executable graph for a backend.

typedef struct SimBackend	SimBackend
	Runtime backend handle shared across implementations.

Enumerations
enum	SimBackendType { SIM_BACKEND_TYPE_CPU = 0 , SIM_BACKEND_TYPE_CUDA , SIM_BACKEND_TYPE_METAL }
	Identifies the concrete backend implementation in use. More...

enum	SimBackendFeature { SIM_BACKEND_FEATURE_NONE = 0ULL , SIM_BACKEND_FEATURE_ANALYTIC_WARP = 1ULL << 0 , SIM_BACKEND_FEATURE_BOUNDARY_AWARE_DIFFS = 1ULL << 1 }
	Compute backend feature flags indicating supported capabilities. More...

enum	SimKernelComplexSemantics { SIM_KERNEL_COMPLEX_SEMANTICS_TRUE_COMPLEX = 0 , SIM_KERNEL_COMPLEX_SEMANTICS_COMPONENTWISE }
	Declares how complex-valued IR lanes should be interpreted by backends. More...

Functions
void	backend_init (SimBackend *backend)
	Initialize a backend instance.

void	backend_launch (SimBackend backend, KernelIR kernel)
	Launch a kernel on the selected backend implementation.

void	backend_destroy (SimBackend *backend)
	Tear down a backend instance and release owned resources.

bool	sim_backend_cpu_vdsp_enabled (const SimBackend *backend)
	Query whether the CPU backend currently uses vDSP fast paths.

void	sim_backend_cpu_set_vdsp_enabled (SimBackend *backend, bool enabled)
	Enable or disable vDSP fast paths on the CPU backend at runtime.

Detailed Description

Backend abstraction layer for libsimcore execution engines.

Backends execute KernelIR graphs against bound simulation fields. The public contract is intentionally small: callers initialize a SimBackend, launch a KernelIR package, inspect last_error, and destroy the backend when its implementation-specific resources are no longer needed.

In the standalone CMake package, the CPU backend is the reference backend. CUDA and Metal are experimental optional backends; requests return SIM_RESULT_NOT_FOUND unless the matching optional backend support is compiled in.

Typedef Documentation

◆ KernelIR

typedef struct KernelIR KernelIR

KernelIR package describing the executable graph for a backend.

The package is caller-owned for the duration of backend_launch(). Backends may cache compiled artifacts keyed by the builder and emitted source, but they do not take ownership of fields, bindings, outputs, params, or builder storage.

◆ SimBackend

typedef struct SimBackend SimBackend

Runtime backend handle shared across implementations.

impl is private to the selected backend type. Callers should initialize the handle with backend_init() before launch and release it with backend_destroy().

◆ SimBackendFeature

typedef enum SimBackendFeature SimBackendFeature

Compute backend feature flags indicating supported capabilities.

KernelIR packages can require features such as analytic warp nodes or boundary-aware finite differences. A backend must advertise all required bits before it is a valid execution target for that kernel.

◆ SimKernelComplexSemantics

typedef enum SimKernelComplexSemantics SimKernelComplexSemantics

Declares how complex-valued IR lanes should be interpreted by backends.

True-complex semantics apply complex algebra to two-lane values. Componentwise semantics allow backends to treat each lane independently, which enables simpler pointwise fast paths for selected kernels.

◆ SimKernelIRBinding

typedef struct SimKernelIRBinding SimKernelIRBinding

Field binding made available to a compiled kernel.

Bindings connect KernelIR field identifiers to runtime field storage and layout metadata. Shape and stride arrays are measured in elements, not bytes; when they are NULL, helper code may fall back to the field layout.

◆ SimKernelIROutput

typedef struct SimKernelIROutput SimKernelIROutput

Output specification emitted by a kernel.

Each output writes one expression root to one bound destination field. The destination field must be present in the KernelIR binding table.

Enumeration Type Documentation

◆ SimBackendFeature

enum SimBackendFeature

Compute backend feature flags indicating supported capabilities.

KernelIR packages can require features such as analytic warp nodes or boundary-aware finite differences. A backend must advertise all required bits before it is a valid execution target for that kernel.

Enumerator
SIM_BACKEND_FEATURE_NONE	No optional capabilities.
SIM_BACKEND_FEATURE_ANALYTIC_WARP	Analytic warp IR nodes.
SIM_BACKEND_FEATURE_BOUNDARY_AWARE_DIFFS	Boundary-aware finite differences.

◆ SimBackendType

enum SimBackendType

Identifies the concrete backend implementation in use.

Enumerator
SIM_BACKEND_TYPE_CPU	Scalar CPU reference implementation.
SIM_BACKEND_TYPE_CUDA	CUDA backend using runtime compilation.
SIM_BACKEND_TYPE_METAL	Metal backend using shader templates.

◆ SimKernelComplexSemantics

enum SimKernelComplexSemantics

Declares how complex-valued IR lanes should be interpreted by backends.

True-complex semantics apply complex algebra to two-lane values. Componentwise semantics allow backends to treat each lane independently, which enables simpler pointwise fast paths for selected kernels.

Enumerator
SIM_KERNEL_COMPLEX_SEMANTICS_TRUE_COMPLEX	Use true complex algebra semantics.
SIM_KERNEL_COMPLEX_SEMANTICS_COMPONENTWISE	Treat lanes independently/componentwise.

Function Documentation

◆ backend_destroy()

void backend_destroy ( SimBackend * backend )

Tear down a backend instance and release owned resources.

The handle is left with no advertised features and last_error set to SIM_RESULT_OK. Passing NULL is a no-op.

Parameters

[in,out] backend Backend instance to destroy.

◆ backend_init()

void backend_init ( SimBackend * backend )

Initialize a backend instance.

The requested backend->type selects CPU, CUDA, or Metal. Unknown types are normalized to CPU. On failure, SimBackend::last_error stores the encountered error code and backend-specific implementation storage is not considered valid.

Parameters

[in,out] backend Backend instance to initialize.

◆ backend_launch()

void backend_launch	(	SimBackend *	backend,
		KernelIR *	kernel
	)

Launch a kernel on the selected backend implementation.

The backend writes results into the fields named by kernel->outputs. On failure, SimBackend::last_error stores the encountered error code.

Parameters

[in,out]	backend	Backend instance executing the kernel.
[in,out]	kernel	Kernel description to execute; storage remains caller-owned.

◆ sim_backend_cpu_set_vdsp_enabled()

void sim_backend_cpu_set_vdsp_enabled	(	SimBackend *	backend,
		bool	enabled
	)

Enable or disable vDSP fast paths on the CPU backend at runtime.

Calls against non-CPU backends or builds without vDSP support are ignored.

Parameters

backend	Backend to mutate.
enabled	Whether vDSP fast paths should be attempted.

◆ sim_backend_cpu_vdsp_enabled()

bool sim_backend_cpu_vdsp_enabled ( const SimBackend * backend )

Query whether the CPU backend currently uses vDSP fast paths.

Parameters

backend Backend to inspect.

Returns: True only for initialized CPU backends compiled with vDSP support and currently configured to use those paths.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ KernelIR

◆ SimBackend

◆ SimBackendFeature

◆ SimKernelComplexSemantics

◆ SimKernelIRBinding

◆ SimKernelIROutput

Enumeration Type Documentation

◆ SimBackendFeature

◆ SimBackendType

◆ SimKernelComplexSemantics

Function Documentation

◆ backend_destroy()

◆ backend_init()

◆ backend_launch()

◆ sim_backend_cpu_set_vdsp_enabled()

◆ sim_backend_cpu_vdsp_enabled()