nros_platform_api/

lib.rs

//! Platform capability sub-traits for nros.
//!
//! This crate exists to break the dependency cycle between
//! `nros-platform` (which depends on every platform crate via its
//! feature-gated `ConcretePlatform` resolver) and the platform crates
//! themselves (which need to implement these traits on their ZSTs).
//! It contains only trait definitions — no implementations, no
//! dependencies — so platform crates can take a build-time dep on it
//! without creating a cycle back through `nros-platform`.
//!
//! `nros-platform` re-exports everything from this crate, so downstream
//! code that writes `use nros_platform::PlatformClock;` continues to
//! work unchanged.
//!
//! Each trait covers an independent system capability. Platform
//! implementations pick which traits to implement based on what the
//! hardware/RTOS provides. RMW shim crates declare trait bounds for
//! the capabilities they need.

#![no_std]
//!
//! # Naming convention
//!
//! Method names drop redundant prefixes when the trait name already
//! supplies the namespace — e.g., `PlatformTcp::open` rather than
//! `PlatformTcp::tcp_open`. Dispatch is always through a qualified
//! path (`<ConcretePlatform as PlatformTcp>::open(...)`), so
//! trait-to-trait collisions (PlatformTcp::open vs PlatformUdp::open)
//! are disambiguated at the call site without needing a prefix on the
//! trait method itself.
//!
//! Three categories still keep sub-namespace prefixes internally:
//!
//! * `PlatformThreading` — `mutex_*`, `condvar_*`, `task_*` because the
//!   trait bundles three independent primitive families and unprefixed
//!   `init` / `drop` would be ambiguous *within* the trait itself.
//! * `PlatformUdpMulticast` — `mcast_*` because these methods have
//!   different signatures from `PlatformUdp`'s same-name methods; keeping
//!   the prefix makes call sites that use both traits self-documenting.
//! * The `close` method appears on both `PlatformTcp` and
//!   `PlatformSocketHelpers` — the first is TCP teardown, the second is
//!   zenoh-pico's generic "shutdown + close" helper. Both live unprefixed
//!   in their respective traits; call sites disambiguate via the
//!   qualified path.
//!
//! # Status (Phase 84.F4)
//!
//! The platform ZSTs (`PosixPlatform`, `ZephyrPlatform`, etc.) do **not**
//! currently implement these traits — every platform exposes its methods
//! as *inherent* `impl Platform { fn foo() {} }` blocks, and shim crates
//! dispatch by name match. 84.F4 migrates each platform to `impl
//! PlatformX for Platform { fn foo() {} }` one trait at a time, with the
//! shims switching to `<P as PlatformX>::foo()`. Until that work is
//! complete the traits here are a target specification.

// phase-359 W10 — the ONE Rust-side spawn helper for the task ABI this crate
// defines. It lived in `nros-node::executor::platform_task`, private, which
// meant the second Rust caller (`nros-cpp`'s native tier runtime) could only
// reach it by exposing a core crate's internals or by writing a third copy of
// allocate-spawn-join — `nros-board-nuttx` already holds a second. A helper for
// an ABI belongs with the ABI.
#[cfg(feature = "alloc")]
extern crate alloc;
// The module is NOT `alloc`-gated; `PlatformTask` inside it is. Gating the whole
// module put `stack_unused_bytes` — a bare `extern` query that allocates nothing
// — behind `alloc`, so `Executor::check_stack_headroom_rule` failed to compile
// in every no-alloc image. That is the build where stack headroom matters most,
// and the rule was unreachable there (phase-425 sweep; the lane that catches it,
// `check workspace-embedded`, runs in no merge-gating event).
pub mod task;

use core::ffi::{c_int, c_void};

pub mod boot_config;
pub mod wake;
pub mod xorshift32;

pub use boot_config::{
    BOOT_SET_DOMAIN, BOOT_SET_LOCATOR, BOOT_SET_NAMESPACE, BOOT_SET_NODE_NAME, BOOT_SET_RMW,
    BakedBootConfig, NROS_BOOT_CONFIG_MAGIC, NROS_BOOT_CONFIG_VERSION,
};
pub use wake::{WAKE_STORAGE_ALIGN, WAKE_STORAGE_BYTES, Wake, WakeInitError, WakeReason};

// ============================================================================
// Clock (required by all RMW backends)
// ============================================================================

/// Monotonic clock.
///
/// The most critical platform primitive. Must be backed by a hardware timer
/// or OS tick — never by a software counter that only advances when polled.
pub trait PlatformClock {
    /// Monotonic nanoseconds since a platform-defined epoch. Never
    /// decreases. See `<nros/platform.h>` for the full contract
    /// (RFC-0073).
    fn clock_ns() -> u64;

    /// Granularity of [`Self::clock_ns`] in nanoseconds: the smallest
    /// non-zero difference two successive reads can report. Non-zero,
    /// and constant after platform init.
    fn clock_resolution_ns() -> u64;

    /// Microseconds since the UNIX epoch, or `0` when this platform has no
    /// wall-clock source. See `<nros/platform.h>` for the full contract
    /// (issue 0758).
    ///
    /// DEFAULTED to `0` deliberately. Every existing port is correct
    /// without changing a line: none of them has an epoch source today, and
    /// `0` is precisely the honest answer. Making this a required method
    /// would have forced eleven ports to write `0` by hand, which is the
    /// same information spelled eleven times plus eleven chances to write
    /// something else.
    ///
    /// It is also the difference between an ABI addition that is a
    /// no-op for ports and one that breaks every image that has not caught
    /// up — and the C side has no such default, so a port implemented in C
    /// DOES say `0` explicitly.
    ///
    /// Unlike [`Self::clock_ns`] this is not monotonic: a port that
    /// acquires its epoch after boot jumps when it does.
    fn epoch_us() -> u64 {
        0
    }
}

// ============================================================================
// Heap allocation (zenoh-pico requires ~64 KB heap)
// ============================================================================

/// Heap memory allocation.
pub trait PlatformAlloc {
    /// Allocate `size` bytes. Returns null on failure.
    fn alloc(size: usize) -> *mut c_void;

