ove/

macros.rs

// Copyright (C) 2026 Kamil Lulko <kamil.lulko@gmail.com>
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// This file is part of oveRTOS.

//! User-facing macros for the oveRTOS Rust SDK.
//!
//! All `#[macro_export]` macros are re-exported at crate root, so the
//! location of this file is purely organizational.

/// Generate `Drop` and thread-safety impls (plus `Debug` for the
/// non-generic forms) for an oveRTOS handle wrapper struct that stores a
/// nullable handle in a field named `handle`.
///
/// # Variants
///
/// - `(Name, destroy_fn, deinit_fn)` — emits `Debug`, `Drop`, `Send`, `Sync`.
/// - `(Name, destroy_fn, deinit_fn, send_only)` — emits `Debug`, `Drop`,
///   `Send`. No `Sync` impl.
/// - `(Name<const N: usize>, destroy_fn, deinit_fn)` — const-generic;
///   emits `Drop`, `Send`, `Sync` only (no `Debug`).
#[doc(hidden)]
#[macro_export]
macro_rules! ove_handle_impl {
    // Non-generic, Send + Sync
    ($name:ident, $destroy:ident, $deinit:ident) => {
        $crate::ove_handle_impl!(@debug $name);
        $crate::ove_handle_impl!(@drop $name, $destroy, $deinit);
        unsafe impl Send for $name {}
        unsafe impl Sync for $name {}
    };

    // Non-generic, Send only (no Sync)
    ($name:ident, $destroy:ident, $deinit:ident, send_only) => {
        $crate::ove_handle_impl!(@debug $name);
        $crate::ove_handle_impl!(@drop $name, $destroy, $deinit);
        unsafe impl Send for $name {}
    };

    // Const-generic, Send + Sync
    ($name:ident<const $N:ident: usize>, $destroy:ident, $deinit:ident) => {
        impl<const $N: usize> Drop for $name<$N> {
            fn drop(&mut self) {
                if self.handle.is_null() { return; }
                #[cfg(not(zero_heap))]
                unsafe { $crate::bindings::$destroy(self.handle) }
                #[cfg(zero_heap)]
                unsafe { $crate::bindings::$deinit(self.handle) }
            }
        }
        unsafe impl<const $N: usize> Send for $name<$N> {}
        unsafe impl<const $N: usize> Sync for $name<$N> {}
    };

    (@debug $name:ident) => {
        impl core::fmt::Debug for $name {
            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                f.debug_struct(stringify!($name))
                    .field("handle", &format_args!("{:p}", self.handle))
                    .finish()
            }
        }
    };

    (@drop $name:ident, $destroy:ident, $deinit:ident) => {
        impl Drop for $name {
            fn drop(&mut self) {
                if self.handle.is_null() { return; }
                #[cfg(not(zero_heap))]
                unsafe { $crate::bindings::$destroy(self.handle) }
                #[cfg(zero_heap)]
                unsafe { $crate::bindings::$deinit(self.handle) }
            }
        }
    };
}

// Legacy `log_fmt!`/`log_inf!`/`log_wrn!`/`log_err!` macros deleted in
// favour of the `log` crate facade.  See `ove::log` for the `log::Log`
// backend; call `ove::log::init()` once in `ove_main`, then use
// `log::info!`/`warn!`/`error!`/`debug!`/`trace!` like any other Rust
// crate.

/// Declare a safe accessor for TFLite model data generated by `convert.py`.
///
/// Generates the `extern "C"` linkage for the `_model_data` and
/// `_model_data_len` symbols and wraps them in a function returning
/// `&'static [u8]`.  No `extern` or `unsafe` needed in application code.
///
/// # Example
///
/// ```ignore
/// ove::model_data!(preprocessor_model,
///     g_audio_preprocessor_int8_model_data,
///     g_audio_preprocessor_int8_model_data_len);
///
/// let data: &[u8] = preprocessor_model();
/// ```
#[macro_export]
macro_rules! model_data {
    ($fn_name:ident, $data_sym:ident, $len_sym:ident) => {
        unsafe extern "C" {
            safe static $data_sym: u8;
            safe static $len_sym: u32;
        }
        fn $fn_name() -> &'static [u8] {
            unsafe { core::slice::from_raw_parts(&$data_sym, $len_sym as usize) }
        }
    };
}

