OS adapters: tasks, waits and explicit storage

These declarations come from public header files. Selection, lifecycle, supported execution modes and physical authorization remain bounded by the corresponding design and support records.

baremetal.h

Bare-metal poll notification with caller-owned storage.

Author

Nexus Team

Functions

nx_result_t nx_baremetal_notify_init(nx_baremetal_notify_t *notification, uint64_t (*now_us)(void*), void *clock_context)

Initialize storage before exposing it to any ISR.

Note

Startup context; not a task/queue emulation. Word publication uses the reviewed inline compiler/CPU port.

Parameters:

  • notification – [out] Unused caller-owned storage

  • now_us – [in] Monotonic microsecond source, continuing while waiting

  • clock_context – [in] Clock source context

Returns:

NX_SUCCESS or NX_ERROR_INVALID

nx_wait_port_t nx_baremetal_notify_port(nx_baremetal_notify_t *notification)

Bind the explicit polling notification.

Note

wake uses compiler RMW or, on M0/M0+, a bounded saved PRIMASK guard. That guard requires one CPU and privileged Thread/configurable-IRQ callers; NMI/HardFault, unprivileged, DMA and other security-domain access to its metadata are unsupported. The owner loop continues to service controller/drain after BUSY. No WFI/WFE is inserted without a reviewed architecture-specific atomic sleep contract.

Parameters:

  • notification – [in] Initialized storage

Returns:

Port whose wait returns BUSY while unchanged before deadline; NX_DEADLINE_NEVER disables expiry, never implies blocking

struct nx_baremetal_notify_t
#include <baremetal.h>

Explicit nonblocking bare-metal notification storage.

Public Members

uint32_t sequence
uint64_t (*now_us)(void*)
void *clock_context

diagnostic.h

Bounded diagnostics with explicit caller-owned ring storage.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_result_t nx_diagnostic_ring_init(nx_diagnostic_ring_t *ring, nx_diagnostic_event_t *events, size_t capacity)

Initialize unpublished ring and caller-owned entries.

Note

Startup or exclusive lifecycle owner only. Both allocations remain alive until all publishers and readers are stopped. Entries cannot alias ring state or a submitted record.

Parameters:

  • ring – [out] Unused caller-owned state.

  • events – [in] Naturally aligned contiguous entry storage.

  • capacity – [in] Nonzero storage length, at most UINT32_MAX.

Returns:

SUCCESS or INVALID without modifying storage on rejection.

nx_result_t nx_diagnostic_ring_write(nx_diagnostic_ring_t *ring, const nx_diagnostic_event_t *event)

Copy one event under a bounded saved interrupt mask.

Note

Privileged Thread/configurable IRQ on one CPU only. NMI/HardFault, unprivileged, SMP, DMA and other security worlds are excluded. Full rings retain older records and saturate the lost-record counter. No clock callback, OS operation, heap, string formatting or transport is used.

Parameters:

  • ring – [inout] Initialized ring.

  • event – [in] Stable record until this call returns.

Returns:

SUCCESS, BUSY when full, INVALID or CONTEXT.

nx_result_t nx_diagnostic_ring_read(nx_diagnostic_ring_t *ring, nx_diagnostic_event_t *event)

Consume one event from caller-owned ring.

Note

Same privileged single-CPU domain as write. Failed reads leave destination unchanged. This is diagnostic storage, never a completion queue or application work queue.

Parameters:

  • ring – [inout] Initialized ring with live producers.

  • event – [out] Separate caller-owned destination.

Returns:

SUCCESS, BUSY when empty, INVALID or CONTEXT.

nx_result_t nx_diagnostic_ring_dropped(const nx_diagnostic_ring_t *ring, uint32_t *dropped)

Snapshot the saturating overflow count.

Note

Uses the same bounded saved-mask domain as record access.

Parameters:

  • ring – [in] Initialized ring.

  • dropped – [out] Caller-owned result.

Returns:

SUCCESS, INVALID or CONTEXT.

struct nx_diagnostic_event_t
#include <diagnostic.h>

One opaque diagnostic record; interpretation belongs to its owner.

Public Members

uint64_t timestamp
uintptr_t identity
uint32_t value
uint32_t event
struct nx_diagnostic_ring_t
#include <diagnostic.h>

Explicit ring state, with no default pool, worker or transport.

Public Members

nx_diagnostic_event_t *events
uint32_t capacity
uint32_t read_index
uint32_t write_index
uint32_t count
uint32_t dropped

freertos.h

Per-object static FreeRTOS storage and optional thin services.

Author

Nexus Team

Note

Running task operations require privileged unmasked Thread mode; IRQ wake has its own contract. Before scheduler start, the selected Baseline port may retain PRIMASK=1 or the Mainline port its exact syscall BASEPRI; all other masks must be zero. Matching a value cannot prove mask provenance. Unsafe contexts return CONTEXT before mutating kernel APIs or object storage; a scheduler-state read may be needed. Startup permits init, task creation, wake and zero-wait queues. Wait, join and nonzero waits require a running scheduler. Port binding and sequence snapshots remain reads. MPU user-task gateways and cross-world secure task calls are outside these privileged, current-security-domain APIs.

Typedefs

typedef struct nx_freertos_queue_waiter nx_freertos_queue_waiter_t

Caller-owned single-operation latch for a closable queue.

Functions

bool nx_freertos_isr_allowed(void)

Test whether the current context may call kernel ISR APIs.

Note

Native POSIX has no physical IRQ and returns false. NMI, faults and kernel-owned exceptions are rejected before entering FreeRTOS. Mainline priority/grouping must respect the syscall ceiling. Baseline PRIMASK ports accept every configurable IRQ and do not read Mainline priority grouping. Nonsecure permission does not exclude Secure-side accesses.

Returns:

True for a privileged unmasked external Cortex-M IRQ within the selected CPU/SoC bounds and kernel mask contract

nx_result_t nx_freertos_notify_init(nx_freertos_notify_t *notification)

Initialize unused notification storage.

Note

Task/startup context; no heap or timer daemon is needed.

Parameters:

  • notification – [out] Caller storage, zeroed before first use

Returns:

SUCCESS or invalid/context/initialization error

nx_wait_port_t nx_freertos_notify_port(nx_freertos_notify_t *notification)

Bind a latched single-waiter notification.

Note

Task wake uses xSemaphoreGive. IRQ wake validates priority then uses xSemaphoreGiveFromISR. Saturated latch is harmless; sequence and request predicates remain authoritative. No deferred daemon publishes wakes.

Parameters:

  • notification – [in] Initialized live storage

Returns:

Notification port using nx_time_now_us clock domain

nx_result_t nx_freertos_notify_destroy(nx_freertos_notify_t *notification)

