Core: requests, status and time

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

fault.h

Bounded observation before retaining platform fail-stop.

Author

Nexus Team

Enums

enum nx_fault_domain_t

Fault origin, without any product safety or recovery decision.

Values:

enumerator NX_FAULT_FREERTOS_ASSERT
enumerator NX_FAULT_FREERTOS_STACK
enumerator NX_FAULT_THREADX_ADAPTER
enumerator NX_FAULT_PLATFORM

Functions

void nx_fault_observe(nx_fault_domain_t domain, nx_result_t reason, const char *file, unsigned line)

Observe a terminal fault before the caller retains effects.

Note

The weak default returns and has no state or side effects. A product may supply one strong implementation, bounded and allocation-free in every calling task/ISR/masked context. No functioning kernel, clock, stack, transport or peripheral may be assumed after corruption. This is best-effort observation, not stack repair, safe outputs or reset proof. The hook must not acquire OS locks, reenter the provider, change incoming masks, mutate accepted requests or release retained storage. If it returns, the terminal caller still parks. A product may perform a separately reviewed non-returning recovery action. No retained event, registry or worker is implicit.

Parameters:

  • domain – [in] Actual reporting path, not a severity assessment.

  • reason – [in] Observed failure, never permission to reclaim loans.

  • file – [in] Static source literal or NULL; do not retain or read untrusted dynamic memory. No task name is dereferenced.

  • line – [in] Diagnostic location, zero when unavailable.

memory.h

Variable-only placement in explicitly selected data regions.

Author

Nexus Team

Defines

NX_CORE_MEMORY_STRING_DETAIL(value)

Place static storage in an authored optional memory region.

Note

Use these attributes on variable definitions, before the type, one variable per declaration. They are not function or instruction attributes. Each use has an independent input section for garbage collection of unused storage. DATA copies its initializer from Flash at reset. BSS is zeroed at reset. NOINIT is neither copied nor cleared; initialize it before reading. Power-loss retention is not promised. BSS/NOINIT reject nonzero initializers. Storage is word aligned and subject to explicit ELF budgets. Unselected use is a compile error. TCM is CPU-only data: never DMA or executable storage. CCM is also CPU-only data; placement never grants bus-master access. ADDSRAM DMA requires provider address, alignment and ownership validation. Ordinary storage, the main MSP and unselected images keep their existing layout.

NX_CORE_MEMORY_STRING(value)
NX_CORE_MEMORY_ATTRIBUTE(name)
NX_MEMORY_ADDSRAM_DATA
NX_MEMORY_ADDSRAM_BSS
NX_MEMORY_ADDSRAM_NOINIT
NX_MEMORY_TCM_DATA
NX_MEMORY_TCM_BSS
NX_MEMORY_TCM_NOINIT
NX_MEMORY_CCM_DATA
NX_MEMORY_CCM_BSS
NX_MEMORY_CCM_NOINIT

request.h

Caller-owned admission, borrow, settlement and stable cancellation.

Author

Nexus Team

Enums

enum nx_request_state_t

Request state; only READY and SETTLED have no provider borrow.

Values:

enumerator NX_REQUEST_READY
enumerator NX_REQUEST_QUEUED
enumerator NX_REQUEST_ACTIVE
enumerator NX_REQUEST_DRAINING
enumerator NX_REQUEST_SETTLED
enumerator NX_REQUEST_QUARANTINED

Functions

void nx_request_initialize(nx_request_t *request)

Initialize fresh unborrowed request storage.

Note

Task-only. Never use initialization to revoke a live borrow.

Parameters:

  • request – [out] Fresh storage, not visible to a provider/observer.

nx_result_t nx_request_prepare(nx_request_t *request, nx_time_us_t deadline)

Prepare a READY or consumed SETTLED request.

Note

Single owner, task-only; failure creates no borrow.

Parameters:

  • request – [inout] Storage with no remaining observers or adapter loans.

  • deadline – [in] Absolute transfer deadline, including queue time.

Returns:

NX_SUCCESS; invalid pointer or borrowed state is rejected.

nx_request_state_t nx_request_state(const nx_request_t *request)

