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 暴露存储之前先初始化。

备注

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

参数:

  • notification – [out] Unused caller-owned storage

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

  • clock_context – [in] Clock source context

返回:

NX_SUCCESS or NX_ERROR_INVALID

nx_wait_port_t nx_baremetal_notify_port(nx_baremetal_notify_t *notification)

绑定显式轮询通知。

备注

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.

参数:

  • notification – [in] Initialized storage

返回:

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>

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

公共成员

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)

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

备注

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.

参数:

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

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

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

返回:

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)

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

备注

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.

参数:

  • ring – [inout] Initialized ring.

  • event – [in] Stable record until this call 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)

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

备注

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

参数:

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

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

返回:

SUCCESS, BUSY when empty, INVALID or CONTEXT.

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

读取饱和溢出计数快照。

备注

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

参数:

  • ring – [in] Initialized ring.

  • dropped – [out] Caller-owned result.

返回:

SUCCESS, INVALID or 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

备注

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.

类型定义

typedef struct nx_freertos_queue_waiter nx_freertos_queue_waiter_t

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

函数

bool nx_freertos_isr_allowed(void)

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

备注

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.

返回:

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)

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

备注

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

参数:

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

返回:

SUCCESS or invalid/context/initialization error

nx_wait_port_t nx_freertos_notify_port(nx_freertos_notify_t *notification)

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

备注

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.

参数:

  • notification – [in] Initialized live storage

返回:

Notification port using nx_time_now_us clock domain

nx_result_t nx_freertos_notify_destroy(nx_freertos_notify_t *notification)

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

备注

Task context. Quiescence is required beyond this busy check.

参数:

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

返回:

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)

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

备注

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.

参数:

  • 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

返回:

SUCCESS or invalid/context/start error

nx_result_t nx_freertos_task_discard_before_scheduler(nx_freertos_task_t *task)

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

备注

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.

参数:

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

返回:

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，并回收内核状态。

备注

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.

参数:

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

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

返回:

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)

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

参数:

  • 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

返回:

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)

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

备注

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

参数:

  • queue – [inout] Live queue

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

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

返回:

SUCCESS, TIMEOUT, INVALID or CONTEXT

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

接收一个字节复制条目。

参数:

  • queue – [inout] Live queue

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

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

返回:

SUCCESS, TIMEOUT, INVALID or CONTEXT

nx_result_t nx_freertos_queue_destroy(nx_freertos_queue_t *queue)

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

参数:

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

返回:

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)

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

备注

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

参数:

  • queue – [inout] Live raw queue

  • item – [in] Configured bytes borrowed until return

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

返回:

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)

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

参数:

  • queue – [inout] Live raw queue

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

  • deadline – [in] nx_time_now_us domain

返回:

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)

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

备注

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

参数:

  • notification – [out] Zeroed caller storage

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

  • index – [in] Exclusively owned kernel notification slot

返回:

SUCCESS, INVALID, CONTEXT or UNSUPPORTED by OS profile

nx_wait_port_t nx_freertos_direct_notify_port(nx_freertos_direct_notify_t *notification)

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

备注

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

参数:

  • notification – [in] Live explicitly bound storage

返回:

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)

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

备注

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

参数:

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

返回:

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)

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

备注

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

参数:

  • 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

返回:

SUCCESS or validation/context/start error

nx_result_t nx_freertos_queue_waiter_init(nx_freertos_queue_waiter_t *waiter)

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

参数:

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

返回:

SUCCESS or validation/context/start error

nx_result_t nx_freertos_queue_waiter_destroy(nx_freertos_queue_waiter_t *waiter)

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

参数:

  • waiter – [inout] Live storage without future callers

返回:

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)

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

备注

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.

参数:

  • 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

返回:

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)

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

备注

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

参数:

  • 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

返回:

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)

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

参数:

  • 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

返回:

SUCCESS, CANCELLED when closed/empty, TIMEOUT or error

nx_result_t nx_freertos_closable_queue_close(nx_freertos_closable_queue_t *queue)

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

备注

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

参数:

  • queue – [inout] Live queue

返回:

SUCCESS, including repeated close, or validation/context

nx_result_t nx_freertos_closable_queue_destroy(nx_freertos_closable_queue_t *queue)

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

备注

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

参数:

  • queue – [inout] Live queue without future entrants

返回:

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

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；栈以其实际字数显式供给。

备注

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.

公共成员

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)

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

备注

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.

参数:

  • event – [in] Maintained trace kind.

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

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

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)

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

备注

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.

参数:

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

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

返回:

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

nx_result_t nx_freertos_mpu_task_delete(nx_freertos_mpu_task_t *task)

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

备注

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

参数:

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

返回:

Success, INVALID, CONTEXT or STATE with storage retained.

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>

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

备注

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.

公共成员

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

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

备注

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.

公共成员

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

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

作者 Nexus Team

函数

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

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

备注

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.

参数:

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

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

返回:

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

struct nx_freertos_stack_binding_t
#include <freertos_stack.h>

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

备注

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

公共成员

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_PRIVILEGED_DATA

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

函数

void nx_freertos_user_delay(uint32_t ticks)

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

备注

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

参数:

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

uint32_t nx_freertos_user_ticks(void)

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

备注

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

返回:

Current kernel tick count in the selected OS clock domain.

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)

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

备注

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.

返回:

Stable port or NULL to leave normal periodic ticking.

void nx_freertos_suppress_ticks_and_sleep(uint32_t expected_idle_ticks)

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

备注

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.

参数:

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

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 value; clock_gettime failure is process-fatal

