API GUIDE / AES / LL

G32S10 AES LL 接口

LL 层接口：当前仅 aesx == AES 返回 true。

1. LL 接口规范

1.1 LL 层边界

全部 helper 定义在 ll_aes.h，使用 static inline。
不维护 handle 或 session。
不打开 CPM 时钟。
不校验枚举、地址、长度或调用顺序。
不执行 cache 操作。
不做等待或超时。
RMW helper 没有锁，调用方必须保证同一 AES 实例串行访问。

1.2 实例 helper

bool ll_aes_is_instance(const aes_regs_t *aesx);

当前仅 aesx == AES 返回 true。

1.3 ASCR 基础配置 helper

void ll_aes_set_page_size(aes_regs_t *aesx,
                          aes_ascr_page_size_t page_size);
void ll_aes_set_input_endian(aes_regs_t *aesx, aes_endian_t endian);
aes_endian_t ll_aes_get_input_endian(const aes_regs_t *aesx);
void ll_aes_set_output_endian(aes_regs_t *aesx, aes_endian_t endian);
aes_endian_t ll_aes_get_output_endian(const aes_regs_t *aesx);
void ll_aes_set_key_length(aes_regs_t *aesx,
                           aes_ascr_key_length_t key_len);
aes_ascr_key_length_t ll_aes_get_key_length(const aes_regs_t *aesx);
void ll_aes_set_mode(aes_regs_t *aesx, aes_ascr_mode_t mode);
aes_ascr_mode_t ll_aes_get_mode(const aes_regs_t *aesx);
void ll_aes_select_encrypt(aes_regs_t *aesx);
void ll_aes_select_decrypt(aes_regs_t *aesx);
void ll_aes_enable(aes_regs_t *aesx);
void ll_aes_disable(aes_regs_t *aesx);

这些 helper 直接读改写 ASCR 对应字段。

1.4 CPU/DMA 启动 helper

void ll_aes_start_cpu(aes_regs_t *aesx);
void ll_aes_start_dma(aes_regs_t *aesx);
void ll_aes_enable_dma(aes_regs_t *aesx);
void ll_aes_disable_dma(aes_regs_t *aesx);
void ll_aes_start_key_expansion(aes_regs_t *aesx);
void ll_aes_init_iv(aes_regs_t *aesx);
void ll_aes_clear(aes_regs_t *aesx);

关键约束：

ll_aes_start_cpu() 置位 ASCR.AESS。
ll_aes_start_dma() 置位 ASCR.DMAS。
ll_aes_start_key_expansion() 置位 ASCR.KEYS，必须在 key FIFO 写入完成后调用。
ll_aes_init_iv() 置位 ASCR.INIT_IV，必须在 CBC IV FIFO 写入完成后调用。
ll_aes_clear() 置位 ASCR.CLR，清除硬件中的 IV、key、input data 和 output data。

1.5 EFUSE key source helper

void ll_aes_clear_efuse_key(aes_regs_t *aesx);
void ll_aes_use_efuse_key(aes_regs_t *aesx);
void ll_aes_use_software_key(aes_regs_t *aesx);
void ll_aes_enable_id_fusion(aes_regs_t *aesx);
void ll_aes_disable_id_fusion(aes_regs_t *aesx);
void ll_aes_set_efuse_key_mode(
    aes_regs_t *aesx,
    aes_ascr_efuse_key_mode_t mode);
void ll_aes_start_efuse_key_read(aes_regs_t *aesx);
void ll_aes_start_efuse_id_read(aes_regs_t *aesx);

这些 helper 只操作 ASCR.EKEY_*、ID_FUSION 和读启动位，不等待完成。

1.6 状态 helper

bool ll_aes_is_efuse_key_reset_done(const aes_regs_t *aesx);
bool ll_aes_is_efuse_key_read_done(const aes_regs_t *aesx);
bool ll_aes_is_efuse_id_read_done(const aes_regs_t *aesx);
bool ll_aes_is_cpu_done(const aes_regs_t *aesx);
bool ll_aes_is_dma_done(const aes_regs_t *aesx);

分别查询：

ASSR.EKEY_RSTD
ASSR.EKEY_RDD
ASSR.EID_RDD
ASSR.AESD
ASSR.DMAD

1.7 状态清除 helper

void ll_aes_clear_efuse_key_read_done(aes_regs_t *aesx);
void ll_aes_clear_efuse_id_read_done(aes_regs_t *aesx);
void ll_aes_clear_cpu_done(aes_regs_t *aesx);
void ll_aes_clear_dma_done(aes_regs_t *aesx);

ASSR 的这些状态位表现为 W1C/XOR 行为：

只有状态位已经为 1 时才允许写 1 清除。
面对一个为 0 的状态位写 1 会把它置 1。

因此 clean helper 必须在确认对应 status bit 为 1 后再调用，否则会制造假的 pending 状态。

1.8 中断使能 helper

