OS 适配器：任务、等待与显式存储

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

baremetal.h

使用调用者存储的裸机轮询通知。

作者 Nexus Team

函数

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

向任何 ISR 暴露存储之前先初始化。

备注

启动上下文；不模拟任务或队列。字发布使用经审查的内联编译器／CPU 端口。

参数:

  • notification – [out] 尚未使用、由调用者拥有的存储

  • now_us – [in] 单调微秒时间源，等待期间持续运行

  • clock_context – [in] 时钟源上下文

返回:

NX_SUCCESS 或 NX_ERROR_INVALID

nx_wait_port_t nx_baremetal_notify_port(nx_baremetal_notify_t *notification)

绑定显式轮询通知。

备注

wake 使用编译器读改写（RMW），在 M0/M0+ 上则使用保存原状态的有界 PRIMASK 保护。该保护仅适用于单 CPU 上的特权 Thread／可配置 IRQ 调用者；不支持 NMI/HardFault、非特权代码、DMA 或其他安全域访问其元数据。返回 BUSY 后，所有者循环仍须继续服务控制器并推进排空。没有经过审查的架构专用原子睡眠合同，不插入 WFI/WFE。

参数:

  • notification – [in] 已初始化的存储

返回:

等待端口：截止时间前若状态未变，wait 返回 BUSY；NX_DEADLINE_NEVER 禁用到期，不意味着阻塞

struct nx_baremetal_notify_t
#include <baremetal.h>

显式、非阻塞的裸机通知存储。

公共成员

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

diagnostic.h

使用调用者显式环形存储的有界诊断。

作者 Nexus Team 版本 1.0.0 日期 2026-10-11 版权 Copyright (c) 2026 Nexus Team

函数

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

初始化尚未发布的环与调用者提供的条目。

备注

仅限启动上下文或独占生命周期所有者。两块存储都必须保持存活，直到所有发布者和读取者停止。条目不得与环状态或已提交记录存在内存别名。

参数:

  • ring – [out] 尚未使用、由调用者拥有的状态。

  • events – [in] 自然对齐的连续条目存储。

  • capacity – [in] 非零存储长度，至多为 UINT32_MAX。

返回:

SUCCESS 或 INVALID；拒绝时不修改存储。

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

在有界且保存原屏蔽状态的临界区内复制一个事件。

备注

仅适用于单 CPU 上的特权 Thread／可配置 IRQ。排除 NMI/HardFault、非特权代码、SMP、DMA 和其他安全域。环满时保留较早记录，并使丢失记录计数器饱和递增。不使用时钟回调、OS 操作、堆、字符串格式化或传输机制。

参数:

  • ring – [inout] 已初始化的环。

  • event – [in] 保持稳定直到本次调用返回的记录。

返回:

SUCCESS、环满时的 BUSY、INVALID 或 CONTEXT。

nx_result_t nx_diagnostic_ring_read(nx_diagnostic_ring_t *ring, nx_diagnostic_event_t *event)

从调用者拥有的环中消费一个事件。

备注

与 write 使用相同的特权单 CPU 域。读取失败时目标保持不变。这是诊断存储，不能用作完成队列或应用工作队列。

参数:

  • ring – [inout] 已初始化且仍有存活生产者的环。

  • event – [out] 调用者拥有的独立目标存储。

返回:

SUCCESS、环空时的 BUSY、INVALID 或 CONTEXT。

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

读取饱和溢出计数快照。

备注

与记录访问使用相同的有界、保存原屏蔽状态的执行域。

参数:

  • ring – [in] 已初始化的环。

  • dropped – [out] 调用者拥有的结果存储。

返回:

SUCCESS、INVALID 或 CONTEXT。

struct nx_diagnostic_event_t
#include <diagnostic.h>

一个不透明诊断记录；解释责任属于其所有者。

公共成员

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

显式环状态，不提供默认池、执行任务或传输机制。

公共成员

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

freertos.h

每对象静态 FreeRTOS 存储与可选轻量服务。

作者 Nexus Team

备注

运行期任务操作要求特权、未屏蔽的 Thread 模式；IRQ 唤醒有独立合同。调度器启动前，选定的 Baseline 端口可保留 PRIMASK=1，Mainline 端口可保留其准确的系统调用 BASEPRI；其他屏蔽值都必须为零。数值匹配不能证明屏蔽状态的来源。不安全的上下文会在修改内核 API 状态或对象存储之前返回 CONTEXT；可能需要读取调度器状态。启动阶段允许初始化、创建任务、唤醒和零等待队列操作。wait、join 和非零等待要求调度器正在运行。端口绑定和序列快照始终只读。MPU 用户任务网关及跨安全域的 Secure 任务调用不属于这些特权、当前安全域 API 的范围。

类型定义

typedef struct nx_freertos_queue_waiter nx_freertos_queue_waiter_t

调用者拥有的单操作锁存器，用于可关闭队列。

函数

bool nx_freertos_isr_allowed(void)

检查当前上下文是否允许调用内核 ISR API。

备注

Native POSIX 没有物理 IRQ，返回 false。NMI、故障和内核拥有的异常会在进入 FreeRTOS 前被拒绝。Mainline 的优先级／分组必须遵守系统调用优先级上限。Baseline PRIMASK 端口接受所有可配置 IRQ，不读取 Mainline 优先级分组。Nonsecure 侧权限不排除 Secure 侧访问。

返回:

仅当当前为特权、未屏蔽的外部 Cortex-M IRQ，且符合选定 CPU／SoC 边界及内核屏蔽合同，才返回 true

nx_result_t nx_freertos_notify_init(nx_freertos_notify_t *notification)

初始化尚未使用的通知存储。

备注

任务／启动上下文；不需要堆或定时器守护任务。

参数:

  • notification – [out] 调用者提供的存储，首次使用前清零

返回:

SUCCESS 或无效参数／上下文／初始化错误

nx_wait_port_t nx_freertos_notify_port(nx_freertos_notify_t *notification)

绑定序列锁存、单等待者通知。

备注

任务唤醒使用 xSemaphoreGive。IRQ 唤醒先验证优先级，再使用 xSemaphoreGiveFromISR。锁存器饱和无害；序列和请求谓词仍是权威依据。不通过延迟守护任务发布唤醒。

参数:

  • notification – [in] 已初始化且存活的存储

返回:

使用 nx_time_now_us 时钟域的通知端口

nx_result_t nx_freertos_notify_destroy(nx_freertos_notify_t *notification)

发布者和等待者均停止并完成 join 后再销毁。

备注

任务上下文。除了本项 busy 检查，还必须确保所有使用者静止。

参数:

  • notification – [inout] 存活存储，之后不再有使用者

返回:

SUCCESS、仍有等待者登记时的 BUSY，或错误

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)

使用调用者提供的准确栈和 TCB 创建一个任务。

备注

任务／启动上下文。没有隐藏执行任务或池容量上限。入口返回时必须处于特权 Thread 模式，已恢复手动设置的中断屏蔽，并在任何临时挂起后恢复调度器。