Destroy after publishers and waiter have stopped and joined.

Note

Task context. Quiescence is required beyond this busy check.

Parameters:

  • notification – [inout] Live storage with no future users

Returns:

SUCCESS, BUSY if a waiter is still registered, or error

nx_result_t nx_freertos_task_start(nx_freertos_task_t *task, const char *name, StackType_t *stack, size_t stack_words, UBaseType_t priority, void (*entry)(void*), void *context)

Create one task from its exact caller-owned stack and TCB.

Note

Task/startup context. No hidden worker or maximum pool. Entry must return in privileged Thread mode, with manual interrupt masks restored and the scheduler resumed after any temporary suspension.

Parameters:

  • task – [out] Zero-initialized unused control storage

  • name – [in] Kernel diagnostic name, copied by the kernel

  • stack – [in] StackType_t array kept until successful join

  • stack_words – [in] Actual capacity, at least the selected port startup minimum; runtime stack budget remains caller-owned

  • priority – [in] Priority below configMAX_PRIORITIES

  • entry – [in] Application entry, may return after cooperative stop

  • context – [in] Entry context kept until join

Returns:

SUCCESS or invalid/context/start error

nx_result_t nx_freertos_task_discard_before_scheduler(nx_freertos_task_t *task)

Discard one created task before its wrapper has executed.

Note

Single privileged startup lifecycle owner; scheduler state must be NOT_STARTED. The kernel candidate is first suspended to remove its retained TCB reference before deletion. No unmatched vTaskSuspendAll may remain during bootstrap: NOT_STARTED cannot reveal the kernel’s private suspension nesting. This caller precondition applies before mutation. Success permits TCB, stack and context reuse after all external users are quiescent. This does not cancel or join an executed task.

Parameters:

  • task – [inout] Live caller-owned static task, unused by other callers

Returns:

SUCCESS after synchronous kernel deletion and latch cleanup; INVALID for absent, incomplete or already entered control; CONTEXT for ISR, unprivileged, noncanonical masks or a running/suspended scheduler, without mutation

nx_result_t nx_freertos_task_join(nx_freertos_task_t *task, nx_time_us_t deadline)

Join a cooperatively returned task and reclaim kernel state.

Note

Single joiner, task context. The entry return parks its wrapper; no self-delete/idle cleanup race releases caller storage early. Stop producers, keep bus owner draining, join producers, then join owner.

Parameters:

  • task – [inout] Started task, distinct from current task

  • deadline – [in] Absolute wait deadline in nx_time_now_us domain

Returns:

SUCCESS only after external vTaskDelete removes the task; TIMEOUT retains handle, TCB, stack and context; CONTEXT rejects unsafe CPU context, self-join or stopped scheduler

nx_result_t nx_freertos_queue_init(nx_freertos_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size)

Create an exact-sized static byte-copy queue.

Parameters:

  • queue – [out] Zero-initialized caller queue control

  • storage – [in] Byte buffer kept until destroy

  • storage_bytes – [in] Actual byte capacity

  • depth – [in] Number of items

  • item_size – [in] Bytes copied per item

Returns:

SUCCESS or invalid/context/start error

nx_result_t nx_freertos_queue_send(nx_freertos_queue_t *queue, const void *item, TickType_t wait_ticks)

Copy an item with a bounded relative kernel wait.

Note

Task context. Admission/stop belongs to the application’s explicit owner adapter, not this generic copy queue.

Parameters:

  • queue – [inout] Live queue

  • item – [in] At least configured item bytes; not retained afterward

  • wait_ticks – [in] Explicit relative wait; portMAX_DELAY prohibited

Returns:

SUCCESS, TIMEOUT, INVALID or CONTEXT

nx_result_t nx_freertos_queue_receive(nx_freertos_queue_t *queue, void *item, TickType_t wait_ticks)

Receive one byte-copy item.

Parameters:

  • queue – [inout] Live queue

  • item – [out] Configured item byte capacity, valid only on success

  • wait_ticks – [in] Explicit relative wait; portMAX_DELAY prohibited

Returns:

SUCCESS, TIMEOUT, INVALID or CONTEXT

nx_result_t nx_freertos_queue_destroy(nx_freertos_queue_t *queue)

Destroy after admission is stopped and all users joined.

Parameters:

  • queue – [inout] Live drained queue, no future operations

Returns:

SUCCESS, BUSY while users/items remain, or invalid/context

nx_result_t nx_freertos_queue_send_until(nx_freertos_queue_t *queue, const void *item, nx_time_us_t deadline)

Send using one absolute monotonic deadline.

Note

Immediate readiness wins over expiration. Stop admission and user quiescence remain external raw-queue obligations.

Parameters:

  • queue – [inout] Live raw queue

  • item – [in] Configured bytes borrowed until return

  • deadline – [in] nx_time_now_us domain, NEVER permits long waits

Returns:

SUCCESS, TIMEOUT or validation/context error

nx_result_t nx_freertos_queue_receive_until(nx_freertos_queue_t *queue, void *item, nx_time_us_t deadline)

Receive using one absolute monotonic deadline.

Parameters:

  • queue – [inout] Live raw queue

  • item – [out] Configured bytes valid only on SUCCESS

  • deadline – [in] nx_time_now_us domain

Returns:

SUCCESS, TIMEOUT or validation/context error

nx_result_t nx_freertos_direct_notify_init(nx_freertos_direct_notify_t *notification, TaskHandle_t receiver, UBaseType_t index)

Bind an exclusive slot of one live receiver task.

Note

Caller ensures slot exclusivity. No global slot registry, allocation, slot discovery or cross-world synchronization.

Parameters:

  • notification – [out] Zeroed caller storage

  • receiver – [in] Task retained until all publishers quiesce

  • index – [in] Exclusively owned kernel notification slot

Returns:

SUCCESS, INVALID, CONTEXT or UNSUPPORTED by OS profile

nx_wait_port_t nx_freertos_direct_notify_port(nx_freertos_direct_notify_t *notification)

Get a direct notification wait port.

Note

Only receiver may wait. Task/validated IRQ publishers use the exclusive slot; notification remains a predicate hint.

Parameters:

  • notification – [in] Live explicitly bound storage

Returns:

Port using nx_time_now_us or an invalid zero port

nx_result_t nx_freertos_direct_notify_destroy(nx_freertos_direct_notify_t *notification)

Unbind after all publishers stop and join.

Note

Does not delete receiver or clear its kernel slot. Receiver and storage must outlive every retained port and publisher.

Parameters:

  • notification – [inout] Live storage with no future users

Returns:

SUCCESS, BUSY if waiting, or validation/context error

