G32S10 I2C HAL 接口

1. 资源模型与公开类型

1.1 HAL 公开宏

1.2 控制器角色

typedef enum {
    HAL_I2C_ROLE_MASTER = 0U,
    HAL_I2C_ROLE_SLAVE = 1U,
} hal_i2c_role_t;

说明：

• HAL_I2C_ROLE_MASTER 配置控制器为主机模式，并禁用从机功能。

• HAL_I2C_ROLE_SLAVE 配置控制器为从机模式，并关闭 master mode 位。

• 主机传输接口要求控制器已初始化为 HAL_I2C_ROLE_MASTER。

• 从机读写和从机事件等待接口要求控制器已初始化为 HAL_I2C_ROLE_SLAVE。

1.3 地址模式

typedef enum {
    HAL_I2C_ADDRESS_MODE_7BIT = 0U,
    HAL_I2C_ADDRESS_MODE_10BIT = 1U,
} hal_i2c_address_mode_t;

地址范围约束：

1.4 主机消息方向和标志

typedef enum {
    HAL_I2C_DIRECTION_WRITE = 0U,
    HAL_I2C_DIRECTION_READ = 1U,
} hal_i2c_direction_t;

消息标志如下：

1.5 中断事件

hal_i2c_irq_event_t 直接复用 I2C 中断寄存器 bit 定义：

说明：

• hal_i2c_irq_handler() 自动清除除 RD_REQ 以外的已处理事件。

• RD_REQ 需要由从机写入数据后通过 hal_i2c_slave_write() 或 hal_i2c_clear_irq() 清除。

• TX abort 发生时，HAL 会锁存 tx_abrt_source 到 last_tx_abort_source。

1.6 公开结构体

1.6.1 hal_i2c_target_t

I2C 主机目标参数：

1.6.2 hal_i2c_msg_t

I2C 主机传输消息参数：

说明：

• 写消息要求 write_data != NULL，除非 data_len == 0。

• 读消息要求 read_data != NULL，除非 data_len == 0。

• flags 不能包含 HAL_I2C_MSG_FLAG_ALL 以外的位。

1.6.3 hal_i2c_dma_config_t

I2C DMA 请求产生配置：

1.6.4 hal_i2c_timing_state_t

HAL 已编程的当前生效 I2C 时序快照：

1.6.5 hal_i2c_init_t

I2C 初始化参数：

1.6.6 hal_i2c_status_t

I2C 控制器运行状态快照：

1.6.7 hal_i2c_irq_callback_t

typedef void (*hal_i2c_irq_callback_t)(i2c_regs_t *i2cx,
                                       uint32_t event_mask,
                                       void *user_ctx);

说明：

• i2cx 为触发事件的 I2C 控制器。

• event_mask 使用 HAL_I2C_IRQ_EVENT_* 位。

• user_ctx 为注册回调时传入的调用者上下文。

• 回调运行在 I2C IRQ 上下文中，不能阻塞、休眠、等待锁或执行大量日志输出。

2. HAL 接口规范

2.1 实例查询、初始化与生命周期

2.1.1 hal_i2c_get_instance_by_id

error_code_t hal_i2c_get_instance_by_id(uint32_t instance_id,
                                        i2c_regs_t **i2cx_out,
                                        const char **name_out);

功能说明： 根据从 0 开始的控制器 ID 查询 I2C 寄存器实例和稳定名称，避免调用层重复维护控制器映射表。

参数表：

返回值表：

2.1.2 hal_i2c_struct_init

void hal_i2c_struct_init(hal_i2c_init_t *i2c_init);

功能说明： 将 hal_i2c_init_t 填充为 SDK 默认值，用于后续按需覆写。

参数表：

返回值表：

默认值如下：

2.1.3 hal_i2c_init

error_code_t hal_i2c_init(const hal_i2c_init_t *i2c_init);

功能说明： 根据初始化参数初始化一个 I2C 控制器。

参数表：

返回值表：

补充说明：

• 调用前必须设置 i2cx 和 input_clock_hz。