参数:

  • task – [out] 已清零且尚未使用的控制存储

  • name – [in] 内核诊断名称，由内核复制

  • stack – [in] 保留直到成功 join 的 StackType_t 数组

  • stack_words – [in] 实际容量，至少满足选定端口的启动最小值；运行期栈预算仍由调用者负责

  • priority – [in] 小于 configMAX_PRIORITIES 的优先级

  • entry – [in] 应用入口，可在协作停止后返回

  • context – [in] 保留直到 join 的入口上下文

返回:

SUCCESS 或无效参数／上下文／启动错误

nx_result_t nx_freertos_task_discard_before_scheduler(nx_freertos_task_t *task)

在包装函数执行之前，丢弃一个已创建的任务。

备注

仅限一个特权启动生命周期所有者；调度器状态必须为 NOT_STARTED。内核候选任务先被挂起，以在删除前移除内核保留的 TCB 引用。bootstrap 期间不得遗留未配对的 vTaskSuspendAll：NOT_STARTED 无法揭示内核私有的挂起嵌套层数。该调用者前置条件必须在修改前满足。成功后，只有在所有外部使用者均静止时，才允许复用 TCB、栈和上下文。这不会取消或 join 已执行的任务。

参数:

  • task – [inout] 存活、由调用者拥有且未被其他调用者使用的静态任务

返回:

仅在同步内核删除及锁存器清理完成后返回 SUCCESS；控制状态不存在、不完整或已经进入执行时返回 INVALID；ISR、非特权、非规范屏蔽状态或调度器正在运行／挂起时返回 CONTEXT，且不修改状态

nx_result_t nx_freertos_task_join(nx_freertos_task_t *task, nx_time_us_t deadline)

对协作返回的任务执行 join，并回收内核状态。

备注

单个 join 调用者，任务上下文。入口返回后停驻于包装函数；不会因自删除／Idle 清理竞态而提前释放调用者存储。先停止生产者，保持总线所有者推进排空，join 生产者，再 join 所有者。

参数:

  • task – [inout] 已启动且不是当前任务的任务

  • deadline – [in] nx_time_now_us 域内的绝对等待截止时间

返回:

仅当外部 vTaskDelete 已移除任务后返回 SUCCESS；TIMEOUT 保留句柄、TCB、栈和上下文；CONTEXT 拒绝不安全的 CPU 上下文、自 join 或已停止的调度器

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)

创建准确容量的静态字节复制队列。

参数:

  • queue – [out] 已清零的调用者队列控制存储

  • storage – [in] 保留直到 destroy 的字节缓冲区

  • storage_bytes – [in] 实际字节容量

  • depth – [in] 条目数量

  • item_size – [in] 每个条目复制的字节数

返回:

SUCCESS 或无效参数／上下文／启动错误

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

在有界内核相对等待内复制一个条目。

备注

任务上下文。准入／停止由应用显式所有者适配器负责，不属于此通用复制队列。

参数:

  • queue – [inout] 存活队列

  • item – [in] 至少为已配置条目字节数；返回后不再保留

  • wait_ticks – [in] 显式相对等待；禁止 portMAX_DELAY

返回:

SUCCESS、TIMEOUT、INVALID 或 CONTEXT

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

接收一个字节复制条目。

参数:

  • queue – [inout] 存活队列

  • item – [out] 已配置的条目字节容量，仅在成功时有效

  • wait_ticks – [in] 显式相对等待；禁止 portMAX_DELAY

返回:

SUCCESS、TIMEOUT、INVALID 或 CONTEXT

nx_result_t nx_freertos_queue_destroy(nx_freertos_queue_t *queue)

准入已停止且全部使用者完成 join 后再销毁。

参数:

  • queue – [inout] 存活且已排空的队列，之后不再有操作

返回:

SUCCESS、仍有使用者／条目时的 BUSY，或无效参数／上下文错误

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

使用一个绝对单调截止时间发送。

备注

立即就绪优先于截止到期。停止准入和使用者静止仍是外部对原始队列必须履行的责任。

参数:

  • queue – [inout] 存活的原始队列

  • item – [in] 已配置数量的字节，借用直到返回

  • deadline – [in] nx_time_now_us 域；NEVER 允许长时间等待

返回:

SUCCESS、TIMEOUT 或验证／上下文错误

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

使用一个绝对单调截止时间接收。

参数:

  • queue – [inout] 存活的原始队列

  • item – [out] 已配置数量的字节，仅在 SUCCESS 时有效

  • deadline – [in] nx_time_now_us 域

返回:

SUCCESS、TIMEOUT 或验证／上下文错误

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

绑定一个存活接收任务的独占通知槽。

备注

调用者确保通知槽独占。不提供全局槽注册表、分配、槽发现或跨安全域同步。

参数:

  • notification – [out] 已清零的调用者存储

  • receiver – [in] 保留直到所有发布者静止的任务

  • index – [in] 独占拥有的内核通知槽

返回:

SUCCESS、INVALID、CONTEXT，或 OS profile 不支持时的 UNSUPPORTED

nx_wait_port_t nx_freertos_direct_notify_port(nx_freertos_direct_notify_t *notification)

取得直接任务通知的等待端口。

备注

仅接收者可以等待。任务／已验证 IRQ 发布者使用独占槽；通知仍只是谓词提示。

参数:

  • notification – [in] 存活且已显式绑定的存储

返回:

使用 nx_time_now_us 的端口，或无效的零端口

nx_result_t nx_freertos_direct_notify_destroy(nx_freertos_direct_notify_t *notification)

全部发布者停止并完成 join 后解除绑定。

备注

不删除接收者，也不清除其内核槽。接收者和存储必须比每个保留的端口及发布者存活更久。

参数:

  • notification – [inout] 存活存储，之后不再有使用者

返回:

SUCCESS、正在等待时的 BUSY，或验证／上下文错误

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)

启动入口函数绝不允许返回的任务。

备注

不提供 join 锁存器、destroy 或强制删除。需要协作关闭和可回收存储时，应选择可 join 的任务。

参数:

  • task – [out] 已清零的永久控制存储，保留直到复位

  • name – [in] 由内核复制的诊断名称

  • stack – [in] 已对齐的实际栈，保留直到复位

  • stack_words – [in] 包含已审查启动最小值的容量

  • priority – [in] 小于 configMAX_PRIORITIES

  • entry – [in] 永久入口；返回将违反内核合同

  • context – [in] 保留直到复位

返回:

SUCCESS 或验证／上下文／启动错误

nx_result_t nx_freertos_queue_waiter_init(nx_freertos_queue_waiter_t *waiter)

初始化调用者提供的准确队列等待者存储。

参数:

  • waiter – [out] 已清零的存储，最多同时执行一个操作

返回:

SUCCESS 或验证／上下文／启动错误

nx_result_t nx_freertos_queue_waiter_destroy(nx_freertos_queue_waiter_t *waiter)

全部操作停止并完成 join 后才允许销毁。

参数:

  • waiter – [inout] 存活存储，之后不再有调用者

返回:

SUCCESS、活动时的 BUSY，或验证／上下文错误

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)

初始化可选、能可靠关闭的字节复制队列。

备注