nx_result_t nx_freertos_permanent_task_start(nx_freertos_permanent_task_t *task, const char *name, StackType_t *stack, size_t stack_words, UBaseType_t priority, void (*entry)(void*), void *context)

Start a task whose entry must never return.

Note

No join latch, destroy or forced deletion. Choose joinable tasks for cooperative shutdown and reclaimable storage.

Parameters:

  • task – [out] Zeroed permanent control, retained until reset

  • name – [in] Copied kernel diagnostic name

  • stack – [in] Aligned actual stack retained until reset

  • stack_words – [in] Capacity includes reviewed startup minimum

  • priority – [in] Below configMAX_PRIORITIES

  • entry – [in] Permanent entry; return violates kernel contract

  • context – [in] Retained until reset

Returns:

SUCCESS or validation/context/start error

nx_result_t nx_freertos_queue_waiter_init(nx_freertos_queue_waiter_t *waiter)

Initialize one exact caller-owned queue waiter.

Parameters:

  • waiter – [out] Zeroed storage, one simultaneous operation maximum

Returns:

SUCCESS or validation/context/start error

nx_result_t nx_freertos_queue_waiter_destroy(nx_freertos_queue_waiter_t *waiter)

Destroy only after all operations stop and join.

Parameters:

  • waiter – [inout] Live storage without future callers

Returns:

SUCCESS, BUSY if active, or validation/context error

nx_result_t nx_freertos_closable_queue_init(nx_freertos_closable_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size, size_t maximum_waiters)

Initialize an optional reliably closable byte-copy queue.

Note

No hidden worker or waiter pool. Each concurrent blocking operation supplies its own initialized waiter. Broadcasting pauses scheduling while visiting at most maximum_waiters latches. Kernel payload copies and each latch signal have their own short IRQ guards. Budget scheduling delay and IRQ latency separately. Large payloads should queue stable handles. The registry is single-core and task-only.

Parameters:

  • queue – [out] Zeroed control kept until destroy

  • storage – [in] Payload buffer kept until destroy

  • storage_bytes – [in] Actual payload capacity

  • depth – [in] Positive item count

  • item_size – [in] Positive byte-copy size

  • maximum_waiters – [in] Explicit positive simultaneous-call budget

Returns:

SUCCESS or validation/context/start error

nx_result_t nx_freertos_closable_queue_send_until(nx_freertos_closable_queue_t *queue, const void *item, nx_time_us_t deadline, nx_freertos_queue_waiter_t *waiter)

Send with close-aware admission and absolute deadline.

Note

Readiness/admission and close serialize in a kernel task scheduling guard. A latched wake closes wake-before-sleep.

Parameters:

  • queue – [inout] Live closable queue

  • item – [in] Bytes borrowed until return, never after timeout

  • deadline – [in] nx_time_now_us domain, NEVER supported

  • waiter – [inout] Exclusive initialized caller waiter

Returns:

SUCCESS, CANCELLED after close, TIMEOUT, BUSY or error

nx_result_t nx_freertos_closable_queue_receive_until(nx_freertos_closable_queue_t *queue, void *item, nx_time_us_t deadline, nx_freertos_queue_waiter_t *waiter)

Receive existing items after close, then CANCELLED.

Parameters:

  • queue – [inout] Live closable queue

  • item – [out] Configured bytes valid only on SUCCESS

  • deadline – [in] nx_time_now_us domain

  • waiter – [inout] Exclusive initialized caller waiter

Returns:

SUCCESS, CANCELLED when closed/empty, TIMEOUT or error

nx_result_t nx_freertos_closable_queue_close(nx_freertos_closable_queue_t *queue)

Stop sends and wake every currently registered waiter.

Note

Task-only, no forced cancellation or task deletion. Close does not join users or authorize storage reclamation.

Parameters:

  • queue – [inout] Live queue

Returns:

SUCCESS, including repeated close, or validation/context

nx_result_t nx_freertos_closable_queue_destroy(nx_freertos_closable_queue_t *queue)

Destroy a closed, drained and quiesced queue.

Note

Stop/join producers, drain with owner, join consumers and then destroy queue and every waiter independently.

Parameters:

  • queue – [inout] Live queue without future entrants

Returns:

SUCCESS, BUSY while open/users/items remain, or error

struct nx_freertos_notify_t
#include <freertos.h>

Static binary latch; one waiter, independently quiesced publishers.

Public Members

StaticSemaphore_t storage
SemaphoreHandle_t handle
uint32_t sequence
uint32_t waiting
struct nx_freertos_task_t
#include <freertos.h>

Task has its own TCB; stack is supplied with its actual word count.

Note

Control fields are adapter-owned. The caller zero-initializes storage before first use and does not modify live fields. Entry is consumed as the wrapper begins execution; context remains borrowed until successful join or prestart discard.

Public Members

StaticTask_t control
StaticSemaphore_t finished_storage
SemaphoreHandle_t finished
TaskHandle_t handle
void (*entry)(void*)
void *context
struct nx_freertos_queue_t
#include <freertos.h>

Queue control only; actual depth/item byte storage is external.

Public Members

StaticQueue_t control
QueueHandle_t handle
uint32_t users
struct nx_freertos_direct_notify_t
#include <freertos.h>

Fixed receiver and exclusive kernel notification slot; no latch.

Public Members

TaskHandle_t receiver
UBaseType_t index
uint32_t sequence
uint32_t waiting
struct nx_freertos_permanent_task_t
#include <freertos.h>

Permanent task control without a join completion semaphore.

Public Members

StaticTask_t control
TaskHandle_t handle
struct nx_freertos_queue_waiter
#include <freertos.h>

Caller-owned single-operation latch for a closable queue.

Public Members

StaticSemaphore_t storage
SemaphoreHandle_t handle
struct nx_freertos_queue_waiter *next
uint32_t active
struct nx_freertos_closable_queue_t
#include <freertos.h>

Opt-in close broadcasts; raw queue storage remains unchanged.

Public Members

nx_freertos_queue_t queue
nx_freertos_queue_waiter_t *send_waiters
nx_freertos_queue_waiter_t *receive_waiters
uint32_t maximum_waiters
bool closed

freertos_diagnostics.h

Bounded explicit FreeRTOS trace sink without global storage.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Enums

enum nx_freertos_trace_kind_t

Maintained kernel trace identities; product interpretation is external.

Values:

enumerator NX_FREERTOS_TRACE_SWITCH_IN
enumerator NX_FREERTOS_TRACE_CREATE
enumerator NX_FREERTOS_TRACE_DELETE

Functions

void nx_freertos_trace_event(nx_freertos_trace_kind_t event, uintptr_t identity, uint32_t value)

Consume one bounded kernel trace event.

Note

