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)

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

备注

默认弱实现直接返回，不保存状态，也不产生副作用。产品可提供一个强实现，但在每种调用它的任务／ISR／已屏蔽上下文中都必须有界且不分配内存。发生损坏后，不得假定内核、时钟、栈、传输或外设仍正常。这里只提供尽力而为的观察，不修复栈，也不证明安全输出或复位。hook 不得取得 OS 锁、重入 provider、改变传入屏蔽、修改已接受的请求或释放保留的存储。若 hook 返回，终止路径的调用方仍将停驻。产品可执行另行审查且不返回的恢复操作。不隐式保留事件、注册表或 worker。

参数:

  • domain – [in] 实际报告路径，不表示严重程度评估。

  • reason – [in] 观察到的故障，绝不授予回收借用的权限。

  • file – [in] 静态源码字符串字面量或 NULL；不得保留或读取不可信动态内存。不解引用任务名。

  • line – [in] 诊断位置；不可用时为零。

memory.h

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

作者 Nexus Team

宏定义

NX_CORE_MEMORY_STRING_DETAIL(value)

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

备注

这些属性用于变量定义，置于类型之前，每个声明只定义一个变量；它们不是函数或指令属性。每次使用都有独立的输入 section，便于回收未使用存储。DATA 在复位时从 Flash 复制初始值；BSS 在复位时清零；NOINIT 既不复制也不清零，读取前必须初始化。不承诺掉电保持。BSS/NOINIT 拒绝非零初始值。存储按字对齐，并受显式 ELF 预算约束。未选入时使用会触发编译错误。TCM 仅用于 CPU 数据，绝不能用作 DMA 或可执行存储。CCM 同样仅用于 CPU 数据，放置在其中不授予总线主设备访问权限。ADDSRAM DMA 仍须由 provider 验证地址、对齐和所有权。普通存储、主 MSP 及未选入的镜像保留现有布局。U575 SRAM4 选择还会准备由复位流程拥有的 PWR/SRAM4/LPDMA 运行门控；自主运行及 DMA 借用接纳仍需各自的 provider。

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
NX_MEMORY_SRAM1_DATA
NX_MEMORY_SRAM1_BSS
NX_MEMORY_SRAM1_NOINIT
NX_MEMORY_SRAM4_DATA
NX_MEMORY_SRAM4_BSS
NX_MEMORY_SRAM4_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)

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

备注

仅限任务上下文。绝不能通过初始化撤销存续的借用。

参数:

  • request – [out] 全新存储，尚不对 provider／观察者可见。

nx_result_t nx_request_prepare(nx_request_t *request, nx_time_us_t deadline)

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

备注

唯一所有者，仅限任务上下文；失败不产生借用。

参数:

  • request – [inout] 不再有观察者或适配器借用的存储。

  • deadline – [in] 包含排队时间的绝对传输 deadline。

返回:

成功返回 NX_SUCCESS；拒绝无效指针或已借用状态。

nx_request_state_t nx_request_state(const nx_request_t *request)

以 acquire 顺序读取请求状态。

备注

任务／IRQ 中的有界操作；SETTLED 保证 provider 的最终访问已经发生，不保证独立的适配器观察者已经退出。

参数:

  • request – [in] 由调用者保持存续的已初始化存储。

返回:

当前状态；NULL 返回 QUARANTINED。

nx_result_t nx_request_admit(nx_request_t *request, nx_request_state_t state)

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

备注

只允许一个串行化的执行所有者；先验证硬件／缓冲区。多生产者适配器须在整个准入期间持有元数据保护；不支持并发准入。

参数:

  • request – [inout] READY 请求；调用者须保持存储，直到 SETTLED。

  • state – [in] 适配器使用 QUEUED；直接 provider 使用 ACTIVE。

返回:

NX_SUCCESS 表示 ACCEPTED。任何失败均表示 REJECTED，且不保留引用、不访问载荷，也不遗留效果。

