扩展与生命周期 API¶

这些公共头文件描述成帧数据、显式所有者、保留时钟和可信代理。其声明并不证明板级连接、执行模式、内核网关或物理资格验证。构造、内存所有权及最后访问要求仍属于各自合同。

显式 F407 熵源构造¶

对于 F407 装配，显式调用 nexus_add_stm32f407_entropy(target)，并在产品装配处链接该目标。它拥有唯一静态 RNG 源并拒绝第二个构造器。getter nx_stm32f407_entropy_instance() 返回已有只读接口；不执行启动、寄存器访问或 factory 注册。

Platform 成功启动后，使用准确验证过的 Board/profile hse_hz 和 hclk_hz 事实调用 nx_stm32f407_entropy_instance_start()。实现检查实时 PLL48/HCLK 关系，仅取得其 RNG 时钟门；不配置共享 PLL，也不启动 Platform。经过审查的时钟源选择为 8 MHz HSE 或 16 MHz HSI。产品必须将这些时钟依赖保持到 stop 完成。

在单一特权、未屏蔽中断的串行任务上下文执行 start/stop。在 nx_stm32f407_entropy_instance_stop() 前等待全部熵使用方退出，并要求 stop 成功后才撤回 Platform 时钟。撤回失败时保留同一所有者与清理责任；重试 stop，不重置或重新绑定状态。停止后的接口仍有效，数据调用返回 STATE。此显式构造器与 TOML typed-factory 选择分离；它及软件 RNG 健康检查均不能证明物理最小熵或 HIL。

stm32f407_entropy.h¶

唯一 F407 RNG 源的显式可选构造。

作者 Nexus Team

函数

const nx_entropy_port_t *nx_stm32f407_entropy_instance(void)¶

返回已有静态源接口，不启动源。

备注

不分配、不访问寄存器、不取得时钟、不加锁或注册。接口私有状态属于唯一显式构造器目标。数据调用直接使用共享 provider 表；冷态接口返回 STATE。

返回:: 稳定只读接口，源停止时仍有效

nx_result_t nx_stm32f407_entropy_instance_start(const nx_stm32f407_entropy_config_t *config)¶

Platform 成功启动后显式启动源。

备注

特权、未屏蔽中断的串行任务。唯一硬件 RNG 所有者；有效状态下重复 start 返回 BUSY。不隐式调度、启动 Platform 或变更时钟配置。写入后的 IO 错误可能保留已拥有的效果；释放 Platform 时钟资源或恢复状态之前必须 stop 成功。

参数:

config – [in] 准确验证过的 Board/profile 事实，本次调用中复制；源/PLL48 依赖保持有效到 stop

返回:

SUCCESS、CONTEXT、INVALID、BUSY、STATE、UNSUPPORTED 或 IO

nx_result_t nx_stm32f407_entropy_instance_stop(void)¶

撤回 Platform 时钟资源前停止源。

备注

源使用方全部退出后，在特权、未屏蔽中断的串行任务执行。撤回失败时重试同一 stop；不得重置或重新绑定私有状态。现有静态接口保持有效，准入关闭时返回 STATE。

返回:: 停止完成时 SUCCESS；IO 保留失败清理的所有权

struct nx_stm32f407_entropy_config_t¶

#include <stm32f407_entropy.h>

针对实时 RCC 准入的准确 Board/profile 事实。

备注

首个范围使用经过审查的 8 MHz HSE Board 或固定 16 MHz HSI。这些值来自经过验证的装配事实，不猜测硬件。start 检查准确的 PLL48 与 HCLK；调用方将源/PLLQ/HCLK 依赖保持至 stop。

公共成员

uint32_t hse_hz¶

uint32_t hclk_hz¶

frame_stream.h¶

完整的成帧块与带步长的 DMA 消费者借用。

作者 Nexus Team

宏定义

NX_FRAME_MAX_PLANES¶

类型定义

typedef struct nx_frame_dma_loan nx_frame_dma_loan_t¶: 不可变消费者块，保留至 DMA 最后访问结束。

备注

首次获取前清零初始化。释放前必须让这个精确控制对象保持存活并由唯一所有者持有；复制的令牌从不授权提前复用或操作另一个实例。

枚举

enum nx_frame_sample_t¶

内存表示；这些取值从不配置总线上的传输。

取值：

enumerator NX_FRAME_PCM_SIGNED¶

enumerator NX_FRAME_PCM_UNSIGNED¶

enumerator NX_FRAME_PDM_BITS¶

enum nx_frame_audio_kind_t¶

串行成帧规则，其完整单位决定块的几何布局。

取值：

enumerator NX_FRAME_AUDIO_I2S¶

enumerator NX_FRAME_AUDIO_SAI¶

enumerator NX_FRAME_AUDIO_PDM¶

enum nx_frame_alignment_t¶

每个存储时隙容器中有效采样位的位置。

取值：

enumerator NX_FRAME_SAMPLE_LSB¶

enumerator NX_FRAME_SAMPLE_MSB¶

函数

nx_result_t nx_frame_layout_audio(const nx_frame_audio_format_t *format, nx_frame_layout_t *layout)¶

计算完整音频存储布局，不访问载荷。

备注

可在任务或 IRQ 中执行的有界纯计算。不执行格式转换、串行器配置或编解码器协商。

参数:

format – [in] 显式成帧规则、采样参数和存储时隙的几何布局。
layout – [out] 独立的新输出；拒绝时保持不变。

返回:

成功返回 SUCCESS；成帧规则不兼容时返回 INVALID，算术溢出时返回 EXHAUSTED；从不保留输入或分配内存。

nx_result_t nx_frame_layout_planar(const nx_frame_plane_t *planes, size_t count, nx_frame_layout_t *layout)¶

检查并复制平面式或带步长的帧几何布局。

备注

有界纯计算。像素和颜色的含义仍由所选相机、显示或 DMA 适配器负责。

参数:

planes – [in] 1..NX_FRAME_MAX_PLANES 个不可变平面描述。
count – [in] 精确平面数，并非运行时池的容量上限。
layout – [out] 新输出；任何拒绝都保持其不变。

返回:

成功返回 SUCCESS；平面为空、相互重叠或步长不足时返回 INVALID；字节数算术溢出时返回 EXHAUSTED。

nx_result_t nx_frame_stream_initialize(nx_frame_stream_t *framed, nx_stream_t *stream, const nx_frame_layout_t *layout)¶

在冷构造阶段将完整帧布局绑定到既有队列。

备注

仅供任务执行的冷构造，存储检查的复杂度为 O(n²)。不据此推断硬件或 DMA 域准入。全部队列、控制对象和载荷存储须保持存活，直至最终停止完成。

参数:

framed – [out] 新控制对象，与队列及载荷均不重叠。
stream – [inout] 已初始化且未被借用的队列，全部时隙空闲。
layout – [in] 已检查的完整帧几何布局，成功时复制。

返回:

成功返回 SUCCESS；存在别名、缓冲区不足或布局无效时返回 INVALID；仍有未归还块时返回 BUSY；停止过程中返回 STATE。

nx_result_t nx_frame_stream_publish(nx_frame_stream_t *framed, const nx_stream_fill_t *fill, uint32_t flags)¶

生产者最后访问结束后，发布一个完整帧。

备注

可在任务或 IRQ 中执行的有界元数据操作。预留、预提交和中止仍使用既有流；发布大小始终等于精确帧大小。

参数:

framed – [inout] 独占且串行使用的生产者绑定。
fill – [in] 既有流的生产者借用，已从全部 DMA 脱离。
flags – [in] 已观察到的既有流边界标志。

返回:

返回既有流的结果；拒绝时保留填充借用。

nx_result_t nx_frame_stream_post_publish(nx_frame_stream_t *framed, nx_stream_producer_t *producer, const nx_stream_fill_t *fill, uint32_t flags)¶

从既有预提交 FIFO 发布一个完整帧。

备注

可在任务或 IRQ 中执行的有界元数据操作；保留待处理数和 FIFO 计数。

参数:

framed – [inout] 同一生产者绑定及完整帧布局。
producer – [inout] 已绑定到此流的既有预提交生产者。
fill – [in] 最早的待处理借用，已不在任何硬件目标中。
flags – [in] 已观察到的既有流边界标志。

返回:

返回既有预提交发布操作的结果；来自其他池时返回 INVALID。

nx_result_t nx_frame_stream_acquire(nx_frame_stream_t *framed, nx_frame_dma_loan_t *loan)¶

获取下一个完整、不可变的 DMA 消费者借用。

备注

可在任务或 IRQ 中调用。在带保护的 O(1) 队列操作前，以 O(n) 扫描固定池来检查输出不重叠。输出不得与队列控制对象或池内任何载荷的完整容量范围重叠。EMPTY 不创建借用，也从不重复上一帧。静音、消隐或停止策略由调用方负责。不得将重试计为额外观察到的边界。

参数:

framed – [inout] 同一串行消费者；使用欠载计数时，每个观察到的输出边界只调用一次。
loan – [inout] 已清零或先前已释放的控制对象；出错时保持不变。

返回:

成功返回 SUCCESS；EMPTY 时增加饱和欠载计数；仍有活动借用时返回 BUSY；输出存在别名时返回 INVALID；已入队块不完整时返回 STATE。

nx_result_t nx_frame_dma_view(const nx_frame_dma_loan_t *loan, size_t plane, size_t x, size_t y, size_t width, size_t height, nx_frame_dma_view_t *view)¶

从活动帧借用导出带步长的字节矩形。

备注

可在任务或 IRQ 中调用。在带保护的 O(1) 视图计算前，以 O(n) 检查输出与不可变池不重叠。输出不得与借用控制对象、队列控制对象或池内任何载荷的完整容量范围重叠。像素对齐、资源及 DMA 域由适配器检查。

参数:

loan – [in] 精确、活动且不可变的 DMA 消费者借用。
plane – [in] 已绑定布局中的平面索引。
x – [in] 行内字节列偏移，并非像素数。
y – [in] 起始完整行。
width – [in] 每个选中行的正数字节数。
height – [in] 选中的正数行数。
view – [out] 新输出；失败时保持不变。

返回:

成功返回 SUCCESS；矩形超出平面时返回 INVALID；借用身份陈旧或来自其他实例时返回 STATE；此处不启动 DMA 访问。

nx_result_t nx_frame_dma_release(nx_frame_stream_t *framed, nx_frame_dma_loan_t *loan, const nx_dma_drain_facts_t *drain)¶

只有适配器证明 DMA 最后访问结束后才能释放。

备注

可在任务或 IRQ 中执行的有界元数据操作。超时或取消不代表静止；排空失败会保留队列借用，停止过程中也不例外。此辅助函数检查证明事实，不停止硬件。

参数:

framed – [inout] 原始所有者；另一个实例不能释放。
loan – [inout] 精确获取的控制对象，仅在成功时清除。
drain – [in] 提供方对引擎、IRQ 和外设静止状态的实际观测；单凭计数器完成不构成证明。

返回:

成功返回 SUCCESS；任何访问源尚未退出时返回 BUSY；令牌身份陈旧或来自其他实例时返回 STATE；排空计数不可能成立时返回 INVALID。

struct nx_frame_audio_format_t¶

#include <frame_stream.h>

不可变音频内存格式，独立于编解码器策略。

备注

PCM 帧按时隙升序存储每个时隙，包括非活动时隙；slot_bits 是容器位宽。I2S 有两个 16/32 位时隙；SAI 有 1..32 个 8/16/32 位时隙。PDM 有 1..8 条按字节交错的通道；每个字节保存同一通道连续的八个位，因此帧数必须能被八整除。active_slots 选择有效通道或时隙，不压缩存储布局。采样字节序须显式声明。

公共成员

nx_frame_audio_kind_t kind¶

nx_frame_sample_t sample¶

nx_frame_alignment_t alignment¶

size_t frames¶

uint32_t active_slots¶

uint8_t slots¶

uint8_t sample_bits¶

uint8_t slot_bits¶

bool big_endian¶

struct nx_frame_plane_t¶

#include <frame_stream.h>

一个平面；最后一行无需尾随的步长填充。

备注

row_bytes 和 stride 的单位为字节，rows 为完整行数。一个平面占用 (rows - 1) * stride + row_bytes 字节。

公共成员

size_t offset¶

size_t row_bytes¶

size_t stride¶

size_t rows¶

struct nx_frame_layout_t¶

#include <frame_stream.h>

复制到已绑定流中的不可变帧几何布局。

备注

各平面的区间（包括行间填充）不得重叠。bytes 是最远平面末端的精确位置，并非各行字节数之和。音频格式是独立、不可变的调用方元数据；此布局表示经检查的完整单位存储。

公共成员

nx_frame_plane_t planes[NX_FRAME_MAX_PLANES]¶

size_t plane_count¶

size_t bytes¶

struct nx_frame_stream_t¶

#include <frame_stream.h>

调用方拥有的绑定；全部队列均由既有流拥有。

备注

发布前初始化。一个串行生产者和一个串行消费者始终使用成帧发布与获取接口，直至停止。硬件、队列容量及同步方式仍须显式提供。

公共成员

nx_stream_t *stream¶

nx_frame_layout_t layout¶

uint32_t underruns¶

struct nx_frame_dma_loan¶

#include <frame_stream.h>

不可变消费者块，保留至 DMA 最后访问结束。

备注

首次获取前清零初始化。释放前必须让这个精确控制对象保持存活并由唯一所有者持有；复制的令牌从不授权提前复用或操作另一个实例。

公共成员

nx_frame_stream_t *owner¶

nx_stream_block_t block¶

const struct nx_frame_dma_loan *identity¶

struct nx_frame_dma_view_t¶

#include <frame_stream.h>

供显式 DMA 适配器使用的已检查二维字节矩形。

公共成员

const uint8_t *data¶

size_t row_bytes¶

size_t stride¶

size_t rows¶

size_t span_bytes¶

spi_dma_owner.h¶

面向有界 BusOwner 的可选类型化完整片选区间 SPI 执行器。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_spi_dma_owner_executor_port(nx_spi_dma_owner_executor_t *executor, const nx_spi_dma_owner_binding_t *binding)¶

绑定新执行器，不开启硬件或准入。

备注

仅供任务调用；替换前须让全部生命周期使用者完成会合退出。沿用原始 FIFO、时隙和 epoch；提供方最终终止结果不受晚到取消影响。停止和隔离期间继续由唯一执行器推进。硬件停止、发布者会合退出和观察者会合退出仍是显式外部步骤。

参数:

executor – [inout] 已清零的新存储，与能力对象及接口对象均不重叠。
binding – [in] 已初始化且仅由此所有者推进的总线。

返回:

供 nx_bus_owner_init 使用的执行器；输入无效时返回全零端口。

nx_result_t nx_spi_dma_owner_submit(nx_bus_owner_t *owner, nx_request_t *request, nx_spi_dma_owner_operation_t *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)¶

检查类型化存储，再使用有界所有者准入。

备注

请求使用包含排队时间的绝对期限。任务级多生产者检查在元数据保护区外执行。不扫描容量，不分配内存，也不创建 OS 锁或工作线程。一次操作对应一个 CS 区间，允许其中出现 SCK 间隙。即使提示通知失败，也须调度有界推进。等待者从不推进共享控制器。已排队请求的提供方失败随后结算，不把已接受准入改判为拒绝。

参数:

owner – [inout] 装配此精确类型化执行器的所有者。
request – [inout] 已准备好的 READY 外层请求。
operation – [in] 不可变链，保持至外层请求进入 SETTLED。
completion – [in] 可选的静态调用方提示端口，或 NULL。
ticket – [out] SUCCESS 时返回稳定的时隙/epoch 身份。

返回:

SUCCESS 表示 ACCEPTED；失败不保留任何内容。

struct nx_spi_dma_owner_operation_t¶

#include <spi_dma_owner.h>

调用方拥有的已排队或活动 SPI 链。

备注

外层期限包含排队停留时间。链、描述符以及全部 TX/RX 缓冲区或固定存储单元保持被借用，直至以 acquire 语义观察到外层 SETTLED。计数和结果以字为单位。

公共成员

const nx_spi_dma_transaction_endpoint_t *endpoint¶

const nx_spi_dma_segment_t *segments¶

size_t count¶

uint8_t word_bits¶

struct nx_spi_dma_owner_executor_t¶

#include <spi_dma_owner.h>

仅为所选实例提供的精确元数据；不添加队列、载荷复制或工作线程。

公共成员

const nx_spi_dma_owner_binding_t *binding¶

nx_spi_dma_transaction_request_t inner¶

bool pending¶

mapped_storage.h¶

有界只读映射与独占存储请求。

作者 Nexus Team

枚举

enum nx_mapped_storage_reader_t¶

只读消费者；能力声明不证明物理布线。

取值：

enumerator NX_MAPPED_STORAGE_CPU_READ¶

enumerator NX_MAPPED_STORAGE_XIP¶

enumerator NX_MAPPED_STORAGE_DMA_READ¶

enum nx_mapped_storage_operation_t¶

物理修改操作，与只读映射所有权分离。

取值：

enumerator NX_MAPPED_STORAGE_PROGRAM¶

enumerator NX_MAPPED_STORAGE_ERASE¶

函数

nx_result_t nx_mapped_storage_prepare(nx_mapped_storage_request_t *request, nx_mapped_storage_operation_t operation, size_t offset, const void *data, size_t length, nx_time_us_t deadline)¶

准备未被借用的调用方存储，不访问载荷。

返回:: 成功返回 SUCCESS，否则返回 INVALID/STATE；失败不保留引用。

const nx_mapped_storage_geometry_t *nx_mapped_storage_geometry(const nx_mapped_storage_port_t *port)¶: 查询不可变几何参数，不启动硬件。

nx_result_t nx_mapped_storage_acquire(const nx_mapped_storage_port_t *port, nx_mapped_storage_reader_t reader, size_t offset, size_t length, nx_mapped_storage_loan_t *loan)¶

在串行执行器上获取一个有界、长度为正的只读范围。

返回:: 返回 SUCCESS 或 INVALID/UNSUPPORTED/BUSY/EXHAUSTED/STATE。拒绝不保留借用。活动只读映射排斥全部命令、编程、擦除、缓存及 DMA 写入者。成功获取后，CPU/XIP/DMA 消费者可以并发运行。

nx_result_t nx_mapped_storage_release(const nx_mapped_storage_port_t *port, const nx_mapped_storage_loan_t *loan)¶

消费者全部会合退出后，释放一个精确的活动借用。

返回:: 返回 SUCCESS、INVALID/STATE，或保留借用的后端解除映射错误。仅供任务调用，使用同一串行执行器；不强制撤销借用，也不因超时释放。

nx_result_t nx_mapped_storage_submit(const nx_mapped_storage_port_t *port, nx_mapped_storage_request_t *request, nx_mapped_storage_ticket_t *ticket)¶

以绝对期限接纳一个独占 PROGRAM/ERASE 请求。

返回:: SUCCESS 表示 ACCEPTED，请求可能已经完成结算。拒绝不保留请求或载荷，也不产生硬件效果。不得仍有活动映射借用。仅供串行任务所有者使用；不创建工作线程、内存分配、锁或队列。

nx_result_t nx_mapped_storage_cancel(const nx_mapped_storage_port_t *port, nx_mapped_storage_ticket_t ticket)¶

通过实例及不重复的写入 epoch 身份请求取消。

返回:: SUCCESS 表示启动或观察排空；STATE 拒绝过期或属于其他实例的身份。取消从不释放存储。须继续推进，直至排空结束。

void nx_mapped_storage_service(const nx_mapped_storage_port_t *port)¶: 不等待地推进一次有界后端步骤或排空尝试。

备注

在以 release 语义发布 SETTLED 前，后端、IRQ 和数据引用全部脱离；该发布是对请求的最后访问。排空失败进入 QUARANTINED；存储继续被借用，后续推进可以重试撤回访问源。

nx_result_t nx_mapped_storage_stop(const nx_mapped_storage_port_t *port)¶

关闭准入并请求取消写入操作。

返回:: 只有全部映射借用与写入访问源均已退出才返回 SUCCESS；BUSY 保留存储，仍需释放借用或继续推进。成功停止后的重复调用不执行后端操作。此所有者不能重启或撤销借用。

struct nx_mapped_storage_geometry_t¶

#include <mapped_storage.h>

精确字节几何参数；各单位须整除总大小，且彼此满足整除关系。

公共成员

const uint8_t *mapped_base¶

size_t size¶

size_t program_unit¶

size_t erase_unit¶

uint32_t readers¶

struct nx_mapped_storage_request_t¶

#include <mapped_storage.h>

调用方拥有的请求及输入，保持被借用至 SETTLED。

备注

准备前先初始化 base。PROGRAM 借用 length 个输入字节；ERASE 要求输入为 NULL。几何对齐在准入时检查。取消、超时或 I/O 失败都不会撤销已产生的部分效果。不得重放。

公共成员

nx_request_t base¶

nx_mapped_storage_operation_t operation¶

size_t offset¶

const void *data¶

size_t length¶

struct nx_mapped_storage_loan_t¶

#include <mapped_storage.h>

一个只读映射的稳定实例绑定身份。

备注

释放前各字段均不可变，数据保持只读。释放前须让全部 CPU 读取者、XIP 指令取指及 DMA 读取者会合退出；复制的令牌不增加借用。释放失败会保留完整借用。

公共成员

const void *instance¶

const void *data¶

size_t length¶

size_t slot¶

uint64_t epoch¶

struct nx_mapped_storage_ticket_t¶

#include <mapped_storage.h>

稳定的写入身份；复用或销毁前须排空控制请求。

公共成员

const void *instance¶

uint64_t epoch¶

struct nx_mapped_storage_ops_t¶

#include <mapped_storage.h>

共享不可变操作表；每个回调都接收实例状态。

公共成员

const nx_mapped_storage_geometry_t *(*geometry)(const void *context)¶

nx_result_t (*acquire)(void *context, nx_mapped_storage_reader_t reader, size_t offset, size_t length, nx_mapped_storage_loan_t *loan)¶

nx_result_t (*release)(void *context, const nx_mapped_storage_loan_t *loan)¶

nx_result_t (*submit)(void *context, nx_mapped_storage_request_t *request, nx_mapped_storage_ticket_t *ticket)¶

nx_result_t (*cancel)(void *context, nx_mapped_storage_ticket_t ticket)¶

void (*service)(void *context)¶

nx_result_t (*stop)(void *context)¶

struct nx_mapped_storage_port_t¶

#include <mapped_storage.h>

不可变接口对象；上下文及全部保留存储必须比使用者存活更久。

公共成员

const nx_mapped_storage_ops_t *ops¶

void *context¶

mapped_storage_owner.h¶

显式、可移植的映射存储构造器及存储。

作者 Nexus Team

函数

nx_result_t nx_mapped_storage_owner_init(nx_mapped_storage_owner_t *owner, nx_mapped_storage_slot_t *slots, size_t capacity, nx_mapped_storage_backend_t backend, nx_clock_t clock)¶

绑定未使用的显式存储，不访问硬件或载荷。

返回:: 返回 SUCCESS 或 INVALID；容量为零、元数据与映射窗口重叠、跨度溢出、单位不一致或缺少回调时拒绝。调用方使用 owner_ops 和此所有者上下文构造 const 接口对象。

变量

const nx_mapped_storage_ops_t nx_mapped_storage_owner_ops¶: 全部可移植所有者实例共享的一张只读方法表。

struct nx_mapped_storage_backend_t¶

#include <mapped_storage_owner.h>

私有提供方边界；回调不可变，上下文独立。

备注

上下文是一个显式给定大小的私有状态范围。几何参数和映射地址保持固定。map 返回 SUCCESS 后建立可读映射窗口；map 失败不留下效果。unmap 返回 SUCCESS 证明全部映射窗口及缓存引用已撤回；失败则保留最后一个映射借用。start 仅在请求准入且已排除映射后调用。start 错误可能已有副作用，因此始终继续排空。poll 推进有界工作，返回 BUSY 或终止结果，并提供单调递增的已完成字节数。cancel 启动撤回，但不证明已排空。drain 返回 SUCCESS 时，全部硬件、IRQ、缓存、DMA、描述符和数据访问源均已脱离；BUSY 保留所有权，其他错误使其进入隔离。任何回调都不保留请求本身。此所有者存活期间，禁止这些回调之外的命令、缓存或 DMA 写入者。物理适配器负责缓存行域、XIP 执行排斥及硬件专属的排空证明。

公共成员

void *context¶

size_t context_size¶

nx_mapped_storage_geometry_t geometry¶

nx_result_t (*map)(void *context)¶

nx_result_t (*unmap)(void *context)¶

nx_result_t (*start)(void *context, nx_mapped_storage_operation_t operation, size_t offset, const void *data, size_t length)¶

nx_result_t (*poll)(void *context, size_t *completed)¶

nx_result_t (*cancel)(void *context)¶

nx_result_t (*drain)(void *context)¶

struct nx_mapped_storage_slot_t¶

#include <mapped_storage_owner.h>

精确的调用方映射容量；各字段归所有者管理。

公共成员

uint64_t epoch¶

size_t next¶

const void *data¶

size_t length¶

bool live¶

struct nx_mapped_storage_owner_t¶

#include <mapped_storage_owner.h>

调用方拥有的状态，仅在初始化成功后发布。

备注

全部方法和控制操作使用同一个串行任务执行器。消费者可以在其他执行上下文使用映射，但释放前须会合退出。不隐式提供 IRQ 保护或跨任务同步。状态、时隙、后端上下文、时钟和接口对象均须保持存活，直至停止及控制使用者与消费者会合退出。

公共成员

nx_mapped_storage_backend_t backend¶

nx_clock_t clock¶

nx_mapped_storage_slot_t *slots¶

size_t capacity¶

size_t free_head¶

size_t loans¶

nx_mapped_storage_request_t *active¶

uint64_t writer_epoch¶

size_t completed¶

nx_result_t terminal¶

bool draining¶

bool accepting¶

native_mapped_storage.h¶

调用方拥有的一致性 Native NOR 模型，每步工作量有界。

作者 Nexus Team

函数

nx_result_t nx_native_mapped_storage_init(nx_native_mapped_storage_t *model, uint8_t *bytes, size_t size, size_t program_unit, size_t erase_unit, size_t quantum, nx_mapped_storage_backend_t *backend)¶

构造未使用的 Native 后端，不修改底层存储字节。

返回:: 返回 SUCCESS 或 INVALID。仅支持 CPU_READ；XIP 和 DMA 标记均拒绝。Native 一致性内存无需缓存维护。可移植所有者仍保证映射与每一次建模修改及排空互斥。

struct nx_native_mapped_storage_t¶

#include <native_mapped_storage.h>

独立的 Native 后端状态，从不替代物理 Flash。

备注

模型保留传入的字节，仅允许从 1 编程为 0，并擦除为 0xff。一次推进最多修改 quantum 个字节。不隐式创建文件、堆、线程、DMA 或可执行映射窗口，也不声称具有持久性。fault_after 限制已修改字节数；SIZE_MAX 禁用该故障。hold_drain 模拟尚存的保留访问源，drain_error 模拟无法证明访问源已撤回的失败。

公共成员

uint8_t *bytes¶

size_t size¶

size_t quantum¶

const uint8_t *input¶

size_t offset¶

size_t length¶

size_t completed¶

size_t fault_after¶

nx_mapped_storage_operation_t operation¶

bool active¶

bool cancelled¶

bool mapped¶

bool hold_drain¶

bool drain_error¶

amp_ipc.h¶

有界、以 epoch 防止旧身份复用的单向共享内存借用。

宏定义

NX_AMP_IPC_UNIT¶: 显式端口隔离单元；支持的缓存粒度须能整除 64。

类型定义

typedef struct nx_amp_ipc nx_amp_ipc_t¶

枚举

enum nx_amp_role_t¶

取值：

enumerator NX_AMP_SENDER¶

enumerator NX_AMP_RECEIVER¶

函数

nx_result_t nx_amp_ipc_send(nx_amp_ipc_t *ipc, uint32_t offset, uint32_t bytes, nx_amp_ticket_t *ticket)¶

发布一个覆盖完整缓存行的载荷范围，不进行复制。

备注

仅供串行所有者 Thread 调用；下方全部 API 均遵守相同规则。不等待，不分配内存，不创建调度器、ISR 或隐式工作线程。输出不得与任何活动实例或通道存储重叠。生产者须在调用前结束 DMA 及其他写入者的访问。

返回:: SUCCESS 转移只读借用，直至轮询到精确 ACK 或 reset_join 成功。拒绝不保留内容，也不发布。EXHAUSTED 表示没有可复用的时隙身份。

nx_result_t nx_amp_ipc_poll(nx_amp_ticket_t ticket)¶: 以 acquire 语义观察精确 ACK；BUSY/IO/STATE 均保留发送方借用。

nx_result_t nx_amp_ipc_receive(nx_amp_ipc_t *ipc, nx_amp_view_t *view)¶: 描述符及载荷失效操作成功后，获取一个发布项。

