Struct CffiPlatform 

pub struct CffiPlatform;

Zero-sized type implementing the platform traits via the canonical nros_platform_* C symbols.

The crate that pulls CffiPlatform into a final binary is responsible for ensuring the symbols are supplied at link time (either by a C translation unit or a Rust -cffi shim crate).

Trait Implementations

impl PlatformAlloc for CffiPlatform

fn alloc(size: usize) -> *mut c_void

Allocate size bytes. Returns null on failure.

fn realloc(ptr: *mut c_void, size: usize) -> *mut c_void

Reallocate a previously allocated block. Returns null on failure.

fn dealloc(ptr: *mut c_void)

Free a previously allocated block.

fn heap_used_bytes() -> usize

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_total_bytes() -> usize

Total managed heap size in bytes (used + free), or 0 if unknown.

impl PlatformClock for CffiPlatform

fn epoch_us() -> u64

issue 0758 — forwards to the C symbol. NOT defaulted here: a C port that supplies the symbol must be able to answer, and one that does not returns 0 from its own definition. Taking the trait default instead would silently ignore a C implementation that exists.

fn clock_ns() -> u64

Monotonic nanoseconds since a platform-defined epoch. Never decreases. See <nros/platform.h> for the full contract (RFC-0073).

fn clock_resolution_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.

impl PlatformCriticalSection for CffiPlatform

fn acquire() -> u32

Enter a critical section. Returns an opaque token to pass to Self::release.

fn release(token: u32)

Leave a critical section, restoring the posture captured at Self::acquire.

impl PlatformLog for CffiPlatform

fn write(severity: u8, name: &[u8], message: &[u8])

Deliver one record. Severity is a stable u8 matching nros_log::Severity::as_u8().

fn flush()

Best-effort drain of any internal buffer. Default = no-op.

impl PlatformNetworkPoll for CffiPlatform

fn network_poll()

Poll the network stack to process pending I/O.

impl PlatformRandom for CffiPlatform

fn random_u8() -> u8

fn random_u16() -> u16

fn random_u32() -> u32

fn random_u64() -> u64

fn random_fill(buf: *mut c_void, len: usize)

Fill buffer with random bytes.

impl PlatformScheduler for CffiPlatform

fn yield_now()

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 set_current_thread_policy(_p: SchedPolicy) -> Result<(), SchedError>

Apply the requested policy to the calling thread.

fn set_affinity(_cpu_mask: u32) -> Result<(), SchedError>

Pin the calling thread to the CPUs whose bit is set in _cpu_mask. Default returns SchedError::Unsupported — platforms with affinity APIs override.

impl PlatformSleep for CffiPlatform

fn sleep_us(us: usize)

Sleep for the given number of microseconds.

fn sleep_ms(ms: usize)

Sleep for the given number of milliseconds.

fn sleep_s(s: usize)

Sleep for the given number of seconds.

impl PlatformSocketHelpers for CffiPlatform

fn set_non_blocking(sock: *const c_void) -> i8

Set socket to non-blocking mode.

fn accept(sock_in: *const c_void, sock_out: *mut c_void) -> i8

Accept a pending connection.

fn close(sock: *mut c_void)

Close a socket (shutdown + close).

fn wait_event(peers: *mut c_void, mutex: *mut c_void) -> i8

Wait for socket events (multi-threaded platforms).

impl PlatformTcp for CffiPlatform

fn create_endpoint(ep: *mut c_void, address: *const u8, port: *const u8) -> i8

Resolve address + port strings into an endpoint handle.

fn free_endpoint(ep: *mut c_void)

Free endpoint resources.

fn open(sock: *mut c_void, endpoint: *const c_void, timeout_ms: u32) -> i8

Open a TCP client connection. endpoint is by-value (opaque bytes on stack).

fn listen(sock: *mut c_void, endpoint: *const c_void) -> i8

Open a TCP listening socket.

fn close(sock: *mut c_void)

Close a TCP socket.

fn read(sock: *const c_void, buf: *mut u8, len: usize) -> usize

Read up to len bytes. Returns bytes read, or usize::MAX on error.

fn read_exact(sock: *const c_void, buf: *mut u8, len: usize) -> usize

Read exactly len bytes. Returns len on success, usize::MAX on error.

fn send(sock: *const c_void, buf: *const u8, len: usize) -> usize

Send len bytes. Returns bytes sent, or usize::MAX on error.

fn set_rx_notify( sock: *const c_void, notify: Option<unsafe extern "C" fn(*mut c_void)>, ctx: *mut c_void, ) -> i8

phase-521 W6 (RFC-0113 D4) — install (Some) or remove (None) the connected socket’s receive notification, called from the stack’s own context each time data is queued, so it must only signal.

impl PlatformThreading for CffiPlatform

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

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_join(task: *mut c_void) -> i8

Block until task exits. Cleans up the task storage on success.

fn task_detach(task: *mut c_void) -> i8

Mark task as detached — its storage is reclaimed on exit without a join.

fn task_cancel(task: *mut c_void) -> i8

Request task to terminate at the next cancellation point. Cooperative.

fn task_exit()

Terminate the calling task immediately. Does not return.

fn task_free(task: *mut *mut c_void)

Free the task storage allocated by task_init.

fn mutex_init(m: *mut c_void) -> i8

Initialise a non-recursive mutex in caller-provided storage.

fn mutex_drop(m: *mut c_void) -> i8

Tear down a non-recursive mutex.

fn mutex_lock(m: *mut c_void) -> i8

Lock; block if held.

fn mutex_try_lock(m: *mut c_void) -> i8

Try to lock; non-zero return immediately if held.