没有隐藏执行任务或等待者池。每个并发阻塞操作都提供自己的已初始化等待者。广播在访问至多 maximum_waiters 个锁存器期间暂停调度。内核载荷复制和每次锁存器信号各自使用短 IRQ 保护。调度延迟和 IRQ 延迟须分别预算。大载荷应通过队列传递稳定句柄。登记机制仅适用于单核和任务上下文。

参数:

  • queue – [out] 已清零的控制存储，保留直到 destroy

  • storage – [in] 载荷缓冲区，保留直到 destroy

  • storage_bytes – [in] 实际载荷容量

  • depth – [in] 正数条目数量

  • item_size – [in] 正数的字节复制大小

  • maximum_waiters – [in] 显式、正数的同时调用预算

返回:

SUCCESS 或验证／上下文／启动错误

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)

发送时执行关闭感知准入，并采用绝对截止时间。

备注

就绪／准入与 close 在内核任务调度保护内串行化。锁存唤醒消除先唤醒、后睡眠的竞态。

参数:

  • queue – [inout] 存活的可关闭队列

  • item – [in] 借用直到返回的字节，超时后绝不保留

  • deadline – [in] nx_time_now_us 域，支持 NEVER

  • waiter – [inout] 调用者独占、已初始化的等待者

返回:

SUCCESS、关闭后的 CANCELLED、TIMEOUT、BUSY 或错误

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)

关闭后仍接收已有条目，排空后返回 CANCELLED。

参数:

  • queue – [inout] 存活的可关闭队列

  • item – [out] 已配置数量的字节，仅在 SUCCESS 时有效

  • deadline – [in] nx_time_now_us 域

  • waiter – [inout] 调用者独占、已初始化的等待者

返回:

SUCCESS、已关闭且为空时的 CANCELLED、TIMEOUT 或错误

nx_result_t nx_freertos_closable_queue_close(nx_freertos_closable_queue_t *queue)

停止发送，并唤醒当前登记的全部等待者。

备注

仅限任务上下文，不提供强制取消或任务删除。close 不会 join 使用者，也不授权回收存储。

参数:

  • queue – [inout] 存活队列

返回:

SUCCESS（包括重复 close），或验证／上下文错误

nx_result_t nx_freertos_closable_queue_destroy(nx_freertos_closable_queue_t *queue)

销毁已关闭、已排空且静止的队列。

备注

停止并 join 生产者，由所有者排空，join 消费者，然后分别销毁队列和每个等待者。

参数:

  • queue – [inout] 存活队列，之后不再有调用者进入

返回:

SUCCESS、尚未关闭／仍有使用者／仍有条目时的 BUSY，或错误

struct nx_freertos_notify_t
#include <freertos.h>

静态二值锁存器；一个等待者，发布者分别停止并排空。

公共成员

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

任务拥有独立 TCB；栈以其实际字数显式供给。

备注

控制字段由适配器拥有。调用者在首次使用前将存储清零，不得修改存活字段。包装函数开始执行时即消耗入口；上下文继续被借用，直到成功 join 或启动前 discard。

公共成员

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>

仅队列控制状态；实际深度／条目字节存储由外部提供。

公共成员

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

固定接收者及独占内核通知槽；不含锁存器。

公共成员

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

永久任务控制，不含 join 完成信号量。

公共成员

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

调用者拥有的单操作锁存器，用于可关闭队列。

公共成员

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

显式选择的关闭广播；原始队列存储不变。

公共成员

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

显式、有界的 FreeRTOS 跟踪接收端，不使用全局存储。

作者 Nexus Team 版本 1.0.0 日期 2026-10-11 版权 Copyright (c) 2026 Nexus Team

枚举

enum nx_freertos_trace_kind_t

维护范围内的内核跟踪身份；产品解释位于外部。

取值：

enumerator NX_FREERTOS_TRACE_SWITCH_IN
enumerator NX_FREERTOS_TRACE_CREATE
enumerator NX_FREERTOS_TRACE_DELETE

函数

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

消费一个有界内核跟踪事件。

备注

应用可覆盖弱空操作，并写入显式 nx_diagnostic_ring_t。可能在内核屏蔽状态或可配置 IRQ 下运行，因此绝不能阻塞、分配、格式化、传输、取得 OS 锁或调用内核服务。接收端负责时间戳和生命周期；不会自动提供缓冲区。trace profile 启用真实内核钩子。

参数:

  • event – [in] 维护范围内的跟踪类别。

  • identity – [in] 不透明任务身份，绝不构成解引用许可。

  • value – [in] 可选的调用者自定义数值诊断信息。

freertos_mpu.h

隔离 MPU 用户任务的特权静态生命周期。

作者 Nexus Team

枚举

enum nx_freertos_mpu_access_t

用户数据是不可执行的普通 RAM，仅允许这些权限。

取值：

enumerator NX_FREERTOS_MPU_READ_ONLY
enumerator NX_FREERTOS_MPU_READ_WRITE

函数

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

使用调用者准确存储创建非特权任务。

备注

仅限特权 Thread，调度器未挂起且没有手动屏蔽。拒绝时不保留引用，不调用内核创建 API。检查实际链接器边界及 MPU_TYPE。创建容量最少为 64 个字；应用须另外预算实际执行深度。不使用堆或对象池。

参数:

  • task – [inout] 受保护链接器 RAM 中的冷态或已无存活任务的元数据。

  • config – [in] 已验证的用户入口、栈和数据映射。

返回:

返回 SUCCESS；或在接纳前返回 INVALID／CONTEXT／STATE／BUSY／IO。GPIO 配置还会以 OVERFLOW 拒绝任务代次溢出。

nx_result_t nx_freertos_mpu_task_delete(nx_freertos_mpu_task_t *task)

外部使用者静止后，删除另一个隔离任务。

备注

一个特权生命周期所有者先停止外部访问。内核删除会同步移除调度器引用。拒绝自删除；不设隐藏回收任务。

备注

GPIO 配置在其授权持有任务生命周期固定引用时返回 BUSY。删除前须先 close 和 join。closing 标记防止在内核删除期间重新打开；保留该代次。

参数:

  • task – [inout] 已拥有、存活且受保护的元数据；绝不能是调用任务本身。

返回:

SUCCESS、INVALID、CONTEXT、STATE 或 BUSY。

struct nx_freertos_mpu_region_t
#include <freertos_mpu.h>

调用者选定的准确区域，在任务创建时复制。

公共成员

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

调用者拥有的完整受保护任务元数据。

备注

首次启动前，在特权 RAM 中零初始化。TCB 包含真实端口上下文和受保护栈。一个特权生命周期所有者串行调用 start/delete。

备注

GPIO 配置要求冷态零初始化，并在删除后保留任务代次；不得重置该历史。

公共成员

StaticTask_t control
TaskHandle_t handle
uint64_t epoch
uint8_t gpio_pinned
uint8_t closing
struct nx_freertos_mpu_config_t
#include <freertos_mpu.h>

不可变创建输入，仅在本次调用内被借用。

备注

入口必须是显式用户代码，且不得返回。栈和上下文数据保持被借用，直到所有者删除；区域不得包含内核 RAM、代码或 MMIO。上下文必须完整位于用户栈、用户 Flash 或已映射数据内。名称必须在可读的链接器保留区域内、在 configMAX_TASK_NAME_LEN 长度内终止；名称在冷路径复制。