nx_result_t nx_amp_ipc_finish(nx_amp_ticket_t ticket)¶: 让调用方视图的全部使用者会合退出，再发布该视图的精确 ACK。

备注

使用有效票据调用即不可撤销地确认本地读取者已会合退出。IO 或 STATE 保留端点和时隙存储；可重试 finish，或关闭后使用 reset_join。陈旧票据不改变任何状态。

nx_result_t nx_amp_ipc_close(nx_amp_ipc_t *ipc, nx_amp_close_t *control)¶: 关闭准入；未完成的发送和接收借用仍被保留。

nx_result_t nx_amp_ipc_join(nx_amp_close_t control)¶: 全部精确 ACK 及本地归还完成后，让已关闭端点会合退出。

备注

BUSY、IO 或 STATE 保留唯一所有者。成功执行最后访问并释放该角色声明。不得重构存储：此处从不重置启动及序列身份。

nx_result_t nx_amp_ipc_reset_join(nx_amp_close_t control)¶: 在取得显式旧对端停止证明后会合退出。

备注

要求端点已关闭；接收者视图必须先由 finish 消费。证明失败保留发送方的全部借用及所有权。成功后此端点退役；任何替代端点均须使用外部启动所有者提供的、严格更新的非零启动 epoch，绝不回绕或复用。

struct nx_amp_word_t¶

#include <amp_ipc.h>

一个写入者的隔离发布字；仅通过端口访问。

公共成员

uint32_t value¶

uint32_t reserved[15]¶

struct nx_amp_record_t¶

#include <amp_ipc.h>

共享描述符；偏移量相对于已配置的载荷窗口。

公共成员

uint32_t sender_epoch¶

uint32_t receiver_epoch¶

uint32_t sequence¶

uint32_t offset¶

uint32_t length¶

uint32_t reserved[11]¶

struct nx_amp_wire_slot_t¶

#include <amp_ipc.h>

调用方拥有的共享时隙，各写入者的缓存行互不重叠。

备注

仅发送方写 offer/published；仅接收方写 receipt/acknowledged。两个 CPU 均须能访问这四个单元。任一端点启动前须完成冷初始化。

公共成员

nx_amp_record_t offer¶

nx_amp_word_t published¶

nx_amp_record_t receipt¶

nx_amp_word_t acknowledged¶

struct nx_amp_port_ops_t¶

#include <amp_ipc.h>

集成方提供的硬件与所有权边界。

备注

每个回调均同步、有界且不可重入。claim 授予此精确通道的唯一角色所有者，并以原子方式拒绝复用或未递增的本地启动 epoch，即使普通 join 已完成也不例外。其权威硬件启动所有者跨 CPU 复位保留此历史；耗尽时关闭接纳。拒绝不产生效果。unclaim 仅发生于最终会合退出后，且从不清除启动身份历史。clean/invalidate 覆盖精确、完整且隔离的缓存行，完成其架构屏障，并可能失败。clean 失败绝不能发布控制字。acquire/release 是不会失败的原子 32 位一致性控制操作：端口负责全部控制缓存维护。它们须跨两个 CPU 和总线互连，对描述符及载荷访问建立顺序。stopped 证明指定的旧对端 CPU、DMA、IRQ 及全部观察者从此再也不能访问通道或载荷。上下文绑定 stopped 所覆盖的精确物理通道和对端执行 epoch。epoch 观测、取消、期限或已流逝的超时都不能提供此证明。现有单核 SoC 均不提供该证明。

公共成员

nx_result_t (*claim)(void *context, const void *owner, const nx_amp_wire_slot_t *lane, nx_amp_role_t role, uint32_t local_epoch)¶

void (*unclaim)(void *context, const void *owner)¶

nx_result_t (*clean)(void *context, const void *address, size_t bytes)¶

nx_result_t (*invalidate)(void *context, const void *address, size_t bytes)¶

uint32_t (*acquire)(void *context, const uint32_t *word)¶

void (*release)(void *context, uint32_t *word, uint32_t value)¶

nx_result_t (*stopped)(void *context, uint32_t old_peer_epoch)¶

struct nx_amp_ticket_t¶

#include <amp_ipc.h>

实例、启动及时隙身份；端点须比每一份票据副本存活更久。

公共成员

nx_amp_ipc_t *owner¶

uint32_t local_epoch¶

uint32_t peer_epoch¶

uint32_t slot¶

uint32_t sequence¶

struct nx_amp_view_t¶

#include <amp_ipc.h>

接收者借用的只读共享范围。

备注

调用方须在 finish 前让每个本地读取者会合退出。有效 finish 调用会消费调用方视图，即使链路确认失败也不例外；端点存储仍被保留。

公共成员

nx_amp_ticket_t ticket¶

const void *data¶

size_t bytes¶

struct nx_amp_close_t¶

#include <amp_ipc.h>

稳定的关闭身份；端点须比全部控制对象副本存活更久。

公共成员

nx_amp_ipc_t *owner¶

uint32_t local_epoch¶

uint32_t peer_epoch¶

amp_ipc_storage.h¶

调用方拥有的端点配置及保留借用状态。

函数

nx_result_t nx_amp_ipc_construct(nx_amp_ipc_t *ipc, const nx_amp_config_t *config)¶: 声明并绑定未使用、已清零初始化的端点存储。

备注

由串行特权所有者 Thread 在发布前调用。claim 前校验范围互不重叠及精确启动 epoch。构造拒绝不保留引用，也不产生共享效果。端口须独立强制唯一硬件及角色所有权；此组件不含全局注册表。

struct nx_amp_local_slot_t¶

#include <amp_ipc_storage.h>

已清零初始化的本地状态；不与其他端点共享。

公共成员

uint32_t sequence¶

uint32_t offset¶

uint32_t length¶

bool active¶

bool returned¶

struct nx_amp_config_t¶

#include <amp_ipc_storage.h>

一条单向通道及精确的调用方存储。

备注

两个启动字均为外部发布、单调且非零的 epoch。绝不重新发布旧启动身份，整机复位后也不例外。启动所有者须在耗尽时关闭接纳。初始共享记录及控制字须已清零，或保留自更早 epoch；活动期间不得编辑。协议控制字和启动字分别占用独立、完整的 64 字节单元。全部共享范围按 granule 对齐，granule 为 1..64 之间的二次幂。载荷大小是 granule 的正整数倍。配置、回调及全部传入存储均须保持存活，直至最终会合退出。

公共成员

const nx_amp_port_ops_t *ops¶

void *context¶

nx_amp_wire_slot_t *wire¶

nx_amp_local_slot_t *slots¶

uint32_t capacity¶

void *payload¶

uint32_t payload_bytes¶

nx_amp_word_t *local_boot¶

nx_amp_word_t *peer_boot¶

uint32_t local_epoch¶

uint32_t peer_epoch¶

uint32_t granule¶

nx_amp_role_t role¶

struct nx_amp_ipc¶

#include <amp_ipc_storage.h>

公共成员

nx_amp_config_t config¶

bool initialized¶

bool closed¶

bool faulted¶

bool joined¶

stm32f407_handoff.h¶

显式所有者排空后的精确 F407 Flash 映像移交。

作者 Nexus Team

函数

nx_result_t nx_stm32f407_handoff_initialize(size_t consumer_capacity)¶

构造唯一的静态 F407 移交准入域。

备注

由串行特权 Thread 在任何消费者启动前调用一次。不使用堆，不写硬件，不执行发现或隐式启动。调用方须登记每个可能在入口之后仍存活的平台或产品执行者、IRQ、DMA、观察者及内存所有者。租约仅在其实际会合退出或排空后释放。

参数:

consumer_capacity – [in] 已登记活动令牌数的正数上限。

返回:

返回 SUCCESS、INVALID、CONTEXT 或 STATE；从不重置 epoch。

nx_clock_domain_t *nx_stm32f407_handoff_domain(void)¶

返回既有的唯一静态准入域。

备注

纯查询；不初始化、不获取租约，也不访问硬件。

返回:: 稳定对象身份，初始化前亦有效。

nx_result_t nx_stm32f407_handoff(nx_clock_barrier_t owners, uint32_t vector_address)¶

校验已停止的 F407 状态，并以尾跳转移交至 Flash。

备注

仅支持所选 STM32F407VET6/ZGT6 裸机映像。调用方须为使用 MSP 的特权 Thread，PRIMASK=1，其他屏蔽寄存器为零。不得已启动调度器。停止实际 Platform，让全部使用者会合退出，并保持准入关闭。无关的空域不能授权移交。活动浮点状态或延迟保存、CP10/11 权限不完整、MPU、ART、SysTick、已启用或挂起或活动的 IRQ、非 HSI16 时钟或非复位总线配置、外设或 DMA 门控、忙碌 Flash 及残留 System 效果均导致拒绝。支持 SystemInit 设置的普通未激活 CP10/11 权限。保留主 SRAM；MSP 须按 8 字节对齐，且位于 (0x20000000,0x20020000]。全部 98 个向量须满足实际观察及生成配置确定的精确 Flash 几何范围。复位 PC 须为 Thumb，且首个半字位于 Flash。成功时设置 VTOR、禁用 CP10/11、设置 CONTROL=0、PSP=0 和 MSP，然后在 PRIMASK=1 下跳转到 PC。这是保持中断屏蔽的移交入口。不复制或清除 RAM，不认证或选择映像，不排空器件，不改变时钟，也不进行物理资格验证。目标映像负责 RAM 启动，并在启用门控前复位控制器。任何旧期限在移交后均不再有效。外部须排除 NMI/HardFault、调试器、DMA 及其他总线主设备。登记属于调用方策略；Platform 和产品所有者从不自动登记。拒绝时保留中断屏蔽状态，且不执行可写 MMIO 操作。即使拒绝，读取 SysTick CTRL 也会消耗 COUNTFLAG。

参数:

owners – [in] 来自此精确域、已关闭且已排空的屏障。
vector_address – [in] 按 512 字节对齐的物理 Flash 向量地址。

返回:

移交前可能返回错误；成功时永不返回。

frame_dma2d.h¶

显式可选的 H743 RGB565 复制与固定 PFC owner。

作者 Nexus Team

宏定义

NX_H743_FRAME_DMA2D_STORAGE_BYTES¶: 为一个可选所有者保留的精确不透明存储。

备注

仅零初始化一次；不得复制或修改。这是一个对象的 ABI 存储，不是存储池或分配器。存储、接口及全部已接受请求都须存活至成功停止。

类型定义

typedef enum nx_frame_blit_format nx_frame_blit_format_t¶: 精确的源到 RGB565 操作；未知值不受支持。

枚举

enum nx_frame_blit_format¶

精确的源到 RGB565 操作；未知值不受支持。

取值：

enumerator NX_FRAME_BLIT_RGB565¶: 源和输出均为 RGB565；零值保留复制操作。

enumerator NX_FRAME_BLIT_ARGB8888_TO_RGB565¶: ARGB8888 到 RGB565；在此小端 MCU 上输入字节顺序为 B、G、R、A。

备注

丢弃 alpha；不进行混合、通道／字节交换或 CLUT 加载。

enum nx_h743_frame_resource_t¶

显式独占的物理资源；没有运行时资源注册表。

取值：

enumerator NX_H743_FRAME_DMA2D_CONTROLLER¶

函数

nx_result_t nx_h743_frame_dma2d_initialize(nx_h743_frame_dma2d_storage_t *storage, const nx_frame_blitter_t *face, const nx_h743_frame_dma2d_config_t *config)¶

取得未启用的 DMA2D 及其专用 RCC 门控／复位位。

备注

在未屏蔽中断的特权任务中，由单个执行者串行调用。调用方明确排除所有其他 DMA2D owner，包括 HAL、IRQ 处理器及组件外的资源选择。stop 前不得改变 Cache／RCC／复位／MPU 或时钟域。所有载荷必须完整位于 AXI SRAM [0x24000000, 0x24080000)；拒绝源／目标重叠。仅支持 RGB565 M2M 或固定 ARGB8888 到 RGB565 PFC。偏移按每侧自身的像素计数（LOM=0），不按字节计数。不支持 CLUT／混合／其他格式／IRQ。不创建引脚、Board 路由、调度器、队列或工作线程。初始化 IO 错误保留清理所有权；应调用 stop。成功 stop 会脱离每个源，随后仅撤回自己的 RCC 时钟门。重复 stop 不访问硬件。

参数:

storage – [inout] 调用方独占的全新零初始化存储。
face – [in] 稳定只读的 {&nx_h743_frame_dma2d_ops, storage}。
config – [in] 精确资源及正数中止观察次数上限。

返回:

SUCCESS、INVALID；外部占有门控／复位／IRQ 时为 BUSY；非 V 修订或缓存启用时为 UNSUPPORTED；也可能为 CONTEXT 或 IO。

变量

const nx_frame_blitter_ops_t nx_h743_frame_dma2d_ops¶

struct nx_frame_blit_request_t¶

#include <frame_dma2d.h>

调用方拥有的单个请求；矩形坐标以字节为单位。

备注

使用普通请求辅助函数初始化／准备 base。ACCEPTED 借用本对象、精确源借用控制体与目标区间，直到 acquire 观察到 SETTLED。接纳时源借用所有权转移给此 owner；只有最终 DMA 访问结束后才释放。拒绝时原借用仍归调用方。不得单独释放、修改或复用已接纳的控制体、源或目标。x／width_bytes 是源字节数，不是输出字节数或像素数。RGB565 的源地址／x／宽度／步幅按 2 字节对齐，ARGB8888 则按 4 字节对齐。目标为 RGB565，按 2 字节对齐。目标行字节数为 width_bytes/source_pixel_bytes*2；destination_stride/capacity 以字节计。LOM=0 时每侧像素间隙最多为 0x3fff；宽度最多为 0x3fff 像素，高度最多为 0xffff 行。成功时通过 nx_request_result 报告输出字节数，不含步幅填充。目标不能与源池槽的完整容量重叠。每个控制体必须与每个槽的完整容量互不重叠。选中的源槽直到最终访问结束都保持不可变。仅限任务的接纳以 O(n) 检查已知池区间。

公共成员

nx_request_t base¶

nx_frame_dma_loan_t *source¶

size_t plane¶

size_t x¶

size_t y¶

size_t width_bytes¶

size_t rows¶

uint8_t *destination¶

size_t destination_stride¶

size_t destination_capacity¶

nx_frame_blit_format_t format¶

struct nx_frame_blitter_ops_t¶

#include <frame_dma2d.h>

仅由单个执行者在任务上下文调用；每次 service 调用都有界。

备注

Submit 返回 SUCCESS 表示 ACCEPTED，包括后续设置／读回错误。已接纳的失败保留全部借用，直到 service 证明最终排空。最先观察到的失败在取消／守卫恢复后仍被保留。

