platform.h

Go to the documentation of this file.

#ifndef NROS_PLATFORM_H
#define NROS_PLATFORM_H
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

 
/* ---- Platform capability defaults (RFC-0042 D2 / phase-241 B + C) ----
 *
 * Platform-*constant* capabilities. The single source of truth for a board's
 * *variable* capabilities is its `nros-board.toml` `[board.capabilities]`, lowered
 * to `-DNROS_PLATFORM_HAS_MALLOC` (etc.) by the build (phase-241 C.2). These
 * blocks supply only the per-platform constants, and never override a `-D` the
 * board already set (every `#define` is `#ifndef`-guarded).
 *
 *  - `NROS_PLATFORM_HAS_MALLOC` gates the canonical `malloc`/`free` shim below.
 *    Absent → a TU using the nros-cpp heap containers fails to *compile* (not
 *    link) — the issue-0038 guard.
 *  - `NROS_PLATFORM_HAS_ATOMICS` is true on every supported target today.
 *
 * RTOS-config-derived capabilities are intentionally NOT defaulted here:
 *  - FreeRTOS heap ← `configSUPPORT_DYNAMIC_ALLOCATION` (FreeRTOSConfig.h),
 *  - Zephyr heap/mutex ← `CONFIG_HEAP_MEM_POOL_SIZE` / `CONFIG_MULTITHREADING`.
 *    Those boards declare `heap = true` in board.toml and the build lowers it to
 *    the Kconfig/FreeRTOSConfig knob, keeping the C view tied to the RTOS config.
 */
/* HAS_ATOMICS is a constant on every supported target. */
#ifndef NROS_PLATFORM_HAS_ATOMICS
#  define NROS_PLATFORM_HAS_ATOMICS
#endif
 
/* HAS_MALLOC by platform. POSIX (and the POSIX-mapped hosted platforms: NuttX,
 * ThreadX-linux, native) and the heap RTOSes (Zephyr, FreeRTOS) always run with
 * an allocator under nros — the generator always configures the RTOS heap
 * (`CONFIG_HEAP_MEM_POOL_SIZE`, `configSUPPORT_DYNAMIC_ALLOCATION`), and each
 * declares `heap = true` in its `nros-board.toml`. They get the canonical
 * malloc/free unconditionally here.
 *
 * Bare-metal / ThreadX-RV64 / ESP / custom do NOT default a heap: they opt in
 * via the board.toml-derived `-DNROS_PLATFORM_HAS_MALLOC` (phase-241 C.2), so a
 * genuinely heap-less board still fails to compile a heap container (the #38
 * compile-gate). */
/* Every hosted/RTOS platform has a heap (POSIX, Zephyr, FreeRTOS, ThreadX-linux,
 * NuttX, and the default/unspecified case). This mirrors the retired nros-c
 * dispatch, where any non-bare-metal platform fell through to `posix.h`'s
 * unconditional malloc. Only bare-metal (incl. ThreadX-RV64 / ESP, which map to
 * `NROS_PLATFORM_BAREMETAL`) withholds the heap and opts in via the
 * board.toml-derived `-DNROS_PLATFORM_HAS_MALLOC` (phase-241 C.2 / the #38 gate). */
#if !defined(NROS_PLATFORM_BAREMETAL)
#  ifndef NROS_PLATFORM_HAS_MALLOC
#    define NROS_PLATFORM_HAS_MALLOC
#  endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---- Return codes ----
 *
 * phase-364 W1 (RFC-0076 D3). This vocabulary was declared and used by NO
 * port: 26 entry points returned a bare `int8_t` 0/-1, so "this platform
 * never does this" and "this failed just now" were the same value.
 *
 * That distinction is not academic. A caller may cache `UNSUPPORTED` forever
 * and MUST retry `NOMEM`: issue 0246 is a transient `pthread_create` failure
 * on NuttX under load, and phase-359 W10's worker pool — unable to ask — caches
 * every refusal, disabling a priority level for the process on what may have
 * been a momentary shortage.
 *
 * `nros_platform_ret_t` is `int8_t` because that is the width the functions
 * already return; it was `int32_t` and, having no users, cost nothing to
 * narrow. Every code below is non-zero, so a caller testing `!= 0` — which is
 * every caller today — is unaffected by ports becoming more specific.
 *
 * The values are written WITHOUT a cast on purpose. `((nros_platform_ret_t) 0)`
 * is the more careful C, and it is why bindgen emitted none of these: it cannot
 * evaluate a cast into a constant, so `nros-platform-cffi` carried a
 * hand-written Rust copy of all three — a mirror of exactly the kind
 * `check-ffi-struct-mirrors` exists to prevent, kept in step by nothing. Bare
 * integer literals cross the generator, so there is now one definition. */
 
