可选通用组件

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

bmp280.h

BMP280 校准与显式强制转换驱动。

作者 Nexus Team

函数

nx_result_t nx_bmp280_parse_calibration(const uint8_t *bytes, size_t length, nx_bmp280_calibration_t *calibration)

解析准确的 24 字节小端校准块。

参数:

  • bytes – [in] Register block beginning at 0x88

  • length – [in] Must be exactly 24

  • calibration – [out] Written only on success

返回:

SUCCESS or INVALID for length/zero pressure divisor

nx_result_t nx_bmp280_compensate(const nx_bmp280_calibration_t *calibration, uint32_t raw_temperature, uint32_t raw_pressure, nx_bmp280_sample_t *sample)

使用经过检查的整数运算补偿一个原始样本。

参数:

  • calibration – [in] Parsed calibration

  • raw_temperature – [in] Unsigned 20-bit ADC value

  • raw_pressure – [in] Unsigned 20-bit ADC value

  • sample – [out] Written only on success

返回:

SUCCESS, INVALID for malformed/overflow calibration or IO for disabled ADC sentinel/out-of-datasheet-range physical output

nx_result_t nx_bmp280_init(nx_bmp280_t *device, nx_bmp280_transport_port_t transport, nx_time_us_t deadline)

验证芯片 ID 并加载校准，不扫描设备。

备注

Task context; failure leaves initialized false and no borrow. Does not soft-reset the part or create a wait loop/task. Retry BUSY explicitly.

参数:

  • device – [out] Zero-initialized unused instance

  • transport – [in] Synchronous settled port and live monotonic clock

  • deadline – [in] Absolute deadline for all initialization accesses

返回:

SUCCESS, BUSY for NVM update, or transport/identity error

nx_result_t nx_bmp280_begin(nx_bmp280_t *device, nx_time_us_t deadline)

启动一次强制温度／压力转换。

备注

Task-only serialized driver owner; oversampling x1/x1.

参数:

  • device – [inout] Initialized non-measuring instance

  • deadline – [in] Absolute deadline covering conversion and reads

返回:

SUCCESS, BUSY, TIMEOUT or transport error

nx_result_t nx_bmp280_poll(nx_bmp280_t *device, nx_bmp280_sample_t *sample)

轮询转换，不使用隐式执行任务或阻塞延迟。

备注

Task-only. Every port call releases temporary buffers before return. BUSY retains device conversion state, never stack or caller buffers. After terminal failure, begin may retry; the external owner chooses policy.

参数:

  • device – [inout] Instance with a previously started conversion

  • sample – [out] Written only on SUCCESS

返回:

SUCCESS, BUSY while converting, TIMEOUT or transport error

void nx_bmp280_stop(nx_bmp280_t *device)

全部同步调用退出后停止软件使用。

备注

Does not power off or reset a physical part. Sensor-internal conversion can finish without accessing MCU storage. No MCU borrow remains.

参数:

  • device – [inout] Quiesced driver instance

struct nx_bmp280_transport_port_t
#include <bmp280.h>

同步、已结清的 SPI 事务端口。

备注

exchange always releases every TX/RX buffer before returning, including TIMEOUT/error. One CS interval covers all bytes; mode 0 or 3, 8-bit words, <=10 MHz. Caller serializes this device and its bus owner. Driver stack transactions never cross asynchronous borrowing boundaries.

公共成员

void *context
nx_result_t (*exchange)(void*, const uint8_t*, uint8_t*, size_t, nx_time_us_t deadline)
nx_clock_t clock
struct nx_bmp280_calibration_t
#include <bmp280.h>

由一个设备实例拥有的寄存器校准数据。

公共成员

uint16_t t1
int16_t t2
int16_t t3
uint16_t p1
int16_t p2
int16_t p3
int16_t p4
int16_t p5
int16_t p6
int16_t p7
int16_t p8
int16_t p9
struct nx_bmp280_sample_t
#include <bmp280.h>

仅成功转换／补偿时输出有效。

公共成员

int32_t centi_celsius
uint32_t pressure_pa
struct nx_bmp280_t
#include <bmp280.h>

显式设备上下文，不含 Board 引脚或自动采样任务。

公共成员

nx_bmp280_transport_port_t transport
nx_bmp280_calibration_t calibration
nx_time_us_t deadline
nx_time_us_t earliest_ready
bool initialized
bool measuring

bmp280_spi.h

固定 SPI 端点上的可选 BMP280 适配器。

作者 Nexus Team

函数

nx_bmp280_transport_port_t nx_bmp280_spi_transport(const nx_spi_endpoint_t *endpoint, nx_clock_t clock)

绑定真实轮询 SPI 端点作为能结清的传输端口。

参数:

  • endpoint – [in] Fixed endpoint kept alive throughout device use

  • clock – [in] Same monotonic domain as IO transfer deadlines

返回:

Narrow transport; no global discovery or CS selection

bus_owner.h

显式、有界的多生产者、单执行者适配器。

作者 Nexus Team

函数

nx_result_t nx_bus_owner_init(nx_bus_owner_t *owner, nx_owner_slot_t *slots, size_t capacity, nx_owner_guard_port_t guard, nx_owner_executor_port_t executor, nx_clock_t clock, const nx_wait_port_t *wake)

初始化尚未使用的 owner／slot 存储。

备注

Startup context; no task, worker, timer or heap is created.