    /// Reallocate a previously allocated block. Returns null on failure.
    fn realloc(ptr: *mut c_void, size: usize) -> *mut c_void;

    /// Free a previously allocated block.
    fn dealloc(ptr: *mut c_void);

    /// Phase 230 Z5 / RFC-0034 D7 — bytes currently allocated from the
    /// platform heap. The true unified figure where the platform owns one
    /// kernel heap shared by the C side (`alloc`) and the Rust
    /// `#[global_allocator]`. Default `0` = "unknown / not instrumented".
    fn heap_used_bytes() -> usize {
        0
    }

    /// Total managed heap size in bytes (used + free), or `0` if unknown.
    fn heap_total_bytes() -> usize {
        0
    }
}

// ============================================================================
// Fatal error
// ============================================================================

/// The image's one ending — phase-366 / RFC-0077.
///
/// Mirrors `nros_platform_panic` in `<nros/platform.h>`. Rust's
/// `#[panic_handler]`, a C precondition failure and a C++ terminate all arrive
/// here, so an image has one fatal path instead of one per language.
///
/// The ABI could express ALLOCATION but not fatality, so each language invented
/// its own ending and four libraries each hardcoded a different one. This is the
/// missing half.
pub trait PlatformPanic {
    /// Terminate the image. Never returns.
    ///
    /// `msg` is a DIAGNOSTIC, not a C string: `len` bytes, no NUL required,
    /// possibly empty, and not necessarily UTF-8 — a port forwarding to a text
    /// sink should treat it as bytes.
    ///
    /// Implementors must tolerate being called from ANY context: interrupt,
    /// scheduler locked, or before the kernel starts. That rules out anything
    /// needing a scheduler, which is why this is not "log at Fatal, then halt".
    ///
    /// Implementors SHOULD emit `msg` where a human can read it first. A silent
    /// halt is the one behaviour no RTOS in this tree chose for itself.
    fn panic(msg: *const u8, len: usize) -> !;
}

// ============================================================================
// Sleep / delay
// ============================================================================

/// Sleep primitives.
///
/// On bare-metal with smoltcp, implementations should poll the network
/// stack during busy-wait sleep to avoid missing packets.
pub trait PlatformSleep {
    /// Sleep for the given number of microseconds.
    fn sleep_us(us: usize);

    /// Sleep for the given number of milliseconds.
    fn sleep_ms(ms: usize);

    /// Sleep for the given number of seconds.
    fn sleep_s(s: usize);
}

// ============================================================================
// Cooperative yield
// ============================================================================

/// Scheduler yield primitive.
///
/// Used inside `socket_wait_event` and similar "let another task make
/// progress" points where the caller isn't actually waiting for I/O
/// readability — the background read task already owns that — it just
/// needs to relinquish the CPU so the real waiter can run.
///
/// Prior to Phase 77.22 each backend hand-rolled its own 1-ms busy
/// sleep (`libc::usleep(1000)`, `vTaskDelay(1)`, `tx_thread_sleep(1)`,
/// `k_usleep(1000)`, `select(.., 1 ms)`) — all with slightly different
/// units and no common home.
///
/// **ISR-safety**: on the hosted-RTOS backends (FreeRTOS / NuttX /
/// Zephyr / ThreadX) the underlying primitives panic or error when
/// invoked from an ISR. Don't call `yield_now()` from an interrupt
/// handler.
///
/// **Bare-metal has no real yield**: there's nothing to yield *to*.
/// The default bare-metal impl is `core::hint::spin_loop()` (a pure
/// CPU hint: emits `YIELD` / `PAUSE` / `WFE` depending on the arch,
/// safe everywhere). Board crates that have armed an IRQ source may
/// opt in to deep idle (`wfi`) via a separate `BoardIdle` hook — not
/// part of this trait because calling `wfi` without an IRQ source
/// deadlocks.
pub trait PlatformYield {
    /// Relinquish the CPU long enough for another task / thread to run.
    ///
    /// Non-blocking in the sleep sense — returns as soon as the
    /// scheduler has had an opportunity to pick a different runnable.
    fn yield_now();
}

// ============================================================================
// Phase 110.D — `PlatformScheduler` (per-thread OS scheduling policy)
// ============================================================================

/// Errors returned by [`PlatformScheduler`] entry points.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SchedError {
    /// The active platform doesn't expose this control surface
    /// (e.g. bare-metal with no scheduler, or an RTOS without an
    /// affinity API).
    Unsupported,
    /// The requested policy is valid for this platform but the
    /// numeric arguments fall outside the platform's accepted range.
    OutOfRange,
    /// A platform-specific syscall / kernel call failed; check
    /// `errno` (POSIX) or the RTOS error code for details.
    KernelError,
}

/// Per-thread OS scheduling policy.
///
/// `Fifo` / `RoundRobin` / `Deadline` / `Sporadic` map to platform-
/// native scheduling classes when available. `Platform(...)` is the
/// escape hatch for RTOS-specific knobs (e.g. ThreadX preempt-
/// threshold) that don't map cleanly into the portable variants.
///
/// User-facing API (`Executor::open_threaded`) takes the abstract
/// [`Priority`-like](crate) values and `PlatformScheduler` translates
/// them into platform-native numerics — direction-flipped priority
/// (Zephyr / ThreadX low-numeric = high-priority vs POSIX / FreeRTOS
/// high-numeric = high-priority) handled internally. Phase 110.D.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SchedPolicy {
    /// POSIX `SCHED_FIFO`. `os_pri` is the platform-native numeric
    /// priority; out-of-range values surface `SchedError::OutOfRange`.
    Fifo { os_pri: u8 },
    /// POSIX `SCHED_RR` with `quantum_ms` time slice.
    RoundRobin { os_pri: u8, quantum_ms: u32 },
    /// Linux `SCHED_DEADLINE` (sched_setattr). All values nanoseconds.
    Deadline {
        runtime_ns: u64,
        period_ns: u64,
        deadline_ns: u64,
    },
    /// NuttX `SCHED_SPORADIC` server. Phase 110.E.
    Sporadic {
        budget_us: u32,
        period_us: u32,
        hi_pri: u8,
        lo_pri: u8,
    },
}