• 接口会使能对应 I2C 时钟门控、配置寄存器、使能控制器并注册 SoC IRQ。

• 初始化时会清空中断 mask，清除已挂起中断，并重置 HAL 跟踪的 TX abort 源和用户回调。

• tx_threshold 允许 0 到 64，rx_threshold 允许 0 到 63。

• fs_spike_length 和 hs_spike_length 不能为 0。

2.1.4 hal_i2c_deinit

error_code_t hal_i2c_deinit(i2c_regs_t *i2cx);

功能说明： 反初始化一个 I2C 控制器。

参数表：

返回值表：

补充说明：

• 接口会 mask 全部 I2C 中断、注销 SoC IRQ、disable 控制器并清除中断。

• 当前实现会忽略 SoC IRQ 注销返回的 IM_ERR_NOT_READY，其他 IRQ 注销错误会向上传递。

• 成功后 HAL 软件状态变为未初始化，并清除已注册用户回调。

2.2 状态与诊断

2.2.1 hal_i2c_is_bus_busy

error_code_t hal_i2c_is_bus_busy(const i2c_regs_t *i2cx, bool *is_busy_out);

功能说明： 读取控制器 STATUS.ACTIVITY，判断总线是否忙。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

2.2.2 hal_i2c_get_status

error_code_t hal_i2c_get_status(const i2c_regs_t *i2cx,
                                hal_i2c_status_t *status_out);

功能说明： 读取一个 I2C 控制器运行状态快照。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

补充说明：该接口可在控制器未初始化时调用，此时返回 HAL 当前保存的软件状态和硬件寄存器快照。

2.2.3 hal_i2c_get_timing

error_code_t hal_i2c_get_timing(const i2c_regs_t *i2cx,
                                hal_i2c_timing_state_t *timing_out);

功能说明： 读取 HAL 为一个控制器编程的时序快照。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

补充说明：该接口读取 HAL 保存的时序快照；控制器未初始化时返回该实例当前保存值。

2.2.4 hal_i2c_get_tx_abort_source

error_code_t hal_i2c_get_tx_abort_source(const i2c_regs_t *i2cx,
                                         uint32_t *abort_source_out);

功能说明： 读取最近一次锁存的 TX abort 源位掩码。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

• HAL 在主机传输过程中检测到 TX_ABRT 时更新该值。

• HAL 在 hal_i2c_irq_handler() 观察到 TX abort 中断时也会更新该值。

• 该接口读取 HAL 保存的最近一次 TX abort 源；控制器未初始化时返回该实例当前保存值。

2.2.5 hal_i2c_dump_regs

void hal_i2c_dump_regs(const i2c_regs_t *i2cx);

功能说明： 将指定 I2C 控制器的主要寄存器原始值输出到日志，用于 bring-up、异常定位和现场状态确认。

返回值：无。

补充说明：

• 该接口始终声明并实现，但只有同时使能 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_I2C_ENABLE_DEBUG_HELPERS 时才会输出寄存器内容；未使能时为 no-op。

• i2cx 必须为 I2C0、I2C1 或 I2C2，非法实例会输出错误日志后返回。

• dump 内容包括 CON、TAR、SAR、SCL count、interrupt status/mask、FIFO level、DMA control/level、SDA timing、spike length 等主要寄存器。

• DATA_CMD 和 CLR_* 寄存器不会被读取：读取 DATA_CMD 可能消费 RX FIFO 数据，读取 CLR_* 寄存器会清除挂起中断状态。

2.3 主机硬件传输接口

HAL 不提供同步 transaction 或 probe API。设备驱动通过 I2C middleware 的im_i2c_device_transfer() 和 im_i2c_device_probe() 访问 7-bit 目标。 HAL 仅为 middleware 提供 callback 注册、非阻塞启动和 abort：

error_code_t hal_i2c_master_callback_register(i2c_regs_t *i2cx,
                                               hal_i2c_master_callback_t callback,
                                               void *user_ctx);
error_code_t hal_i2c_master_transfer_start(i2c_regs_t *i2cx,
                                           const hal_i2c_target_t *target,
                                           const hal_i2c_msg_t *msgs,
                                           size_t msg_count);