nx_result_t nx_native_notify_init(nx_native_notify_t *notification)

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

备注

Task context; POSIX signal handlers are unsupported.

参数:

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

返回:

NX_SUCCESS or an initialization error

nx_wait_port_t nx_native_notify_port(nx_native_notify_t *notification)

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

参数:

  • notification – [in] Initialized storage

返回:

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)

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

备注

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

参数:

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

返回:

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)

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

备注

Task context; caller keeps buffer until successful destroy.

参数:

  • 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

返回:

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)

向队列复制一个条目。

备注

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.

参数:

  • 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

返回:

SUCCESS, TIMEOUT, STATE (closed) or error

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

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

备注

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.

参数:

  • 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

返回:

SUCCESS, TIMEOUT, STATE (closed) or error

nx_result_t nx_native_queue_close(nx_native_queue_t *queue)

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

备注

Task context; caller must join queue users before destroy.

参数:

  • queue – [inout] Live queue

返回:

NX_SUCCESS or invalid error

nx_result_t nx_native_queue_destroy(nx_native_queue_t *queue)

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

参数:

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

返回:

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)

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

备注

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

参数:

  • 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

返回:

NX_SUCCESS or invalid/start error

nx_result_t nx_native_task_join(nx_native_task_t *task)

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

备注

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.

参数:

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

返回:

NX_SUCCESS only after pthread_join confirms execution exit

struct nx_native_notify_t
#include <native.h>

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

备注

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.

公共成员

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

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

备注

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

公共成员

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

公共成员

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

参数:

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

返回:

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

nx_result_t nx_freertos_secure_context_rebind(nx_freertos_secure_context_t *context, void *task)

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

备注

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.

参数:

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

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

返回:

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

nx_freertos_secure_context_t *nx_freertos_secure_context_for_task(void *task)

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

备注

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.

参数:

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

返回:

Prepared caller-owned metadata, or NULL when unauthorized.

void nx_freertos_secure_fault(nx_freertos_secure_fault_t fault)

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

备注

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.

参数:

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

struct nx_freertos_secure_context_t
#include <secure_context.h>

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

备注

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.

公共成员

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

备注

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.

类型定义

typedef struct nx_threadx_queue_waiter nx_threadx_queue_waiter_t

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

函数

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

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

备注

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.

参数:

  • startup – [in] Product initialization inside tx_application_define

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

返回:

CONTEXT or INVALID before entry; successful entry never returns

void nx_threadx_fail_stop(nx_result_t reason)

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

备注

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.

参数:

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

nx_result_t nx_threadx_external_tick_setup(uint32_t tick_hz)

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

备注

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.

参数:

  • tick_hz – [in] Exact immutable resolved kernel frequency

返回:

SUCCESS after binding a real bounded periodic IRQ source

bool nx_threadx_isr_allowed(void)

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

备注

Native has no hardware IRQ source and returns false.

返回:

True only in a privileged unmasked reviewed external IRQ

nx_result_t nx_threadx_notify_init(nx_threadx_notify_t *notification)

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

参数:

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

返回:

SUCCESS, INVALID, CONTEXT or IO

nx_wait_port_t nx_threadx_notify_port(nx_threadx_notify_t *notification)

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

备注

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.

参数:

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

返回:

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

nx_result_t nx_threadx_notify_destroy(nx_threadx_notify_t *notification)

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

参数:

  • notification – [inout] Live caller latch

返回:

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)

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

备注

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.

参数:

  • 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

返回:

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，并证明引用已撤离。

备注

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

参数:

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

  • deadline – [in] Absolute Core deadline or NX_DEADLINE_NEVER

返回:

SUCCESS, INVALID, CONTEXT, TIMEOUT or IO

nx_result_t nx_threadx_task_discard_before_scheduler(nx_threadx_task_t *task)

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

备注

This is prestart rollback, never runtime cancellation.

参数:

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

返回:

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)

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

备注

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

参数:

  • 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

返回:

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)

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

参数:

  • 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

返回:

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 发送；立即就绪优先于截止到期。

参数:

  • 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

返回:

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 接收；只在 SUCCESS 时修改输出。

参数:

  • 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

返回:

SUCCESS, INVALID, CONTEXT, TIMEOUT, OVERFLOW or IO

nx_result_t nx_threadx_queue_destroy(nx_threadx_queue_t *queue)

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

参数:

  • queue – [inout] Live caller control and storage

返回:

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

nx_result_t nx_threadx_queue_waiter_init(nx_threadx_queue_waiter_t *waiter)

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

参数:

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

返回:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_queue_waiter_destroy(nx_threadx_queue_waiter_t *waiter)

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

参数:

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

返回:

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)

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

备注

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

参数:

  • 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

返回:

SUCCESS, INVALID, CONTEXT or IO

nx_result_t nx_threadx_closable_queue_close(nx_threadx_closable_queue_t *queue)

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

参数:

  • queue – [inout] Live close-aware queue

返回:

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)

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

备注

A closed queue rejects sends without changing payload.

参数:

  • 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

返回:

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)

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

备注

Closed and empty returns CANCELLED; failure leaves output.

参数:

  • 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

返回:

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

nx_result_t nx_threadx_closable_queue_destroy(nx_threadx_closable_queue_t *queue)

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

参数:

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

返回:

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

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

备注

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.

函数

void nx_freertos_external_tick_setup(uint32_t tick_hz)

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

备注

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.

参数:

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

void nx_freertos_runtime_counter_start(void)

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

备注

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)

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

备注

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.

返回:

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

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)

等待调用者的权威谓词。

备注

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.

参数:

  • 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

返回:

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

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)