// Per-thread OS-scheduling control surface.
//
// Each platform implements as much of this trait as its kernel
// supports. `bare-metal` returns [`SchedError::Unsupported`] from
// every entry point — there is no scheduler to talk to.
//
// Phase 110.D wires this for Linux + NuttX (via POSIX) at v1; Zephyr
// / FreeRTOS / ThreadX impls land alongside per-RTOS bring-up.

// ============================================================================
// Phase 110.E.b — `PlatformTimer` (ISR-driven periodic refill)
// ============================================================================

/// Errors returned by [`PlatformTimer`] entry points.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TimerError {
    /// The active platform doesn't expose a periodic-timer surface
    /// (e.g. bare-metal without a board-side `SysTickHook`).
    Unsupported,
    /// `period_us` is below the platform's minimum timer resolution
    /// or above its maximum representable interval.
    OutOfRange,
    /// A platform-specific syscall / kernel call failed; check
    /// `errno` (POSIX) or the RTOS error code for details.
    KernelError,
}

/// Periodic timer for ISR-driven sporadic-server budget refill
/// (Phase 110.E.b). The trait factors out the per-platform timer
/// surface so the executor (`nros-node`) can register an atomic
/// refill callback without becoming generic over the platform —
/// see `docs/design/0017-platform-timer.md`.
///
/// Default `create_periodic` returns [`TimerError::Unsupported`] so
/// platforms without a timer surface inherit safe behavior; `destroy`
/// is a no-op default for the same reason.
pub trait PlatformTimer {
    /// Opaque per-platform handle (FreeRTOS `TimerHandle_t`,
    /// Zephyr `*mut k_timer`, ThreadX `*mut TX_TIMER`, POSIX
    /// `timer_t`). Must be `Send + Sync + 'static` so the executor
    /// can stash it across thread boundaries.
    type TimerHandle: Send + Sync + 'static;

    /// Register a periodic timer that fires `callback(user_data)`
    /// every `period_us` microseconds. Returns the platform-native
    /// handle for later destruction.
    ///
    /// # Safety
    ///
    /// `user_data` must outlive the returned handle. The callback is
    /// invoked from a platform-defined timer context (direct ISR on
    /// Zephyr / bare-metal, deferred via `xTimerPendFunctionCall` on
    /// FreeRTOS, signal handler on POSIX) — bodies should be
    /// short and use atomic ops only.
    fn create_periodic(
        _period_us: u32,
        _callback: extern "C" fn(*mut c_void),
        _user_data: *mut c_void,
    ) -> Result<Self::TimerHandle, TimerError> {
        Err(TimerError::Unsupported)
    }

    /// Cancel + free the timer. Idempotent on already-destroyed
    /// handles. Must drain in-flight callback invocations before
    /// returning so the user_data pointer is no longer accessed.
    fn destroy(_handle: Self::TimerHandle) {}

    /// Phase 110.E.b follow-up — register a one-shot timer that
    /// fires `callback(user_data)` exactly once after `timeout_us`
    /// microseconds. Used by per-callback runtime measurement: arm
    /// just before dispatch with `timeout_us = budget_us`; on
    /// callback completion call `cancel`. If the timer fires first
    /// the callback overran its budget.
    ///
    /// Default returns `Unsupported` so platforms without a oneshot
    /// surface inherit safe behavior.
    fn create_oneshot(
        _timeout_us: u32,
        _callback: extern "C" fn(*mut c_void),
        _user_data: *mut c_void,
    ) -> Result<Self::TimerHandle, TimerError> {
        Err(TimerError::Unsupported)
    }

    /// Phase 110.E.b follow-up — cancel a previously-armed oneshot
    /// timer. Returns `true` when the cancellation prevented the
    /// callback from firing, `false` when the callback already
    /// fired (or the timer was already cancelled). Default is a
    /// no-op returning `false`.
    fn cancel(_handle: &mut Self::TimerHandle) -> bool {
        false
    }
}

pub trait PlatformScheduler {
    /// Apply the requested policy to the calling thread.
    ///
    /// Default returns [`SchedError::Unsupported`] so single-core bare-
    /// metal targets and RTOS impls without per-thread scheduling
    /// pickup the no-op behavior automatically. Platforms with a
    /// real scheduler override this.
    fn set_current_thread_policy(_p: SchedPolicy) -> Result<(), SchedError> {
        Err(SchedError::Unsupported)
    }

    /// Cooperative yield. Same semantics as
    /// [`PlatformYield::yield_now`]; mirrored here so consumers don't
    /// need to import both traits when only the scheduler control
    /// surface is in scope. Default is a `core::hint::spin_loop()`.
    fn yield_now() {
        core::hint::spin_loop();
    }

    /// Pin the calling thread to the CPUs whose bit is set in
    /// `cpu_mask`. Default returns [`SchedError::Unsupported`] —
    /// platforms with affinity APIs override.
    fn set_affinity(_cpu_mask: u32) -> Result<(), SchedError> {
        Err(SchedError::Unsupported)
    }
}

// ============================================================================
// Random number generation
// ============================================================================

/// Pseudo-random number generation.
///
/// A simple xorshift32 PRNG is sufficient. Seed with hardware entropy
/// (RNG peripheral, ADC noise, wall-clock time) during platform init.
pub trait PlatformRandom {
    fn random_u8() -> u8;
    fn random_u16() -> u16;
    fn random_u32() -> u32;
    fn random_u64() -> u64;

    /// Fill buffer with random bytes.
    fn random_fill(buf: *mut c_void, len: usize);
}

// ============================================================================
// Wall-clock time (for logging, not timing-critical)
// ============================================================================