公共成员

nx_result_t (*submit)(void *context, nx_frame_blit_request_t *request, nx_time_us_t now)¶

nx_result_t (*service)(void *context, nx_time_us_t now)¶

nx_result_t (*cancel)(void *context, nx_frame_blit_request_t *request)¶

nx_result_t (*stop)(void *context)¶

struct nx_frame_blitter_t¶

#include <frame_dma2d.h>

不可变接口；状态位于调用方拥有的独立私有存储中。

公共成员

const nx_frame_blitter_ops_t *ops¶

void *context¶

struct nx_h743_frame_dma2d_config_t¶

#include <frame_dma2d.h>

适用于关闭 D-Cache 的精确 H743 V 修订的初始配置。

备注

abort_observations 限定进入隔离前 service 失败观察的次数。它是软件进展预算，不是实测的总线／DMA 时间界限。同一执行者在可恢复隔离后继续 service；实际排空可使请求结算。若观察到活动期间 RCC 时钟门丢失或复位被置位，则永久保留全部借用。恢复寄存器不能证明已丢失的传输历史；没有 API 能回收它。未被观察到的复位脉冲无法检测，因此仍必须独占 RCC 所有权。系统恢复由外部负责。

公共成员

nx_h743_frame_resource_t resource¶

uint32_t abort_observations¶

union nx_h743_frame_dma2d_storage_t¶

#include <frame_dma2d.h>

公共成员

uint64_t alignment¶

uintptr_t pointer_alignment¶

unsigned char private_bytes[NX_H743_FRAME_DMA2D_STORAGE_BYTES]¶

stm32u575_retained_time.h¶

从保留的 U575 日历建立独立单调时钟域。

作者 Nexus Team

宏定义

NX_U575_RETAINED_TIME_STORAGE_BYTES¶

枚举

enum nx_u575_retained_time_resource_t¶

独占的精确 RTC 源；其他所有者不得配置它。

取值：

enumerator NX_U575_RETAINED_TIME_RTC¶

函数

nx_result_t nx_stm32u575_retained_time_initialize(nx_stm32u575_retained_time_storage_t *storage, const nx_stm32u575_retained_time_config_t *config, nx_clock_t *clock)¶

打开独立的经过时间时钟，不读取或更改 Core TIM2。

备注

精确 U575 TZEN0，由特权、未屏蔽中断的 Thread 在裸机环境集成。外部启动代码负责有效的原始日历、LSE32768、RTCEN、RTCAPBEN，晶体模式 LSEBYP=0 及保守驱动档位 10/11。ES0499 Rev12 的 2.2.3/16 影响 X 修订；本配置不构成修订资格证明。外部启动／板级所有者须依据 2.2.1 排除 LQFP 参考封装上的 PC13 跳变；读取不能证明电气静默。

备注

每对元组读取前检查所选 MSIS4／等总线频率配置，且不得存在并发时钟配置写入者。此保守配置不是通用的 RTC 写入频率规则。要求 PRER127/255、BCD24h BYPSHAD，且无移位、校准或闹钟。

备注

独立及委托构造都要求 RTC IRQ 静默、WUTE/WUTIE 清零且没有 RTC 标志。成功构造后，显式 wake_owner 只能操作其 WUT／IRQ 字段。INITS 不能证明日历来源，包括有意设置的 YY00。无需解锁 DBP/WPR；不写入硬件。

备注

此接口的时钟域独立于 nx_time_now_us()。不转换旧 Core 截止时间。所有使用者与观察者完成汇合后，停止／重新打开会使旧接口中的数值截止时间失效。

参数:

storage – [inout] 全新零初始化，或已完全停止且外部已完成汇合的所有者。
config – [in] 独立不可变配置，在本次调用中复制。
clock – [out] 独立可写接口，仅成功时复制。

返回:

SUCCESS、INVALID、STATE、BUSY、CONTEXT、UNSUPPORTED 或 EXHAUSTED；拒绝时所有者与输出不变，且不写入硬件。

nx_result_t nx_stm32u575_retained_time_initialize_alarm_a_copy(nx_stm32u575_retained_time_storage_t *storage, const nx_stm32u575_retained_time_config_t *config, nx_clock_t *clock)¶

为同一个具体 Stop2 所有者打开固定 AlarmA-copy 委托。

备注

仍须满足普通初始化的全部前提。与仅使用 WUT 的初始化函数不同，此函数将固定 AlarmA 比较寄存器、ALRAE 和 ALRAF/CALRAF 显式委托给同一个串行化唤醒所有者。仍禁止 ALRAIE 和自动清除标志。固定配置屏蔽所有日历字段，且不比较亚秒，在秒递增时产生第一个事件。两个闹钟寄存器初始均为零。受委托者保持日历／时钟源不变，并负责在任何复合复制请求结束前完全撤回生产者。不准入 AlarmA factory、任意闹钟调度器或第二个 RTC 写入者。

参数:

storage – [inout] 同一份已清零的新存储，或已完全停止且完成会合退出的存储。
config – [in] 同一不可变配置，其中 wake_owner 非 NULL。
clock – [out] 独立可写接口对象，每次拒绝时均保持不变。

返回:

与普通初始化相同的结果；不发生硬件写入。

nx_result_t nx_stm32u575_retained_time_sample(nx_stm32u575_retained_time_storage_t *storage, nx_stm32u575_retained_time_snapshot_t *snapshot)¶

观察有界一致元组并扩展独立时钟域。

备注

Thread 可持有 PRIMASK；排除 BASEPRI/FAULTMASK 及 Handler 模式。BUSY 表示八次有界重试后仍无一致元组，且所有者与输出都不变。源／配置变化、日历回退或超出窗口、时间耗尽都会永久污染此活动纪元。后续采样返回 STATE；任何陈旧值都无效。

参数:

storage – [inout] 同一个串行化特权 Thread 所有者。
snapshot – [out] 独立、对齐、可写的输出；失败时不变。

返回:

SUCCESS、INVALID、STATE、BUSY、CONTEXT 或 EXHAUSTED。

nx_result_t nx_stm32u575_retained_time_validate_wake(nx_stm32u575_retained_time_storage_t *storage, const void *wake_owner, uint64_t generation)¶

依据此活动时钟代次检查一个显式 WUT 身份。

备注

同一个串行化特权 Thread，允许 PRIMASK 为 0 或 1。WUT 所有者通过 sample 取得代次，并在每次转换前后检查。重新打开使旧绑定失效；不会推断出第二个所有者。

返回:: SUCCESS、INVALID、STATE 或 CONTEXT；不产生输出或硬件效果。

nx_result_t nx_stm32u575_retained_time_validate_alarm_a_copy(nx_stm32u575_retained_time_storage_t *storage, const void *wake_owner, uint64_t generation)¶

校验精确的显式启用 AlarmA-copy 所有者及活动时钟代次。

备注

与 validate_wake 相同的 Thread／PRIMASK 边界。普通的仅使用 WUT 的时钟不能授权 AlarmA。身份／代次／模式错误会被拒绝，且不污染时钟；观察到时钟源或固定配置偏移则污染该纪元。

参数:

storage – [inout] 同一个活动的串行化时钟所有者。
wake_owner – [in] 显式启用初始化时指定的精确稳定身份。
generation – [in] 成功采样取得的非零代次。

返回:

SUCCESS、INVALID、STATE 或 CONTEXT；不发生硬件写入。

nx_time_us_t nx_stm32u575_retained_time_now(void *context)¶

时钟接口读取；失败时不能返回陈旧或无效时间戳。

备注

任何采样失败时，污染该纪元，保留中断屏蔽状态，调用 nx_fault_observe(NX_FAULT_PLATFORM, reason, …)，若观察者返回则停驻。产品可提供另行评审且不返回的恢复路径。故障观察不释放任何借用或观察者。

参数:

context – [inout] 成功初始化时的精确活动存储。

返回:

同一独立单调时钟域中的新有效采样。

nx_result_t nx_stm32u575_retained_time_stop(nx_stm32u575_retained_time_storage_t *storage)¶

所有外部接口／截止时间使用者完成汇合后关闭时钟接纳。

备注

不重置代次或更改时钟源。显式重新打开会启动新的从零开始的经过时间域，包括此前被污染的时钟域。此只读时钟源组件不建立调度器、唤醒 IRQ、WFI、Core 恢复、Stop2 或 VBAT 保留保证。

返回:: SUCCESS、INVALID、CONTEXT 或 STATE；干净状态下重复停止具有幂等性。

union nx_stm32u575_retained_time_storage_t¶

#include <stm32u575_retained_time.h>

单个零初始化的调用方所有者，不是存储池或分配服务。

备注

不得复制或修改。存储须在每个复制的时钟接口、截止时间使用者及观察者存续期间保持有效。未来电源模式中的内存保留由装配方保证，不能由 RAM 地址推断。此只读时钟不要求 SRAM4，也不进入 Stop2。

公共成员

uint64_t alignment¶

uintptr_t pointer_alignment¶

unsigned char private_bytes[NX_U575_RETAINED_TIME_STORAGE_BYTES]¶

struct nx_stm32u575_retained_time_config_t¶

#include <stm32u575_retained_time.h>

由串行生命周期所有者声明的有界观察间隔。

备注

每个 max_gap_seconds 至少观察一次，其取值为 1..86400 秒。日历快照不能检测错过完整的百年周期或外部微小时钟调整。须排除全部日历写入者和其他 RTC 配置所有者，包括轮询 AlarmA 工厂选择。下文仅描述唯一显式 WUT 委托。完整经过时间（包括唤醒延迟或恢复）必须落在此间隔内；标称 WUT 时长本身不构成上限。

公共成员

nx_u575_retained_time_resource_t resource¶

uint32_t max_gap_seconds¶

const void *wake_owner¶: 仅 RTC 时为 NULL；否则为一个 WUT 所有者的稳定身份。

备注

仅委托 WUCKSEL/WUTE/WUTIE、WUTR、WUTF/SCR.CWUTF 及 RTC IRQ 所有权；该有界操作可改变 ICSR.WUTWF。同一串行所有者须保留全部日历／时钟源字段。仅比较身份而不解引用；身份不构成授权。

struct nx_stm32u575_retained_time_snapshot_t¶

#include <stm32u575_retained_time.h>

在此所有者的启动生命周期内一并复制的成功采样。

备注

微秒数为 floor(ticks*1000000/256)；分辨率为 3906.25us，并精确携带四分之一微秒的余数。代次仅在显式成功初始化／重新打开时变化，不随自然的 99->00 回绕变化。

公共成员

const void *identity¶

uint64_t generation¶

nx_time_us_t now¶

uint64_t ticks¶

stm32u575_lpdma_copy.h¶

精确的 U575 SRAM4 有限自主复制接收器。

作者 Nexus Team

宏定义

NX_U575_LPDMA_COPY_STORAGE_BYTES¶

函数

nx_result_t nx_stm32u575_lpdma_copy_initialize(nx_stm32u575_lpdma_copy_storage_t *storage, const nx_stm32u575_lpdma_copy_config_t *config, nx_stm32u575_lpdma_copy_t *copy)¶

构造一个串行化特权 Thread 所有者，不进行 MMIO 写入。

备注

仅适用于精确的 STM32U575ZIT6Q TZEN0/MSIS4/MSIK4/等频总线/Range4 及已选择的 SRAM4。LPDMA1EN/SRAM4EN 和供电／保留由所选启动流程负责；所有通道和中断向量初始必须静止。运行门控所有者须在停止及会合退出完成前，保持两个门控和独占硬件配置稳定；其他 LPDMA 通道均不得启动。此组件仅拥有固定的睡眠／自主运行位，并保留无关 RTC 位。SRAM4EN 和供电／保留前提由启动流程及组合睡眠所有者负责。此组件从不通过修改 SRAM4PD/PDS 修复丢失的 RAM，也从不禁用调用方的 SRAM4EN。

参数:

storage – [inout] 已清零的新存储，或已干净停止且完成外部会合退出的存储。
config – [in] 独立且不可变的时钟／所有者绑定。
copy – [out] 独立可写的不可变接口对象，失败时不变。

nx_result_t nx_stm32u575_lpdma_copy_request_prepare(nx_stm32u575_lpdma_copy_request_t *request, const nx_stm32u575_retained_time_snapshot_t *domain, const void *source, void *destination, size_t length, nx_stm32u575_lpdma_copy_workspace_t *workspace, nx_time_us_t deadline)¶

在未被借用的请求中准备复制后的元数据，不进行 MMIO。

备注

拒绝范围、别名、回绕或状态时，请求的每个字节均保持不变。准备操作不借用或写入任何缓冲区／工作区。绝不将旧 Core TIM2 截止时间转换到此时钟域。

参数:

request – [inout] 已初始化为 READY 或已消费的 SETTLED 请求，且已完全会合退出。
domain – [in] 独立的成功保留时钟采样。
source – [in] 全部位于非安全 SRAM4 内、借用期间不可变的字节。
destination – [out] 独立的借用可写 SRAM4 范围。
length – [in] 至少两字节；两个完整范围均须容纳于 SRAM4。
workspace – [inout] 独立且对齐的 24 字节 SRAM4 LLI 工作区。
deadline – [in] 该时钟域中的绝对微秒数，或 NEVER。

nx_result_t nx_stm32u575_lpdma_copy_cancel(const nx_stm32u575_lpdma_copy_t *copy, nx_stm32u575_lpdma_copy_request_t *request)¶

锁存精确活动身份的取消请求，但不释放借用。

备注

观察到通道完成后，延迟取消会以 STATE 拒绝。在尚未观察到完成时取消，会确定首个失败。仅排空 DMA 不能释放 AlarmA/WUT/时钟恢复链的借用。

参数:

copy – [in] 已初始化物理接收器的不可变 face。
request – [inout] 精确活动请求，须保留到 SETTLED。

nx_result_t nx_stm32u575_lpdma_copy_service(const nx_stm32u575_lpdma_copy_t *copy, uint32_t poll_limit)¶

观察并执行有界 DMA 撤回；绝不发布 SETTLED。

备注

每阶段使用正数有限观察预算，不是时间估计。BUSY 会保留请求、两个缓冲区及工作区，即使 DMA 已空闲也不释放。只有具体 Stop2 owner 才能在整个 RTC/IRQ/DMA/时钟/门控链恢复后释放借用。配置未知时不执行 DMA MMIO。借用期间若观察到外部置位的 LPDMA 复位，不确定的借用将被永久隔离；复位默认的 IDLE 不能证明先前主设备的访问已汇合。不存在软件强制释放路径。保留传入的屏蔽状态；借用期间，具体 Stop2 边界要求保持 PRIMASK1、BASEPRI/FAULTMASK0，直到完全恢复。