Application may override the weak no-op and write an explicit nx_diagnostic_ring_t. May run under kernel masks or configurable IRQ, so never block, allocate, format, transmit, acquire OS locks or call kernel services. The sink owns timestamp and lifetime; no buffer is provided automatically. Trace profile enables real kernel hooks.

Parameters:

  • event – [in] Maintained trace kind.

  • identity – [in] Opaque task identity, never a dereference license.

  • value – [in] Optional caller-defined numeric diagnostic.

freertos_mpu.h

Privileged static lifecycle for isolated MPU user tasks.

Author

Nexus Team

Enums

enum nx_freertos_mpu_access_t

User data is nonexecuting normal RAM with only these permissions.

Values:

enumerator NX_FREERTOS_MPU_READ_ONLY
enumerator NX_FREERTOS_MPU_READ_WRITE

Functions

nx_result_t nx_freertos_mpu_task_start(nx_freertos_mpu_task_t *task, const nx_freertos_mpu_config_t *config)

Create an unprivileged task from exact caller-owned storage.

Note

Privileged Thread only, scheduler not suspended, no manual masks. Rejection retains no references and calls no kernel creation API. Actual linker bounds and MPU_TYPE are checked. Minimum creation capacity is 64 words; applications budget actual execution depth separately. No heap or object pool.

Parameters:

  • task – [inout] Zero/live-free metadata in protected linker RAM.

  • config – [in] Validated user entry, stack and data mappings.

Returns:

Success or INVALID/CONTEXT/STATE/BUSY/IO before admission.

nx_result_t nx_freertos_mpu_task_delete(nx_freertos_mpu_task_t *task)

Delete another isolated task after external users quiesce.

Note

One privileged lifecycle owner stops external access first. Single-core kernel deletion removes scheduler references synchronously. Self deletion is rejected; no hidden reaper.

Parameters:

  • task – [inout] Owned live protected metadata; never the calling task.

Returns:

Success, INVALID, CONTEXT or STATE with storage retained.

struct nx_freertos_mpu_region_t
#include <freertos_mpu.h>

A caller-selected exact region, copied during task creation.

Public Members

void *address
size_t bytes
nx_freertos_mpu_access_t access
struct nx_freertos_mpu_task_t
#include <freertos_mpu.h>

Complete caller-owned protected task metadata.

Note

Zero-initialize in privileged RAM. The TCB includes the real port’s context and syscall stack, inaccessible to users. One privileged lifecycle owner serializes start/delete.

Public Members

StaticTask_t control
TaskHandle_t handle
struct nx_freertos_mpu_config_t
#include <freertos_mpu.h>

Immutable creation inputs, borrowed for this call only.

Note

The entry must be explicit user code and must not return. Stack and context data remain borrowed until owner deletion; regions never include kernel RAM, code or MMIO. Context must be contained in the user stack, user flash or mapped data. Names terminate within configMAX_TASK_NAME_LEN in a readable reserved linker region; names are copied cold.

Public Members

TaskFunction_t entry
void *context
size_t context_bytes
const char *name
StackType_t *stack
size_t stack_words
UBaseType_t priority
const nx_freertos_mpu_region_t *regions
size_t region_count

freertos_stack.h

Optional bounded task stack paint snapshot.

Author

Nexus Team

Functions

nx_result_t nx_freertos_stack_observe(const nx_freertos_stack_binding_t *binding, nx_stack_observation_t *out)

Copy bounded stack paint facts using actual kernel identity.

Note

Privileged unmasked running Thread; task stack quiescent throughout the scan. Available only with NEXUS_OS_TRACE. xTaskGetStaticBuffers verifies TCB/stack identity, not size. The original capacity is a caller contract. No task suspend, interrupt mask, allocation or live painting is performed. Worst-case work is words*sizeof(StackType_t) byte reads. Paint is the locked kernel’s 0xA5. Untouched/touched bytes do not prove physical stack peaks. The POSIX kernel port uses a separate pthread execution stack; its query is not an MCU or Linux execution-stack peak measurement.

Parameters:

  • binding – [in] Exact original TCB, stack and capacity, all live.

  • out – [out] Distinct output, unchanged on rejection.

Returns:

SUCCESS, INVALID, CONTEXT or STATE for a binding mismatch.

struct nx_freertos_stack_binding_t
#include <freertos_stack.h>

Exact static task facts supplied at original creation.

Note

The caller retains all storage, excludes delete/join/discard and never replaces the live binding. This is not a registry.

Public Members

TaskHandle_t handle
StaticTask_t *control
StackType_t *stack
size_t words

freertos_user.h

Narrow pointer-free services for MPU-isolated user tasks.

Author

Nexus Team

Defines

NX_FREERTOS_USER_CODE

Explicitly reviewed unprivileged executable code section.

NX_FREERTOS_USER_DATA

Explicit user RAM, separate from kernel and provider state.

NX_FREERTOS_PRIVILEGED_DATA

Trusted static task metadata placed in protected kernel RAM.

Functions

void nx_freertos_user_delay(uint32_t ticks)

Delay the calling user task through the real MPU SVC.

Note

Thread only with a running scheduler. No handle or pointer crosses the boundary. This is not a microsecond deadline.

Parameters:

  • ticks – [in] Relative kernel ticks; zero requests rescheduling.

uint32_t nx_freertos_user_ticks(void)

Read the kernel’s wrapping 32-bit tick counter through SVC.

Note

Thread-only MPU profile service, distinct from Core time. No object, memory, I/O or privilege-changing API exists.

Returns:

Current kernel tick count in the selected OS clock domain.

lowpower.h

Explicit continuous-clock tickless timer port.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Defines

NX_FREERTOS_LATE_TICK_BUDGET

Bounded late alarm catch-up; larger delays violate the timer port.

Functions

const nx_freertos_lowpower_port_t *nx_freertos_lowpower_port(void)

Return the explicitly selected continuous timer port.

Note

A maintained SoC binding or application implementation overrides the weak NULL default. The port and context remain live throughout the scheduler; no runtime rebinding, hidden pool or worker is provided. Absence of a port never stops ticks or sleeps.

Returns:

Stable port or NULL to leave normal periodic ticking.

void nx_freertos_suppress_ticks_and_sleep(uint32_t expected_idle_ticks)

Kernel tickless hook with measured phase preservation.

Note

Called only by Idle with scheduler suspended. Uses reviewed masked shallow WFI, exact saved PRIMASK restoration and bounded pended-tick catch-up. The configured tick rate must divide 1000000 exactly. The final kernel readiness check precedes tick pause; a rejected pause makes no changes. Default profiles do not call this hook. HIL must verify the concrete timer, clock continuity and actual wake latency.

Parameters:

  • expected_idle_ticks – [in] Kernel’s bounded next-unblock window.