/// Wall-clock / system time.
///
/// Used for logging timestamps and `z_time_now_as_str()`.
/// On bare-metal without an RTC, return 0.
///
/// ONE method for one fact, matching `nros_platform_time_now_ns` in the C ABI
/// (issue 0532 item 5). It replaced `time_now_ms` + `time_since_epoch_secs` +
/// `time_since_epoch_nanos`.
///
/// The old doc justified the split by zenoh-pico's FFI shape: "zpico-platform-
/// shim forwards each of these directly to a `_z_time_*` symbol, so collapsing
/// them into a Rust struct would require the shim to decompose the struct on
/// every call." That argument was against a STRUCT, and it still holds — but a
/// single `u64` is not a struct. The shim now takes one value and derives the
/// pair with a divide and a remainder, which is both cheaper than two FFI calls
/// and, unlike them, cannot tear across a second boundary.
pub trait PlatformTime {
    /// Wall-clock nanoseconds since the Unix epoch, or 0 if this platform has
    /// no real-time clock.
    fn time_now_ns() -> u64;
}

// ============================================================================
// Threading (multi-threaded platforms only)
// ============================================================================
//
// Handle types are opaque `*mut c_void` to match the shape zenoh-pico
// passes across the FFI boundary. The original draft had typed wrappers
// (`TaskHandle`, `MutexHandle`, ...) but every shipped platform used
// `*mut c_void` internally and the shim never materialised the typed
// forms — keeping them in the trait would have required a pointless
// cast at every impl site. (F4.1 / F4.5 decision, 2026-04-24.)
//
// Mutex / condvar / task method names keep their sub-namespace prefix
// (`mutex_*`, `condvar_*`, `task_*`) because the trait bundles three
// independent primitive families and unprefixed `init` / `drop` would
// be ambiguous *within* the trait itself.

/// Threading primitives: tasks, mutexes, and condition variables.
///
/// # Threading
///
/// Mutex / condvar operations must be safe under concurrent callers.
/// **Recursive mutex (`mutex_rec_*`) must support same-thread
/// re-entrancy** — zenoh-pico relies on this; a non-recursive mutex
/// backing `mutex_rec_*` deadlocks under load.
///
/// # ISR-safety
///
/// **None of these methods are ISR-safe** on hosted RTOSes
/// (FreeRTOS / NuttX / Zephyr / ThreadX) — the underlying primitives
/// panic or error when invoked from an ISR. Only `core::hint::spin_loop()`
/// in [`PlatformYield::yield_now`] is.
///
/// For single-threaded platforms (bare-metal), all operations should
/// be no-ops returning `0`, except [`task_init`](Self::task_init)
/// which should return `-1`.
pub trait PlatformThreading {
    /// Smallest number of bytes ever left unused on the CALLING task's
    /// stack, or `0` if this platform does not instrument it.
    ///
    /// Defaulted so every existing impl keeps compiling: a port that says
    /// nothing reports `0`, which the ABI documents as "not instrumented"
    /// rather than "no headroom left".
    fn task_stack_unused_bytes() -> usize {
        0
    }
    // -- Tasks --

    /// Spawn a new task. `task` is opaque caller-provided storage;
    /// `attr` carries scheduling hints (priority, stack size) or
    /// `null` for defaults; `entry` is the task entry point; `arg`
    /// is forwarded to `entry`. Returns `0` on success, non-zero
    /// on failure.
    fn task_init(
        task: *mut c_void,
        attr: *mut c_void,
        entry: Option<unsafe extern "C" fn(*mut c_void) -> *mut c_void>,
        arg: *mut c_void,
    ) -> i8;

    /// Block until `task` exits. Cleans up the task storage on
    /// success.
    fn task_join(task: *mut c_void) -> i8;
    /// Mark `task` as detached — its storage is reclaimed on exit
    /// without a join.
    fn task_detach(task: *mut c_void) -> i8;
    /// Request `task` to terminate at the next cancellation point.
    /// Cooperative.
    fn task_cancel(task: *mut c_void) -> i8;
    /// Terminate the calling task immediately. Does not return.
    fn task_exit();
    /// Free the task storage allocated by `task_init`.
    fn task_free(task: *mut *mut c_void);

    // -- Mutex --

    /// Initialise a non-recursive mutex in caller-provided storage.
    fn mutex_init(m: *mut c_void) -> i8;
    /// Tear down a non-recursive mutex.
    fn mutex_drop(m: *mut c_void) -> i8;
    /// Lock; block if held.
    fn mutex_lock(m: *mut c_void) -> i8;
    /// Try to lock; non-zero return immediately if held.
    fn mutex_try_lock(m: *mut c_void) -> i8;
    /// Unlock; only the owning thread may call this.
    fn mutex_unlock(m: *mut c_void) -> i8;

    // -- Recursive mutex --

    /// Initialise a *recursive* mutex (same-thread re-entrancy
    /// permitted). Required by zenoh-pico.
    fn mutex_rec_init(m: *mut c_void) -> i8;
    /// Tear down a recursive mutex.
    fn mutex_rec_drop(m: *mut c_void) -> i8;
    /// Lock; re-entry from the owning thread must succeed.
    fn mutex_rec_lock(m: *mut c_void) -> i8;
    /// Try to lock; same re-entry semantics as `mutex_rec_lock`.
    fn mutex_rec_try_lock(m: *mut c_void) -> i8;
    /// Unlock; releases when the lock count returns to zero.
    fn mutex_rec_unlock(m: *mut c_void) -> i8;

    // -- Condition variables --

    /// Initialise a condition variable in caller-provided storage.
    fn condvar_init(cv: *mut c_void) -> i8;
    /// Tear down a condition variable.
    fn condvar_drop(cv: *mut c_void) -> i8;
    /// Wake one waiter on the condition variable.
    fn condvar_signal(cv: *mut c_void) -> i8;
    /// Wake all waiters on the condition variable.
    fn condvar_signal_all(cv: *mut c_void) -> i8;
    /// Phase 124.B.7.a — ISR-safe variant of [`Self::condvar_signal`].
    /// Callable from interrupt / signal-handler context. Backends
    /// implement via async-signal-safe primitives (POSIX: `pipe`
    /// write forwarded by a worker thread — Linux may use `eventfd`,
    /// which is a Linux syscall and not POSIX; RTOS:
    /// `xSemaphoreGiveFromISR`, `tx_event_flags_set` from ISR,
    /// `k_sem_give` from ISR). Returns non-zero when the backend
    /// has no ISR-safe path — caller can fall back to
    /// `condvar_signal` (with the obvious latency cost).
    ///
    /// Default body: forward to `condvar_signal`. POSIX and other
    /// backends override to use their async-signal-safe primitive.
    fn condvar_signal_from_isr(cv: *mut c_void) -> i8 {
        Self::condvar_signal(cv)
    }
    /// Atomically release `m` and block on `cv`. The mutex is
    /// re-acquired before this function returns.
    fn condvar_wait(cv: *mut c_void, m: *mut c_void) -> i8;