参数:

  • owner – [out] Unused caller-owned adapter storage

  • slots – [in] Exact queue capacity, no maximum pool

  • capacity – [in] Number of slots, greater than zero

  • guard – [in] Live short exclusion port

  • executor – [in] Single real execution port

  • clock – [in] Same monotonic domain as request deadlines

  • wake – [in] Optional static executor notification, or NULL

返回:

SUCCESS or INVALID

nx_result_t nx_bus_owner_submit(nx_bus_owner_t *owner, nx_request_t *request, void *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)

建立请求链唯一的准入判定。

备注

Task multi-producer context. Free-slot admission and FIFO insertion use constant metadata work under the guard. An exhausted epoch permanently retires its slot. Deadline includes queue residence. Caller must not modify request, operation or buffers after admission. A notification error after admission cannot change SUCCESS to rejection; executor must recheck/pump periodically.

参数:

  • owner – [inout] Live accepting adapter

  • request – [inout] Prepared READY storage, retained until SETTLED

  • operation – [in] Executor-specific descriptor and payload storage

  • completion – [in] Optional static caller wake port, or NULL

  • ticket – [out] Stable cancellation identity, valid on SUCCESS

返回:

SUCCESS means ACCEPTED; rejection retains zero references

nx_result_t nx_bus_owner_cancel(nx_bus_owner_t *owner, nx_owner_ticket_t ticket)

通过稳定适配器存储提交取消。

备注

Task multi-producer context. No request pointer is accepted. Queued cancellation settles without starting. Active cancellation drains cooperatively; an irreversible operation may already have transferred data.

参数:

  • owner – [inout] Live adapter

  • ticket – [in] Previously accepted slot/epoch

返回:

SUCCESS when marked, STATE for stale/released identity

nx_result_t nx_bus_owner_service(nx_bus_owner_t *owner)

至多推进一个有界执行步骤。

备注

Task/explicit loop only. Consumers never service through wait. Keep calling during stop until idle; no callback creates a worker.

参数:

  • owner – [inout] Live adapter, called by its unique executor

返回:

SUCCESS for progress/idle, BUSY for provider wait/contention, or provider error while retaining ownership for continued recovery

void nx_bus_owner_stop(nx_bus_owner_t *owner)

关闭准入，并请求每个已接受操作停止。

备注

Task context. Executor must keep servicing/draining while producers wait/join. Stop is not settlement or storage reclamation.

参数:

  • owner – [inout] Live adapter

bool nx_bus_owner_idle(nx_bus_owner_t *owner)

检查执行及完成发布是否都已退出。

备注

Join producers and any wake publishers before reclaiming owner, slots, guard or notifications. No future submit/cancel is permitted.

参数:

  • owner – [inout] Live adapter

返回:

True if no queue/active/service publisher remains

struct nx_owner_guard_port_t
#include <bus_owner.h>

显式、有界元数据排斥端口。

备注

Task producer calls only. enter/leave must serialize all producers and the executor. Never hold this guard over start/service/cancel, waiting, payload copies or notification callbacks. State restores incoming interrupt mask when an architecture guard is used. Port storage stays live.

公共成员

void *context
uintptr_t (*enter)(void*)
void (*leave)(void*, uintptr_t)
struct nx_owner_executor_port_t
#include <bus_owner.h>

真实且唯一的执行所有者，注入时不依赖 OS。

start 返回 SUCCESS 后开始借用 operation，直到 service 返回 SUCCESS。BUSY 或任何 start 错误都必须不保留 operation 引用／硬件效果；部分启动后发生的错误必须改为接受操作，再通过 service 报告。service 返回 SUCCESS 必须证明全部硬件／IRQ／延后访问已停止，写入最终 result/count，并释放 operation。BUSY 仍保留借用。其他 service 错误保留所有权，并要求继续恢复／service。cancel 请求排空，绝不单独释放 operation。回调只在外部调度的执行者中运行，且必须位于适配器元数据临界区之外。

备注

terminal_authority selects providers that observe deadlines and latch their first terminal hardware fact themselves. Their final result survives late cancellation/publication. Other executors use adapter deadline/cancellation results. Queued deadlines always belong to the adapter.

公共成员

void *context
nx_result_t (*start)(void*, void *operation, nx_time_us_t deadline)
nx_result_t (*service)(void*, nx_result_t *result, size_t *transferred)
nx_result_t (*cancel)(void*)
bool terminal_authority
struct nx_owner_ticket_t
#include <bus_owner.h>

稳定控制身份；绝不解引用过期请求指针。

公共成员

size_t slot
uint64_t epoch
struct nx_owner_slot_t
#include <bus_owner.h>

调用者拥有的准确槽，连接在空闲链或 FIFO 链中；只能通过 owner init 初始化。

公共成员

nx_request_slot_t identity
void *operation
nx_wait_port_t completion
size_t next
bool cancel_requested
bool cancel_sent
struct nx_bus_owner_t
#include <bus_owner.h>

显式适配器状态；全部存储由外部应用供给。

公共成员

nx_owner_slot_t *slots
size_t capacity
size_t head
size_t tail
size_t active
size_t free_head
nx_owner_guard_port_t guard
nx_owner_executor_port_t executor
nx_clock_t clock
nx_wait_port_t wake
nx_result_t cancellation_result
bool accepting
bool servicing

clock_domain.h

显式时钟消费者与绑定 epoch 的排空控制。

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