// Legacy `ove::main!(fn_name)` declarative macro deleted in favour of
// the `#[ove::main]` proc-macro attribute provided by the `ove-macros`
// crate (re-exported at the crate root in `lib.rs`).
//
// Migration:
//   fn app_main() { ... }
//   ove::main!(app_main);
// becomes
//   #[ove::main]
//   fn app_main() { ... }
//
// Lifetime caveat (same for both forms): anything worker threads
// access after `app_main` returns must have `'static` storage — use
// `static`/`InitCell`/`InitMut` cells.  A stack-local value in
// `app_main` is dropped when the function unwinds; a thread that
// captured a reference into it dangles.  On FreeRTOS the failure is
// immediate (scheduler reclaims the main stack); on POSIX/NuttX/Zephyr
// the UB is latent.

// ---------------------------------------------------------------------------
// Unified creation macros
//
// These macros work in both heap and zero-heap modes. In heap mode they call
// `new()`. In zero-heap mode they declare function-local `static` storage
// and call `from_static()`.
// ---------------------------------------------------------------------------

/// Create a [`crate::Mutex<T>`] around `$val` that works in both heap and
/// zero-heap modes.
///
/// Use `()` as the value for a "no-data" lock (i.e. `Mutex<()>` used
/// purely to synchronise access to other state) — matches
/// `std::sync::Mutex<()>` / `parking_lot::Mutex<()>` convention.
#[cfg(has_sync)]
#[macro_export]
macro_rules! mutex {
    ($val:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Mutex::new($val).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_mutex_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::Mutex::from_static(core::ptr::addr_of_mut!(_S), $val) }.unwrap()
        }
    }};
}

/// Create a [`crate::RecursiveMutex`] that works in both heap and zero-heap modes.
#[cfg(has_sync)]
#[macro_export]
macro_rules! recursive_mutex {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::RecursiveMutex::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_mutex_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::RecursiveMutex::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create a [`crate::Semaphore`] that works in both heap and zero-heap modes.
#[cfg(has_sync)]
#[macro_export]
macro_rules! semaphore {
    ($initial:expr, $max:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Semaphore::new($initial, $max).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_sem_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::Semaphore::from_static(core::ptr::addr_of_mut!(_S), $initial, $max) }
                .unwrap()
        }
    }};
}

/// Create an [`crate::Event`] that works in both heap and zero-heap modes.
#[cfg(has_sync)]
#[macro_export]
macro_rules! event {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Event::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_event_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::Event::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create a [`crate::CondVar`] that works in both heap and zero-heap modes.
#[cfg(has_sync)]
#[macro_export]
macro_rules! condvar {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::CondVar::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_condvar_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::CondVar::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create an [`crate::EventGroup`] that works in both heap and zero-heap modes.
#[cfg(has_eventgroup)]
#[macro_export]
macro_rules! eventgroup {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::EventGroup::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_eventgroup_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::EventGroup::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create a [`crate::audio::Graph`] that works in both heap and zero-heap modes.
///
/// Mirrors the C `ove_audio_graph_create(pg, frames, nodes, channels,
/// sample_bytes)` macro: in zero-heap mode emits a per-call-site `static`
/// backing array sized by `nodes * frames * channels * sample_bytes` bytes
/// and attaches it to the graph automatically; in heap mode just calls
/// [`crate::audio::Graph::new`].  Yields a [`crate::Result`] wrapping a
/// [`crate::audio::Graph`].
///
/// All arguments must be constant expressions.
///
/// # Example
/// ```ignore
/// // 2 non-sink nodes (source + processor), 512 frames, mono, S16 (2 bytes).
/// let mut graph = ove::audio_graph!(512, 2, 1, 2)?;
/// ```
#[cfg(has_audio)]
#[macro_export]
macro_rules! audio_graph {
    ($frames:expr, $nodes:expr, $channels:expr, $sample_bytes:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::audio::Graph::new($frames)
        }
        #[cfg(zero_heap)]
        {
            const _STORAGE_BYTES: usize =
                ($nodes) * ($frames) as usize * ($channels) * ($sample_bytes);
            #[repr(C, align(4))]
            struct _AudioBufStorage([u8; _STORAGE_BYTES]);
            static mut _AUDIO_BUF: _AudioBufStorage = _AudioBufStorage([0; _STORAGE_BYTES]);
            let slice: &'static mut [u8] = unsafe {
                core::slice::from_raw_parts_mut(
                    core::ptr::addr_of_mut!(_AUDIO_BUF) as *mut u8,
                    _STORAGE_BYTES,
                )
            };
            $crate::audio::Graph::new_with_storage($frames, slice)
        }
    }};
}

