API GUIDE / I2C / OVERVIEW

G32S10 I2C API 概述

模块概述：本文档定义 G32S10 SDK 当前 I2C 硬件接口，覆盖以下两层：

1. 文档范围

本文档定义 G32S10 SDK 当前 I2C 硬件接口，覆盖以下两层：

HAL I2C：面向 middleware、BSP 和硬件适配层的控制器接口
LL I2C：面向寄存器与位操作的低层接口

本文档基于以下实现与头文件编写：

code/include/drivers/g32s10/i2c/hal_i2c.h
code/include/drivers/g32s10/i2c/ll_i2c.h
code/include/drivers/g32s10/i2c/i2c_regs.h
code/drivers/g32s10/i2c/hal_i2c.c

补充说明：

设备驱动应使用 I2C middleware 的 device API；HAL 层负责控制器初始化、FIFO、IRQ service、从机 FIFO 读写和 DMA 请求配置。
LL 层公开接口均为 static inline，直接访问寄存器，不维护软件状态，不做完整业务语义判断。
I2C HAL 当前不使用 handle 结构体，公开接口通过 i2c_regs_t * 传递控制器实例。

2. 分层关系

APPLICATION Device driver 业务代码、板级支持与示例入口

↓

MIDDLEWARE I2C middleware bus/device 面向场景的公共能力与资源管理

↓

HAL HAL I2C 模块级配置、状态管理与硬件访问

↓

LL LL I2C 寄存器访问与字段级控制

↓

HARDWARE REGISTERS I2C Registers 实例地址、寄存器布局与位域定义

分层职责如下：

HAL I2C

封装 I2C 控制器初始化、反初始化、硬件传输推进、从机读写、中断 service 和 DMA 请求产生配置
维护每个控制器的软件状态、初始化参数快照、时序快照、DMA 配置和最近一次 TX abort 源
不注册 SoC IRQ；由 middleware 或平台 IRQ 入口调用 IRQ service

LL I2C

提供寄存器位级访问入口
不维护软件状态，不处理上层传输流程
调用方必须保证实例指针、参数范围和并发访问安全

i2c_regs.h

定义 I2C 实例、寄存器结构体、位域 mask、状态位和中断位

3. 资源模型与公开类型

3.1 模块基地址与实例

当前 HAL/LL 支持 3 个 I2C 控制器：

实例	基地址宏	基地址	有效寄存器偏移	说明
`I2C0`	`I2C0_IOBASE`	`0x100CA000`	`0x000-0x0A4`	I2C 控制器 0
`I2C1`	`I2C1_IOBASE`	`0x10010000`	`0x000-0x0A4`	I2C 控制器 1
`I2C2`	`I2C2_IOBASE`	`0x10011000`	`0x000-0x0A4`	I2C 控制器 2

i2c_regs.h 中提供如下实例宏：

#define I2C0  ((i2c_regs_t *)(uintptr_t)I2C0_IOBASE)
#define I2C1  ((i2c_regs_t *)(uintptr_t)I2C1_IOBASE)
#define I2C2  ((i2c_regs_t *)(uintptr_t)I2C2_IOBASE)

HAL 层通过 HAL_IS_I2C_INSTANCE(INSTANCE) 检查实例合法性，该宏映射到 ll_i2c_is_instance()。

I2C 寄存器块说明如下：

寄存器	RW	偏移	说明
`con`	RW	`0x000`	控制寄存器，配置 master/slave、速度、10 bit 地址和 restart
`tar`	RW	`0x004`	目标地址寄存器，配置主机访问目标地址和特殊命令
`sar`	RW	`0x008`	从机地址寄存器
`hs_maddr`	RW	`0x00C`	High-speed master code 地址寄存器
`data_cmd`	RW	`0x010`	TX/RX 数据命令寄存器，写入发送数据或读命令，读取接收数据
`ss_scl_hcnt` / `ss_scl_lcnt`	RW	`0x014` / `0x018`	标准模式 SCL high/low count
`fs_scl_hcnt` / `fs_scl_lcnt`	RW	`0x01C` / `0x020`	快速/快速增强模式 SCL high/low count
`hs_scl_hcnt` / `hs_scl_lcnt`	RW	`0x024` / `0x028`	高速模式 SCL high/low count
`intr_stat`	R	`0x02C`	中断 mask 后状态寄存器
`intr_mask`	RW	`0x030`	中断 mask 配置寄存器
`raw_intr_stat`	R	`0x034`	原始中断状态寄存器
`rx_tl` / `tx_tl`	RW	`0x038` / `0x03C`	RX/TX FIFO 中断阈值寄存器
`clr_intr`	R	`0x040`	组合中断读清寄存器
`clr_rx_under` / `clr_rx_over`	R	`0x044` / `0x048`	RX FIFO 下溢/上溢中断读清寄存器
`clr_tx_over`	R	`0x04C`	TX FIFO 上溢中断读清寄存器
`clr_rd_req`	R	`0x050`	从机读请求中断读清寄存器
`clr_tx_abrt`	R	`0x054`	TX abort 中断读清寄存器
`clr_rx_done`	R	`0x058`	从机 RX done 中断读清寄存器
`clr_activity`	R	`0x05C`	Activity 中断读清寄存器
`clr_stop_det` / `clr_start_det`	R	`0x060` / `0x064`	STOP/START 检测中断读清寄存器
`clr_gen_call`	R	`0x068`	General call 中断读清寄存器
`enable`	RW	`0x06C`	控制器使能和 master abort 控制寄存器
`status`	R	`0x070`	控制器状态寄存器，包含 activity 与 FIFO 状态
`txflr` / `rxflr`	R	`0x074` / `0x078`	TX/RX FIFO 当前水位寄存器
`sda_hold`	RW	`0x07C`	SDA hold 时间配置寄存器
`tx_abrt_source`	R	`0x080`	TX abort 原因寄存器
`reserved_0`	—	`0x084`	保留
`dma_cr`	RW	`0x088`	DMA 请求使能控制寄存器
`dma_tdlr` / `dma_rdlr`	RW	`0x08C` / `0x090`	DMA TX/RX 数据水位寄存器
`sda_setup`	RW	`0x094`	SDA setup 时间配置寄存器
`ack_general_call`	RW	`0x098`	General call ACK 使能寄存器
`enable_status`	R	`0x09C`	控制器使能状态寄存器
`fs_spklen` / `hs_spklen`	RW	`0x0A0` / `0x0A4`	标准/快速与高速模式 spike suppression 长度寄存器

