Storage Types

Backend-specific opaque storage types and static-allocation macros. More...

Collaboration diagram for Storage Types:

Modules
	Heap Gates
	Preprocessor flags indicating which heap-backed _create()/_destroy() functions are compiled.
	OVE_*_DEFINE Macros
	File-scope static storage object declarations.
	OVE_*_DEFINE_STATIC Macros
	One-step static primitive declaration with automatic initialisation.

Macros
#define	OVE_STATIC_INIT_ASSERT(cond)   assert(cond)
	Assertion macro used by static constructor macros on init failure.

Detailed Description

Backend-specific opaque storage types and static-allocation macros.

This header selects the correct backend storage header and exposes:

• Opaque storage types (ove_*_storage_t) — raw byte arrays with the correct size and alignment for each backend's primitive. Use these with _init() functions for zero-heap (static) allocation.
• OVE_*_DEFINE() macros — file-scope convenience wrappers that declare a named storage object of the correct type.
• OVE_*_DEFINE_STATIC() macros — one-step primitives that declare a handle, allocate static storage, and register a C constructor that initialises the handle before main(). Available in both heap and zero-heap modes — the handle is statically allocated either way.

Backend selection

The correct backend header is chosen at build time via the CONFIG_OVE_RTOS_* defines. Foreign-language toolchains use alternate selection logic:

• __BINDGEN__ (Rust bindgen): uses exact build-time sizes from storage_sizes.h generated by ove_rust.cmake.
• __ZIG_CIMPORT__ (Zig @cImport): uses either exact build-time sizes from zig_storage_sizes.h (zero-heap) or minimal 1-byte opaque types (heap mode).

Note

In zero-heap mode (CONFIG_OVE_ZERO_HEAP) the OVE_HEAP_* gates are not defined, so no heap-backed _create()/_destroy() functions are compiled. Application code must use _init() with caller-supplied storage, or the OVE_*_DEFINE_STATIC() macros. Calling a _create() symbol in zero-heap mode is a link error.

Storage-hygiene contract (Phase 5 audit)

Every public _init() function accepts a caller-provided ove_*_storage_t and must not allocate anything itself. The tests/suites/test_init_no_alloc.c regression test enforces this empirically on every backend with -Wl,--wrap=malloc engaged (FreeRTOS-QEMU, Zephyr-QEMU, NuttX-QEMU).

The ove_thread_init() stack-buffer parameter (the final void* argument) has per-backend semantics:

Backend	Uses caller stack?	Notes
FreeRTOS	✅	xTaskCreateStatic consumes it directly.
Zephyr	✅	k_thread_create over the caller's K_THREAD_STACK_DEFINE buffer.
NuttX	⚠ Ignored	task_create() and group_allocate() kmm-alloc internally; documented in nuttx_thread.c. The trap test does not catch this because kmm is not a libc malloc.
POSIX	⚠ Ignored	Host-mode backend; pthread_create manages its own stack.
WASM	⚠ Ignored	Host-mode backend; host pthreads manage stack.

For strict zero-heap deployments: FreeRTOS and Zephyr honor the full storage-hygiene contract including the stack. NuttX's limitation is upstream (kernel group_allocate) and not fixable without forking; POSIX and WASM are host/sim backends with no zero-heap obligation.

Storage struct size stability

The ove_*_storage_t types are concrete (non-opaque) structs whose size is resolvable at C compile time. This is a deliberate ABI commitment: the Zig binding relies on @sizeOf(ove_queue_storage_t) resolving via @cImport at build time, and the Rust binding uses bindgen to derive the same sizes for MaybeUninit<...> wrappers. Making them opaque would be a breaking change that requires adding ove_*_storage_size() runtime queries and rewriting all binding static-allocation paths.

Macro Definition Documentation

OVE_STATIC_INIT_ASSERT

#define OVE_STATIC_INIT_ASSERT

(

cond

)

assert(cond)

Assertion macro used by static constructor macros on init failure.

Defaults to assert(). Define OVE_STATIC_INIT_ASSERT before including any oveRTOS header to override with a custom handler (e.g. a board-specific panic routine).