/// Create a [`crate::Queue`] that works in both heap and zero-heap modes.
///
/// # Example
/// ```ignore
/// let q = ove::queue!(u32, 8);
/// ```
#[cfg(has_queue)]
#[macro_export]
macro_rules! queue {
    ($T:ty, $N:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Queue::<$T, $N>::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_queue_storage_t = unsafe { core::mem::zeroed() };
            static mut _B: [core::mem::MaybeUninit<$T>; $N] =
                unsafe { core::mem::MaybeUninit::uninit().assume_init() };
            unsafe {
                $crate::Queue::<$T, $N>::from_static(
                    core::ptr::addr_of_mut!(_S),
                    core::ptr::addr_of_mut!(_B) as *mut _,
                )
            }
            .unwrap()
        }
    }};
}

/// Create a [`crate::Timer`] that works in both heap and zero-heap modes.
///
/// # Example
/// ```ignore
/// let t = ove::timer!(my_callback, 100, false);
/// ```
#[cfg(has_timer)]
#[macro_export]
macro_rules! timer {
    ($callback:expr, $period_ms:expr, $one_shot:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Timer::new($callback, $period_ms, $one_shot).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_timer_storage_t = unsafe { core::mem::zeroed() };
            unsafe {
                $crate::Timer::from_static(
                    core::ptr::addr_of_mut!(_S),
                    $callback,
                    $period_ms,
                    $one_shot,
                )
            }
            .unwrap()
        }
    }};
}

/// Create a [`crate::JoinHandle`] for a thread that works in both heap
/// and zero-heap modes.
///
/// Uses the safe `fn()` entry pattern (no `StopToken`). The name is
/// automatically null-terminated.  In zero-heap mode the storage is
/// emitted as a `static $crate::ThreadStorage<$stack>` and passed by
/// reference to [`crate::Builder::spawn_static_simple`] — no `static mut`,
/// no `addr_of_mut!`, no `unsafe` in user-visible expansion.
///
/// # Example
/// ```ignore
/// let h = ove::thread!("worker", my_entry, Priority::Normal, 4096);
/// h.detach();  // fire-and-forget; or store in InitCell<JoinHandle<()>>.
/// ```
#[macro_export]
macro_rules! thread {
    ($name:expr, $entry:expr, $prio:expr, $stack:expr) => {{
        // SAFETY: `concat!($name, "\0")` is a comptime literal that ends
        // with a single nul; the caller's $name must not contain inner
        // nuls (responsibility of the macro caller — same as today).
        let _name = unsafe {
            core::ffi::CStr::from_bytes_with_nul_unchecked(concat!($name, "\0").as_bytes())
        };
        #[cfg(not(zero_heap))]
        {
            $crate::Thread::builder()
                .name(_name)
                .priority($prio)
                .stack_size($stack)
                .spawn_simple($entry)
                .unwrap()
        }
        #[cfg(zero_heap)]
        {
            static _STORAGE: $crate::ThreadStorage<$stack> = $crate::ThreadStorage::new();
            $crate::Thread::builder()
                .name(_name)
                .priority($prio)
                .spawn_static_simple(&_STORAGE, $entry)
                .unwrap()
        }
    }};
}

/// Create a [`crate::Stream`] that works in both heap and zero-heap modes.
///
/// # Example
/// ```ignore
/// let s = ove::stream!(256, 1);
/// ```
#[cfg(has_stream)]
#[macro_export]
macro_rules! stream {
    ($N:expr, $trigger:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Stream::<$N>::new($trigger).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_stream_storage_t = unsafe { core::mem::zeroed() };
            static mut _B: [u8; $N] = [0u8; $N];
            unsafe {
                $crate::Stream::<$N>::from_static(
                    core::ptr::addr_of_mut!(_S),
                    core::ptr::addr_of_mut!(_B) as *mut _,
                    $trigger,
                )
            }
            .unwrap()
        }
    }};
}