typedef int8_t nros_platform_ret_t;

#define NROS_PLATFORM_RET_OK              0
#define NROS_PLATFORM_RET_ERROR           -1
#define NROS_PLATFORM_RET_UNSUPPORTED     -5
#define NROS_PLATFORM_RET_NOMEM           -6
#define NROS_PLATFORM_RET_INVALID         -7
#define NROS_PLATFORM_RET_TIMEOUT         -8
 
/* ---- Clock (monotonic) ---- */

uint64_t nros_platform_clock_ns(void);

uint64_t nros_platform_clock_resolution_ns(void);
 
/* RFC-0073 / phase-352 W6 — `nros_platform_clock_ms` and
 * ~~`nros_platform_clock_us`~~ are RETIRED. They were kept for one release as
 * `static inline` wrappers behind NROS_PLATFORM_LEGACY_CLOCK_UNITS; both
 * the wrappers and the escape hatch are now gone. Callers divide
 * `nros_platform_clock_ns()` themselves — and a caller that hand-declares
 * either retired name is caught by
 * `scripts/check-retired-platform-clock-symbols.py` (issue #555). */
 
/* ---- Clock (wall-clock epoch) ---- */

uint64_t nros_platform_epoch_us(void);
 
/* ---- Allocation ---- */

void *nros_platform_alloc(size_t size);

void *nros_platform_realloc(void *ptr, size_t size);

void nros_platform_dealloc(void *ptr);
 
/* Canonical `malloc`/`free` C-ABI surface (issue-0038). nros-cpp's heap
 * containers (`heap_string.hpp`, `heap_sequence.hpp`) allocate through
 * `nros_platform_malloc` / `nros_platform_free` so C and C++ share one
 * allocator. Defined ONCE here (replacing the former 5 per-header copies) as a
 * thin forward to the platform `alloc`/`dealloc` funnel (RFC-0034 D6), GATED on
 * the heap capability: a board without `NROS_PLATFORM_HAS_MALLOC` does not get
 * the canonical malloc/free, so using a heap container on a heap-less board is a
 * compile error (the 241.A gate), not a latent link failure. */
#ifdef NROS_PLATFORM_HAS_MALLOC
static inline void *nros_platform_malloc(size_t size) {
    return nros_platform_alloc(size);
}
 
static inline void nros_platform_free(void *ptr) {
    nros_platform_dealloc(ptr);
}
#endif /* NROS_PLATFORM_HAS_MALLOC */

size_t nros_platform_heap_used_bytes(void);

size_t nros_platform_task_stack_unused_bytes(void);

size_t nros_platform_task_stack_unused_bytes_upto(size_t limit);

size_t nros_platform_heap_total_bytes(void);
 
/* ---- Atomics ---- */
/* RFC-0042 D1 / phase-243 — single portable atomic-bool pair (was per-RTOS
 * `static inline` in the retired nros-c sub-headers: posix `__atomic`, zephyr
 * `atomic_set`, freertos critical-section, bare-metal barrier). The `__atomic_*`
 * builtins lower to a plain load/store + acquire/release fence for a
 * naturally-aligned 1-byte `bool` on every target nros builds — no CAS /
 * A-extension needed (riscv32imc never builds nros-c). Used directly (not C11
 * `<stdatomic.h>`, which does not compile under g++). Header-only inline, so
 * there is no extern symbol + no Rust-mirror entry. */