Read request state with acquire ordering.

Note

Task/IRQ bounded; SETTLED guarantees provider’s final access has occurred, not that separate adapter observers exited.

Parameters:

  • request – [in] Initialized storage kept alive by the caller.

Returns:

Current state, or QUARANTINED for NULL.

nx_result_t nx_request_admit(nx_request_t *request, nx_request_state_t state)

Establish the chain’s unique admission and provider borrow.

Note

One serialized execution owner; validate hardware/buffers first. Multi-producer adapters hold their metadata guard across admission; concurrent admissions are unsupported.

Parameters:

  • request – [inout] READY request; caller owns storage until SETTLED.

  • state – [in] QUEUED for adapter or ACTIVE for direct provider.

Returns:

NX_SUCCESS means ACCEPTED. Any failure means REJECTED with zero retained references, payload access or residual effects.

nx_result_t nx_request_transition(nx_request_t *request, nx_request_state_t state)

Advance an already admitted request without readmission.

Note

Execution owner; short task/IRQ metadata operation.

Parameters:

  • request – [inout] Admitted request owned by the executor.

  • state – [in] ACTIVE, DRAINING or QUARANTINED.

Returns:

NX_SUCCESS or NX_ERROR_STATE for an illegal transition.

void nx_request_settle(nx_request_t *request, nx_result_t result, size_t transferred)

Release-publish SETTLED as the final provider access.

Note

Detach active/queued references and capture any static wake target first. No hardware/IRQ/deferred observer may access request or payload afterwards. Cancel/timeout alone do not satisfy this requirement. A failed drain stays QUARANTINED.

Parameters:

  • request – [inout] Borrowed storage after all sources have drained.

  • result – [in] Final transfer result, not admission status.

  • transferred – [in] Valid transferred bytes/samples.

nx_result_t nx_request_result(const nx_request_t *request, nx_result_t *result, size_t *transferred)

Copy the unique settled result after acquire publication.

Parameters:

  • request – [in] Live request storage with no concurrent reuse.

  • result – [out] Final operation result.

  • transferred – [out] Valid byte/sample count.

Returns:

NX_SUCCESS, NX_ERROR_BUSY while borrowed or invalid arguments.

nx_result_t nx_request_slot_bind(nx_request_slot_t *slot, nx_request_t *request, uint64_t *epoch)

Bind a stable slot to a new request incarnation.

Parameters:

  • slot – [inout] Zero-initialized, unbound adapter-owned slot.

  • request – [in] Live storage to bind; binding itself is not admission.

  • epoch – [out] Nonzero identity for later control commands.

Returns:

NX_SUCCESS, BUSY, INVALID or EXHAUSTED; no identity repeats.

nx_request_t *nx_request_slot_lookup(const nx_request_slot_t *slot, uint64_t expected_epoch)

Resolve cancellation using stable storage before dereference.

Parameters:

  • slot – [in] Stable slot protected by adapter synchronization.

  • expected_epoch – [in] Incarnation named by the command.

Returns:

Live request only for a matching bound incarnation; else NULL.

nx_result_t nx_request_slot_release(nx_request_slot_t *slot, uint64_t expected_epoch)

Drop a slot reference only after settlement and control drain.

Parameters:

  • slot – [inout] Stable slot whose commands/observers have exited.

  • expected_epoch – [in] Incarnation to release.

Returns:

NX_SUCCESS, STATE for stale identity, BUSY while borrowed.

struct nx_request_t
#include <request.h>

Caller-owned request metadata, without payload or callbacks.

Note

Fields are private to helpers/providers while borrowed. Initialize before first use. One owner prepares/submits and consumes results. GCC/Clang lock-free 32-bit atomic access publishes state; fields are read only after acquire SETTLED.

Public Members

uint32_t state
nx_result_t result
size_t transferred
nx_time_us_t deadline
struct nx_request_slot_t
#include <request.h>

Adapter-owned stable cancellation identity.

Note

The slot, not a possibly freed request, is targeted by cross- task commands. Serialize bind/lookup/release in the adapter. Keep slot and command storage until command acknowledgement; epoch exhaustion rejects rebinding rather than reusing IDs.