参数:

copy – [in] 已初始化物理接收器的不可变 face。
poll_limit – [in] 每个排空阶段使用正数观察预算。

nx_result_t nx_stm32u575_lpdma_copy_stop(const nx_stm32u575_lpdma_copy_t *copy, uint32_t poll_limit)¶

关闭接纳，并保留全部活动借用，直到复合恢复完成。

备注

返回 BUSY 时，须保持所有相关对象存活并关闭 RUN 接纳。外部发布者均已汇合后，可安全重复干净停止。公共类型或软件执行成功不表示 Stop2 物理驻留、LPBAM 外设、物理复制或 HIL 结果。

参数:

copy – [in] 已初始化物理接收器的不可变 face。
poll_limit – [in] 每个排空阶段使用正数观察预算。

变量

const nx_stm32u575_lpdma_copy_ops_t nx_stm32u575_lpdma_copy_ops¶: 精确物理实现的身份，不接受任意回调。

union nx_stm32u575_lpdma_copy_storage_t¶

#include <stm32u575_lpdma_copy.h>

调用者提供的零初始化 owner；存活期间绝不能复制、复位或重建。

备注

保持此存储、每个复制的 face 及绑定时钟存活，直到 stop 成功且全部外部观察者已汇合。仅存在一个精确 ch0 owner；没有分配、队列、工作线程或 factory 查找。由一个特权 Thread 串行执行每项生命周期及控制操作。ISR、并发生产者或尚未汇合的延迟取消命令，均不得跨 prepare/复用使用请求指针。

公共成员

uint64_t alignment¶

uintptr_t pointer_alignment¶

unsigned char private_bytes[NX_U575_LPDMA_COPY_STORAGE_BYTES]¶

struct nx_stm32u575_lpdma_copy_workspace_t¶

#include <stm32u575_lpdma_copy.h>

由 provider 生成的一个完整后继 LLI；不使用调用者的原始指令。

备注

完整的 24 字节范围必须位于已选 SRAM4 中，并按四字节对齐。provider 仅在接纳后覆盖全部字。借用期间须保持其不可变，并与两个缓冲区及所有请求／控制存储互不重叠。NOINIT section 从不代表描述符已构造。

公共成员

uint32_t private_words[6]¶

struct nx_stm32u575_lpdma_copy_config_t¶

#include <stm32u575_lpdma_copy.h>

显式绑定同一 owner 的时钟；仅在初始化时复制。

备注

clock 是存活且显式选入 AlarmA-copy 的保留时钟。wake_owner 是具体 Stop2 owner 的稳定身份。身份相等表示可信装配绑定，不是硬件认证。此组件中不存在 RTC 写入者。

公共成员

nx_stm32u575_retained_time_storage_t *clock¶

const void *wake_owner¶

struct nx_stm32u575_lpdma_copy_request_t¶

#include <stm32u575_lpdma_copy.h>

在独立保留时间域中执行一次有限的双块复制。

备注

prepare 前须初始化 base。从 ACCEPTED 到以 acquire 观察 SETTLED 且外部使用者汇合期间，调用者不得修改准备好的元数据。source、destination 及整个 workspace 必须是精确非安全 SRAM4 中互不重叠的范围，不能使用 CPU 可见的 SRAM1 或安全别名。length 至少为两字节；字节宽度的递增传输保持精确字节数。

公共成员

nx_request_t base¶

const void *identity¶

const void *source¶

void *destination¶

size_t length¶

nx_stm32u575_lpdma_copy_workspace_t *workspace¶

const void *clock_identity¶

uint64_t clock_generation¶

struct nx_stm32u575_lpdma_copy_ops_t¶

#include <stm32u575_lpdma_copy.h>

共享只读方法；公共 service 从不释放此链。

公共成员

nx_result_t (*cancel)(void *context, nx_stm32u575_lpdma_copy_request_t *request)¶

nx_result_t (*service)(void *context, uint32_t poll_limit)¶

nx_result_t (*stop)(void *context, uint32_t poll_limit)¶

struct nx_stm32u575_lpdma_copy_t¶

#include <stm32u575_lpdma_copy.h>

不可变 typed face；复制的 face 仍指向同一个精确存活 owner。

公共成员

const nx_stm32u575_lpdma_copy_ops_t *ops¶

void *context¶

stm32u575_lpdma_lptim1.h¶

精确 U575 的有限 LPTIM1 自主寄存器更新。

宏定义

NX_U575_LPDMA_LPTIM1_STORAGE_BYTES¶

函数

nx_result_t nx_stm32u575_lpdma_lptim1_initialize(nx_stm32u575_lpdma_lptim1_storage_t *storage, const nx_stm32u575_lpdma_lptim1_config_t *config, nx_stm32u575_lpdma_lptim1_t *receiver)¶: 绑定一个无副作用的 owner；不写 MMIO、不分配，也无 worker。

备注

精确 STM32U575ZIT6Q TZEN0、MSIS4/MSIK4、各总线频率相同、Range4、caches off。选定 SRAM4/LPDMA1 startup 和保留 LSE RTC 访问须保持有效。LPDMA0 和整个 LPTIM1 控制器必须独占；不得存在其他 channel、timer writer、IRQ user 或外部 reset。Config/face/control storage 必须分开。拒绝不保留新引用。

nx_result_t nx_stm32u575_lpdma_lptim1_start(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)¶: 显式准备冷态 LPTIM1 访问门控与 LSE kernel。

备注

未屏蔽的 privileged Thread，每阶段轮询预算为正数。仅拥有 LPTIM1EN、LPTIM1SEL 和新增的 LSESYSEN，保持 RTC/LSE 来源不变。LPTIM1 必须处于 reset/cold 状态，初始无时钟且 mux 为 reset 值。准备失败可能保留效果；须保持 owner 有效，并调用 stop 直至成功。它从不启动 timer，也不借用 request。

nx_result_t nx_stm32u575_lpdma_lptim1_request_prepare(nx_stm32u575_lpdma_lptim1_request_t *request, const nx_stm32u575_retained_time_snapshot_t *domain, const nx_stm32u575_lptim1_tuple_t *tuple, nx_stm32u575_lpdma_lptim1_workspace_t *workspace, nx_time_us_t deadline)¶: 准备一组 SRAM4 tuple，不借用或写入 data/LLI。

备注

Tuple 内容须从 prepare 到 settlement 保持不变。无效、重叠或回绕的区段不改变 request 的任何字节。Deadline 是保留时间域的绝对微秒值或 NEVER；不转换 TIM2 时间。

nx_result_t nx_stm32u575_lpdma_lptim1_cancel(const nx_stm32u575_lpdma_lptim1_t *receiver, nx_stm32u575_lpdma_lptim1_request_t *request)¶: 请求撤源，不撤销任何被借用的存储。

备注

复合恢复全程使用屏蔽的 privileged MSP Thread。观察到 DMA 完成之后的迟到 cancel 被以 STATE 拒绝。首次失败保留。

nx_result_t nx_stm32u575_lpdma_lptim1_service(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)¶: 有界隔离 producer/master，从不独立 settlement。

备注

Producer UEDE 撤源先于 DMA suspend/reset/idle。全部最终 peripheral/IRQ 引用与 Stop2 恢复先于最终归还。Clock/access profile 未知时不允许 peripheral MMIO；借用期间的外部 DMA 或 LPTIM reset 将该借用永久隔离。

nx_result_t nx_stm32u575_lpdma_lptim1_stop(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)¶: 关闭准入，并在复合 join 后恢复自有 start 效果。

备注

正数的每阶段观察预算不代表经过时间。BUSY 保持全部效果和存储有效；通过 concrete Stop2 owner 恢复。新的最终 write-OK 证明表示寄存器写入已同步，绝不代表物理 Stop2 驻留、输出播放、Board 路线或 HIL。

变量

const nx_stm32u575_lpdma_lptim1_ops_t nx_stm32u575_lpdma_lptim1_ops¶

struct nx_stm32u575_lptim1_tuple_t¶

#include <stm32u575_lpdma_lptim1.h>

调用者拥有且不可变的一组寄存器 tuple，位于精确 SRAM4 中。

备注

CCR1 < ARR、RCR=0 且 1023<=ARR<=65535。恰好一组 tuple；重复更新需要单独的 write-OK 证明，本参考不准入。该参考不建立 GPIO 路线或物理波形播放。

公共成员

uint32_t ccr1¶

uint32_t rcr¶

uint32_t arr¶

struct nx_stm32u575_lpdma_lptim1_workspace_t¶

#include <stm32u575_lpdma_lptim1.h>

恰好两个生成的 continuation LLI；绝不是调用者指令。

备注

整个对齐的 48 字节范围是独立的 nonsecure SRAM4。Owner 仅在 ACCEPTED 之后写入所有字；直到 SETTLED 都须保持不可变。

公共成员

uint32_t private_words[12]¶

union nx_stm32u575_lpdma_lptim1_storage_t¶

#include <stm32u575_lpdma_lptim1.h>

调用者存储须预先清零，不得复制、reset 或重建活动 owner。

备注

由一个 privileged Thread 串行调用全部方法；不得有 ISR 或并发 writer。Owner、clock 和每个 face 必须保持有效，直至 stop 与 observer join 完成。

公共成员

uint64_t alignment¶

uintptr_t pointer_alignment¶

unsigned char private_bytes[NX_U575_LPDMA_LPTIM1_STORAGE_BYTES]¶

struct nx_stm32u575_lpdma_lptim1_config_t¶

#include <stm32u575_lpdma_lptim1.h>

显式绑定有效的 retained-clock 和同一 concrete Stop2。

备注

使用普通 retained-clock 初始化器，wake_owner 等于 nx_stm32u575_stop2_identity()。无需 AlarmA-copy opt-in。

公共成员

nx_stm32u575_retained_time_storage_t *clock¶

const void *wake_owner¶

struct nx_stm32u575_lpdma_lptim1_request_t¶

#include <stm32u575_lpdma_lptim1.h>

准备好的元数据；prepare 之后所有字段由 provider 控制。

备注

先初始化 base。ACCEPTED 借用 request、tuple 和 workspace，直到 acquire 观察到 SETTLED 且外部 join 完成。Cancel/deadline 不撤销借用。CPU control storage 必须与 SRAM4 data/LLI 分开。借用期间不得修改或重新 prepare。

公共成员

nx_request_t base¶

const void *identity¶

const nx_stm32u575_lptim1_tuple_t *tuple¶

void *private_destination¶

size_t private_length¶

nx_stm32u575_lpdma_lptim1_workspace_t *workspace¶

const void *clock_identity¶

uint64_t clock_generation¶

struct nx_stm32u575_lpdma_lptim1_ops_t¶

#include <stm32u575_lpdma_lptim1.h>

共享不可变方法；service 从不发布 SETTLED。

公共成员

nx_result_t (*cancel)(void*, nx_stm32u575_lpdma_lptim1_request_t*)¶

nx_result_t (*service)(void*, uint32_t)¶

nx_result_t (*stop)(void*, uint32_t)¶

nx_result_t (*start)(void*, uint32_t)¶

struct nx_stm32u575_lpdma_lptim1_t¶

#include <stm32u575_lpdma_lptim1.h>

复制的不可变 face 保留精确物理 owner 身份。

公共成员

const nx_stm32u575_lpdma_lptim1_ops_t *ops¶

void *context¶

stm32u575_stop2.h¶

精确 U575 TZEN0 保留 RTC 的 Stop2 边界。

作者 Nexus Team

函数

const void *nx_stm32u575_stop2_identity(void)¶: 供保留时间 wake_owner 使用的稳定可信装配身份。

nx_result_t nx_stm32u575_stop2_initialize(size_t capacity, nx_stm32u575_retained_time_storage_t *clock)¶

绑定静态所有者并构造其 RUN 域。

备注

仅一次，由特权、未屏蔽中断的 Thread 串行调用。时钟存储须在此所有者的整个生命周期中保留。不写入硬件，也不分配堆内存。

参数:

capacity – [in] 外部使用者租约数量的正数上限。
clock – [inout] 绑定到此身份的活动保留时间所有者。

返回:

SUCCESS、INVALID、CONTEXT、STATE 或时钟失败。

nx_clock_domain_t *nx_stm32u575_stop2_domain(void)¶: 纯查询；全部平台／产品 RUN 所有者均须显式登记。

nx_stm32u575_stop2_result_t nx_stm32u575_stop2_enter(nx_clock_barrier_t owners, uint32_t wake_ticks, uint32_t poll_limit)¶

在 PRIMASK=1 时配置 WUT、跨越 Stop2、恢复并排空。

备注

仅适用于精确 STM32U575ZIT6Q TZEN0 裸机。特权 MSP Thread，CONTROL=0、PRIMASK=1、BASEPRI=FAULTMASK=0；不得已启动调度器。关闭 RUN 接纳、停止 Platform/System，并汇合全部生产者、IRQ、DMA、观察者及截止时间使用者。仅在实际排空后释放租约；没有剩余使用者时才传入已关闭屏障。登记从不自动进行。结束 Core TIM2 截止时间；不读取或重新启动 TIM2。独立 RTC 时钟位于此 RUN 域之外。要求 MSIS4/MSIK4／等总线频率、静默门控、全部 SRAM 保留，并关闭缓存、调试、MPU、SysTick、其他 IRQ 及 EXTI 源。拒绝时读取 SysTick CTRL 也会消耗 COUNTFLAG。独占 RTC：绑定的日历读取者及此 WUT 写入者。启动代码提供有效的保留 LSE 日历及 DBP=1。仅写入 WUT；每阶段先解锁 WPR 再重新锁定。外部须排除 NMI/HardFault、调试器、看门狗、其他主设备及异步配置写入者。门控值为零不能证明这些义务已满足。绑定是可信装配身份，不是硬件认证。WUTR=wake_ticks-1；首次 WUTF 位于 WUTR 至 WUTR+2 个节拍之间。RTC 采样分辨率为 3906.25us；短唤醒可能显示零经过时间。保留时钟的 max_gap_seconds 必须覆盖睡眠、配置／排空执行及外部有界唤醒延迟。如果硬件唤醒失败，WFI 没有 CPU 时长上限。错过采样间隔会污染独立时钟纪元。wait_executed 仅证明执行了 WFI，不证明物理驻留。全部返回路径均保留屏蔽状态。成功要求观察到 WUT、IRQ 及所加门控均已撤回，并恢复 MSIS4/MSIK4/Range4。排空失败时保留所有权。保持接纳关闭及相关对象存活；任何重启前均须调用 recover。任何失败都不撤销借用。重新启动 Platform 会创建新的 TIM2 纪元；旧截止时间均不能跨越该生命周期。仍不支持 RTOS Tick 补偿及 LPBAM。

