GPIO 引脚状态：在同一保留租约下显式选择寄存器图像¶

本文说明如何选择明确编写的 DEFAULT 或 SLEEP GPIO 图像，同时保持原有 pad 所有权。当前命名状态装配仅限 STM32G474RET6、GPIOA、baremetal 和 hse24-pll170。其中 PA5 软件 Board 夹具不建立 PCB 接线、电气安全或硬件低功耗行为资格。公共头文件的存在不会自动为其他 provider 增加该模式。

公共 pin-state 声明是 API 合同的权威来源。I/O 演进设计及其实施台账将本机制与后续 wake、retention 和电源模式工作分开记录。本文解释接入和责任边界，不替代这些声明，也不将 IO-31 标记为完成。

一份编写的计划，三种不同身份¶

Board 事实明确给出两个 GPIO 图像。普通 TOML 以 mode = "named-states" 选择 GPIO binding；严格解析产生不可变寄存器计划和既有静态 provider 存储。它不引入运行时字符串、堆、worker、动态注册表或第二个引脚配置权威。

nx_pin_state_id_t 标识一个生成的 factory 实例。
nx_pin_state_port_t 是该实例的不可变公共 face，包含共享 readonly 操作表和该实例的私有 context。
nx_pin_state_selection_t 选择 NX_PIN_STATE_DEFAULT 或 NX_PIN_STATE_SLEEP；它不是 factory 实例 ID。

nx_factory_pin_state() 直接返回既有 face，不访问硬件。普通 GPIO 查找不会返回命名状态实例。生命周期工作属于显式 Platform start/stop；运行选择通过 nx_pin_state_select() 直接进入 provider。

选定配置由以下维护文件给出：

schema = 2
board_package = "../../../cmake/package/verification/io_evolution/boards/g474-pin-states"
backend = "baremetal"
clock = "hse24-pll170"

[memory]
main_stack_bytes = 2048
libc_heap_bytes = 0
static_ram_limit_bytes = 16384
flash_load_limit_bytes = 65536

[gpio.status]
binding = "state-a5"
mode = "named-states"

软件 Board 明确规定：default 为 PA5 output、push-pull、low speed、no pull、level zero，sleep 为 analog/no-pull。这些是夹具值，不是根据板名推断的安全电平。产品必须提供已审查的电气事实及自身策略，不能将这些名称当作安全保证。

FIG-22 描述当前选定的软件生命周期。箭头分别表示构建期生成、纯查找、状态选择和清理。每条失败路径都保留尚未证明已释放的责任；渲染成功不建立物理转换或 HIL 结果。

冷态启动先取得责任，再驱动输出¶

生成的 Platform 拥有精确选定的 pads、bank gate 及原始冷态快照。冷态准入在接受硬件效果前检查选定资源。命名状态初始化要求选定 pads 处于 input 或 analog、未锁定，且 bank 已供钟并未处于 reset。既有 output 或 AF 所有权不构成接管该 pad 的许可。

初始化在开放实例前证明已达到编写的 DEFAULT 图像。启动失败可能留下部分效果及清理责任。Platform rollback 必须执行受检查的 provider stop 与原始快照恢复，不能因为构造返回错误就丢弃租约。必须保持 owner、不可变计划及其完整存储有效，直到清理实际成功。

选择操作在串行特权上下文中执行¶

调用者提供同一 CPU 上唯一、串行、不可重入的特权 Thread 执行者。调用入口的中断屏蔽状态必须清零。ISR/NMI、竞争的 pad 或 RCC 写者、时钟转换和寄存器接管不能与调用并发。这些是接入前提，不是寄存器数值匹配或取得 factory 指针后自动获得的许可。

provider 在有界中断屏蔽区间内执行并恢复保存的中断状态。GPIO 寄存器访问前先检查 bank gate/reset，再检查选定 lock 位，不接管已锁定 pad。bank 不可用时直接拒绝，不暗中开启时钟或清除 reset。即使重新选择同一状态，也检查干净的已提交图像；外部偏移可以返回 STATE 并保留 dirty 责任，而不是静默接受已被修改的图像。

转换时，provider 首先证明整个选定组已撤驱动，再设置所需输出 latch 与电气字段，应用目标 mode，并检查实际目标图像。只有这些证明完成后才提交新选择。掩码保留未选中的 pads。这个顺序描述软件行为，不证明 pad 电压无毛刺、外部偏置或电气稳定时间。

部分失败后，寄存器图像可能既不等于旧图像，也不等于目标图像。租约仍被保留；调用者不能复用存储或将 pads 交给其他写者。尚未 stop 的已初始化实例可以显式重试受支持的目标；其他情况应继续受检查的 Platform 清理。初始化失败或已经撤回的 provider 不能通过选择操作重新开放。没有隐藏后台修复、自动时钟恢复，也不会因 deadline 到期而释放所有权。

stop 有两个不同的完成边界¶

私有 provider stop 证明选定驱动已撤回。成功是该 provider 的最后一次访问，但不会仅凭这个结果恢复 Platform 冷态快照或释放 bank 租约；这些仍是独立的生成 Platform 清理步骤。

Platform 先恢复保存的选定 pad 图像并证明恢复成功，再释放自身 GPIO gate 责任。如果 provider stop 成功后，快照恢复失败，尚待恢复的快照及租约继续存活。如果快照恢复已经证明完成，而仅 gate 清理失败，则只保留剩余 gate 责任。必须保持完整存储有效，直到整个 Platform stop 成功，重试时只推进未完成的清理。不能重复构造、清零存储，也不能将首个错误解释为所有资源仍完整运行或全部已释放。

使用公共 selected face¶

Platform start 成功后，外部产品只使用公共及生成头文件。下面的片段是维护链接夹具中的命名状态分支；外层夹具负责 start 和 stop。它不是独立应用，也不表示物理执行结果。

    const nx_pin_state_port_t* pins =
        nx_factory_pin_state(NX_PIN_STATE_ID_STATUS);
    nx_result_t selected = nx_pin_state_select(pins, NX_PIN_STATE_SLEEP);
    if (selected != NX_SUCCESS)
        return (int)selected;
    selected = nx_pin_state_select(pins, NX_PIN_STATE_DEFAULT);
    if (selected != NX_SUCCESS)
        return (int)selected;

factory 查找、同步选择和最终 Platform 清理不分配 request 或 transfer buffer。操作在至多 16 个选定 pad bit 上执行有界工作；readonly 计划、可变 provider 状态及 Platform 保存的快照是不同的成本项。这个结构性结论不表示已测 MCU 延迟、总 RAM 或最坏中断屏蔽时间。

当前范围与验证边界¶

当前源码为精确的 G474 参考配置实现命名 GPIO 图像、冷态所有权与显式选择。派生能力矩阵记录选定模式和源定义，不建立板卡资格，也不会执行固件镜像。

Native 寄存器/factory 测试建立其实际执行的软件和失败路径证据。真实 ARM 链接、installed SDK 消费和 HIL 各自需要匹配源码的证据。公共接口和图示不建立 AF 切换、wake 路由、retention、deep Sleep/STOP 进入、单调时间连续性、PCB 安全或真实 pad 时序。这些仍属于独立合同与工作包。