类型定义

typedef struct nx_clock_domain nx_clock_domain_t

不透明提供者，由其特权所有者静态供给。

typedef struct nx_clock_lease nx_clock_lease_t

一个稳定、调用者拥有的消费者 token。

备注

Zero-initialize before first acquisition. On SUCCESS the provider borrows this exact object; do not copy, mutate or reclaim it until release succeeds. Internal fields are not application controls. A release is the provider’s final access, not proof that a peripheral has stopped. Release only after that consumer’s IRQ, DMA and observer drain.

枚举

enum nx_clock_power_mode_t

仅浅睡眠保持既有时钟／时间域。

取值：

enumerator NX_CLOCK_SHALLOW_SLEEP
enumerator NX_CLOCK_DEEP_STOP
enumerator NX_CLOCK_DYNAMIC_RUN

函数

nx_result_t nx_clock_domain_acquire(nx_clock_domain_t *domain, nx_clock_lease_t *lease)

无等待地取得一个允许准入的时钟消费者。

备注

Privileged Thread or configurable IRQ only; same CPU, saved-mask metadata guard. NMI/HardFault/SMP excluded. Capacity bounds token/alias scans. Token remains borrowed until successful release, even while admission is closed.

返回:

SUCCESS, BUSY for closed admission, EXHAUSTED for budget, or INVALID/STATE/CONTEXT with no retained token or effects

nx_result_t nx_clock_domain_release(nx_clock_domain_t *domain, nx_clock_lease_t *lease)

消费者排空后移除准确保留的 token。

备注

Same contexts as acquire. Copied tokens cannot release the original. There is no callback or last access after SUCCESS.

返回:

SUCCESS or INVALID/STATE/CONTEXT without removing a borrow

nx_result_t nx_clock_domain_close(nx_clock_domain_t *domain, nx_clock_barrier_t *control)

关闭准入并返回当前 epoch 控制身份。

备注

Serialized privileged Thread only. No waiting, cancellation, clock writes or implicit consumer shutdown. Idempotent in the same closed epoch; output must not alias live storage.

nx_result_t nx_clock_domain_quiescent(nx_clock_barrier_t control)

验证准入已关闭且保留消费者为零。

备注

Same CPU privileged Thread. This certifies only explicitly enrolled consumers. It does not authorize PLL reprogramming, suspend kernel Tick or change the Core deadline domain.

返回:

SUCCESS, BUSY while consumers remain, STATE for stale/open control, INVALID or CONTEXT; no state changes

nx_result_t nx_clock_domain_reopen(nx_clock_barrier_t control)

在新的准入 epoch 下重新开放已排空的时钟域。

备注

Serialized privileged Thread. Does not restart the clock or reinterpret existing deadlines. Actual cold clock changes additionally require all Tick/time providers stopped and a new explicit deadline domain; this API performs neither.

返回:

SUCCESS, BUSY, STATE, EXHAUSTED or CONTEXT without changes

struct nx_clock_lease
#include <clock_domain.h>

一个稳定、调用者拥有的消费者 token。

备注

Zero-initialize before first acquisition. On SUCCESS the provider borrows this exact object; do not copy, mutate or reclaim it until release succeeds. Internal fields are not application controls. A release is the provider’s final access, not proof that a peripheral has stopped. Release only after that consumer’s IRQ, DMA and observer drain.

公共成员

nx_clock_domain_t *owner
struct nx_clock_lease *next
uint64_t epoch
struct nx_clock_barrier_t
#include <clock_domain.h>

绑定 epoch 的关闭控制与静止证据。

备注

A value copy is allowed. This is not an authorization token or proof about unregistered consumers. Domain storage lives longer than every copy. A successful reopen invalidates all prior controls without resetting the epoch.

公共成员

nx_clock_domain_t *domain
uint64_t epoch

dp83848.h

显式 DP83848 身份、复位与链路观察机制。

作者 Nexus Team

宏定义

NX_DP83848_TI_ID
NX_DP83848_NS_ID
NX_DP83848_10_HALF
NX_DP83848_10_FULL
NX_DP83848_100_HALF
NX_DP83848_100_FULL

函数

nx_result_t nx_dp83848_probe(nx_dp83848_t *phy, nx_time_us_t deadline)

读取准确支持的身份；不匹配时绝不改用默认 PHY。

参数:

  • phy – [inout] Explicit MDIO face, address and expected supported model.

  • deadline – [in] Finite absolute MDIO clock deadline.

返回:

Success, UNSUPPORTED for identity mismatch, or MDIO error.

nx_result_t nx_dp83848_reset(nx_dp83848_t *phy, nx_time_us_t deadline)

有界 BMCR 软件复位，并观察自清除确认。

备注

Task-only finite absolute deadline; reset restraps the device and clears configured truth. This is not a GPIO, power or strap proof.

参数:

  • phy – [inout] Proved identity and caller-owned component state.

  • deadline – [in] Finite absolute MDIO clock deadline.

返回:

Success after real reset acknowledgement, or state/MDIO error.

nx_result_t nx_dp83848_configure(nx_dp83848_t *phy, const nx_dp83848_mode_t *mode, nx_time_us_t deadline)

启动显式协商或固定模式，不等待伪造链路。

备注

Task-only; identity must be proved. SUCCESS means registers configured, not autonegotiation complete. Failures retain configured=false.