参数:

owners – [in] 来自此精确域、已关闭且已排空的屏障。
wake_ticks – [in] 2..65536 个 RTC/16 节拍，标称 488.28125us。
poll_limit – [in] 每阶段有限观察预算，必须为正。

返回:

主结果／清理结果、保留效果及 RTC 采样。

nx_stm32u575_stop2_result_t nx_stm32u575_stop2_recover(nx_clock_barrier_t owners, uint32_t poll_limit)¶: 重试保留的 WUT／IRQ／时钟排空，不再执行 WFI。

备注

使用相同屏蔽边界及精确已关闭屏障。恢复不能修复被污染的 RTC 纪元，也不能授权旧截止时间。即使 RTC 采样无效，硬件排空仍可完成。须在保留时钟显式停止／重新打开前汇合其全部使用者。

struct nx_stm32u575_stop2_result_t¶

#include <stm32u575_stop2.h>

有界转换结果；快照仅属于 RTC 时钟域。

公共成员

nx_result_t primary¶

nx_result_t cleanup¶

uint32_t remaining_effects¶

bool wait_executed¶

bool wake_flag¶

nx_stm32u575_retained_time_snapshot_t before¶

nx_stm32u575_retained_time_snapshot_t after¶

stm32u575_stop2_copy.h¶

同一精确 owner 的 U575 Stop2 有限 SRAM4 复制边界。

函数

nx_stm32u575_stop2_copy_result_t nx_stm32u575_stop2_copy_enter(nx_clock_barrier_t owners, const nx_stm32u575_lpdma_copy_t *copy, nx_stm32u575_lpdma_copy_request_t *request, uint32_t escape_ticks, uint32_t poll_limit)¶

携带一次有限的 AlarmA 触发 SRAM4 复制跨越 Stop2。

备注

enter 对中断屏蔽状态、MSP Thread 及已停止／汇合的 RUN 域所设的全部前提仍须满足。时钟使用显式 AlarmA-copy 初始化函数及此 owner 的唤醒身份。所选启动代码提供非安全 SRAM4 及已准备的 LPDMA1 访问；无关通道及主设备均静默。接收器验证实际绑定及寄存器。调用者回调或门控掩码均不能授权例外。

备注

全部日历掩码位均已置位；ALRMASSR=0、ALRAIE=0 及 ALRAFCLR=0。在 ALRAE 使能 trigger14 上的下一个整秒事件前，接收器已准备就绪。生产者保持使能期间，不得清除 ALRAF 或 DMA pending。WUT 是独立的逃逸源。接收器拥有其生成的第二个 LLI，以及 LPDMA1 channel0 IRQ114 唤醒向量。wait_executed 仅证明执行了 WFI，不证明物理驻留。

备注

拒绝时，新请求保持未借用。一旦接纳，配置失败会保留每个复制引用，直到 RTC/WUT 生产者、DMA 主设备／复位、IRQ、门控及时钟恢复均被独立确认静默。保持两个 owner、时钟、缓冲区、工作区及 RUN 屏障存活，且屏障保持关闭。保留状态的恢复期间须保持 PRIMASK=1。recover 重试同一复合链，不执行 WFI。若观察到外部 LPDMA 复位，此链将被永久隔离：静默复位值及复位解除不能证明先前主设备的最终访问。只有外部确立的系统复位才能结束该责任。受污染的时钟可以在硬件排空后以错误结束请求，但绝不能提供新的成功经过时间结果。此处不建立任何旧 TIM2 截止时间、RTOS 补偿、外设 LPBAM 计划或物理复制结果。

备注

此模式仅链接 Nexus::U575Stop2Copy。它与 Nexus::U575Stop2 拥有相同的静态 RUN 域及 WUT/recover 符号；同时链接两个备选实现会被拒绝。仍可调用仅使用 WUT 的 enter，但会拒绝每个保留中的复制借用。完全恢复前须保持 PRIMASK=1。

参数:

owners – [in] 精确 RUN 域中已关闭且排空的屏障。
copy – [in] 已初始化且不可变的 LPDMA1/channel0 face。
request – [inout] 已准备为 READY、位于绑定保留时间域中的复制请求。
escape_ticks – [in] 4096..65536 个 RTC/16 节拍，标称 2..32 s。
poll_limit – [in] 每阶段使用正数观察预算。

返回:

接纳、转换、清理及保留效果。

struct nx_stm32u575_stop2_copy_result_t¶

#include <stm32u575_stop2_copy.h>

分别观察复制接纳及精确 Stop2 转换。

备注

accepted 表示请求、缓冲区及工作区已被借用，包括后续 RTC/电源配置失败的情况。只有以 acquire 观察到请求 SETTLED 后，才能读取最终复制结果及计数。transition 描述边界；dma_wake 记录所观察到的 ch0 NVIC pending。

公共成员

bool accepted¶

bool dma_wake¶

nx_stm32u575_stop2_result_t transition¶

stm32u575_stop2_lptim1.h¶

同一 concrete Stop2 owner 和有限 LPTIM1 LPBAM 边界。

函数

nx_stm32u575_stop2_lptim1_result_t nx_stm32u575_stop2_lptim1_enter(nx_clock_barrier_t owners, const nx_stm32u575_lpdma_lptim1_t *receiver, nx_stm32u575_lpdma_lptim1_request_t *request, uint32_t escape_ticks, uint32_t poll_limit)¶: 跨 Stop2 的一组有限硬件请求 LPTIM1 tuple。

备注

仅链接 Nexus::U575Stop2Lptim1；WUT/copy 备选互斥。沿用同一 static owner、RUN ClockDomain 和 recovery。普通 retained time 使用此 wake identity；须先显式启动专用 receiver。仍须满足关闭并排空的精确 RUN barrier、已停止的 Platform、privileged MSP Thread CONTROL0/PRIMASK1/BASEPRI0/FAULTMASK0。全部保留恢复期间须维持掩码及 RUN 准入关闭。

备注

LPTIM1 LSE/preload/CC1E，初始 ARR1023/RCR0；request13/BREQ1 门控 CCR1，两个生成的软件请求 LLI 写 RCR，最后写 ARR。无 AlarmA trigger。WUT 在 4096..65536 个 RTC/16 tick 时提供逃逸唤醒。正数 poll_limit 约束观察次数，不约束 WFI 时长或物理响应。

备注

UEDE 撤源/DIEROK 先于 DMA suspend/reset/idle 和引用移除。新的 write-OK 是成功的必要条件。自有 RCC reset 按 ES0499 关闭 LPTIM1。全部 peripheral/IRQ/gate/clock 恢复先于 SETTLED；start access gate 保留至 joined public stop。Cancel/deadline 从不撤销存储借用。Profile 未知时不允许 peripheral MMIO。外部 peripheral reset 将活动借用永久隔离，直至系统 reset。Recovery 从不执行 WFI。该参考不暗示 GPIO/Board 路线、输出播放、物理驻留、timing/power 或 HIL 结果。

struct nx_stm32u575_stop2_lptim1_result_t¶

#include <stm32u575_stop2_lptim1.h>

准入与软件睡眠观察，不是最终结果。

备注

即使后续设置失败，accepted 仍借用 request/tuple/workspace。dma_wake 表示 pending IRQ114；wait_executed 仅证明执行过 WFI。

公共成员

bool accepted¶

bool dma_wake¶

nx_stm32u575_stop2_result_t transition¶

user_io_async.h¶

有界复制式 UART 用户代理。

类型定义

typedef struct nx_user_io_async nx_user_io_async_t¶

枚举

enum nx_user_io_async_constants¶

取值：

enumerator NX_USER_IO_ASYNC_ABI¶

enumerator NX_USER_IO_ASYNC_SUBMIT¶

enumerator NX_USER_IO_ASYNC_POLL¶

enumerator NX_USER_IO_ASYNC_CANCEL¶

enumerator NX_USER_IO_ASYNC_CONSUME¶

函数

nx_result_t nx_user_io_async_dispatch(nx_user_io_async_t *mediation, const nx_user_io_async_message_t *message, const uint8_t *payload, nx_user_io_async_reply_t *reply)¶

认证并复制一次有界用户网关事务。

备注

特权、未屏蔽中断的 Thread，由唯一网关执行者串行调用。每次调用均认证当前主体。可信复制端口提供故障隔离和映射稳定性；仅范围检查不能证明两者。调用方另外推进既有 BusOwner/UARTOwner；本调用从不执行其 service。CANCEL 仅请求其排空。CONSUME 要求以 acquire 观察 SETTLED 及既有所有者的空闲／汇合屏障，先复制回复，再擦除字节并释放精确单元。回复复制失败、取消或隔离都不释放已接受单元。不提供 SVC/CMSE 入口或 NS RTOS。

参数:

mediation – [inout] 可信特权绑定及精确复制槽位。
message – [in] 临时完整可读的用户头部，仅复制一次。
payload – [in] 临时可读的 SUBMIT 字节；其他情况为 NULL。
reply – [out] 临时、互不重叠且完整可写的用户回复。

返回:

回复复制后返回 SUCCESS；否则返回身份、跨度、协议、复制或控制错误。任何返回后均不保留用户地址。接受后仍可能发生回复复制错误：以 POLL 查询所提出的槽位／纪元；重复 SUBMIT 不得重放或替换它。

nx_result_t nx_user_io_async_close(nx_user_io_async_t *mediation)¶: 关闭复制接纳并取消此绑定的活动工作。

备注

可信特权管理操作，不是用户网关动作。与 dispatch/join 使用同一串行生命周期执行者，但同步身份／复制回调可以请求 close。这不是通用的跨任务并发控制 API。关闭是永久的，但不关闭底层所有者。此处不运行工作线程或提供者 service。须继续推进所有者，并通过常规 dispatch 认证 POLL/CONSUME。身份／复制回调可以请求 close，但不得递归 dispatch 或重新构造。全部绑定存储保持存活。

nx_result_t nx_user_io_async_reap(nx_user_io_async_t *mediation)¶: 用户映射永久丢失后的特权回收。

备注

与 close/join 使用相同的可信串行管理；绝不是不可信的传输动作。由内核决定何时授权清理。先 close/cancel，再另行推进真实所有者。每个保留的精确单元都必须以 acquire 观察 SETTLED，且所有者必须空闲。随后可信 drained 证明阻止未来网关入口并汇合全部外部观察者，同时保留角色。只有此后才能擦除全部复制载荷并回收单元，无需向用户复制输出。待处理、隔离或未汇合的工作保留每个单元不变。成功具有幂等性，并永久拒绝 dispatch。它不释放角色：回收任何绑定存储前仍须成功 join。不提供强制撤销借用、进程存活策略或提供者 service。

nx_result_t nx_user_io_async_join(nx_user_io_async_t *mediation)¶

汇合已关闭／已消费单元、所有者及可信网关角色。

备注

可信串行管理。不创建重新初始化／重新打开、隐式提供者停止或身份注册表。成功 join 后，可由新对象申领更大的会话；不得重置或重新构造此活动对象。

返回:: 仅在不再存在网关／复制、复制单元或所有者发布者，且可信角色释放证明外部网关观察者已汇合后返回 SUCCESS；BUSY 或错误均保留角色与存储。

struct nx_user_io_async_message_t¶

#include <user_io_async.h>

十二个本地 C 网关标量字；不含主体、地址或回调。

备注

SUBMIT 在精确已申领的非零会话内，为显式槽位提出精确下一个非零 64 位纪元，并提供正数长度及既有所有者时钟域中的绝对截止时间。其他动作使用精确已接受纪元，长度／截止时间字均为零。device 必须匹配不可变可信绑定；reserved=0。字对按低半部、高半部编码，不依赖编译器枚举、指针或 uint64_t 的对齐 ABI。这些是本地 C 网关记录；字节序及任何传输序列化均由集成内核负责。

公共成员

uint32_t abi¶

uint32_t action¶

uint32_t device¶

uint32_t slot¶

uint32_t session_low¶

uint32_t session_high¶

uint32_t epoch_low¶

uint32_t epoch_high¶

uint32_t length¶

uint32_t deadline_low¶

uint32_t deadline_high¶

uint32_t reserved¶

struct nx_user_io_async_reply_t¶

#include <user_io_async.h>

十个已初始化标量字；不含特权指针。

备注

state 为编码成 uint32_t 的 Core nx_request_state_t 值。仅 SETTLED 具有最终结果／计数；其他结果为 BUSY，计数为零。accepted=1 表示保留的复制单元，包括既有所有者拒绝接纳时的终结错误。仅接受本身不产生硬件效果。

公共成员

uint32_t abi¶

uint32_t slot¶

uint32_t session_low¶

uint32_t session_high¶

uint32_t epoch_low¶

uint32_t epoch_high¶

uint32_t state¶

uint32_t result¶

uint32_t transferred¶

uint32_t accepted¶

user_io_async_storage.h¶

针对精确复制 UART 用户单元的可信内核装配。

枚举

enum nx_user_io_copy_access¶

名义复制权限；实际访问仍须经过可信复制。

取值：

enumerator NX_USER_IO_COPY_READ¶

enumerator NX_USER_IO_COPY_WRITE¶

函数

nx_result_t nx_user_io_async_construct(nx_user_io_async_t *mediation, nx_user_io_async_slot_t *slots, size_t count, const nx_user_io_async_config_t *config)¶

在真实所有者之上初始构造精确复制代理。

备注

特权、未屏蔽中断的 Thread，所有者空闲且没有并发使用者。初始 O(n squared) 别名检查拒绝全部已知可变单元／载荷／控制重叠及用户 RAM 别名。接纳检查固定区域范围，复制量不超过所选精确载荷预算；不增加队列或工作线程。策略、单元、所有者、提供者及全部上下文须在永久关闭、消费直至成功汇合期间保持稳定。纯初始检查先于构造保留及可信角色申领；成功申领后不再有可失败步骤。新对象须从外部申领更大的会话；不得重新构造此对象以重置纪元。

参数:

mediation – [out] 全新零初始化的特权存储，仅初始化一次。
slots – [inout] 调用方拥有的精确单元／载荷，不设最大存储池。
count – [in] 能以标量槽位 ID 表示的正数单元数量。
config – [in] 不可变可信主体／授权／复制／所有者绑定。

返回:

SUCCESS 或 INVALID/STATE/CONTEXT/BUSY/EXHAUSTED，或可信申领错误；不新增保留的用户引用或硬件效果；拒绝时每个输出均保持不变。

struct nx_user_io_copy_region_t¶