void ll_aes_enable_cpu_done_irq(aes_regs_t *aesx);
void ll_aes_disable_cpu_done_irq(aes_regs_t *aesx);
void ll_aes_enable_dma_done_irq(aes_regs_t *aesx);
void ll_aes_disable_dma_done_irq(aes_regs_t *aesx);
void ll_aes_enable_efuse_key_read_done_irq(aes_regs_t *aesx);
void ll_aes_disable_efuse_key_read_done_irq(aes_regs_t *aesx);
void ll_aes_enable_efuse_id_read_done_irq(aes_regs_t *aesx);
void ll_aes_disable_efuse_id_read_done_irq(aes_regs_t *aesx);
uint32_t ll_aes_get_enabled_irq_status(const aes_regs_t *aesx);

ll_aes_get_enabled_irq_status() 返回 ASSR & ASINTEN。EKEY_RSTD 没有 ASINTEN 对应位，因此不会被该 helper 返回。

1.9 DMA 参数 helper

void ll_aes_set_source_addr(aes_regs_t *aesx, uint32_t addr);
uint32_t ll_aes_get_source_addr(const aes_regs_t *aesx);
void ll_aes_set_source_transfer_count(aes_regs_t *aesx, uint32_t words);
uint32_t ll_aes_get_source_transfer_count(const aes_regs_t *aesx);
void ll_aes_set_destination_addr(aes_regs_t *aesx, uint32_t addr);
uint32_t ll_aes_get_destination_addr(const aes_regs_t *aesx);
void ll_aes_set_destination_transfer_count(aes_regs_t *aesx, uint32_t words);
uint32_t ll_aes_get_destination_transfer_count(const aes_regs_t *aesx);
void ll_aes_set_block_count(aes_regs_t *aesx, uint32_t blocks);
uint32_t ll_aes_get_block_count(const aes_regs_t *aesx);

单位：

ASSTC / ASDTC：32-bit word
ASBNUM：128-bit AES block

地址写入必须先于对应 transfer count 写入。

1.10 FIFO helper

void ll_aes_write_data_input(aes_regs_t *aesx, uint32_t word);
uint32_t ll_aes_read_data_output(const aes_regs_t *aesx);
void ll_aes_write_key(aes_regs_t *aesx, uint32_t word);
void ll_aes_write_iv(aes_regs_t *aesx, uint32_t word);

ASDI、ASKY 和 ASIV 是 write-only FIFO；ASDO 是 read-only FIFO。读取 ASDO 可能推动 CPU output FIFO 状态，因此只能在实际读取结果时调用。

2. 寄存器映射与位域

2.1 寄存器表

Offset	寄存器	访问	用途
`0x000`	`ASCR`	RW	AES 控制、算法、key source、endian 和启动位。
`0x004`	`ASSR`	RW	完成状态；完成位写 1 清除。
`0x008`	`ASINTEN`	RW	AES/DMA/EFUSE 本地中断使能。
`0x00C`	`ASSA`	RW	DMA 源地址。
`0x010`	`ASSTC`	RW	DMA 源 transfer count，单位 word。
`0x014`	`ASDA`	RW	DMA 目标地址。
`0x018`	`ASDTC`	RW	DMA 目标 transfer count，单位 word。
`0x01C`	`ASBNUM`	RW	AES block count，单位 128-bit block。
`0x020`	`ASDI`	WO	CPU 输入 FIFO。
`0x024`	`ASDO`	RO	CPU 输出 FIFO。
`0x028`	`ASKY`	WO	key FIFO。
`0x02C`	`ASIV`	WO	CBC IV FIFO。

2.2 ASCR 关键字段

字段	bit	说明
`PS`	`[31:28]`	DMA page size。
`EKEY_CLR`	`20`	清除已加载/fuse 的 EFUSE key 和 chip-id 状态。
`EKEY_USE`	`19`	选择 EFUSE key。
`ID_FUSION`	`18`	启用 chip-id fusion。
`EKEY_MODE`	`[17:16]`	EFUSE key mode 0 到 3。
`EID_RD`	`15`	启动 EFUSE chip-id read。
`EKEY_RD`	`14`	启动 EFUSE key read。
`DOUT_ENDIAN`	`13`	输出 endian。
`DIN_ENDIAN`	`12`	输入 endian。
`CLR`	`10`	清除硬件 key、IV、input 和 output。
`DMAS`	`9`	DMA start。
`DMAE`	`8`	DMA mode enable。
`KEYL`	`[7:6]`	key length：0=AES-128，1=AES-192，2=AES-256。
`MODE`	`5`	0=ECB，1=CBC。
`DECE`	`4`	1=decrypt，0=encrypt。
`AESS`	`3`	CPU start。
`KEYS`	`2`	key expansion start。
`INIT_IV`	`1`	从 ASIV FIFO 初始化 CBC IV。
`EN`	`0`	AES enable。

2.3 ASSR 与 ASINTEN

状态	ASSR bit	ASINTEN bit	用途
`AESD`	0	0	CPU block done
`DMAD`	1	1	DMA segment done
`EKEY_RDD`	2	2	EFUSE user-key read done
`EID_RDD`	3	3	EFUSE chip-id read done
`EKEY_RSTD`	4	无	reset-loaded EFUSE state ready