参数:

  • phy – [inout] Proved identity, kept live through operations.

  • mode – [in] Explicit fixed mode or negotiation advertisement.

  • deadline – [in] Finite absolute MDIO clock deadline.

返回:

Success means configured registers; otherwise no configured truth.

对锁存低电平 BMSR 读取两次，并观察 DP83848 PHYSTS 的真实速率／双工状态。

备注

Task-only; output changes only on SUCCESS. up requires actual link and complete autonegotiation when selected. Protocol or remote fault does not invent speed/link. MAC application remains an external action.

参数:

  • phy – [inout] Probed and configured caller-owned component.

  • link – [out] Observed value, separate from component storage.

  • deadline – [in] Finite absolute MDIO clock deadline.

返回:

Success copies observed link; other results preserve output.

struct nx_dp83848_mode_t
#include <dp83848.h>

外部策略显式选择自动协商或固定模式。

公共成员

uint8_t advertisement
bool autonegotiation
bool full_duplex
uint16_t speed_mbps
struct nx_dp83848_t
#include <dp83848.h>

调用者拥有的 PHY 状态；不提供默认板级地址、reset GPIO 或执行任务。

备注

expected_id selects TI or NS model, ignoring revision nibble only. One task owner serializes this component and the shared MDIO port.

公共成员

const nx_mdio_port_t *mdio
uint32_t expected_id
uint8_t address
bool probed
bool configured
nx_dp83848_mode_t mode

file_flash.h

支持故障注入的 Native 持久文件 Flash 模型。

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

函数

nx_storage_status_t nx_file_flash_open(nx_file_flash_t *flash, const char *path, size_t size, size_t erase_size, size_t program_size)

打开使用独占锁的持久主机 Flash 模型。

备注

Task-only POSIX model. Does not qualify MCU Flash or actual power loss; existing file size mismatch is rejected without truncation.

参数:

  • flash – [out] Unused caller-owned storage

  • path – [in] Regular-file path; symlink traversal rejected

  • size – [in] Exact persistent byte size

  • erase_size – [in] Uniform erase block bytes

  • program_size – [in] Aligned program bytes, 1..256

返回:

OK or INVALID/IO; failed open retains no file descriptor

void nx_file_flash_close(nx_file_flash_t *flash)

全部存储使用者静止后关闭主机文件。

备注

No future port calls are permitted until explicit reopen.

参数:

  • flash – [inout] Open serialized model

void nx_file_flash_fail_after(nx_file_flash_t *flash, int64_t events)

设置显式模型中断边界。

备注

Zero simulates power-off until explicitly cleared.

参数:

  • flash – [inout] Serialized open model

  • events – [in] Programmed/erased bytes and sync attempts permitted; negative disables

struct nx_file_flash_t
#include <file_flash.h>

公共成员

int fd
nx_storage_port_t port
int64_t fail_after
uint64_t mutation_events

flash_storage.h

显式物理 Flash 区域适配器，不使用全局登记表。

作者 Nexus Team

函数

nx_result_t nx_flash_storage_bind(nx_flash_storage_adapter_t *adapter, nx_flash_region_t region, nx_time_us_t deadline, nx_storage_port_t *port)

绑定显式可写、擦除粒度统一的物理区域。

备注

Task-only, serialized caller. No region is reserved by the platform. Mixed sector geometries require another explicit storage adapter; this one rejects them. IO pulse settlement guarantees sync durability; no caller buffer survives a port call. Physical power-loss remains unqualified.

参数:

  • adapter – [out] Unused caller storage kept through all store calls

  • region – [in] Externally selected writable physical region

  • deadline – [in] Absolute whole-transaction deadline for mutations

  • port – [out] Narrow synchronous persistent port, valid on SUCCESS

返回:

SUCCESS or INVALID/PERMISSION/UNSUPPORTED geometry error

void nx_flash_storage_set_deadline(nx_flash_storage_adapter_t *adapter, nx_time_us_t deadline)

设置下一事务唯一的绝对修改截止时间。

备注

Caller serializes and sets this before open/save/recovery. Per-pulse timeouts cannot preempt hardware pulses; IO settles before return.

参数:

  • adapter – [inout] Bound adapter with no active store operation

  • deadline – [in] Absolute deadline in nx_time_now_us domain

struct nx_flash_storage_adapter_t
#include <flash_storage.h>

调用者拥有的适配器，不使用动态绑定或全局 token 查找。

公共成员

nx_flash_region_t region
nx_time_us_t deadline

log.h

实例内同步、有界日志接收端。

作者 Nexus Team

枚举

enum nx_log_level_t

结构化严重级别；在访问接收端前完成过滤。

取值：

enumerator NX_LOG_DEBUG
enumerator NX_LOG_INFO
enumerator NX_LOG_WARNING
enumerator NX_LOG_ERROR

函数

nx_result_t nx_log_init(nx_log_t *logger, nx_log_sink_port_t sink, nx_log_level_t minimum)

向任务暴露日志对象之前初始化。

参数:

  • logger – [out] Unused caller storage

  • sink – [in] Required bounded synchronous sink

  • minimum – [in] Minimum accepted severity

返回:

SUCCESS or INVALID

nx_result_t nx_log_write(nx_log_t *logger, nx_log_level_t level, const void *bytes, size_t length, nx_time_us_t deadline)

写入调用者字节，不进行隐式分配／格式化。

备注