error_code_t hal_i2c_master_transfer_abort(i2c_regs_t *i2cx,
                                           uint32_t timeout_ms);

hal_i2c_master_transfer_start() 只启动硬件并在 IRQ 中推进 FIFO；它不等待 transaction 完成。终态通过已注册的 callback 报告。middleware 负责等待、 总超时、NACK 返回和超时后的 abort 恢复。

2.4 从机接口

2.4.1 hal_i2c_slave_read

error_code_t hal_i2c_slave_read(i2c_regs_t *i2cx,
                                uint8_t *data_out,
                                size_t data_len,
                                size_t *read_len_out);

功能说明： 读取从机 RX FIFO 中当前可用的字节。

参数表：

返回值表：

补充说明：本接口不阻塞。

2.4.2 hal_i2c_slave_write

error_code_t hal_i2c_slave_write(i2c_regs_t *i2cx,
                                 const uint8_t *data,
                                 size_t data_len,
                                 size_t *written_len_out);

功能说明： 向从机 TX FIFO 写入字节，用于响应主机读请求。

参数表：

返回值表：

补充说明：

• 本接口不阻塞。

• 写入完成后会清除 RD_REQ 中断。

2.4.3 hal_i2c_slave_wait_event

error_code_t hal_i2c_slave_wait_event(i2c_regs_t *i2cx,
                                      uint32_t event_mask,
                                      uint32_t *event_mask_out,
                                      uint32_t timeout_ms);

功能说明： 在从机模式下等待选定的原始中断事件。

参数表：

返回值表：

补充说明：

• event_mask 必须至少包含一个 HAL_I2C_IRQ_EVENT_* 有效位，且不能包含 HAL_I2C_IRQ_EVENT_ALL 以外的位。

• 超时时 *event_mask_out 被置为 0。

2.5 中断接口

2.5.1 hal_i2c_register_irq_callback

error_code_t hal_i2c_register_irq_callback(i2c_regs_t *i2cx,
                                           hal_i2c_irq_callback_t callback,
                                           void *user_ctx);

功能说明： 注册或注销一个 I2C 中断回调。

返回值：IM_OK、IM_ERR_INVALID_PARAM 或 IM_ERR_NOT_READY。

2.5.2 hal_i2c_enable_irq

error_code_t hal_i2c_enable_irq(i2c_regs_t *i2cx, uint32_t event_mask);

功能说明： 使能选定的 I2C 中断事件。

返回值：IM_OK、IM_ERR_INVALID_PARAM 或 IM_ERR_NOT_READY。

补充说明：event_mask 必须非 0，且不能包含 HAL_I2C_IRQ_EVENT_ALL 以外的位。

2.5.3 hal_i2c_disable_irq

error_code_t hal_i2c_disable_irq(i2c_regs_t *i2cx, uint32_t event_mask);

功能说明： 禁用选定的 I2C 中断事件。

参数和返回值同 hal_i2c_enable_irq()。

2.5.4 hal_i2c_get_pending_irq

error_code_t hal_i2c_get_pending_irq(const i2c_regs_t *i2cx,
                                     uint32_t *masked_event_mask_out,
                                     uint32_t *raw_event_mask_out);

功能说明： 读取屏蔽后和原始挂起的 I2C 中断事件位掩码。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

2.5.5 hal_i2c_clear_irq

error_code_t hal_i2c_clear_irq(i2c_regs_t *i2cx, uint32_t event_mask);

功能说明： 清除选定的 I2C 中断事件。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

补充说明：

• 硬件清除寄存器遵循读清语义。

• 当前实现会按事件分别读取对应 clear 寄存器。

• RX_FULL、TX_EMPTY 和 MST_HOLD 没有独立 clear 寄存器，传入这些位不会产生额外读清动作；调用方应通过 FIFO 状态变化、继续传输或中断 mask 处理。

2.5.6 hal_i2c_irq_handler

void hal_i2c_irq_handler(i2c_regs_t *i2cx);

