API GUIDE / RSA / Middleware

G32S10 RSA Middleware 接口

Middleware 层接口：应用包含：

1. 构建配置与文件组织

1.1 文件职责

文件	说明
`include/im_rsa.h`	公开宏、类型、设备对象和 4 个 API
`src/im_rsa.c`	参数校验、字节/word 转换、IRQ、waiter 和恢复
`Kconfig`	RSA MID 编译选项
`CMakeLists.txt`	在 `CONFIG_MIDDLEWARE_RSA=y` 时编译 MID
`example/main/main.c`	96/1024/2048/4096-bit 模幂向量测试

应用包含：

#include "im_rsa.h"

2. 资源模型与公开宏

2.1 内存与数据所有权

MID 不动态分配输入、输出、模数、指数或临时 word 数组。中间 word 数组位于调用方持有的 im_rsa_t 对象中。

请求中的 key、input 和 output 在整个 im_rsa_modexp() 调用期间必须有效。output 只在函数返回 IM_OK 时表示完整结果。

2.2 中断所有权

im_rsa_config_t.irq_id 必须等于 IRQ_RSA。MID 拥有该中断，应用不得同时注册自己的 RSA IRQ handler。

3. 公开类型

3.1 `im_rsa_t`

typedef struct im_rsa im_rsa_t;

调用方持有的 RSA 设备对象。第一次 im_rsa_init() 前必须零初始化，之后保持地址不变。应用不得读取或修改对象字段，也不得复制活动对象。

3.2 `im_rsa_state_t`

typedef enum {
    IM_RSA_STATE_RESET = 0,
    IM_RSA_STATE_READY,
    IM_RSA_STATE_BUSY,
    IM_RSA_STATE_TIMEOUT,
    IM_RSA_STATE_ERROR,
} im_rsa_state_t;

状态	说明
`RESET`	未初始化或已 deinit。
`READY`	可以提交一次模幂请求。
`BUSY`	请求阶段正在等待 RSA IRQ。
`TIMEOUT`	正在执行超时恢复。
`ERROR`	恢复失败；只允许调用 `im_rsa_deinit()`。

MID 不提供公开状态查询 API。

3.3 `im_rsa_key_t`

typedef struct {
    const uint8_t *modulus;
    size_t modulus_size;
    uint32_t modulus_bits;
    const uint8_t *exponent;
    size_t exponent_size;
} im_rsa_key_t;

字段	约束
`modulus`	非 NULL，unsigned big-endian
`modulus_size`	必须等于 `modulus_bits / 8`
`modulus_bits`	96 到 4096，32 的整数倍
`exponent`	非 NULL，unsigned big-endian，且内容非全 0
`exponent_size`	1 到 `modulus_size`

modulus 必须为奇数。

3.4 `im_rsa_modexp_request_t`

typedef struct {
    const im_rsa_key_t *key;
    const uint8_t *input;
    size_t input_size;
    uint8_t *output;
    size_t output_size;
} im_rsa_modexp_request_t;

字段	约束
`key`	非 NULL，指向有效 `im_rsa_key_t`
`input`	unsigned big-endian；`input_size == 0` 时允许 NULL
`input_size`	0 到 `modulus_size`
`output`	非 NULL，unsigned big-endian 输出
`output_size`	至少为 `modulus_size`

输入短于模数时，MID 在左侧补零。输入值必须严格小于 N。

输出按完整模数宽度写入，较短结果在高位补零，便于调用方直接按modulus_size 字节比较。

4. RSA MID 设备生命周期

STATE RESET

→

STATE READY

→

STATE WAITING

→

STATE ERROR

RESET → READY · config_struct_init → init 成功

READY → WAITING · im_rsa_modexp()

WAITING → READY · N 配置、模幂和结果读取完成

WAITING → ERROR · abort 失败

READY / ERROR → RESET · im_rsa_deinit()

成功或超时恢复成功后回到 READY。abort 失败进入 ERROR。

5. 接口规范

5.1 `im_rsa_config_struct_init()`

void im_rsa_config_struct_init(im_rsa_config_t *config);

清零配置并设置默认 IRQ 名称。传 NULL 无效果。

5.2 `im_rsa_init()`

error_code_t im_rsa_init(im_rsa_t *dev, const im_rsa_config_t *config);

执行：

校验设备和配置非 NULL。
要求设备状态为 RESET。
保存配置，初始化两个内部 waiter。
初始化 RSA HAL。
注册 N_CFG_DONE、COMPLETE 和 ERROR HAL callbacks。
注册并使能 IRQ_RSA。
进入 READY。

关键返回码：

返回值	条件
`IM_OK`	初始化成功。
`IM_ERR_INVALID_PARAM`	空指针或 IRQ/HAL 配置非法。
`IM_ERR_BUSY`	设备不在 RESET。
其它	HAL 或 IRQ 初始化错误。

5.3 `im_rsa_modexp()`

error_code_t im_rsa_modexp(im_rsa_t *dev,
                           const im_rsa_modexp_request_t *request,
                           uint32_t timeout_ms);

同步计算：

output = input ^ exponent mod modulus

操作流程：

校验请求和操作数。
将 big-endian 字节转换为 HAL 的 MSW-first word 数组。
配置 RSA N、E 和模数位数。
等待 N_CFG_DONE。
启动模幂运算并等待完成 IRQ。
从结果 FIFO 读取 word。
转换为 big-endian 字节写入 output。
回到 READY。

timeout_ms 用于每个等待阶段。取 0 时使用第 8.2 节的自动超时。

5.4 `im_rsa_deinit()`

error_code_t im_rsa_deinit(im_rsa_t *dev);

关闭并释放 IRQ_RSA，必要时 abort BUSY/TIMEOUT/ERROR 状态下的硬件操作，反初始化 HAL，清理活动请求上下文。当前实现无论清理过程中是否发生错误，最后都会把设备状态置为 RESET，并返回遇到的第一个清理错误。

函数返回清理过程中遇到的第一个错误。

6. 错误处理与并发约束

6.1 常见错误码

错误码	典型原因
`IM_ERR_INVALID_PARAM`	N/E/M 指针、长度、位宽、奇偶性或范围非法
`IM_ERR_NOT_READY`	设备尚未初始化
`IM_ERR_BUSY`	上一请求仍处于 BUSY
`IM_ERR_TIMEOUT`	N 配置或模幂阶段等待超时
`IM_ERR_HARDWARE`	HAL 错误回调或 ERROR 状态请求

6.2 上下文和并发

im_rsa_init()、im_rsa_modexp() 和 im_rsa_deinit() 必须在任务上下文调用。
不可从 IRQ 调用。
同一个 im_rsa_t 同一时刻只能执行一个请求。
init/deinit 不得与 modexp 并发。
一个 IRQ_RSA 只能由一个 MID 对象拥有。