nx_result_t nx_request_transition(nx_request_t *request, nx_request_state_t state)

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

备注

执行所有者调用；任务／IRQ 中的短元数据操作。

参数:

  • request – [inout] 已获准入、由执行器拥有的请求。

  • state – [in] ACTIVE、DRAINING 或 QUARANTINED。

返回:

成功返回 NX_SUCCESS；非法转换返回 NX_ERROR_STATE。

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

作为提供者最后一次访问，以 release 顺序发布 SETTLED。

备注

先撤离 active/queued 引用，并捕获所有静态唤醒目标。此后任何硬件／IRQ／延后观察者都不得再访问请求或载荷。仅取消／超时不能满足此条件。排空失败时继续保持 QUARANTINED。

参数:

  • request – [inout] 所有源均已排空后的借用存储。

  • result – [in] 最终传输结果，不是准入状态。

  • transferred – [in] 有效传输的字节／样本数。

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

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

参数:

  • request – [in] 存续的请求存储，且不得并发复用。

  • result – [out] 最终操作结果。

  • transferred – [out] 有效字节／样本数。

返回:

成功返回 NX_SUCCESS；仍在借用时返回 NX_ERROR_BUSY；参数无效时拒绝。

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

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

参数:

  • slot – [inout] 零初始化、尚未绑定且由适配器拥有的槽。

  • request – [in] 待绑定的存续存储；绑定本身不表示准入。

  • epoch – [out] 用于后续控制命令的非零身份标识。

返回:

返回 NX_SUCCESS、BUSY、INVALID 或 EXHAUSTED；身份标识绝不重复。

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

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

参数:

  • slot – [in] 由适配器同步保护的稳定槽。

  • expected_epoch – [in] 命令所指定的实例代次。

返回:

仅在已绑定的实例代次匹配时返回存续请求；否则返回 NULL。

nx_result_t nx_request_slot_release(nx_request_slot_t *slot, uint64_t expected_epoch)

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

参数:

  • slot – [inout] 相关命令／观察者均已退出的稳定槽。

  • expected_epoch – [in] 要释放的实例代次。

返回:

成功返回 NX_SUCCESS；身份标识过期返回 STATE；仍有借用返回 BUSY。

struct nx_request_t
#include <request.h>

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

备注

借用期间字段只由 helper/provider 私有访问。首次使用前先初始化。由同一所有者准备／提交并消费结果。通过 GCC/Clang 无锁的 32 位原子访问发布状态；只有以 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>

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

备注

跨任务命令针对槽，而不针对可能已释放的请求。在适配器中串行化 bind/lookup/release。保留槽与命令存储，直到命令获确认；epoch 耗尽时拒绝重新绑定，不复用 ID。

公共成员

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] 全新且已零初始化，或已撤离的 sidecar；控制存储须独立。

  • slot – [in] 由调用者互斥保护的稳定调用者槽。

  • epoch – [in] 非零且精确的槽实例代次，绝不重新生成。

返回:

返回 SUCCESS 或 INVALID/STATE；拒绝时不保留引用。

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

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

备注

借用状态不暴露推测的结果／计数。NULL 槽、过期 epoch 和重叠均在访问请求前拒绝。它既不推进硬件，也不把 deadline 解释为借用释放。调用者保证绑定存储的生命周期。输出须与完整描述符及已借用缓冲区不重叠；这里只检查公共 request 跨度。

参数:

  • observer – [inout] 由调用者串行化保护的已绑定 sidecar。

  • now – [in] 与请求 deadline 相同的单调时间域。

  • out – [out] 独立输出；错误时保持不变。

返回:

成功返回 SUCCESS；身份标识过期／已释放返回 STATE；参数无效返回 INVALID；时间倒退返回 IO；计数器饱和，不复用 epoch。

void nx_request_observer_detach(nx_request_observer_t *observer)

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

备注