公共成员

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_mpu_gpio.h

供一个受保护任务使用的标量 GPIO WRITE 授权。

作者 Nexus Team 版本 1.0.0 日期 2026-10-20 版权 Copyright (c) 2026 Nexus Team

函数

nx_result_t nx_freertos_mpu_gpio_open(void)

为精确的存活受保护任务打开固定授权。

备注

特权 Thread；调度器正在运行或尚未启动。BASEPRI/FAULTMASK 必须为零，但调度器启动前所选端口的引导 BASEPRI 除外。保存并恢复 PRIMASK。此操作固定任务生命周期，阻止其删除，直到 join。

返回:

SUCCESS，或 INVALID／CONTEXT／STATE／BUSY。拒绝不遗留部分固定引用。

nx_result_t nx_freertos_mpu_gpio_close(void)

撤销后续调用；不删除任务，也不停止 GPIO。

备注

同一个特权生命周期所有者串行调用 open/close/join 和任务 start/delete。NMI/HardFault 不得访问此授权。保留传入的中断屏蔽状态。

返回:

SUCCESS、INVALID、CONTEXT 或 STATE；保留全部固定引用。

nx_result_t nx_freertos_mpu_gpio_join(void)

在删除任务或停止 GPIO 之前，对已关闭的授权执行 join。

备注

单核上保存中断屏蔽状态的边界排除所有正在执行的标量效果。join 返回前解除其任务固定引用；不删除任务，也不重置其生命周期代次。

返回:

SUCCESS 解除固定引用；INVALID／CONTEXT／STATE 保留固定引用。

变量

const nx_freertos_mpu_gpio_binding_t nx_freertos_mpu_gpio_binding
struct nx_freertos_mpu_gpio_grant_t
#include <freertos_mpu_gpio.h>

特权 Flash 中不可变的 WRITE 授权。

备注

port_slot 指向只读、生成的 nx_binding_led 指针。已初始化的精确 GPIOC PC7 接口、操作表与提供者状态须在授权打开期间持续有效，直到成功 join。唯一生命周期所有者不得停止或重新配置该 GPIO。不授予 READ、翻转、指针复制或 MMIO 映射能力。

公共成员

const nx_gpio_port_t *const *port_slot
uint32_t device
uint32_t mask
struct nx_freertos_mpu_gpio_t
#include <freertos_mpu_gpio.h>

调用方拥有的受保护授权；仅在冷启动时清零。

备注

所有字段均视为私有。join 解除所捕获任务代次的绑定，不重置绑定任务的代次历史。存储必须在所链接绑定的整个生命周期内保持有效，包括拒绝和关闭状态。

公共成员

uint64_t task_epoch
TaskHandle_t handle
uint8_t phase
struct nx_freertos_mpu_gpio_binding_t
#include <freertos_mpu_gpio.h>

特权 Flash 中单个不可变装配绑定。

备注

仅定义一个 nx_freertos_mpu_gpio_binding 符号。control 和 task 位于互不重叠的特权 RAM 中；grant 位于特权 Flash 中。用户参数从不选择这些对象。

备注

删除后保留任务代次。仅在冷启动时初始化。

公共成员

nx_freertos_mpu_gpio_t *control
nx_freertos_mpu_task_t *task
const nx_freertos_mpu_gpio_grant_t *grant

freertos_stack.h

可选、有界的任务栈涂色快照。

作者 Nexus Team

函数

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

使用真实内核身份复制有界栈涂色事实。

备注

特权、未屏蔽、正在运行的 Thread；整个扫描期间任务栈必须静止。仅在 NEXUS_OS_TRACE 下可用。xTaskGetStaticBuffers 验证 TCB／栈身份，不验证大小。原始容量属于调用者合同。不挂起任务、不屏蔽中断、不分配，也不对存活栈重新涂色。最坏工作量为读取 words*sizeof(StackType_t) 个字节。涂色值是锁定内核使用的 0xA5。未触及／已触及的字节不能证明物理栈峰值。POSIX 内核端口使用独立的 pthread 执行栈；其查询不能测得 MCU 或 Linux 执行栈峰值。

参数:

  • binding – [in] 准确的原始 TCB、栈及容量，均须存活。

  • out – [out] 独立输出，拒绝时保持不变。

返回:

SUCCESS、INVALID、CONTEXT，或绑定不匹配时的 STATE。

struct nx_freertos_stack_binding_t
#include <freertos_stack.h>

原始创建时提供的准确静态任务事实。

备注

调用者保留全部存储，排除 delete/join/discard，并且绝不替换存活绑定。这不是注册表。

公共成员

TaskHandle_t handle
StaticTask_t *control
StackType_t *stack
size_t words

freertos_user.h

MPU 隔离用户任务的窄接口、无指针服务。

作者 Nexus Team

宏定义

NX_FREERTOS_USER_CODE

显式审查的非特权可执行代码段。

NX_FREERTOS_USER_DATA

显式用户 RAM，与内核和提供者状态分离。

NX_FREERTOS_USER_BSS

在预留 RAM 区间中显式定义、零初始化的用户存储。

NX_FREERTOS_PRIVILEGED_DATA

放入受保护内核 RAM 的可信静态任务元数据。

函数

void nx_freertos_user_delay(uint32_t ticks)

通过真实 MPU SVC 延迟调用用户任务。

备注

仅限调度器正在运行的 Thread。边界两侧不传递句柄或指针。这不是微秒截止时间。

参数:

  • ticks – [in] 内核相对 tick 数；零表示请求重新调度。

uint32_t nx_freertos_user_ticks(void)

通过 SVC 读取内核可回绕的 32 位 tick 计数器。

备注

仅限 Thread 的 MPU 配置服务，与 Core 时间不同。此服务不跨边界传递对象句柄或指针。

返回:

选定 OS 时钟域内的当前内核 tick 计数。

nx_result_t nx_freertos_user_gpio_write(uint32_t device, uint32_t set_mask, uint32_t reset_mask)

通过当前受保护任务的一个静态 GPIO 授权执行写入。

备注

仅限 Thread，且调度器正在运行。未知标识符和授权外的位返回 PERMISSION；掩码重叠或两者均为零时返回 INVALID。不引入用户 MMIO 映射、READ、翻转、OS 等待、堆分配或指针借用。已关闭或陈旧的任务代次不产生 GPIO 写入。

参数:

  • device – [in] 精确的装配内授权标识符，不是指针。

  • set_mask – [in] 获授权可置位的位，与 reset_mask 不重叠。

  • reset_mask – [in] 获授权可复位的位。

返回:

标量 SUCCESS，或 INVALID／PERMISSION／STATE／CONTEXT。

lowpower.h

显式的连续时钟无 tick 定时器端口。

作者 Nexus Team 版本 1.0.0 日期 2026-10-11 版权 Copyright (c) 2026 Nexus Team

宏定义

NX_FREERTOS_LATE_TICK_BUDGET

有界的延迟闹钟追赶；超出边界即违反定时器端口合同。

函数

const nx_freertos_lowpower_port_t *nx_freertos_lowpower_port(void)

返回显式选定的连续定时器端口。

备注