static inline void nros_platform_atomic_store_bool(bool *ptr, bool value) {
    __atomic_store_n(ptr, value, __ATOMIC_RELEASE);
}
 
static inline bool nros_platform_atomic_load_bool(const bool *ptr) {
    return __atomic_load_n(ptr, __ATOMIC_ACQUIRE);
}
 
/* ---- Sleep ---- */

void nros_platform_sleep_us(size_t us);

void nros_platform_sleep_ms(size_t ms);

void nros_platform_sleep_s(size_t s);
 
/* ---- Cooperative yield ---- */

void nros_platform_yield_now(void);
 
/* ---- Random ---- */

uint8_t  nros_platform_random_u8(void);
uint16_t nros_platform_random_u16(void);
uint32_t nros_platform_random_u32(void);
uint64_t nros_platform_random_u64(void);
void     nros_platform_random_fill(void *buf, size_t len);
 
/* ---- Wall clock ---- */

uint64_t nros_platform_time_now_ns(void);
 
/* Issue 0532 item 5 — ~~`nros_platform_time_now_ms`~~,
 * ~~`nros_platform_time_since_epoch_secs`~~ and
 * ~~`nros_platform_time_since_epoch_nanos`~~ are RETIRED, the same way
 * phase-352 W6 retired `clock_ms` / `clock_us` rather than keeping
 * wrappers. A caller that hand-declares any of the three is caught by
 * `scripts/check-retired-platform-clock-symbols.py`. */
 
/* ---- Threading: tasks ---- */
 
/* ---- Task attributes ----
 *
 * phase-364 W3 (RFC-0076 D2). `attr` used to be an undefined `void *`: IGNORED
 * by the posix and zephyr ports, a PRIVATE struct in the freertos and esp-idf
 * ports, and MANDATORY on threadx (a `NULL` was a hard failure). Three struct
 * types, no shared definition, and therefore no portable way to ask for a stack
 * size — which is why phase-359 W7 wrote a bespoke C shim to spawn a NuttX tier
 * with a 64 KiB stack, and why W10's generic spawn passes `NULL` and would fail
 * on ThreadX.
 *
 * One type now, defined here, and `attr == NULL` means "every default" on
 * EVERY port. */
typedef struct {
    const char *name;
    size_t stack_bytes;
    void *stack_mem;
    int32_t priority;
    int8_t core;
    uint8_t flags;
} nros_platform_task_attr_t;

#define NROS_PLATFORM_TASK_DETACHED 0x01u
 
/* ---- Normalised priority band (phase-364 W5) ----
 *
 * `0` = least urgent … `NROS_PLATFORM_PRIORITY_MAX` = most urgent. A port maps
 * the band onto its native range; the map is documented at each port's
 * `task_init` and is the ONLY place a direction is decided.
 *
 * The band is deliberately small. It is a portable ORDERING, not a claim that
 * every RTOS has 256 usable levels — ThreadX ships 32 by default, FreeRTOS's
 * `configMAX_PRIORITIES` is commonly 5 to 32, and a map that pretended
 * otherwise would collapse distinct tiers onto one level without saying so. */
#define NROS_PLATFORM_PRIORITY_MIN      0
#define NROS_PLATFORM_PRIORITY_MAX      255
#define NROS_PLATFORM_PRIORITY_INHERIT  INT32_MIN

#define NROS_PLATFORM_PRIORITY_RAW(n)   (-0x40000000 - (int32_t) (n))
#define NROS_PLATFORM_PRIORITY_IS_RAW(p) \
    ((p) <= -0x40000000 && (p) != NROS_PLATFORM_PRIORITY_INHERIT)

#define NROS_PLATFORM_PRIORITY_RAW_VALUE(p) (-0x40000000 - (int32_t) (p))

void nros_platform_task_attr_init(nros_platform_task_attr_t *attr);

int8_t nros_platform_task_init(void *task, void *attr,
                               void *(*entry)(void *), void *arg);