由调用者串行化；请求处于 QUARANTINED 时也允许调用。它不表示请求结算、槽释放或销毁。

参数:

  • observer – [inout] 所有读取者均已退出后的存续 sidecar。

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>

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

备注

只允许一个串行化观察者；不依赖 Arch/OS/SoC，也不使用锁。采样期间调用者须排除槽 bind/release、请求 prepare/reuse 及并发观察调用。稳定槽须存续至 detach；观察绝不取得或释放借用。

公共成员

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)

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

备注

调用者须保证该区域静默，且填充标记时没有活动栈帧。不依赖 Arch/OS，也不在内部屏蔽中断。工作量最多为 bytes 次读取。未被写入的保留区，或恰好等于填充值的写入，可能掩盖实际使用；这不是溢出检测。MSP 资格需要独立确认启动时填充标记的来源，以及静默的采样点。该跨度须排除当前 SP、全部活动栈帧及异常栈保留区。它既不填充栈，也不声称读取物理 MSP 寄存器。

参数:

  • base – [in] 调用者证明来源的、存续且向下增长的栈区域。

  • bytes – [in] 原始已填充标记区域的正容量，单位为字节。

  • paint – [in] 区域启用前使用的精确填充值。

  • out – [out] 独立输出；跨度或别名无效时保持不变。

返回:

返回 SUCCESS 或 INVALID，不分配内存，也不保留指针。

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)

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

备注

物理 provider 要求平台已成功启动，调用者为特权任务／可配置 IRQ；不支持 NMI/HardFault 调用者。不调用 OS、不分配内存，也不等待。物理时钟在已成功启动且仍存续的 epoch 之外返回零；仅凭零不能证明就绪，启动状态才是权威。撤销时钟前须等待全部消费者退出。停止／重启或时钟变化会使全部旧 deadline 失效，即使新 epoch 的数值相同。UINT64_MAX 为保留值；时钟耗尽要求受控重启。若观察到硬件溢出确认失败，即使已成功隔离有限源，也会终止当前 epoch，并进入不可继续的终态。provider 保留所有权、屏蔽中断、调用 nx_fault_observe；若观察者返回则停驻。它绝不会以无效的零时间恢复 deadline 消费者。观察既不释放借用，也不证明安全输出；产品负责另行审查且不返回的恢复路径。普通关闭仍须先等待所有消费者及可选低功耗所有者退出。

返回:

自时间域初始化以来的微秒数。

bool nx_deadline_expired(nx_time_us_t deadline, nx_time_us_t now)

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

参数:

  • deadline – [in] 绝对时间或 NX_DEADLINE_NEVER。

  • now – [in] 同一时钟域中的快照。

返回:

有限 deadline 已到期时为 true，包含恰好相等的情况。

nx_time_us_t nx_deadline_after(nx_time_us_t now, uint64_t duration_us)

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

参数:

  • now – [in] 当前有限时间。

  • duration_us – [in] 相对时长，单位为微秒。

返回:

绝对 deadline，饱和于 NX_DEADLINE_NEVER。

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

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

备注

唯一执行所有者。复位会建立新的时钟域；复位／时钟变化后不得复用尚未完成的 deadline。

参数:

  • clock – [out] 调用者拥有的扩展状态。

  • counter – [in] 第一次硬件快照。

  • frequency_hz – [in] 非零且稳定的计数器频率。

返回:

成功返回 NX_SUCCESS；参数无效返回 NX_ERROR_INVALID。

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

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

备注

即使空闲，也必须至少每 2^32 个 tick 观察一次。仅凭两次快照无法检测多次漏掉的回绕。计数器须在等待期间持续运行，频率不得变化。

参数:

  • clock – [inout] 已初始化、仅有一个所有者的扩展状态。

  • counter – [in] 当前计数器快照。

  • time_us – [out] 扩展后的已用微秒数。

返回:

返回 NX_SUCCESS、NX_ERROR_STATE 或 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