struct nx_freertos_tick_snapshot_t
#include <lowpower.h>

Stopped-tick epoch with the concrete port’s declared precision.

Public Members

uint64_t time_us
uint32_t phase_us
struct nx_freertos_lowpower_port_t
#include <lowpower.h>

Caller-owned, immutable tickless timer implementation.

All methods run in privileged Idle Thread mode with PRIMASK=1 and scheduler suspended. They are bounded, never block or call kernel functions. pause_tick atomically stops the periodic tick and snapshots elapsed phase in its current tick period; a pending tick is rejected without effects. SUCCESS borrows the timer until resume_tick. now_us is the same monotonic clock as snapshot, continuous during shallow sleep. arm_deadline programs an enabled IRQ wake source; rejection retains no alarm. disarm removes only that alarm. resume_tick restores the periodic source with its next expiry at the supplied absolute clock instant, preserving phase within its declared quantization and sampling bound rather than adding callback latency to every tick. It must not publish an already accounted tick. The alarm wakes by deadline; at most eight extra ticks of latency may be caught up. Reversed clocks or larger latency fail stop. This does not configure clocks, NVIC, SCR or a board timer.

Public Members

void *context
uint64_t (*now_us)(void *context)
nx_result_t (*pause_tick)(void *context, nx_freertos_tick_snapshot_t *snapshot)
nx_result_t (*arm_deadline)(void *context, uint64_t deadline_us)
void (*disarm)(void *context)
void (*resume_tick)(void *context, uint64_t next_tick_us)

native.h

Explicit POSIX notification, queue and task storage.

Author

Nexus Team

Functions

uint64_t nx_native_now_us(void)

Read POSIX monotonic microseconds.

Returns:

Clock value; clock_gettime failure is process-fatal

nx_result_t nx_native_notify_init(nx_native_notify_t *notification)

Initialize a notification in unused caller storage.

Note

Task context; POSIX signal handlers are unsupported.

Parameters:

  • notification – [out] Storage kept alive through all publishers

Returns:

NX_SUCCESS or an initialization error

nx_wait_port_t nx_native_notify_port(nx_native_notify_t *notification)

Bind a single-waiter latched notification port.

Parameters:

  • notification – [in] Initialized storage

Returns:

Port using CLOCK_MONOTONIC absolute microseconds and NX_DEADLINE_NEVER for untimed waiting

nx_result_t nx_native_notify_destroy(nx_native_notify_t *notification)

Destroy after external publisher quiescence.

Note

Stop and join publishers first. The check cannot authorize a future call to race destruction. No storage access is allowed afterward.

Parameters:

  • notification – [inout] Live storage with no future publishers

Returns:

NX_SUCCESS or BUSY when a waiter is still registered

nx_result_t nx_native_queue_init(nx_native_queue_t *queue, void *storage, size_t storage_bytes, size_t depth, size_t item_size)

Initialize an explicit bounded byte-copy queue.

Note

Task context; caller keeps buffer until successful destroy.

Parameters:

  • queue – [out] Unused caller storage

  • storage – [in] Caller-owned byte buffer

  • storage_bytes – [in] Actual byte capacity

  • depth – [in] Number of items, greater than zero

  • item_size – [in] Bytes per item, greater than zero

Returns:

NX_SUCCESS or invalid/initialization error

nx_result_t nx_native_queue_send(nx_native_queue_t *queue, const void *item, uint64_t deadline_us)

Copy one item to the queue.

Note

Immediately available capacity is used even at an expired deadline. A finite deadline bounds waiting; spurious wakes never restart its budget. No item is retained on failure.

Parameters:

  • queue – [inout] Live queue

  • item – [in] At least item_size bytes, borrowed during call only

  • deadline_us – [in] Absolute CLOCK_MONOTONIC deadline or NX_DEADLINE_NEVER

Returns:

SUCCESS, TIMEOUT, STATE (closed) or error

nx_result_t nx_native_queue_receive(nx_native_queue_t *queue, void *item, uint64_t deadline_us)

Receive one item; closed queues can still be drained.

Note

An immediately available item can be received at an expired deadline. On failure the output is unchanged. Closed queues return STATE only after existing items have been drained.

Parameters:

  • queue – [inout] Live queue

  • item – [out] At least item_size bytes; valid only on SUCCESS

  • deadline_us – [in] Absolute CLOCK_MONOTONIC deadline or NX_DEADLINE_NEVER

Returns:

SUCCESS, TIMEOUT, STATE (closed) or error

nx_result_t nx_native_queue_close(nx_native_queue_t *queue)

Reject sends and wake all waiting callers.

Note

Task context; caller must join queue users before destroy.

Parameters:

  • queue – [inout] Live queue

Returns:

NX_SUCCESS or invalid error

nx_result_t nx_native_queue_destroy(nx_native_queue_t *queue)

Destroy quiesced and drained queue storage.

Parameters:

  • queue – [inout] Closed queue, no future users

Returns:

NX_SUCCESS or BUSY if users/items remain

nx_result_t nx_native_task_start(nx_native_task_t *task, void *stack, size_t stack_bytes, void (*entry)(void*), void *context)

Start a task using the supplied host stack.

Note

Task context. No default task, pool or hidden stack exists. POSIX library bookkeeping is host-runtime allocation, not MCU RAM evidence.

Parameters:

  • task – [out] Zero-initialized unused caller handle

  • stack – [in] Aligned storage accepted by pthread_attr_setstack

  • stack_bytes – [in] Host stack size, at least PTHREAD_STACK_MIN

  • entry – [in] Returning bounded application entry

  • context – [in] Entry context, kept alive until join

Returns:

NX_SUCCESS or invalid/start error

nx_result_t nx_native_task_join(nx_native_task_t *task)

Join after requesting cooperative application stop.

Note

May block until entry returns. No forced cancellation. Caller may release context, handle and stack only after success. One external owner serializes start/join; multiple simultaneous joiners and external pthread_cancel/detach are unsupported. Stop/join publishers before destroying their notification or queue storage.

Parameters:

  • task – [inout] Started task; caller must not be the joined task

Returns:

NX_SUCCESS only after pthread_join confirms execution exit

struct nx_native_notify_t
#include <native.h>

Single waiter, multiple task publishers; fields are private.

Note

Initialize/destroy have one external lifecycle owner. Stop and join all publishers and the waiter before destroy. External pthread_cancel of a caller blocked in these APIs is unsupported; use cooperative stop, publish and join.

Public Members

pthread_mutex_t mutex
pthread_cond_t condition
uint32_t sequence
bool initialized
bool waiting
struct nx_native_queue_t
#include <native.h>

Caller-sized queue storage; no heap or global object pool.

Note