Task multi-producer entry with nonblocking serialization. M0/M0+ use CPU-local saved-PRIMASK metadata exclusion and require privileged callers on one CPU. Sink calls run after restoring the incoming mask. This does not make NMI/HardFault or cross-security-domain writers valid. IRQ use is prohibited. Drop/retry policy remains with the external caller.

参数:

  • logger – [inout] Live instance

  • level – [in] Message severity

  • bytes – [in] Message bytes, borrowed only during this call

  • length – [in] Byte count; zero permits NULL

  • deadline – [in] Absolute deadline understood by sink

返回:

SUCCESS for filtered/sent bytes, BUSY for concurrent/recursive writes, STATE after stop, otherwise sink error

nx_result_t nx_log_flush(nx_log_t *logger, nx_time_us_t deadline)

刷新显式接收端，不创建后台执行任务。

备注

Same task/privilege/CPU domain as write.

参数:

  • logger – [inout] Live instance

  • deadline – [in] Absolute sink deadline

返回:

SUCCESS, BUSY, STATE, UNSUPPORTED or sink error

nx_result_t nx_log_stop(nx_log_t *logger)

拒绝新写入并检查接收端是否已退出。

备注

Task context. A stop caller may retry; no active sink call is forcibly cancelled. Join publishers before reclaiming logger/sink storage.

参数:

  • logger – [inout] Live instance; external users must eventually join

返回:

SUCCESS when no sink call is active, BUSY while draining

struct nx_log_sink_port_t
#include <log.h>

调用者注入的同步接收端。

备注

write/flush release every byte buffer before returning even on timeout/error; asynchronous/DMA sinks require their own settled adapter. Calls are bounded by absolute monotonic deadlines, in task context. No sink discovery, allocation, formatting, worker or global error handler exists.

公共成员

void *context
nx_result_t (*write)(void*, nx_log_level_t, const void*, size_t, nx_time_us_t deadline)
nx_result_t (*flush)(void*, nx_time_us_t deadline)
struct nx_log_t
#include <log.h>

日志存储属于调用者；共享不可变端口在初始化时复制。

公共成员

nx_log_sink_port_t sink
nx_log_level_t minimum
uint32_t busy
uint32_t stopped

modbus_rtu.h

有界 Modbus RTU 核心与显式 RS485 端口。

作者 Nexus Team

宏定义

NX_MODBUS_ADU_MAX
NX_MODBUS_REGISTER_MAX

枚举

enum nx_modbus_register_result_t

取值：

enumerator NX_MODBUS_OK
enumerator NX_MODBUS_ILLEGAL_ADDRESS
enumerator NX_MODBUS_ILLEGAL_VALUE
enumerator NX_MODBUS_DEVICE_FAILURE
enumerator NX_MODBUS_DEVICE_BUSY

取值：

函数

uint16_t nx_modbus_crc16(const uint8_t *bytes, size_t length)

对调用者字节计算标准 Modbus CRC16。

参数:

  • bytes – [in] Input, NULL only when length is zero

  • length – [in] Byte count

返回:

CRC16; zero for invalid NULL input with nonzero length

bool nx_modbus_rtu_init(nx_modbus_rtu_t *server, const nx_modbus_config_t *config)

初始化尚未使用或完全静止的协议实例。

备注

Task-only; configuration is copied, contexts stay live. First direction(false) failure is reported; no worker or UART is created. Reinitializing a faulted TX borrow is prohibited; stop/recover it first.

参数:

  • server – [out] Caller-owned storage, no existing transport borrow

  • config – [in] Explicit register/RS485 ports and finite budgets

返回:

True when initialized into RX silence acquisition

bool nx_modbus_rtu_feed(nx_modbus_rtu_t *server, uint8_t byte, uint64_t arrival_us)

输入外部添加时间戳的 UART 字节。

备注

Task-only. IRQ queues are external, bounded and explicit; queue overflow must call rx_error. No live UART discovery or ISR callback.

参数:

  • server – [inout] Initialized instance, serialized by caller

  • byte – [in] Wire byte

  • arrival_us – [in] Capture timestamp in port monotonic domain

返回:

True if byte joined the frame, false for discard/error

bool nx_modbus_rtu_poll(nx_modbus_rtu_t *server, uint64_t now_us)

推进 RTU 静默间隔与有界同步 RS485 响应。

备注

Task-only, explicit external scheduling. RS485 drain must observe the final stop bit. Failed abort retains TX bytes and asserted DE in LINK_FAULTED; keep instance/port alive until successful recover or stop.

参数:

  • server – [inout] Initialized instance, single execution owner

  • now_us – [in] Snapshot in the same monotonic domain

返回:

True for successful progress, false for clock/transport error

void nx_modbus_rtu_rx_error(nx_modbus_rtu_t *server, uint64_t now_us)

丢弃发生错误或溢出的接收帧。

备注

Task-only. Does not discard a retained faulted TX borrow.

参数:

  • server – [inout] Initialized serialized instance

  • now_us – [in] Error timestamp in port’s monotonic domain

bool nx_modbus_rtu_recover(nx_modbus_rtu_t *server)

结清保留的 TX，再恢复接收静默判定。

备注

Explicit task maintenance action, no fabricated recovery.

参数:

  • server – [inout] Initialized serialized instance with live ports

返回:

True only after actual port abort/drain and receive direction

bool nx_modbus_rtu_stop(nx_modbus_rtu_t *server)