#include <user_io_async_storage.h>

名义上的实际用户 RAM；真实访问仍由可信复制强制检查。

公共成员

uintptr_t begin¶

size_t bytes¶

uint32_t access¶

struct nx_user_io_copy_ops_t¶

#include <user_io_async_storage.h>

有界可信内核身份及具有故障隔离的复制。

备注

identity 认证当前入口，绝不接受用户提供的身份。复制操作保证在回调期间完成全部经检查的 CPU 访问，并保证映射／进程生命周期。无论成功或错误，返回后均不保留用户地址、内核临时指针、映射或观察者。错误可能发生在部分字节已复制之后；拒绝时擦除复制载荷单元，回复失败可通过精确槽位／纪元恢复。任何回调都不得阻塞、递归 dispatch，或以权限观察替代故障安全复制。身份／复制回调可以关闭此代理。新的内核／CMSE 包装层必须真正建立这些前提；本组件不提供它们。claim 是针对实际所有者／控制器绑定的可信独占角色授权者。即使会话更大，也拒绝第二个活动角色；并依据跨新存储、进程／器件复位及重构保留的持久、不回绕历史，拒绝复用或不递增的非零会话。失败申领不保留任何引用或效果。成功申领永久消耗该会话，并保留精确角色直至释放。release 返回 SUCCESS 证明外部网关／传输观察者已汇合，并分离全部授权引用；失败时原角色保持不变。drained 返回 SUCCESS 永久阻止未来外部网关入口，并汇合全部网关／传输观察者，同时精确角色仍被申领。drained 失败保留角色及每个单元不变。它不得修改绑定配置、单元身份或请求。claim、release 和 drained 有界，且不得递归 construct、dispatch、close、reap 或 join。上下文／历史必须保持存活；源码不实现此内核授权、物理隔离、存储分区或恢复策略。同一控制器的不同包装不构成不同角色。

公共成员

nx_result_t (*claim)(void *context, uint32_t principal, uint32_t device, uint64_t session, nx_bus_owner_t *owner, const nx_user_io_async_t *role)¶

nx_result_t (*release)(void *context, const nx_user_io_async_t *role, uint64_t session)¶

nx_result_t (*drained)(void *context, const nx_user_io_async_t *role, uint64_t session)¶

nx_result_t (*identity)(void *context, uint32_t *principal)¶

nx_result_t (*copy_in)(void *context, uint32_t principal, void *destination, const void *user_source, size_t bytes)¶

nx_result_t (*copy_out)(void *context, uint32_t principal, void *user_destination, const void *source, size_t bytes)¶

struct nx_user_io_copy_port_t¶

#include <user_io_async_storage.h>

公共成员

const nx_user_io_copy_ops_t *ops¶

void *context¶

size_t context_bytes¶

struct nx_user_io_async_config_t¶

#include <user_io_async_storage.h>

不可变可信的单主体／单设备／单所有者授权。

备注

这是内核配置，绝不从用户复制。owner/executor/port 必须是已构造的精确 BusOwner + UARTOwner 桥接，不得有其他直接生产者或外部请求／载荷观察者。不安装完成回调。全部回调上下文保持在特权内存中；显式范围覆盖其完整活动控制。保护、时钟及唤醒上下文可以是同一可信对象。调用方负责实际 UART 启动、硬件归属、执行者调度、时钟／截止时间域及最终停止。

公共成员

uint32_t principal¶

uint32_t device¶

uint64_t session¶

nx_bus_owner_t *owner¶

nx_uart_owner_executor_t *executor¶

const nx_uart_port_t *port¶

size_t port_context_bytes¶

size_t guard_context_bytes¶

size_t clock_context_bytes¶

size_t wake_context_bytes¶

nx_user_io_copy_port_t copy¶

const nx_user_io_copy_region_t *regions¶

size_t region_count¶

struct nx_user_io_async_slot_t¶

#include <user_io_async_storage.h>

精确特权单元；仅初始化 data 和 capacity。

备注

其他字段初始均为零，构造后为机制私有。data 是独立可写特权 RAM；capacity 是精确正数字节预算，最大为 UINT32_MAX。此处绝不赋入用户指针。Core 身份纪元从不回绕，并在 consume/close 后保留；不得复制或重置活动单元。UARTOwner 借用操作／载荷直至真实提供者的最后访问，此后用户结果保留至回复复制成功且 CONSUME 已汇合，或可信 reap 已汇合。两条路径均保留纪元历史。

公共成员

uint8_t *data¶

size_t capacity¶

nx_request_slot_t identity¶

nx_request_t request¶

nx_uart_owner_operation_t operation¶

nx_owner_ticket_t owner_ticket¶

struct nx_user_io_async¶

#include <user_io_async_storage.h>

调用方拥有的可信控制；仅初始化一次，不得重置纪元。

公共成员

const nx_user_io_async_config_t *config¶

nx_user_io_async_slot_t *slots¶

size_t count¶

bool initialized¶

bool constructing¶

bool closing¶

bool closing_call¶

bool working¶

bool releasing¶

bool joined¶

bool reaping¶

bool reaped¶

i3c_controller.h¶

显式有界的 I3C 发现、传输及事件所有权。

类型定义

typedef struct nx_i3c_controller nx_i3c_controller_t¶

枚举

enum nx_i3c_kind_t¶

取值：

enumerator NX_I3C_DISCOVER¶

enumerator NX_I3C_PRIVATE¶

enumerator NX_I3C_CCC¶

enum nx_i3c_event_kind_t¶

取值：

enumerator NX_I3C_EVENT_IBI¶

enumerator NX_I3C_EVENT_HOT_JOIN¶

函数

nx_result_t nx_i3c_request_prepare(nx_i3c_request_t *request, nx_i3c_kind_t kind, nx_i3c_endpoint_t endpoint, uint8_t ccc, uint8_t *data, size_t bytes, bool read, bool broadcast, nx_time_us_t deadline)¶: 准备未使用的元数据，不取得载荷借用。

备注

由所有者 Thread 串行执行。DISCOVER 没有载荷或目标。PRIVATE 允许 1..65535 字节。CCC 仅允许 ENEC/DISEC 广播／定向写入，以及具有精确定义长度的定向 GETMWL/GETMRL/GETPID/GETBCR/GETDCR/GETSTATUS 读取。GETMRL 使用两字节；若已确认 BCR 的 bit2 声明 IBI 载荷，则使用三字节。拒绝改变地址、HDR 及控制器交接 CCC。全部 API 都要求唯一串行执行者。端口与时钟回调不得重入核心、调用应用代码或修改保留状态。不得在 ISR 中调用；不进行分配，不使用 OS 锁或工作线程。绝对截止时间使用注入的时钟。

nx_result_t nx_i3c_submit(nx_i3c_controller_t *controller, nx_i3c_request_t *request, nx_i3c_ticket_t *ticket)¶: 经初始校验及就绪检查后接纳有限操作。

备注

SUCCESS 转移借用。拒绝不产生效果，也不保留引用。输出不得与保留的控制器、端口表、目标／事件存储、策略、请求或载荷形成别名。端口与时钟上下文范围仍由调用方负责。

nx_result_t nx_i3c_service(nx_i3c_controller_t *controller)¶: 执行一个有界 FIFO／事件阶段，或一次排空证明。

备注

部分 DAA、畸形观察及错误使接纳进入故障状态，同时保留每个已知／暂定分配地址。取消、超时或排空失败绝不释放借用。静默证明失败时保持 QUARANTINED；继续 service 可以恢复。事件溢出返回 OVERFLOW 并锁存计数，不丢弃已保留的队列事件。

nx_result_t nx_i3c_cancel(nx_i3c_ticket_t ticket)¶: 在解引用请求前，使用稳定纪元请求撤回。

nx_result_t nx_i3c_endpoint(nx_i3c_controller_t *controller, size_t index, nx_i3c_endpoint_t *endpoint)¶: 仅获取已确认目标；拒绝暂定／已退役记录。

nx_result_t nx_i3c_event_take(nx_i3c_controller_t *controller, nx_i3c_event_t *event)¶: 复制一个保留事件；EMPTY 时输出不变。

nx_result_t nx_i3c_event_status(nx_i3c_controller_t *controller, nx_i3c_event_status_t *status)¶: 复制饱和丢失计数器，不清零。

nx_result_t nx_i3c_close(nx_i3c_controller_t *controller)¶: 关闭接纳，不更改借用、目标身份或事件。

nx_result_t nx_i3c_reset(nx_i3c_controller_t *controller)¶: 使动态地址失效前，证明已完成整条总线复位。

备注

要求接纳已关闭。硬件证明必须同时覆盖真实线路、FIFO、IRQ 静默，以及每个目标的动态地址均已失效。仅外设复位或 FIFO 清空绝不构成此证明。失败保留全部借用与地址记录。成功使未完成工作结算并使端点失效；保留事件仍携带旧纪元供调用方处理。

nx_result_t nx_i3c_reopen(nx_i3c_controller_t *controller)¶: 重新打开空闲且无故障的暂停；故障要求显式总线复位。

nx_result_t nx_i3c_stop(nx_i3c_controller_t *controller)¶: 关闭、撤回，最后放弃唯一控制器。

备注

活动工作或队列事件返回 BUSY。调用方须继续 service、消费事件并重试。存在已分配／暂定地址或故障时返回 STATE，直至整条总线复位证明使其失效。最终真实线路／FIFO／IRQ 静默证明成功后释放所有权，不得重新构造此对象。存储须在所有复制的端点与票据存续期间保持有效。

struct nx_i3c_endpoint_t¶

#include <i3c_controller.h>

绑定到控制器的已确认目标代次，绝不是工厂 ID。

公共成员

nx_i3c_controller_t *controller¶

size_t index¶

uint64_t epoch¶

struct nx_i3c_ticket_t¶

#include <i3c_controller.h>

稳定操作身份；控制器须在全部复制的控制存续期间保持有效。

公共成员

nx_i3c_controller_t *controller¶

uint64_t epoch¶

struct nx_i3c_request_t¶

#include <i3c_controller.h>

调用方拥有的有限操作；不隐式发现总线。

备注

仅使用 nx_request_initialize 初始化 base 一次。已接受元数据和载荷保持借用，直至以 acquire 观察 SETTLED。TX 保持不可变；transferred 统计交给 FIFO 的字节，而不是目标已确认的效果。错误后不重放。在整个已接受借用期间，公共字段均不可变。

公共成员

nx_request_t base¶

nx_i3c_endpoint_t endpoint¶

uint8_t *data¶

size_t bytes¶

nx_i3c_kind_t kind¶

uint8_t ccc¶

bool read¶

bool broadcast¶

struct nx_i3c_event_t¶

#include <i3c_controller.h>

复制的事件；不调用回调、不创建目标、不隐式执行工作。

备注

IBI 端点保留精确已确认目标纪元。已确认 BCR 的 bit1 必须声明 IBI 能力。bit2 置位时要求 1..4 字节载荷且包含 MDB；否则为零数据字节。HOT_JOIN 不携带端点，仅请求由调用方显式控制的发现。与所选 H563 参考一致，载荷最多四字节；不提供时间戳保证。

公共成员

nx_i3c_event_kind_t kind¶

nx_i3c_endpoint_t endpoint¶

uint8_t payload[4]¶

uint8_t bytes¶

struct nx_i3c_event_status_t¶

#include <i3c_controller.h>

显式丢失统计；计数器饱和而不回绕。

公共成员

uint32_t overflow¶

uint32_t rejected_ibi¶

i3c_controller_storage.h¶

调用方存储及聚合 I3C 硬件边界。

函数

nx_result_t nx_i3c_controller_construct(nx_i3c_controller_t *controller, const nx_i3c_controller_config_t *config)¶: 绑定尚未使用且已零初始化的存储，并申领一个控制器。

备注

拒绝重叠、未对齐、地址运算溢出的存储、重复 PID／地址、I3C 保留地址及非零目标。config 值被复制，无需继续存活；但其引用的存储与上下文须保持存活，并与每个请求／载荷／输出分离。48 位 PID 由调用方编写，绝不由工厂选择。正数事件容量及 1..8 字节 service 批次对应此有界 SDR/IBI 参考。不支持传统 I2C、DMA、HDR、目标角色、隐式发现或隐藏事件工作线程。

struct nx_i3c_target_definition_t¶

#include <i3c_controller_storage.h>

预先编写的不可变目标策略，不是运行时工厂发现。

公共成员

uint64_t pid¶

uint8_t address¶

struct nx_i3c_target_state_t¶

#include <i3c_controller_storage.h>

调用方拥有的目标记录，仅零初始化一次。

备注

DAA 出错时核心保留暂定及已确认地址。纪元从不重置或回绕，包括总线复位后。

公共成员

uint64_t epoch¶

uint8_t address¶

uint8_t bcr¶

uint8_t dcr¶

bool assigned¶

bool tentative¶

struct nx_i3c_command_t¶

#include <i3c_controller_storage.h>

值命令；begin 同步复制，不保留指针。

公共成员

nx_i3c_kind_t kind¶

uint32_t bytes¶

uint8_t address¶

uint8_t ccc¶

bool read¶

bool broadcast¶

struct nx_i3c_observation_t¶

#include <i3c_controller_storage.h>

单次有界硬件观察及聚合 FIFO 进度。

备注

任何回调均不保留跨度。tx/rx 计数不得超过提供的容量。本次观察中，DAA 确认必须先确认此前的地址分配，再处理下一个身份。若 DAA 完成时仍有未确认的暂定地址，则是错误，绝不视为隐式成功。事件数据全部复制。

公共成员

size_t transmitted¶

size_t received¶

nx_result_t error¶

uint64_t pid¶

uint8_t bcr¶

uint8_t dcr¶

uint8_t ibi_address¶

uint8_t ibi_payload[4]¶

uint8_t ibi_bytes¶

bool identity¶

bool assigned¶

bool complete¶

bool ibi¶

bool hot_join¶

struct nx_i3c_port_ops_t¶

#include <i3c_controller_storage.h>

同步有界硬件叶操作；不转发请求。

begin 和 assign 是不可失败的命令。pump 报告之后发生的硬件失败，并最多处理所给批次容量，加一个 IBI 锁存及一个热加入锁存。不保留命令或跨度，不调用应用代码。withdraw 请求中止。quiescent 返回 SUCCESS 证明真实线路／FIFO／IRQ 已静默，且全部端口观察者已分离。

reset 还须证明每个目标的动态地址均已失效。仅清空 FIFO 或复位控制器不能报告 SUCCESS。BUSY/IO/UNSUPPORTED 证明结果保留借用与所有权。仅在最终静默证明成功后才调用 release。端口上下文及提供的存储须在所有观察者存续期间保持有效。