    /// Wait with absolute monotonic deadline (milliseconds since
    /// the [`PlatformClock::clock_ns`] epoch). Returns non-zero on
    /// timeout.
    fn condvar_wait_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8;

    // -- Wake primitive (Phase 130) --
    //
    // Binary-semaphore-shaped primitive for the executor's wake_flag
    // / spin_once cv-wait pair. Default bodies return "unsupported"
    // (`-1`, size 0) so existing single-thread bare-metal platforms
    // don't need to override; platforms that want event-driven wake
    // (POSIX, Zephyr, FreeRTOS, NuttX, ThreadX) override with their
    // native binary semaphore.

    /// Initialise a binary-semaphore-shaped wake primitive in
    /// caller-provided storage. See `<nros/platform.h>` for the
    /// per-platform backing primitive (POSIX `sem_t`, Zephyr
    /// `k_sem`, FreeRTOS `xSemaphoreBinary`, …). Default returns
    /// `-1` (unsupported).
    fn wake_init(_w: *mut c_void) -> i8 {
        -1
    }
    /// Tear down a wake primitive. Default returns `-1`
    /// (unsupported).
    fn wake_drop(_w: *mut c_void) -> i8 {
        -1
    }
    /// Block until signaled or `timeout_ms` elapses. Returns `0` on
    /// signal, `1` on timeout, `-1` on error. Default returns `-1`
    /// (unsupported).
    fn wake_wait_ms(_w: *mut c_void, _timeout_ms: u32) -> i8 {
        -1
    }
    /// Wake one waiter. Idempotent — a signal pending when another
    /// arrives is coalesced (the primitive stays at value 1).
    /// Default returns `-1` (unsupported).
    fn wake_signal(_w: *mut c_void) -> i8 {
        -1
    }
    /// ISR-safe signal. Returns `-1` when the backend has no ISR
    /// path; callers may fall back to `wake_signal` (with the
    /// obvious latency cost). Default forwards to `wake_signal`.
    fn wake_signal_from_isr(w: *mut c_void) -> i8 {
        Self::wake_signal(w)
    }
    /// Caller-storage size requirement (bytes). Default `0` —
    /// signals "no wake primitive available". May be called before
    /// `wake_init`.
    fn wake_storage_size() -> usize {
        0
    }
    /// Caller-storage alignment requirement (bytes). Default `1`.
    fn wake_storage_align() -> usize {
        1
    }
    /// Caller-storage size requirement (bytes) for a task handle.
    ///
    /// phase-359 W10 added these probes to `platform.h` and to the C ports but
    /// not to this trait or the export macro, so `check-platform-abi-mirror`
    /// saw a header symbol with no Rust emission. Same contract as the wake
    /// pair above: default `0` means "this platform cannot start a task", which
    /// is the honest answer for a port whose `task_init` always fails, and it
    /// is safe to call before `task_init`.
    fn task_storage_size() -> usize {
        0
    }
    /// Caller-storage alignment requirement (bytes) for a task handle.
    /// Default `1`.
    fn task_storage_align() -> usize {
        1
    }
    /// Caller-storage size requirement (bytes) for a plain mutex.
    ///
    /// phase-364 W2 declared the lock family's probes in `platform.h` without
    /// the trait or macro halves — the same shape phase-359 W10 left for
    /// `task`, one commit later. Defaults match the pair above: `0` size means
    /// "this platform offers no such primitive", `1` alignment is the
    /// no-constraint answer, and both are safe to call before any `*_init`.
    fn mutex_storage_size() -> usize {
        0
    }
    /// Caller-storage alignment requirement (bytes) for a plain mutex.
    fn mutex_storage_align() -> usize {
        1
    }
    /// Caller-storage size requirement (bytes) for a RECURSIVE mutex.
    fn mutex_rec_storage_size() -> usize {
        0
    }
    /// Caller-storage alignment requirement (bytes) for a recursive mutex.
    fn mutex_rec_storage_align() -> usize {
        1
    }
    /// Caller-storage size requirement (bytes) for a condition variable.
    fn condvar_storage_size() -> usize {
        0
    }
    /// Caller-storage alignment requirement (bytes) for a condition variable.
    fn condvar_storage_align() -> usize {
        1
    }
}

/// Network poll callback for bare-metal platforms using smoltcp.
///
/// Not required for platforms with OS-level networking (POSIX, Zephyr, NuttX).
///
/// **Dispatch model**: bare-metal smoltcp platforms route this hook to
/// `SmoltcpBridge::poll_network()` so CFFI callers, RMW shims, and direct
/// platform users all share one network pump.
pub trait PlatformNetworkPoll {
    /// Poll the network stack to process pending I/O.
    ///
    /// Default no-op — platforms with OS-level networking don't need a
    /// pump (kernel TCP/IP stack runs in the background). Bare-metal
    /// smoltcp providers override this.
    fn network_poll() {}
}

/// Global mutual exclusion against preemption + ISR delivery
/// (Phase 121.9).
///
/// Backs the Rust `critical_section::Impl` registration used by
/// DDS, nros-rmw-{xrce,zenoh}, and any other no_std consumer of
/// `critical_section::with()`. The token returned by `acquire` is
/// passed back to `release`; it holds whatever bookkeeping the
/// platform needs to restore the prior posture (Cortex-M PRIMASK bit,
/// Cortex-R CPSR I-bit, RISC-V `mstatus.MIE` snapshot, pthread
/// recursion depth, etc.) and is opaque to callers.
///
/// Reentrant by contract: nested `acquire` / `release` pairs must
/// stack — the platform impl is responsible for nesting (PRIMASK
/// already stacks; pthread side uses a recursive mutex).
pub trait PlatformCriticalSection {
    /// Enter a critical section. Returns an opaque token to pass to
    /// [`Self::release`].
    fn acquire() -> u32;