Public Members

nx_request_t *request
uint64_t epoch

request_observer.h

Optional stable-identity request observation without locks.

Author

Nexus Team

Functions

nx_result_t nx_request_observer_bind(nx_request_observer_t *observer, const nx_request_slot_t *slot, uint64_t epoch)

Bind the exact live incarnation without storing its pointer.

Parameters:

  • observer – [inout] Fresh zero/detached sidecar, distinct control.

  • slot – [in] Stable caller slot, protected by caller exclusion.

  • epoch – [in] Nonzero exact slot incarnation, never regenerated.

Returns:

SUCCESS or INVALID/STATE, no retained reference on rejection.

nx_result_t nx_request_observer_sample(nx_request_observer_t *observer, nx_time_us_t now, nx_request_observation_t *out)

Copy state and acquire-observed final result for exact epoch.

Note

Borrowed state exposes no speculative result/count. NULL slot, stale epoch and overlap reject before request access. This neither services hardware nor interprets deadline as borrow release. Caller guarantees binding storage lifetime. Output is disjoint from the complete descriptor and borrowed buffers; only the common request span is checked here.

Parameters:

  • observer – [inout] Bound sidecar under caller serialization.

  • now – [in] Same monotonic domain as the request deadline.

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

Returns:

SUCCESS, STATE for stale/released identity, INVALID or IO for reversed time; counters saturate without epoch reuse.

void nx_request_observer_detach(nx_request_observer_t *observer)

Remove only this sidecar reference, leaving loans untouched.

Note

Caller-serialized; allowed while request is quarantined. It is not request settlement, slot release or destruction.

Parameters:

  • observer – [inout] Live sidecar after all its readers have exited.

struct nx_request_observation_t
#include <request_observer.h>

Copied facts; result/count are valid only when settled is true.

Public Members

uint64_t epoch
nx_time_us_t observed_at
nx_time_us_t deadline
nx_request_state_t state
nx_result_t result
size_t transferred
bool settled
struct nx_request_observer_t
#include <request_observer.h>

Caller-owned optional sidecar, fresh zero storage before bind.

Note

One serialized observer; no Arch/OS/SoC dependency or lock. Caller excludes slot bind/release, request prepare/reuse and concurrent observer calls during sample. Stable slot stays alive until detach; observing never acquires/releases a loan.

Public Members

const nx_request_slot_t *slot
uint64_t epoch
nx_time_us_t last_observed
nx_time_us_t max_gap
uint32_t samples
uint32_t transitions
uint32_t clock_errors
nx_request_state_t last_state
bool observed

stack_observation.h

Bounded read-only observation of caller-painted stack spans.

Author

Nexus Team

Functions

nx_result_t nx_stack_observe(const void *base, size_t bytes, uint8_t paint, nx_stack_observation_t *out)

Read a bounded low-address paint prefix without mutation.

Note

Caller ensures this region is quiescent and painting had no live frames. No Arch/OS dependency or internal mask occurs. Work is at most bytes reads. Unwritten reservations or writes equal to paint can hide usage; this is not overflow detection. MSP qualification needs independently established boot paint and a quiescent sampling point. The span excludes current SP, all active frames and exception-stack reservation. It never paints or claims to read the physical MSP register.

Parameters:

  • base – [in] Live downward-growing stack region, caller-provenance.

  • bytes – [in] Original positive painted region capacity in bytes.

  • paint – [in] Exact fill used before the region became active.

  • out – [out] Distinct output, unchanged on invalid span or alias.

Returns:

SUCCESS or INVALID, without allocation or retained pointers.

struct nx_stack_observation_t
#include <stack_observation.h>

Byte-prefix paint observations, not an exact physical stack peak.

Public Members

size_t capacity_bytes
size_t untouched_bytes
size_t touched_bytes

status.h

Small vendor-independent result vocabulary.

Author

Nexus Team

Enums

enum nx_result_t

Operation result; success at submission means admission only.

Values:

enumerator NX_SUCCESS
enumerator NX_ERROR_INVALID
enumerator NX_ERROR_BUSY
enumerator NX_ERROR_STATE
enumerator NX_ERROR_TIMEOUT
enumerator NX_ERROR_CANCELLED
enumerator NX_ERROR_IO
enumerator NX_ERROR_UNSUPPORTED
enumerator NX_ERROR_OVERFLOW
enumerator NX_ERROR_EMPTY
enumerator NX_ERROR_PERMISSION
enumerator NX_ERROR_NACK
enumerator NX_ERROR_ARBITRATION
enumerator NX_ERROR_EXHAUSTED
enumerator NX_ERROR_CONTEXT

time.h

Absolute monotonic microsecond deadlines and wrap extension.

Author

Nexus Team

Defines

NX_DEADLINE_NEVER

Typedefs

typedef uint64_t nx_time_us_t

Microseconds in one boot/clock domain; no wall-clock semantics.

Functions

nx_time_us_t nx_time_now_us(void)

Read the selected provider’s monotonic clock.

Note

Physical providers require successful platform startup and a privileged task/configurable IRQ; NMI/HardFault callers are unsupported. No OS, allocation or wait. Physical clocks return zero outside a successfully started live epoch; zero alone cannot prove readiness. Startup status is authoritative. All consumers join before clock withdrawal. Stop/restart or a clock change invalidates every old deadline, even if a new epoch has the same numerical value. UINT64_MAX is reserved; clock exhaustion requires controlled restart. An observed hardware overflow acknowledgement failure ends the live epoch and is terminal, even when finite source isolation succeeds. The provider retains ownership, masks interrupts, calls nx_fault_observe and parks if the observer returns. It never resumes deadline consumers with invalid zero time. Observation neither releases loans nor proves safe outputs; products own separately reviewed non-returning recovery. Ordinary shutdown still requires every consumer and optional low-power owner joined first.

Returns:

Microseconds since domain initialization.

bool nx_deadline_expired(nx_time_us_t deadline, nx_time_us_t now)

Test an absolute deadline against a clock snapshot.

Parameters:

  • deadline – [in] Absolute time or NX_DEADLINE_NEVER.

  • now – [in] Snapshot in the same clock domain.

Returns:

True when a finite deadline has expired, including equality.

nx_time_us_t nx_deadline_after(nx_time_us_t now, uint64_t duration_us)

Add a duration without wrapping the monotonic domain.

Parameters:

  • now – [in] Current finite time.

  • duration_us – [in] Relative duration in microseconds.

Returns:

Absolute deadline, saturating at NX_DEADLINE_NEVER.

nx_result_t nx_clock32_initialize(nx_clock32_t *clock, uint32_t counter, uint32_t frequency_hz)

Initialize counter extension and its clock domain.

Note

Single execution owner. Reset creates a new clock domain; do not reuse outstanding deadlines after reset/clock change.

Parameters:

  • clock – [out] Caller-owned extension state.

  • counter – [in] First hardware snapshot.

  • frequency_hz – [in] Nonzero stable counter frequency.

Returns:

NX_SUCCESS, or NX_ERROR_INVALID for invalid arguments.

nx_result_t nx_clock32_observe(nx_clock32_t *clock, uint32_t counter, nx_time_us_t *time_us)

Extend a wrapping counter and convert to microseconds.

Note

Observe at least once per 2^32 ticks, even when idle. Multiple missed wraps cannot be detected from two snapshots. Counter must continue through waits; frequency cannot change.

Parameters:

  • clock – [inout] Initialized, single-owner extension state.

  • counter – [in] Current counter snapshot.

  • time_us – [out] Extended elapsed microseconds.

Returns:

NX_SUCCESS, NX_ERROR_STATE or NX_ERROR_EXHAUSTED.

struct nx_clock_t
#include <time.h>

An explicitly injected clock; its context outlives all borrowers.

Public Members

nx_time_us_t (*read)(void *context)
void *context
struct nx_clock32_t
#include <time.h>

State for extending one 32-bit free-running hardware counter.

Public Members

uint64_t ticks
uint32_t previous
uint32_t frequency_hz
bool initialized