回收协议存储之前先使端口结清。

备注

Stop future feed/poll users first. No future use except explicit initialization is allowed after successful stop.

参数:

  • server – [inout] Initialized, exclusively owned instance

返回:

True when no transport borrow remains and instance is stopped; false preserves fault state, TX bytes and all port lifetime obligations

struct nx_modbus_registers_t
#include <modbus_rtu.h>

公共成员

void *context
nx_modbus_register_result_t (*read)(void*, uint16_t, uint16_t, uint16_t*)
nx_modbus_register_result_t (*authorize_write)(void*, uint16_t, uint16_t, const uint16_t*)
nx_modbus_register_result_t (*write_atomic)(void*, uint16_t, uint16_t, const uint16_t*)
struct nx_modbus_rs485_port_t
#include <modbus_rtu.h>

公共成员

void *context
uint64_t (*now_us)(void*)
bool (*direction)(void*, bool transmit)
bool (*write)(void*, const uint8_t*, size_t, uint64_t deadline_us)
bool (*drain)(void*, uint64_t deadline_us)
bool (*abort_and_settle)(void*, uint64_t deadline_us)
struct nx_modbus_counters_t
#include <modbus_rtu.h>

公共成员

uint64_t frames
uint64_t accepted
uint64_t crc_errors
uint64_t timing_errors
uint64_t overflows
uint64_t exceptions
uint64_t broadcasts
uint64_t tx_errors
uint64_t clock_errors
struct nx_modbus_config_t
#include <modbus_rtu.h>

公共成员

uint8_t address
uint32_t baudrate
uint8_t bits_per_character
uint32_t tx_timeout_us
uint32_t abort_timeout_us
nx_modbus_registers_t registers
nx_modbus_rs485_port_t port
struct nx_modbus_rtu_t
#include <modbus_rtu.h>

公共成员

nx_modbus_config_t config
nx_modbus_counters_t counters
nx_modbus_link_state_t state
uint32_t t1_5_us
uint32_t t3_5_us
uint64_t last_byte_us
uint64_t last_event_us
uint16_t rx_length
uint16_t tx_length
uint8_t rx[NX_MODBUS_ADU_MAX]
uint8_t tx[NX_MODBUS_ADU_MAX]
uint16_t values[NX_MODBUS_REGISTER_MAX]
bool initialized
bool clock_started

owner_observer.h

显式 owner 推进诊断，不含默认状态。

作者 Nexus Team

函数

nx_result_t nx_owner_observer_bind(nx_owner_observer_t *observer, nx_bus_owner_t *owner)

绑定已初始化的准确 owner，不创建工作。

参数:

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

  • owner – [inout] Initialized stable owner, no concurrent lifecycle.

返回:

SUCCESS or INVALID/STATE, no service or borrow on rejection.

nx_result_t nx_owner_observer_service(nx_owner_observer_t *observer, nx_time_us_t now, nx_owner_observation_t *out)

准确执行一次真实 service 步骤并复制诊断。

备注

Clock reversal never blocks drain or rewrites its result. Snapshot uses the existing guard outside hardware service. No callback, slot scan or worker occurs under that guard. Quarantine and elapsed deadlines never release a loan. Output also excludes accepted descriptors and payloads. Only the owner/slot control spans are checked here.

参数:

  • observer – [inout] Bound sidecar on the unique executor.

  • now – [in] Monotonic timestamp, independent of service result.

  • out – [out] Distinct stable output, no retained references.

返回:

Actual service result; invalid bindings reject beforehand.

void nx_owner_observer_detach(nx_owner_observer_t *observer)

仅撤销观察绑定，不拆除 owner 或借用。

参数:

  • observer – [inout] Caller-serialized sidecar, no remaining readers.

struct nx_owner_observation_t
#include <owner_observer.h>

已复制的 service 事实，不含 request、payload 或 slot 引用。

公共成员

nx_result_t service_result
nx_result_t diagnostic_result
nx_time_us_t observed_at
nx_time_us_t max_gap
uint32_t calls
uint32_t busy
uint32_t errors
uint32_t quarantines
uint32_t clock_errors
nx_owner_ticket_t active
nx_request_state_t active_state
bool has_active
bool idle
struct nx_owner_observer_t
#include <owner_observer.h>

调用者显式选择的附加状态；不向默认 owner 增加指针。

备注

Exact owner, slots and guard remain live until detach and all observer calls exit. The same unique owner executor calls this wrapper; producer calls retain the owner guard. Never reinitialize/replace the bound owner underneath it.

公共成员

nx_bus_owner_t *owner
nx_time_us_t last_observed
nx_owner_observation_t observation
bool observed

spi_async_owner.h

一个显式总线的可选有限异步 SPI 执行者。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_spi_async_owner_executor_port(nx_spi_async_owner_executor_t *executor, const nx_spi_port_t *port)

将具备异步能力的总线绑定到显式 owner 执行者。

备注

Startup/task context. Operations use nx_spi_owner_operation_t endpoints on this bus only; membership is checked before admission. No polling fallback is selected. Controller and executor remain live through drain, control acknowledgement and observer exit. QUARANTINED retains both buffer loans. Hardware stop and IRQ/notification destruction are explicit external steps after owner shutdown, not part of this bind.

参数:

  • executor – [out] Fresh storage with no previous outstanding loans.

  • port – [in] Initialized controller exclusively owned by this executor; direct clients and other owners must quiesce.