    /// Leave a critical section, restoring the posture captured at
    /// [`Self::acquire`].
    fn release(token: u32);
}

// ============================================================================
// Networking — TCP
// ============================================================================

/// TCP networking.
///
/// Socket and endpoint parameters are opaque `*mut c_void` pointers to
/// platform-specific types (`_z_sys_net_socket_t`, `_z_sys_net_endpoint_t`).
/// The shim provides correctly-sized `#[repr(C)]` wrappers whose sizes are
/// auto-detected from C headers at build time (see Phase 80 design).
///
/// Read functions return `usize::MAX` on error. Send returns `usize::MAX` on error.
///
/// Method names are unprefixed — the trait already namespaces them. Shims
/// dispatch via `<ConcretePlatform as PlatformTcp>::open(...)` etc.
pub trait PlatformTcp {
    /// Resolve address + port strings into an endpoint handle.
    fn create_endpoint(ep: *mut c_void, address: *const u8, port: *const u8) -> i8;
    /// Free endpoint resources.
    fn free_endpoint(ep: *mut c_void);
    /// Open a TCP client connection. `endpoint` is by-value (opaque bytes on stack).
    fn open(sock: *mut c_void, endpoint: *const c_void, timeout_ms: u32) -> i8;
    /// Open a TCP listening socket.
    fn listen(sock: *mut c_void, endpoint: *const c_void) -> i8;
    /// Close a TCP socket.
    fn close(sock: *mut c_void);
    /// Read up to `len` bytes. Returns bytes read, or `usize::MAX` on error.
    fn read(sock: *const c_void, buf: *mut u8, len: usize) -> usize;
    /// Read exactly `len` bytes. Returns `len` on success, `usize::MAX` on error.
    fn read_exact(sock: *const c_void, buf: *mut u8, len: usize) -> usize;
    /// Send `len` bytes. Returns bytes sent, or `usize::MAX` on error.
    fn send(sock: *const c_void, buf: *const u8, len: usize) -> usize;
}

// ============================================================================
// Networking — UDP unicast
// ============================================================================

/// UDP unicast networking.
pub trait PlatformUdp {
    fn create_endpoint(ep: *mut c_void, address: *const u8, port: *const u8) -> i8;
    fn free_endpoint(ep: *mut c_void);
    fn open(sock: *mut c_void, endpoint: *const c_void, timeout_ms: u32) -> i8;
    fn close(sock: *mut c_void);
    fn read(sock: *const c_void, buf: *mut u8, len: usize) -> usize;
    fn read_exact(sock: *const c_void, buf: *mut u8, len: usize) -> usize;
    fn send(sock: *const c_void, buf: *const u8, len: usize, endpoint: *const c_void) -> usize;
    /// Set the receive timeout on a UDP socket (milliseconds).
    /// 0 means block indefinitely (no timeout).
    fn set_recv_timeout(sock: *const c_void, timeout_ms: u32);

    /// Open a UDP socket in listen (server) mode, bound to the given
    /// endpoint. Returns 0 on success, negative on failure.
    ///
    /// Optional — the default returns `-1`, which the shim forwards to
    /// `_z_listen_udp_unicast` as "not implemented". Platforms that
    /// need UDP server sockets (e.g. for running an XRCE-DDS agent
    /// locally) should override this. Once Phase 84.F4 lands (the
    /// "platform traits become a real contract" refactor), the shim
    /// will dispatch through this trait method automatically.
    fn listen(_sock: *mut c_void, _endpoint: *const c_void, _timeout_ms: u32) -> i8 {
        -1
    }
}

// ============================================================================
// Networking — socket helpers
// ============================================================================

/// Socket helper operations called by zenoh-pico's transport layer.
///
/// Unprefixed method names: dispatch via
/// `<ConcretePlatform as PlatformSocketHelpers>::set_non_blocking(...)`.
/// Note that the `close` method here is the socket-layer close (shutdown +
/// close) used by zenoh-pico's generic helpers; `PlatformTcp::close` is the
/// TCP-specific close. Both exist because zenoh-pico's C surface has both.
pub trait PlatformSocketHelpers {
    /// Set socket to non-blocking mode.
    fn set_non_blocking(sock: *const c_void) -> i8;
    /// Accept a pending connection.
    fn accept(sock_in: *const c_void, sock_out: *mut c_void) -> i8;
    /// Close a socket (shutdown + close).
    fn close(sock: *mut c_void);
    /// Wait for socket events (multi-threaded platforms).
    fn wait_event(peers: *mut c_void, mutex: *mut c_void) -> i8;
}

// ============================================================================
// libc stubs (bare-metal only)
// ============================================================================

/// Standard C library functions needed by zenoh-pico on bare-metal targets.
///
/// Platforms with a C runtime (RTOS, POSIX) do NOT need to implement this.
///
/// # Dispatch model (Phase 84.F4.6)
///
/// This trait is **documentary only** — it is NOT dispatched through by
/// `zpico-platform-shim` or `xrce-platform-shim`. The C libraries resolve
/// these symbols (`strlen`, `memcpy`, `errno`, ...) at link time directly
/// from `#[unsafe(no_mangle)] extern "C" fn` definitions in
/// `nros-baremetal-common`, which bare-metal platform crates pull in
/// via the `libc-stubs` feature:
///
/// ```text
///   nros-baremetal-common = { ..., features = ["libc-stubs"] }
/// ```
///
/// The trait is retained in this API surface so that a future shim
/// refactor could route libc through typed Rust methods without
/// changing consumers. Today, implementing `PlatformLibc` on a platform
/// ZST would be pure documentation; the actual contract — "the linker
/// can resolve `strlen` etc." — is enforced at link time, not at
/// compile time. No platform crate implements this trait in the
/// current tree.
pub trait PlatformLibc {
    fn strlen(s: *const u8) -> usize;
    fn strcmp(s1: *const u8, s2: *const u8) -> c_int;
    fn strncmp(s1: *const u8, s2: *const u8, n: usize) -> c_int;
    fn strchr(s: *const u8, c: c_int) -> *mut u8;
    fn strncpy(dest: *mut u8, src: *const u8, n: usize) -> *mut u8;
    fn memcpy(dest: *mut c_void, src: *const c_void, n: usize) -> *mut c_void;
    fn memmove(dest: *mut c_void, src: *const c_void, n: usize) -> *mut c_void;
    fn memset(dest: *mut c_void, c: c_int, n: usize) -> *mut c_void;
    fn memcmp(s1: *const c_void, s2: *const c_void, n: usize) -> c_int;
    fn memchr(s: *const c_void, c: c_int, n: usize) -> *mut c_void;
    fn strtoul(nptr: *const u8, endptr: *mut *mut u8, base: c_int) -> core::ffi::c_ulong;
    fn errno_ptr() -> *mut c_int;
}

