Crate nros_platform

Expand description

Unified platform abstraction traits for nros.

This crate defines the backend-agnostic interface that platform implementations (POSIX, Zephyr, FreeRTOS, bare-metal, etc.) must satisfy. RMW backends consume these traits via thin shim crates that translate RMW-specific C symbols (e.g., z_clock_now, uxr_millis) into calls on the active platform implementation.

§Trait hierarchy

Capabilities are split into independent sub-traits so each RMW backend can declare exactly what it needs:

PlatformClock — monotonic clock (required by all backends)
PlatformAlloc — heap allocation (zenoh-pico only)
PlatformSleep — sleep / delay (zenoh-pico only)
PlatformYield — cooperative yield (zenoh-pico socket_wait_event)
PlatformRandom — pseudo-random number generation (zenoh-pico only)
PlatformTime — wall-clock time (zenoh-pico only)
PlatformThreading — tasks, mutexes, condvars (multi-threaded platforms)

§Compile-time resolution

Exactly one platform feature must be enabled. The ConcretePlatform type alias (gated on any platform-* feature) resolves to the active backend, eliminating generic parameters.

Modules§

wake: Phase 130 — ergonomic Rust wrapper around PlatformThreading’s wake primitive.
xorshift32: Xorshift32 PRNG helpers shared by RTOS platform crates that lack a hardware RNG.

Structs§

DeployOverlay: Deploy-metadata overlay threaded from nros::main!() into the board’s boot config (issue #48 cause 1).
NullNodeRuntime: No-op NodeDispatchRuntime for tests / placeholders. Every call returns Err(()) so callers that depend on a populated runtime fail loud rather than silently no-op.
RuntimeCtx: Runtime context handed to BoardEntry::run(setup).
SignaledCallback: Layer-clean substitute for nros::node_metadata::CallbackId + nros::node::CallbackCtx at the NodeDispatchRuntime boundary (Phase 216.A.2). nros-platform sits below nros in the dep graph, so the trait surface cannot reference those types directly. The nros-side runtime impl wraps a real (CallbackId, &mut CallbackCtx) pair into this opaque shape before invoking NodeDispatchRuntime::signal_callback; the concrete dispatcher casts ctx_ptr back to &mut nros::CallbackCtx<'_> at the call site.
TierSpec: One scheduling tier: an RTOS task running an Executor over the shared session, admitting only the listed callback groups.
Wake: RAII wrapper around the platform’s wake primitive.

Enums§

DispatchStrategy: How a Node expects its callbacks to fire.
NetworkError: Network bringup failure mode (matches the coarse shape of [super::transport::TransportError]).
RuntimeError: Error returned by the codegen-emitted run_plan(runtime) body (Phase 212.N.4) and by Node pkg register(runtime) wrappers (Phase 212.N.7 step-2).
SchedError: Errors returned by PlatformScheduler entry points.
SchedPolicy: Per-thread OS scheduling policy.
TimerError: Errors returned by PlatformTimer entry points.
WakeInitError: Errors at construction time.
WakeReason: Reason wait_ms returned.

Constants§

NET_ENDPOINT_ALIGN
NET_ENDPOINT_SIZE
NET_SOCKET_ALIGN
NET_SOCKET_SIZE
WAKE_STORAGE_ALIGN: Alignment of the inline storage buffer. Wide enough for every pointer-aligned primitive on 64-bit hosts.
WAKE_STORAGE_BYTES: Maximum bytes the wake primitive may occupy on any supported platform. Sized generously so we never have to bump for a new RTOS port. Asserted against the runtime probe in Wake::new.

Traits§

Board: Super-trait every board impl carries (mirrors nros-board-common::board_init::Board).
BoardConfig: Universal board configuration accessors.
BoardEntry: Per-board boot driver.
BoardExit: Per-board termination contract.
BoardInit: Per-board hardware-init contract.
BoardPrint: Per-board stdout contract.
BoardTransportConfig: Phase 173.5 — mutable transport knobs the orchestration generator writes into a board Config from nros.toml [[transport]] (the NanoRosOwned net-stack path: the board owns smoltcp/lwIP/NetX, so the IP / baud value lands in the board Config rather than an RTOS config fragment).
EmbassyBoardEntry: Board-side hook for Embassy integration (Phase 216.C.1).
NetworkWait: Carrier / DHCP / link-up gate for IP-aware transports.
NodeDispatchRuntime: Node runtime sink the codegen-emitted run_plan(runtime) body talks to (Phase 212.N.7 step-3.1).
NodeRuntime: Phase 214.K.1 — backward-compat alias. The board-side dispatch sink was renamed NodeRuntime → NodeDispatchRuntime to disambiguate from the user-facing nros::NodeRuntime metadata trait. This alias stays for one release cycle so external impl callers (per-board crates outside the tree) get a clear deprecation arrow rather than a hard break. Node runtime sink the codegen-emitted run_plan(runtime) body talks to (Phase 212.N.7 step-3.1).
PlatformAlloc: Heap memory allocation.
PlatformClock: Monotonic clock.
PlatformCriticalSection: Global mutual exclusion against preemption + ISR delivery (Phase 121.9).
PlatformIvc: Inter-processor mailbox transport, modelled after NVIDIA Tegra IVC.
PlatformLibc: Standard C library functions needed by zenoh-pico on bare-metal targets.
PlatformLog: Per-platform leveled log delivery.
PlatformNetworkPoll: Network poll callback for bare-metal platforms using smoltcp.
PlatformRandom: Pseudo-random number generation.
PlatformScheduler
PlatformSerial: Serial (byte-stream) transport.
PlatformSleep: Sleep primitives.
PlatformSocketHelpers: Socket helper operations called by zenoh-pico’s transport layer.
PlatformTcp: TCP networking.
PlatformThreading: Threading primitives: tasks, mutexes, and condition variables.
PlatformTime: Wall-clock / system time.
PlatformTimer: 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.
PlatformUdp: UDP unicast networking.
PlatformUdpMulticast: UDP multicast networking (used for zenoh scouting on desktop platforms).
PlatformYield: Scheduler yield primitive.
RticBoardEntry: Board-side hook for RTIC integration. The nros::main!() proc-macro (216.B.3) generates a #[rtic::app] module that calls Self::init_hardware from inside the framework-generated #[init] body and wires the returned pair into RTIC #[local] storage.
TransportBringup: Per-board transport bringup contract.

Functions§

freertos_priority_for: FreeRTOS native priority (0..=configMAX_PRIORITIES-1, here 0–7) for a normalized 0–31 priority. RFC-0016 §Design: linear interpolation (n*7 + 15) / 31 (round-to-nearest), so 0→0 (idle) and 31→7 (highest). Higher number = higher priority on FreeRTOS.
posix_nice_for: POSIX nice value (-20..=19, lower = more CPU) for a normalized 0–31 priority. Best-effort: native preemption normally uses the default scheduler (strict ordering needs SCHED_FIFO + privileges), so this is an advisory niceness, linear over the scale and clamped, with idle (0) pinned to the maximum 19. Anchors track the RFC-0016 table (12→0 normal, 31→-20 critical).
threadx_priority_for: ThreadX native priority (0..=31, lower = higher priority) for a normalized 0–31 priority. RFC-0016: inverted scale 31 - n, so the normalized idle (0) maps to ThreadX 31 (lowest) and normalized critical (31) maps to ThreadX 0 (highest).

Type Aliases§

ConcretePlatform