返回:

Valid executor port, or a zero port for incomplete methods.

struct nx_spi_async_owner_executor_t
#include <spi_async_owner.h>

独立于轮询适配器的准确异步存储。

备注

inner is a private publication object. Its borrow must end before the outer owner publishes SETTLED. No queue, payload copy, allocation or hidden worker is created.

公共成员

const nx_spi_port_t *port
nx_spi_request_t inner
bool pending

spi_owner.h

有界 owner 适配器的显式轮询 SPI 执行者。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_spi_owner_executor_port(nx_spi_owner_executor_t *executor, const nx_spi_port_t *port)

绑定显式同步 SPI 执行适配器。

备注

start executes a real CPU-active polling transaction and releases all IO buffers before returning. Owner service later publishes its caller-owned request. Polling cannot be preempted by another task’s cancel; once the polling call returns, its result is final despite later cancellation or publication delay. Do not claim IRQ/DMA mode or low-CPU asynchronous hardware execution. Endpoints must prove their controller identity before any wire effect; distinct chip selects on this controller remain valid. The controller and executor outlive owner shutdown and all observers.

参数:

  • executor – [out] Fresh storage with no outstanding operation

  • port – [in] Controller exclusively serviced by this owner

返回:

Port for nx_bus_owner_init, or a zero port for invalid input

struct nx_spi_owner_operation_t
#include <spi_owner.h>

调用者拥有的 SPI 事务描述符，借用保持到 SETTLED。

公共成员

const nx_spi_endpoint_t *endpoint
const uint8_t *tx
uint8_t *rx
size_t length
struct nx_spi_owner_executor_t
#include <spi_owner.h>

准确轮询执行者存储，不复制载荷或设置队列。

公共成员

const nx_spi_port_t *port
nx_result_t result
size_t transferred
bool pending

storage.h

使用显式窄端口的双 bank 持久 blob 存储。

作者 Nexus Team

宏定义

NX_STORAGE_HEADER_SIZE

枚举

enum nx_storage_status_t

存储错误显式暴露重试／重开／恢复决策。

取值：

enumerator NX_STORAGE_OK
enumerator NX_STORAGE_INVALID
enumerator NX_STORAGE_IO
enumerator NX_STORAGE_CORRUPT
enumerator NX_STORAGE_NO_SPACE
enumerator NX_STORAGE_NOT_FOUND
enumerator NX_STORAGE_UNSUPPORTED

函数

nx_storage_status_t nx_storage_open(nx_storage_t *storage, const nx_storage_port_t *port, size_t offset, size_t bank_size, void *workspace, size_t workspace_bytes)

打开／恢复两个外部供给、擦除粒度统一的 bank。

备注

Task-only bounded scan over both bank payloads. Workspace remains borrowed by the instance through every subsequent load/save call.

参数:

  • storage – [out] Unused or quiesced instance, no concurrent calls

  • port – [in] Persistent settled port, may be storage’s existing port

  • offset – [in] Erase-aligned start within port region

  • bank_size – [in] Each bank’s erase-aligned byte size

  • workspace – [in] Caller buffer, disjoint from instance/payload

  • workspace_bytes – [in] At least max(32, port.program_size)

返回:

OK for recovered/empty store, CORRUPT for ambiguous or only invalid committed generations, IO/INVALID for port/geometry failures

nx_storage_status_t nx_storage_load(nx_storage_t *storage, void *output, size_t *size)

加载并验证最新提交的完整 blob。

备注

Output bytes valid only on OK; failure may partially write output. No destination pointer is retained after returning.

参数:

  • storage – [inout] Open instance, exclusively owned for this call

  • output – [out] Destination; NULL requests only required size

  • size – [inout] Input capacity, output payload/required bytes

返回:

OK, NOT_FOUND, NO_SPACE, CORRUPT or IO/INVALID

nx_storage_status_t nx_storage_save(nx_storage_t *storage, const void *data, size_t size)

将完整 blob 提交到非活动 bank。

备注

Marker is programmed last after sync. Failed mutation keeps the previous bank and requires reopen; ambiguous marker failure can mean the new blob committed. Product owns migration/authentication/recovery policy.

参数:

  • storage – [inout] Open exclusively owned instance

  • data – [in] Payload disjoint from workspace, borrowed during call

  • size – [in] Payload bytes; zero permits NULL

返回:

OK, NO_SPACE, INVALID or underlying port error

size_t nx_storage_capacity(const nx_storage_t *storage)

查询可用 blob 容量，不访问硬件。

参数:

  • storage – [in] Geometry-established instance, or NULL

返回:

Payload bytes per bank, or zero for invalid geometry

struct nx_storage_port_t
#include <storage.h>

同步且已结清的持久 Flash 端口。

备注

Task-only; caller serializes every operation. Offsets are byte-relative to the supplied region. program changes only 1 to 0 in complete aligned program units; erase uses complete uniform erase units. sync makes earlier successful writes durable. Errors can change a subset of addressed units, but never retain caller buffers after returning. RAM is a model, not a persistent implementation. Product owns the region/layout and power policy.

公共成员

void *ctx
size_t size
size_t erase_size
size_t program_size
nx_storage_status_t (*read)(void*, size_t, void*, size_t)
nx_storage_status_t (*program)(void*, size_t, const void*, size_t)
nx_storage_status_t (*erase)(void*, size_t, size_t)
nx_storage_status_t (*sync)(void*)
struct nx_storage_t
#include <storage.h>