// ============================================================================
// Logging — Phase 88 leveled log delivery
// ============================================================================

/// Per-platform leveled log delivery.
///
/// Matches the post-Phase-129 platform-ABI pattern: the portable
/// facade (`nros-log`) formats messages into a fixed buffer; each
/// `nros-platform-<rtos>` carries the actual delivery (stderr,
/// `printk`, `esp_log_write`, `syslog`, board-registered UART writer,
/// etc.).
///
/// `severity` is the `u8` discriminant of `nros_log::Severity`
/// (0 = Trace .. 5 = Fatal). Implementors should map onto the
/// platform's nearest native level.
///
/// `name` is the logger name (UTF-8, NOT null-terminated, may be
/// empty); `message` is the already-formatted body (UTF-8, NOT
/// null-terminated). Delivery is infallible from the caller's POV;
/// platforms that fill an internal buffer (RTT, syslog) silently
/// drop on overflow.
///
/// Thread / ISR safety is per-platform — see the table in
/// `docs/roadmap/phase-88-nros-log.md`. The ABI itself is synchronous
/// and the caller-side facade carries a recursion guard so a sink
/// that triggers `log()` from inside `write` is short-circuited.
pub trait PlatformLog {
    /// Deliver one record. Severity is a stable `u8` matching
    /// `nros_log::Severity::as_u8()`.
    fn write(severity: u8, name: &[u8], message: &[u8]);

    /// Best-effort drain of any internal buffer. Default = no-op.
    fn flush() {}
}

// ============================================================================
// Networking — UDP multicast
// ============================================================================

/// UDP multicast networking (used for zenoh scouting on desktop platforms).
pub trait PlatformUdpMulticast {
    fn mcast_open(
        sock: *mut c_void,
        endpoint: *const c_void,
        lep: *mut c_void,
        timeout_ms: u32,
        iface: *const u8,
    ) -> i8;
    fn mcast_listen(
        sock: *mut c_void,
        endpoint: *const c_void,
        timeout_ms: u32,
        iface: *const u8,
        join: *const u8,
    ) -> i8;
    fn mcast_close(
        sockrecv: *mut c_void,
        socksend: *mut c_void,
        rep: *const c_void,
        lep: *const c_void,
    );
    fn mcast_read(
        sock: *const c_void,
        buf: *mut u8,
        len: usize,
        lep: *const c_void,
        addr: *mut c_void,
    ) -> usize;
    fn mcast_read_exact(
        sock: *const c_void,
        buf: *mut u8,
        len: usize,
        lep: *const c_void,
        addr: *mut c_void,
    ) -> usize;
    fn mcast_send(
        sock: *const c_void,
        buf: *const u8,
        len: usize,
        endpoint: *const c_void,
    ) -> usize;
}

// ============================================================================
// Inter-VM / mailbox transport (NVIDIA IVC and similar)
// ============================================================================

/// Inter-processor mailbox transport, modelled after NVIDIA Tegra IVC.
///
/// IVC (Inter-VM Communication on Tegra; in practice CCPLEX↔SPE on AGX
/// Orin) is a header-prefixed lock-free SPSC ring in shared DRAM, paired
/// with a hardware doorbell for wake. One channel is one peer — there
/// is no discovery, naming, QoS, or fanout — which is why it's a *link*
/// transport (peer to TCP/UDP/Serial/RawEth inside zenoh-pico) rather
/// than a new RMW backend.
///
/// Channel handles are opaque `*mut c_void` to match the shape zenoh-pico
/// passes across its FFI boundary. The driver crate (`nvidia-ivc`)
/// translates between this opaque handle and either NVIDIA's FSP
/// `tegra_ivc_*` API (`fsp` feature) or a Unix-socket pair
/// (`unix-mock` feature, host dev + CI).
///
/// **Zero-copy contract** (Phase 11.3.A). NVIDIA's FSP IVC API is
/// fundamentally a "borrow ring slot, fill, commit / release"
/// pattern. Both backends mirror that here so consumers don't branch
/// on backend:
///
/// - [`Self::rx_get`] returns a pointer into the channel's RX slot
///   (and writes the frame length to `*len_out`); [`Self::rx_release`]
///   advances the producer-visible cursor. Returns null +
///   `*len_out = 0` if the ring is empty.
/// - [`Self::tx_get`] returns a writable pointer to the next free TX
///   slot (and writes the slot capacity to `*cap_out`);
///   [`Self::tx_commit`] makes the slot visible to the peer (and
///   rings the per-frame doorbell on FSP — see `notify` for batching).
///   [`Self::tx_abandon`] frees the slot without sending. Returns
///   null + `*cap_out = 0` if the ring is full.
///
/// Single outstanding RX slot and single outstanding TX slot per
/// channel — borrow, finish, repeat. Multi-frame batching is the
/// caller's job (loop `tx_get` / fill / `tx_commit`, then one
/// `notify`).
///
/// `frame_size` is the fixed per-channel frame size negotiated at
/// carveout setup (typical NVIDIA IVC: 64 bytes per frame, 16 frames
/// per channel). The link layer uses it to pick its reassembly buffer.
pub trait PlatformIvc {
    /// Resolve a channel ID into an opaque handle. Returns null on
    /// failure. The numeric ID matches the NVIDIA channel index
    /// (`channel 2 = aon_echo`).
    fn channel_get(id: u32) -> *mut c_void;

