类型化 I/O：设备与执行合同

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

model.h、spi_dma_model.h 和 rtc_lptim_model.h 中的 Native 模型控制供主机测试使用，不建立 MCU 硬件支持或设备探测能力。可选接口只描述被选择的合同；接口存在并不代表每个 provider 都支持。

adc.h

已审查的 ADC 单次采样与低速轮询扫描。

作者 Nexus Team

函数

nx_result_t nx_adc_port_info(const nx_adc_port_t *port, nx_adc_info_t *info)

查询固定、已审查的 ADC 序列与原始计数格式。

参数:

  • port – [in] 单次或低速扫描 provider。

  • info – [out] 分辨率、声明的参考值及序列长度。

返回:

成功或 INVALID。

nx_result_t nx_adc_port_sequence_info(const nx_adc_port_t *port, nx_adc_sequence_info_t *info)

读取固定通道顺序与完整扫描的时序事实。

参数:

  • port – [in] 已初始化且支持时序信息的 provider。

  • info – [out] 冷态只读事实；不会启动采集。

返回:

成功或 INVALID/STATE/UNSUPPORTED。

nx_result_t nx_adc_port_attach_observer(const nx_adc_port_t *port, nx_adc_observer_t *observer)

采集开始前附加可选观察者存储。

备注

分离或回收前，先停止并等待相关访问者退出。没有隐藏分配；轮询及有限模式无需观察存储。

参数:

  • port – [in] 已初始化的连续采集 provider，由一个任务所有者控制。

  • observer – [inout] 已初始化且稳定的调用方存储；传入 NULL 表示分离。provider 在启动时验证精确的 stream 数量。

返回:

成功或 BUSY/CONTEXT/UNSUPPORTED。

nx_result_t nx_adc_port_block_observation(const nx_adc_port_t *port, const nx_stream_block_t *block, nx_adc_observation_t *observation)

查询一个存活消费者借用的软件完成记录。

参数:

  • port – [in] 同一个稳定且支持观察的 provider。

  • block – [in] 同一 stream 当前已取得的不可变 block。

  • observation – [out] 复制的 epoch、序号、观察时间和间隙标志。这绝不是硬件采样孔径时间戳。

返回:

成功或 INVALID/STATE/UNSUPPORTED；拒绝时输出不变。

nx_result_t nx_adc_port_sample(const nx_adc_port_t *port, uint16_t *samples, size_t capacity, nx_time_us_t deadline, size_t *count)

通过有界轮询采样固定单次／扫描序列。

备注

采集持续占用 CPU，且仅限任务上下文。参考电压、采样误差和最大速率需要实物资格验证。

参数:

  • port – [inout] 唯一执行所有者；通道及采样时间配置固定。

  • samples – [out] 按配置通道顺序排列的原始计数。

  • capacity – [in] 样本容量至少为 channel_count。

  • deadline – [in] 时钟域中的绝对 deadline。

  • count – [out] 完整有效样本；其余输出保持不变。

返回:

成功或 INVALID/BUSY/TIMEOUT/IO；返回前完成中止及排空。不保留缓冲区，也不承诺 DMA、触发或流式能力。

nx_result_t nx_adc_port_stream_start(const nx_adc_port_t *port, nx_stream_t *stream, uint32_t trigger_hz)

使用调用者存储启动选定的触发／块采集。

备注

block 包含按通道顺序排列的原生 uint16_t 原始计数。容量及长度必须为完整扫描的整数倍；DMA 域、对齐和物理速率需要独立证据。

参数:

  • port – [in] 支持触发及 block 的 provider，由一个任务执行者控制。

  • stream – [inout] 已初始化、供消费者不可变访问的 block 机制。

  • trigger_hz – [in] 请求的完整扫描速率，为正值；超出所声明定时器或 ADC 能力的速率由 provider 拒绝。

返回:

缓冲区准入前返回成功或 INVALID/BUSY/UNSUPPORTED。

nx_result_t nx_adc_port_stream_stop(const nx_adc_port_t *port)

停止触发与内存写入源，不撤销消费者借用。

备注

消费者的 READY/BORROWED block 仍须排空或释放。

参数:

  • port – [in] 同一个采集执行者；BUSY 时保留存储。

返回:

成功证明源已分离；BUSY 保留生产者存储；仅支持轮询的 provider 返回 UNSUPPORTED。

nx_result_t nx_adc_port_stream_service(const nx_adc_port_t *port)

消费者排空后，显式恢复离散块采集。

备注

不会创建任务、重试或隐藏的重新 arm。block 模式明确说明触发间隙；连续无间隙捕获需要另外声明的硬件能力及资格验证。

参数:

  • port – [in] 与 start 和 stop 相同的唯一任务执行者。

返回:

引擎已 arm 时返回成功；源排空或空闲 block 背压期间返回 BUSY；采集停止后返回 STATE。

nx_result_t nx_adc_port_attach_wake(const nx_adc_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

检查发布者 IRQ 优先级后，附加可选提示接收端。

备注

先锁存 block 或错误条件，再通知。回收旧 sink 存储前，停止并等待发布者及等待者退出。

参数:

  • port – [in] 已初始化且支持 block 的 provider，由一个任务执行者控制。

  • wake – [in] 不可变的借用目标；NULL 表示分离。

  • syscall_ceiling – [in] 可选的额外未移位内核安全优先级数值下限；不得削弱生成策略。PRIMASK 内核目标要求为零。不调用内核时忽略。

返回:

成功或 CONTEXT/STATE/PERMISSION/UNSUPPORTED。

struct nx_adc_info_t
#include <adc.h>

原始计数事实；标称 Vref 不是经过校准的物理测量。

公共成员

uint8_t resolution_bits
uint32_t reference_mv
size_t channel_count
struct nx_adc_sequence_info_t
#include <adc.h>

选定模式下不可变的完整扫描时序事实。

备注

sample_times 按通道顺序保存 sample_cycles 的采样码。scan_cycles 包含各通道的采样及转换周期。时钟声明和周期数描述调度，不建立电气精度或采样孔径时间戳的事实。数组在 provider 整个生命周期内保持有效。

公共成员

const uint8_t *channels
const uint8_t *sample_times
const uint16_t *sample_cycles
size_t channel_count
size_t sample_code_count
uint32_t adc_clock_hz
uint32_t timer_clock_hz
uint32_t scan_cycles
uint16_t conversion_cycles
struct nx_adc_ops_t
#include <adc.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*info)(const void *context, nx_adc_info_t *info)
nx_result_t (*sample)(void *context, uint16_t *samples, size_t capacity, nx_time_us_t deadline, size_t *count)
nx_result_t (*stream_start)(void *context, nx_stream_t *stream, uint32_t trigger_hz)
nx_result_t (*stream_stop)(void *context)
nx_result_t (*stream_service)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
nx_result_t (*sequence_info)(const void *context, nx_adc_sequence_info_t *info)
nx_result_t (*attach_observer)(void *context, nx_adc_observer_t *observer)
nx_result_t (*block_observation)(const void *context, const nx_stream_block_t *block, nx_adc_observation_t *observation)
struct nx_adc_port
#include <adc.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_adc_ops_t *ops
void *context

adc_format.h

明确的整数采样表示与扫描布局。

作者 Nexus Team

枚举

enum nx_adc_encoding_t

整数编码；不隐式转换电压或浮点数。

取值：

enumerator NX_ADC_ENCODING_UNKNOWN
enumerator NX_ADC_UNSIGNED
enumerator NX_ADC_TWOS_COMPLEMENT
enum nx_adc_byte_order_t

显式声明字节序，与执行代码的 CPU 无关。

取值：

enumerator NX_ADC_BYTE_ORDER_UNKNOWN
enumerator NX_ADC_LITTLE_ENDIAN
enumerator NX_ADC_BIG_ENDIAN
enum nx_adc_group_t

硬件转换组；描述性事实不会启用该组。

取值：

enumerator NX_ADC_GROUP_UNKNOWN
enumerator NX_ADC_REGULAR
enumerator NX_ADC_INJECTED
enum nx_adc_trigger_t

触发身份不是采样孔径时间戳。

取值：

enumerator NX_ADC_TRIGGER_UNKNOWN
enumerator NX_ADC_TRIGGER_SOFTWARE
enumerator NX_ADC_TRIGGER_TIMER
enumerator NX_ADC_TRIGGER_EVENT

函数

nx_result_t nx_adc_format_validate(const nx_adc_format_t *format)

验证完整的不可变布局，不读取采样存储。

参数:

  • format – [in] 可读、自然对齐的布局，由调用方保持有效。

返回:

SUCCESS 或 INVALID；不分配、不访问硬件，也不保留借用。

nx_result_t nx_adc_format_decode(const nx_adc_format_t *format, const void *samples, size_t bytes, size_t scan, size_t channel, int64_t *value)

从调用者拥有或消费者已取得的扫描数据中解码一个整数。

备注

不保留任何指针。输入、输出或 format 重叠，以及地址回绕的范围，均在访问前拒绝。样本装载的工作量有界，为 1..4 字节。此操作既不转换为经过校准的工程单位，也不与活跃生产者同步；消费者负责完成该访问的同步／退出等待。

参数:

  • format – [in] 有效且不可变、通道布局一致的扫描描述。

  • samples – [in] 可读存储；必须先等待所有生产者或 DMA 访问结束。

  • bytes – [in] 为 scan_stride 的正整数倍，包含填充。

  • scan – [in] 从零开始的完整扫描索引。

  • channel – [in] 按 provider 顺序从零开始的通道位置。

  • value – [out] 独立且已对齐的输出，被拒绝时保持不变。

返回:

SUCCESS 或 INVALID；全部 32 位无符号或有符号原始值均可容纳于 int64_t。

struct nx_adc_format_t
#include <adc_format.h>

各通道存储格式一致的不可变整数布局，与 ADC 接口独立。

备注

storage_bytes 为 1..4；significant_bits 在该存储范围内为 1..32。lsb_bits 表示丢弃的低位，不是算术缩放因子。sample_stride 和 scan_stride 以字节计，包含显式填充。channel_count 保持 provider 另行声明的通道顺序。软件触发使用 identity0；硬件触发标识是非零、装配内局部的 ID，绝不是地址或物理时序承诺。group 或 trigger 声明描述 provider 已支持的模式；验证布局不会为设备增加支持，也不会配置设备。

公共成员

size_t sample_stride
size_t scan_stride
uint32_t trigger_identity
uint16_t channel_count
uint8_t storage_bytes
uint8_t significant_bits
uint8_t lsb_bits
nx_adc_encoding_t encoding
nx_adc_byte_order_t byte_order
nx_adc_group_t group
nx_adc_trigger_t trigger

adc_group.h

可选的有限完整序列整数 ADC 采集。

作者 Nexus Team

函数

nx_result_t nx_adc_group_prepare(nx_adc_group_request_t *request, void *frames, size_t bytes, size_t frame_count, nx_time_us_t deadline)

准备调用者存储，不访问硬件，也不保留借用。

备注

请求与帧存储彼此独立。准备过程不读取样本字节，也不证明 DMA 域或芯片模式成立。复用前必须等待所有先前的观察者退出。拒绝 NX_DEADLINE_NEVER。

参数:

  • request – [inout] 已初始化为 READY，或已完全消费的 SETTLED 存储。

  • frames – [out] 已对齐、非空的原始输出，包含显式填充。

  • bytes – [in] 长度为正且地址不回绕的范围；由 provider 验证精确布局。

  • frame_count – [in] 正的完整帧数，不是原始 rank 数。

  • deadline – [in] 平台单调时间域中的有限绝对 deadline。

返回:

返回 SUCCESS 或 INVALID/STATE；被拒绝的请求保持不变。

nx_result_t nx_adc_group_submit(const nx_adc_group_port_t *port, nx_adc_group_request_t *request)

由唯一所有者接受并启动一次选定的有限采集。

备注

请求被接受后，调用方不得修改描述符；只有以 acquire 语义观察到 SETTLED 后，才能访问帧存储。预转换可能写入整个范围，但不会将预转换数据发布为有效数据。准入后的 arm 失败仍保留借用，直到实际排空。没有可信完成时间戳时，首次在 deadline 时刻或之后观察到完成即为 TIMEOUT。单帧 injected 配置有意防止第二次触发及 JDR 覆盖。

参数:

  • port – [in] 已初始化的选中接口，其保留配置事实不可变。

  • request – [inout] 精确处于 READY 的描述符及独占可写范围。

返回:

SUCCESS 表示已 ACCEPTED，包括立即进入 SETTLED 的失败。其他结果表示拒绝，不保留指针，也不留下新的残余效果。

nx_result_t nx_adc_group_cancel(const nx_adc_group_port_t *port, nx_adc_group_request_t *request)

开始取消，不撤销已接受的存储借用。

备注

最先出现的终结故障、取消或超时保持最终决定权。

参数:

  • port – [in] 同一个稳定的选中接口，并由串行化的特权任务调用。

  • request – [inout] 当前已接受且仍然存活的精确请求。

返回:

SUCCESS 表示开始或观察到取消，不代表已经 SETTLED。

nx_result_t nx_adc_group_service(const nx_adc_group_port_t *port)

推进有界的预转换、采集和排空，不包含隐藏等待。

备注

只要各源、ADC、DMA 或 IRQ 仍可能引用请求或输出，就不得回收它们。QUARANTINED 请求仍归当前所有者持有，可重试排空。

参数:

  • port – [in] 同一个稳定的选中接口，并由串行化的特权任务调用。

返回:

推进或结算后返回 SUCCESS；排空尚未完成时返回 BUSY；或返回错误并保留恢复责任。

nx_result_t nx_adc_group_stop(const nx_adc_group_port_t *port)

关闭准入，证明请求的源已排空后才报告空闲。

备注

停止不等于冷关闭：引脚、公共时钟、内部源使能和 provider 存储仍被保留，直到平台完成退出等待后关闭。

参数:

  • port – [in] 同一个稳定的选中接口，并由串行化的特权任务调用。

返回:

仅在最终请求分离后返回 SUCCESS；BUSY/IO 保留全部租约。

nx_result_t nx_adc_group_info(const nx_adc_group_port_t *port, nx_adc_group_info_t *info)

复制实际选定事实与当前保留的所有者状态。

备注

观察到空闲或故障不会释放请求或任何冷租约。

参数:

  • port – [in] 同一个已初始化的选中接口，由唯一任务执行者调用。

  • info – [out] 独立且已对齐的输出，被拒绝时保持不变。

返回:

返回 SUCCESS 或 INVALID/STATE/CONTEXT/UNSUPPORTED。

struct nx_adc_group_request_t
#include <adc_group.h>

完整的原始帧存储跨度，具有明确的有限请求生命周期。

备注

base.transferred 统计完整帧，不统计字节或单个 rank。SUCCESS 表示恰好完成 frame_count 帧；错误时报告的保证有效帧数为零。部分 DMA/JEOC 进度不会发布为有效前缀。

公共成员

nx_request_t base
void *frames

独占的生产者存储，包含填充。

size_t bytes

精确等于 frame_count * info.format.scan_stride。

size_t frame_count

完整帧数量，必须为正且不超过选定上限。

struct nx_adc_group_info_t
#include <adc_group.h>

冷态选定的 rank 顺序、实际整数布局与调度事实。

备注

数组属于不可变的选中配置事实，其生命周期长于此端口。物理 rank 可能是芯片勘误要求丢弃的填充；format 仅描述有效逻辑结果。不承诺隐式数据打包、工程单位、采样孔径时间戳或触发计数器。

公共成员

nx_adc_format_t format
const uint8_t *channels

逻辑 rank 顺序，包含重复项。

const uint8_t *sample_times

实际逐通道采样编码。

const uint16_t *sample_halfcycles

不可变的采样编码查找表。

size_t sample_code_count
uint32_t adc_clock_hz
uint32_t physical_scan_halfcycles

包含所有丢弃的 rank。

uint32_t timer_period_us

软件触发时为零；不表示采样孔径。

size_t max_frames
uint16_t physical_ranks
bool active
bool fault
bool quarantined
struct nx_adc_group_ops_t
#include <adc_group.h>

共享只读的选定方法；普通 ADC 方法表不增加。

备注

由一个特权任务串行化所有调用。IRQ 只在同一个唯一物理所有者中记录有界事实。不提供分配、池、隐式任务、自动重新 arm 或运行时发现。

公共成员

nx_result_t (*submit)(void *context, nx_adc_group_request_t *request)
nx_result_t (*cancel)(void *context, nx_adc_group_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*info)(const void *context, nx_adc_group_info_t *info)
struct nx_adc_group_port
#include <adc_group.h>

不可变的选定接口，多个实例共享同一 const 方法表。

备注

接口、上下文和配置的生命周期覆盖每个请求、向量及保留责任的关闭过程。现有普通 ADC 或 PWM/ADC 接口不得暴露同一个已租用的 ADC。工厂仅返回此既有对象。

公共成员

const nx_adc_group_ops_t *ops
void *context

adc_observer.h

调用者拥有的可选 ADC 发布观察。

作者 Nexus Team

宏定义

NX_ADC_OBSERVATION_DISCONTINUITY

函数

nx_result_t nx_adc_observer_initialize(nx_adc_observer_t *observer, nx_adc_observation_t *records, size_t count)

初始化全新、尚未借用的可选观察存储。

参数:

  • observer – [out] 已对齐的新控制对象，尚未发布给读者。

  • records – [out] 独立且已对齐、大小精确的记录数组。

  • count – [in] 正数量；必须等于选中 stream 的数量。

返回:

成功或 INVALID/CONTEXT；被拒绝的输出保持不变。

nx_result_t nx_adc_observer_bind(nx_adc_observer_t *observer, nx_stream_t *stream, const void *owner, size_t owner_size)

仅提供者可执行的冷绑定；第一次 DMA 借用之前验证每个元数据／载荷范围。

参数:

  • observer – [inout] 已初始化的独占观察控制对象。

  • stream – [in] 精确的已初始化 stream，且没有尚未归还的借用。

  • owner – [in] provider 稳定且完整的私有状态范围。

  • owner_size – [in] 正的精确状态字节数。

返回:

成功或 INVALID/BUSY，不留下部分保留的绑定。

nx_result_t nx_adc_observer_record(nx_adc_observer_t *observer, const nx_stream_fill_t *fill, nx_time_us_t observed_at)

仅提供者可执行的记录，必须先于对应的 release 发布。

参数:

  • observer – [inout] 已绑定、由精确生产者持有的控制对象。

  • fill – [in] 仍为 FILLING，且已证明内存目标已分离。

  • observed_at – [in] 同一时钟域中的软件观察。

返回:

成功或 STATE/EXHAUSTED，不允许标识回绕。

nx_result_t nx_adc_observer_read(const nx_adc_observer_t *observer, const nx_stream_block_t *block, nx_adc_observation_t *observation)

只读取当前已取得块的准确 epoch 记录。

参数:

  • observer – [in] 稳定且已绑定的观察控制对象。

  • block – [in] 同一 stream 中仍存活且不可变的消费者借用。

  • observation – [out] 完整副本；拒绝时不变。

返回:

成功；借用缺失、陈旧或已释放时返回 INVALID/STATE。

nx_result_t nx_adc_observer_unbind(nx_adc_observer_t *observer)

全部生产者／消费者借用完成 join 后，仅提供者可解除绑定。

参数:

  • observer – [inout] 稳定且已初始化的控制对象；允许 NULL。

返回:

成功，或返回 BUSY 并保留已绑定的 stream。

struct nx_adc_observation_t
#include <adc_observer.h>

一个借用的软件观察，绝不表示采样孔径。

备注

observed_at 使用目标分离读回之后的平台单调时钟，包含 IRQ 递送及发布延迟。sequence 统计观察到的有效 block 记录，不统计定时器触发、样本或推测的漏失扫描。

公共成员

uint64_t epoch
nx_time_us_t observed_at
uint64_t sequence
uint32_t flags
struct nx_adc_observer_t
#include <adc_observer.h>

调用者拥有的可选观察者控制与准确记录。

备注

附加前先初始化；内部字段属于一个生产者。记录和控制对象必须保持存活，直到 provider 成功停止且全部消费者归还借用。不会扩大默认 stream、slot 或有限 provider 的存储。

公共成员

nx_stream_t *stream
nx_adc_observation_t *records
size_t count
uint64_t sequence
bool discontinuity

advanced_pwm.h

可选固定互补 PWM 与锁存刹车。

作者 Nexus Team

函数

nx_result_t nx_advanced_pwm_set_duty(const nx_advanced_pwm_t *port, uint32_t duty_ticks)

依据固定声明的 PSC/ARR 与互补通道对暂存占空比。

备注

影子 duty 在下一次 update 时生效。硬件死区编码必须精确表示冷配置的 tDTS 计数；PSC 不会缩放死区。此 API 不认证引脚时序。

参数:

  • port – [in] 一个串行化的特权任务所有者。

  • duty_ticks – [in] 从零到维护中的周期值，含两端。

返回:

SUCCESS 或 INVALID/STATE/CONTEXT；不重新配置基础时钟。

nx_result_t nx_advanced_pwm_start(const nx_advanced_pwm_t *port)

仅刹车未激活且无锁存故障时启用输出。

备注

禁止自动重新使能输出及不可逆的硬件 LOCK。break 绝不会静默重新启动输出。

参数:

  • port – [in] 已审查引脚、时钟及向量租约的特权任务所有者。

返回:

SUCCESS 或 BUSY/STATE/IO/CONTEXT；失败时保留所有权。

nx_result_t nx_advanced_pwm_stop(const nx_advanced_pwm_t *port)

禁用并读回主输出与两个通道源。

备注

冷装配保留已审查的非活动引脚及共享向量租约，直到成功且 IRQ 静止。已锁存的 break 在停止后仍保留。

参数:

  • port – [in] 特权任务所有者；不得并发调用 duty 或生命周期操作。

返回:

SUCCESS 证明输出源已分离；BUSY 保留责任。

nx_result_t nx_advanced_pwm_state(const nx_advanced_pwm_t *port, nx_advanced_pwm_state_t *state)

查询暂存占空比、实际启用状态与锁存刹车事实。

参数:

  • port – [in] 特权任务所有者。

  • state – [out] 独立可写的快照，绝不能是 provider 存储。

返回:

SUCCESS 或 INVALID/STATE/CONTEXT。

nx_result_t nx_advanced_pwm_clear_fault(const nx_advanced_pwm_t *port)

仅已禁用且 BKIN 未激活时清除软件故障。

备注

重新检查物理输入及待处理的硬件 break。应用恢复策略和外部电源安全由 Nexus 之外负责。

参数:

  • port – [in] 执行恢复的特权任务所有者。

返回:

SUCCESS 或 BUSY/STATE/IO/CONTEXT；不会使能输出。

struct nx_advanced_pwm_state_t
#include <advanced_pwm.h>

计数使用固定预分频后的时钟；死区使用 tDTS。

公共成员

uint32_t period_ticks
uint32_t duty_ticks
uint32_t tick_hz
uint32_t deadtime_ticks
uint32_t deadtime_hz
bool running
bool fault
struct nx_advanced_pwm_ops_t
#include <advanced_pwm.h>

共享不可变控制；配置是冷装配事实。

公共成员

nx_result_t (*set_duty)(void *context, uint32_t duty_ticks)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_advanced_pwm_state_t *state)
nx_result_t (*clear_fault)(void *context)
struct nx_advanced_pwm
#include <advanced_pwm.h>

不可变身份；控制器状态与配置必须在所有 IRQ 完全退出前保持有效。

公共成员

const nx_advanced_pwm_ops_t *ops
void *context

can.h

经典 CAN 值帧与调用者拥有的邮箱请求。

作者 Nexus Team

宏定义

NX_CAN_LOSS_SOFTWARE
NX_CAN_LOSS_HARDWARE_LOWER_BOUND
NX_CAN_LOSS_SATURATED
NX_CAN_DLC_NORMALIZED

枚举

enum nx_can_format_t

取值：

enumerator NX_CAN_STANDARD
enumerator NX_CAN_EXTENDED
enum nx_can_frame_kind_t

取值：

enumerator NX_CAN_DATA
enumerator NX_CAN_REMOTE
enum nx_can_event_kind_t

取值：

enumerator NX_CAN_EVENT_FRAME
enumerator NX_CAN_EVENT_LOSS

函数

nx_result_t nx_can_tx_prepare(nx_can_tx_request_t *request, const nx_can_frame_t *frame, nx_time_us_t deadline)

验证并复制经典帧到未被借用的请求存储。

备注

仅限任务所有者；失败时不保留引用，也不更改帧。

参数:

  • request – [inout] 已初始化为 READY 或已消费的 SETTLED 存储。

  • frame – [in] 在此复制的值；忽略 remote 帧数据字节。

  • deadline – [in] provider 时钟中的绝对 deadline，包含准入时间。

返回:

成功；非经典帧返回 INVALID；借用期间返回 STATE。

nx_result_t nx_can_port_submit(const nx_can_port_t *port, nx_can_tx_request_t *request)

将一个帧准入到三个硬件邮箱之一。

备注

串行化的特权任务所有者，进入时 IRQ 屏蔽位须清零。REJECTED 不保留任何内容。TXOK 加上硬件已完成或已空，才证明成功。

参数:

  • port – [in] 稳定且不可变的接口及私有存储。

  • request – [inout] READY 值请求，保持存活直到 SETTLED。

返回:

成功表示 ACCEPTED，不表示已完成线上发送；其他结果均为拒绝。

nx_result_t nx_can_port_cancel(const nx_can_port_t *port, nx_can_tx_request_t *request)

请求中止，不撤销请求借用。

备注

中止可能与真实发送竞争；已观察到 TXOK 时仍为 SUCCESS。中止失败保持 QUARANTINED，必须保持存储存活。

参数:

  • port – [in] 由串行任务执行者拥有的稳定接口。

  • request – [inout] 先前由本实例接受且仍存活的请求。

返回:

成功表示请求排空；无关请求返回 STATE。

nx_result_t nx_can_port_service(const nx_can_port_t *port)

处理锁存完成状态与绝对超时／排空截止时间。

备注

工作量限于三个邮箱／六帧；无 worker、阻塞或重放。

参数:

  • port – [in] 串行任务所有者接口，进入时屏蔽位须清零。

返回:

成功；启动前返回 STATE；非法调用者返回 CONTEXT。

nx_result_t nx_can_port_read_events(const nx_can_port_t *port, nx_can_event_t *events, size_t capacity, size_t *count)

消费值事件，不覆盖此前尚未消费的事实。

备注

每次有界记录复制均以短临界区排除元数据并发访问；待发布的丢失边界排在较旧记录之后、后续帧之前。

参数:

  • port – [in] 稳定实例；此操作由一个任务消费者拥有。

  • events – [out] 调用方容量；不保留输出引用。

  • capacity – [in] 非零的事件记录数量。

  • count – [out] 已复制数量；EMPTY 表示没有可用记录。

返回:

成功、EMPTY、INVALID 或 CONTEXT。

nx_result_t nx_can_port_state(const nx_can_port_t *port, nx_can_state_t *state)

即使 RX 已满，仍复制权威错误／准入状态。

备注

仅限任务上下文，工作量有界；bus-off 被锁存，直到显式恢复。

参数:

  • port – [in] 存活的实例和存储。

  • state – [out] 不保留引用的值输出。

返回:

成功、INVALID 或 CONTEXT。

nx_result_t nx_can_port_stop(const nx_can_port_t *port)

关闭准入、中止 TX、撤离 IRQ/RX 发布者。

备注

绝不会为释放另一个所有者的借用而复位共享主控制器。推进后重试。成功表示 provider 不再访问 RX 或 wake 存储。

参数:

  • port – [in] 串行化的所有者；还须等待外部观察者退出。

返回:

硬件排空后成功；BUSY 保留请求、环及 wake 借用。

nx_result_t nx_can_port_recover(const nx_can_port_t *port)

bus-off 且完整排空之后，显式重新进入初始化。

备注

无自动恢复或重传；域及 filter 标识保持不变。

参数:

  • port – [in] 已启动的所有者，且不存在 active 或 quarantined TX slot。

返回:

有界硬件确认后成功；借用期间返回 BUSY。