维护范围内的 SoC 绑定或应用实现覆盖弱 NULL 默认值。端口和上下文必须在调度器整个生命周期内存活；不提供运行期重新绑定、隐藏池或执行任务。没有端口时绝不停止 tick，也不进入睡眠。

返回:

稳定端口，或以 NULL 保持正常周期 tick。

void nx_freertos_suppress_ticks_and_sleep(uint32_t expected_idle_ticks)

保留实测相位的内核无 tick 钩子。

备注

仅由 Idle 在调度器挂起时调用。使用经过审查的屏蔽状态浅睡眠 WFI、准确恢复保存的 PRIMASK，并有界追赶待处理 tick。配置的 tick 频率必须能整除 1000000。暂停 tick 前先做最后一次内核就绪检查；暂停被拒绝时不产生修改。默认 profile 不调用此钩子。HIL 必须验证具体定时器、时钟连续性和实际唤醒延迟。

参数:

  • expected_idle_ticks – [in] 内核给出的有界、距下一次解除阻塞的窗口。

struct nx_freertos_tick_snapshot_t
#include <lowpower.h>

tick 停止 epoch，精度以具体端口声明为准。

公共成员

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

调用者拥有的不可变无 tick 定时器实现。

全部方法在特权 Idle Thread 模式、PRIMASK=1 且调度器挂起时运行。方法必须有界，不阻塞、不调用内核函数。pause_tick 以原子方式停止周期 tick，并快照当前 tick 周期已经过的相位；若有 pending tick，则无效果地拒绝。SUCCESS 开始借用定时器，直到 resume_tick。now_us 必须与 snapshot 使用同一单调时钟，并在浅睡眠期间连续运行。arm_deadline 配置已启用的 IRQ 唤醒源；拒绝时不得保留闹钟。disarm 仅撤销该闹钟。resume_tick 恢复周期源，下一次到期必须位于所供给的绝对时钟时刻；在已声明量化和采样边界内保持相位，而不是给每个 tick 累加回调延迟。不得发布已经计入的 tick。闹钟必须不晚于截止时间唤醒；至多允许追赶八个额外 tick 的延迟。时钟倒退或更大延迟必须故障停止。本接口不配置时钟、NVIC、SCR 或板级定时器。

公共成员

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

显式 POSIX 通知、队列与任务存储。

作者 Nexus Team

函数

uint64_t nx_native_now_us(void)

读取 POSIX 单调微秒时间。

返回:

时钟值；clock_gettime 失败会导致进程终止

nx_result_t nx_native_notify_init(nx_native_notify_t *notification)

在调用者尚未使用的存储中初始化通知。

备注

任务上下文；不支持 POSIX 信号处理函数。

参数:

  • notification – [out] 存储须比所有发布者存活更久

返回:

NX_SUCCESS 或初始化错误

nx_wait_port_t nx_native_notify_port(nx_native_notify_t *notification)

绑定单等待者的序列锁存通知端口。

参数:

  • notification – [in] 已初始化的存储

返回:

端口使用 CLOCK_MONOTONIC 绝对微秒时间；NX_DEADLINE_NEVER 表示不设超时的等待

nx_result_t nx_native_notify_destroy(nx_native_notify_t *notification)

外部发布者静止后再销毁。

备注

先停止并 join 发布者。本项检查不能授权未来调用与销毁竞态执行。此后不允许访问存储。

参数:

  • notification – [inout] 存活存储，之后不再有发布者

返回:

NX_SUCCESS，或仍有等待者登记时的 BUSY

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)

初始化显式、有界的字节复制队列。

备注

任务上下文；调用者保留缓冲区，直到成功 destroy。

参数:

  • queue – [out] 尚未使用的调用者存储

  • storage – [in] 调用者拥有的字节缓冲区

  • storage_bytes – [in] 实际字节容量

  • depth – [in] 条目数量，大于零

  • item_size – [in] 每条目字节数，大于零

返回:

NX_SUCCESS 或无效参数／初始化错误

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

向队列复制一个条目。

备注

即使截止时间已到期，仍使用立即可用的容量。有限截止时间约束等待；伪唤醒绝不重新开始等待预算。失败时不保留任何条目。

参数:

  • queue – [inout] 存活队列

  • item – [in] 至少 item_size 字节，仅在调用期间借用

  • deadline_us – [in] CLOCK_MONOTONIC 绝对截止时间，或 NX_DEADLINE_NEVER

返回:

SUCCESS、TIMEOUT、STATE（已关闭）或错误

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

接收一个条目；关闭的队列仍可排空。

备注

截止时间已到期时仍可接收立即可用的条目。失败时输出不变。关闭的队列仅在现有条目排空后返回 STATE。

参数:

  • queue – [inout] 存活队列

  • item – [out] 至少 item_size 字节；仅在 SUCCESS 时有效

  • deadline_us – [in] CLOCK_MONOTONIC 绝对截止时间，或 NX_DEADLINE_NEVER

返回:

SUCCESS、TIMEOUT、STATE（已关闭）或错误

nx_result_t nx_native_queue_close(nx_native_queue_t *queue)

拒绝发送，并唤醒全部正在等待的调用者。

备注

任务上下文；调用者必须在 destroy 前 join 队列使用者。

参数:

  • queue – [inout] 存活队列

返回:

NX_SUCCESS 或无效参数错误

nx_result_t nx_native_queue_destroy(nx_native_queue_t *queue)

销毁已静止且已排空的队列存储。

参数:

  • queue – [inout] 已关闭队列，之后不再有使用者

返回:

NX_SUCCESS，或仍有使用者／条目时的 BUSY

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

使用供给的主机栈启动任务。

备注

任务上下文。没有默认任务、池或隐藏栈。POSIX 库的内部管理分配属于主机运行时，不能作为 MCU RAM 证据。

参数:

  • task – [out] 已清零且尚未使用的调用者句柄

  • stack – [in] pthread_attr_setstack 接受的对齐存储

  • stack_bytes – [in] 主机栈大小，至少为 PTHREAD_STACK_MIN

  • entry – [in] 会返回、执行有界的应用入口

  • context – [in] 入口上下文，保留直到 join

返回:

NX_SUCCESS 或无效参数／启动错误

nx_result_t nx_native_task_join(nx_native_task_t *task)

请求应用协作停止之后执行 join。

备注

可能阻塞直到入口返回。不提供强制取消。调用者仅在成功后才可释放上下文、句柄和栈。一个外部所有者串行执行 start/join；不支持多个同时 join 的调用者，也不支持外部 pthread_cancel/detach。销毁通知或队列存储前，先停止并 join 发布者。

参数:

  • task – [inout] 已启动的任务；调用者不得是被 join 的任务

返回:

仅在 pthread_join 确认执行已退出后返回 NX_SUCCESS

struct nx_native_notify_t
#include <native.h>

单等待者、多个 Task 发布者；字段为私有状态。

备注

initialize/destroy 由一个外部生命周期所有者负责。destroy 前，停止并 join 所有发布者和等待者。不支持外部对阻塞在这些 API 中的调用者执行 pthread_cancel；应使用协作停止、发布和 join。

公共成员

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

由调用者确定容量的队列存储，不使用堆或全局对象池。