实例元数据与调用者确定容量的工作区。

备注

Two independently erasable banks commit whole blobs. No heap, global registry, maximum pool or default product reservation. Wire format v1 is explicit little-endian and CRC-protected, not authenticated. Keep instance, port context and workspace alive through close/quiescence. A mutating I/O error invalidates opened; reopen to establish which commit actually survived.

公共成员

nx_storage_port_t flash
size_t offset
size_t bank_size
size_t payload_offset
uint64_t generation
size_t payload_size
int active_bank
bool opened
uint8_t *workspace
size_t workspace_bytes

uart_owner.h

显式 IRQ UART 执行者与私有提供者请求结清。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_uart_owner_executor_port(nx_uart_owner_executor_t *executor, const nx_uart_port_t *uart)

将 UART 控制器绑定到一个显式 service 执行者。

备注

Startup/task context. Controller and executor remain alive through owner stop/drain and external observer quiescence. Direct UART users must not share this controller. Queued time belongs to the bus owner; after start the UART’s first terminal TC/error/cancel/deadline fact is authoritative. cancel observes provider completion/deadline before asking it to abort. Failed drain keeps both requests QUARANTINED; service must continue during recovery. Outer SETTLED never precedes inner acquire-observed SETTLED and pointer detach. The application separately stops hardware and RX consumers only after all owner operations and controls quiesce.

参数:

  • executor – [inout] Unused caller-owned storage, no concurrent calls

  • uart – [inout] Initialized UART exclusively owned by this executor

返回:

Port for nx_bus_owner_init, or an invalid zero port for NULL

struct nx_uart_owner_operation_t
#include <uart_owner.h>

调用者拥有的 TX 载荷描述符，借用保持到外层 SETTLED。

公共成员

const uint8_t *data
size_t length
struct nx_uart_owner_executor_t
#include <uart_owner.h>

一个执行者准确且私有的提供者请求。

备注

inner is a separate publication object, not another outer queue or caller admission. Only this executor accesses it; producers retain their outer request and payload until the bus owner publishes outer SETTLED. No buffer copy, heap, worker or pool. Never pass inner to application observers.

公共成员

const nx_uart_port_t *port
nx_uart_tx_request_t inner
bool pending

user_io_broker.h

由内核调用的窄接口用户 GPIO 消息合同。

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

类型定义

typedef struct nx_user_io_broker nx_user_io_broker_t

broker 与持久内核调用存储保持提供者私有。

typedef struct nx_user_io_call nx_user_io_call_t

枚举

enum nx_user_io_constants

此消息 ABI 仅允许标量 GPIO 操作。

取值：

enumerator NX_USER_IO_ABI
enumerator NX_USER_GPIO_READ
enumerator NX_USER_GPIO_WRITE

函数

nx_user_io_result_t nx_user_io_broker_gpio(nx_user_io_broker_t *broker, nx_user_io_call_t *call, const nx_user_io_message_t *message, nx_user_io_reply_t *reply)

通过可信网关执行一个标量 GPIO 消息。

备注

Kernel-invoked privileged Thread with incoming masks clear, one serialized broker executor. Principal comes from the configured trusted kernel identity port. Pin both validated memory ranges before any GPIO call; snapshot input once, copy an initialized reply. Kernel call storage is zero-initialized outside user RAM and must outlive retained pins. No OS SVC/MPU/TZ wiring or user privilege elevation is provided by this component.

返回:

REJECTED has accepted=false, no pin/effect. ACCEPTED may already be detached or retain cleanup after a failure.

nx_user_io_result_t nx_user_io_broker_gpio_finish(nx_user_io_broker_t *broker, nx_user_io_call_t *call)

重试保留的清理，不读取用户存储或重放 I/O。

备注

Same privileged serialized kernel owner, incoming masks clear. Successful unpin follows actual provider/observer drain; a failed unpin keeps memory, call slot and identity retained. Does not imply that a previously performed GPIO write can be reversed.

struct nx_user_io_message_t
#include <user_io_broker.h>

来自不可信方的已复制消息；身份绝不取自用户输入。

备注

No arbitrary port, MMIO, callback, slot or principal pointer. reserved words must be zero. WRITE has read_mask=0 and disjoint set/reset masks. READ has zero set/reset masks and a positive authorized read_mask. Caller keeps storage immutable until the gateway completes or retains its pin.

公共成员

uint32_t abi
uint32_t device
uint32_t operation
uint32_t set_mask
uint32_t reset_mask
uint32_t read_mask
uint32_t reserved[2]
struct nx_user_io_reply_t
#include <user_io_broker.h>

完整初始化的复制结果；错误或 WRITE 时 value 为零。

公共成员

uint32_t result
uint32_t value
struct nx_user_io_result_t
#include <user_io_broker.h>

区分准入、保留清理责任与可能发生的效果。

备注

accepted means at least one memory pin was acquired. On retained=true the exact kernel call slot and user address space remain borrowed. device_effect_possible is set before a WRITE provider call; an error cannot authorize replay. result describes admission/device execution; cleanup_result separately describes the most recent release attempt. This is software responsibility, not physical pin evidence.

公共成员

nx_result_t result
nx_result_t cleanup_result
bool accepted
bool retained
bool device_effect_possible