nx_result_t nx_can_port_attach_wake(const nx_can_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

检查全部四个实际 IRQ 后，借用可选唤醒目标。

备注

无隐式 OS 策略；NULL 表示分离。wake 仅为提示。sink 必须同时支持任务中的 service/cancel 及可配置 IRQ 上下文。

参数:

  • port – [in] 串行任务所有者，已启动且屏蔽位清零。

  • wake – [in] 不可变目标，保持存活直到成功停止或分离。

  • syscall_ceiling – [in] 附加的 BASEPRI 数值阈值。

返回:

成功；较早发布者仍存活时返回 BUSY；或返回 PERMISSION、INVALID、CONTEXT。失败时不产生新借用。

struct nx_can_frame_t
#include <can.h>

经典 2.0A/B 值帧；DLC 始终为 0..8，绝不是 CAN FD。

公共成员

uint32_t id
nx_can_format_t format
nx_can_frame_kind_t kind
uint8_t dlc
uint8_t data[8]
struct nx_can_tx_request_t
#include <can.h>

调用者拥有的帧在 prepare 时复制；必须先初始化 base。

公共成员

nx_request_t base
nx_can_frame_t frame
struct nx_can_event_t
#include <can.h>

值接收事实或有序丢失边界。

备注

时间戳是 IRQ 取得或报告时间，不是硬件 SOF。硬件 overrun 仅证明损失下限。原始 DLC 9..15 规范化为 8。

公共成员

nx_can_frame_t frame
nx_time_us_t timestamp_us
uint64_t lost
uint32_t flags
nx_can_event_kind_t kind
uint8_t fifo
uint8_t filter
uint8_t raw_dlc
struct nx_can_state_t
#include <can.h>

锁存控制器状态，与接收环是否已满无关。

公共成员

bool started
bool closing
bool bus_off
uint8_t pending
uint8_t transmit_errors
uint8_t receive_errors
uint8_t last_error
struct nx_can_ops_t
#include <can.h>

共享不可变操作；执行所有者串行执行 Task 方法。

公共成员

nx_result_t (*submit)(void*, nx_can_tx_request_t*)
nx_result_t (*cancel)(void*, nx_can_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_can_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_can_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_can_port
#include <can.h>

不可变接口面；查找不分配、不启动、不取得硬件。

公共成员

const nx_can_ops_t *ops
void *context

can_fd.h

可选 CAN FD 值接口与持续借用的硬件请求。

作者 Nexus Team

宏定义

NX_CAN_FD_TIMESTAMP_UNAVAILABLE

枚举

enum nx_can_wire_format_t

精确的线上格式；经典 CAN 接口保持独立。

取值：

enumerator NX_CAN_WIRE_CLASSIC
enumerator NX_CAN_WIRE_FD

函数

nx_result_t nx_can_fd_tx_prepare(nx_can_fd_tx_request_t *request, const nx_can_fd_frame_t *frame, nx_time_us_t deadline)

验证精确帧并复制到尚未借用的请求存储。

备注

串行任务所有者。失败时不更改帧，也不建立借用。

参数:

  • request – [inout] 已初始化为 READY 或已消费的 SETTLED 存储。

  • frame – [in] 复制完整值，不保留此地址。

  • deadline – [in] provider 时钟中的绝对 deadline，包含准入时间。

返回:

成功；帧格式错误时返回 INVALID；借用期间返回 STATE。

nx_result_t nx_can_fd_port_submit(const nx_can_fd_port_t *port, nx_can_fd_tx_request_t *request)

将一个精确值准入物理硬件发送元素。

备注

串行化的特权任务，进入时屏蔽位须清零。准入不隐含软件 FIFO 顺序；硬件队列按 ID 仲裁。

参数:

  • port – [in] 稳定且不可变的选中控制器接口。

  • request – [inout] READY 请求，保留至以 acquire 语义观察到 SETTLED。

返回:

SUCCESS 表示 ACCEPTED；所有失败均无效果地拒绝。

nx_result_t nx_can_fd_port_cancel(const nx_can_fd_port_t *port, nx_can_fd_tx_request_t *request)

请求取消，同时保留已接受的存储借用。

备注

物理发送可能先于取消完成，此时仍为 SUCCESS。超时或取消不会释放存储。排空失败为 QUARANTINED。

参数:

  • port – [in] 由唯一任务执行者拥有的选中接口。

  • request – [inout] 先前由本实例接受的精确请求。

返回:

成功表示请求排空；STATE 表示拒绝无关请求。

nx_result_t nx_can_fd_port_service(const nx_can_fd_port_t *port)

处理有界的硬件事实与绝对截止时间进展。

备注

无隐藏 worker、重试或阻塞等待。wake 仍仅为提示。

参数:

  • port – [in] 串行化的特权任务接口，进入时屏蔽位须清零。

返回:

成功；不可用时返回 STATE；非法调用者返回 CONTEXT。

nx_result_t nx_can_fd_port_read_events(const nx_can_fd_port_t *port, nx_can_fd_event_t *events, size_t capacity, size_t *count)

将有序值事件复制到不会被持续借用的调用者输出存储。

备注

较早保留的记录排在待发布的丢失边界之前。接收存储已满或提示失败，都不得抹除协议状态。

参数:

  • port – [in] 稳定实例，由一个任务消费者使用。

  • events – [out] 可写输出，必须与全部借用存储不重叠。

  • capacity – [in] 正的完整输出事件记录数。

  • count – [out] 不保留引用的已复制数量，与 events 不重叠。

返回:

成功；EMPTY 表示复制数量为零；或返回 INVALID、STATE、CONTEXT。

nx_result_t nx_can_fd_port_state(const nx_can_fd_port_t *port, nx_can_fd_state_t *state)

复制权威的锁存协议状态与所有权状态。

备注

仅限任务上下文；事件环已满不会隐藏 bus-off 或错误状态。

参数:

  • port – [in] 稳定的选中实例，包括成功停止之后。

  • state – [out] 可写值，与全部已借用控制对象不重叠。

返回:

成功、INVALID 或 CONTEXT。绝不保留输出。

nx_result_t nx_can_fd_port_stop(const nx_can_fd_port_t *port)

关闭准入、排空发送借用并撤离 IRQ 发布者。

备注

绝不可复位共享外设域来撤销另一所有者。物理推进后重试。停止成功不代表观察者已退出。

参数:

  • port – [in] 唯一任务所有者；还须另行等待独立观察者退出。

返回:

成功释放 provider 借用；失败保留尚未完成的租约。

nx_result_t nx_can_fd_port_recover(const nx_can_fd_port_t *port)

完整排空发送后，恢复同一硬件身份。

备注

显式恢复绝不重放帧，也不重新分配共享 RAM。

参数:

  • port – [in] 已启动的任务所有者，且没有 pending 或 quarantined 请求。

返回:

有界确认后成功；借用期间返回 BUSY。

nx_result_t nx_can_fd_port_attach_wake(const nx_can_fd_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

验证实际启用的 IRQ 源后借用唤醒接收端。

备注

NULL 表示分离。拒绝时保留先前的 sink。通知必须有界，并在任务及可配置 IRQ 上下文中均合法。

参数:

  • port – [in] 唯一任务所有者，已启动且进入时屏蔽位清零。

  • wake – [in] 不可变 sink，保留直到成功分离或停止。

  • syscall_ceiling – [in] 附加的 BASEPRI 数值阈值。

返回:

成功；发布期间返回 BUSY；或返回 PERMISSION、INVALID、CONTEXT。

struct nx_can_fd_frame_t
#include <can_fd.h>

具有精确字节长度的值帧，不使用原始或移位后的 DLC。

备注

FD 接受 0..8/12/16/20/24/32/48/64 字节；在线上不向上取整或填充。FD remote 帧及经典帧 BRS 无效。选中硬件模式不支持某种形式时，provider 可以拒绝该形式的合法值。

公共成员

uint32_t id
nx_can_format_t format
nx_can_frame_kind_t kind
nx_can_wire_format_t wire
uint8_t payload_bytes
bool brs
uint8_t data[64]
struct nx_can_fd_tx_request_t
#include <can_fd.h>

准备操作复制完整值；被接受的请求保持借用。

公共成员

nx_request_t base
nx_can_fd_frame_t frame
struct nx_can_fd_event_t
#include <can_fd.h>

已取得的值事件，包含观察到的发送者 ESI。

备注

acquired_us 是 provider 取得时间，绝不是 SOF。硬件计数器禁用时报告 raw0 及 TIMESTAMP_UNAVAILABLE。filter 是该帧格式 filter 列表中的硬件索引。硬件丢失证明的是下限；经典 DLC9..15 规范化为 8，并附带标志。

公共成员

nx_can_fd_frame_t frame
nx_time_us_t acquired_us
uint64_t lost
uint32_t flags
nx_can_event_kind_t kind
uint16_t hardware_timestamp
uint8_t fifo
uint8_t filter
uint8_t raw_dlc
bool error_passive
bool nonmatching
struct nx_can_fd_filter_t
#include <can_fd.h>

不可变掩码过滤器；不包含产品寄存器或协议策略。

公共成员

uint32_t id
uint32_t mask
nx_can_format_t format
uint8_t fifo
struct nx_can_fd_state_t
#include <can_fd.h>

锁存协议状态；载荷长度不表示帧数量。

公共成员

nx_can_state_t controller
uint8_t data_last_error
bool error_warning
bool error_passive
struct nx_can_fd_ops_t
#include <can_fd.h>

公共成员

nx_result_t (*submit)(void*, nx_can_fd_tx_request_t*)
nx_result_t (*cancel)(void*, nx_can_fd_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_can_fd_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_can_fd_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_can_fd_port
#include <can_fd.h>

公共成员

const nx_can_fd_ops_t *ops
void *context

cycle_probe.h

显式选用的原始周期观察，不作经过时间承诺。

作者 Nexus Team

宏定义

NX_IO_CYCLE_PROBES
NX_IO_IRQ_PROBE_DECLARE(id)
NX_IO_IRQ_PROBE_BEGIN(id)
NX_IO_IRQ_PROBE_END(id)

函数

nx_result_t nx_io_cycle_probe_begin(nx_io_cycle_probe_t *probe, nx_io_cycle_token_t *token)

开始一次原始观察，不启用或复位 DWT。

备注

可配置 IRQ 或唯一任务执行者。probe 失败绝不可阻止真实 I/O 派发、取消、service 或保留责任的排空。

参数:

  • probe – [inout] 存活且独占、为零或先前已完成的 sidecar。

  • token – [inout] 为零或非活动的 token，必须与完整 probe 不重叠。

返回:

即使计数器不可用仍返回 SUCCESS；INVALID/STATE/BUSY 在访问计数器前拒绝。统计同一 probe 的重入。

nx_result_t nx_io_cycle_probe_end(nx_io_cycle_probe_t *probe, nx_io_cycle_token_t *token)

结束对应令牌，发布原始事实并移除其引用。

备注

不得仅从两个计数器值推导有效的 elapsed 或预算结论。

参数:

  • probe – [inout] 与 begin 使用的同一个稳定 sidecar。

  • token – [inout] 精确且仍活动的 token；不得并发修改。

返回:

返回 SUCCESS 或 INVALID；使用其他或非活动 token 时返回 STATE。

nx_result_t nx_io_cycle_probe_snapshot(const nx_io_cycle_probe_t *probe, nx_io_cycle_observation_t *out)

保存并恢复本地中断排除状态，在保护期间复制有界 IRQ 统计。

备注

仅限特权任务。恢复进入时的屏蔽状态。对于任务 service 生产者，采样须使用同一执行者，或先等待生产者退出；IRQ 屏蔽不会等待另一个被抢占任务退出。这不是 SMP 排他。屏蔽期间不访问 provider、payload、request 或计数器。

参数:

  • probe – [in] 稳定、位于同一 CPU 的 sidecar 及存活的生产者绑定。

  • out – [out] 独立且已对齐的复制结果；拒绝时不变。

返回:

返回 SUCCESS 或 INVALID；ISR 或非特权调用者返回 CONTEXT。

nx_result_t nx_uart_word_port_service_observed(const nx_uart_word_port_t *port, nx_io_cycle_probe_t *probe)

仅派发一个字服务步骤，可选记录原始观察。

备注

无额外 ops 表、worker、请求或 payload 引用。无效观察绝不阻止派发。调用方须证明完整私有状态、借用描述符及缓冲区均与观察存储不重叠；此 API 只知道接口或方法范围及 context 标识。

参数:

  • port – [in] 原有稳定接口、方法及唯一任务执行者。

  • probe – [inout] 可选的存活 sidecar；NULL 表示省略观察。

返回:

SUCCESS 仅证明派发；INVALID/UNSUPPORTED 描述接口情况。

nx_result_t nx_spi_dma_transaction_service_observed(const nx_spi_dma_transaction_port_t *port, nx_io_cycle_probe_t *probe)

仅派发一个完整 CS 区间的 DMA 服务步骤，并记录原始观察。

备注

不重叠及执行者规则与 word wrapper 相同。诊断失败不会释放 QUARANTINED 借用，也不改变结算决定权。

参数:

  • port – [in] 原有增强控制器及其唯一任务执行者。

  • probe – [inout] 可选、稳定且不重叠的 sidecar，或 NULL。

返回:

派发后返回 SUCCESS；无效接口返回 INVALID 或 UNSUPPORTED。

struct nx_io_cycle_observation_t
#include <cycle_probe.h>

复制的原始计数器事实；可读不表示经过时间已知。

备注

一对值是模 2^32 的余数，包含抢占及 probe 开销。不建立回绕次数、复位、频率或 epoch 连续性。elapsed_known 始终为 false。没有任何字段证明预算已满足、IRQ 到达延迟、独占 CPU 时间或物理 WCET 上界。attempts 包含当前活动尝试；其他总计描述已完成尝试。总计采用饱和而非回绕。

公共成员

uint32_t attempts
uint32_t raw_pairs
uint32_t unavailable_pairs
uint32_t reentries
uint32_t last_begin
uint32_t last_end
uint32_t last_modulo_cycles
uint32_t maximum_modulo_cycles
bool last_available
bool elapsed_known
bool active
struct nx_io_cycle_probe_t
#include <cycle_probe.h>

可选的零初始化附属状态；默认提供者状态不增加。

备注

每个 sidecar 由一个物理向量或一个唯一任务执行者写入。不同嵌套向量必须使用不同 sidecar。NMI、HardFault、其他核及其他安全状态不得访问此存储。只有全部生产者、token 和读者退出后，才能复位或回收。

公共成员

nx_io_cycle_observation_t observation
struct nx_io_cycle_token_t
#include <cycle_probe.h>

零初始化栈令牌；活动期间不得复制或重新绑定。

公共成员

nx_io_cycle_probe_t *owner
uint32_t before
bool available

diagnostic.h

有效 request 快照具有非零 epoch 和有限 observed_at；其 deadline 可以为 NX_DEADLINE_NEVER，表示无期限。SERVICE 事实要求 last_service_at 与 observed_at 在同一单调时钟域中且均为有限值，maximum_service_gap_us 为有限正值。未知事实组保持未知。

显式复制事实解释待处理 I/O，不执行恢复。

作者 Nexus Team

宏定义

NX_IO_FACT_REQUEST
NX_IO_FACT_STREAM
NX_IO_FACT_LIFECYCLE
NX_IO_FACT_OWNER
NX_IO_FACT_SERVICE
NX_IO_FACT_OBSERVERS
NX_IO_FACT_ALL
NX_IO_DIAG_QUEUED
NX_IO_DIAG_ACTIVE
NX_IO_DIAG_DRAINING
NX_IO_DIAG_QUARANTINED
NX_IO_DIAG_SETTLED
NX_IO_DIAG_DEADLINE_REACHED
NX_IO_DIAG_NOT_STARTED
NX_IO_DIAG_STOPPING
NX_IO_DIAG_OWNER_CLOSED
NX_IO_DIAG_NO_FREE_SLOT
NX_IO_DIAG_OWNER_PENDING
NX_IO_DIAG_SERVICE_OVERDUE
NX_IO_DIAG_OBSERVERS_PENDING
NX_IO_DIAG_STREAM_OUTSTANDING
NX_IO_DIAG_STREAM_CURSOR_BUSY
NX_IO_DIAG_STREAM_LOSS

函数

nx_result_t nx_io_diagnose(const nx_io_diagnostic_facts_t *facts, nx_io_diagnostic_t *out)

分类给定观察，不访问实际 I/O。

备注

任务／IRQ 中执行固定有界工作，不访问 MMIO、不加锁、不分配、不执行 service 或恢复。deadline 与 quarantine 从不撤销已接受的借用。重用存储前，调用者仍必须排空控制路径并 join observer。

参数:

  • facts – [in] 稳定且对齐的副本；不保留指针。

  • out – [out] 已对齐输出，与全部输入区间分离。

返回:

返回 SUCCESS；事实格式错误或发生别名时返回 INVALID；service 时间倒退时返回 STATE。拒绝保持输出不变。

const char *nx_io_diagnostic_name(uint32_t finding)

可选的稳定原因 key，仅接受一个 finding 位。

备注

任务／IRQ 中执行固定工作量，不格式化或分配。

参数:

  • finding – [in] 一个 NX_IO_DIAG 标志，不能是组合掩码。

返回:

返回不可变静态文本；零、未知位或多个位返回 NULL。

struct nx_io_diagnostic_facts_t
#include <diagnostic.h>

稳定的调用者副本，各事实组独立声明已知。

备注

request／stream 可以为 NULL；存在时对应事实组即已知。known 仅接受 LIFECYCLE、OWNER、SERVICE 和 OBSERVERS。置零的未知值不能建立 ready、健康或漏调 service 的事实。OWNER 字段只有在 owner observer 的 diagnostic_result 成功时才能来自该观察；它们描述准入与待处理工作，不解释 service 返回 BUSY 的原因。SERVICE 时间戳使用同一单调时钟域，两者均为有限值，maximum_service_gap_us 是声明的有限正预算。该函数不自行读取时钟。副本在本次调用期间保持稳定；不同设备的观察不必同时发生。

公共成员

const nx_request_observation_t *request
const nx_stream_observation_t *stream
uint32_t known
nx_time_us_t last_service_at
nx_time_us_t observed_at
nx_time_us_t maximum_service_gap_us
bool started
bool stopping
bool owner_accepting
bool owner_queued
bool owner_slot_available
bool observers_pending
struct nx_io_diagnostic_t
#include <diagnostic.h>

独立 finding 与不可用事实组。

备注

零 finding 不是健康证明。SETTLED 不建立 I/O 成功或 observer 已 join 的事实。未结清 stream 块包含生产者、ready 和消费者借用；cursor busy 仅描述普通 stream cursor。Loss 是此快照尚未发布的 stream 元数据，不是累计总数；发布会把它转移到之后的块中。

公共成员

uint32_t findings
uint32_t unknown_facts

dma.h

显式 DMA 内存域、物理流与排空事实。

作者 Nexus Team

宏定义

NX_DMA_MEMORY_READ
NX_DMA_MEMORY_WRITE

枚举

enum nx_dma_direction_t

传输方向决定设备对调用者内存的访问。

取值：

enumerator NX_DMA_TO_DEVICE
enumerator NX_DMA_FROM_DEVICE

函数

nx_result_t nx_dma_buffer_validate(const nx_dma_memory_region_t *regions, size_t count, const void *data, size_t length, size_t alignment, nx_dma_direction_t direction)

验证整个缓冲区位于一个显式内存域内。

备注

任务或 IRQ 中的有界检查，无 MMIO、分配或副作用。

参数:

  • regions – [in] 不可变的 SoC 域，在此调用期间保持存活。

  • count – [in] 正的域数量。

  • data – [in] 调用方的非空缓冲区；此 helper 绝不借用它。

  • length – [in] 正字节长度，包含所有 DMA 访问。

  • alignment – [in] 非零且为 2 的幂的传输对齐。

  • direction – [in] 设备读取或写入所提供的内存。

返回:

成功；范围或对齐格式错误返回 INVALID；范围不在所需 DMA 域内返回 PERMISSION。

nx_result_t nx_dma_storage_validate(const nx_dma_memory_region_t *regions, size_t count, const void *storage, size_t capacity, size_t transfer_bytes, size_t alignment, size_t cache_line_bytes, nx_dma_direction_t direction)

检查显式拥有的 reservation 及其 DMA payload。

备注

任务／IRQ 中进行有界验证，不分配或操作 cache。调用者独占全部 cache line 和填充区域，直到排空并 acquire 观察到 SETTLED。此处仅验证几何，不能证明所有权，也不能替代 provider 准入、真实 cache 几何、模式长度检查或 cache 维护。取消不解除该义务。

参数:

  • regions – [in] 不可变且已复核的 SoC DMA 域，不保留。

  • count – [in] 正的域数量。

  • storage – [in] 调用者拥有的 reservation，与实际存活的借用区间分离。

  • capacity – [in] 完整 reservation 字节数，包含自有填充区域。

  • transfer_bytes – [in] 正的 payload 长度，不超过 capacity。

  • alignment – [in] 非零且为 2 的幂的传输对齐。

  • cache_line_bytes – [in] 零表示无 cache 约束；否则为已复核、二次幂的 cache line 大小，地址和 capacity 必须是其整数倍。辅助函数从不对区间取整。

  • direction – [in] 完整存储的设备访问权限。

返回:

返回 SUCCESS、INVALID 或 PERMISSION；不访问或借用内存。

nx_result_t nx_dma_resources_validate(const nx_dma_resource_t *resources, size_t count)

拒绝装配资源集合中重复的物理流。

备注

冷态冲突检查；选中 SoC 在使用前必须依据真实拓扑验证全部标识。此 helper 不推断芯片支持，也不分配。

参数:

  • resources – [in] 不可变资源列表，不保留引用。

  • count – [in] 资源数量；为零时允许 NULL 列表。

返回:

成功；非空列表为 NULL 或使用保留的零控制器时返回 INVALID；物理引擎重复时返回 BUSY。

nx_result_t nx_dma_drain_check(const nx_dma_drain_facts_t *facts)

分别要求 DMA 引擎、IRQ 与外设排空。

备注

provider 必须先观察实际寄存器及顺序，才能设置这些事实。此 helper 不会停止硬件。

参数:

  • facts – [in] provider 的观察结果；不保留引用。

返回:

仅在全部源已分离且空闲时成功；任何源仍存在时返回 BUSY；不可能的计数器值返回 INVALID。

struct nx_dma_memory_region_t
#include <dma.h>

已审查的 DMA 可见内存区间，不等同于 CPU 可访问性。

备注

begin 加 size 不得回绕。在带缓存的架构上，缓存维护仍是 provider 的责任。

公共成员

uintptr_t begin
size_t size
uint32_t permissions
struct nx_dma_resource_t
#include <dma.h>

不透明物理引擎与请求选择器身份。

备注

控制器零保留为无效值。其他值的含义由 provider 定义；SoC 验证自身拓扑。同一 controller/stream 上的两个 selector 相互冲突。

公共成员

uint8_t controller
uint8_t stream
uint8_t channel
struct nx_dma_drain_facts_t
#include <dma.h>

释放内存借用前必须独立满足的事实。

备注

remaining 描述 DMA 内存传输，不是线上字节。计数器为零绝不证明 peripheral_idle。

公共成员

size_t length
size_t remaining
bool engine_disabled
bool irq_detached
bool peripheral_idle

encoder.h

可选的原始模数正交编码器观察。

作者 Nexus Team

枚举

enum nx_encoder_mode_t

精确的边沿计数模式，不是可任意组合的掩码。

取值：

enumerator NX_ENCODER_MODE_UNKNOWN
enumerator NX_ENCODER_MODE_X2_TI1
enumerator NX_ENCODER_MODE_X2_TI2
enumerator NX_ENCODER_MODE_X4_TI12

函数

nx_result_t nx_encoder_start(const nx_encoder_t *port)

仅启用冷装配选定的两个编码器输入与计数器。

备注

provider 绝不在运行时改变引脚、速率、滤波或模式。时钟、引脚及向量租约从冷装配一直保持到关闭。

参数:

  • port – [in] 一个串行化的特权 Thread-mode 所有者。

返回:

SUCCESS 或错误；写入失败保留恢复责任。

nx_result_t nx_encoder_stop(const nx_encoder_t *port)

观察计数器与输入源均已撤离后才返回。

备注

停止保留原始位置，不释放冷资源。

参数:

  • port – [in] 同一个串行化的特权 Thread-mode 所有者。

返回:

SUCCESS 证明源已撤回；失败保留会话。

nx_result_t nx_encoder_read(const nx_encoder_t *port, nx_encoder_sample_t *sample)

读取一个模数位置，不推断跨回绕的行程。

备注

observed_at 是软件观察时间，不是传感器边沿采样孔径。方向、速度、机械零位及无界有符号位置，需要外部采样约束和产品策略。一次读取无法重建漏掉的完整回绕。单独读取的 DIR 位不是原子边沿历史。

参数:

  • port – [in] 串行化的特权 Thread-mode 所有者。

  • sample – [out] 已对齐的独立输出；拒绝时不变。

返回:

返回 SUCCESS 或 INVALID/STATE/CONTEXT/UNSUPPORTED。

nx_result_t nx_encoder_state(const nx_encoder_t *port, nx_encoder_state_t *state)

报告精确计数器位宽与选定的硅片过滤器编码。

备注

滤波码及其内核时钟不构成抗噪声、物理边沿速率或传感器及 Board 电气行为的资格结论。

参数:

  • port – [in] 串行化的特权 Thread-mode 所有者。

  • state – [out] 已对齐的独立输出；拒绝时不变。

返回:

返回 SUCCESS 或 INVALID/STATE/CONTEXT/UNSUPPORTED。

struct nx_encoder_sample_t
#include <encoder.h>

一个原始模数计数值与独立的软件观察时间。

公共成员

nx_time_us_t observed_at
uint32_t count
struct nx_encoder_state_t
#include <encoder.h>

不可变输入／过滤器事实与实际计数器启用状态。

公共成员

uint32_t filter_clock_hz
nx_encoder_mode_t mode
uint8_t counter_bits
uint8_t filter_a
uint8_t filter_b
bool running
struct nx_encoder_ops_t
#include <encoder.h>

共享方法；无环形缓冲、请求、分配、回调或工作线程。

公共成员

nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*read)(void *context, nx_encoder_sample_t *sample)
nx_result_t (*state)(const void *context, nx_encoder_state_t *state)
struct nx_encoder
#include <encoder.h>

不可变身份；精确的私有状态拥有整个控制器。

公共成员

const nx_encoder_ops_t *ops
void *context

entropy.h

熵源接口提供有界、通过健康检查的源数据字。nx_entropy_fill 使用有限绝对截止时间；读取失败时擦除本次已准入的全部输出。它不分配内存、不创建工作线程，也不证明熵质量；它不是 DRBG。存在熵源不代表密码库可以按完整熵含量计入信用。时钟与关闭前提见显式 F407 构造器。GD32 熵源尚未实现。

显式熵源与有限的完整填充或全部擦除操作。

作者 Nexus Team

类型定义

typedef struct nx_entropy_port nx_entropy_port_t

含私有可变状态的静态双指针源接口。

备注

调用方串行化使用和生命周期；接口、方法表和状态必须存活至每次调用结束。返回后不保留缓冲区或请求。源启用、时钟依赖、恢复和停止由显式生命周期所有者负责，不由 TLS 或此接口负责。

函数

nx_result_t nx_entropy_port_try_read(const nx_entropy_port_t *port, uint32_t *word)

尝试复制一个完整源数据字，不等待。

备注

公共存储区间无效时，在访问 provider 前拒绝。此包装层无法推断不透明上下文的范围；调用方证明其完整区间互不重叠。provider 拒绝时绝不使用固定值或时间戳代替熵。

参数:

  • port – [in] 在其串行任务执行器中使用的有效只读接口

  • word – [out] 自然对齐的可写数据字，与接口、方法表及完整 provider 私有状态互不重叠

返回:

SUCCESS、BUSY、IO、STATE、INVALID 或 UNSUPPORTED

nx_result_t nx_entropy_fill(const nx_entropy_port_t *port, void *output, size_t bytes, const nx_clock_t *clock, nx_time_us_t deadline)

在有限截止时间前恰好填满请求的字节。

备注

仅限任务上下文的同步轮询；无堆、工作线程或 OS 等待。BUSY 导致下一次受时钟约束的轮询。所提供时钟必须在整个调用期间持续推进；更换时间域或停止计时器违反合同。拒绝 NX_DEADLINE_NEVER。完整数据字按最低有效字节在前输出；最后一个字中未用的字节被丢弃。零字节请求验证接口与时钟，但不访问时钟或源，并允许 NULL 输出。准入前拒绝保持输出不变。准入后任何错误均通过 volatile 写擦除全部输出；不得消费部分熵。输出与接口、方法表、时钟及其全部有效不透明上下文互不重叠。本函数检测已知区间别名，不推断不透明对象的范围。调理、DRBG 和信任策略由密码库负责。

参数:

  • port – [in] 有效的串行化源；不得并发生命周期变更

  • output – [out] 可写字节区间；仅零字节时允许 NULL

  • bytes – [in] 所需输出的准确大小，不是熵含量估计

  • clock – [in] 单一稳定时间域内有效的单调微秒时钟

  • deadline – [in] 该时间域内的有限绝对截止时间

返回:

仅完整填充返回 SUCCESS；否则为 TIMEOUT、IO、STATE 或源错误；准入前拒绝返回 INVALID/UNSUPPORTED

struct nx_entropy_ops_t
#include <entropy.h>

共享的只读熵源方法。

备注

try_read 仅限任务上下文且执行有界，从不等待硬件。SUCCESS 复制一个完整、通过健康检查的 32 位数据字；BUSY 表示尚无数据字，IO 表示源或健康检查失败，STATE 表示不可用或已关闭。失败保持输出不变。provider 负责硬件健康检查与首样本处理。不隐含确定性回退、调理、DRBG 或密码学认证。

公共成员

nx_result_t (*try_read)(void *context, uint32_t *word)
struct nx_entropy_port
#include <entropy.h>

含私有可变状态的静态双指针源接口。

备注

调用方串行化使用和生命周期；接口、方法表和状态必须存活至每次调用结束。返回后不保留缓冲区或请求。源启用、时钟依赖、恢复和停止由显式生命周期所有者负责，不由 TLS 或此接口负责。

公共成员

const nx_entropy_ops_t *ops
void *context

ethernet.h

调用者拥有的无标签 Ethernet II 帧与接收借用。

作者 Nexus Team

宏定义

NX_ETH_FRAME_MIN
NX_ETH_FRAME_MAX
NX_ETH_RX_STORAGE_MIN
NX_ETH_RX_CRC
NX_ETH_RX_LENGTH
NX_ETH_RX_FRAGMENT
NX_ETH_RX_UNSUPPORTED
NX_ETH_RX_DMA_ERROR
NX_ETH_RX_BACKPRESSURE

函数

nx_result_t nx_eth_tx_prepare(nx_eth_tx_request_t *request, const void *data, size_t length, nx_time_us_t deadline)

准备已初始化、未借用的请求及不可变帧。

备注

任务所有者。仅支持 Ethernet II，不含 FCS 时为 14..1514 字节；不支持 VLAN 或以长度编码的 802.3。失败时不修改请求或 payload。

参数:

  • request – [inout] 已初始化为 READY 或已消费的 SETTLED 存储。

  • data – [in] 不可变、连续的 Ethernet II 帧。

  • length – [in] 不含 FCS 的字节数，范围为 14..1514。

  • deadline – [in] provider 时钟中的绝对 deadline，或 NEVER。

返回:

成功；帧或重叠问题返回 INVALID；借用期间返回 STATE。

nx_result_t nx_eth_port_submit(const nx_eth_port_t *port, nx_eth_tx_request_t *request)

将一个帧准入到调用者拥有的硬件描述符。

备注

串行化的特权任务，屏蔽位清零。SUCCESS 表示 ACCEPTED。借用包含请求和帧，直到以 acquire 语义观察到 SETTLED。完成报告 MAC 线上状态，绝不表示另一应用已收到数据。

参数:

  • port – [in] 稳定接口及存活的私有装配。

  • request – [inout] 已准备的存储，在接受时借用。

返回:

成功表示 ACCEPTED；BUSY/STATE/IO 或无效输入均为拒绝。

nx_result_t nx_eth_port_cancel(const nx_eth_port_t *port, nx_eth_tx_request_t *request)

关闭 TX 准入并排空共享 TX 引擎，不重放传输。

备注

任务所有者。取消作用于整个控制器：其他待处理 TX 请求也变为 CANCELLED。绝不撤销借用。源卡住时进入隔离。成功排空后，重新应用已确认的链路事实，才重新开放 TX。

参数:

  • port – [in] 串行任务所有者接口。

  • request – [inout] 由本实例接受且仍存活的请求。

返回:

成功表示请求排空；外来请求返回 STATE。

nx_result_t nx_eth_port_service(const nx_eth_port_t *port)

Task 所有者有界推进；不含执行任务、锁、池或等待。

参数:

  • port – [in] 串行任务所有者接口及存活的存储。

返回:

成功；启动前返回 STATE；或返回无效上下文或输入错误。

nx_result_t nx_eth_port_acquire(const nx_eth_port_t *port, nx_eth_rx_frame_t *frame)

Task 消费者取得完整帧借用；EMPTY 不产生借用。

参数:

  • port – [in] 稳定且已启动的实例，以及一个消费者。

  • frame – [out] 精确且不可变的帧借用，而非对输出存储的借用。

返回:

成功；EMPTY 表示未取得借用；或返回无效状态或上下文错误。

nx_result_t nx_eth_port_release(const nx_eth_port_t *port, const nx_eth_rx_frame_t *frame)

消费者最后一次访问；拒绝过期、外来及重复释放。

备注

已持有的描述符绝不重新 arm，即使环回绕或停止时也不例外。

参数:

  • port – [in] 与取得借用时相同的 provider 标识。

  • frame – [in] 消费者最后一次访问结束后的精确已取得 token。

返回:

成功；token 被修改时返回 STATE；或返回无效输入或上下文错误。

nx_result_t nx_eth_port_state(const nx_eth_port_t *port, nx_eth_state_t *state)

复制锁存的实例／链路／错误事实；不保留输出。

参数:

  • port – [in] 稳定的私有实例。

  • state – [out] 不保留引用的输出，与全部 provider 存储分离。

返回:

成功；输出别名返回 INVALID；或返回 CONTEXT。

应用外部 PHY 观察，不自动协商或虚构链路。

备注

任务所有者；更改速率或双工模式前，必须显式 link-down，并观察到 TX/RX 引擎及 FIFO 空闲。BUSY 保留旧模式。重新应用未改变的 up 事实是幂等操作。link-down 关闭准入，以 IO 排空待处理 TX；后续 up 要求真实静止。这不构成 PHY 电源、复位或电气证明。

参数:

  • port – [in] 串行任务所有者接口。

  • link – [in] 已观察的 up、速率及双工事实，绝非猜测。

返回:

成功；真实排空前返回 BUSY；或返回 STATE/IO/上下文错误。

nx_result_t nx_eth_port_stop(const nx_eth_port_t *port)

关闭准入，通过读回确认撤离 MAC/DMA/IRQ 源。

备注

任务所有者。关闭时拒绝新的 RX 借用；既有借用仍可释放。BUSY 保留硬件、存储及 wake 所有权；超时隔离待处理 TX。已持有的 RX 借用仍有效，必须在 SUCCESS 前释放。调用方回收存储前，须等待 IRQ 及消费者退出。

参数:

  • port – [in] 存活的接口和全部存储，包含已持有借用。

返回:

成功释放各源；BUSY/IO 保留剩余所有权。

nx_result_t nx_eth_port_attach_wake(const nx_eth_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

验证实际 IRQ 策略后绑定可选借用提示。

备注

没有待处理 TX 的任务所有者；notify 必须有界，并在 IRQ 中合法。service 不会在任务中调用 IRQ 提示。停止后再分离。

参数:

  • port – [in] 已启动的串行任务所有者接口。

  • wake – [in] 借用的 IRQ 提示；NULL 表示请求分离。

  • syscall_ceiling – [in] 精确配置的未移位 syscall 数值阈值。

返回:

成功；发布者存活时返回 BUSY；或返回策略或上下文错误。

struct nx_eth_tx_request_t
#include <ethernet.h>

调用者拥有的不可变连续帧，不含硬件 FCS。

公共成员

nx_request_t base
const uint8_t *data
size_t length
#include <ethernet.h>

观察到的 PHY 事实，由外部链路所有者显式供给。

公共成员

struct nx_eth_rx_frame_t
#include <ethernet.h>

完整不可变帧；释放必须匹配准确实例世代。

备注

data 不含 FCS；存储保持存活直到匹配的 release。复制 token 不会建立第二个借用。时间戳为取得时间，不是 SOF。

公共成员

const uint8_t *data
size_t length
size_t slot
const void *identity
uint64_t epoch
nx_time_us_t timestamp_us
struct nx_eth_state_t
#include <ethernet.h>

锁存事实不因接收背压或唤醒提示失败而丢失。

公共成员

uint64_t received
uint64_t discarded
uint64_t unavailable_events
uint32_t receive_flags
size_t pending_tx
size_t held_rx
bool started
bool closing
bool fatal_bus_error
bool transmit_underflow
struct nx_eth_ops_t
#include <ethernet.h>

公共成员

nx_result_t (*submit)(void*, nx_eth_tx_request_t*)
nx_result_t (*cancel)(void*, nx_eth_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*acquire)(void*, nx_eth_rx_frame_t*)
nx_result_t (*release)(void*, const nx_eth_rx_frame_t*)
nx_result_t (*state)(void*, nx_eth_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_eth_port
#include <ethernet.h>

公共成员

const nx_eth_ops_t *ops
void *context

ethernet_frames.h

可选的 scatter-gather 帧及 MAC 时钟借用。

作者 Nexus Team

备注

实物资格验证与软件验证彼此独立。

宏定义

NX_ETH_FRAMES_CAPTURE_CORRUPT

捕获诊断；UNKNOWN 时间戳仍不能用于测量。

函数

nx_result_t nx_eth_frames_tx_prepare(nx_eth_frames_tx_request_t *request, const nx_eth_fragment_t *fragments, size_t fragment_count, bool timestamp, nx_time_us_t deadline)

准备尚未借用的请求存储，不产生硬件效果。

备注

串行任务所有者。验证非空 fragment、溢出及跨 fragment 的完整 Ethernet II 头；允许一个带内 C-tag。不含 FCS 时，无标签长度为 14..1514，带标签长度为 18..1518。由硬件插入填充及 FCS。拒绝以长度编码的 802.3、QinQ 及 0x88A8。失败时保留请求原状，不保留引用。deadline 为 provider 的绝对单调时间，与 PTP 时钟域不同。

nx_result_t nx_eth_frames_port_submit(const nx_eth_frames_port_t *port, nx_eth_frames_tx_request_t *request)

验证全部存储与槽后，才 ACCEPT 一个完整帧。

备注

特权且未屏蔽中断的任务所有者；无池、堆、worker 或 OS 锁。REJECTED 不保留引用或 OWN 效果。ACCEPTED 借用请求、fragment 数组及每段 payload，直到以 acquire 语义观察到 SETTLED。归还一个描述符不证明线上发送完成。仅在已证明 MAC 成功时，transferred 才为完整帧字节数，否则为零。

nx_result_t nx_eth_frames_port_cancel(const nx_eth_frames_port_t *port, nx_eth_frames_tx_request_t *request)

请求控制器范围内的 TX 撤离，不重放。

备注

其他待处理 TX 也会取消；已观察到的线上发送成功可以优先成立。取消绝不撤销借用。缺少排空证明时保留 QUARANTINED 借用。不会复位共享的 MAC/PTP/RX 所有者。

nx_result_t nx_eth_frames_port_service(const nx_eth_frames_port_t *port)

有界的任务进展；IRQ 每次在每个方向上最多处理一个描述符。

nx_result_t nx_eth_frames_port_acquire(const nx_eth_frames_port_t *port, nx_eth_frames_rx_loan_t *loan, nx_eth_fragment_t *fragments, size_t capacity)

按完整帧容量准入，取得一个完整帧。

备注

一个任务消费者。EMPTY 不建立借用；views 太少时返回 OVERFLOW，完整帧仍留在队列中，全部输出不变。停止关闭新取得操作。已持有描述符在回绕或停止时均不重新 arm。

nx_result_t nx_eth_frames_port_release(const nx_eth_frames_port_t *port, const nx_eth_frames_rx_loan_t *loan)

消费者的最终访问；拒绝过期、被修改、外来或重复释放。

nx_result_t nx_eth_frames_port_state(const nx_eth_frames_port_t *port, nx_eth_frames_state_t *state)

将锁存事实复制到不保留的输出；输出与全部借用存储不重叠。

nx_result_t nx_eth_frames_port_clock(const nx_eth_frames_port_t *port, nx_io_timestamp_t *stamp)

在硬件计数器自身时钟域中读取一致的当前计数。

备注

既不提供时钟同步、UTC 映射或 PHY 补偿，也不以取得时间作为回退值。source 为 SERVICE_OBSERVATION，不是 SFD 事件。所有者扩展秒回绕，拒绝回退、溢出及有歧义的间隔；ticks 为纳秒，rate 为 1e9，不确定度未知。

在真实 TX/RX 静默后应用显式的外部 PHY 观察。

nx_result_t nx_eth_frames_port_stop(const nx_eth_frames_port_t *port)

关闭准入，证明 DMA/MAC/IRQ 已撤离后才释放。

备注

已持有的 RX 借用及已取得引用的发布者保留所有权。任何失败均保留未完成租约。不得冲洗非空 TX FIFO 来伪造静止。调用方还须分别等待全部外部生产者、消费者及观察者退出。

nx_result_t nx_eth_frames_port_recover(const nx_eth_frames_port_t *port, nx_time_us_t deadline)

排空失败后，由独占 MAC 所有者显式恢复。

备注

任务所有者；使用有限绝对 deadline。存在已持有 RX 借用或已取得引用的发布者时，返回 BUSY 且不复位。已分离的待处理 TX 以其锁定的终结原因结算前，必须确认复位；没有实际状态时绝不报告线上成功。无自动重放。复位使旧硬件时钟 epoch 失效，并记录 RX 间隙。源失败或超时保留 QUARANTINED 借用及恢复责任。

nx_result_t nx_eth_frames_port_attach_wake(const nx_eth_frames_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

可选的借用 IRQ 提示；验证实际优先级，撤离引用并等待发布者退出。

struct nx_eth_fragment_t
#include <ethernet_frames.h>

不可变的 TX 片段；其字节持续借用至 SETTLED。

公共成员

const uint8_t *data
size_t length
struct nx_eth_vlan_t
#include <ethernet_frames.h>

单个带内 0x8100 C-tag；TCI 使用主机字节序，含 PCP/DEI/VID。

公共成员

uint16_t tci
bool present
struct nx_eth_frames_tx_request_t
#include <ethernet_frames.h>

一个完整 L2 帧，不含前导码、硬件填充和硬件 FCS。

备注

ACCEPTED 后，fragment 数组及每个 fragment 均保持借用。请求 TX 捕获是可选的：即使线上成功，时间戳仍可能不可用或损坏。仅在以 acquire 语义观察到 SETTLED 后读取时间戳。

公共成员

nx_request_t base
const nx_eth_fragment_t *fragments
size_t fragment_count
bool timestamp_requested
nx_io_timestamp_t stamp
uint32_t capture_flags
struct nx_eth_frames_rx_loan_t
#include <ethernet_frames.h>

一个帧全部描述符上的完整接收借用。

备注

输出 fragment views 不包含 FCS，即使 FCS 跨越两个缓冲区。views 数组是不保留引用的输出；底层字节在精确 release 前保持不可变。复制此 token 不建立借用。

公共成员

const void *identity
uint64_t epoch
size_t first_slot
size_t descriptor_count
size_t fragment_count
size_t length
nx_time_us_t acquired_us
nx_io_timestamp_source_t acquired_source
nx_eth_vlan_t vlan
nx_io_timestamp_t stamp
uint32_t capture_flags
struct nx_eth_frames_state_t
#include <ethernet_frames.h>

锁存的引擎事实与选定时钟 epoch，不是协议状态。

公共成员

nx_eth_state_t mac
uint32_t clock_epoch
uint64_t receive_gaps
uint32_t timestamp_resolution_ns
bool quarantined
struct nx_eth_frames_ops_t
#include <ethernet_frames.h>

公共成员

nx_result_t (*submit)(void*, nx_eth_frames_tx_request_t*)
nx_result_t (*cancel)(void*, nx_eth_frames_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*acquire)(void*, nx_eth_frames_rx_loan_t*, nx_eth_fragment_t*, size_t)
nx_result_t (*release)(void*, const nx_eth_frames_rx_loan_t*)
nx_result_t (*state)(void*, nx_eth_frames_state_t*)
nx_result_t (*clock)(void*, nx_io_timestamp_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*, nx_time_us_t)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_eth_frames_port
#include <ethernet_frames.h>

公共成员

const nx_eth_frames_ops_t *ops
void *context

exti.h

静态 EXTI 线路绑定、有界事件存储与排空。

作者 Nexus Team

宏定义

NX_EXTI_EVENT_LOSS
NX_EXTI_EVENT_COALESCED

枚举

enum nx_exti_edge_t

取值：

enumerator NX_EXTI_RISING
enumerator NX_EXTI_FALLING
enumerator NX_EXTI_BOTH

函数

nx_result_t nx_exti_port_read(const nx_exti_port_t *port, nx_exti_event_t *events, size_t capacity, size_t *count)

从准确静态线路绑定读取排队 EXTI 事件。

参数:

  • port – [inout] 一个消费者；按配置有界的 IRQ 生产者存储。

  • events – [out] 调用方目的存储，绝不保留引用。

  • capacity – [in] 目的事件数量。

  • count – [out] 已复制事件；可通过事件标志观察丢失。

返回:

成功、EMPTY 或 INVALID。不提供消抖策略或回调。

nx_result_t nx_exti_port_stop(const nx_exti_port_t *port)

禁用线路源、清除 pending 并排空处理函数。

备注

撤回失败时，可能已经禁用了部分源。回收事件或 wake 存储前须重试并观察到成功。共享派发域仍引用接口或状态期间，二者均须保持存活。

参数:

  • port – [inout] 执行所有者；消费者及写入者必须先静止。

返回:

成功证明不再访问事件存储；BUSY 或 IO 保留存储、wake 目标及清理责任。共享向量保留其他线路。

nx_result_t nx_exti_port_attach_wake(const nx_exti_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

附加或解除显式事件／丢失 IRQ 唤醒目标。

备注

实际共享向量优先级必须满足目标要求。释放旧目标存储前，先停止并等待发布者退出。wake 回调观察的是已锁存的事件或丢失事实。

参数:

  • port – [in] 已初始化的 line，由一个任务执行者控制。

  • wake – [in] 不可变且存活的目标；NULL 表示分离。

  • syscall_ceiling – [in] 可选的额外未移位内核安全优先级数值下限；不得削弱生成策略。PRIMASK 内核目标要求为零。不调用内核时忽略。

返回:

成功或 CONTEXT/STATE/PERMISSION/UNSUPPORTED。

struct nx_exti_event_t
#include <exti.h>

边沿事实；时间戳精度与合并行为由提供者决定。

备注

LOSS 是独立边界，排在较旧缓冲事实之后、后续事实之前。其 edge 无效；时间戳为检测或报告时间，绝不重建丢失边沿。对于 COALESCED 事实，edge 可能由 IRQ 后采样的引脚电平推导，不代表完整边沿历史。

公共成员

nx_time_us_t timestamp_us
uint32_t flags
uint8_t line
nx_exti_edge_t edge
struct nx_exti_ops_t
#include <exti.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*read)(void *context, nx_exti_event_t *events, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_exti_port
#include <exti.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_exti_ops_t *ops
void *context

flash.h

完整物理 Flash 几何与显式有界区域。

作者 Nexus Team

枚举

enum nx_flash_program_flags

超出单元对齐要求的物理编程约束。

取值：

enumerator NX_FLASH_PROGRAM_REQUIRES_FRESH_ERASE

函数

const nx_flash_geometry_t *nx_flash_port_geometry(const nx_flash_port_t *port)

无副作用地查询准确物理 Flash 几何。

参数:

  • port – [in] 选中的精确密度物理 Flash provider。

返回:

不可变几何信息；端口无效时返回 NULL。

nx_result_t nx_flash_port_read(const nx_flash_port_t *port, uint32_t offset, void *data, size_t length)

有界读取物理 Flash，不保留目标存储。

参数:

  • port – [in] 固定 provider；不得并发擦除或编程。

  • offset – [in] 物理相对偏移。

  • data – [out] 目标存储；返回后不再保留。

  • length – [in] 字节数；为零时允许 data 为 NULL。

返回:

成功或 INVALID；范围被拒绝或发生回绕时不进行访问。

nx_result_t nx_flash_port_program(const nx_flash_port_t *port, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)

对齐编程物理 Flash，并结清全部硬件脉冲。

备注

仅限任务上下文、由 CPU 主动执行的操作。从 Flash 执行时的停顿、看门狗和掉电策略由产品负责。MCU 上不以 RAM 模拟 Flash。

备注

使用 NX_FLASH_PROGRAM_REQUIRES_FRESH_ERASE 时，每个待编程单元必须经过成功擦除，且擦除后尚未经历任何编程脉冲。在带 ECC 的 Flash 上，读到全 0xff 不能证明这一点。失败或中断的脉冲会消耗该单元，直到下次成功擦除所属扇区。调用方负责此来源证明；provider 不维护隐式擦除历史位图。

备注

输入全为 0xff 的单元不得触发编程脉冲。provider 可以拒绝从可见内容判断尚未擦除的目标。

参数:

  • port – [inout] 具有有效电压/时钟策略的唯一执行所有者。

  • offset – [in] 按编程单元对齐的物理偏移。

  • data – [in] 长度已对齐的输入，仅借用到返回。

  • length – [in] 正的编程单元整数倍。

  • deadline – [in] 在硬件脉冲之间检查的绝对 deadline。

返回:

成功或 INVALID/TIMEOUT/IO。返回证明已无缓冲区或硬件访问；已开始的脉冲不能被抢占。

nx_result_t nx_flash_port_erase(const nx_flash_port_t *port, uint32_t offset, size_t length, nx_time_us_t deadline)

擦除完整物理扇区范围，并结清脉冲。

参数:

  • port – [inout] 唯一执行所有者。

  • offset – [in] 精确位于扇区起点的物理偏移。

  • length – [in] 若干完整扇区长度之和，且为正值。

  • deadline – [in] 在擦除脉冲之间检查的绝对 deadline。

返回:

成功或 INVALID/TIMEOUT/IO；超时或错误可能只完成部分擦除。返回前等待当前脉冲进入空闲。

nx_result_t nx_flash_region_validate(const nx_flash_region_t *region)

根据物理几何验证区域边界。

参数:

  • region – [in] 调用方显式持有的区域描述。

返回:

成功或 INVALID；每次操作分别检查擦除几何。

nx_result_t nx_flash_region_read(const nx_flash_region_t *region, uint32_t offset, void *data, size_t length)

在显式物理区域内读取。

参数:

  • region – [in] 有效区域。

  • offset – [in] 相对于区域的字节偏移。

  • data – [out] 目标缓冲区。

  • length – [in] 字节数。

返回:

成功或 INVALID，不访问区域以外的地址。

nx_result_t nx_flash_region_program(const nx_flash_region_t *region, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)

在显式可写物理区域内编程。

参数:

  • region – [in] 有效且可写的区域。

  • offset – [in] 相对于区域的已对齐偏移。

  • data – [in] 输入缓冲区；仅借用到返回。

  • length – [in] 已对齐的正长度。

  • deadline – [in] 绝对脉冲 deadline。

返回:

成功、INVALID/PERMISSION 或底层脉冲操作的结果。

nx_result_t nx_flash_region_erase(const nx_flash_region_t *region, uint32_t offset, size_t length, nx_time_us_t deadline)

在可写区域内擦除完整物理扇区。

参数:

  • region – [in] 显式有效且可写的区域。

  • offset – [in] 相对于区域的扇区边界。

  • length – [in] 完整扇区长度之和。

  • deadline – [in] 绝对脉冲 deadline。

返回:

成功、INVALID/PERMISSION 或底层脉冲操作的结果。

struct nx_flash_sector_t
#include <flash.h>

擦除扇区几何，偏移相对于完整物理 Flash。

公共成员

uint32_t offset
uint32_t size
struct nx_flash_geometry_t
#include <flash.h>

只读物理几何；平台不预留产品存储。

备注

program_flags 声明额外的单元要求。零值不免除所选 provider 的编程规则。

公共成员

uint32_t base_address
uint32_t size
uint32_t program_unit
const nx_flash_sector_t *sectors
size_t sector_count
uint32_t program_flags
struct nx_flash_region_t
#include <flash.h>

消费者显式选择的边界，不含隐式产品分区。

公共成员

const nx_flash_port_t *port
uint32_t offset
uint32_t size
bool writable
struct nx_flash_ops_t
#include <flash.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

const nx_flash_geometry_t *(*geometry)(const void *context)
nx_result_t (*read)(const void *context, uint32_t offset, void *data, size_t length)
nx_result_t (*program)(void *context, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)
nx_result_t (*erase)(void *context, uint32_t offset, size_t length, nx_time_us_t deadline)
struct nx_flash_port
#include <flash.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_flash_ops_t *ops
void *context

fwd.h

类型化 I/O face 的轻量身份。

作者 Nexus Team

备注

访问其布局、操作、请求或值类型前，须包含对应公共头文件。前置身份既不构造也不取得任何设备。

类型定义

typedef struct nx_adc_group_port nx_adc_group_port_t

不透明身份；完整合同位于其公共头文件。

typedef struct nx_adc_port nx_adc_port_t
typedef struct nx_advanced_pwm nx_advanced_pwm_t
typedef struct nx_can_fd_port nx_can_fd_port_t
typedef struct nx_can_port nx_can_port_t
typedef struct nx_encoder nx_encoder_t
typedef struct nx_eth_frames_port nx_eth_frames_port_t
typedef struct nx_eth_port nx_eth_port_t
typedef struct nx_exti_port nx_exti_port_t
typedef struct nx_flash_port nx_flash_port_t
typedef struct nx_gpio_port nx_gpio_port_t
typedef struct nx_i2c_endpoint nx_i2c_endpoint_t
typedef struct nx_i2c_long_endpoint nx_i2c_long_endpoint_t
typedef struct nx_i2c_port nx_i2c_port_t
typedef struct nx_lptim_port nx_lptim_port_t
typedef struct nx_mdio_port nx_mdio_port_t
typedef struct nx_pin_state_port nx_pin_state_port_t
typedef struct nx_pwm_adc nx_pwm_adc_t
typedef struct nx_pwm_group nx_pwm_group_t
typedef struct nx_pwm_port nx_pwm_port_t
typedef struct nx_rtc_port nx_rtc_port_t
typedef struct nx_spi_dma_transaction_endpoint nx_spi_dma_transaction_endpoint_t
typedef struct nx_spi_dma_transaction_port nx_spi_dma_transaction_port_t
typedef struct nx_spi_endpoint nx_spi_endpoint_t
typedef struct nx_spi_port nx_spi_port_t
typedef struct nx_spi_transaction_endpoint nx_spi_transaction_endpoint_t
typedef struct nx_timer_capture nx_timer_capture_t
typedef struct nx_uart_port nx_uart_port_t
typedef struct nx_uart_word_port nx_uart_word_port_t
typedef struct nx_usb_activation_port nx_usb_activation_port_t
typedef struct nx_usb_device_port nx_usb_device_port_t
typedef struct nx_usb_endpoint_port nx_usb_endpoint_port_t
typedef struct nx_watchdog_port nx_watchdog_port_t

gpio.h

固定 GPIO 授权掩码与有界端口操作。

作者 Nexus Team

函数

nx_result_t nx_gpio_port_write(const nx_gpio_port_t *port, uint32_t set_mask, uint32_t reset_mask)

原子设置／复位一个端口的授权输出掩码。

备注

任务/IRQ 中均有界且不等待。一个串行化写入者拥有此绑定。停止或切换模式前必须使写入者及 IRQ 静默。

参数:

  • port – [in] 固定且已初始化的绑定，无注册表或 OS 锁。

  • set_mask – [in] 获授权的置位位集。

  • reset_mask – [in] 获授权的复位位集；须与 set_mask 不相交。

返回:

返回 NX_SUCCESS，或在任何寄存器写入前返回 INVALID/PERMISSION。

nx_result_t nx_gpio_port_read(const nx_gpio_port_t *port, uint32_t *value)

读取受绑定掩码限制的单次输入快照。

参数:

  • port – [in] 固定且已初始化的绑定。

  • value – [out] 掩码处理后的输入快照；错误时保持不变。

返回:

返回 NX_SUCCESS 或 NX_ERROR_INVALID。不保证跨端口同时采样。

nx_result_t nx_gpio_port_toggle(const nx_gpio_port_t *port, uint32_t mask)

在单写者合同下翻转授权输出。

备注

相对于无关写入，读改写不是原子操作。

参数:

  • port – [in] 具有串行化写入者的固定输出绑定。

  • mask – [in] 获授权、需要翻转的子集。

返回:

返回 NX_SUCCESS，或在寄存器写入前返回 INVALID/PERMISSION。

struct nx_gpio_ops_t
#include <gpio.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*write)(void *context, uint32_t set_mask, uint32_t reset_mask)
nx_result_t (*read)(const void *context, uint32_t *value)
nx_result_t (*toggle)(void *context, uint32_t mask)
struct nx_gpio_port
#include <gpio.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_gpio_ops_t *ops
void *context

i2c.h

地址端点、重复 START 与显式 STOP 结清。

作者 Nexus Team

宏定义

NX_I2C_MAX_MESSAGES

维护范围内的有限消息准入边界，访问硬件之前检查。

NX_I2C_MAX_MESSAGE_BYTES

函数

nx_result_t nx_i2c_endpoint_transaction(const nx_i2c_endpoint_t *endpoint, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)

执行一个轮询、7 位地址消息事务。

备注

仅限任务上下文，由一个执行者负责。没有隐式扫描或 GPIO 恢复。总线恢复失败绝不报告为传输成功。

参数:

  • endpoint – [in] 固定的地址/控制器绑定。

  • messages – [inout] 消息缓冲区；写入方向的数据不会被修改。

  • count – [in] 1..NX_I2C_MAX_MESSAGES 条。

  • deadline – [in] provider 时钟域中的有限绝对 deadline。

  • transferred – [out] provider 跨消息记录的字节进度，错误返回时也提供。TX 可能已统计交给数据寄存器的字节，而此时尚不知道线上传输或 ACK 结果。

返回:

成功或 INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/NACK/ARBITRATION/IO。每条消息包含 1..NX_I2C_MAX_MESSAGE_BYTES 字节，可独立选择读或写。返回前完成 STOP/中止排空并归还缓冲区。控制器结清不代表总线已恢复。

nx_result_t nx_i2c_port_recover(const nx_i2c_port_t *port)

总线故障后恢复空闲控制器。

参数:

  • port – [inout] 唯一执行者；不存在活跃事务或缓冲区借用。

返回:

仅观察到硬件总线空闲时成功；否则返回 BUSY/IO/UNSUPPORTED。不重放失败事务。

nx_result_t nx_i2c_request_prepare(nx_i2c_request_t *request, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline)

准备未借用请求，不复制载荷。

备注

payload 不得与控制存储重叠，读取范围也不得与不可变的写入范围重叠。限制与轮询模式一致。

参数:

  • request – [inout] 已初始化的 READY 存储，或已消费的 SETTLED 存储

  • messages – [inout] 1..8 个完整描述符

  • count – [in] 精确的描述符数量

  • deadline – [in] provider 时钟域中的绝对 deadline

返回:

返回 SUCCESS、INVALID、UNSUPPORTED 或 STATE；不产生新借用

nx_result_t nx_i2c_request_validate(const nx_i2c_request_t *request)

验证有限描述符以及载荷／控制存储分离。

备注

有界冷态检查。provider 在取得任何借用前另行验证状态、上下文及 DMA 域。

参数:

  • request – [in] 完整且由调用方持有的请求，不予保留

返回:

返回 SUCCESS、INVALID 或 UNSUPPORTED，不修改输入

nx_result_t nx_i2c_endpoint_submit(const nx_i2c_endpoint_t *endpoint, nx_i2c_request_t *request)

准入一个有限、异步、重复 START 事务。

备注

选中模式声明 DMA 域。仅 DMA 完成不能证明线上/STOP 排空或借用归还。任何已接受的中止均须先显式本地恢复才能复用；恢复不重放事务，也不在 Board GPIO 上产生脉冲。

参数:

  • endpoint – [in] 已初始化的固定地址及唯一执行者

  • request – [inout] READY 描述符及其引用的全部存储

返回:

SUCCESS 表示 ACCEPTED；拒绝不保留任何引用

nx_result_t nx_i2c_endpoint_start_admitted(const nx_i2c_endpoint_t *endpoint, nx_i2c_request_t *request)

启动已借用的 QUEUED 请求，不重复准入。

备注

其他错误要求由适配器结清；不回退为轮询。

参数:

  • endpoint – [in] 位于适配器精确控制器上的固定地址

  • request – [inout] 经适配器准入的 QUEUED 存储

返回:

SUCCESS 将执行权交给 provider；BUSY 保持 QUEUED

bool nx_i2c_endpoint_on_port(const nx_i2c_endpoint_t *endpoint, const nx_i2c_port_t *port)

证明控制器身份，不产生硬件效果。

参数:

  • endpoint – [in] 不可变的带地址子对象

  • port – [in] 精确的执行控制器

返回:

仅当 provider 状态匹配且方法兼容时为真

nx_result_t nx_i2c_port_cancel(const nx_i2c_port_t *port, nx_i2c_request_t *request)

请求取消，不回收任何存储。

参数:

  • port – [in] 与 submit/service 相同的唯一执行者

  • request – [inout] 精确的活跃描述符，不得使用陈旧裸指针

返回:

SUCCESS 开始排空；其他请求返回 STATE

void nx_i2c_port_service(const nx_i2c_port_t *port)

在有界 Task 上下文处理截止时间，并推进 STOP/DMA 排空。

备注

最终发布发生在来源分离及本地线上空闲之后。排空失败会隔离全部存储。不调用 payload 完成回调，也绝不自动重放。

参数:

  • port – [in] 仍然有效的唯一执行者，在整个停止过程中持续调用 service

nx_result_t nx_i2c_port_stop(const nx_i2c_port_t *port)

关闭准入，全部借用者排空后才停止。

参数:

  • port – [in] 外部生产者已静默的控制器

返回:

SUCCESS 证明来源已撤回；BUSY 要求继续 service

nx_result_t nx_i2c_port_attach_wake(const nx_i2c_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

检查实际 IRQ 策略后附加一个可选提示接收端。

备注

仅限任务上下文。sink 须保持有效，直到成功停止或分离。

参数:

  • port – [in] 已初始化的异步控制器

  • wake – [in] 借用的 sink；或在发布者退出后使用 NULL 分离

  • syscall_ceiling – [in] 不得削弱选中的内核策略

返回:

返回 SUCCESS，或在替换任何活跃绑定前拒绝

struct nx_i2c_message_t
#include <i2c.h>

一个消息；新消息以重复 START 开始，最后以 STOP 结束。

公共成员

uint8_t *data
size_t length
bool read
struct nx_i2c_request_t
#include <i2c.h>

调用者拥有的有限消息序列。

备注

描述符与 payload 保持借用直到 SETTLED。写入数据保持不可变；读取数据写入调用方存储。取消、deadline 和隔离均不撤销借用。

公共成员

nx_request_t base
nx_i2c_message_t *messages
size_t count
struct nx_i2c_ops_t
#include <i2c.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*recover)(void *context)
nx_result_t (*cancel)(void *context, nx_i2c_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_i2c_port
#include <i2c.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_i2c_ops_t *ops
void *context
struct nx_i2c_endpoint_ops_t
#include <i2c.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*transaction)(void *context, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)
nx_result_t (*submit)(void *context, nx_i2c_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_i2c_request_t *request)
bool (*on_port)(const void *context, const nx_i2c_port_t *port)
struct nx_i2c_endpoint
#include <i2c.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_i2c_endpoint_ops_t *ops
void *context

i2c_bus_clear.h

显式开漏 I2C 总线清理，保留租约。

作者 Nexus Team

宏定义

NX_I2C_BUS_CLEAR_MAX_PULSES

每次尝试中允许完成的恢复低／高电平周期上限。

函数

nx_result_t nx_i2c_bus_clear_init(nx_i2c_bus_clear_t *clear, nx_i2c_bus_clear_port_t port, nx_clock_t clock, nx_i2c_bus_clear_timing_t timing)

绑定显式电气操作，不接触引脚。

参数:

  • clear – [inout] 新的清零会话，或没有租约的会话。

  • port – [in] 必须具备全部五个方法；调用方须验证电气授权，不能依赖通用 GPIO API 推定。

  • clock – [in] 必需的、有界的同一启动域内单调时间读取。

  • timing – [in] 已审查且非零的低电平/高电平/STOP/轮询时长。

返回:

返回 SUCCESS、INVALID，或因保留租约而返回 BUSY。拒绝使会话及外部资源保持不变。

nx_result_t nx_i2c_bus_clear_run(nx_i2c_bus_clear_t *clear, nx_time_us_t deadline, nx_time_us_t cleanup_deadline, nx_i2c_bus_clear_result_t *result)

用至多九个脉冲清理一个空闲、已授权总线。

备注

仅限任务上下文，其他总线使用者均已静默。时序证据及实际开漏行为需要物理 HIL。

参数:

  • clear – [inout] 已初始化且无保留租约的会话。

  • deadline – [in] 主要操作的有限绝对 deadline。

  • cleanup_deadline – [in] 同一时钟域中的有限绝对 STOP/租约 deadline，不得早于 deadline。

  • result – [out] 独立的主要/清理结果及保留效果。

返回:

主要操作失败时返回该失败，否则返回清理结果。无效输入或已有租约会被拒绝，不调用回调，也不改变 result。主要 deadline 已到期时不产生引脚效果。每次释放 SCL 后，必须先观察到物理 HIGH，再计其高电平时长。时钟冻结或倒退时报告 IO 并退出，不持续空转。每次已取得所有权的尝试均在独立预算内显式执行 STOP 清理；STOP 或 release 方法失败会保留租约。若 release 在其 deadline 之后成功，清理报告 TIMEOUT，但 lease_held 为 false，以保留实际已经归还所有权的事实。绝不重放失败的 I2C 事务，也不重试恢复脉冲。

nx_result_t nx_i2c_bus_clear_finish(nx_i2c_bus_clear_t *clear, nx_time_us_t deadline, nx_i2c_bus_clear_result_t *result)

仅重试保留的 STOP 清理与所有权归还。

参数:

  • clear – [inout] 已初始化且保留租约的会话。

  • deadline – [in] 新的有限绝对清理 deadline。

  • result – [out] 保留的主要结果/脉冲数及最新清理结果。

返回:

返回最新清理结果；INVALID/STATE 拒绝且无效果。release 失败后，不重复已经证明完成的 STOP。失败保留租约，不得因此开始新的总线清理或事务。成功不会将主要操作的失败改为成功。

struct nx_i2c_bus_clear_ops_t
#include <i2c_bus_clear.h>

授权双引脚 GPIO 交接的只读方法。

备注

仅限任务上下文，由一个执行者负责。acquire 是有界、非阻塞的交接：成功证明控制器、DMA、IRQ、其他主机及引脚使用者均已静默；两个物理引脚已按审查过的开漏 GPIO 模式独占租用，且两根线均已释放。失败不保留租约或效果。drive 只拉 LOW 或释放引脚；false 绝不表示主动驱动 HIGH。scl_low 为 true 时，drive 先建立 SCL LOW，再改变 SDA，包括从未知先前引脚状态重试的情况。sample 读取物理电平，而不是输出锁存值。方法均有界，错误时保留租约。release 仅在成功时恢复保存的外设/引脚所有权；失败保留全部租约/存储责任。wait_until 使用注入时钟中的有限绝对时间域，即使时钟停止，也须在调用方已证明的有限上界内到达 target 或报告错误。迟到的等待不能使已到期操作获得资格。任何回调均不得递归操作本会话或运行事务。适配器在 acquire 前必须验证经过审查的开漏、上拉、电压及双引脚授权事实。

公共成员

nx_result_t (*acquire)(void *context)
nx_result_t (*drive)(void *context, bool scl_low, bool sda_low)
nx_result_t (*sample)(void *context, bool *scl_high, bool *sda_high)
nx_result_t (*wait_until)(void *context, nx_time_us_t target)
nx_result_t (*release)(void *context)
struct nx_i2c_bus_clear_port_t
#include <i2c_bus_clear.h>

显式不可变 GPIO 方法与调用者拥有的适配器状态。

公共成员

const nx_i2c_bus_clear_ops_t *ops
void *context
struct nx_i2c_bus_clear_timing_t
#include <i2c_bus_clear.h>

调用者选择的电气时序，单位为微秒。

备注

全部字段均非零。low/high 约束每个清理脉冲；stop_setup 约束观察到 SCL 高电平至释放 SDA 的间隔。stretch_poll 约束实际 SCL 采样之间的间隔。这些值需要板卡/器件电气审查；机制不提供通用安全默认值。

公共成员

uint32_t low_us
uint32_t high_us
uint32_t stop_setup_us
uint32_t stretch_poll_us
struct nx_i2c_bus_clear_result_t
#include <i2c_bus_clear.h>

分别记录恢复结果与 STOP／所有权归还结果。

备注

pulses 统计已完成的恢复低/高电平周期，不统计准备 STOP 的边沿。stop_observed 证明请求的 STOP 序列结束时，两根线的采样均为 HIGH。lease_held 表示适配器、会话及上下文必须保持有效，且不得启动控制器事务。清理失败绝不替换主要失败。

公共成员

nx_result_t primary
nx_result_t cleanup
uint8_t pulses
bool stop_observed
bool lease_held
struct nx_i2c_bus_clear_t
#include <i2c_bus_clear.h>

调用者拥有、零初始化的单执行者会话。

备注

公共字段用于机制内部存储，不是调用方控制项。方法、上下文及 clock 的生命周期覆盖每个保留租约。不存在分配、worker、锁、事务缓冲区或隐式重试。放弃保留租约必须显式承接产品隔离/复位责任。

公共成员

nx_i2c_bus_clear_port_t port
nx_clock_t clock
nx_i2c_bus_clear_timing_t timing
nx_i2c_bus_clear_result_t result
nx_time_us_t last_time
bool clock_observed
bool initialized

i2c_long.h

可选的有界 I2C 长消息，不产生额外 START。

作者 Nexus Team

宏定义

NX_I2C_LONG_MAX_MESSAGE_BYTES

函数

nx_result_t nx_i2c_long_messages_validate(const nx_i2c_message_t *messages, size_t count)

取得任何硬件之前验证完整消息。

备注

每条消息包含 1..65535 字节。可修改的读取范围不得与写入范围或描述符存储重叠。写入数据和描述符在整个事务期间保持不可变。

参数:

  • messages – [in] 调用方持有的有限描述符及数据

  • count – [in] 1..NX_I2C_MAX_MESSAGES 条

返回:

返回 SUCCESS、INVALID 或 UNSUPPORTED；不保留任何引用

nx_result_t nx_i2c_long_endpoint_transaction(const nx_i2c_long_endpoint_t *endpoint, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)

执行有限消息，不拆分地址阶段。

备注

仅限任务上下文，与基础 I2C 共用一个执行者。每条消息发出一次 START；只有后续消息发出重复 START。硬件 reload 不拆分消息。最终 STOP 和总线空闲观察先于成功返回。失败绝不重放前缀。中止排空失败时，不能返回并归还借用存储。不执行隐式总线恢复。

参数:

  • endpoint – [in] 选中的可选长消息 provider

  • messages – [inout] 借用至返回的描述符和缓冲区

  • count – [in] 1..NX_I2C_MAX_MESSAGES 条

  • deadline – [in] provider 时钟域中的有限绝对 deadline

  • transferred – [out] 包含失败情况的寄存器字节进度；TX 计数不能证明这些字节已在线上获得 ACK

返回:

本地控制器排空后返回 SUCCESS 或 INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/NACK/ARBITRATION/IO

struct nx_i2c_long_ops_t
#include <i2c_long.h>

共享只读的可选长消息实现。

公共成员

nx_result_t (*transaction)(void *context, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)
struct nx_i2c_long_endpoint
#include <i2c_long.h>

可选不可变接口；控制器状态与基础 I2C 共享。

备注

接口和私有上下文的生命周期覆盖所有调用方。不拥有队列或堆。

公共成员

const nx_i2c_long_ops_t *ops
void *context

lptim.h

在独立 tick 域中执行有限的 16 位计数。

作者 Nexus Team

函数

nx_result_t nx_lptim_request_prepare(nx_lptim_request_t *request, const nx_lptim_domain_t *domain, uint32_t ticks, nx_time_us_t deadline)

把复制的计数元数据准备到已初始化且未借用的存储中。

备注

完整存储范围必须对齐、不发生地址回绕且互不重叠。该操作不建立借用、不访问时钟、不转换单位，也不证明物理速率。

参数:

  • request – [inout] READY 或结果已消费的 SETTLED 存储，且所有观察者均已 join。

  • domain – [in] 在此复制独立、非零的 owner／代次值。

  • ticks – [in] 精确的正计数，范围为 1..65536，单位是该域的 tick。

  • deadline – [in] 绝对 Core 单调 deadline 或 NX_DEADLINE_NEVER。

返回:

SUCCESS 或 INVALID/STATE；失败保持请求的每个字节不变。

nx_result_t nx_lptim_port_sample(const nx_lptim_port_t *port, nx_lptim_sample_t *sample)

由一个任务 owner 复制当前计数域和声明单位。

备注

开放且空闲时报告计数器为零且未运行。此有限接口不恢复未观察到的回绕，也不提供绝对时钟。

参数:

  • port – [in] 串行访问的只读接口面；不允许并发模型／生命周期操作。

  • sample – [out] 独立、对齐且可写的快照。

返回:

SUCCESS、关闭时的 STATE 或 INVALID/UNSUPPORTED；拒绝时输出不变。

nx_result_t nx_lptim_port_submit(const nx_lptim_port_t *port, nx_lptim_request_t *request)

完成空闲／域／范围检查后借用一个 READY 计数请求。

备注

有限 deadline 已到期时，在产生请求源效果前返回 TIMEOUT。接受请求前预留最终不回绕的域递增：EXHAUSTED 绝不丢弃此前已经接受的借用。时钟上下文生命周期、完整范围／不重叠及不可重入由装配方负责。

参数:

  • port – [in] 同一个串行 owner，持有复制的外部 Core 时钟接口面。

  • request – [inout] 调用方请求；没有队列或隐藏 worker。

返回:

SUCCESS 表示 ACCEPTED；INVALID/STATE/BUSY/TIMEOUT/EXHAUSTED/UNSUPPORTED 表示拒绝，不保留引用或效果。

nx_result_t nx_lptim_port_cancel(const nx_lptim_port_t *port, nx_lptim_request_t *request)

接受取消，但保持借用直到证明已撤源。

备注

cancel／stop 可以在尚未观察到事件／到期之前先锁存原因。首次原因保持不变；transferred 记录真实撤源时最终的请求源进度。

参数:

  • port – [in] 同一个串行执行者；没有隐式跨任务锁。

  • request – [inout] 精确的活动请求身份；不读取其他请求身份指向的存储。

返回:

SUCCESS 仍可能表示 QUARANTINED；拒绝返回 STATE/INVALID/UNSUPPORTED。

nx_result_t nx_lptim_port_service(const nx_lptim_port_t *port)

观察 deadline／事件，并继续有界的真实撤源。

备注

首次观察到的到期优先于 pending 完成事件。最终以 release 发布 SETTLED 前，清除全部请求源、pending 和 owner 引用。

参数:

  • port – [in] 同一个串行任务 owner；不隐式推进请求源。

返回:

空闲／已结清时返回 SUCCESS，活动或撤源被 hold 阻止时返回 BUSY；INVALID/STATE/UNSUPPORTED 可以拒绝分发。

nx_result_t nx_lptim_port_stop(const nx_lptim_port_t *port)

关闭准入；取消／到期绝不是借用已归还的证明。

备注

重复执行已完成的干净 stop 是安全的；它不重置代次或生命周期。tick 速率／请求源和备份／Stop／VBAT 连续性需要独立硬件合同；此接口不建立这些验证资格。

参数:

  • port – [in] 串行 owner，且所有外部发布者均已静止。

返回:

脱离引用后返回 SUCCESS，BUSY 保留隔离存储；INVALID/STATE/UNSUPPORTED 可以拒绝分发。

struct nx_lptim_domain_t
#include <lptim.h>

owner 与不回绕的计数代次，绝不是 RTC/Core token。

备注

仅比较身份，不解引用。结束 owner 存储生命周期或复用其地址前，必须退役所有 token／观察者。

公共成员

const void *identity
uint64_t generation
struct nx_lptim_sample_t
#include <lptim.h>

声明单位与模计数值，不是绝对时间估计。

备注

完整的 65536 tick 计数会把计数器回绕到零。单凭计数器为零不能证明完成、空闲、遗漏回绕或低功耗连续性。tick_hz 是固定声明速率，不是物理振荡器精度。

公共成员

nx_lptim_domain_t domain
uint32_t tick_hz
uint16_t counter
bool running
struct nx_lptim_request_t
#include <lptim.h>

一次由调用方持有的有限计数；transferred 是最终观察到的 tick 数。

备注

先初始化 base。ACCEPTED 后，保持整个请求有效且调用方不可修改，直到以 acquire 观察到 SETTLED 并完成外部 join。锁存的 CANCELLED/TIMEOUT 固定终止原因，而不是最终进度：撤源被 hold 阻止时，脱离前请求源仍可能继续累计 tick。

公共成员

nx_request_t base
nx_lptim_domain_t domain
uint32_t ticks
struct nx_lptim_ops_t
#include <lptim.h>

共享只读方法实现相应公共合同。

公共成员

nx_result_t (*sample)(const void *context, nx_lptim_sample_t *sample)
nx_result_t (*submit)(void *context, nx_lptim_request_t *request)
nx_result_t (*cancel)(void *context, nx_lptim_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_lptim_port
#include <lptim.h>

只读双指针接口面；provider 存储保持私有。

公共成员

const nx_lptim_ops_t *ops
void *context

mdio.h

使用绝对截止时间的窄接口 Clause22 站点管理。

作者 Nexus Team

函数

nx_result_t nx_mdio_read(const nx_mdio_port_t *port, uint8_t address, uint8_t reg, uint16_t *value, nx_time_us_t deadline)

读取一个 Clause22 PHY 寄存器，不保留输出存储。

备注

串行化的特权任务调用，进入时中断屏蔽均清除；deadline 是 provider 时钟域中的有限绝对时间。地址和寄存器均为 0..31。BUSY 在产生新 MMIO 效果前拒绝；超时不伪称 busy 已清除。

参数:

  • port – [in] 稳定的接口及调用方持有的执行上下文。

  • address – [in] Clause22 PHY 地址，0..31。

  • reg – [in] Clause22 寄存器地址，0..31。

  • value – [out] 仅在及时观察到完成后写入。

  • deadline – [in] provider 时钟域中的有限绝对 deadline。

返回:

成功、不发出新命令的 BUSY，或超时/输入/上下文错误。

nx_result_t nx_mdio_write(const nx_mdio_port_t *port, uint8_t address, uint8_t reg, uint16_t value, nx_time_us_t deadline)

写入一个 Clause22 PHY 寄存器，不实现特定 PHY 策略序列。

备注

与 read 相同的任务/deadline 规则。不在屏蔽 IRQ 时忙等，也不回退。

参数:

  • port – [in] 稳定的接口及调用方持有的执行上下文。

  • address – [in] Clause22 PHY 地址，0..31。

  • reg – [in] Clause22 寄存器地址，0..31。

  • value – [in] 精确的 16 位寄存器值。

  • deadline – [in] provider 时钟域中的有限绝对 deadline。

返回:

成功、不发出新命令的 BUSY，或超时/输入/上下文错误。

struct nx_mdio_ops_t
#include <mdio.h>

公共成员

nx_result_t (*read)(void*, uint8_t, uint8_t, uint16_t*, nx_time_us_t)
nx_result_t (*write)(void*, uint8_t, uint8_t, uint16_t, nx_time_us_t)
struct nx_mdio_port
#include <mdio.h>

公共成员

const nx_mdio_ops_t *ops
void *context

model.h

显式主机模型夹具，不建立物理 MCU 资格。

作者 Nexus Team

函数

nx_result_t nx_native_clock_configure(bool enabled, nx_time_us_t now)

将主机模型切换到确定性时钟域。

参数:

  • enabled – [in] true 选择手动时钟，false 选择真实单调时间。

  • now – [in] 手动时钟的初始微秒值，须小于 UINT64_MAX。

返回:

成功或 INVALID。调用方必须先结清所有请求；切换会创建新时间域，使旧 deadline 失效。

nx_result_t nx_native_clock_advance(uint64_t duration_us)

推进确定性时间，不隐式触发硬件 IRQ。

参数:

  • duration_us – [in] 非负微秒增量。

返回:

成功；非手动模式返回 STATE，溢出返回 EXHAUSTED。

nx_result_t nx_native_gpio_configure(uint32_t mask, uint32_t initial)

写者静止后配置固定 GPIO 模型。

参数:

  • mask – [in] 获授权的输入/输出位掩码。

  • initial – [in] 位于掩码范围内的初始输出快照。

返回:

成功或 INVALID；不虚构 Board/电气资格。

void nx_native_gpio_input(uint32_t value)

在确定性模型中注入一个 GPIO 输入快照。

参数:

  • value – [in] 物理端口快照；读取时屏蔽未授权位。

uint32_t nx_native_gpio_output(void)

观察输出状态，用于主机行为断言。

返回:

模型输出快照；不具有实测波形语义。

nx_result_t nx_native_uart_configure(const nx_native_uart_config_t *config)

在固定 UART 上配置准确的 RX/TX 夹具容量。

参数:

  • config – [in] 调用方持有的选中配置存储描述。

返回:

成功、INVALID，或因仍有活跃请求而返回 BUSY。

nx_result_t nx_native_uart_tx_validate(void *context, const nx_uart_tx_request_t *request)

为选定 RS485 绑定验证准确 Native TX 上下文。

备注

仅限任务上下文；不产生模型 IRQ、准入、GPIO 或状态修改。

参数:

  • context – [in] 已配置 Native UART 接口的精确上下文。

  • request – [in] 仍然有效的 READY/QUEUED 描述符，不予保留。

返回:

执行与 Native submit/start 相同的纯检查，且可拒绝。

nx_result_t nx_native_uart_model_irq_configure(const nx_uart_port_t *binding, const nx_irq_policy_t *policy, const nx_irq_source_t *source)

将显式 IRQ 事实复制到静止的主机 UART 模型。

备注

仅限任务上下文的冷态配置；调用方已停止发布者。不得残留活跃请求、stream 或已绑定的 wake。默认准备过程显式模拟 BASEPRI/四位 IRQ；此入口可以模拟 Baseline，不虚构 SoC/Board。

参数:

  • binding – [in] 没有 IRQ 使用者的已配置 Native UART 接口。

  • policy – [in] 在本次调用中复制的不可变 CPU/内核事实。

  • source – [in] 在本次调用中复制的实际模型发布者事实。

返回:

成功，或在产生效果前返回 INVALID、CONTEXT、STATE 或 BUSY。

void nx_native_uart_irq_step(void)

执行一个确定性 TX IRQ 字节／TC 事件。

备注

不模拟实际硬件 IRQ、时延或线上时序。

nx_result_t nx_native_uart_receive(uint8_t byte, uint32_t flags)

将一个 RX IRQ 事实注入有界、选定配置的存储。

参数:

  • byte – [in] 接收到的字节；NO_BYTE 状态事实时忽略此值。

  • flags – [in] NX_UART_EVENT_* 错误事实；正常接收为零。

返回:

成功、OVERFLOW，或禁用时返回 STATE。

void nx_native_uart_fault(bool start_failure, bool hold_drain)

配置启动失败或无法证明硬件排空。

参数:

  • start_failure – [in] 直接准入后失败，不作为拒绝。

  • hold_drain – [in] 保留 QUARANTINED 请求，直到显式解除。

size_t nx_native_uart_transmitted(void)

观察捕获的 TX 字节。

返回:

捕获到调用方持有的 tx_log 中的数量。

nx_result_t nx_native_spi_configure(uint8_t *registers, size_t length)

配置固定 SPI 回显或寄存器文件模型。

参数:

  • registers – [inout] 可选的调用方持有的寄存器字节；NULL 表示回显。

  • length – [in] 寄存器容量；仅回显模式允许为零。

返回:

成功或 INVALID；夹具只有一个串行化执行者。

void nx_native_spi_fault(size_t fail_after, bool busy)

注入有界 SPI 部分失败或控制器占用。

参数:

  • fail_after – [in] 发生失败的字节索引；SIZE_MAX 禁用故障。

  • busy – [in] true 表示不访问 CS/缓冲区即拒绝事务。

bool nx_native_spi_cs_active(void)

事务结束后检查模型 CS 电平。

返回:

模型事务持有活跃 CS 时为真。

nx_result_t nx_native_i2c_configure(uint8_t *memory, size_t length, uint8_t address)

配置一个 7 位地址的寄存器文件 I2C 模型。

参数:

  • memory – [inout] 由调用方持有、夹具保留的寄存器字节。

  • length – [in] 正的寄存器容量，最多 256。

  • address – [in] 有效且非保留的 7 位地址。

返回:

成功或 INVALID。

void nx_native_i2c_fault(nx_result_t result, bool stuck)

注入 NACK、仲裁丢失或总线卡死。

参数:

  • result – [in] Success 禁用故障；支持 NACK/ARBITRATION/IO。

  • stuck – [in] true 使显式恢复持续失败，直到解除。

nx_result_t nx_native_flash_configure(uint8_t *memory, const nx_flash_geometry_t *geometry)

配置物理几何 RAM 模型，明确不具备持久性。

参数:

  • memory – [inout] 调用方持有、大小符合几何信息的字节存储；擦除为 0xff。

  • geometry – [in] 调用方持有的不可变连续扇区几何，program_flags = 0。此 NOR 模型不实现隐藏 ECC 擦除历史要求。

返回:

成功、因几何无效而返回 INVALID，或因编程标志不支持而返回 UNSUPPORTED；没有堆、产品预留或持久化。

void nx_native_flash_fault(size_t pulse_count)

完整模型脉冲之后注入编程／擦除失败。

参数:

  • pulse_count – [in] 允许完成的完整脉冲数；SIZE_MAX 禁用故障。

void nx_native_watchdog_boot(uint32_t causes)

复位看门狗夹具，模拟新一次启动。

备注

仅用于测试；此操作不能禁用真实 IWDG。

参数:

  • causes – [in] 锁存的复位原因掩码。

bool nx_native_watchdog_expired(void)

观察已启用确定性 IWDG 的到期。

返回:

标称模型 deadline 到期后为真，并锁存 IWDG。

nx_result_t nx_native_exti_configure(uint8_t line, nx_exti_edge_t edge, nx_exti_event_t *events, size_t capacity)

为一个静态 EXTI 线路配置准确存储。

参数:

  • line – [in] 0..15。

  • edge – [in] RISING/FALLING/BOTH 选择。

  • events – [inout] 夹具持有的队列存储。

  • capacity – [in] 正的事件容量。

返回:

成功或 INVALID；复位前须使生产者/消费者静默。

nx_result_t nx_native_exti_emit(uint8_t line, nx_exti_edge_t edge)

注入一个带时间戳的选定边沿事实。

参数:

  • line – [in] 已配置的静态线。

  • edge – [in] RISING 或 FALLING 事件。

返回:

成功，或 INVALID/STATE/OVERFLOW；丢失仍可被观察。

nx_result_t nx_native_pwm_configure(uint32_t tick_hz, uint32_t period_ticks)

写者静止后配置固定 PWM 模型定时器事实。

参数:

  • tick_hz – [in] 预分频后的正频率。

  • period_ticks – [in] 固定共享时基的正周期。

返回:

成功或 INVALID。

nx_result_t nx_native_adc_configure(const uint16_t *samples, size_t count, uint8_t resolution_bits, uint32_t reference_mv)

配置固定 ADC 原始计数序列与格式。

参数:

  • samples – [in] 夹具持有的标称样本序列。

  • count – [in] 正的通道数。

  • resolution_bits – [in] 1..16。

  • reference_mv – [in] 正的标称参考电压。

返回:

成功或 INVALID。

void nx_native_adc_fault(size_t sample_count)

若干完整样本之后注入 ADC 失败。

参数:

  • sample_count – [in] 允许完成的完整样本数；SIZE_MAX 禁用故障。

void nx_native_gpio_model_input(const nx_gpio_port_t *binding, uint32_t value)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

uint32_t nx_native_gpio_model_output(const nx_gpio_port_t *binding)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_uart_model_configure(const nx_uart_port_t *binding, const nx_native_uart_config_t *config)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_uart_model_irq_step(const nx_uart_port_t *binding)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_uart_model_receive(const nx_uart_port_t *binding, uint8_t byte, uint32_t flags)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_uart_model_fault(const nx_uart_port_t *binding, bool start_failure, bool hold_drain)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

size_t nx_native_uart_model_transmitted(const nx_uart_port_t *binding)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_spi_model_configure(const nx_spi_endpoint_t *binding, uint8_t *registers, size_t length)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_spi_model_fault(const nx_spi_port_t *binding, size_t fail_after, bool busy)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

bool nx_native_spi_model_cs_active(const nx_spi_endpoint_t *binding)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_i2c_model_configure(const nx_i2c_endpoint_t *binding, uint8_t *memory, size_t length, uint8_t address)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_i2c_model_fault(const nx_i2c_port_t *binding, nx_result_t result, bool stuck)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_flash_model_configure(const nx_flash_port_t *binding, uint8_t *memory, const nx_flash_geometry_t *geometry)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_flash_model_fault(const nx_flash_port_t *binding, size_t pulse_count)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_watchdog_model_boot(const nx_watchdog_port_t *binding, uint32_t causes)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

bool nx_native_watchdog_model_expired(const nx_watchdog_port_t *binding)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_exti_model_configure(const nx_exti_port_t *binding, uint8_t line, nx_exti_edge_t edge, nx_exti_event_t *events, size_t capacity)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_exti_model_emit(const nx_exti_port_t *binding, uint8_t line, nx_exti_edge_t edge)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_pwm_model_configure(const nx_pwm_port_t *binding, uint32_t tick_hz, uint32_t period_ticks)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

nx_result_t nx_native_adc_model_configure(const nx_adc_port_t *binding, const uint16_t *samples, size_t count, uint8_t resolution_bits, uint32_t reference_mv)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_adc_model_fault(const nx_adc_port_t *binding, size_t sample_count)

仅操作选定的 Native 模型接口面。

备注

对于空接口或其他 provider 的接口，状态操作返回 INVALID，观察返回零/false，注入无效果。所引用的夹具存储仍由调用方持有；重新配置要求写入者和 IRQ 静默，绝不撤销活跃 UART 借用。

void nx_native_spi_model_async_configure(const nx_spi_port_t *binding, bool automatic_irq)

选择显式或自动模型 SPI IRQ 推进。

备注

先使控制器静默。自动 service 每次调用至多推进一个字节或一个独立的最终空闲事实；不模拟物理 DMA 或线上时序。

void nx_native_spi_model_irq_step(const nx_spi_port_t *binding)

在准确 Native 总线上注入一个有界 SPI 字节／空闲事件。

void nx_native_spi_model_drain_hold(const nx_spi_port_t *binding, bool hold)

注入无法证明 SPI 硬件排空的失败。

备注

保留请求转为 QUARANTINED，直到解除 hold，且执行者再次 service 总线。不撤销任何借用。

nx_result_t nx_native_uart_model_idle(const nx_uart_port_t *binding)

注入 UART IDLE，并发布当前有效字节前缀。

返回:

成功、无前缀时返回 EMPTY、未运行块流时返回 STATE、模型写入者活跃时返回 BUSY，或其他 provider 返回 INVALID。不撤销生产者借用。

nx_result_t nx_native_adc_model_trigger(const nx_adc_port_t *binding)

向选定空闲块注入一次 ADC 定时器触发扫描。

备注

每次成功发布一次交错排列的原始计数扫描；失败的部分扫描先分离，绝不发布。

返回:

成功、必需 block 仍被持有时返回 OVERFLOW、扫描失败返回 IO、停止后返回 STATE，或其他 provider 返回 INVALID。不声称硬件节拍或模拟精度。

变量

const nx_gpio_port_t *const nx_native_gpio

固定模型绑定；不分配、不查找、不探测、不构造。

const nx_uart_port_t *const nx_native_uart
const nx_spi_endpoint_t *const nx_native_spi
const nx_spi_port_t *const nx_native_spi_port
const nx_i2c_port_t *const nx_native_i2c_port
const nx_i2c_endpoint_t *const nx_native_i2c
const nx_flash_port_t *const nx_native_flash
const nx_watchdog_port_t *const nx_native_watchdog
const nx_exti_port_t *const nx_native_exti
const nx_pwm_port_t *const nx_native_pwm
const nx_adc_port_t *const nx_native_adc
struct nx_native_uart_config_t
#include <model.h>

UART 存储归夹具所有，直到端口停止且 IRQ 静止。

公共成员

nx_uart_rx_profile_t profile
void *rx_storage
size_t rx_capacity
uint8_t *tx_log
size_t tx_capacity
bool automatic_irq

observation.h

显式时间戳来源与经过检查的服务派发。

作者 Nexus Team

枚举

enum nx_io_timestamp_source_t

观察位置；软件时间不表示硬件 SOF。

取值：

enumerator NX_IO_TIMESTAMP_UNKNOWN
enumerator NX_IO_TIMESTAMP_HARDWARE_EVENT
enumerator NX_IO_TIMESTAMP_IRQ_OBSERVATION
enumerator NX_IO_TIMESTAMP_SERVICE_OBSERVATION
enumerator NX_IO_TIMESTAMP_ACQUIRE_OBSERVATION
enum nx_io_timestamp_budget_verdict_t

时序界限可能跨越预算，无法证明满足预算或超出预算。

取值：

enumerator NX_IO_TIMESTAMP_BUDGET_UNKNOWN
enumerator NX_IO_TIMESTAMP_BUDGET_WITHIN
enumerator NX_IO_TIMESTAMP_BUDGET_EXCEEDED

函数

nx_result_t nx_io_timestamp_elapsed(const nx_io_timestamp_t *first, const nx_io_timestamp_t *last, nx_io_timestamp_delta_t *out)

比较两个关系已明确的观察事件。

备注

任务/IRQ 中均为纯操作且工作量恒定；不读取时钟、不访问硬件、不分配、不加锁，也不保留引用。输入可以重合。调用方负责证明事件配对及时间戳来源。可以比较不同的显式来源种类以观察交付时延，但不得重新标记任一观察。

参数:

  • first – [in] 稳定、已对齐且未被并发修改的首个事实。

  • last – [in] 同一时间域、epoch 和速率中稳定的末个事实。

  • out – [out] 独立且已对齐的结果，拒绝时保持不变。

返回:

返回 SUCCESS；存储格式无效或重叠时返回 INVALID，来源为 UNKNOWN 时返回 UNSUPPORTED，时间域不兼容或 tick 倒退时返回 STATE，上界溢出时返回 EXHAUSTED。

nx_result_t nx_io_timestamp_budget(const nx_io_timestamp_t *first, const nx_io_timestamp_t *last, uint64_t maximum_ticks, nx_io_timestamp_budget_result_t *out)

将完整时序误差区间与预算比较。

备注

纯 O(1) Task／IRQ 操作，不访问时钟、不保留引用。WITHIN 要求 upper <= maximum；EXCEEDED 要求 lower > maximum。当 lower <= maximum < upper，或误差界未知时，结果为 UNKNOWN。SUCCESS 本身不表示满足预算。既有时间戳 owner／来源合同仍适用：本函数不扩展原始 DWT、不验证 epoch 连续性、不同步采样、不建立 IRQ 到达时刻，也不证明 WCET。

参数:

  • first – [in] 稳定且对齐的扩展时间戳，须与另一事实构成因果配对。

  • last – [in] 同一 domain／epoch／rate 内稳定且对齐的事实。

  • maximum_ticks – [in] 包含边界的最大值，单位为声明的 tick。

  • out – [out] 独立且已对齐的结果，拒绝时保持不变。

返回:

与 elapsed 相同的 SUCCESS、INVALID／UNSUPPORTED／STATE；不确定度之和或上界不可表示时返回 EXHAUSTED。

nx_result_t nx_uart_port_service_checked(const nx_uart_port_t *port)

派发选定的 UART 服务，或说明服务缺失。

备注

与普通 service 采用相同的上下文、串行化和生命周期规则。SUCCESS 仅证明已派发，不证明进展、健康、结清或允许回收存储。不读取请求，不增加状态、锁或隐藏 worker。

参数:

  • port – [in] 仍然有效的不可变接口及已初始化的 provider 状态。

返回:

一次派发后返回 SUCCESS；接口格式无效返回 INVALID，没有 service 方法返回 UNSUPPORTED。

nx_result_t nx_spi_port_service_checked(const nx_spi_port_t *port)

派发选定的 SPI 服务，或说明服务缺失。

备注

与 nx_spi_port_service 采用相同的上下文和所有者规则；SUCCESS 仅证明已派发，绝不代表结清。

参数:

  • port – [in] 仍然有效的不可变接口及已初始化的 provider 状态。

返回:

派发后返回 SUCCESS，或返回 INVALID/UNSUPPORTED。

nx_result_t nx_i2c_port_service_checked(const nx_i2c_port_t *port)

派发选定的 I2C 服务，或说明服务缺失。

备注

与 nx_i2c_port_service 采用相同的上下文和所有者规则；SUCCESS 仅证明已派发，绝不代表结清。

参数:

  • port – [in] 仍然有效的不可变接口及已初始化的 provider 状态。

返回:

派发后返回 SUCCESS，或返回 INVALID/UNSUPPORTED。

struct nx_io_timestamp_t
#include <observation.h>

由调用者明确提供的时间事实，不访问时钟。

备注

ticks 是扩展计数，在一个非零 domain/epoch 中单调递增。其所有者扩展计数器回绕，并在复位、不连续或速率变化时改变 epoch。domain 和 epoch 是装配内身份，不表示跨核、安全域或设备同步的时钟。UNKNOWN 不提供可用测量。频率是精确声明的 ticks/second，而非实测精度。已知且为零的不确定度表示零误差；未知不确定度使用独立标志。这些事实本身不能建立物理精度、因果配对或事件身份。

公共成员

uint64_t ticks
uint64_t ticks_per_second
uint32_t domain
uint32_t epoch
uint64_t uncertainty_ticks
nx_io_timestamp_source_t source
bool uncertainty_known
struct nx_io_timestamp_delta_t
#include <observation.h>

同一时钟域内的差值，带明确的误差界。

备注

uncertainty_known 为 false 时，uncertainty_ticks 为零，不描述任何误差界限。不隐含时间转换、舍入或跨时钟同步。

公共成员

uint64_t ticks
uint64_t ticks_per_second
uint64_t uncertainty_ticks
bool uncertainty_known
struct nx_io_timestamp_budget_result_t
#include <observation.h>

在声明的 tick 域内比较包含边界的区间与预算。

备注

仅当 delta.uncertainty_known 为 true 时 lower／upper 才可使用。否则两者均为零，verdict 为 UNKNOWN，绝不表示精确的零。

公共成员

nx_io_timestamp_delta_t delta
uint64_t lower_ticks
uint64_t upper_ticks
nx_io_timestamp_budget_verdict_t verdict

pin_state.h

显式静态默认态与睡眠态引脚配置。

作者 Nexus Team

枚举

enum nx_pin_state_selection_t

仅支持显式编写的 GPIO 状态；不隐含电源策略。

取值：

enumerator NX_PIN_STATE_DEFAULT
enumerator NX_PIN_STATE_SLEEP
enumerator NX_PIN_STATE_INVALID

函数

nx_result_t nx_pin_state_select(const nx_pin_state_port_t *port, nx_pin_state_selection_t state)

选择一个明确支持的 GPIO 状态，无需等待。

备注

在同一 CPU 的特权 Thread 上下文中串行调用，进入时中断屏蔽位须已清除。不得从 ISR/NMI 调用，不得有其他 pad/RCC 所有者竞争；不支持 AF 切换、时钟转换、唤醒或保持策略。部分失败仍保留租约；可重试一个明确支持的目标，或由所有者执行受检查的清理。这不证明物理瞬态、外部偏置或 PCB 安全。

参数:

  • port – [in] 静态独占 pad/gate 租约，所有写者均已静止。

  • state – [in] 默认态或睡眠态；两种名称均不代表电气安全。

返回:

实际读回目标状态后返回 SUCCESS；或在保留 provider 所有权的同时返回 INVALID/UNSUPPORTED/ CONTEXT/STATE/BUSY/IO。

struct nx_pin_state_ops_t
#include <pin_state.h>

一个静态拥有的 provider；不执行发现，也不按寄存器分派。

公共成员

nx_result_t (*select)(void *context, nx_pin_state_selection_t state)
struct nx_pin_state_port
#include <pin_state.h>

不可变公共接口对象；provider 存储与计划的生命周期须覆盖每次使用。

公共成员

const nx_pin_state_ops_t *ops
void *context

pwm_adc.h

可选的有限相干 PWM／触发 ADC 窗口。

作者 Nexus Team

函数

nx_result_t nx_pwm_adc_prepare(nx_pwm_adc_request_t *request, uint16_t *samples, size_t sample_count, const nx_pwm_group_frame_t *frame, nx_time_us_t deadline)

准备彼此独立且尚未借用的请求、帧和采样存储。

备注

请求、样本范围、源帧描述符及占空比范围必须自然对齐、地址不回绕且互不重叠。再次准备前，调用方已消费先前结果，并等待所有适配器观察者退出。拒绝 NX_DEADLINE_NEVER；可以准备已到期的有限 deadline，但不得因此准入新的物理效果。准备过程不访问样本内容、不借用硬件，也不建立速率/区域支持。失败使已初始化请求保持不变。

参数:

  • request – [inout] 已初始化为 READY，或已完全消费的 SETTLED 存储。

  • samples – [out] 自然对齐且可写的调用方样本数组。

  • sample_count – [in] 精确的正样本数；provider 检查 DMA。

  • frame – [in] 仅在本次调用中按值复制的可读描述符；完整占空比数组须保持有效直到 SETTLED。

  • deadline – [in] 整个窗口的有限绝对单调 deadline。

返回:

返回 SUCCESS 或 INVALID/STATE；不访问硬件，也不产生 provider 借用。

nx_result_t nx_pwm_adc_submit(const nx_pwm_adc_t *port, nx_pwm_adc_request_t *request)

由唯一任务所有者准入并布防一个完整有限窗口。

备注

准入后的 arm/预转换失败在已接受请求之下排空。正常完成在 SETTLED 前停止 PWM 来源，且绝不自动重装。仅 DMA TC 不足以证明完成或输出安全。错误/取消报告的保证有效样本数为零；中止后的 DMA 剩余计数不能建立有效前缀。成功窗口恰好报告 sample_count。普通操作成功完成后，可以另行显式准备并提交；显式停止或锁存故障则需要冷关闭/重新初始化。准入前，provider 检查上下文、固定帧、区域，以及与全部冷态描述符/MMIO 的重叠。整个窗口的完整占空比帧保持恒定；样本数不承诺精确的 PWM 脉冲数。没有可信完成时间戳时，首次在请求 deadline 时刻或之后观察到完成会报告 TIMEOUT，即使 DMA 已经完成。这一保守观察规则不承诺物理执行时间上界，也绝不放宽必需的来源排空。

参数:

  • port – [in] 已初始化且稳定的选中耦合接口及冷租约。

  • request – [inout] 调用方准备的精确 READY 窗口。

返回:

SUCCESS 表示 ACCEPTED，包括可能已经 SETTLED 的错误。拒绝表示不保留指针、不访问 payload，也不产生新效果。

nx_result_t nx_pwm_adc_cancel(const nx_pwm_adc_t *port, nx_pwm_adc_request_t *request)

锁存取消，同时保留对应活动窗口的借用。

备注

取消局限于本任务，不提供跨任务稳定身份。外部应使用既有适配器 slot/epoch 机制。先前终态故障保持保留；取消绝不清除它。

参数:

  • port – [in] 同一个仍然有效的耦合接口及串行化特权任务。

  • request – [inout] 精确的已准入请求，须保持有效直到 SETTLED。

返回:

SUCCESS 开始或观察到取消，绝不代表已经 SETTLED。

nx_result_t nx_pwm_adc_service(const nx_pwm_adc_t *port)

由同一任务所有者推进有界完成或源排空。

备注

没有隐藏 worker、等待或分配。只有观察到来源/向量撤回后，才允许最终指针分离和 release 发布。

参数:

  • port – [in] 同一个仍然有效的耦合接口及串行化特权任务。

返回:

推进或结清后返回 SUCCESS，排空尚未完成时返回 BUSY；或返回故障，要求继续恢复 service 并显式停止。

nx_result_t nx_pwm_adc_stop(const nx_pwm_adc_t *port)

关闭准入并尝试最终排空，不撤销借用。

备注

继续由唯一执行者 service/stop，直到静默。冷关闭还需等待向量退出并恢复保存的租约。故障恢复不自动重新启动 PWM 或恢复采集。SUCCESS 不释放引脚、时钟或私有存储；这些冷租约保持持有，直到平台最终完成退出汇合并成功关闭。

参数:

  • port – [in] 同一个仍然有效的耦合接口及串行化特权任务。

返回:

SUCCESS 证明来源已停止；BUSY/IO 保留恢复所需存储。

nx_result_t nx_pwm_adc_state(const nx_pwm_adc_t *port, nx_pwm_adc_state_t *state)

复制精确的固定事实与观察到的活动／故障／隔离状态。

备注

state 是观察操作，不是来源排空或归还操作。

参数:

  • port – [in] 同一个仍然有效的耦合接口及串行化特权任务。

  • state – [out] 独立且已对齐的输出，拒绝时保持不变。

返回:

返回 SUCCESS、INVALID/STATE/CONTEXT，或因缺少方法而返回 UNSUPPORTED。

struct nx_pwm_adc_request_t
#include <pwm_adc.h>

一个有限窗口；传输数量以原始采样为单位，不以字节计。

备注

首次 prepare 前初始化 base。成功准入后，请求和占空比数组须保持有效且调用方不可修改，直到以 acquire 观察到 SETTLED。可写样本范围由 provider 独占；借用期间调用方既不读也不写。帧元数据在准备时复制。本有限窗口接口不包含后续影子提交、自动重装、控制算法或工程单位转换。硬件专有样本存储和整数编码由 state.format 报告。

公共成员

nx_request_t base

借用状态与释放发布状态。

uint16_t *samples

独占可写的原始采样存储。

size_t sample_count

请求的采样数量，必须为正。

nx_pwm_group_frame_t frame

复制的元数据；占空比数组保持借用。

struct nx_pwm_adc_state_t
#include <pwm_adc.h>

精确的选定事实与观察到的源／恢复状态。

备注

format 描述实际支持的硬件，不建立采样孔径时间戳、模拟精度、PWM 占空比 epoch、IRQ 时延、输出脉冲数量或已检查物理电路的事实。

公共成员

nx_adc_format_t format

实际整数存储表示与来源。

uint32_t tick_hz

PWM 计数器每秒的计数刻度数。

uint32_t period_ticks

以计数器刻度表示的固定周期。

uint32_t trigger_ticks

以计数器刻度表示的固定相位。

uint32_t deadtime_ticks

以独立的 deadtime_hz 单位表示的死区时间。

uint32_t deadtime_hz

死区时钟；不得从 PSC 推断。

size_t pwm_channels

完整、固定顺序的帧通道数。

size_t max_samples

提供者／DMA 的有限窗口计数上限。

bool running

观察到的源／计数器活动状态。

bool fault

需要冷恢复的锁存故障。

bool quarantined

撤离未完成时保留所有权。

struct nx_pwm_adc_ops_t
#include <pwm_adc.h>

仅选定实例具有的操作；普通 PWM／ADC 方法表不增加。

备注

每个回调实现对应的公共函数契约。一个特权任务串行化 submit/cancel/service/stop/state；IRQ 只向同一私有所有者锁存有界物理事实。缺失回调返回 UNSUPPORTED。不进行分配，也没有隐藏 worker。

公共成员

nx_result_t (*submit)(void *context, nx_pwm_adc_request_t *request)
nx_result_t (*cancel)(void *context, nx_pwm_adc_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_adc_state_t *state)
struct nx_pwm_adc
#include <pwm_adc.h>

不可变的冷装配选定身份；工厂不执行分配。

备注

接口、方法表、上下文及冷配置的生命周期覆盖每个请求和 IRQ 发布者。一个耦合接口拥有全部选中硬件；不存在可独立启动的 PWM-group 或 ADC 接口暴露该硬件。

公共成员

const nx_pwm_adc_ops_t *ops
void *context

pwm_group.h

固定时基、原子的多通道 PWM 影子提交。

作者 Nexus Team

函数

nx_result_t nx_pwm_group_commit(const nx_pwm_group_t *port, const nx_pwm_group_frame_t *frame)

暂存完整通道组及其内部触发比较值。

备注

provider 声明精确的通道数、触发范围及 ISR 预算。占空比包含零与 period。所有通道共用一个固定时基。部分硬件写入失败时必须禁用输出并保留故障责任，不能让混合新旧值的通道组进入下一次更新。停止必须显式进行；禁止 break 后自动恢复输出。

参数:

  • port – [in] 一个串行化特权任务/可配置 IRQ 所有者。

  • frame – [in] 完整且可读的批次；返回后不保留指针。

返回:

SUCCESS 表示一个一致的组已暂存，等待硬件更新，不代表更新已经发生。无效输入没有效果。

nx_result_t nx_pwm_group_start(const nx_pwm_group_t *port)

仅输出已禁用且刹车未激活、已清除时启动。

参数:

  • port – [in] 拥有全部冷租约的串行化特权任务所有者。

返回:

返回 SUCCESS，或返回错误并保留清理及相应故障责任。

nx_result_t nx_pwm_group_stop(const nx_pwm_group_t *port)

撤离主输出、通道、计数器与拥有的 IRQ 源。

备注

此源码层承诺不认证外部电路的电气安全。Board 空闲电平和发布者汇合属于装配职责。

参数:

  • port – [in] 同一个特权任务所有者；冷态引脚/向量租约保持持有。

返回:

SUCCESS 证明来源已撤回；失败保留责任。

nx_result_t nx_pwm_group_clear_fault(const nx_pwm_group_t *port)

禁用期间检查实际刹车状态后显式清除故障。

参数:

  • port – [in] 串行化特权任务恢复所有者。

返回:

仅在影子值一致且 break 已确认后返回 SUCCESS；绝不使能输出。产品功率级恢复策略仍由外部负责。

nx_result_t nx_pwm_group_state(const nx_pwm_group_t *port, nx_pwm_group_state_t *state)

读取固定单位与观察到的启用／故障事实，不启动硬件。

参数:

  • port – [in] 串行化特权任务所有者。

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

返回:

返回 SUCCESS 或 INVALID/STATE/CONTEXT/UNSUPPORTED。

struct nx_pwm_group_frame_t
#include <pwm_group.h>

一个同步影子批次；通道顺序由装配固定。

公共成员

const uint32_t *duty_ticks
size_t channel_count
uint32_t trigger_ticks
struct nx_pwm_group_state_t
#include <pwm_group.h>

固定单位、软件故障锁存与实际硬件启用状态。

公共成员

uint32_t period_ticks
uint32_t tick_hz
uint32_t deadtime_ticks
uint32_t deadtime_hz
size_t channel_count
bool running
bool fault
bool quarantined
struct nx_pwm_group_ops_t
#include <pwm_group.h>

共享操作；提交必须防止部分影子发布。

公共成员

nx_result_t (*commit)(void *context, const nx_pwm_group_frame_t *frame)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*clear_fault)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_group_state_t *state)
struct nx_pwm_group
#include <pwm_group.h>

不可变身份；无默认设备状态或分配。

公共成员

const nx_pwm_group_ops_t *ops
void *context

rtc.h

独立时间域中的原始日历与一次有限 alarm。

作者 Nexus Team

函数

nx_result_t nx_rtc_calendar_validate(const nx_rtc_calendar_t *calendar)

验证原始日历字段，不改变任何存储。

参数:

  • calendar – [in] 可读且自然对齐的值。

返回:

SUCCESS 或 INVALID；不访问时钟或 provider。

nx_result_t nx_rtc_alarm_validate(const nx_rtc_alarm_t *alarm)

验证有限 alarm 模式的日和时间范围。

参数:

  • alarm – [in] 可读且自然对齐的值。

返回:

SUCCESS 或 INVALID；不承诺 provider 能够 armed 该 alarm。

nx_result_t nx_rtc_request_prepare(nx_rtc_request_t *request, const nx_rtc_domain_t *domain, const nx_rtc_alarm_t *alarm, nx_time_us_t deadline)

把域／模式复制到已初始化且未被借用的调用方存储中。

备注

输入必须是完整、对齐、不回绕且与请求不重叠的范围。该冷操作不建立借用，也无法获知不透明 provider 或时钟上下文的完整范围。准入检查已知 provider 范围；不透明上下文的不重叠由装配方负责。

参数:

  • request – [inout] READY 或结果已消费的 SETTLED 存储，所有 join 已完成。

  • domain – [in] 在本次调用中复制非零 owner／代次。

  • alarm – [in] 在本次调用中复制有效模式。

  • deadline – [in] 绝对 Core 单调 deadline 或 NX_DEADLINE_NEVER。

返回:

SUCCESS 或 INVALID/STATE；所有失败均保持请求不变。

nx_result_t nx_rtc_port_read(const nx_rtc_port_t *port, nx_rtc_snapshot_t *snapshot)

由唯一串行任务执行者复制已设置的日历／域。

参数:

  • port – [in] 有效、只读且存活的接口面；不允许并发生命周期写入者。

  • snapshot – [out] 独立、对齐且可写的输出。

返回:

SUCCESS、关闭／未设置时的 STATE、INVALID 或 UNSUPPORTED；失败保持输出不变。

nx_result_t nx_rtc_port_set(const nx_rtc_port_t *port, const nx_rtc_calendar_t *calendar)

设置空闲日历，并推进不回绕的设置域。

备注

拒绝不改变状态。不隐式执行备份复位、同步、Core 时间调整，也不授予覆盖保留硬件的权限。

参数:

  • port – [in] 同一个唯一串行特权任务 owner。

  • calendar – [in] 独立的原始值，通过验证后复制。

返回:

SUCCESS、存在借用时的 BUSY、关闭时的 STATE、INVALID、EXHAUSTED 或 UNSUPPORTED。

nx_result_t nx_rtc_port_submit(const nx_rtc_port_t *port, nx_rtc_request_t *request)

借用并 armed 一个未来 alarm；没有队列、分配或 worker。

备注

关闭／域过期／已匹配当前时刻的模式返回 STATE；已有活动请求返回 BUSY。观察到有限 deadline 已到期时，在准入前返回 TIMEOUT。日历、计数器和 Core deadline 分属不同域。在整个 owner 生命周期及所有外部 join 期间，装配方保持复制的时钟接口面所借用上下文有效、不重叠且不重入。

参数:

  • port – [in] 已初始化的串行 owner，持有有效、复制的 Core 时钟接口面。

  • request – [inout] 精确属于当前设置域的 READY 请求。

返回:

SUCCESS 表示 ACCEPTED；INVALID/STATE/BUSY/TIMEOUT/UNSUPPORTED 表示拒绝，不保留引用或效果。

nx_result_t nx_rtc_port_cancel(const nx_rtc_port_t *port, nx_rtc_request_t *request)

为精确借用的请求锁存取消，但不撤销借用。

备注

在 service 前执行 cancel／stop，可以先于尚未观察的到期或事件锁存原因。等待撤源期间首次终止原因始终不变。

参数:

  • port – [in] 同一个串行执行者；跨任务控制需要适配器。

  • request – [inout] 精确的活动请求身份；不读取其他请求身份指向的存储。

返回:

SUCCESS 表示已接受取消；请求仍可能处于 QUARANTINED／被借用状态。拒绝返回 STATE/INVALID/UNSUPPORTED。

nx_result_t nx_rtc_port_service(const nx_rtc_port_t *port)

观察 deadline／事件，或继续真实撤源。

备注

首次观察时，到期优先于 pending 事件。先脱离请求源／pending 引用，再以 release 发布 SETTLED，作为 provider 的最终请求访问。

参数:

  • port – [in] 同一个串行任务执行者；有界，不隐藏等待。

返回:

空闲／已结清时返回 SUCCESS，活动或撤源被 hold 阻止时返回 BUSY；INVALID/STATE/UNSUPPORTED 可以拒绝分发。

nx_result_t nx_rtc_port_stop(const nx_rtc_port_t *port)

关闭准入，并在归还任何借用前证明已撤源。

备注

重复执行已完成的干净 stop 是幂等的。stop 不重置身份，也不撤销指针。请求源／provider 的生命周期仍须覆盖外部 join。

参数:

  • port – [in] 同一个串行 owner，且外部发布者均已静止。

返回:

已关闭且完成 join 时返回 SUCCESS；BUSY 保留隔离请求。INVALID/STATE/UNSUPPORTED 可以拒绝分发。

struct nx_rtc_calendar_t
#include <rtc.h>

原始 YY 日历；没有 UTC、世纪、时区或振荡器策略。

备注

YY 为 00..99，YY 模 4 等于零时为闰年。星期是独立的 1..7 值，不根据日期推算。其他字段使用从 1 起算的月／日及 24 小时时／分／秒，不含闰秒。自然的 year99->00 回绕不重置设置域。

公共成员

uint8_t year
uint8_t month
uint8_t day
uint8_t weekday
uint8_t hour
uint8_t minute
uint8_t second
struct nx_rtc_domain_t
#include <rtc.h>

不透明的 owner 身份与不重复的设置代次。

备注

只比较身份而不解引用。仅在该 owner 存储生命周期内有效；结束或复用前必须退役全部 token／观察者。它既不授予权限，也不是跨启动／备份复位身份。

公共成员

const void *identity
uint64_t generation
struct nx_rtc_snapshot_t
#include <rtc.h>

在一次串行操作中复制日历与设置域。

公共成员

nx_rtc_domain_t domain
nx_rtc_calendar_t calendar
struct nx_rtc_alarm_t
#include <rtc.h>

精确的未来日／时间匹配；没有月／年或通配掩码。

公共成员

uint8_t day
uint8_t hour
uint8_t minute
uint8_t second
struct nx_rtc_request_t
#include <rtc.h>

调用方持有的 alarm，借用持续到以 acquire 观察到 SETTLED。

备注

首次 prepare 前先初始化 base。域和模式按值复制。ACCEPTED 后，完整请求持续有效，且调用方不得修改，直到 SETTLED 及所有独立控制者／观察者 join 完成。transferred 以发生次数计：SUCCESS 为 1，其他结果均为 0。

公共成员

nx_request_t base
nx_rtc_domain_t domain
nx_rtc_alarm_t alarm
struct nx_rtc_ops_t
#include <rtc.h>

共享只读方法实现相应公共合同。

公共成员

nx_result_t (*read)(const void *context, nx_rtc_snapshot_t *snapshot)
nx_result_t (*set)(void *context, const nx_rtc_calendar_t *calendar)
nx_result_t (*submit)(void *context, nx_rtc_request_t *request)
nx_result_t (*cancel)(void *context, nx_rtc_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_rtc_port
#include <rtc.h>

双指针身份；接口面、ops 和 context 的生命周期覆盖借用／观察者。

公共成员

const nx_rtc_ops_t *ops
void *context

rtc_lptim_model.h

显式主机请求源推进与撤源故障。

作者 Nexus Team

函数

nx_result_t nx_native_rtc_model_advance(const nx_rtc_port_t *port, uint32_t seconds)

按有界的显式请求源秒数推进已设置的原始日历。

备注

工作量固定且有界，最多进位一天。已关闭但已设置的日历仍可推进；这不重新开放准入，也不证明备份保持。不读取／推进 Core 时钟，不发布、不结清，也不改变终止原因。请求源变化不是 IRQ、worker 或硬件验证资格。

参数:

  • port – [in] 精确的 Native RTC 接口面，与每个公共调用串行执行。

  • seconds – [in] 0..86400；零绝不创建事件。

返回:

SUCCESS、未设置／未构造时的 STATE、INVALID 或 UNSUPPORTED。

nx_result_t nx_native_rtc_model_hold_withdraw(const nx_rtc_port_t *port, bool hold)

注入／解除无法撤回已 armed 请求源的外部条件。

参数:

  • port – [in] 同一个串行 owner 上精确的 Native RTC 接口面。

  • hold – [in] true 阻止撤源；false 只解除故障。

返回:

SUCCESS 或 INVALID/STATE/UNSUPPORTED；绝不结清请求。

nx_result_t nx_native_lptim_model_advance(const nx_lptim_port_t *port, uint32_t ticks)

推进有限请求源，并在精确计数上限处饱和。

备注

达到完整的 65536 tick 时，采样的 16 位计数器为零；pending 完成标志与之独立。撤源被 hold 阻止时，进度可在观察到取消／时间条件后继续推进。不访问请求、终止原因或 Core 时钟。

参数:

  • port – [in] 精确的 Native LPTIM 接口面，与全部公共调用串行执行。

  • ticks – [in] 0..65536 个请求源 tick；空闲／未 armed 时不累计。

返回:

SUCCESS 或 INVALID/STATE/UNSUPPORTED。

nx_result_t nx_native_lptim_model_hold_withdraw(const nx_lptim_port_t *port, bool hold)

注入／解除撤源 hold；仍由真实公共 service 执行排空。

参数:

  • port – [in] 串行执行者上精确的 Native LPTIM 接口面。

  • hold – [in] false 不清除 provider 引用，也不发布结果。

返回:

SUCCESS 或 INVALID/STATE/UNSUPPORTED。

spi.h

单执行者轮询 SPI 端点与完整 CS 事务。

作者 Nexus Team

宏定义

NX_SPI_MEMORY_TX_FIXED

显式单元素 DMA 地址，两者均借用到 SETTLED。

NX_SPI_MEMORY_RX_FIXED

函数

nx_result_t nx_spi_endpoint_transfer(const nx_spi_endpoint_t *endpoint, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline, size_t *transferred)

执行一个有界、全双工、8 位轮询事务。

备注

仅限任务上下文，由唯一执行者负责，不分配，也无 OS 锁。一次 CS 有效区间覆盖整个传输。deadline 不能抢占正在传输的硬件字节；外设排空可能晚于 deadline。

参数:

  • endpoint – [in] 一个控制器上的固定 CS/模式/速率绑定。

  • tx – [in] 发送字节；NULL 表示发送 0xff。

  • rx – [out] 接收字节；NULL 表示丢弃。

  • length – [in] 正的传输长度；至少提供一个缓冲区。

  • deadline – [in] 绝对 deadline；包含在适配器队列中的驻留时间。

  • transferred – [out] 完整字节数；执行前清零。

返回:

成功或 BUSY/INVALID/TIMEOUT/IO。排空后返回并归还全部缓冲区及 CS；轮询由 CPU 主动执行，不是 IRQ/DMA 异步。

nx_result_t nx_spi_port_recover(const nx_spi_port_t *port)

保留故障后恢复空闲 SPI 控制器。

参数:

  • port – [in] 唯一执行者，不存在活跃事务或 CS 借用。

返回:

仅在证明复位/空闲后成功；BUSY/STATE/UNSUPPORTED 保留恢复责任，绝不重放工作。

nx_result_t nx_spi_request_prepare(nx_spi_request_t *request, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline)

准备未借用的有限请求，不复制缓冲区。

参数:

  • request – [inout] 新初始化的描述符，或已消费的 SETTLED 描述符。

  • tx – [in] 非空 TX 字节；所选模式支持 dummy 发送时可为 NULL；保持不可变直到最终结清。

  • rx – [out] RX 缓冲区；所选模式支持丢弃时可为 NULL。

  • length – [in] 正字节数，且至少提供一个缓冲区。

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

返回:

成功或 INVALID/STATE；失败不产生缓冲区借用。

nx_result_t nx_spi_endpoint_submit(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)

提交一个有限、异步、覆盖整个 CS 区间的事务。

备注

仅限任务上下文的有界准入。所选模式声明 DMA 域/长度/缓冲区要求。仅 DMA TC 绝不证明外设空闲；总线执行者继续 service，直到 SETTLED。

参数:

  • endpoint – [in] 单执行者总线上的已初始化 endpoint。

  • request – [inout] READY 存储；仅在 NX_SUCCESS 后保留。

返回:

成功表示 ACCEPTED；所有拒绝错误均不保留引用，也不产生残余硬件效果。

nx_result_t nx_spi_endpoint_submit_memory(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request, uint8_t memory_flags)

提交显式递增或单元素 DMA 内存。

备注

固定方向需要一个字节，其他方向需要 length 字节，均位于已审查 DMA 域。实际范围不得重叠。所有地址在排空期间持续借用，直到以 acquire 观察到 SETTLED。不使用隐藏 scratch。两个 fixed 标志可显式实现仅发时钟的传输。请求准备不保留这些标志；只有本次成功准入才选择它们。普通 submit 和既有所有者仍遵循原有缓冲区契约。

参数:

  • endpoint – [in] 已初始化的单执行者 DMA endpoint

  • request – [inout] 具有两个非 NULL 调用方地址的 READY 请求

  • memory_flags – [in] TX_FIXED 重复发送一个不可变 dummy 字节；RX_FIXED 重复写入调用方持有的一个丢弃字节；零表示使用完整且地址递增的 TX/RX 缓冲区

返回:

SUCCESS 表示 ACCEPTED；其他结果不保留任何引用

nx_result_t nx_spi_endpoint_start_admitted(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)

启动适配器已准入的 QUEUED 请求，不重复准入。

参数:

  • endpoint – [in] 已初始化的精确 CS 绑定及总线执行者。

  • request – [inout] 活跃的 QUEUED 存储，已由其适配器借用。

返回:

成功将执行权交给总线；BUSY 保持 QUEUED。其他错误必须由适配器执行者结清。

bool nx_spi_endpoint_on_port(const nx_spi_endpoint_t *endpoint, const nx_spi_port_t *port)

验证端点属于所推进的总线。

备注

任务/IRQ 中均为有界冷态身份检查，不查找，也不产生所有权效果。适配器在执行硬件前检查；异步准入也在借用前检查。

参数:

  • endpoint – [in] 由调用方保持有效的不可变 endpoint 身份。

  • port – [in] 绑定到适配器的精确执行总线。

返回:

仅当 provider 证明控制器状态匹配且总线方法兼容时为真；无效或缺少方法时为 false。

nx_result_t nx_spi_port_cancel(const nx_spi_port_t *port, nx_spi_request_t *request)

请求取消，不撤销 DMA/CS 缓冲区借用。

备注

跨任务控制使用稳定的适配器 slot 和 epoch。

参数:

  • port – [in] 与 submit 和 service 相同的唯一执行所有者。

  • request – [inout] 精确、仍然有效的活跃请求，不得使用陈旧裸指针。

返回:

成功开始排空或观察到先前结清；其他请求返回 STATE，仅轮询 provider 返回 UNSUPPORTED。

void nx_spi_port_service(const nx_spi_port_t *port)

由唯一 Task 执行者推进一个异步总线。

备注

有界且不等待的 service。最终发布发生在 DMA/IRQ 分离及证明外设空闲之后；排空失败会隔离。

参数:

  • port – [in] 仍然有效的 provider；停止及整个排空期间持续调用。

nx_result_t nx_spi_port_stop(const nx_spi_port_t *port)

关闭准入，完整排空之前保留活动源。

参数:

  • port – [in] 仍然有效的总线；所有外部生产者均已静默。

返回:

成功证明来源已撤回，BUSY 要求 service；provider 不提供异步生命周期时返回 UNSUPPORTED。

nx_result_t nx_spi_port_attach_wake(const nx_spi_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

向异步总线 IRQ 发布者附加可选提示接收端。

备注

释放唤醒存储前，等待旧发布者及等待者退出。

参数:

  • port – [in] 由任务执行者控制的一个已初始化总线。

  • wake – [in] 不可变的借用目标；NULL 表示分离。

  • syscall_ceiling – [in] 可选的额外未移位内核安全优先级数值下限；不得削弱生成策略。PRIMASK 内核目标要求为零。不调用内核时忽略。

返回:

成功；实际优先级不安全时返回 PERMISSION，非法控制返回 CONTEXT/STATE，仅轮询总线返回 UNSUPPORTED。

struct nx_spi_request_t
#include <spi.h>

调用者拥有的有限 SPI 请求，包含一个完整 CS 区间。

备注

prepare 前初始化 base。已接受请求持续借用 TX/RX 中所有非 NULL 缓冲区，直到以 acquire 观察到 SETTLED，包括取消和超时排空期间。QUARANTINED 保留借用。

公共成员

nx_request_t base
const uint8_t *tx
uint8_t *rx
size_t length
struct nx_spi_ops_t
#include <spi.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*recover)(void *context)
nx_result_t (*cancel)(void *context, nx_spi_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_spi_port
#include <spi.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_spi_ops_t *ops
void *context
struct nx_spi_endpoint_ops_t
#include <spi.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*transfer)(void *context, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline, size_t *transferred)
nx_result_t (*submit)(void *context, nx_spi_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_spi_request_t *request)
bool (*on_port)(const void *context, const nx_spi_port_t *port)
nx_result_t (*submit_memory)(void *context, nx_spi_request_t *request, uint8_t memory_flags)
struct nx_spi_endpoint
#include <spi.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_spi_endpoint_ops_t *ops
void *context

spi_dma_model.h

显式 Native 分段传输与排空故障控制。

作者 Nexus Team

函数

void nx_native_spi_dma_model_step(const nx_spi_dma_transaction_port_t *port)

推进一个模型传输字，或观察最终空闲事件。

备注

由调用方安排任务/模型 IRQ；没有隐藏 worker。有界提示之前先锁存事实。发布者汇合后绝不再调用。已停止的所有者不能驱动后继实例的模型。

参数:

  • port – [in] 精确、仍然有效的 Native 增强控制器。

nx_result_t nx_native_spi_dma_model_automatic(const nx_spi_dma_transaction_port_t *port, bool automatic)

选择在任务服务期间进行可选的单步推进。

备注

仅限任务上下文。仍可显式逐步推进。此模型不建立物理 IRQ/DMA 时序或 HIL。

参数:

  • port – [in] 精确、仍然有效且已静默的 Native 增强控制器。

  • automatic – [in] true 表示每次 service 推进一个模型步骤。

返回:

返回 SUCCESS、INVALID、STATE、CONTEXT，或因借用未结束而返回 BUSY。

nx_result_t nx_native_spi_dma_model_hold(const nx_spi_dma_transaction_port_t *port, bool hold)

注入或解除无法证明模型物理排空的故障。

备注

仅限任务上下文，借用期间允许调用。移除故障不等于结清；继续推进模型并由唯一执行者 service。

参数:

  • port – [in] 精确、仍然有效的 Native 增强控制器。

  • hold – [in] 为 true 时保留全部请求/CS 借用。

返回:

返回 SUCCESS、INVALID、STATE 或 CONTEXT。

nx_result_t nx_native_spi_dma_model_fault(const nx_spi_dma_transaction_port_t *port, size_t fail_after)

在选定的零基传输字之前使阶段失败。

备注

仅限任务上下文的模型输入；不重放，也不提前释放借用。

参数:

  • port – [in] 精确、仍然有效的 Native 增强控制器。

  • fail_after – [in] SIZE_MAX 禁用注入故障。

返回:

返回 SUCCESS、INVALID、STATE 或 CONTEXT。

spi_dma_owner_binding.h

可选不可变的分段 SPI 所有权与 IRQ 绑定。

作者 Nexus Team

函数

bool nx_spi_dma_owner_contains(const nx_spi_dma_owner_binding_t *binding, const nx_spi_dma_transaction_endpoint_t *endpoint)

检查精确端点归属，不产生硬件效果。

备注

不获取资源、不初始化、不分配，也不执行 service。

参数:

  • binding – [in] 由 provider 拥有、稳定且不可变的能力描述。

  • endpoint – [in] 所选总线上的稳定增强端点。

返回:

身份格式错误或归属不符时返回 false。

nx_result_t nx_spi_dma_owner_attach_wake(const nx_spi_dma_owner_binding_t *binding, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

将借用的提示接收端附加到实际验证过的 IRQ 发布者。

备注

仅限任务上下文。拒绝时保留原有绑定。提示不代表完成。仅 detach 不能等待已捕获接收器的发布者退出。销毁通知数据前，须停止并等待发布者和等待者退出。

参数:

  • binding – [in] 稳定的所选控制器能力描述。

  • wake – [in] 保持有效直到发布者退出的不可变接收器；按 provider 生命周期契约传入 NULL 可解除绑定。

  • syscall_ceiling – [in] 实际的未移位内核阈值。

返回:

SUCCESS、INVALID、CONTEXT、UNSUPPORTED 或 provider 失败。

struct nx_spi_dma_owner_binding_t
#include <spi_dma_owner_binding.h>

仅选定实例具有的提供者能力，不修改 IO 接口。

备注

稳定的不可变存储须比执行器和发布者存活更久。contains 证明实际控制器身份；显示名称或调用方拼装的一对指针不能证明归属。attach_wake 在借用接收器前验证实际 IRQ 源。缺少钩子时，可显式周期性执行 service。

公共成员

const nx_spi_dma_transaction_port_t *port
bool (*contains)(const nx_spi_dma_transaction_endpoint_t*, const nx_spi_dma_transaction_port_t*)
nx_result_t (*attach_wake)(const nx_spi_dma_transaction_port_t*, const nx_irq_wake_t*, uint8_t)

spi_dma_transaction.h

可选的有限、完整 CS 区间分段 SPI DMA 请求合同。

作者 Nexus Team

函数

nx_result_t nx_spi_dma_transaction_prepare(nx_spi_dma_transaction_request_t *request, const nx_spi_dma_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline)

验证每个范围后准备尚未借用的存储。

备注

描述符和载荷不得与请求存储重叠。RX 不得覆盖任何 TX 或描述符。仅当多次 RX 指向同一个显式 FIXED 丢弃单元时，才允许重复别名。准入时检查 provider 特有的内存域。

参数:

  • request – [inout] 已初始化为 READY 或已消费的 SETTLED 存储。

  • segments – [in] 调用方拥有的不可变数组，最多 MAX_SEGMENTS 项。

  • count – [in] 正数段数；每段的 words 均为正数。

  • word_bits – [in] 全部段共用的 8 位或 16 位硬件位宽。

  • deadline – [in] 整条链的绝对单调时限。

返回:

SUCCESS 或 INVALID/UNSUPPORTED/STATE；失败时不建立借用。

nx_result_t nx_spi_dma_transaction_validate(const nx_spi_dma_transaction_request_t *request)

验证不可变字段，不执行准入或修改内存。

nx_result_t nx_spi_dma_transaction_submit(const nx_spi_dma_transaction_endpoint_t *endpoint, nx_spi_dma_transaction_request_t *request)

在仅限任务的单一执行者上准入一个有限链。

备注

准入前验证全部内存域和段。整条链共用一个 CS 有效区间；允许段间出现 SCK 间隔。仅有 DMA TC 不能证明线路空闲。

参数:

  • endpoint – [in] 稳定的增强 DMA 端点及 provider 状态。

  • request – [inout] READY 描述符；仅在 SUCCESS 时保留引用。

返回:

SUCCESS 表示 ACCEPTED，也可能已经 SETTLED。拒绝时不保留引用，也不产生硬件副作用。

nx_result_t nx_spi_dma_transaction_cancel(const nx_spi_dma_transaction_port_t *port, nx_spi_dma_transaction_request_t *request)

取消对应活动请求，同时保留全部借用。

参数:

  • port – [in] 与 submit 和 service 共用的同一个单执行者。

  • request – [inout] 精确的当前请求，或已通过 acquire 语义观测为 SETTLED 的请求。

返回:

SUCCESS 启动或观测取消；INVALID/STATE/CONTEXT 拒绝操作，但不撤销任何已有借用。

void nx_spi_dma_transaction_service(const nx_spi_dma_transaction_port_t *port)

推进一个有界阶段边界、完成或排空。

备注

不等待、不分配、不复制载荷，也无隐藏任务或 OS 锁。排空或释放失败时保留 QUARANTINED 存储。最终硬件引用撤离且 CS 释放后才发布 SETTLED；这是 provider 对调用方请求和描述符的最后一次访问。

参数:

  • port – [in] 仅限任务上下文的增强控制器；停止过程中仍须继续调用。

nx_result_t nx_spi_dma_transaction_stop(const nx_spi_dma_transaction_port_t *port)

关闭准入，并在源完整撤离后停止。

备注

成功停止后重复 stop 不再访问硬件；其他所有者可能已取得该控制器。

参数:

  • port – [in] 稳定的单执行者状态；生产者已静止。

返回:

SUCCESS 证明已停止；BUSY 表示仍须执行 service，并保留全部未完成存储，包括隔离中的请求。

struct nx_spi_dma_segment_t
#include <spi_dma_transaction.h>

显式 DMA 字，使用调用者拥有的填充值／丢弃单元。

备注

两个地址都必须提供。FIXED 方向借用一个字；地址递增方向借用 words 个元素。全部段位宽相同。DMA 不使用轮询段的隐式 NULL/dummy 表示，也不使用隐藏暂存区。

公共成员

const void *tx
void *rx
size_t words
uint8_t memory_flags
struct nx_spi_dma_transaction_request_t
#include <spi_dma_transaction.h>

调用者拥有的请求；每个分段持续借用至排空完成。

备注

prepare 前先初始化 base。ACCEPTED 借用本对象、描述符数组、全部 TX/RX 范围和固定单元，直到通过 acquire 语义观测到 SETTLED。中间段完成、取消和超时都不释放这些借用。完成计数以成功结算的段中的字数为单位；失败段的部分副作用不作量化。

公共成员

nx_request_t base
const nx_spi_dma_segment_t *segments
size_t count
uint8_t word_bits
struct nx_spi_dma_transaction_endpoint_ops_t
#include <spi_dma_transaction.h>

公共成员

nx_result_t (*submit)(void *context, nx_spi_dma_transaction_request_t *request)
struct nx_spi_dma_transaction_endpoint
#include <spi_dma_transaction.h>

公共成员

const nx_spi_dma_transaction_endpoint_ops_t *ops
void *context
struct nx_spi_dma_transaction_port_ops_t
#include <spi_dma_transaction.h>

公共成员

nx_result_t (*cancel)(void *context, nx_spi_dma_transaction_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_spi_dma_transaction_port
#include <spi_dma_transaction.h>

公共成员

const nx_spi_dma_transaction_port_ops_t *ops
void *context

spi_transaction.h

可选的多分段、完整 CS 区间 8／16 位轮询 SPI。

作者 Nexus Team

宏定义

NX_SPI_MAX_SEGMENTS

描述符数量有界；不存在隐藏的拼接缓冲。

函数

nx_result_t nx_spi_transaction_validate(const nx_spi_segment_t *segments, size_t count, uint8_t word_bits)

验证每个描述符与范围，不产生硬件效果。

备注

不借用、复制、分配或修改内存。NULL 数据指针可表示合法的填充发送或接收丢弃操作。本检查不验证 provider 特有的控制器、速率或限制。

参数:

  • segments – [in] 已对齐的不可变数组，由调用方保留。

  • count – [in] 正数描述符数量，最多 MAX_SEGMENTS 个。

  • word_bits – [in] 只能为 8 或 16；整个 CS 有效区间保持不变。

返回:

SUCCESS；范围格式错误、重叠或溢出时为 INVALID；描述符数量或字宽超限时为 UNSUPPORTED。

nx_result_t nx_spi_transaction_transfer(const nx_spi_transaction_endpoint_t *endpoint, const nx_spi_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline, size_t *transferred)

在同一个 CS 有效区间内执行全部分段。

备注

仅限任务上下文的单执行者；轮询持续占用 CPU。线路排空或 provider 复位，并释放 CS 后，函数返回并释放描述符及载荷借用。时限不能抢占正在传输的一个字。错误不重放先前的段。阶段之间不分配、不取得 OS 锁、不使用隐藏暂存区，也不改变位宽或切换 CS。这是同步操作：已有的有限 DMA 请求和取消契约保持不变。

参数:

  • endpoint – [in] 可选增强接口，具有稳定的私有状态。

  • segments – [in] 调用方拥有的描述符及其数据范围。

  • count – [in] 阶段数量；所有阶段均须在硬件使用前验证。

  • word_bits – [in] 共用的硬件帧位宽，为 8 位或 16 位。

  • deadline – [in] 全部阶段共用的绝对单调时限。

  • transferred – [out] 完整接收的字数，单位不是字节；独立可写的 size_t 存储，在执行 provider 前清零。

返回:

SUCCESS 或 INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/IO。

struct nx_spi_segment_t
#include <spi_transaction.h>

单个 CS 区间内的一个阶段。

备注

字使用事务共用的 8 位或 16 位位宽。NULL TX 重复发送 dummy；NULL RX 丢弃接收。二者均可为 NULL，仅产生时钟。非 NULL 范围包含 words 个元素；16 位范围须按 uint16_t 对齐。描述符和 TX 存储在返回前保持不可变。RX 不得与描述符、TX 存储、其他 RX 范围或完成计数输出重叠。普通字节范围 SPI 仍为独立且未改变的接口。

公共成员

const void *tx
void *rx
size_t words
uint16_t dummy
struct nx_spi_transaction_ops_t
#include <spi_transaction.h>

共享不可变方法；缺少传输方法时报告 UNSUPPORTED。

公共成员

nx_result_t (*transfer)(void *context, const nx_spi_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline, size_t *transferred)
struct nx_spi_transaction_endpoint
#include <spi_transaction.h>

可选接口，与选定提供者的现有总线状态共享。

公共成员

const nx_spi_transaction_ops_t *ops
void *context

stream.h

调用者拥有的有界块与显式生产者／消费者借用。

作者 Nexus Team

宏定义

NX_STREAM_BOUNDARY_IDLE
NX_STREAM_BOUNDARY_TRIGGER
NX_STREAM_BOUNDARY_LOSS
NX_STREAM_BOUNDARY_ERROR

枚举

enum nx_stream_slot_state_t

取值：

enumerator NX_STREAM_SLOT_FREE
enumerator NX_STREAM_SLOT_FILLING
enumerator NX_STREAM_SLOT_READY
enumerator NX_STREAM_SLOT_BORROWED

函数

nx_result_t nx_stream_initialize(nx_stream_t *stream, nx_stream_slot_t *slots, size_t count)

初始化未借用的 stream 与准确供给的块数组。

备注

仅限任务上下文的冷装配。本辅助函数不验证 DMA 内存域；硬件 provider 必须验证每个块。

参数:

  • stream – [out] 全新存储，尚未向任何生产者或消费者公开。

  • slots – [inout] 与全部控制及槽元数据分离的缓冲。

  • count – [in] 正数精确块数，不是缓冲池最大数量。

返回:

成功或 INVALID；不分配，也不保留无效输入。

nx_result_t nx_stream_reserve(nx_stream_t *stream, nx_stream_fill_t *fill)

为一个串行生产者预留下一个空闲块。

备注

任务/IRQ 中的有界元数据操作；载荷写入在短暂中断屏蔽区之外、返回的借用范围内执行。

参数:

  • stream – [inout] 已初始化的活动流，只有一个生产者。

  • fill – [out] 生产者借用，在 publish 或经证明的 abort 前有效。

返回:

成功；OVERFLOW 不覆盖数据；停止时返回 STATE；单调借用身份无法递增时返回 EXHAUSTED。

bool nx_stream_can_reserve(const nx_stream_t *stream)

查询下一个物理槽，不产生借用或丢失。

备注

任务/IRQ 中的有界提示。生产者仍须先调用 reserve 才能访问载荷；其他上下文不得与准入并发竞争。

参数:

  • stream – [in] 已初始化的活动流，只有一个串行化生产者。

返回:

仅在准入开放且下一个槽空闲时返回 true。

void nx_stream_note_loss(nx_stream_t *stream, uint32_t count)

锁存明确观察到的生产者丢弃边界。

备注

任务/IRQ 中的有界操作。在 UINT32_MAX 饱和；下一个发布块携带 LOSS，与其有效载荷长度无关。

参数:

  • stream – [inout] 由串行化生产者控制的活动流。

  • count – [in] 丢失块或边界的正数数量，不能猜测字节数。

nx_result_t nx_stream_publish(nx_stream_t *stream, const nx_stream_fill_t *fill, size_t length, uint32_t flags)

全部硬件写引用撤离后，发布完整块。

备注

任务/IRQ 中的有界操作。如果引擎仍能写入所发布的块，DMA 半完成/全完成标志就不足以证明可发布。消费者可见的块字节在消费者释放前保持不可变。

参数:

  • stream – [inout] 与 reserve 相同的串行化生产者。

  • fill – [in] 当前生产者借用；发布后不再保留该令牌引用。

  • length – [in] 预留容量范围内的正数已生产字节数。

  • flags – [in] provider 实际观测到的 IDLE/TRIGGER 边界。

返回:

成功、INVALID 或 STATE；失败时保留生产者所有权。

nx_result_t nx_stream_acquire(nx_stream_t *stream, nx_stream_block_t *block)

一个串行消费者取得下一个就绪块。

备注

任务/IRQ 中的有界元数据操作；消费者在屏蔽区外处理载荷。可乱序释放，且不会覆盖仍被持有的数据。

参数:

  • stream – [inout] 活动流；停止过程中消费者仍可排空。

  • block – [out] 带精确代次令牌的不可变消费者借用。

返回:

成功、EMPTY 或 INVALID；空流不建立借用。

nx_result_t nx_stream_release(nx_stream_t *stream, const nx_stream_block_t *block)

最终使用之后，仅释放匹配的消费者实例世代。

备注

任务/IRQ 中的有界操作；release 是消费者对该块的最后一次访问。

参数:

  • stream – [inout] 同一消费者所有者；不再有该块的剩余观测者。

  • block – [in] 精确的已获取令牌，不能重新拼装指针代替。

返回:

成功；过期或重复释放返回 STATE；也可能返回 INVALID。

nx_result_t nx_stream_abort(nx_stream_t *stream, const nx_stream_fill_t *fill, bool memory_quiesced)

仅内存写入源撤离之后中止生产者借用。

备注

仅取消或达到时限不能证明已静止。

参数:

  • stream – [inout] 与 reserve 相同的生产者所有者。

  • fill – [in] 当前的精确借用。

  • memory_quiesced – [in] 仅在 provider 证明 DMA/IRQ 已停止后才为 true。

返回:

成功；排空未获证明时为 BUSY；令牌过期时为 STATE。

nx_result_t nx_stream_stop(nx_stream_t *stream)

关闭生产者准入，保留每一个未结清借用。

备注

任务/IRQ 中的常量元数据工作量，与块数无关。本操作不停止硬件，也不撤销借用。

参数:

  • stream – [inout] 活动控制对象，须保持有效直到最后一次 stop 成功。

返回:

仅在全部块空闲时成功；生产者引用撤离且消费者排空并释放之前返回 BUSY；控制对象无效时返回 INVALID。

nx_result_t nx_stream_post_initialize(nx_stream_producer_t *producer, nx_stream_t *stream)

将预提交生产者绑定到静止、已初始化的 stream。

备注

仅限任务上下文的冷绑定。调用方拥有排他生产者权限，并保留控制对象直到全部待填充操作及 IRQ 排空。

参数:

  • producer – [out] 独立的调用方控制对象，不得与缓冲建立别名

  • stream – [inout] 准入已开放，且无未归还的生产者或消费者借用

返回:

SUCCESS、INVALID、BUSY 或 STATE；拒绝时输出不变

bool nx_stream_post_can_reserve(const nx_stream_producer_t *producer)

查询下一个预提交槽，不产生借用或猜测丢失。

备注

任务/IRQ 中的有界提示；写入载荷前仍须 reserve。

参数:

  • producer – [in] 同一排他且串行化的生产者

返回:

下次预留可以成功时返回 true

nx_result_t nx_stream_post_reserve(nx_stream_producer_t *producer, nx_stream_fill_t *fill)

预留未来填充，不提前使更早的块就绪。

备注

任务/IRQ 中为 O(1)。失败时输出和丢失计数不变；仅显式观测到边界后才可调用 note_loss。

参数:

  • producer – [inout] 活动的预提交生产者

  • fill – [out] 精确的待完成借用，在 FIFO 发布或 LIFO 中止前有效

返回:

SUCCESS、OVERFLOW、STATE、EXHAUSTED 或 INVALID

nx_result_t nx_stream_post_publish(nx_stream_producer_t *producer, const nx_stream_fill_t *fill, size_t length, uint32_t flags)

仅发布最早 pending 且已撤离引用的生产者借用。

备注

任务/IRQ 中为 O(1)。消费者通过原有流执行 acquire/release。

参数:

  • producer – [inout] 与 reserve 相同的排他生产者

  • fill – [in] 精确的最旧令牌，已从全部硬件目标中撤离

  • length – [in] 正数有效字节数，最多为块容量

  • flags – [in] 实际观测到的 IDLE/TRIGGER/ERROR 边界事实

返回:

SUCCESS、INVALID 或 STATE；拒绝时保留借用

nx_result_t nx_stream_post_abort(nx_stream_producer_t *producer, const nx_stream_fill_t *fill, bool memory_quiesced)

证明内存排空后，取消最新 pending 填充。

备注

任务/IRQ 中为 O(1)。不推进消费者或已发布游标，不会在后续发布位置前产生 FREE 空洞。停止会关闭准入，但仍允许经证明的尾部回滚。

参数:

  • producer – [inout] 同一生产者；回滚严格遵循 LIFO

  • fill – [in] 精确的最新待完成令牌

  • memory_quiesced – [in] 源已撤离，不再有剩余写入

返回:

SUCCESS、BUSY、STATE 或 INVALID；失败时保留借用

struct nx_stream_slot_t
#include <stream.h>

调用者拥有的块元数据；仅初始化 data 与 capacity。

备注

存储须保持有效，直到生产者和消费者均已静止。

公共成员

uint8_t *data
size_t capacity
size_t length
uint64_t epoch
uint32_t flags
uint32_t lost_blocks
nx_stream_slot_state_t state
struct nx_stream_t
#include <stream.h>

调用者拥有的 stream 控制，必须先初始化再发布。

备注

outstanding 统计非空闲块，包括填充中、就绪和已借用状态。仅流操作可修改该计数。

公共成员

nx_stream_slot_t *slots
size_t count
size_t producer
size_t consumer
size_t outstanding
uint64_t epoch
uint32_t losses
bool stopping
struct nx_stream_fill_t
#include <stream.h>

可变生产者借用；中止或发布前必须停止硬件。

公共成员

uint8_t *data
size_t capacity
size_t slot
uint64_t epoch
struct nx_stream_producer_t
#include <stream.h>

调用者显式选择的预提交生产者，不产生默认成本。

备注

一个串行化生产者拥有本控制对象及流。预提交生产者活动期间，不得混用普通 reserve/publish/abort。两个硬件目标在引用撤离前保持 FILLING。发布遵循 FIFO，回滚遵循 LIFO，以免在消费者路径中留下空洞。

公共成员

nx_stream_t *stream
size_t cursor
size_t pending
struct nx_stream_block_t
#include <stream.h>

不可变消费者借用，直到匹配释放成功之前均有效。

公共成员

const uint8_t *data
size_t length
size_t slot
uint64_t epoch
uint32_t flags
uint32_t lost_blocks

stream_budget.h

可选恒定工作量快照与经过检查的冷态容量计算。

作者 Nexus Team

函数

nx_result_t nx_stream_observe(const nx_stream_t *stream, nx_stream_observation_t *out)

在一个短 IRQ 临界区内快照维护的元数据。

备注

任务/IRQ 中的固定工作量，不扫描槽，也不访问载荷。调用方须保持全部存储有效；不保留观测者引用。next_free 是普通流游标，不是私有预提交游标。输出与全部载荷分离。

参数:

  • stream – [in] 已初始化的活动存储，不得并发销毁。

  • out – [out] 独立输出；元数据或别名检查拒绝时保持不变。

返回:

SUCCESS；控制事实不一致时返回 INVALID 或 STATE。

nx_result_t nx_stream_budget_calculate(const nx_stream_budget_t *budget, nx_stream_budget_result_t *out)

经过检查的冷态计算，不修改 stream 或分配存储。

备注

required = targets + spares + ceil(raterelease_delay / (block_units1000000))；载荷大小为 requiredblockunit_bytes。在所声明的 FIFO 队首释放延迟界限下，此有限算术计算是保守的；乱序释放仍可能阻塞下一个游标。延迟要求 target_delay_us < floor(units_per_block*1000000/units_per_second)。本计算不建立背压，也不构成硬件资格证明。

参数:

  • budget – [in] 显式速率、最长释放延迟和流水线配置。

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

返回:

SUCCESS、INVALID；算术溢出时返回 EXHAUSTED。

struct nx_stream_observation_t
#include <stream_budget.h>

O(1) 汇总事实；总空闲容量不证明游标位置空闲。

公共成员

size_t capacity
size_t outstanding
size_t free_blocks
uint64_t epoch
uint32_t losses
bool next_free
bool stopping
struct nx_stream_budget_t
#include <stream_budget.h>

显式工程假设，不推断硬件速率。

备注

release_delay 包含每个已发布 FIFO 队首块直到释放为止的排队和消费者延迟。通过 unit_bytes 将单位转换为字节。targets/spares 是实际选择的硬件借用。除 delay/targets/spares 外，全部量均为正数。

公共成员

uint64_t units_per_second
size_t units_per_block
size_t unit_bytes
nx_time_us_t release_delay_us
nx_time_us_t target_delay_us
size_t hardware_targets
size_t spare_blocks
size_t configured_blocks
struct nx_stream_budget_result_t
#include <stream_budget.h>

依据声明假设得到的保守预算，绝不作为物理证据。

公共成员

size_t retained_blocks
size_t required_blocks
size_t required_payload_bytes
nx_time_us_t block_fill_us
bool capacity_sufficient
bool target_latency_sufficient

stream_profile.h

可选只读的连续流冷准入配置。

作者 Nexus Team

函数

nx_result_t nx_uart_stream_profile_start(const nx_uart_stream_profile_t *profile, nx_stream_t *stream)

绑定的 UART 借用缓冲池之前验证实际缓冲池。

备注

调用方须在此次冷缓冲池检查前等待全部池用户退出。在 provider 派发前失败，不会建立借用、改变 epoch 或产生硬件副作用。速率、FIFO 队首持有时间及 IRQ 延迟始终是声明的假设，不是量测。本操作不建立外部 UART 流控，也不保证无丢失。底层未使用 profile 的 API 保留其显式契约。

参数:

  • profile – [in] 稳定、只读且已经审核的绑定与假设。

  • stream – [inout] 已初始化且尚未借出的缓冲池，块数及各块字节容量与声明精确一致；须保持有效，直到原 provider 停止且全部消费者释放借用。

返回:

几何或别名不匹配时为 INVALID；停止中的元数据返回 STATE；已有借用时为 BUSY；不在中断未屏蔽任务上下文中时为 CONTEXT；溢出或预算不足时为 EXHAUSTED；目标延迟不满足要求时为 UNSUPPORTED；其余情况返回 provider 结果。

nx_result_t nx_adc_stream_profile_start(const nx_adc_stream_profile_t *profile, nx_stream_t *stream, uint32_t trigger_hz)

ADC 准入之前验证缓冲池与完整扫描速率。

备注

ADC 停止触发会产生采样缺口。任何预算都不能使这一暂停保留按实际时间连续发生的采样，也不能证明未来消费者或 IRQ 的界限。不会创建观测者或队列。

参数:

  • profile – [in] 到所选 ADC 接口的稳定只读绑定。

  • stream – [inout] 已初始化且未借出的精确缓冲池，要求同 UART。

  • trigger_hz – [in] 每秒完整扫描的正数标称次数，不大于所声明的生产速率上界。

返回:

冷检查错误同 UART，否则返回原 info/start 结果。provider 的扫描、定时器、DMA/cache 及别名检查仍然适用；任何被拒绝的操作都不保留新引用。

struct nx_uart_stream_profile_t
#include <stream_profile.h>

选定的 UART 接口与不可变的字节流假设。

备注

已审核的装配绑定实际连续 provider。要求两个硬件目标及一个替补块。profile 不分配也不拥有调用方的缓冲池。普通字节接口及 provider 状态布局保持不变。冷准入以 O(n^2) 重新检查载荷互不重叠；IRQ 或稳定 I/O 路径不增加额外检查。

公共成员

const nx_uart_port_t *port
nx_stream_budget_t budget
struct nx_adc_stream_profile_t
#include <stream_profile.h>

选定的 ADC 接口与完整扫描流假设。

备注

一个单位是一轮完整的所选扫描，每通道存储一个 uint16_t。分辨率位数不能替代存储位宽。几何和速率是已审核的装配输入，不能据此证明采样准确度或孔径时刻。

公共成员

const nx_adc_port_t *port
nx_stream_budget_t budget

timer.h

固定定时器／通道 PWM，共享同一个基准配置。

作者 Nexus Team

函数

nx_result_t nx_pwm_port_set(const nx_pwm_port_t *port, uint32_t period_ticks, uint32_t duty_ticks)

原子暂存已审查固定基准 PWM 的占空比。

备注

影子更新在下一次更新事件生效；成功暂存不代表电气输出立即改变。

参数:

  • port – [inout] 固定定时器/通道，只有一个串行化写入者。

  • period_ticks – [in] 已维护共享时基的正数周期。

  • duty_ticks – [in] 从零到 period_ticks，包含两端。

返回:

成功或 INVALID/STATE/BUSY。零及 100% 对应显式恒定电平。共享通道必须使用同一 PSC/ARR/时基；配置会拒绝改变其他通道的时基。

nx_result_t nx_pwm_port_start(const nx_pwm_port_t *port)

启用此前已配置的固定 PWM 输出。

参数:

  • port – [inout] Board 已设置无效电平后的执行所有者。

返回:

成功或 INVALID/STATE。

nx_result_t nx_pwm_port_stop(const nx_pwm_port_t *port)

以声明的 Board 非活动电气电平停止 PWM。

参数:

  • port – [inout] 已静止的执行所有者；不得并发 set/start。

返回:

成功或 INVALID；不承诺高级 break/capture 能力。

nx_result_t nx_pwm_port_state(const nx_pwm_port_t *port, nx_pwm_state_t *state)

查询暂存 PWM 计数与选定定时器时钟。

参数:

  • port – [in] 固定且已初始化的通道。

  • state – [out] 已暂存的计数、时钟及运行状态。

返回:

成功或 INVALID。

struct nx_pwm_state_t
#include <timer.h>

PWM 计数对应固定声明的预分频后定时器时钟。

公共成员

uint32_t period_ticks
uint32_t duty_ticks
uint32_t tick_hz
bool running
struct nx_pwm_ops_t
#include <timer.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*set)(void *context, uint32_t period_ticks, uint32_t duty_ticks)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_state_t *state)
struct nx_pwm_port
#include <timer.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_pwm_ops_t *ops
void *context

timer_capture.h

可选原始定时器边沿捕获与调用者拥有的事件。

作者 Nexus Team

枚举

enum nx_timer_capture_flags

可观察丢失事件，不是准确的物理边沿总数。

取值：

enumerator NX_TIMER_CAPTURE_OVERCAPTURE
enumerator NX_TIMER_CAPTURE_RING_LOSS

函数

nx_result_t nx_timer_capture_start(const nx_timer_capture_t *port, nx_timer_capture_event_t *events, size_t capacity)

借用准确事件环并启用固定捕获通道。

备注

环一直被借用，直到 stop 成功。ISR 对事件存储的访问仅限于该环。借用期间调用方不得修改环或其 provider。计数器按已报告位宽取模回卷；观测时间不是绝对边沿时间戳，也不构成时钟准确度资格证明。

参数:

  • port – [in] 单一特权任务所有者，与 stop/read 串行执行。

  • events – [inout] 已对齐的可写环，容量为正数。

  • capacity – [in] 事件数量；无隐藏缓冲或工作任务。

返回:

SUCCESS 转移环的借用；拒绝时不保留任何引用。

nx_result_t nx_timer_capture_stop(const nx_timer_capture_t *port)

归还存储之前禁用并读回通道／IRQ 源。

备注

捕获停止后，read 仍可排空事件。撤离失败绝不释放存储。仅在 stop 成功且发布者静止后，冷装配才释放 Board 引脚、定时器时钟及共享向量租约。

参数:

  • port – [in] 特权任务所有者，并保留生成的 IRQ 所有者。

返回:

SUCCESS 是对环的最后一次访问；仍有排队事件或硬件撤离失败时，BUSY 保留借用。

nx_result_t nx_timer_capture_read(const nx_timer_capture_t *port, nx_timer_capture_event_t *event)

在短且保存原屏蔽状态的元数据临界区内复制最早事件。

参数:

  • port – [in] 单一特权任务消费者。

  • event – [out] 独立可写输出；EMPTY 或拒绝时保持不变。

返回:

SUCCESS、EMPTY、STATE 或 INVALID；无需另行释放块。

nx_result_t nx_timer_capture_state(const nx_timer_capture_t *port, nx_timer_capture_state_t *state)

查询计数器单位与可观察队列／丢失事实。

备注

硬件过捕获和环饱和可能合并边沿。丢失事件不用于估算边沿数量、边沿频率或实际 IRQ WCET。

参数:

  • port – [in] 特权任务所有者；不得并发执行生命周期写操作。

  • state – [out] 独立可写快照。

返回:

SUCCESS 或 INVALID/STATE/CONTEXT。

struct nx_timer_capture_event_t
#include <timer_capture.h>

硬件模计数器与独立的 IRQ 观察时间。

公共成员

nx_time_us_t observed_at
uint32_t captured_ticks
uint32_t flags
struct nx_timer_capture_state_t
#include <timer_capture.h>

固定计数器单位与当前软件保留状态。

公共成员

uint32_t tick_hz
uint32_t loss_incidents
size_t pending
uint8_t counter_bits
bool running
bool draining
struct nx_timer_capture_ops_t
#include <timer_capture.h>

共享不可变方法；不逐次取得资源或分配。

公共成员

nx_result_t (*start)(void *context, nx_timer_capture_event_t *events, size_t capacity)
nx_result_t (*stop)(void *context)
nx_result_t (*read)(void *context, nx_timer_capture_event_t *event)
nx_result_t (*state)(const void *context, nx_timer_capture_state_t *state)
struct nx_timer_capture
#include <timer_capture.h>

不可变身份；状态和方法必须在所有调用与 IRQ 完全退出前保持有效。

公共成员

const nx_timer_capture_ops_t *ops
void *context

uart.h

IRQ TX 请求与分别预算的字节／事件接收。

作者 Nexus Team

宏定义

NX_UART_EVENT_PARITY
NX_UART_EVENT_FRAMING
NX_UART_EVENT_OVERRUN
NX_UART_EVENT_NOISE
NX_UART_EVENT_LOSS
NX_UART_EVENT_NO_BYTE

枚举

enum nx_uart_rx_profile_t

取值：

enumerator NX_UART_RX_BYTES
enumerator NX_UART_RX_EVENTS
enumerator NX_UART_RX_BLOCKS

函数

nx_result_t nx_uart_tx_prepare(nx_uart_tx_request_t *request, const uint8_t *data, size_t length, nx_time_us_t deadline)

准备未借用 IRQ TX 描述符，不复制数据。

参数:

  • request – [inout] 新初始化的请求，或已经消费的 SETTLED 请求。

  • data – [in] 非空载荷，保持不变直到 SETTLED。

  • length – [in] 正数字节数。

  • deadline – [in] nx_time_now_us 时钟域中的绝对时限。

返回:

NX_SUCCESS 或 INVALID/STATE；失败时不保留缓冲引用。

nx_result_t nx_uart_port_submit(const nx_uart_port_t *port, nx_uart_tx_request_t *request)

向单执行者 UART 提交一个直接请求。

备注

仅限任务上下文的有界准入。TX 完成须等待真正的 TC，即线路空闲。IRQ 仅搬运字节或发布硬件事实；所有者调用 service 以观测时限并结算请求。最先观测到的终态事实锁定其结果。后续 service、时限或取消不会覆盖已观测到的 TC。IRQ/service 延迟界限仍是 provider 与产品资格验证的输入。

参数:

  • port – [inout] 由当前执行上下文拥有、已初始化且空闲的端口。

  • request – [inout] READY 描述符；仅在 NX_SUCCESS 时借用。

返回:

NX_SUCCESS 表示 ACCEPTED，包括随后启动失败的情况。BUSY/INVALID/CONTEXT/STATE/TIMEOUT 表示 REJECTED，借用为零；直接提交时已经过期的请求不获准入。

nx_result_t nx_uart_port_start_admitted(const nx_uart_port_t *port, nx_uart_tx_request_t *request)

启动适配器已准入的 QUEUED 请求，不重复准入。

参数:

  • port – [inout] 已初始化的单执行者端口。

  • request – [inout] 已由适配器借用的 QUEUED 描述符。

返回:

BUSY 保留 QUEUED；NX_SUCCESS 将执行权转给端口。其他启动错误须由适配器执行者结算。

nx_result_t nx_uart_port_cancel(const nx_uart_port_t *port, nx_uart_tx_request_t *request)

请求取消；接受取消不表示请求结清。

参数:

  • port – [inout] 与 submit/service 相同的单一执行所有者。

  • request – [inout] 当前活动且有效的描述符；跨任务调用方应使用稳定的适配器槽及期望 epoch，不能使用此指针。

返回:

取消仍待完成或已结算时返回 NX_SUCCESS；请求不匹配时为 STATE。借用持续到 SETTLED。

void nx_uart_port_service(const nx_uart_port_t *port)

观察时间／硬件完成并排空一个活动请求。

备注

有界操作，无等待或回调；在 stop/drain 全程及所声明的最大 service 间隔内持续调用。发布完成是对请求的最后一次访问。硬件不能排空时保留 QUARANTINED。

参数:

  • port – [inout] 单一任务/主循环执行所有者。

nx_result_t nx_uart_port_read_events(const nx_uart_port_t *port, nx_uart_rx_event_t *events, size_t capacity, size_t *count)

从选定事件配置读取缓冲的 RX 事件。

参数:

  • port – [inout] 已初始化的事件 profile 端口；只有一个消费者。

  • events – [out] 调用方拥有的目标存储；不保留引用。

  • capacity – [in] 目的事件数量。

  • count – [out] 已复制的事件，包含显式丢失/错误标志。

返回:

NX_SUCCESS、EMPTY 或 INVALID/UNSUPPORTED。IRQ 只向已配置存储生产数据；溢出绝不静默覆盖。

nx_result_t nx_uart_port_read_bytes(const nx_uart_port_t *port, uint8_t *bytes, size_t capacity, size_t *count)

从选定字节配置读取缓冲字节。

参数:

  • port – [inout] 已初始化的字节 profile 端口；只有一个消费者。

  • bytes – [out] 调用方拥有的目标存储；不保留引用。

  • capacity – [in] 目标容量，单位为字节。

  • count – [out] 已复制的字节数；返回 OVERFLOW 时仍有效；提供者在复制字节并尝试重新启用 RX 后发生 IO 失败时也仍有效。

返回:

NX_SUCCESS、EMPTY、OVERFLOW 或 INVALID/UNSUPPORTED。字节模式报告累计丢失，不虚构时间戳。提供者若在复制后重新启用 RX 源失败，可以返回 IO；count 和已复制字节仍有效。准入关闭，仍保留责任的硬件必须经验证停止。

nx_result_t nx_uart_port_stop(const nx_uart_port_t *port)

关闭准入，并在释放硬件之前排空 TX。

备注

回收存储前，RX/IRQ 和外部消费者必须静止。不自动销毁任务或通知对象。

参数:

  • port – [inout] 所有者；生产者必须已经静止。

返回:

停止后返回 NX_SUCCESS；仍须继续 service 时返回 BUSY。

nx_result_t nx_uart_port_attach_wake(const nx_uart_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

附加或解除一个显式 IRQ 唤醒目标。

备注

回收旧目标前，须等待全部先前发布者静止。IRQ 事件在通知前锁存 RX/完成事实。解除绑定阻止未来发布；通知存储仍须等待外部等待者和回调退出。

参数:

  • port – [in] 已初始化的 provider，由单一任务执行者控制。

  • wake – [in] 不可变的活动目标；NULL 表示解除绑定。

  • syscall_ceiling – [in] 可选的额外未移位内核安全优先级数值下限；不得削弱生成策略。PRIMASK 内核目标要求为零。不调用内核时忽略。

返回:

成功；不在任务控制上下文时返回 CONTEXT；实际 IRQ 优先级不安全时返回 PERMISSION；也可能返回 provider 的 STATE/UNSUPPORTED。

nx_result_t nx_uart_port_rx_start(const nx_uart_port_t *port, nx_stream_t *stream)

使用调用者准确存储启动选定 RX 块模式。

备注

provider 的边界和缺口是显式能力事实。provider 绝不能覆盖被消费者借用的块。

参数:

  • port – [in] 支持块的 provider，只有一个任务执行所有者。

  • stream – [inout] 已初始化的块流；保留到 RX 停止且全部已获取的消费者块被释放。

返回:

成功或 INVALID/BUSY/UNSUPPORTED；失败准入的借用为零。所选硬件模式验证每个 DMA 块的内存域。

nx_result_t nx_uart_port_rx_stop(const nx_uart_port_t *port)

停止 RX 块生产，不撤销消费者借用。

备注

消费者单独排空 READY 块并释放借用；RX stop 成功不会销毁流或 wake 存储。

参数:

  • port – [in] 与 RX start 相同的执行者；BUSY 时存储继续有效。

返回:

成功证明内存访问源已撤离；BUSY 保留生产者借用；仅支持字节/事件的 provider 返回 UNSUPPORTED。

struct nx_uart_rx_event_t
#include <uart.h>

时间戳属于提供者时钟；精度由硬件决定。

备注

NO_BYTE 标识仅含状态的 IRQ 事实：byte 无效。LOSS 是独立的 NO_BYTE 边界标记，排在更旧的已缓冲事实之后、后续接收之前。其时间戳是 provider 检测或报告的时间，绝不是为丢失字节重建的时间戳。字节 profile 读取报告累计丢失，并省略仅含状态的事实。

公共成员

nx_time_us_t timestamp_us
uint32_t flags
uint8_t byte
struct nx_uart_tx_request_t
#include <uart.h>

调用者拥有的 TX 描述符；第一次 prepare 之前必须初始化 base。

公共成员

nx_request_t base
const uint8_t *data
size_t length
struct nx_uart_ops_t
#include <uart.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*submit)(void *context, nx_uart_tx_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_uart_tx_request_t *request)
nx_result_t (*cancel)(void *context, nx_uart_tx_request_t *request)
void (*service)(void *context)
nx_result_t (*read_events)(void *context, nx_uart_rx_event_t *events, size_t capacity, size_t *count)
nx_result_t (*read_bytes)(void *context, uint8_t *bytes, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
nx_result_t (*rx_start)(void *context, nx_stream_t *stream)
nx_result_t (*rx_stop)(void *context)
struct nx_uart_port
#include <uart.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_uart_ops_t *ops
void *context

uart_format.h

显式的载荷、校验、停止位与硬件流控格式。

作者 Nexus Team

枚举

enum nx_uart_parity_t

取值：

enumerator NX_UART_PARITY_NONE
enumerator NX_UART_PARITY_EVEN
enumerator NX_UART_PARITY_ODD
enum nx_uart_stop_t

取值：

enumerator NX_UART_STOP_1
enumerator NX_UART_STOP_2
enum nx_uart_flow_t

取值：

enumerator NX_UART_FLOW_NONE
enumerator NX_UART_FLOW_RTS
enumerator NX_UART_FLOW_CTS
enumerator NX_UART_FLOW_RTS_CTS

函数

nx_result_t nx_uart_format_validate(nx_uart_format_t format)

验证公共 USART-v1 子集，不访问硬件。

备注

纯函数、有界，任务/IRQ 安全；Board 准入仍单独处理。

参数:

  • format – [in] 显式载荷位宽、奇偶校验、停止位和流控选择。

返回:

7E/O、8N/E/O 或 9N 配合一个或两个停止位时成功；未知值返回 INVALID，已知但不兼容的组合返回 UNSUPPORTED。

struct nx_uart_format_t
#include <uart_format.h>

不可变的线上格式；data_bits 不含校验位。

备注

RTS/CTS 需要单独审核 Board 路由及对端接线。

公共成员

uint8_t data_bits
nx_uart_parity_t parity
nx_uart_stop_t stop
nx_uart_flow_t flow

uart_rs485.h

可选单所有者 RS485 方向与线尾适配器。

作者 Nexus Team

类型定义

typedef nx_result_t (*nx_uart_tx_validate_fn)(void *context, const nx_uart_tx_request_t *request)

准确传输端口的无副作用 TX 准入验证器。

备注

读取时钟/硬件事实，但不写 GPIO/MMIO，不准入、不启动，也不保留引用。一个执行者拥有适配器及传输接口；不允许外部直接 TX。

参数 context:

[in] 不可变传输接口的精确 context。

参数 request:

[in] 活动的 READY 或 QUEUED 描述符；绝不保留引用。

返回值:

采用与传输接口 submit/start 相同的可拒绝检查。

函数

nx_result_t nx_uart_rs485_initialize(nx_uart_rs485_state_t *state, const nx_uart_rs485_config_t *config)

绑定独占传输端口并建立非活动 DE。

备注

仅限任务上下文，不等待。不推定物理收发器存在。成功置有效 DE 后开始 setup；通过 acquire 语义观测到传输真正结算后才开始 hold。传输时限包括 setup 和线路完成；必须执行的 drain/hold 可使借用持续到该时限之后。TX 被拒绝时 DE 和传输接口均不变。排空或 DE 撤离失败时，保留 QUARANTINED 外层存储及 DE 所有权，直到 service 重试。

参数:

  • state – [inout] 调用方拥有的全新零初始化控制对象。

  • config – [in] 生命周期内不可变的绑定；一个获授权的 DE 位、实际板级极性，以及 nx_time_now_us 域中的 setup/hold。

返回:

成功或 INVALID/CONTEXT/STATE/GPIO 失败；无 TX 借用。

变量

const nx_uart_ops_t nx_uart_rs485_ops
struct nx_uart_rs485_config_t
#include <uart_rs485.h>

不可变的选定电气／时序事实，不含任务或堆。

备注

绑定期间，配置、接口、ops 及 context 身份不得改变。它们与可变适配器、请求及载荷存储分离；精确引脚所有权由外部负责。

公共成员

const nx_uart_port_t *transport
const nx_gpio_port_t *direction
nx_uart_tx_validate_fn validate
uint32_t mask
nx_time_us_t setup_us
nx_time_us_t hold_us
bool active_high
struct nx_uart_rs485_state_t
#include <uart_rs485.h>

调用者显式选择的适配器，init 前零初始化。

备注

初始化后控制对象为私有。不可变配置、两个接口、引脚所有权及全部存储，须保持有效直到 stop 成功且外部观测者退出。默认 UART 状态不变。

公共成员

const nx_uart_rs485_config_t *config
nx_uart_tx_request_t inner
nx_uart_tx_request_t *active
nx_time_us_t boundary
nx_result_t terminal
size_t transferred
uint8_t phase
bool initialized
bool closing

uart_word.h

独立的九位接口与调用者拥有的字请求。

作者 Nexus Team

函数

nx_result_t nx_uart_word_tx_prepare(nx_uart_word_tx_request_t *request, const uint16_t *data, size_t words, nx_time_us_t deadline)

准备尚未借用的九位载荷，不执行准入。

备注

任务所有者；载荷值在 provider 准入前检查。

参数:

  • request – [inout] 已初始化的 READY 或已消费的 SETTLED 描述符。

  • data – [in] 已对齐的不可变字数组，与描述符分离。

  • words – [in] 正数字数，可表示为字节范围。

  • deadline – [in] nx_time_now_us 单调域中的绝对传输时限。

返回:

成功、INVALID 或 STATE；拒绝时不保留引用，也不产生副作用。

nx_result_t nx_uart_word_port_submit(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

将一个 READY 请求准入唯一、未屏蔽中断的任务执行者。

备注

计数以字为单位；完成要求实际线路 TC。

参数:

  • port – [in] 已初始化的活动接口、私有状态及 IRQ 绑定。

  • request – [inout] 调用方拥有的描述符；成功时借用。

返回:

成功表示 ACCEPTED；拒绝时不借用，也不产生硬件副作用。

nx_result_t nx_uart_word_port_start_admitted(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

接管适配器的 QUEUED 借用，不再次准入。

参数:

  • port – [in] 活动的单所有者接口。

  • request – [inout] 已有适配器借用。

返回:

成功转移执行权；BUSY 保留 QUEUED 及其借用。

nx_result_t nx_uart_word_port_cancel(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

请求取消，不撤销请求／载荷的所有权。

备注

排空期间继续 service；排空失败时保留 QUARANTINED。

参数:

  • port – [in] 与 submit/service 相同的中断未屏蔽任务执行者。

  • request – [inout] 活动请求；跨任务控制使用稳定的槽。

返回:

当前请求返回成功；其他活动请求返回 STATE。

void nx_uart_word_port_service(const nx_uart_word_port_t *port)

由所有者执行有界的截止时间、排空与结清工作。

备注

IRQ 仅发布事实；SETTLED 是 provider 的最后一次访问。无等待、隐藏工作任务或回调；须遵守所声明的最大 service 间隔。

参数:

  • port – [in] 单一中断未屏蔽任务所有者，保持有效直到 stop 完成。

nx_result_t nx_uart_word_port_read(const nx_uart_word_port_t *port, uint16_t *words, size_t capacity, size_t *count)

复制字，不持续借用目标存储。

备注

丢失不会虚构硬件时间戳，也不会虚构缺失字数。

参数:

  • port – [in] 已初始化的接口，由任务执行者控制且只有一个消费者。

  • words – [out] 已对齐的目标，与 provider/RX 存储分离。

  • capacity – [in] 正数目标容量，单位为字。

  • count – [out] 已复制数量；OVERFLOW 时也有效。

返回:

成功、EMPTY、OVERFLOW、INVALID、CONTEXT 或 STATE。

nx_result_t nx_uart_word_port_stop(const nx_uart_word_port_t *port)

关闭准入，并在活动 TX 与 IRQ 源排空后停止。

备注

回收 provider 存储前，调用方须等待全部正在执行的 IRQ 退出。

参数:

  • port – [in] 单一任务所有者；外部生产者和观测者已静止。

返回:

硬件引用撤离后成功；仍须继续 service 时返回 BUSY。

struct nx_uart_word_tx_request_t
#include <uart_word.h>

每个 uint16_t 包含 0..511；按字计数，不以字节计且不包含校验位。

备注

请求及保持不变的载荷持续被借用，直到以 acquire 语义观测到 SETTLED。

公共成员

nx_request_t base
const uint16_t *data
size_t words
struct nx_uart_word_ops_t
#include <uart_word.h>

公共成员

nx_result_t (*submit)(void *context, nx_uart_word_tx_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_uart_word_tx_request_t *request)
nx_result_t (*cancel)(void *context, nx_uart_word_tx_request_t *request)
void (*service)(void *context)
nx_result_t (*read)(void *context, uint16_t *words, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
struct nx_uart_word_port
#include <uart_word.h>

独立不可变接口；默认字节接口／状态不增加。

备注

静态身份；查找不分配、不发现设备，也不初始化。

公共成员

const nx_uart_word_ops_t *ops
void *context

usb_activation.h

可选的非零 USB endpoint 显式激活接口。

作者 Nexus Team

函数

nx_result_t nx_usb_activation_set(const nx_usb_activation_port_t *port, uint64_t epoch, uint8_t endpoint_address, bool active)

显式激活或反激活一个已选定的非零 endpoint 方向。

备注

不借用任何 request 或 buffer。目标变更之前，必须显式取消并排空该目标的既有借用；失败从不撤销其他借用。配置／类策略仍由外部负责。

参数:

  • port – [in] 已启动；由序列化特权 Task owner 调用，进入时 IRQ masks 须 clear。

  • epoch – [in] 当前软件 USB epoch；冷态 epoch 0 合法。

  • endpoint_address – [in] USB 地址字节；不准入 EP0。

  • active – [in] 请求的 active 状态；此操作从不提交 packet。

返回:

证明成立后成功；操作缺失时返回 UNSUPPORTED。INVALID／CONTEXT／STATE／BUSY 在写入前拒绝。IO 可能已有部分效果，并关闭 controller 准入，直到显式恢复。

struct nx_usb_activation_ops_t
#include <usb_activation.h>

可选的 controller 操作；操作缺失时返回 UNSUPPORTED。

公共成员

nx_result_t (*set)(void *context, uint64_t epoch, uint8_t endpoint_address, bool active)
struct nx_usb_activation_port
#include <usb_activation.h>

不可变的借用 face，使用既有 controller context。

公共成员

const nx_usb_activation_ops_t *ops
void *context

usb_device.h

全速设备数据包与调用者拥有的端点借用。

作者 Nexus Team

枚举

enum nx_usb_stage_t

取值：

enumerator NX_USB_DATA
enumerator NX_USB_STATUS
enum nx_usb_event_kind_t

取值：

enumerator NX_USB_EVENT_SETUP
enumerator NX_USB_EVENT_RESET
enumerator NX_USB_EVENT_SUSPEND
enumerator NX_USB_EVENT_RESUME
enumerator NX_USB_EVENT_LOSS

函数

nx_result_t nx_usb_in_prepare(nx_usb_request_t *request, const uint8_t *bytes, size_t length, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)

准备一个 IN 数据包，不读取或借用其字节。

参数:

  • request – [inout] 已初始化且未借出的请求。

  • bytes – [in] 不可变报文字节；仅在长度为零时允许 NULL。

  • length – [in] 报文长度；不自动追加终止 ZLP。

  • stage – [in] DATA 或控制 STATUS；STATUS 长度必须为零。

  • epoch – [in] EP0 使用当前 SETUP epoch；非零端点使用零。

  • deadline – [in] 独立单调时钟中的绝对时限。

返回:

成功、INVALID 或 STATE；拒绝时不保留引用。

nx_result_t nx_usb_out_prepare(nx_usb_request_t *request, uint8_t *bytes, size_t capacity, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)

准备 OUT 数据包容量，不修改其存储。

参数:

  • request – [inout] 已初始化且未借出的请求。

  • bytes – [out] 仅在提交被接受后借用，持续到 SETTLED。

  • capacity – [in] 最多为端点 MPS；短包正常完成。

  • stage – [in] DATA 或容量为零的控制 STATUS。

  • epoch – [in] EP0 使用当前 SETUP epoch；非零端点使用零。

  • deadline – [in] 独立单调时钟中的绝对时限。

返回:

成功、INVALID 或 STATE；拒绝时不建立借用。

nx_result_t nx_usb_endpoint_submit(const nx_usb_endpoint_port_t *port, nx_usb_request_t *request)

仅准入一个数据包，不隐式建立队列或执行完整 USB 事务。

备注

单一特权任务执行者，IRQ 屏蔽须解除。写入 IN FIFO 不能证明主机已 ACK。OUT 过长时仍排空全部报文字，不使目标缓冲溢出。

参数:

  • port – [in] 稳定的端点接口及私有状态。

  • request – [inout] READY 报文；缓冲须保持有效，直到以 acquire 语义观测到 SETTLED。

返回:

成功表示 ACCEPTED；第四方缓冲不会被提前复制。

nx_result_t nx_usb_endpoint_cancel(const nx_usb_endpoint_port_t *port, nx_usb_request_t *request)

请求端点禁用／排空，不撤销缓冲区借用。

备注

控制 OUT0 没有硬件禁用命令：取消可能需要完整停止设备才能结算。缺少证明时进入 QUARANTINED。Reset/SETUP 使 epoch 失效，但只有实际源排空后才释放借用。

参数:

  • port – [in] 同一个串行化特权任务所有者。

  • request – [inout] 由此精确端点接受的活动请求。

返回:

成功表示请求排空；失败时保留全部先前接受的借用。

nx_result_t nx_usb_endpoint_stall(const nx_usb_endpoint_port_t *port, bool stalled)

仅端点无存活传输时设置／清除 STALL。

参数:

  • port – [in] 已启动的串行化所有者，IRQ 屏蔽须解除。

  • stalled – [in] 期望的 STALL；清除 bulk/interrupt STALL 时同时复位 DATA0。

返回:

回读验证后成功；BUSY 保留待完成请求。

nx_result_t nx_usb_device_service(const nx_usb_device_port_t *port)

仅 Task 有界推进；截止时间绝不依赖 USB SOF。

参数:

  • port – [in] 串行化特权所有者；进入时 IRQ 屏蔽须解除。

返回:

成功表示请求推进；不提前释放时钟或端点借用。

nx_result_t nx_usb_device_read_events(const nx_usb_device_port_t *port, nx_usb_event_t *events, size_t capacity, size_t *count)

消费有界值事件，绝不保留输出。

备注

Invalid/STATE 拒绝时，两个输出均保持不变。

参数:

  • port – [in] 单一任务消费者及稳定控制器。

  • events – [out] 调用方记录，与 provider 及活动借用分离。

  • capacity – [in] 正数输出数量。

  • count – [out] 独立的计数输出；EMPTY 表示零。

返回:

成功、EMPTY 或拒绝；state 中的最新 SETUP 才是权威事实。

nx_result_t nx_usb_device_state(const nx_usb_device_port_t *port, nx_usb_device_state_t *state)

仅 Task 的权威快照，与事件环可用空间无关。

参数:

  • port – [in] 串行化特权所有者，IRQ 屏蔽须解除。

  • state – [out] 与其他存储分离的调用方快照；不保留引用。

返回:

成功时复制状态；别名或上下文检查拒绝时输出不变。

nx_result_t nx_usb_device_address(const nx_usb_device_port_t *port, uint64_t epoch, uint8_t address)

为匹配的零数据标准 SETUP 暂存 SET_ADDRESS。

参数:

  • port – [in] 串行化特权控制器所有者。

  • epoch – [in] 当前 SETUP 身份。

  • address – [in] 0..127，与 SETUP wValue 匹配。

返回:

成功仅暂存地址；实际 status-IN XFRC 后地址才生效。

nx_result_t nx_usb_device_attach_wake(const nx_usb_device_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

附加／解除被借用且兼容 Task/IRQ 的唤醒提示。

参数:

  • port – [in] 已启动的串行化所有者，IRQ 屏蔽须解除。

  • wake – [in] 不可变目标；NULL 表示解除绑定。

  • syscall_ceiling – [in] 附加的 IRQ 优先级数值下限。

返回:

实际优先级策略检查通过后成功；发布者仍活动时返回 BUSY；拒绝时不保留新接收器。

nx_result_t nx_usb_device_stop(const nx_usb_device_port_t *port)

断开连接、禁用、排空、撤离 IRQ，再释放时钟消费者。

备注

PIO OUT0 可以继续启用：全局 stop 成功意味着在最终 SETTLED 前已证明断开连接、OUT NAK、无 DMA、RX FIFO 为空、IRQ 引用撤离且发布者退出。强制复位不能撤销尚未证明安全释放的已接受借用。

参数:

  • port – [in] 串行化的所有者；还须等待外部观察者退出。

返回:

成功结束 provider 对端点/环/wake 存储的访问；BUSY 保留全部存储及 48MHz 所有权，直到实际推进。

struct nx_usb_request_t
#include <usb_device.h>

公共成员

nx_request_t base
const uint8_t *in
uint8_t *out
size_t length
uint64_t control_epoch
nx_usb_stage_t stage
struct nx_usb_setup_t
#include <usb_device.h>

公共成员

uint8_t request_type
uint8_t request
uint16_t value
uint16_t index
uint16_t length
uint64_t epoch
struct nx_usb_event_t
#include <usb_device.h>

公共成员

nx_usb_setup_t setup
nx_time_us_t timestamp_us
uint64_t lost
nx_usb_event_kind_t kind
struct nx_usb_device_state_t
#include <usb_device.h>

公共成员

nx_usb_setup_t setup
uint64_t epoch
uint64_t lost_events
bool started
bool closing
bool suspended
bool control_pending
uint8_t address
struct nx_usb_endpoint_ops_t
#include <usb_device.h>

共享只读数据包方法；上下文为选定端点。

公共成员

nx_result_t (*submit)(void*, nx_usb_request_t*)
nx_result_t (*cancel)(void*, nx_usb_request_t*)
nx_result_t (*stall)(void*, bool)
struct nx_usb_endpoint_port
#include <usb_device.h>

公共成员

const nx_usb_endpoint_ops_t *ops
void *context
struct nx_usb_device_ops_t
#include <usb_device.h>

控制器身份与端点身份保持分离。

公共成员

nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_usb_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_usb_device_state_t*)
nx_result_t (*address)(void*, uint64_t, uint8_t)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
nx_result_t (*stop)(void*)
struct nx_usb_device_port
#include <usb_device.h>

公共成员

const nx_usb_device_ops_t *ops
void *context

usb_profile.h

仅针对选定实例的不可变 USB 事实。

作者 Nexus Team

备注

选定事实不构成经实际观测建立的物理资格。

枚举

enum nx_usb_fs_limit

取值：

enumerator NX_USB_FS_PHY_CLOCK_HZ
enumerator NX_USB_FS_FIFO_WORDS
enumerator NX_USB_FS_ENDPOINT_NUMBERS
enumerator NX_USB_FS_MAX_PACKET
enum nx_usb_profile_role_t

取值：

enumerator NX_USB_PROFILE_DEVICE
enum nx_usb_profile_speed_t

取值：

enumerator NX_USB_PROFILE_FULL_SPEED
enum nx_usb_profile_phy_t

取值：

enumerator NX_USB_PROFILE_INTERNAL_FS
enum nx_usb_profile_engine_t

取值：

enumerator NX_USB_PROFILE_PIO
enum nx_usb_profile_transfer_t

取值：

enumerator NX_USB_PROFILE_CONTROL
enumerator NX_USB_PROFILE_BULK
enumerator NX_USB_PROFILE_INTERRUPT

函数

nx_result_t nx_usb_profile_validate(const nx_usb_device_profile_t *profile)

校验精确的选定 FS 事实，不观测 controller。

备注

在 Task／ISR 中有界且只读。事实标识选定的软件支持；绝不表示 PCB 布线、VBUS 接线或物理资格。公共元数据、endpoint 数组、face 及 operations table 须按其 C 类型自然对齐，存储范围不能回绕。数值检查中的拒绝不能用于探测任意地址或不透明的私有 context。 EP0 选择 control/64；非零 bulk 选择 8/16/32/64-byte MPS。interrupt 选择非零 IN，MPS 为 1..64-byte。host 轮询间隔属于外部 descriptor，不属于此 profile。

参数:

  • profile – [in] 稳定、可读且不可变的事实、face 及 endpoint 数组。

返回:

成功或 INVALID，公共元数据未对齐也会拒绝；不分配内存，不访问 MMIO，不发现设备，也不影响生命周期。

const nx_usb_endpoint_profile_t *nx_usb_profile_endpoint(const nx_usb_device_profile_t *profile, uint8_t number, bool in)

在先前已校验的不可变 profile 中查找一个方向。

备注

在 Task／ISR 中执行只读有界查找；所有输入的生命周期仍由外部管理。

参数:

  • profile – [in] 稳定、已校验的选定事实及 endpoint 数组。

  • number – [in] 与方向独立的 endpoint 编号。

  • in – [in] true 表示 IN 方向；false 表示 OUT 方向。

返回:

返回选定的稳定成员或 NULL；profile／array 元数据未对齐时也返回 NULL。不能发现新 endpoint。

nx_result_t nx_usb_setup_reject(const nx_usb_setup_decision_port_t *port, uint64_t epoch)

通过经检查的 EP0 IN STALL 拒绝一个已发布的 SETUP epoch。

备注

使用同一个特权单 Task 执行者，进入时中断未屏蔽。provider 在同一局部 IRQ 临界区中检查其已发布的 epoch 并执行 STALL，保留进入时的 mask。该保护排除已由软件发布的替代 SETUP；不保证与尚未被 IRQ 采集的物理总线包之间的原子性。不隐含取消、全局停止、内存分配、class 策略或地址提交。

参数:

  • port – [in] 稳定的选定 decision face，使用同一个 controller owner。

  • epoch – [in] 要拒绝的非零、已由软件发布的 SETUP 身份。

返回:

guard 检查及 STALL 读回成功后返回成功；epoch 已被替代或源正在 closing 时返回 STATE，任一 EP0 packet 仍活动时返回 BUSY，元数据不合法时返回 INVALID，执行者不合法时返回 CONTEXT，STALL 读回失败时返回 IO，未提供可选操作时返回 UNSUPPORTED。拒绝不保留借用。

struct nx_usb_endpoint_profile_t
#include <usb_profile.h>

公共成员

const nx_usb_endpoint_port_t *port
uint16_t max_packet
uint8_t number
bool in
nx_usb_profile_transfer_t transfer
struct nx_usb_setup_decision_ops_t
#include <usb_profile.h>

可选的 epoch 绑定 EP0 拒绝接口，与 generic ops 独立。

公共成员

nx_result_t (*reject)(void*, uint64_t)
struct nx_usb_setup_decision_port_t
#include <usb_profile.h>

公共成员

const nx_usb_setup_decision_ops_t *ops
void *context
struct nx_usb_device_profile_t
#include <usb_profile.h>

公共成员

const nx_usb_device_port_t *port
const nx_usb_endpoint_profile_t *endpoints
size_t endpoint_count
uint32_t phy_clock_hz
uint16_t fifo_words
uint16_t rx_fifo_words
uint8_t endpoint_numbers
nx_usb_profile_role_t role
nx_usb_profile_speed_t speed
nx_usb_profile_phy_t phy
nx_usb_profile_engine_t engine
nx_usb_setup_decision_port_t setup_decision

wake.h

显式借用 IRQ 唤醒目标与系统调用阈值检查。

作者 Nexus Team

枚举

enum nx_irq_kernel_policy_t

显式内核中断屏蔽策略，独立于任何 RTOS。

取值：

enumerator NX_IRQ_KERNEL_NONE
enumerator NX_IRQ_KERNEL_PRIMASK
enumerator NX_IRQ_KERNEL_BASEPRI

函数

nx_result_t nx_irq_wake_validate(const nx_irq_wake_t *wake, const nx_irq_policy_t *policy, const nx_irq_source_t *source)

依据显式内核策略验证实际 IRQ 事实。

备注

无绑定或回调副作用的冷检查。NONE 不接受任何会调用内核的目标。PRIMASK 在固定为零的优先级分组下允许全部有效可配置 IRQ。会调用内核的 BASEPRI 目标要求已维护的抢占分组，且优先级数值不小于阈值。非内核提示不强制内核分组。绑定不授权后续违反 CPU 上下文要求的操作。

参数:

  • wake – [in] 可选不可变目标；NULL 禁用通知。

  • policy – [in] 已验证的不可变 CPU 和内核配置。

  • source – [in] 外部 IRQ 编号、未移位的优先级及分组。

返回:

成功；事实或目标格式错误时返回 INVALID；会调用内核的目标处于不安全中断域时返回 PERMISSION。

nx_result_t nx_irq_wake_signal(const nx_irq_wake_t *wake)

权威状态锁存后发送一个有界提示。

备注

按目标允许的任务/IRQ 上下文执行，无隐藏任务或重试。wake 失败不撤销状态，也不撤销请求所有权。

参数:

  • wake – [in] 先前已验证的活动目标或 NULL。

返回:

回调结果；NULL 返回成功；无效目标返回 INVALID。

struct nx_irq_wake_t
#include <wake.h>

IRQ 提供者借用的可选不可变唤醒目标。

备注

notify 在发布者上下文中运行，必须有界且在该 IRQ 中合法。存储及 context 须比全部发布者存活更久。销毁接收器前，须停止并等待发布者退出。wake 仅为提示；已锁存的 RX/请求谓词仍为权威依据。

公共成员

void *context
nx_result_t (*notify)(void *context)
bool calls_kernel
struct nx_irq_policy_t
#include <wake.h>

用于冷态唤醒绑定的不可变 CPU 与内核事实。

备注

NONE 和 PRIMASK 要求 syscall 阈值为零。BASEPRI 要求非零且未移位的阈值。配置拥有这些事实；wake 目标不能放宽它们。

公共成员

nx_irq_kernel_policy_t kernel
uint16_t external_irq_count
uint8_t priority_bits
uint8_t syscall_ceiling
struct nx_irq_source_t
#include <wake.h>

附加任何被借用的接收端之前读取实际发布者事实。

公共成员

int16_t irq_number
uint8_t priority
uint8_t priority_group

watchdog.h

不可逆 IWDG 效果与中立硬件复位原因。

作者 Nexus Team

宏定义

NX_RESET_POWER_ON
NX_RESET_PIN
NX_RESET_SOFTWARE
NX_RESET_IWDG
NX_RESET_WWDG
NX_RESET_LOW_POWER
NX_RESET_BROWNOUT

函数

nx_result_t nx_watchdog_port_enable(const nx_watchdog_port_t *port, uint32_t timeout_us, bool debug_freeze, nx_watchdog_state_t *state)

启用 IWDG，并报告其生效状态及已知的时间范围；激活不可逆。

备注

成功证明标称硬件编程已完成，不保证时限。振荡器界限未知时，两个超时界限均保持零。需要有界时序的产品必须在激活前准入振荡器配置。Enable 在特权任务中执行，并与 feed、state 和 platform stop 串行化。仅在本调用返回后才可安装 IRQ 喂狗；激活不支持在影子寄存器编程期间并发重载。

参数:

  • port – [inout] 固定 provider；产品拥有喂狗和恢复策略。

  • timeout_us – [in] 所请求的标称超时，须处于已维护范围内。

  • debug_freeze – [in] 请求由 CPU 管理的调试冻结设置；外部调试器配置不属于此请求。

  • state – [out] 实际超时界限及剩余副作用；若启用后后续配置失败，也包括 enabled=true。

返回:

成功，或返回 INVALID/STATE/UNSUPPORTED/IO；绝不声称回滚禁用了已启用的硬件。已有启用状态会被识别。无法由 CPU 访问调试控制的提供者在激活前以 UNSUPPORTED 拒绝 true；它既不查询，也不改变外部调试器控制。

nx_result_t nx_watchdog_port_feed(const nx_watchdog_port_t *port)

喂已启用 IWDG，不改变产品健康策略。

参数:

  • port – [inout] 固定且已启用的 provider，只有一个串行化喂狗所有者。

返回:

成功或 INVALID/STATE；任务/IRQ 中有界，不分配。

nx_result_t nx_watchdog_port_state(const nx_watchdog_port_t *port, nx_watchdog_state_t *state)

查询当前看门狗效果与超时不确定性。

参数:

  • port – [in] 固定 provider。

  • state – [out] 当前硬件状态或已记忆的初始化状态。

返回:

成功或 INVALID；不能确定超时界限时，UNSUPPORTED 保留已观测硬件副作用，并将两个超时界限保持为零。绝不能因查询失败或超时未知而推断看门狗已禁用。

uint32_t nx_reset_cause(void)

读取清除标志前捕获的锁存启动复位原因。

备注

不隐式确认、不重启，也不作产品分类。

返回:

NX_RESET_* 位掩码；可同时报告多个原因。

struct nx_watchdog_state_t
#include <watchdog.h>

硬件选定的超时边界，包含声明的 LSI 不确定性。

备注

最小值和最大值均为零表示超时边界未知，例如硬件影子寄存器更新尚未完成，或振荡器限制尚未复核。enabled 和 irreversible 事实仍然有效。debug_freeze 报告提供者支持的固件配置。能够由 CPU 读取调试控制的提供者会观察该设置。不具备 CPU 调试控制访问能力的提供者仅支持 false；该值既未观察，也不描述外部调试器的设置。

公共成员

uint32_t minimum_timeout_us
uint32_t maximum_timeout_us
bool enabled
bool irreversible
bool debug_freeze
struct nx_watchdog_ops_t
#include <watchdog.h>

使用同一个提供者状态的共享只读方法。

备注

各方法遵循对应公共操作的所有权合同。缺失的可选方法返回 UNSUPPORTED。

公共成员

nx_result_t (*enable)(void *context, uint32_t timeout_us, bool debug_freeze, nx_watchdog_state_t *state)
nx_result_t (*feed)(void *context)
nx_result_t (*state)(const void *context, nx_watchdog_state_t *state)
struct nx_watchdog_port
#include <watchdog.h>

指向调用者自有状态的不可变接口。

备注

接口和状态的生命周期覆盖调用方、IRQ 及保留的借用。工厂查找既不初始化，也不取得硬件。

公共成员

const nx_watchdog_ops_t *ops
void *context