G32S10 RSA HAL 接口

1. 资源与公开类型

1.1 实例与构建开关

#define RSA ((rsa_regs_t *)(uintptr_t)SC_RSA_IOBASE)

1.2 尺寸与范围

1.3 HAL 配置

typedef struct {
    rsa_regs_t *instance;
} hal_rsa_config_t;

当前只接受 RSA 实例。

1.4 模幂配置

typedef struct {
    const uint32_t *message_words;
    const uint32_t *exponent_words;
    const uint32_t *modulus_words;
    uint32_t n_bits;
    uint32_t message_word_count;
    uint32_t exponent_word_count;
    uint32_t modulus_word_count;
} hal_rsa_modexp_config_t;

hal_rsa_configure_it() 在返回前消费全部输入数组，不保留输入指针。

1.5 HAL 状态与 phase

typedef struct hal_rsa_handle hal_rsa_handle_t;

typedef enum {
    HAL_RSA_STATE_RESET = 0,
    HAL_RSA_STATE_READY,
    HAL_RSA_STATE_BUSY,
    HAL_RSA_STATE_ERROR,
} hal_rsa_state_t;

typedef enum {
    HAL_RSA_PHASE_IDLE = 0,
    HAL_RSA_PHASE_N_CONFIG,
    HAL_RSA_PHASE_OPERATION,
    HAL_RSA_PHASE_DONE,
} hal_rsa_phase_t;

调用方必须将 hal_rsa_handle_t 零初始化，初始化后不得直接修改 HAL 字段。

1.6 callback

typedef enum {
    HAL_RSA_CALLBACK_N_CFG_DONE = 0,
    HAL_RSA_CALLBACK_COMPLETE,
    HAL_RSA_CALLBACK_ERROR,
    HAL_RSA_CALLBACK_COUNT,
} hal_rsa_callback_type_t;

typedef void (*hal_rsa_callback_t)(hal_rsa_handle_t *handle,
                                   void *user_data);

callback 从 hal_rsa_irq_handler() 调用，不能阻塞、等待、调用 hal_rsa_operation_start() 或读取 result FIFO。

2. HAL 接口

2.1 hal_rsa_init

error_code_t hal_rsa_init(hal_rsa_handle_t *handle,
                          const hal_rsa_config_t *config);

初始化 caller-owned handle，打开 HAL_CPM_ID_GATE_RSA，关闭全部本地中断并清理状态。

返回：

2.2 callback 与 user data

error_code_t hal_rsa_callback_register(
    hal_rsa_handle_t *handle,
    hal_rsa_callback_type_t type,
    hal_rsa_callback_t callback);

error_code_t hal_rsa_user_data_set(
    hal_rsa_handle_t *handle,
    void *user_data);

callback = NULL 表示注销。callback 与 user data 会被所有三个事件共用。

2.3 hal_rsa_configure_it

error_code_t hal_rsa_configure_it(
    hal_rsa_handle_t *handle,
    const hal_rsa_modexp_config_t *modexp);

启动模数配置阶段：

1. 校验 M/E/N 和长度。

2. 清空 RSAC 和控制状态。

3. 关闭全部 RSA 中断。

4. 清除全部 RSAINFO 状态。

5. 打开 N_CFG_DONE 和 error local interrupts。

6. 写 RSAC.N_LEN。

7. 将 message 和 exponent 前置零扩展到 128 words 后写入 FIFO。

8. 写入 modulus 的 n_words 个 words。

成功后状态为 BUSY / N_CONFIG。返回 IM_OK 只表示输入已提交，不表示 N 配置完成。

错误：

• IM_ERR_INVALID_PARAM：配置、长度、指针、exponent 全 0 或 modulus 非奇数

• IM_ERR_NOT_READY：handle 未初始化或不在 READY

2.4 hal_rsa_irq_handler

void hal_rsa_irq_handler(hal_rsa_handle_t *handle);

该函数由持有 IRQ_RSA 的 SoC IRQ entry 调用。

处理规则：

• PRD_OFW 是 warning，不改变最终模幂结果；HAL 清除后继续。

• RD_UFW、WR_OFW、N_EVEN 是 error，进入 ERROR 并调用 error callback。

• N_CONFIG phase 收到 N_CFG_DONE：清除 N_CFG，调用 N_CFG callback，状态仍为 BUSY。

• OPERATION phase 收到仅 N_CFG_DONE：清除后继续等待，不视为失败。

• OPERATION phase 收到 INT_DONE：清除 INT，进入 DONE，调用 complete callback。

2.5 hal_rsa_operation_start

error_code_t hal_rsa_operation_start(hal_rsa_handle_t *handle);

必须在 N_CFG_DONE callback 之后由任务上下文调用：

• 要求 BUSY / N_CONFIG

• 关闭 N_CFG local interrupt

• 打开 INT_DONE 和 error local interrupts

• 置位 RSAC.EN

• phase 进入 OPERATION

不得从 IRQ callback 中调用。

2.6 hal_rsa_result_read

error_code_t hal_rsa_result_read(
    hal_rsa_handle_t *handle,
    uint32_t *output_words,
    uint32_t output_word_count);

必须在 COMPLETE callback 后调用：

• 要求 BUSY / DONE

• output_word_count >= n_bits / 32

• 从 RSAP 读取 n_words

• 转换回 HAL 边界的 MSW-first 顺序

• 成功后进入 READY / IDLE

2.7 hal_rsa_abort

error_code_t hal_rsa_abort(hal_rsa_handle_t *handle);

关闭 RSA 中断，触发软件复位并轮询 RSARSTN.RSTN。成功清除状态并回到 READY / IDLE。

失败条件：

• software reset 超时

• systick 未初始化且内部 reset timeout 需要时间基准

不得在 IRQ 上下文调用。

2.8 hal_rsa_deinit

error_code_t hal_rsa_deinit(hal_rsa_handle_t *handle);

关闭本地中断，清除状态，释放 CPM gate 并清理 handle。若 handle 处于 BUSY 或 ERROR，先执行内部 software reset。该接口不释放 SoC IRQ。

2.9 hal_rsa_regs_dump

error_code_t hal_rsa_regs_dump(const hal_rsa_handle_t *handle);

仅当以下条件同时成立时提供 dump：

CONFIG_SDK_ENABLE_DEBUG_HELPERS=y
CONFIG_RSA_ENABLE_DEBUG_HELPERS=y

否则返回 IM_ERR_UNSUPPORTED。FIFO 寄存器显示为 skipped。

3. HAL 操作流程

READY / IDLE
  -> hal_rsa_configure_it()
  -> BUSY / N_CONFIG
  -> IRQ: N_CFG_DONE
  -> callback N_CFG_DONE
  -> task: hal_rsa_operation_start()
  -> BUSY / OPERATION
  -> IRQ: INT_DONE
  -> callback COMPLETE
  -> BUSY / DONE
  -> task: hal_rsa_result_read()
  -> READY / IDLE

一次 handle 只能有一个活动模幂操作。多次运算应串行执行。

4. 数据格式

4.1 HAL word 顺序

message、exponent、modulus 和 result 在 HAL API 边界都是 MSW-first。