    /// Fixed frame size negotiated for this channel, in bytes.
    fn frame_size(ch: *mut c_void) -> u32;

    /// Borrow the next-available RX frame. Writes the frame length to
    /// `*len_out` and returns a pointer into the ring. Returns null +
    /// `*len_out = 0` if no frame is available.
    fn rx_get(ch: *mut c_void, len_out: *mut usize) -> *const u8;

    /// Release the most recently `rx_get`'d frame back to the
    /// producer. Pair 1:1 with `rx_get` calls that returned non-null.
    fn rx_release(ch: *mut c_void);

    /// Borrow the next free TX slot. Writes the slot capacity to
    /// `*cap_out` and returns a writable pointer. Returns null +
    /// `*cap_out = 0` if the ring is full.
    fn tx_get(ch: *mut c_void, cap_out: *mut usize) -> *mut u8;

    /// Commit `len` bytes from the most recently `tx_get`'d slot.
    /// Slot is then visible to the peer; per-frame doorbell may also
    /// fire on FSP. Pair 1:1 with `tx_get` calls that returned
    /// non-null.
    fn tx_commit(ch: *mut c_void, len: usize);

    /// Abandon the most recently `tx_get`'d slot without sending.
    /// Pair 1:1 with `tx_get` calls that returned non-null.
    fn tx_abandon(ch: *mut c_void);

    /// Ring the doorbell. On FSP this is redundant (commit/release
    /// already invoke `ch->notify_remote`); on unix-mock it's a no-op
    /// (SOCK_DGRAM wakes the peer naturally). Provided for symmetry
    /// so callers can batch-commit then notify once.
    fn notify(ch: *mut c_void);
}

// ============================================================================
// Serial (UART / PTY)
// ============================================================================

/// Serial (byte-stream) transport.
///
/// Used by XRCE-DDS's HDLC-framed serial transport and (once the
/// bare-metal migration lands) by zenoh-pico's serial link layer.
///
/// # Handle model
///
/// `open()` returns a platform-defined [`Handle`](PlatformSerial::Handle)
/// — an FD on POSIX, a port-table index on bare-metal, whatever the
/// impl wants. Every other method takes the handle back. This lets a
/// single platform impl service multiple concurrent devices (e.g.,
/// `zpico-serial`'s two-port table) without the trait constraining
/// the impl to a single active device.
///
/// Single-device platforms return the same handle forever and ignore
/// it internally; `INVALID` gives a well-defined "no live handle"
/// sentinel for shims that stash the current handle in a `static`.
///
/// # Path conventions
///
/// `path` in `open()` is platform-specific: a null-terminated UTF-8
/// device path on POSIX (e.g., `/dev/ttyUSB0` or a PTY), or a
/// board-defined port identifier on bare-metal (typically parsed by
/// the platform's internal handler). Callers pass the locator string
/// from their config unchanged; interpretation is the platform's job.
///
/// # I/O conventions
///
/// Read / write return `usize::MAX` on hard error. Read with
/// `timeout_ms == 0` should block for a platform-chosen default;
/// positive values are the poll/select deadline in milliseconds.
/// Returning `0` from `read()` indicates "no data within timeout" and
/// is **not** an error — both XRCE and zenoh-pico tolerate
/// timeout-zero reads.
pub trait PlatformSerial {
    /// Platform-specific handle type. POSIX returns the FD (`i32`);
    /// bare-metal returns a port-table index (`u8`). Must be `Copy`
    /// so shims can stash it in a `static`.
    type Handle: Copy;

    /// Sentinel handle meaning "not a live device". Shims initialise
    /// their cached handle to this and compare against it to detect
    /// "transport not yet opened" states.
    const INVALID: Self::Handle;

    /// Returns `true` if `h` is a live handle (not [`INVALID`](Self::INVALID)
    /// and points at a device that was opened and not yet closed).
    fn is_valid(h: Self::Handle) -> bool;

    /// Open the serial device identified by `path`. Returns a live
    /// handle on success, [`INVALID`](Self::INVALID) on failure.
    fn open(path: *const u8) -> Self::Handle;

    /// Close the given handle. No-op if already closed or invalid.
    fn close(h: Self::Handle);

    /// Configure baud rate (in bits per second). Returns 0 on success,
    /// -1 on error. Called after `open()`; implementations may choose
    /// to apply the baud rate during `open()` instead and make this a
    /// no-op.
    fn configure(h: Self::Handle, baudrate: u32) -> i8;

    /// Read up to `len` bytes into `buf`. Returns the number of bytes
    /// read, `0` on timeout, or `usize::MAX` on hard error.
    fn read(h: Self::Handle, buf: *mut u8, len: usize, timeout_ms: u32) -> usize;

    /// Write `len` bytes from `buf`. Returns bytes written, or
    /// `usize::MAX` on error.
    fn write(h: Self::Handle, buf: *const u8, len: usize) -> usize;
}

/// Smallest number of bytes ever left unused on the CALLING task's stack, or
/// `0` if this port does not instrument it.
///
/// Lives at the crate root, NOT in [`task`], because that module is
/// `#[cfg(feature = "alloc")]` -- `PlatformTask` allocates its own storage --
/// while this is a bare `extern "C"` query returning a `usize`. Gating it
/// behind `alloc` made it unavailable on exactly the no_std targets whose
/// stacks are worth watching, and broke the executor's stack-headroom rule
/// on the Zephyr build.
///
/// The heap has had `heap_used_bytes` since RFC-0034 D7; this is the stack's
/// counterpart. HEADROOM, not usage, and for the CALLING task only -- both
/// kernels answer for self with no handle, and answering for an arbitrary
/// task needs a native handle this ABI does not carry.
///
/// `0` means "not instrumented", not "no headroom".
pub fn stack_unused_bytes() -> usize {
    unsafe extern "C" {
        fn nros_platform_task_stack_unused_bytes() -> usize;
    }
    // SAFETY: a plain query with no arguments and no state; every port either
    // answers or returns 0.
    unsafe { nros_platform_task_stack_unused_bytes() }
}