int8_t nros_platform_task_join(void *task);

int8_t nros_platform_task_detach(void *task);

int8_t nros_platform_task_cancel(void *task);

void nros_platform_task_exit(void);

void nros_platform_task_free(void **task);

size_t nros_platform_task_storage_size(void);
size_t nros_platform_task_storage_align(void);
size_t nros_platform_mutex_storage_size(void);
size_t nros_platform_mutex_storage_align(void);
size_t nros_platform_mutex_rec_storage_size(void);
size_t nros_platform_mutex_rec_storage_align(void);
size_t nros_platform_condvar_storage_size(void);
size_t nros_platform_condvar_storage_align(void);
 
/* ---- Opaque-storage sizes, at COMPILE time ----
 *
 * phase-364 W2 (RFC-0076 D1). The probes above answer a caller that allocates
 * at runtime. They cannot answer one that embeds these objects BY VALUE —
 * zenoh-pico's `_z_mutex_t` is a type, and a function call cannot size an
 * array — so the same facts are also available as macros.
 *
 * These are UPPER BOUNDS over every supported port, not per-port exact sizes: a
 * single header cannot know which port will link, and a consumer that embeds by
 * value must reserve enough for the one that does. Each port asserts its own
 * type fits (`_Static_assert` in its `platform.c`), so a bound that stops being
 * true is a compile error in the port rather than a silent overrun in the
 * consumer.
 *
 * They replace a hand-computed table in `zpico-sys` that recorded other
 * platforms' sizes as `≈` values with a "2× safety margin", checked by nobody,
 * about structs that are Kconfig-dependent on at least two of those platforms —
 * issue 0570's shape. The numbers below are deliberately generous for the same
 * reason the old ones were; the difference is that they are now checked.
 *
 * A port may raise a bound by defining it before including this header. */
#ifndef NROS_PLATFORM_TASK_STORAGE_SIZE
/* 512. ThreadX is the large one, and the number here is MEASURED, not
 * estimated: `sizeof(TX_THREAD)` is **360** bytes on the 64-bit Linux port,
 * plus this port's owned-stack pointer and padding.
 *
 * The estimate it replaces is worth keeping visible. `zpico-sys` recorded
 * "ThreadX TX_THREAD ≈ 232" and sized its task storage at 256 — correct for a
 * 32-bit port and 128 bytes short on a 64-bit one. That table was hand-written
 * prose about another platform's struct, which is why phase-364 W2 replaced it
 * with probes and `_Static_assert`s; this bound was raised BECAUSE one of those
 * asserts failed on the first real ThreadX build, rather than because someone
 * re-read the comment. */
#  define NROS_PLATFORM_TASK_STORAGE_SIZE     512
#endif
#ifndef NROS_PLATFORM_MUTEX_STORAGE_SIZE
/* 256, not a tighter fit, and the reason is recorded rather than guessed:
 * `zpico-sys` bounded this at 64 B, met ThreadX's `TX_MUTEX` (~120 B with
 * ownership / inheritance / suspension-list fields), and silently corrupted the
 * neighbouring field — presenting as a HANG in `Executor::open` after the zenoh
 * handshake, because every mutex op on the in-band executor trampled a
 * neighbour. Over-reserving costs bytes; under-reserving costs that. */
#  define NROS_PLATFORM_MUTEX_STORAGE_SIZE    256
#endif
#ifndef NROS_PLATFORM_MUTEX_REC_STORAGE_SIZE
#  define NROS_PLATFORM_MUTEX_REC_STORAGE_SIZE 256
#endif
#ifndef NROS_PLATFORM_CONDVAR_STORAGE_SIZE
/* POSIX `pthread_cond_t` is 48 B; a composite RTOS condvar
 * (`TX_MUTEX + TX_SEMAPHORE + UINT`) is ~184. Same reasoning as the mutex. */