3.2 I2C 硬件能力摘要

项目	说明
控制器实例	`I2C0`、`I2C1`、`I2C2`
FIFO 深度	TX FIFO 64 entry，RX FIFO 64 entry
地址模式	支持 7 bit 与 10 bit 地址
控制器角色	HAL 当前支持主机-only 与从机-only 两种配置
总线速度	标准模式、快速模式、快速增强模式、高速模式
主机传输	HAL 提供同步阻塞式 transmit、receive、write-read、probe、general call、START byte 和多消息传输；主机写路径使用 TX_EMPTY/TX_ABRT/STOP 中断推进和完成
从机访问	HAL 提供非阻塞 RX FIFO 读取、TX FIFO 写入和原始中断事件等待
中断	支持 RX/TX FIFO、读请求、TX abort、START/STOP、general call、activity 等事件
DMA	HAL 配置 I2C 控制器侧 TX/RX DMA 请求产生，不负责 DMA 通道搬运编排

3.3 HAL 返回状态约定

HAL 层可失败接口统一返回 SDK 公共错误码类型：

error_code_t

常用返回值如下：

返回值	说明
`IM_OK`	操作成功
`IM_ERR_INVALID_PARAM`	参数为空、实例非法、枚举非法、地址越界、mask 越界或配置范围非法
`IM_ERR_NOT_READY`	控制器未初始化、角色不匹配、FIFO 当前不可读写或控制器状态不允许当前操作
`IM_ERR_TIMEOUT`	等待 enable/disable、FIFO、总线空闲、传输完成或事件时超时
`IM_ERR_BUSY`	同一控制器已有 HAL 传输或重配置操作正在进行，或 TX abort 指示仲裁丢失/从机 TX flush 类状态
`IM_ERR_NOT_FOUND`	TX abort 指示目标地址、数据或 general call 未收到 ACK
`IM_ERR_UNSUPPORTED`	请求速率超过所选速度模式上限、根据输入时钟无法计算可支持的 SCL 计数，或 TX abort 指示不支持的命令序列
`IM_ERR_IO`	TX abort 指示用户 abort 或未归类的底层 I/O 失败

3.4 总线速度

typedef enum {
    HAL_I2C_SPEED_STANDARD = 0U,
    HAL_I2C_SPEED_FAST = 1U,
    HAL_I2C_SPEED_FAST_PLUS = 2U,
    HAL_I2C_SPEED_HIGH = 3U,
} hal_i2c_speed_t;

速度上限如下：

速度枚举	说明	最大 `bitrate_hz`
`HAL_I2C_SPEED_STANDARD`	标准模式	100000
`HAL_I2C_SPEED_FAST`	快速模式	400000
`HAL_I2C_SPEED_FAST_PLUS`	快速增强模式	1000000
`HAL_I2C_SPEED_HIGH`	高速模式	3400000

说明：

HAL 会根据 input_clock_hz 和 bitrate_hz 自动计算 SCL high/low count。
HAL_I2C_SPEED_FAST_PLUS 在寄存器 CON.SPEED 中与 fast mode 使用同一个硬件编码。
当请求速率超过所选速度模式上限时，hal_i2c_init() 返回 IM_ERR_UNSUPPORTED。

4. 关键行为约束

4.1 主机传输约束

主机传输接口只支持已初始化且角色为 HAL_I2C_ROLE_MASTER 的控制器。
HAL 主机路径通过 hal_i2c_master_transfer_start() 启动，并以 hal_i2c_master_callback_register() 注册的 IRQ 回调报告终态；同步等待、事务超时和恢复由 I2C middleware 实现。
同一控制器同时只能执行一个 HAL 主机传输、特殊主机命令、速率重配置或 DMA 配置操作；冲突时返回 IM_ERR_BUSY。
hal_i2c_master_transfer_abort() 是 middleware 的恢复接口，可在 IRQ-driven 主机传输进行中请求硬件 abort。
发生 TX abort 时，传输接口按 abort 源返回 IM_ERR_NOT_FOUND、IM_ERR_BUSY、IM_ERR_UNSUPPORTED、IM_ERR_IO 或 IM_ERR_NOT_READY，调用方可读取 last_tx_abort_source 诊断精确原因。

4.2 并发约束

HAL 当前按控制器维护全局软件状态，并对主机传输、特殊主机命令、速率重配置、DMA 配置和反初始化做轻量 busy 保护。
IRQ 回调注册、中断 mask 和中断清除接口不提供跨上下文互斥；调用方仍应按 IRQ 上下文规则组织访问顺序。
LL 层直接访问寄存器，不保证可重入；调用方必须自行处理并发和中断上下文访问顺序。