API GUIDE / EFUSE / LL

G32S10 EFUSE LL 接口

LL 层接口：efuse_regs.h 通过 EFUSE_IOBASE 定义唯一实例：

1. 资源模型与公开类型

1.1 实例与寄存器布局

efuse_regs.h 通过 EFUSE_IOBASE 定义唯一实例：

#define EFUSE  ((efuse_regs_t *)(uintptr_t)EFUSE_IOBASE)

实例	基地址宏	基地址
`EFUSE`	`EFUSE_IOBASE`	`0x134A0000UL`

偏移	寄存器	访问	用途
`0x000`	`CTRL`	R/W	地址、长度、读、写、复位和 REDN 路径选择。
`0x004`	`CFG`	R/W	读写调整和 strobe 时序。
`0x008`	`STATE`	R/W	读写完成状态、安全/保护状态。
`0x00C`	`DATA`	R/W	单次访问的最多 4 byte 数据。
`0x010`	`SPEEN`	W	特殊段访问解锁键。
`0x014`	`SPESEG`	R/W	特殊段状态。
`0x018`	`PSRAM_STATE`	R	PSRAM 段保护状态。

单次硬件事务的 CTRL.ADDR 是 8 bit 字节地址，CTRL.LEN 将 1 至 4 byte 编码为 blen - 1；HAL 会将任意段访问拆分为最多 4 byte 的事务。

2. LL 接口规范

LL 接口全部定义为 static inline，首参数为有效的 efuse_regs_t *efusex。它们不检查空指针、实例、地址或控制器状态；ll_efuse_start_read() 与 ll_efuse_start_write() 仅额外拒绝不在 1 至 4 范围内的 blen。同一实例上的并发 start、reset 或 clear 必须由调用方串行化。

2.1 原始寄存器读取

接口	返回值
`ll_efuse_get_ctrl(efusex)`	原始 `CTRL`。
`ll_efuse_get_cfg(efusex)`	原始 `CFG`。
`ll_efuse_get_state(efusex)`	原始 `STATE`。
`ll_efuse_get_data(efusex)`	原始 `DATA`。
`ll_efuse_get_speseg(efusex)`	原始 `SPESEG`。
`ll_efuse_get_psram_state(efusex)`	原始只读 `PSRAM_STATE`。

2.2 状态、特殊访问和时序

接口	功能
`ll_efuse_clear_data(efusex)`	将 `DATA` 清零。
`ll_efuse_clear_state_bits(efusex, mask)`	原子清除指定 `STATE` 位。
`ll_efuse_clear_read_done(efusex)`	清除 `STATE.RD_DONE`。
`ll_efuse_clear_write_done(efusex)`	清除 `STATE.WR_DONE`。
`ll_efuse_enable_special_access(efusex)`	向 `SPEEN` 写入 `EFUSE_SPEEN_KEY`。
`ll_efuse_reset(efusex)`	将 `CTRL` 清零，清除 done 状态与 `DATA`。
`ll_efuse_set_cfg(efusex, value)`	原样写入 `CFG`。调用方负责所有时序字段的合法性。

2.3 事务启动与完成查询

bool ll_efuse_start_read(efuse_regs_t *efusex,
                         uint32_t addr,
                         uint32_t blen,
                         bool use_backup);

bool ll_efuse_start_write(efuse_regs_t *efusex,
                          uint32_t addr,
                          uint32_t data,
                          uint32_t blen,
                          bool use_backup);

两个启动接口仅接受 blen 为 1 至 4；addr 由 CTRL.ADDR 字段掩码写入，调用方必须保证地址在 8 bit 范围内。成功时写入 CTRL，并分别置位 RDEN 或 WREN；LEN 写入 blen - 1，use_backup 为 true 时置位 REDN。它们不等待完成，调用方必须自行轮询：

接口	完成条件
`ll_efuse_read_done(efusex)`	返回 `STATE.RD_DONE`。
`ll_efuse_write_done(efusex)`	返回 `STATE.WR_DONE`。

3. 寄存器与位域约定

3.1 `CTRL`

字段	含义
`REDN[31]`	选择备份/REDN 路径。
`ADDR[28:21]`	字节地址。
`LEN[17:16]`	本次事务长度编码：`0`、`1`、`2`、`3` 分别表示 1、2、3、4 byte；LL/HAL 写入 `blen - 1`。
`RESET[4]`	复位控制器命令。
`WREN[1]`	启动写事务。
`RDEN[0]`	启动读事务。

3.2 `CFG`

字段	含义
`INT_EN[31]`	EFUSE 中断总使能位。当前 HAL 使用 polling，不依赖该位。
`RD_ADJ[23:20]`	读调整值。
`RD_STROBE[19:16]`	有符号 4 bit 读 strobe，范围 -8 至 7。
`WR_ADJ[15:12]`	写调整值。
`WR_STROBE[8:0]`	有符号 9 bit 写 strobe，范围 -256 至 255。

3.3 `STATE` 与保护位

RD_DONE、WR_DONE 是 HAL 轮询完成的状态位。其余位包含 CHIP ID、RETENT、SCBOOT、OS KEY、USER KEY、SCBOOT 备份和 OSC trim 等保护或安全状态；段写入前 HAL 根据段元数据读取 STATE 或 PSRAM_STATE 并拒绝已保护的段。

SPEEN 是写入键寄存器，不应读回或在通用寄存器 dump 中读取。SPESEG 记录特殊段相关状态；PSRAM_STATE 的 bit0 至 bit24 分别对应 PSRAM 类型、配置和时序参数的保护状态。