/// Create a [`crate::Workqueue`] that works in both heap and zero-heap modes.
///
/// `$name` must be a `c"..."` literal — the underlying API requires a
/// null-terminated string and the C-string literal makes the compiler
/// enforce that.
///
/// # Example
/// ```ignore
/// let wq = ove::workqueue!(c"myq", Priority::Normal, 4096);
/// ```
#[cfg(has_workqueue)]
#[macro_export]
macro_rules! workqueue {
    ($name:expr, $prio:expr, $stack:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Workqueue::new($name, $prio, $stack).unwrap()
        }
        #[cfg(all(zero_heap, not(rtos_zephyr)))]
        {
            static mut _S: $crate::ffi::ove_workqueue_storage_t = unsafe { core::mem::zeroed() };
            // 8-byte align (ARM AAPCS) is sufficient on FreeRTOS/NuttX/POSIX.
            #[repr(C, align(8))]
            struct AlignedStack([u8; $stack]);
            static mut _STACK: AlignedStack = AlignedStack([0u8; $stack]);
            unsafe {
                $crate::Workqueue::from_static(
                    core::ptr::addr_of_mut!(_S),
                    $name,
                    $prio,
                    $stack,
                    core::ptr::addr_of_mut!(_STACK) as *mut _,
                )
            }
            .unwrap()
        }
        #[cfg(all(zero_heap, rtos_zephyr))]
        {
            // Zephyr workqueues run on a kernel thread; the stack needs
            // the same MPU treatment as `thread!` — power-of-2 aligned
            // and rounded up by a 128-byte FPU guard pad.  Without
            // this, the workqueue crashes inside `z_reset_time_slice`
            // on the first work-handler dispatch.
            static mut _S: $crate::ffi::ove_workqueue_storage_t = unsafe { core::mem::zeroed() };
            const _STACK_TOTAL: usize = ($stack + 128usize).next_power_of_two();
            #[repr(C, align(8192))]
            struct ZStack([u8; _STACK_TOTAL]);
            static mut _STACK: ZStack = ZStack([0u8; _STACK_TOTAL]);
            unsafe {
                $crate::Workqueue::from_static(
                    core::ptr::addr_of_mut!(_S),
                    $name,
                    $prio,
                    $stack,
                    core::ptr::addr_of_mut!(_STACK) as *mut _,
                )
            }
            .unwrap()
        }
    }};
}

/// Wrap a safe Rust `fn()` into an `ove_work_fn` C trampoline.
///
/// The oveRTOS C work handler has no `user_data` slot, so this just
/// generates a `unsafe extern "C"` trampoline that calls the supplied
/// safe function. Use this with [`crate::work!`] so app code never has to write
/// `unsafe extern "C"` itself.
///
/// # Example
/// ```ignore
/// fn on_work() { /* ... */ }
/// let w = ove::work!(ove::work_handler!(on_work));
/// ```
#[cfg(has_workqueue)]
#[macro_export]
macro_rules! work_handler {
    ($f:ident) => {{
        unsafe extern "C" fn _tramp(_w: $crate::ffi::ove_work_t) {
            $f();
        }
        Some(_tramp as unsafe extern "C" fn($crate::ffi::ove_work_t))
    }};
}

/// Create a [`crate::Work`] item that works in both heap and zero-heap modes.
///
/// The handler must be an `ove_work_fn` (an `unsafe extern "C" fn`). To
/// avoid writing that yourself, wrap a safe `fn()` with [`work_handler!`].
#[cfg(has_workqueue)]
#[macro_export]
macro_rules! work {
    ($handler:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Work::new($handler).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_work_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::Work::from_static(core::ptr::addr_of_mut!(_S), $handler) }.unwrap()
        }
    }};
}

/// Create a [`crate::Watchdog`] that works in both heap and zero-heap modes.
///
/// The argument is the timeout in **milliseconds**, matching
/// [`crate::Watchdog::new`].
#[cfg(has_watchdog)]
#[macro_export]
macro_rules! watchdog {
    ($timeout_ns:expr) => {{
        #[cfg(not(zero_heap))]
        {
            $crate::Watchdog::new($timeout_ns).unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_watchdog_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::Watchdog::from_static(core::ptr::addr_of_mut!(_S), $timeout_ns) }
                .unwrap()
        }
    }};
}