备注

由一个生命周期所有者执行 initialize、close 和 destroy。存活期间支持多个生产者／消费者。不支持外部对阻塞使用者执行 pthread_cancel。

公共成员

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>

显式任务句柄；启动时供给栈存储。

备注

由一个外部生命周期所有者串行执行 start/join；仅有一个 join 调用者。入口可以尝试自 join，此时返回 BUSY。不支持外部取消或 detach。

公共成员

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

secure_context.h

供可信 NS 内核使用的调用者自有 Secure 上下文租约。

作者 Nexus Team 版本 1.0.0 日期 2026-10-11 版权 Copyright (c) 2026 Nexus Team

宏定义

NX_FREERTOS_SECURE_MIN_STACK_BYTES

最小上下文容量不包含八字节 ARM 栈封印。

枚举

enum nx_freertos_secure_fault_t

Secure 上下文完整性失败，与普通拒绝区分。

取值：

enumerator NX_FREERTOS_SECURE_SEAL_FAILURE
enumerator NX_FREERTOS_SECURE_STACK_FAILURE

函数

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

为一个可信任务身份准备准确 Secure 存储。

备注

Secure 特权 Thread 启动上下文／独占生命周期所有者。两段内存都必须是 Secure、可写且互不重叠。prepare 期间，不得有 NS 任务以此身份运行。拒绝重复 prepare；epoch 绝不重置。不使用分配、内核操作或运行期注册表。

参数:

  • context – [out] 已清零、由调用者拥有的 Secure 元数据。

  • stack – [in] 八字节对齐的 Secure 可写栈分配。

  • bytes – [in] 整块分配，包含上端八字节封印。

  • task – [in] 不透明 NS 任务身份，此处绝不解引用。

返回:

SUCCESS、INVALID、CONTEXT、STATE 或 BUSY。

nx_result_t nx_freertos_secure_context_rebind(nx_freertos_secure_context_t *context, void *task)

在保留 epoch 历史的前提下重新绑定已退役元数据。

备注

仅限 Secure 生命周期所有者，在先前任务已 join 且每个观察者均已停止后调用。复用现有栈；下一次分配后，过期句柄仍无效。

参数:

  • context – [inout] 已准备、未租出且未加载的 Secure 元数据。

  • task – [in] 新的可信 NS 任务身份。

返回:

SUCCESS、INVALID、CONTEXT、STATE 或 BUSY。

nx_freertos_secure_context_t *nx_freertos_secure_context_for_task(void *task)

解析可信、静态组合的 Secure 任务记录。

备注

Secure 应用使用不可变映射覆盖弱 NULL 默认值。调用期间持有两侧 PRIMASK 状态；绝不能解引用 NS 提供的元数据指针、分配、阻塞、发现对象、调用内核或修改映射。NS 内核及其 SVC/PendSV 被信任：此机制不认证恶意 NS 特权内核。NS Thread 调用不能伪装为 Handler 来源。

参数:

  • task – [in] 可信 NS 内核提供的不透明身份。

返回:

已准备、由调用者拥有的元数据；未获授权时为 NULL。

void nx_freertos_secure_fault(nx_freertos_secure_fault_t fault)

已加载 Secure 栈发生完整性失败后执行故障停止。

备注

Secure 应用可覆盖以安全记录／复位。调用期间持有两侧屏蔽；不得返回、阻塞、调用内核或释放保留的存储。默认保持屏蔽并自旋。不强加传输机制或产品恢复策略。

参数:

  • fault – [in] 封印或栈不变量被破坏。

struct nx_freertos_secure_context_t
#include <secure_context.h>

显式 Secure 元数据，绝不存放于 Nonsecure RAM。

备注

prepare 前清零。准备期间字段由机制拥有，应用不得修改。元数据和栈必须保持存活，直到任务已 join、租约已释放且不再有已加载上下文。Secure 栈的运行期容量属于应用预算，不是此端口的最小值。

公共成员

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

调用者拥有的 ThreadX 任务、等待和字节队列服务。

作者 Nexus Team

备注

特权、单核、当前安全域 API。所有控制存储初始清零，存活期间由适配器拥有。一个外部生命周期所有者串行执行 init/destroy 和 join；回收存储前，发布者、队列调用者和 IRQ 源必须静止。运行期任务操作要求未屏蔽的 Thread 模式且内核正在运行。真实 bootstrap 允许对象初始化、任务 create/discard 和唤醒；不允许阻塞等待或队列操作。手动屏蔽、ISR 或不支持的上下文会在修改前返回 CONTEXT。字节队列的任务阈值保护拒绝外来的优先级零时间片调用者。调用者控制存储、栈范围、完整借用的名称／上下文对象、队列载荷、条目缓冲区和等待者必须互不重叠。冷路径准入拒绝已知的控制／栈／载荷重叠，以及起始地址位于控制存储或栈内的名称／上下文；未知不透明对象的完整范围仍由调用者负责。绝不能通过可关闭队列内部的原始队列执行操作。所有截止时间均使用 nx_time_now_us；NX_DEADLINE_NEVER 是真正无界的内核等待。超时绝不撤销任何已接受的 I/O 借用。MPU/TZ 隔离、无 tick 睡眠及其他 Cortex-M 端口不属于此后端范围。

类型定义

typedef struct nx_threadx_queue_waiter nx_threadx_queue_waiter_t

每个同时执行的关闭感知操作都显式拥有一个调用者锁存器。

函数

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

由产品拥有的显式、不可逆内核入口。

备注

特权冷启动 Thread/MSP，无存活 FP 上下文或屏蔽状态。启动阶段可创建并 discard 尚未使用的静态对象。启动返回后，bootstrap 范围即被封闭。只有可信内核可调用适配器 tx_application_define；适配器在产品回调之前验证规范的特权 Thread 上下文。这不是安全隔离 API。内核意外返回时调用故障停止并保留全部效果；绝不重新开放 bootstrap 回收。

参数:

  • startup – [in] 在 tx_application_define 内执行的产品初始化

  • context – [in] 在整个启动及内核生命周期内借用

返回:

进入前返回 CONTEXT 或 INVALID；成功进入后绝不返回

void nx_threadx_fail_stop(nx_result_t reason)

产品失败钩子；默认永久停驻。

备注

不修复或规范化实际故障上下文；它可能处于屏蔽、ISR 或非特权状态。不得假定内核、时钟、栈可正常使用，也不得假定拥有访问外设的权限。适配器在此钩子之前先调用 Core 故障钩子。产品负责另外审查的安全输出／复位动作。返回不授权清理；适配器将停驻。

参数:

  • reason – [in] 上下文、永久入口或内核返回失败

nx_result_t nx_threadx_external_tick_setup(uint32_t tick_hz)

仅显式外部 Tick 模式要求的产品钩子。

备注

真实内核 bootstrap，特权且 PRIMASK 屏蔽。提供者负责定时器时钟和 IRQ 优先级上限；不得改变平台的连续单调时钟。缺少钩子会导致链接失败。失败将进入保留状态的故障停止。

参数:

  • tick_hz – [in] 准确、不可变、已解析的内核频率

返回:

绑定真实、有界的周期 IRQ 源后返回 SUCCESS

bool nx_threadx_isr_allowed(void)

只读的可配置 IRQ 与选定屏蔽策略检查。

备注

Native 没有硬件 IRQ 源，返回 false。

返回:

仅在特权、未屏蔽且经过审查的外部 IRQ 中返回 true

nx_result_t nx_threadx_notify_init(nx_threadx_notify_t *notification)

在任务或真实 bootstrap 上下文初始化一个二值锁存器。

参数:

  • notification – [inout] 已清零的调用者控制存储，保留直到 destroy

返回:

SUCCESS、INVALID、CONTEXT 或 IO

nx_wait_port_t nx_threadx_notify_port(nx_threadx_notify_t *notification)

绑定序列提示和一个并发阻塞等待者。

备注

绑定／arm 为只读操作。wake 支持任务／bootstrap，或经 nx_threadx_isr_allowed 准入的 IRQ。wait 仅限任务上下文；有限截止时间到期的判断优先于序列变化。

参数:

  • notification – [inout] 存活锁存器，须在每个端口使用者存活期间保留

返回:

等待接口；控制存储为 null 或未存活时返回空接口

nx_result_t nx_threadx_notify_destroy(nx_threadx_notify_t *notification)

全部发布者和等待者静止后才允许销毁。

参数:

  • notification – [inout] 存活的调用者锁存器

返回:

SUCCESS、INVALID、CONTEXT、BUSY 或 IO；失败时保留锁存器

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)

使用准确存储创建可协作返回的任务。

备注

没有适配器堆或执行任务。名称被借用，不复制。Linux 使用自己的 pthread 栈；调用者缓冲区仅用于验证内核元数据，不是主机栈预算。优先级更高的入口可能在 start 返回前运行。

参数:

  • task – [inout] 已清零的调用者 TCB／控制存储，保留直到 join/discard

  • name – [in] 借用的不可变名称，保留直到回收

  • stack – [in] 八字节对齐的调用者存储

  • stack_bytes – [in] 实际容量，至少为 TX_MINIMUM_STACK

  • priority – [in] ThreadX 优先级；数值越小越先运行

  • entry – [in] 仅在应用停止／排空后返回

  • context – [in] 借用直到成功 join/discard

返回:

SUCCESS、INVALID、CONTEXT 或 IO；部分失败且无法确认可回收时，保留存活控制存储

nx_result_t nx_threadx_task_join(nx_threadx_task_t *task, nx_time_us_t deadline)

对协作返回的任务执行 join，并证明引用已撤离。

备注

拒绝自 join。超时保留任务、借用名称、栈和上下文。仅有完成提示绝不允许回收；真实内核删除成功才证明引用已撤离。

参数:

  • task – [inout] 存活的调用者任务，仅允许一个外部 join 调用者

  • deadline – [in] 绝对 Core 截止时间，或 NX_DEADLINE_NEVER

返回:

SUCCESS、INVALID、CONTEXT、TIMEOUT 或 IO

nx_result_t nx_threadx_task_discard_before_scheduler(nx_threadx_task_t *task)

仅在真实 bootstrap 内丢弃尚未使用的任务。

备注

这是启动前回滚，绝不是运行期取消。

参数:

  • task – [inout] 存活且入口从未开始执行的任务

返回:

SUCCESS、INVALID、CONTEXT 或 IO；失败时保留存储

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)

启动不含完成锁存器的永久任务。

备注

栈按八字节对齐；失败时可能保留存活状态。

参数:

  • task – [inout] 已清零的调用者控制存储，保留直到复位

  • name – [in] 借用的不可变名称，保留直到复位

  • stack – [in] 已对齐的调用者缓冲区，保留直到复位

  • stack_bytes – [in] 实际容量，至少为 TX_MINIMUM_STACK

  • priority – [in] ThreadX 优先级数值越小越先运行

  • entry – [in] 绝不返回；返回将触发保留状态的故障停止

  • context – [in] 借用直到复位

返回:

SUCCESS、INVALID、CONTEXT 或 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)

初始化支持准确任意字节条目的有界队列。

参数:

  • queue – [inout] 已清零的调用者控制存储，保留直到 destroy

  • storage – [in] 调用者载荷存储，保留直到 destroy

  • storage_bytes – [in] 准确的深度乘以 item_size

  • depth – [in] 正数、有界且小于 TX_WAIT_FOREVER 的容量

  • item_size – [in] 正数字节数，不缩减为字尺寸

返回:

SUCCESS、INVALID、CONTEXT 或 IO

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

仅 Task 发送；立即就绪优先于截止到期。

参数:

  • queue – [inout] 存活队列，在整个操作期间保留

  • item – [in] 准确的 item_size 个可读字节，借用直到返回

  • deadline – [in] 绝对 Core 截止时间，或 NX_DEADLINE_NEVER

返回:

SUCCESS、INVALID、CONTEXT、TIMEOUT、OVERFLOW 或 IO

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

仅 Task 接收；只在 SUCCESS 时修改输出。

参数:

  • queue – [inout] 存活队列，在整个操作期间保留

  • item – [out] 准确的 item_size 个可写字节，借用直到返回

  • deadline – [in] 绝对 Core 截止时间，或 NX_DEADLINE_NEVER

返回:

SUCCESS、INVALID、CONTEXT、TIMEOUT、OVERFLOW 或 IO

nx_result_t nx_threadx_queue_destroy(nx_threadx_queue_t *queue)

每个调用者静止后，销毁已排空队列。

参数:

  • queue – [inout] 存活的调用者控制存储及数据存储

返回:

SUCCESS、INVALID、CONTEXT 或 BUSY；失败时保留存储

nx_result_t nx_threadx_queue_waiter_init(nx_threadx_queue_waiter_t *waiter)

初始化一个显式关闭感知操作锁存器。

参数:

  • waiter – [inout] 已清零的调用者存储，保留直到等待者 destroy

返回:

SUCCESS、INVALID、CONTEXT 或 IO

nx_result_t nx_threadx_queue_waiter_destroy(nx_threadx_queue_waiter_t *waiter)

等待者操作返回后，销毁其非活动存储。

参数:

  • waiter – [inout] 存活的调用者锁存器，不能有并发使用者

返回:

SUCCESS、INVALID、CONTEXT、BUSY 或 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)

向字节队列加入显式、有界的关闭广播。

备注

载荷大小和 maximum_waiters 约束任务调度暂停时长；整个复制／广播过程不屏蔽中断。

参数:

  • queue – [inout] 已清零的调用者控制存储，保留直到 destroy

  • storage – [in] 调用者载荷存储，保留直到 destroy

  • storage_bytes – [in] 准确的深度乘以 item_size

  • depth – [in] 正数且小于 TX_WAIT_FOREVER 的容量

  • item_size – [in] 正数、准确的载荷字节数

  • maximum_waiters – [in] 正数的最大同时操作数

返回:

SUCCESS、INVALID、CONTEXT 或 IO

nx_result_t nx_threadx_closable_queue_close(nx_threadx_closable_queue_t *queue)

拒绝发送、唤醒已登记等待者、保留已入队条目。

参数:

  • queue – [inout] 存活的关闭感知队列