功能说明： 处理一个 I2C 控制器的中断源，并调用已注册用户回调。

返回值：无。

补充说明：

• 该入口由 middleware、平台 IRQ 入口或应用在已注册 SoC IRQ 后调用；HAL 不绑定 SoC IRQ。

• 非法实例、未初始化实例或无挂起中断时直接返回。

• 若中断包含 TX abort，会先锁存 tx_abrt_source。

• 回调执行后自动清除除 RD_REQ 以外的已处理事件。

• 若 RX_FULL、TX_EMPTY 或 MST_HOLD 等电平型事件在回调返回后仍然成立，HAL 会临时 mask 对应事件；调用方处理 FIFO 或阈值条件后，可再次调用 hal_i2c_enable_irq() 重新使能。

2.6 DMA 辅助接口

2.6.1 hal_i2c_configure_dma

error_code_t hal_i2c_configure_dma(i2c_regs_t *i2cx,
                                   const hal_i2c_dma_config_t *dma_config);

功能说明： 配置 I2C 控制器侧 DMA 请求产生。

返回值：IM_OK、IM_ERR_INVALID_PARAM 或 IM_ERR_NOT_READY。

补充说明：

• tx_data_level 和 rx_data_level 必须小于 HAL_I2C_FIFO_DEPTH。

• 本接口只配置 I2C 侧 DMA_CR、DMA_TDLR 和 DMA_RDLR，不启动 DMA 控制器。

2.6.2 hal_i2c_get_dma_config

error_code_t hal_i2c_get_dma_config(const i2c_regs_t *i2cx,
                                    hal_i2c_dma_config_t *dma_config_out);

功能说明： 读取 HAL 跟踪的 I2C DMA 请求配置。

返回值：IM_OK、IM_ERR_INVALID_PARAM 或 IM_ERR_NOT_READY。

2.6.3 hal_i2c_get_data_register_address

error_code_t hal_i2c_get_data_register_address(const i2c_regs_t *i2cx,
                                               uintptr_t *address_out);

功能说明： 读取用于 DMA 配置的 I2C DATA_CMD 寄存器地址。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

3. 关键行为约束

3.1 初始化约束

• hal_i2c_init() 要求 i2c_init != NULL，i2cx 必须是 I2C0、I2C1 或 I2C2。

• role、address_mode 和 speed 必须为公开枚举值。

• input_clock_hz 和 bitrate_hz 必须非 0。

• bitrate_hz 不得超过所选 speed 的最大速率。

• 从机地址根据 address_mode 按 7 bit 或 10 bit 范围校验。

• DMA TX/RX 阈值必须小于 HAL_I2C_FIFO_DEPTH。

3.2 从机访问约束

• 从机接口只支持已初始化且角色为 HAL_I2C_ROLE_SLAVE 的控制器。

• hal_i2c_slave_read() 和 hal_i2c_slave_write() 均为非阻塞接口。

• hal_i2c_slave_write() 写完后会清除 RD_REQ，适合作为读请求回调或轮询事件后的响应动作。

3.3 中断约束

• 用户回调在 IRQ 上下文中执行，应保持短小，不应阻塞。

• event_mask 必须只包含 HAL_I2C_IRQ_EVENT_* 支持位。

• HAL 中断入口会自动清除除 RD_REQ 以外的事件；RD_REQ 通常由从机写数据路径清除。

• RX_FULL、TX_EMPTY 和 MST_HOLD 属于状态型/条件型事件，hal_i2c_clear_irq() 不会通过独立 clear 寄存器清除这些事件。

3.4 调试 dump 约束

• hal_i2c_dump_regs() 面向调试场景，不改变 HAL 软件状态。

• dump API 受 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_I2C_ENABLE_DEBUG_HELPERS 双开关控制。

• dump API 不读取 DATA_CMD 与 CLR_* 寄存器，避免读操作产生 RX FIFO 消费或中断清除副作用。

• dump 输出的是调用时刻硬件寄存器原始值；部分状态寄存器可能随硬件状态机变化，调用方应结合传输阶段和中断处理顺序判断。