#  define NROS_PLATFORM_CONDVAR_STORAGE_SIZE  256
#endif
#ifndef NROS_PLATFORM_STORAGE_ALIGN
/* Every opaque type on every supported port is at most 8-byte aligned. */
#  define NROS_PLATFORM_STORAGE_ALIGN         8
#endif
 
 
/* ---- Threading: non-recursive mutex ----
 *
 * Both mutex kinds INHERIT PRIORITY on every port (issue 1907): Zephyr's
 * `k_mutex`, FreeRTOS's mutex semaphores and ThreadX's `TX_INHERIT` do it
 * natively, and the POSIX port sets `PTHREAD_PRIO_INHERIT` (on NuttX that
 * needs CONFIG_PRIORITY_INHERITANCE, which it refuses to build without). A
 * new port must do the same: a mutex wait is exempt from the "no unbounded
 * wait" rule (issue 1196) only because inheritance bounds it. */
 
int8_t nros_platform_mutex_init(void *m);
int8_t nros_platform_mutex_drop(void *m);
int8_t nros_platform_mutex_lock(void *m);
int8_t nros_platform_mutex_try_lock(void *m);
int8_t nros_platform_mutex_unlock(void *m);
 
/* ---- Threading: recursive mutex ---- */

int8_t nros_platform_mutex_rec_init(void *m);
int8_t nros_platform_mutex_rec_drop(void *m);
int8_t nros_platform_mutex_rec_lock(void *m);
int8_t nros_platform_mutex_rec_try_lock(void *m);
int8_t nros_platform_mutex_rec_unlock(void *m);
 
/* ---- Threading: condition variables ----
 *
 * The mutex a wait releases must be held by the caller EXACTLY ONCE (issue
 * 1907). Several ports build every mutex as a recursive one, and the kernels'
 * condition waits release one level: a caller holding `m` twice would keep it
 * across the wait, and every signaller would block on it. POSIX gives the
 * same advice for a recursive mutex. ThreadX and Zephyr's native arm refuse
 * such a wait (-1). NuttX releases every level, which is not portable.
 * FreeRTOS and Zephyr's POSIX arm cannot see the count, so there such a wait
 * deadlocks. */
 
int8_t nros_platform_condvar_init(void *cv);
int8_t nros_platform_condvar_drop(void *cv);
int8_t nros_platform_condvar_signal(void *cv);
int8_t nros_platform_condvar_signal_all(void *cv);

int8_t nros_platform_condvar_signal_from_isr(void *cv);

int8_t nros_platform_condvar_wait_until(void *cv, void *m, uint64_t abstime);
 
/* ---- Threading: wake primitive (Phase 130) ----
 *
 * Binary-semaphore-shaped primitive used by the executor's wake_flag /
 * spin_once cv-wait pair. Separate from `nros_platform_condvar_*` so
 * the executor doesn't inherit zenoh-pico's pthread-shaped Zephyr
 * ABI (which on libc hangs past `pthread_cond_timedwait` deadlines).
 *
 * Per-platform impl:
 *  * POSIX:    `sem_t` with `sem_clockwait(CLOCK_MONOTONIC)` (glibc >= 2.30;
 *              elsewhere `sem_timedwait` on a re-anchored REALTIME deadline).
 *  * Zephyr:   `k_sem` (kernel-native, libc-pthread-free).
 *  * FreeRTOS: `xSemaphoreCreateBinary` + `xSemaphoreGiveFromISR`.
 *  * NuttX:    the POSIX source, via NuttX libc (`sem_clockwait`).
 *  * ThreadX:  `tx_semaphore` (ISR-safe `tx_semaphore_put`).
 *  * bare:     atomic flag + busy-spin against the platform clock.
 *
 * `wait_ms` returns 0 on signal, 1 on timeout, -1 on error.
 * `signal_from_isr` returns -1 if the backend has no ISR-safe path;
 * callers may fall back to `signal()` accepting the latency cost.
 * Storage is opaque to the caller; size/alignment via the probe
 * helpers below. */
int8_t  nros_platform_wake_init(void *w);
int8_t  nros_platform_wake_drop(void *w);
int8_t  nros_platform_wake_wait_ms(void *w, uint32_t timeout_ms);
int8_t  nros_platform_wake_signal(void *w);
int8_t  nros_platform_wake_signal_from_isr(void *w);