fn mutex_unlock(m: *mut c_void) -> i8

Unlock; only the owning thread may call this.

fn mutex_rec_init(m: *mut c_void) -> i8

Initialise a recursive mutex (same-thread re-entrancy permitted). Required by zenoh-pico.

fn mutex_rec_drop(m: *mut c_void) -> i8

Tear down a recursive mutex.

fn mutex_rec_lock(m: *mut c_void) -> i8

Lock; re-entry from the owning thread must succeed.

fn mutex_rec_try_lock(m: *mut c_void) -> i8

Try to lock; same re-entry semantics as mutex_rec_lock.

fn mutex_rec_unlock(m: *mut c_void) -> i8

Unlock; releases when the lock count returns to zero.

fn condvar_init(cv: *mut c_void) -> i8

Initialise a condition variable in caller-provided storage.

fn condvar_drop(cv: *mut c_void) -> i8

Tear down a condition variable.

fn condvar_signal(cv: *mut c_void) -> i8

Wake one waiter on the condition variable.

fn condvar_signal_all(cv: *mut c_void) -> i8

Wake all waiters on the condition variable.

fn condvar_signal_from_isr(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).

fn condvar_wait_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8

Atomically release m and block on cv until signalled or until the absolute monotonic deadline abstime (milliseconds since the PlatformClock::clock_ns epoch); the mutex is re-acquired before this returns. Returns 0 when signalled, 1 on timeout and -1 on error (issue 1906). The remaining time rounds UP to the port’s tick.

fn wake_init(w: *mut c_void) -> i8

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_drop(w: *mut c_void) -> i8

Tear down a wake primitive. Default returns -1 (unsupported).

fn wake_wait_ms(w: *mut c_void, timeout_ms: u32) -> i8

Block until signaled or timeout_ms elapses. Returns 0 on signal, 1 on timeout, -1 on error. Default returns -1 (unsupported).

fn wake_signal(w: *mut c_void) -> i8

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_from_isr(w: *mut c_void) -> i8

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_storage_size() -> usize

Caller-storage size requirement (bytes). Default 0 — signals “no wake primitive available”. May be called before wake_init.

fn wake_storage_align() -> usize

Caller-storage alignment requirement (bytes). Default 1.

fn task_storage_size() -> usize

Caller-storage size requirement (bytes) for a task handle.

fn task_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a task handle. Default 1.

fn task_stack_unused_bytes() -> usize

Smallest number of bytes ever left unused on the CALLING task’s stack, or 0 if this platform does not instrument it.

fn task_stack_unused_bytes_upto(limit: usize) -> usize

task_stack_unused_bytes, capped at limit, reading at most limit bytes of the stack (phase-436 E5).

fn wake_park_until_us(_w: *mut c_void, _deadline_us: u64) -> i8

phase-436 W7 — OPTIONAL microsecond park.

fn wake_park_granularity_us() -> u64

The finest park wake_park_until_us can express, in microseconds.

fn wake_park_handles_us( _w: *mut c_void, _handles: *const i32, _n: usize, _deadline_us: u64, ) -> i8

phase-521 W3 (RFC-0113 D3) — park on the wake object and on OS handles: the same park as wake_park_until_us, ended also when one of n handles at handles becomes readable.

fn mutex_storage_size() -> usize

Caller-storage size requirement (bytes) for a plain mutex.

fn mutex_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a plain mutex.

fn mutex_rec_storage_size() -> usize

Caller-storage size requirement (bytes) for a RECURSIVE mutex.

fn mutex_rec_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a recursive mutex.

fn condvar_storage_size() -> usize

Caller-storage size requirement (bytes) for a condition variable.

fn condvar_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a condition variable.

impl PlatformTime for CffiPlatform

fn time_now_ns() -> u64

Wall-clock nanoseconds since the Unix epoch, or 0 if this platform has no real-time clock.

impl PlatformTimer for CffiPlatform

type TimerHandle = CffiTimerHandle

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.

fn create_periodic( period_us: u32, callback: extern "C" fn(*mut c_void), user_data: *mut c_void, ) -> Result<Self::TimerHandle, TimerError>

Register a periodic timer that fires callback(user_data) every period_us microseconds. Returns the platform-native handle for later destruction.

fn create_oneshot( timeout_us: u32, callback: extern "C" fn(*mut c_void), user_data: *mut c_void, ) -> Result<Self::TimerHandle, TimerError>

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.

fn destroy(handle: Self::TimerHandle)

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 cancel(handle: &mut Self::TimerHandle) -> bool

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.

impl PlatformUdp for CffiPlatform

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 listen(sock: *mut c_void, endpoint: *const c_void, timeout_ms: u32) -> i8

Open a UDP socket in listen (server) mode, bound to the given endpoint. Returns 0 on success, negative on failure.

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

fn set_recv_timeout(sock: *const c_void, timeout_ms: u32)

Set the receive timeout on a UDP socket (milliseconds). 0 means block indefinitely (no timeout).

fn readiness_handle(sock: *const c_void) -> i32

phase-521 W4 (RFC-0113 D4) — the OS handle that becomes readable when a datagram arrives: a file descriptor on POSIX and NuttX.

fn set_rx_notify( sock: *const c_void, notify: Option<unsafe extern "C" fn(*mut c_void)>, ctx: *mut c_void, ) -> i8

phase-521 W4 (RFC-0113 D4) — install (Some) or remove (None) the socket’s receive notification, called from the stack’s own context each time a datagram is queued, so it must only signal.

impl PlatformUdpMulticast for CffiPlatform

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

impl PlatformYield for CffiPlatform

fn yield_now()

Relinquish the CPU long enough for another task / thread to run.