One lifecycle owner initializes, closes and destroys. Multiple producers/consumers are supported while live. External pthread_cancel of blocked users is unsupported.

Public Members

pthread_mutex_t mutex
pthread_cond_t readable
pthread_cond_t writable
uint8_t *bytes
size_t depth
size_t item_size
size_t head
size_t count
size_t users
bool closed
bool initialized
struct nx_native_task_t
#include <native.h>

Explicit task handle; stack storage is supplied at start.

Note

Start/join are serialized by one external lifecycle owner; there is one joiner. An entry may attempt a self-join, which returns BUSY. External cancellation and detachment are unsupported.

Public Members

pthread_t thread
void (*entry)(void*)
void *context
bool started

secure_context.h

Caller-owned Secure context leases for a trusted NS kernel.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Defines

NX_FREERTOS_SECURE_MIN_STACK_BYTES

Minimum context capacity excludes the eight-byte ARM stack seal.

Enums

enum nx_freertos_secure_fault_t

Secure-context integrity failures, distinct from normal rejection.

Values:

enumerator NX_FREERTOS_SECURE_SEAL_FAILURE
enumerator NX_FREERTOS_SECURE_STACK_FAILURE

Functions

nx_result_t nx_freertos_secure_context_prepare(nx_freertos_secure_context_t *context, void *stack, size_t bytes, void *task)

Prepare exact Secure storage for one trusted task identity.

Note

Secure privileged Thread startup/exclusive lifecycle owner. Both memory spans must be Secure, writable and disjoint. No NS task may run against this identity during prepare. Repeat prepare is rejected; epochs are never reset. No allocation, kernel operation or runtime registry is used.

Parameters:

  • context – [out] Zero-initialized caller-owned Secure metadata.

  • stack – [in] Eight-byte-aligned Secure writable stack allocation.

  • bytes – [in] Whole allocation, including eight-byte upper seal.

  • task – [in] Opaque NS task identity, never dereferenced here.

Returns:

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

nx_result_t nx_freertos_secure_context_rebind(nx_freertos_secure_context_t *context, void *task)

Rebind retired metadata while preserving its epoch history.

Note

Secure lifecycle owner only after joining the previous task and stopping every observer. Existing stack is reused; stale handles remain invalid after the next allocation.

Parameters:

  • context – [inout] Prepared, unleased and unloaded Secure metadata.

  • task – [in] New trusted NS task identity.

Returns:

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

nx_freertos_secure_context_t *nx_freertos_secure_context_for_task(void *task)

Resolve a trusted, statically composed Secure task record.

Note

Secure application overrides the weak NULL default with an immutable mapping. Called with both PRIMASK states held; never dereference an NS-provided metadata pointer, allocate, block, discover objects, call a kernel or mutate mappings. The NS kernel and its SVC/PendSV are trusted: this mechanism does not authenticate an adversarial NS privileged kernel. NS Thread calls cannot spoof Handler origin.

Parameters:

  • task – [in] Opaque identity supplied by the trusted NS kernel.

Returns:

Prepared caller-owned metadata, or NULL when unauthorized.

void nx_freertos_secure_fault(nx_freertos_secure_fault_t fault)

Fail stop after a loaded Secure stack integrity failure.

Note

Secure application may override to record/reset safely. Called with both masks held; must not return, block, call a kernel or release retained storage. Default holds masks and spins. No transport or product recovery policy is imposed.

Parameters:

  • fault – [in] Seal or stack invariant violation.

struct nx_freertos_secure_context_t
#include <secure_context.h>

Explicit Secure metadata, never stored in Nonsecure RAM.

Note

Zero-initialize before prepare. Fields are mechanism-owned while prepared; applications cannot modify them. Metadata and stack remain alive until the task is joined, lease freed and no loaded context remains. Runtime Secure stack capacity is an application budget, not this port minimum.

Public Members

uint8_t *stack
size_t stack_bytes
void *task
uint8_t *saved_sp
uint8_t *limit
uint8_t *top
uint32_t epoch
bool prepared
bool leased

threadx.h

Caller-owned ThreadX task, wait and byte queue services.

Author

Nexus Team

Note

Privileged, single-core, current-security-domain APIs. All controls start zeroed and remain adapter-owned while live. One external lifecycle owner serializes init/destroy and joins; publishers, queue callers and IRQ sources must quiesce before reclaiming storage. Runtime task operations require unmasked Thread mode and a running kernel. Actual bootstrap permits object init, task create/discard and wake; it does not permit blocking waits or queue operations. A manual mask, ISR or unsupported context returns CONTEXT before mutation. The byte queue’s task threshold guard rejects foreign priority-zero time-sliced callers. Caller controls, stack ranges, full borrowed name/context objects, queue payloads, item buffers and waiters must be disjoint. Cold admission rejects known control/stack/payload overlap and name/context starting inside control or stack; unknown opaque extents remain the caller’s responsibility. Never operate a closable queue through its raw inner queue. All deadlines use nx_time_now_us; NX_DEADLINE_NEVER is an actual unbounded kernel wait. Timeout never revokes any accepted I/O borrow. MPU/TZ isolation, tickless sleep and additional Cortex-M ports are outside this backend scope.

Typedefs

typedef struct nx_threadx_queue_waiter nx_threadx_queue_waiter_t

One explicit caller latch per simultaneous close-aware operation.

Functions

nx_result_t nx_threadx_kernel_enter(void (*startup)(void*), void *context)

Explicit irreversible kernel entry owned by the product.

Note

Privileged cold Thread/MSP, no live FP context or masks. Startup may create and discard unused static objects. After startup returns, the bootstrap scope is sealed. Only the trusted kernel may call adapter tx_application_define; it validates canonical privileged Thread context before the product callback. This is not a security isolation API. An unexpected kernel return invokes fail-stop and retains all effects; it never reopens bootstrap reclamation.

Parameters:

  • startup – [in] Product initialization inside tx_application_define

  • context – [in] Borrowed through startup and kernel lifetime

Returns:

CONTEXT or INVALID before entry; successful entry never returns

void nx_threadx_fail_stop(nx_result_t reason)

Product failure hook; default parks forever.

Note

Actual fault context is not repaired or normalized; it may be masked, ISR or unprivileged. Do not assume a working kernel, clock, stack or permission to access a peripheral. The adapter observes the Core fault hook before this hook. Product owns separately reviewed safe output/reset actions. Returning does not authorize cleanup; the adapter parks.

Parameters:

  • reason – [in] Context, permanent-entry or kernel-return failure

nx_result_t nx_threadx_external_tick_setup(uint32_t tick_hz)

Mandatory product hook only for explicit external Tick.

Note