int8_t   nros_platform_wake_park_until_us(void *w, uint64_t deadline_us);

#define NROS_PLATFORM_PARK_SIGNALLED 0
#define NROS_PLATFORM_PARK_EXPIRED   1
#define NROS_PLATFORM_PARK_YIELDED   2

uint64_t nros_platform_wake_park_granularity_us(void);

int8_t   nros_platform_wake_park_handles_us(void *w, const int32_t *handles, size_t n,
                                            uint64_t deadline_us);

size_t  nros_platform_wake_storage_size(void);
size_t  nros_platform_wake_storage_align(void);
 
/* ---- Critical section ---- */
/* Phase 121.9 — global mutual exclusion against preemption + ISR
 * delivery. Backs the Rust `critical_section::Impl` registration used
 * by DDS, nros-rmw-{xrce,zenoh}, and any consumer of
 * `critical_section::with()`. Reentrant by contract: every acquire
 * must be paired with exactly one release, and the platform handles
 * nesting (PRIMASK already stacks; pthread side uses a recursive
 * mutex).
 *
 * The `uint32_t` token holds whatever the platform needs to restore
 * the prior posture — Cortex-M PRIMASK bit, Cortex-R CPSR I-bit,
 * RISC-V `mstatus.MIE` snapshot, pthread depth counter — and is
 * opaque to the caller. */
uint32_t nros_platform_critical_section_acquire(void);
void     nros_platform_critical_section_release(uint32_t token);
 
/* ---- Logging (Phase 88) ---- */
/* Per-platform leveled log delivery, matching the post-Phase-129
 * pattern: portable facade (`nros-log`) formats into a buffer and
 * hands the rendered text to whichever `nros-platform-<rtos>` is
 * linked in. POSIX writes to stderr; Zephyr routes through
 * `LOG_MODULE_DECLARE(nros)` (or `printk` fallback); ESP-IDF goes
 * through `esp_log_write`; NuttX through `syslog`; FreeRTOS /
 * ThreadX / bare-metal expose a `register_log_writer(...)` helper
 * in their platform crate so boards register the actual writer
 * (UART / semihosting / defmt / RTT) once at startup.
 *
 * `severity`: matches `nros_log::Severity::as_u8()`:
 *   0 = Trace, 1 = Debug, 2 = Info, 3 = Warn, 4 = Error, 5 = Fatal.
 * Implementors should map onto the platform's nearest level.
 *
 * `name_ptr` / `name_len`: logger name (NOT null-terminated; UTF-8).
 *   May be empty (the catch-all logger).
 * `msg_ptr`  / `msg_len`:  already-formatted message body (NOT null-
 *   terminated; UTF-8). Implementors that need a `CStr` must copy
 *   into their own buffer + append `'\0'`.
 *
 * No return value: log delivery never fails from the caller's POV.
 * Platforms drop silently on internal overflow (e.g. RTT ring full).
 *
 * `nros_platform_log_flush`: best-effort drain of any internal
 * buffer (RTT, syslog buffered chan, etc.). Default impl = no-op.
 *
 * Thread / ISR safety is documented per platform — see the table
 * in `docs/roadmap/phase-88-nros-log.md`. The ABI itself is
 * synchronous + reentrant-safe at the caller layer (a recursion
 * guard in `nros-log` prevents fan-out re-entry). */
void nros_platform_log_write(
    uint8_t        severity,
    const uint8_t *name_ptr, uintptr_t name_len,
    const uint8_t *msg_ptr,  uintptr_t msg_len);
void nros_platform_log_flush(void);
 
/* Board-supplied writer hook. ONLY meaningful on platforms whose
 * `nros_platform_log_write` impl is itself a thin dispatcher to a
 * board-registered fn (FreeRTOS, ThreadX, bare-metal). On platforms
 * with a native logger (POSIX, Zephyr, ESP-IDF, NuttX), the symbol
 * is absent and the board should not link against it.
 *
 * Board crates call this ONCE at startup, before any task / thread
 * begins logging. Re-calling replaces the registration.
 *
 * `writer` matches the signature of `nros_platform_log_write`.
 * `flusher` is optional (pass NULL for fully-synchronous writers). */
