Core：请求、状态与时间

这些声明来自公共头文件。选择、生命周期、支持的执行模式和物理资源授权范围仍以对应设计及支持记录为准。

fault.h

在平台保持故障停止之前执行有界观察。

作者 Nexus Team

枚举

enum nx_fault_domain_t

故障来源，不包含任何产品安全或恢复决策。

取值：

enumerator NX_FAULT_FREERTOS_ASSERT
enumerator NX_FAULT_FREERTOS_STACK
enumerator NX_FAULT_THREADX_ADAPTER
enumerator NX_FAULT_PLATFORM

函数

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

在调用者保留效果之前观察终止故障。

备注

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.

参数:

  • 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

仅将变量放入显式选定的数据区域。

作者 Nexus Team

宏定义

NX_CORE_MEMORY_STRING_DETAIL(value)

将静态存储放入配置声明的可选内存区域。

备注

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

调用者拥有的准入、借用、结清与稳定取消机制。

作者 Nexus Team

枚举

enum nx_request_state_t

请求状态；只有 READY 和 SETTLED 不存在提供者借用。

取值：

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

函数

void nx_request_initialize(nx_request_t *request)

初始化全新且未被借用的请求存储。

备注

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

参数:

  • 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)

准备处于 READY 或结果已消费的 SETTLED 请求。

备注

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

参数:

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

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

返回:

NX_SUCCESS; invalid pointer or borrowed state is rejected.

nx_request_state_t nx_request_state(const nx_request_t *request)

以 acquire 顺序读取请求状态。

备注

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

参数:

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

返回:

Current state, or QUARANTINED for NULL.

nx_result_t nx_request_admit(nx_request_t *request, nx_request_state_t state)

建立请求链唯一的准入判定和提供者借用。

备注

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

参数:

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

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

返回:

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)

推进已准入的请求，不重复准入。

备注

Execution owner; short task/IRQ metadata operation.

参数:

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

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

返回:

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 顺序发布 SETTLED。

备注

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.

参数:

  • 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)

在 acquire 观察发布之后，复制唯一的最终结果。

参数:

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

  • result – [out] Final operation result.

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

返回:

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)

将稳定槽绑定到新的请求实例世代。

参数:

  • 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.

返回:

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)

在解引用之前，通过稳定存储解析取消请求。

参数:

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

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

返回:

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)

仅在请求结清且控制引用排空之后撤销槽引用。

参数:

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

  • expected_epoch – [in] Incarnation to release.

返回:

NX_SUCCESS, STATE for stale identity, BUSY while borrowed.

struct nx_request_t
#include <request.h>

调用者拥有的请求元数据，不含载荷或回调。

备注

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.

公共成员

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

适配器拥有的稳定取消身份。

备注

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.

公共成员

nx_request_t *request
uint64_t epoch

request_observer.h

可选、无锁、基于稳定身份的请求观察。

作者 Nexus Team

函数

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

绑定准确且存活的实例世代，不存储其指针。

参数:

  • 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.

返回:

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)

复制准确 epoch 的状态，以及以 acquire 观察的最终结果。

备注

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.

参数:

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

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

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

返回:

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)

仅移除此附加观察引用，不改变借用。

备注

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

参数:

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

struct nx_request_observation_t
#include <request_observer.h>

已复制的事实；仅 settled 为 true 时 result/count 有效。

公共成员

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>

调用者拥有的可选附加状态，绑定之前必须使用全新清零存储。

备注

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.

公共成员

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

对调用者涂色的栈范围作有界只读观察。

作者 Nexus Team

函数

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

读取有界的低地址涂色前缀，不修改存储。

备注

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.

参数:

  • 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.

返回:

SUCCESS or INVALID, without allocation or retained pointers.

struct nx_stack_observation_t
#include <stack_observation.h>

字节前缀涂色观察，不是准确的物理栈峰值。

公共成员

size_t capacity_bytes
size_t untouched_bytes
size_t touched_bytes

status.h

精简且独立于厂商的结果集合。

作者 Nexus Team

枚举

enum nx_result_t

操作结果；提交时成功只表示已准入。

取值：

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

绝对单调微秒截止时间与回绕扩展。

作者 Nexus Team

宏定义

NX_DEADLINE_NEVER

类型定义

typedef uint64_t nx_time_us_t

同一启动／时钟域内的微秒数，不具有墙上时钟语义。

函数

nx_time_us_t nx_time_now_us(void)

读取选定提供者的单调时钟。

备注

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.

返回:

Microseconds since domain initialization.

bool nx_deadline_expired(nx_time_us_t deadline, nx_time_us_t now)

依据时钟快照检查绝对截止时间。

参数:

  • deadline – [in] Absolute time or NX_DEADLINE_NEVER.

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

返回:

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)

增加持续时间，不使单调时间域回绕。

参数:

  • now – [in] Current finite time.

  • duration_us – [in] Relative duration in microseconds.

返回:

Absolute deadline, saturating at NX_DEADLINE_NEVER.

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

初始化计数扩展及其时钟域。

备注

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

参数:

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

  • counter – [in] First hardware snapshot.

  • frequency_hz – [in] Nonzero stable counter frequency.

返回:

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)

扩展回绕计数器并换算为微秒。

备注

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.

参数:

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

  • counter – [in] Current counter snapshot.

  • time_us – [out] Extended elapsed microseconds.

返回:

NX_SUCCESS, NX_ERROR_STATE or NX_ERROR_EXHAUSTED.

struct nx_clock_t
#include <time.h>

显式注入的时钟；其上下文必须在所有借用者退出前保持有效。

公共成员

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

用于扩展一个 32 位自由运行硬件计数器的状态。

公共成员

uint64_t ticks
uint32_t previous
uint32_t frequency_hz
bool initialized