/// Declare a `static` wrapped in [`crate::InitCell`] for cross-thread shared state.
///
/// # Example
/// ```ignore
/// ove::shared!(QUEUE: Queue<u32, 8>);
/// // then use QUEUE.send(...) directly — Deref eliminates .get()
/// ```
#[macro_export]
macro_rules! shared {
    ($vis:vis $name:ident : $ty:ty) => {
        $vis static $name: $crate::InitCell<$ty> = $crate::InitCell::new();
    };
}

/// Declare a `static` wrapped in [`crate::InitMut`] for single-owner mutable state.
///
/// # Example
/// ```ignore
/// ove::shared_mut!(ENGINE: DspEngine);
/// ```
#[macro_export]
macro_rules! shared_mut {
    ($vis:vis $name:ident : $ty:ty) => {
        $vis static $name: $crate::InitMut<$ty> = $crate::InitMut::new();
    };
}

/// Declare a `static` [`crate::lvgl::EventHandler<T>`] for LVGL event callbacks.
///
/// Bundles a `&'static InitCell<T>` of shared state with a safe
/// `fn(&T, EventCtx)` callback. Pass the resulting static to
/// [`EventTarget::on_with`](crate::lvgl::EventTarget::on_with) or
/// [`EventTarget::on_clicked_with`](crate::lvgl::EventTarget::on_clicked_with).
///
/// # Example
/// ```ignore
/// struct NavState { page: i32 }
/// ove::shared!(NAV: ove::lvgl::LvCell<NavState>);
/// fn on_next(state: &ove::lvgl::LvCell<NavState>, _e: ove::lvgl::EventCtx<'_>) {
///     state.update(|s| NavState { page: s.page + 1 });
/// }
/// ove::event_handler!(NAV_NEXT: LvCell<NavState> = &NAV, on_next);
/// // ...later: button.on_clicked_with(&NAV_NEXT);
/// ```
#[cfg(has_lvgl)]
#[macro_export]
macro_rules! event_handler {
    ($vis:vis $name:ident : $t:ty = $cell:expr, $fn:expr) => {
        $vis static $name: $crate::lvgl::EventHandler<$t> =
            $crate::lvgl::EventHandler::new($cell, $fn);
    };
}

/// Create a [`crate::net_tls::Session`] that works in both heap and zero-heap
/// modes.  In zero-heap mode the session draws its mbedTLS state from a
/// file-scope static and the per-protocol static buffer
/// (`CONFIG_OVE_NET_TLS_HEAP_SIZE`).
#[cfg(has_net_tls)]
#[macro_export]
macro_rules! tls_session {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::net_tls::Session::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_tls_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::net_tls::Session::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create a [`crate::net_http::Client`] that works in both heap and zero-heap
/// modes.  In zero-heap mode the response body and headers borrow into the
/// client's embedded `_resp_buf[CONFIG_OVE_NET_HTTP_MAX_RESPONSE]` and are
/// valid until the next request.
#[cfg(has_net_http)]
#[macro_export]
macro_rules! http_client {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::net_http::Client::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_http_client_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::net_http::Client::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}

/// Create a [`crate::net_mqtt::Client`] that works in both heap and zero-heap
/// modes.  In zero-heap mode the per-connection RX/TX buffers
/// (`CONFIG_OVE_NET_MQTT_RX_BUF` / `CONFIG_OVE_NET_MQTT_TX_BUF`) live in the
/// client storage.
#[cfg(has_net_mqtt)]
#[macro_export]
macro_rules! mqtt_client {
    () => {{
        #[cfg(not(zero_heap))]
        {
            $crate::net_mqtt::Client::new().unwrap()
        }
        #[cfg(zero_heap)]
        {
            static mut _S: $crate::ffi::ove_mqtt_client_storage_t = unsafe { core::mem::zeroed() };
            unsafe { $crate::net_mqtt::Client::from_static(core::ptr::addr_of_mut!(_S)) }.unwrap()
        }
    }};
}