Actual kernel bootstrap, privileged PRIMASK masked. Provider owns timer clock and IRQ ceiling; it must not change the platform’s continuous monotonic clock. Missing hook fails linking. Failure enters retaining fail-stop.

Parameters:

  • tick_hz – [in] Exact immutable resolved kernel frequency

Returns:

SUCCESS after binding a real bounded periodic IRQ source

bool nx_threadx_isr_allowed(void)

Read-only configurable-IRQ and selected mask-policy gate.

Note

Native has no hardware IRQ source and returns false.

Returns:

True only in a privileged unmasked reviewed external IRQ

nx_result_t nx_threadx_notify_init(nx_threadx_notify_t *notification)

Initialize one binary latch in task or actual bootstrap.

Parameters:

  • notification – [inout] Zeroed caller control retained until destroy

Returns:

SUCCESS, INVALID, CONTEXT or IO

nx_wait_port_t nx_threadx_notify_port(nx_threadx_notify_t *notification)

Bind a sequence hint and one concurrent blocking waiter.

Note

Binding/arm are reads. Wake supports task/bootstrap or an IRQ admitted by nx_threadx_isr_allowed. Wait is task-only; finite deadline expiration precedes a changed sequence.

Parameters:

  • notification – [inout] Live latch retained through every port user

Returns:

Wait face; empty face for null or non-live control

nx_result_t nx_threadx_notify_destroy(nx_threadx_notify_t *notification)

Destroy only after all publishers and waiter quiesce.

Parameters:

  • notification – [inout] Live caller latch

Returns:

SUCCESS, INVALID, CONTEXT, BUSY or IO; failure retains it

nx_result_t nx_threadx_task_start(nx_threadx_task_t *task, const char *name, void *stack, size_t stack_bytes, UINT priority, void (*entry)(void*), void *context)

Create a cooperatively returning task using exact storage.

Note

No adapter heap or worker. Name is borrowed, not copied. Linux uses its own pthread stack; the caller buffer only validates kernel metadata and is not a host stack budget. Higher-priority entries may run before start returns.

Parameters:

  • task – [inout] Zeroed caller TCB/control, retained until join/discard

  • name – [in] Borrowed immutable name, retained until reclamation

  • stack – [in] Eight-byte aligned caller storage

  • stack_bytes – [in] Actual capacity, at least TX_MINIMUM_STACK

  • priority – [in] ThreadX priority; smaller values run first

  • entry – [in] Returns only after application stop/drain

  • context – [in] Borrowed until successful join/discard

Returns:

SUCCESS, INVALID, CONTEXT or IO; partial failure retains live control if reclamation cannot be established

nx_result_t nx_threadx_task_join(nx_threadx_task_t *task, nx_time_us_t deadline)

Join a cooperatively returned task and prove detachment.

Note

Self-join is rejected. Timeout retains task, borrowed name, stack and context. Completion hint alone never reclaims; successful real kernel deletion establishes detachment.

Parameters:

  • task – [inout] Live caller task, one external joiner only

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

Returns:

SUCCESS, INVALID, CONTEXT, TIMEOUT or IO

nx_result_t nx_threadx_task_discard_before_scheduler(nx_threadx_task_t *task)

Discard an unused task only inside actual bootstrap.

Note

This is prestart rollback, never runtime cancellation.

Parameters:

  • task – [inout] Live task whose entry has never begun

Returns:

SUCCESS, INVALID, CONTEXT or IO; failure retains storage

nx_result_t nx_threadx_permanent_task_start(nx_threadx_permanent_task_t *task, const char *name, void *stack, size_t stack_bytes, UINT priority, void (*entry)(void*), void *context)

Start a permanent task without a completion latch.

Note

Eight-byte stack alignment; failure can retain live state.

Parameters:

  • task – [inout] Zeroed caller control, retained until reset

  • name – [in] Borrowed immutable name, retained until reset

  • stack – [in] Aligned caller buffer, retained until reset

  • stack_bytes – [in] Actual capacity, at least TX_MINIMUM_STACK

  • priority – [in] Smaller ThreadX priority values run first

  • entry – [in] Never returns; return invokes retaining fail-stop

  • context – [in] Borrowed until reset

Returns:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_queue_init(nx_threadx_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size)

Initialize an exact arbitrary-byte bounded queue.

Parameters:

  • queue – [inout] Zeroed caller control retained until destroy

  • storage – [in] Caller payload storage retained until destroy

  • storage_bytes – [in] Exact depth multiplied by item_size

  • depth – [in] Positive bounded capacity, below TX_WAIT_FOREVER

  • item_size – [in] Positive byte count, without word-size narrowing

Returns:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_queue_send_until(nx_threadx_queue_t *queue, const void *item, nx_time_us_t deadline)

Task-only send; immediate readiness wins over expiration.

Parameters:

  • queue – [inout] Live queue retained throughout the operation

  • item – [in] Exactly item_size readable bytes borrowed until return

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

Returns:

SUCCESS, INVALID, CONTEXT, TIMEOUT, OVERFLOW or IO

nx_result_t nx_threadx_queue_receive_until(nx_threadx_queue_t *queue, void *item, nx_time_us_t deadline)

Task-only receive; output changes only on SUCCESS.

Parameters:

  • queue – [inout] Live queue retained throughout the operation

  • item – [out] Exactly item_size writable bytes borrowed until return

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

Returns:

SUCCESS, INVALID, CONTEXT, TIMEOUT, OVERFLOW or IO

nx_result_t nx_threadx_queue_destroy(nx_threadx_queue_t *queue)

Destroy a drained queue after every caller quiesces.

Parameters:

  • queue – [inout] Live caller control and storage

Returns:

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

nx_result_t nx_threadx_queue_waiter_init(nx_threadx_queue_waiter_t *waiter)

Initialize one explicit close-aware operation latch.

Parameters:

  • waiter – [inout] Zeroed caller storage retained until waiter destroy

Returns:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_queue_waiter_destroy(nx_threadx_queue_waiter_t *waiter)

Destroy inactive waiter after its operation has returned.

Parameters:

  • waiter – [inout] Live caller latch with no concurrent users

Returns:

SUCCESS, INVALID, CONTEXT, BUSY or IO

nx_result_t nx_threadx_closable_queue_init(nx_threadx_closable_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size, size_t maximum_waiters)

Add explicit bounded close broadcast to a byte queue.

Note

Payload size and maximum_waiters bound task scheduling pause; the entire copy/broadcast does not mask interrupts.

Parameters:

  • queue – [inout] Zeroed caller control retained until destroy

  • storage – [in] Caller payload storage retained until destroy

  • storage_bytes – [in] Exact depth multiplied by item_size

  • depth – [in] Positive capacity below TX_WAIT_FOREVER

  • item_size – [in] Positive exact payload byte count

  • maximum_waiters – [in] Positive maximum simultaneous operations