typedef void (*nros_platform_log_writer_fn_t)(
    uint8_t        severity,
    const uint8_t *name_ptr, uintptr_t name_len,
    const uint8_t *msg_ptr,  uintptr_t msg_len);
 
typedef void (*nros_platform_log_flush_fn_t)(void);
 
void nros_platform_register_log_writer(
    nros_platform_log_writer_fn_t writer,
    nros_platform_log_flush_fn_t  flusher);
 
/*
 * Runtime locator override (nano-ros #166 / phase-286 W1).
 *
 * Returns a middleware locator to use INSTEAD of the build-time-baked default
 * (`CONFIG_NROS_ZENOH_LOCATOR` / `option_env!("NROS_LOCATOR")`), or NULL to keep
 * the bake. Only the native_sim/native_posix platform impl returns non-NULL
 * (from `-testargs --nros-locator=<loc>`); every real-embedded impl returns
 * NULL. Entry points (Rust `zephyr_component_main!`, the C/C++ entries) prefer
 * this when non-NULL so native_sim tests can each dial a distinct per-test
 * zenohd, retiring the shared-baked-port serialization.
 *
 * The returned pointer is owned by the platform (argv-backed) and valid for the
 * process lifetime; the caller must not free it.
 */
const char* nros_runtime_locator_override(void);
 
/* ---- Fatal error (phase-366 / RFC-0077) ----
 *
 * The image's one ending. Rust's `#[panic_handler]`, a C precondition failure
 * and a C++ terminate all arrive here, so an operator debugging a board has one
 * place to look instead of four.
 *
 * Before this existed the ABI could express ALLOCATION but not fatality, so each
 * language invented its own: `nros-c` spun silently, `nros-board-nuttx` printed
 * and exited 1, the ThreadX RV64 board wrote UART and exited QEMU, the FreeRTOS
 * board did semihosting + `bkpt` + spin. Four reasonable answers to four
 * different questions, none of them the image's to choose.
 *
 * `msg` is a DIAGNOSTIC, not a C string: `len` bytes, no NUL required, possibly
 * empty (`msg` may be NULL only when `len == 0`). It is not necessarily UTF-8 —
 * a port that forwards to a text sink should treat it as bytes.
 *
 * Contract on the implementor:
 *   - MUST NOT return. Declared `_Noreturn` so a caller (and Rust's `-> !`) can
 *     rely on it.
 *   - 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 simply "log at Fatal then halt".
 *   - SHOULD emit `msg` somewhere a human can read before terminating. A silent
 *     halt is the one behaviour no RTOS in this tree chose for itself.
 *
 * Spelled through `NROS_PLATFORM_NORETURN` because this header is included from
 * C++ too (`nros-cpp`), where `_Noreturn` is not a keyword — that mismatch is a
 * hard `'_Noreturn' does not name a type` in every C++ TU, which is how it was
 * found.
 *
 * Ports map it to the fatal path they already have (`k_panic`, `PANIC()`,
 * `esp_system_abort`, the FreeRTOS hook, `abort()`). A C/C++ image overrides the
 * port's definition by defining this symbol strongly; a Rust image declares its
 * own `#[panic_handler]` in the entry package. Either way the choice belongs to
 * whoever builds the image — RFC-0077.
 */
#if defined(__cplusplus)
#  define NROS_PLATFORM_NORETURN [[noreturn]]
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
#  define NROS_PLATFORM_NORETURN _Noreturn
#else
#  define NROS_PLATFORM_NORETURN __attribute__((noreturn))
#endif
 
NROS_PLATFORM_NORETURN void nros_platform_panic(const char *msg, size_t len);
 
#ifdef __cplusplus
}  /* extern "C" */
#endif
 
#endif /* NROS_PLATFORM_H */