备注

全部端口／时钟回调均不可重入：不得调用核心、调用应用代码或修改核心保留状态。claim 原子地取得控制器及其 IRQ／时钟／引脚的独占所有权。SUCCESS 要求独立建立证明：每个目标的动态地址都已失效，包括 MCU 复位期间仍保持供电的目标。调用方须在构造前建立此基线；claim 绝不尝试未经证明的复位。拒绝不产生效果。ready 是只读接纳检查。

公共成员

nx_result_t (*claim)(void *context, const void *owner)¶

void (*release)(void *context, const void *owner)¶

nx_result_t (*ready)(void *context)¶

void (*begin)(void *context, const nx_i3c_command_t *command)¶

void (*pump)(void *context, const uint8_t *tx, size_t tx_capacity, uint8_t *rx, size_t rx_capacity, nx_i3c_observation_t *observation)¶

void (*assign)(void *context, uint8_t address)¶

void (*withdraw)(void *context)¶

nx_result_t (*quiescent)(void *context)¶

nx_result_t (*reset)(void *context)¶

struct nx_i3c_controller_config_t¶

#include <i3c_controller_storage.h>

调用方的精确容量；静态控制器与目标数据分离。

公共成员

const nx_i3c_port_ops_t *ops¶

void *context¶

nx_clock_t clock¶

const nx_i3c_target_definition_t *definitions¶

nx_i3c_target_state_t *targets¶

size_t target_count¶

nx_i3c_event_t *events¶

size_t event_capacity¶

size_t batch_bytes¶

struct nx_i3c_controller¶

#include <i3c_controller_storage.h>

公共成员

nx_i3c_controller_config_t config¶

nx_request_slot_t slot¶

nx_i3c_request_t *active¶

size_t progress¶

size_t pending_target¶

size_t event_head¶

size_t event_count¶

nx_i3c_event_status_t event_status¶

nx_result_t result¶

bool initialized¶

bool closed¶

bool faulted¶

bool draining¶

bool joined¶

f407_i2s2_slave_tx.h¶

精确面向 F407 的有限 stereo16 I2S2 从机发送器。

宏定义

NX_F407_I2S2_SLAVE_TX_STORAGE_BYTES¶

枚举

enum nx_f407_i2s2_resource_t¶

由同一份已验证硬件 IR 选定的固定芯片资源。

取值：

enumerator NX_F407_I2S2_SLAVE_TX¶

函数

nx_result_t nx_f407_i2s2_slave_tx_initialize(nx_f407_i2s2_slave_tx_storage_t *storage, const nx_f407_i2s2_slave_tx_t *face, const nx_f407_i2s2_slave_tx_config_t *config)¶

取得选定 F407 SPI2 工作模式及固定引脚的所有权。

调用方拥有外部主机，并且从初始化或提交之前开始，持续保持 CK 处于空闲 LOW、WS 处于 HIGH，直到以 acquire 语义观察到 ACTIVE。引脚读取只反映采样瞬间，不能证明电气信号持续静止。主机必须恰好传输所声明的完整帧，并在需要下一个尚未提供的数据字之前停止。再次启动时从左声道开始。已预填充时，若取消请求且 CK 仍保持空闲，DR 便无法排空；必须保留处于 QUARANTINED 的存储，直到协调提供的排空时钟允许先观察 TXE，再重新观察 BSY。这种错误排空可能产生欠载，并不保证得到有效的立体声音频或发送完整帧；错误一律报告零传输字节。超时、TC 或 NDTR0 都不能证明线上发送完成或已完成最终访问。调用方还必须按 DS8626 提供有效的工作电压、I/O 电平、负载、CK/WS/SD 时序和 DMA 补充数据裕量。ACTIVE 和引脚采样既不测量这些电气或速率条件，也不构成对它们的验证。

由一个未屏蔽中断的特权任务串行执行所有方法，并串行管理外部所有者的生命周期。所有拒绝路径都必须保留调用前的中断屏蔽状态。不允许从 NMI/HardFault 调用，也不允许其他 DMA/IRQ/引脚所有者、复位或重配时钟的写入方、调试器写入方以及并发 Platform stop 介入。借用期间一旦观察到复位或时钟配置历史丢失，请求就会被永久保留；将寄存器恢复成复位时的样子不能证明此前已经完成最终访问。主 SRAM 对 DMA 可见；CCM 不可见。芯片引脚能力既不能证明 PCB 布线，也不代表已经完成编解码器或电气 HIL 验证。实际的 F407 及封装身份由装配配置和测试夹具确定：仅凭共用的器件组标识和容量读数，既不能区分 F405 与 F407，也不能验证物理封装。

备注

仅支持精确的 F407VE/ZG 器件、baremetal、HSE8/PLL168 以及有效运行中的 TIM2。常规硬件角色以独占方式声明 SPI2/I2S2、PB12 WS/PB13 CK/PB15 SD AF5、DMA1 Stream4 channel0 及两个向量。不启用 PLLI2S、连续 DBM 或 IRQ 服务。外设、引脚和 SPI2 时钟门控的所有权一直保留到 stop 返回 SUCCESS，独立于每个请求持续时间较短的帧借用。选定的冷复位 Platform 单独持有共享的 GPIOB/DMA1 时钟门控。初始化要求这两个门控已经开启；本提供方绝不启用或撤回它们。所有共享域使用者，包括外部 HAL 使用者，都必须在 Platform stop 前完成活动并汇合退出。时钟门控状态不能证明引擎已经复位；不支持接管运行状态未知的硬件。

参数:

storage – [inout] 全新的零初始化存储，且与所有控制对象的存储范围互不重叠。
face – [in] 地址稳定且只读的 {&nx_f407_i2s2_slave_tx_ops, storage}。
config – [in] 固定资源及观察预算。

返回:

SUCCESS、INVALID、CONTEXT、BUSY、STATE、UNSUPPORTED 或 IO。初始化返回 IO 时仍保留清理责任；复用前须调用 stop。

变量

const nx_f407_i2s2_slave_tx_ops_t nx_f407_i2s2_slave_tx_ops¶: 共享且不可变的方法表；回调接收存储上下文。

struct nx_f407_i2s2_tx_request_t¶

#include <f407_i2s2_slave_tx.h>

一个完整、连续且交错存储的 stereo16 帧块。

备注

使用常规辅助函数初始化并准备 base。源数据由一个平面内的连续非空行组成，没有偏移或填充，大小为 4..131068 字节且必须是四的倍数。每帧按先左声道、后右声道的顺序存放 16 位小端采样。固定的 Philips I2S 线上格式使用 16 位时隙，并以 MSB 优先的顺序发送每个采样。采样值、速率、编解码器和外部时钟均由调用方决定。接受请求时会移交该确切且不可变的源帧借用，并借用此请求，直至以 acquire 语义观察到 SETTLED。不得自行释放、修改或复用已接受的存储。只有在内存传输和线上发送均完成后，SUCCESS 才报告整个块的字节数。任何错误或取消均报告零字节；DMA 计数无法证明已经串行发送的音频字节数。

公共成员

nx_request_t base¶

nx_frame_dma_loan_t *source¶

struct nx_f407_i2s2_slave_tx_ops_t¶

#include <f407_i2s2_slave_tx.h>

由一个特权任务串行执行所有操作；不提供 ISR 回调。

备注

submit 返回 SUCCESS 表示 ACCEPTED，即使后续设置失败也不改变这一含义。QUEUED 尚未完成就绪准备。只有在观察到 DR 中已有一个半字且有效运行的 TIM2 已经过所需间隔后，以 acquire 语义观察到 ACTIVE，才允许外部主机开始提供 CK。发生错误、取消或超时时，仍保留完整借用，直到实际完成 DMA 引擎、串行发送器、向量和地址引用的撤回。service 在空闲或请求已终结时返回 SUCCESS；否则返回 BUSY 或观察到的失败状态，同时继续保留借用。stop 关闭后续请求接纳并请求取消；待 service 证明剩余清理已经完成后，再次调用 stop。由于读取 SR 会清除 UDR/FRE，请求的首次 SR 观察仅在接受后发生。观察到的故障在整个清理过程中保持锁存；后续无故障的状态读取不能抹去本次操作的失败原因。任何方法都不分配内存、不启动任务，也不重放数据块。接纳请求时，会以 O(slot count) 的复杂度检查控制对象是否与池中每个槽位的完整容量范围重叠；service/cancel 不扫描该池。

公共成员

nx_result_t (*submit)(void *context, nx_f407_i2s2_tx_request_t *request)¶

nx_result_t (*service)(void *context)¶

nx_result_t (*cancel)(void *context, nx_f407_i2s2_tx_request_t *request)¶

nx_result_t (*stop)(void *context)¶

struct nx_f407_i2s2_slave_tx_t¶

#include <f407_i2s2_slave_tx.h>

由调用方持有的不可变接口对象；私有状态单独存放。

公共成员

const nx_f407_i2s2_slave_tx_ops_t *ops¶

void *context¶

struct nx_f407_i2s2_slave_tx_config_t¶

#include <f407_i2s2_slave_tx.h>

精确选定的资源，以及为正数的有界观察预算。

备注

poll_limit 限制每次就绪准备或排空观察循环的次数，并不表示经过的时间，也不保证外部时钟推进。就绪准备必须在 I2SE 读回后观察到至少三个实际的 1 MHz TIM2 计数推进。截止时间是当前有效 Platform TIM2 时间纪元内的绝对时间。调用方必须先停止该所有者并等待其活动完全结束，再执行 Platform stop/restart；截止时间也涵盖线上发送排空和观察者撤回。这里并不意味着会自动加入 ClockDomain。

公共成员

nx_f407_i2s2_resource_t resource¶

uint32_t poll_limit¶

union nx_f407_i2s2_slave_tx_storage_t¶

#include <f407_i2s2_slave_tx.h>

供一个所有者使用的精确大小存储，在发布前完成一次清零。

备注

不得复制或修改。存储和接口对象必须始终保持有效，直到 stop 成功。已接受的请求及源帧借用一直保留到以 acquire 语义观察到 SETTLED；stop 失败绝不撤销尚未结束的借用。

公共成员

uint64_t alignment¶

uintptr_t pointer_alignment¶

unsigned char private_bytes[NX_F407_I2S2_SLAVE_TX_STORAGE_BYTES]¶

MCUboot 控制与显式 Flash 装配¶

Nexus::MCUBootControl 暴露下述无状态公共控制 API，仅使用 Nexus 类型。Nexus::MCUBootPort 是独立的具体 Flash 装配边界；Nexus::MCUBootBootStorage 属于独立链接的 boot 镜像。这些 target 均不属于默认平台装配。

helper 选择、boot／应用所有权图、有限 operation 与 Flash region 生命周期、部分持久写入和产品恢复责任，以 MCUboot 权威合同为准。所选覆盖配置支持永久更新请求；控制 API 不鉴别候选镜像、不复位硬件，也不提供回滚。软件模型与已链接镜像预算不建立物理 Flash、掉电或 HIL 资格。

mcuboot_control.h¶

固定 MCUboot 覆盖镜像的无状态控制。

所选单镜像配置仅支持永久更新请求。此 API 不下载或校验镜像、不复位硬件、不确认试运行镜像，也不提供回滚。应用负责授权、有效候选字节、维护调度、平台生命周期和复位策略。作者 Nexus Team

枚举

enum nx_mcuboot_request_t¶

请求的更新行为；明确不支持 TEST。

取值：

enumerator NX_MCUBOOT_REQUEST_TEST¶

enumerator NX_MCUBOOT_REQUEST_PERMANENT¶

enum nx_mcuboot_action_t¶

上游观察到的动作，不是物理或镜像健康结论。

备注

外部 trailer 元数据中可能观察到 TEST 和 REVERT；出现这些值不会为覆盖模式固件增加相应模式支持。

取值：

enumerator NX_MCUBOOT_ACTION_NONE¶

enumerator NX_MCUBOOT_ACTION_TEST¶

enumerator NX_MCUBOOT_ACTION_PERMANENT¶

enumerator NX_MCUBOOT_ACTION_REVERT¶

enumerator NX_MCUBOOT_ACTION_FAILED¶

函数

nx_result_t nx_mcuboot_query(nx_mcuboot_action_t *action)¶

查询上游对镜像零的计划动作。

备注

仅限 task／boot 上下文。调用方串行化访问，为整个调用提供不可变 Flash operation hook 及其有限 deadline。所有被引用的 area、region、时钟与 provider 持续存活至返回。固定上游 API 将不可读的 secondary trailer 视为空，因此 NONE 不能证明 secondary 可用或镜像有效。

参数:

action – 仅在成功时接收值；不保留该指针。

返回:

已知动作返回 NX_SUCCESS，NULL 返回 NX_ERROR_INVALID，上游 PANIC、未知值或报告的读取错误返回 NX_ERROR_IO。

nx_result_t nx_mcuboot_request(nx_mcuboot_request_t request)¶

使用上游公共 trailer API 请求永久更新。

备注

沿用 query 的串行化、有限 operation 与生命周期合同。返回时当前 Flash 访问已结清；超时不是中止物理脉冲。该调用不证明候选真实性、不承诺恢复旧镜像、不续期 deadline、不停止基础设施，也不复位 MCU。

参数:

request – PERMANENT 请求更新；TEST 无访问即拒绝。

返回:

上游完成且读回报告 PERMANENT 后返回 NX_SUCCESS；TEST 返回 NX_ERROR_UNSUPPORTED，未知请求返回 NX_ERROR_INVALID，读回其他已知动作返回 NX_ERROR_STATE，上游错误返回 NX_ERROR_IO。部分持久 trailer 修改后仍可能返回错误，包括不能悄悄提升为永久更新的 pending TEST。

扩展与生命周期 API¶

显式 F407 熵源构造¶

stm32f407_entropy.h¶

frame_stream.h¶

spi_dma_owner.h¶

mapped_storage.h¶

mapped_storage_owner.h¶

native_mapped_storage.h¶

amp_ipc.h¶

amp_ipc_storage.h¶

stm32f407_handoff.h¶

frame_dma2d.h¶

stm32u575_retained_time.h¶

stm32u575_lpdma_copy.h¶

stm32u575_lpdma_lptim1.h¶

stm32u575_stop2.h¶

stm32u575_stop2_copy.h¶

stm32u575_stop2_lptim1.h¶

user_io_async.h¶

user_io_async_storage.h¶

i3c_controller.h¶

i3c_controller_storage.h¶

f407_i2s2_slave_tx.h¶

MCUboot 控制与显式 Flash 装配¶

mcuboot_control.h¶

Nexus Embedded Platform

导航