Returns:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_closable_queue_close(nx_threadx_closable_queue_t *queue)

Reject sends, wake registered waiters, retain queued items.

Parameters:

  • queue – [inout] Live close-aware queue

Returns:

SUCCESS, INVALID or CONTEXT; close is idempotent

nx_result_t nx_threadx_closable_queue_send_until(nx_threadx_closable_queue_t *queue, const void *item, nx_time_us_t deadline, nx_threadx_queue_waiter_t *waiter)

Send with immediate close wake and explicit admission.

Note

A closed queue rejects sends without changing payload.

Parameters:

  • queue – [inout] Live queue retained throughout the operation

  • item – [in] Exactly item_size readable bytes borrowed until return

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

  • waiter – [inout] Live exclusive latch for this simultaneous call

Returns:

SUCCESS, CANCELLED, TIMEOUT, BUSY, INVALID, CONTEXT or IO

nx_result_t nx_threadx_closable_queue_receive_until(nx_threadx_closable_queue_t *queue, void *item, nx_time_us_t deadline, nx_threadx_queue_waiter_t *waiter)

Receive and drain previously queued items after close.

Note

Closed and empty returns CANCELLED; failure leaves output.

Parameters:

  • queue – [inout] Live queue retained throughout the operation

  • item – [out] Exactly item_size writable bytes borrowed until return

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

  • waiter – [inout] Live exclusive latch for this simultaneous call

Returns:

SUCCESS, CANCELLED, TIMEOUT, BUSY, INVALID, CONTEXT or IO

nx_result_t nx_threadx_closable_queue_destroy(nx_threadx_closable_queue_t *queue)

Destroy only a closed, drained and quiesced queue.

Parameters:

  • queue – [inout] Live control and its borrowed payload storage

Returns:

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

struct nx_threadx_notify_t
#include <threadx.h>

One binary latch; publishers quiesce before destruction.

Public Members

TX_SEMAPHORE control
uint32_t sequence
uint32_t waiting
bool live
struct nx_threadx_task_t
#include <threadx.h>

Returning task retains all storage until external successful join.

Public Members

TX_THREAD control
TX_SEMAPHORE finished
void (*entry)(void*)
void *context
uint32_t entered
uint32_t returned
bool live
struct nx_threadx_permanent_task_t
#include <threadx.h>

Permanent task has no completion latch, join or destroy.

Public Members

TX_THREAD control
void (*entry)(void*)
void *context
bool live
struct nx_threadx_queue_t
#include <threadx.h>

Exact arbitrary byte items; no native word-size narrowing.

Public Members

TX_SEMAPHORE readable
TX_SEMAPHORE writable
uint8_t *storage
size_t depth
size_t item_size
size_t head
size_t tail
size_t count
uint32_t users
bool live
struct nx_threadx_queue_waiter
#include <threadx.h>

One explicit caller latch per simultaneous close-aware operation.

Public Members

nx_threadx_notify_t notification
struct nx_threadx_queue_waiter *next
uint32_t active
struct nx_threadx_closable_queue_t
#include <threadx.h>

Optional bounded close broadcast; registry is task-only.

Public Members

nx_threadx_queue_t queue
nx_threadx_queue_waiter_t *send_waiters
nx_threadx_queue_waiter_t *receive_waiters
size_t maximum_waiters
bool closed

tick.h

Explicit external Tick and diagnostic counter contracts.

Author

Nexus Team

Note

Applications implement these symbols only when the authored OS policy enables them. No weak timer/counter fallback is supplied. The platform never invents timer wiring.

Functions

void nx_freertos_external_tick_setup(uint32_t tick_hz)

Configure the application’s selected kernel Tick source.

Note

Scheduler startup calls this in its canonical masked, privileged context. Configure a periodic interrupt, clear pending state and route it to the selected kernel Tick handler at its validated priority. Do not start tasks here. Hardware clock and routing remain application/SoC-owned.

Parameters:

  • tick_hz – [in] Exact authored Tick frequency in hertz

void nx_freertos_runtime_counter_start(void)

Start the explicitly selected diagnostic counter.

Note

Called during scheduler startup. Counter initialization must be bounded, allocation-free and safe in the startup mask.

uint32_t nx_freertos_runtime_counter_now(void)

Read the diagnostic counter without blocking.

Note

Called by the kernel during context switches. It must be bounded, allocation-free and safe in interrupt/critical context. Configure a frequency above Tick frequency and account for wrapping when interpreting recorded totals.

Returns:

Monotonic modulo-32-bit counter in application-defined units

wait.h

Optional sequence-latched waiting without hidden workers.

Author

Nexus Team

Functions

nx_result_t nx_wait_until(const nx_wait_port_t *port, bool (*ready)(void*), void *context, uint64_t deadline_us)

Wait for an authoritative caller predicate.

Note

Task context. No service, queue, callback dispatch or task creation is implicit. A shared-bus client must not use ready to service the controller; its execution owner must remain running during stop/drain.

Parameters:

  • port – [in] Live single-waiter notification port

  • ready – [in] Bounded predicate, called in caller context

  • context – [in] Predicate context, retained for this call only

  • deadline_us – [in] Absolute deadline in port’s clock domain, or NX_DEADLINE_NEVER; no wall-clock or relative values

Returns:

NX_SUCCESS when predicate is observed true, including a final observation after TIMEOUT; otherwise port error

struct nx_wait_port_t
#include <wait.h>

Single-waiter notification port.

Caller owns storage and serializes arm/wait. Multiple wake publishers are permitted by each backend’s documented context. Sequence is a hint; the predicate/request is authoritative. There must be fewer than 2^32 wakes between arm and recheck. All deadlines are absolute monotonic microseconds in the backend’s clock domain, with NX_DEADLINE_NEVER explicitly disabling timeout. Clocks must continue while waiting and never change domain; construct relative budgets with nx_deadline_after to avoid overflow. A timeout does not settle a request or release its buffers. Before destroy, stop and join every publisher and waiter; SETTLED alone does not prove notification storage is reclaimable. arm snapshots the sequence. wait must atomically observe a changed sequence or a latched wake, including a wake between the caller’s recheck and sleeping. A changed sequence cannot bypass a finite deadline: wait checks expiry on every call and every return from blocking before reporting a hint. A nonblocking backend may return BUSY while unexpired. Only one owner may arm/wait; a second concurrent wait is outside the port contract even when a backend rejects it.

Public Members

void *context
uint32_t (*arm)(void *context)
nx_result_t (*wait)(void *context, uint32_t sequence, uint64_t deadline_us)
nx_result_t (*wake)(void *context)