返回:

SUCCESS、INVALID 或 CONTEXT；close 是幂等操作

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)

发送时提供立即关闭唤醒与显式准入。

备注

已关闭队列拒绝发送，且不修改载荷。

参数:

  • queue – [inout] 存活队列，在整个操作期间保留

  • item – [in] 准确的 item_size 个可读字节，借用直到返回

  • deadline – [in] 绝对 Core 截止时间，或 NX_DEADLINE_NEVER

  • waiter – [inout] 本次并发调用独占的存活锁存器

返回:

SUCCESS、CANCELLED、TIMEOUT、BUSY、INVALID、CONTEXT 或 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)

关闭后接收并排空此前已入队的条目。

备注

已关闭且为空时返回 CANCELLED；失败时输出保持不变。

参数:

  • queue – [inout] 存活队列，在整个操作期间保留

  • item – [out] 准确的 item_size 个可写字节，借用直到返回

  • deadline – [in] 绝对 Core 截止时间，或 NX_DEADLINE_NEVER

  • waiter – [inout] 本次并发调用独占的存活锁存器

返回:

SUCCESS、CANCELLED、TIMEOUT、BUSY、INVALID、CONTEXT 或 IO

nx_result_t nx_threadx_closable_queue_destroy(nx_threadx_closable_queue_t *queue)

仅销毁已关闭、已排空且静止的队列。

参数:

  • queue – [inout] 存活控制存储及其借用的载荷存储

返回:

SUCCESS、INVALID、CONTEXT 或 BUSY；失败时保留存储

struct nx_threadx_notify_t
#include <threadx.h>

一个二值锁存器；销毁之前发布者必须静止。

公共成员

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

返回型任务保留全部存储，直到外部成功 join。

公共成员

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>

永久任务不含完成锁存器、join 或 destroy。

公共成员

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

准确的任意字节条目，不缩减为原生字尺寸。

公共成员

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>

每个同时执行的关闭感知操作都显式拥有一个调用者锁存器。

公共成员

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

可选、有界关闭广播；登记仅在 Task 上下文执行。

公共成员

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

显式外部 Tick 与诊断计数器合同。

作者 Nexus Team

备注

只有配置中显式声明的 OS 策略启用这些符号时，应用才实现它们。不提供弱定时器／计数器回退实现。平台绝不臆造定时器接线。

函数

void nx_freertos_external_tick_setup(uint32_t tick_hz)

配置应用选定的内核 Tick 源。

备注

调度器启动时在其规范、已屏蔽、特权上下文调用。配置周期中断，清除 pending 状态，并以已验证的优先级路由到选定内核 Tick 处理函数。不得在此启动任务。硬件时钟和路由仍由应用／SoC 拥有。

参数:

  • tick_hz – [in] 配置中显式声明的准确 Tick 频率，单位为赫兹

void nx_freertos_runtime_counter_start(void)

启动显式选定的诊断计数器。

备注

调度器启动期间调用。计数器初始化必须有界、不分配，并在启动屏蔽状态下安全。

uint32_t nx_freertos_runtime_counter_now(void)

无阻塞地读取诊断计数器。

备注

由内核在上下文切换期间调用。必须有界、不分配，并在中断／临界上下文中安全。配置高于 Tick 的频率，并在解释记录总量时处理回绕。

返回:

以应用定义单位计量、按 2^32 取模回绕的单调计数器

wait.h

可选的序列锁存等待，不含隐藏执行任务。

作者 Nexus Team

函数

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

等待调用者的权威谓词。

备注

任务上下文。不隐式执行服务、队列操作、回调派发或任务创建。共享总线客户端不得用 ready 服务控制器；停止／排空期间，其执行所有者必须保持运行。

参数:

  • port – [in] 存活的单等待者通知端口

  • ready – [in] 有界谓词，在调用者上下文调用

  • context – [in] 谓词上下文，仅在本次调用期间保留

  • deadline_us – [in] 端口时钟域内的绝对截止时间，或 NX_DEADLINE_NEVER；不能使用墙上时钟或相对值

返回:

观察到谓词为 true 时返回 NX_SUCCESS，包括 TIMEOUT 后的最后一次观察；否则返回端口错误

nx_result_t nx_wait_select(const nx_wait_port_t *port, const nx_wait_source_t *sources, size_t count, size_t start, uint64_t deadline_us, size_t *selected)

按调用者选定的循环优先顺序等待任一 source。

备注

仅任务上下文，遵守 nx_wait_until 的 arm/recheck 和 deadline 合同。每轮扫描从 start 回绕，至多访问 count 个谓词，不分配或保留注册。Source ready 不授予所有权，也不消费事件；调用者必须获取或尝试真实操作。显式推进下次 start 以选择公平性。调用者连接 source 通知到同一 port，维护权威谓词，并在回收状态前停止和 join publisher/waiter。没有隐式 worker、派发、订阅、自动注销或 service。除非调用者 callback 改变 selected，错误会保留它。

参数:

  • port – [in] Source publisher 使用的同一有效单 waiter port

  • sources – [in] 稳定数组，每个 ready callback 非 NULL

  • count – [in] 可读 source 条目数量，非零

  • start – [in] 首个检查索引，严格小于 count

  • deadline_us – [in] Port 时间域内的绝对单调 deadline，或 NX_DEADLINE_NEVER

  • selected – [out] 仅成功时写索引；与 port、sources、其有效 context 及其他借用元数据独立

返回:

观察到 ready 时返回 NX_SUCCESS，包括后端错误后的最终 ready；参数无效或重叠返回 INVALID，跨度不可表示返回 OVERFLOW，或返回 port 错误

struct nx_wait_port_t
#include <wait.h>

单等待者通知端口。

调用者拥有存储，并串行执行 arm/wait。各后端文档规定的上下文允许多个唤醒发布者。序列只是提示；谓词／请求才是权威依据。arm 与重新检查之间的唤醒次数必须少于 2^32。所有截止时间均为后端时钟域内的绝对单调微秒时间；NX_DEADLINE_NEVER 显式禁用超时。时钟必须在等待期间连续运行且不得改变时间域；应使用 nx_deadline_after 构造相对预算，避免溢出。超时不会使请求结清或释放缓冲区。销毁前，必须停止并 join 每个发布者和等待者；仅有 SETTLED 不能证明通知存储可回收。arm 快照序列；wait 必须原子地观察序列变化或已锁存唤醒，包括调用者再次检查与睡眠之间发生的唤醒。序列变化不能绕过有限截止时间：wait 在每次调用以及每次从阻塞返回后，都先检查到期，再报告提示。未到期时，非阻塞后端可以返回 BUSY。仅一个所有者可以执行 arm/wait；即使后端会拒绝第二个并发等待，其行为仍位于端口合同之外。

公共成员

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)
struct nx_wait_source_t
#include <wait.h>

一个调用者拥有的权威 ready source。

备注

ready 在等待调用者的上下文执行，必须有界。按状态要求的同步规则观察真实状态，不 service 控制器或修改 source 数组。若谓词允许，context 可为 NULL。整个选择期间，source 配置和 context 必须保持有效。

公共成员

bool (*ready)(void *context)
void *context