RK3576开发板I2C驱动实战教程，触觉智能开发板实操教学，HYM8563 RTC时钟芯片为例

起始条件(S) → 7位从机地址 → R/W位 → ACK → 8位数据 → ACK → 停止条件(P)

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ S │A6 │A5 │A4 │A3 │A2 │A1 │A0 │R/W│ACK│D7 │D6 │D5 │D4 │D3 │D2 │D1 │D0 │ P │
│ ↓ │◄──────── 从机地址7bit ────────►│   │◄──────── 数据8bit────────────►│ ↑ │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
  S     ▲──── SCL 时钟采样 SDA ────▲                                     P
起始          每个时钟1位数据          停止
条件                                   条件

7'h51 (HYM8563) → 左移1位 → 0xA2 (写) / 0xA3 (读)
   bit:  6   5   4   3   2   1   0   R/W
        1   0   1   0   0   0   1   0/1
        └──────── 0xA2 (写) / 0xA3 (读)

BCD 编码示例：时间 12:34:56
  秒(0x56) = 0101 0110 → 高4位(5) + 低4位(6) = 56 秒
  分(0x34) = 0011 0100 → 高4位(3) + 低4位(4) = 34 分
  时(0x12) = 0001 0010 → 高4位(1) + 低4位(2) = 12 时
驱动中的 BCD 转换函数（定义在 linux/bcd.h）:
  bcd2bin(0x56) = 5*10 + 6 = 56          // BCD → 整数
  bin2bcd(34)   = (3<<4) | 4 = 0x34       // 整数 → BCD

/* I2C2 - 挂载 HYM8563 RTC */
&i2c2 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&i2c2m0_xfer>;
    hym8563: hym8563@51 {
        compatible = "haoyu,hym8563";       // 驱动匹配的关键字符串
        reg = <0x51>;                       // I2C 7 位从机地址 (7'h51)
        #clock-cells = <0>;                 // 可作为时钟提供者
        clock-frequency = <32768>;          // CLKOUT 输出频率
        clock-output-names = "hym8563";     // 时钟输出名称
        interrupt-parent = <&gpio0>;        // 中断控制器
        interrupts = <RK_PC5 IRQ_TYPE_LEVEL_LOW>;  // 中断引脚与触发方式
        wakeup-source;                      // 支持系统唤醒
    };
};

&pinctrl {
    i2c2 {
        /* I2C2 M0 组：SCL = GPIO1_B4, SDA = GPIO1_B3 */
        i2c2m0_xfer: i2c2m0-xfer {
            rockchip,pins =
                <1 RK_PB4 9 &pcfg_pull_none>,   /* i2c2_scl_m0 */
                <1 RK_PB3 9 &pcfg_pull_none>;   /* i2c2_sda_m0 */
        };
        /* I2C2 M1 组：备用引脚（如需要） */
        i2c2m1_xfer: i2c2m1-xfer {
            rockchip,pins =
                <1 RK_PB4 10 &pcfg_pull_none>,  /* i2c2_scl_m1 */
                <1 RK_PB3 10 &pcfg_pull_none>;  /* i2c2_sda_m1 */
        };
    };
};

# 查看 GPIO1_B3 (I2C2_SDA) 当前功能
cat /sys/kernel/debug/pinctrl/pinctrl-handles | grep i2c2
# 或者检查 pinctrl 设置
cat /sys/kernel/debug/gpio | grep i2c

// Kconfig
config RTC_DRV_HYM8563
    tristate "Haoyu Microelectronics HYM8563"
    depends on OF
    help
      Say Y to enable support for the HYM8563 I2C RTC chip.
// Makefile
obj-$(CONFIG_RTC_DRV_HYM8563)   += rtc-hym8563.o

struct hym8563 {
    struct i2c_client   *client;         // I2C 客户端（关联设备和适配器）
    struct rtc_device   *rtc;            // RTC 核心框架设备
#ifdef CONFIG_COMMON_CLK
    struct clk_hw       clkout_hw;       // CLKOUT 时钟提供者
#endif
    int alarm_or_timer_irq;             // 0=闹钟模式, 1=定时器模式
    int alarm_tm_sec;                    // 闹钟秒数（定时器模式用）
};

static int hym8563_rtc_read_time(struct device *dev, struct rtc_time *tm)
{
    struct i2c_client *client = to_i2c_client(dev);
    u8 buf[7];
    int ret;
    // ---- I2C 通信：一次读取 7 个时间寄存器 (SEC ~ YEAR) ----
    // SMBus 协议：发送寄存器地址 0x02 → 连续读取 7 个字节
    ret = i2c_smbus_read_i2c_block_data(client, HYM8563_SEC, 7, buf);
    if (ret < 0)
        return ret;
    // ---- BCD 解码：将 BCD 格式转为内核 tm 结构体 ----
    tm->tm_sec   = bcd2bin(buf[0] & HYM8563_SEC_MASK);    // buf[0]=SEC
    tm->tm_min   = bcd2bin(buf[1] & HYM8563_MIN_MASK);    // buf[1]=MIN
    tm->tm_hour  = bcd2bin(buf[2] & HYM8563_HOUR_MASK);   // buf[2]=HOUR
    tm->tm_mday  = bcd2bin(buf[3] & HYM8563_DAY_MASK);    // buf[3]=DAY
    tm->tm_wday  = bcd2bin(buf[4] & HYM8563_WEEKDAY_MASK); // buf[4]=WEEKDAY, 0=周日
    tm->tm_mon   = bcd2bin(buf[5] & HYM8563_MONTH_MASK) - 1; // buf[5]=MONTH, -1=0基
    tm->tm_year  = bcd2bin(buf[6]) + 100;                   // buf[6]=YEAR, +100=2000基
    return 0;
}

static int hym8563_rtc_set_time(struct device *dev, struct rtc_time *tm)
{
    struct i2c_client *client = to_i2c_client(dev);
    u8 buf[7];
    int ret;
    // ---- 年份范围检查 ----
    // 硬件世纪位不可靠，驱动限制：2000–2099
    if (tm->tm_year < 100 || tm->tm_year >= 200)
        return -EINVAL;
    // ---- BCD 编码：将 tm 结构体转为 BCD 格式 ----
    buf[0] = bin2bcd(tm->tm_sec);
    buf[1] = bin2bcd(tm->tm_min);
    buf[2] = bin2bcd(tm->tm_hour);
    buf[3] = bin2bcd(tm->tm_mday);
    buf[4] = bin2bcd(tm->tm_wday);
    buf[5] = bin2bcd(tm->tm_mon + 1);   // +1: 0基→1基
    buf[6] = bin2bcd(tm->tm_year - 100); // -100: 2000基→0基
    // ---- 写入时序：STOP → 写时间 → 清除STOP ----
    // ① 先设置 STOP 位，暂停 RTC 计数（防止写入过程中时间变化）
    ret = i2c_smbus_write_byte_data(client, HYM8563_CTL1,
                                     HYM8563_CTL1_STOP);
    if (ret < 0)
        return ret;
    // ② 一次性写入 7 个时间寄存器
    ret = i2c_smbus_write_i2c_block_data(client, HYM8563_SEC, 7, buf);
    if (ret < 0)
        return ret;
    // ③ 清除 STOP 位，RTC 恢复计数（从新设定的时间开始）
    ret = i2c_smbus_write_byte_data(client, HYM8563_CTL1, 0);
    if (ret < 0)
        return ret;
    return 0;
}

static int hym8563_probe(struct i2c_client *client)
{
    struct hym8563 *hym8563;
    int ret;
    struct rtc_time tm_read, tm = {
        .tm_wday = 0,
        .tm_year = 121,      // 2021年
        .tm_mon  = 0,        // 1月
        .tm_mday = 1,
        .tm_hour = 12,
        .tm_min  = 0,
        .tm_sec  = 0,
    };
    // ① 分配私有数据结构
    hym8563 = devm_kzalloc(&client->dev, sizeof(*hym8563), GFP_KERNEL);
    if (!hym8563)
        return -ENOMEM;
    // ② 分配 RTC 核心设备
    hym8563->rtc = devm_rtc_allocate_device(&client->dev);
    if (IS_ERR(hym8563->rtc))
        return PTR_ERR(hym8563->rtc);
    hym8563->client = client;
    i2c_set_clientdata(client, hym8563);
    // ③ 初始化硬件：清除STOP/中断/标志位
    ret = hym8563_init_device(client);
    if (ret) {
        dev_err(&client->dev, "could not init device, %d\n", ret);
        return ret;
    }
    // ④ 注册中断（仅当 DT 中配置了 interrupt 时才执行）
    if (client->irq > 0) {
        ret = devm_request_threaded_irq(&client->dev, client->irq,
                        NULL, hym8563_irq,
                        IRQF_TRIGGER_LOW | IRQF_ONESHOT,
                        client->name, hym8563);
        // ... 错误处理 ...
    }
    // ⑤ 检查 VL 位 — 判断 RTC 时间是否有效
    ret = i2c_smbus_read_byte_data(client, HYM8563_SEC);
    dev_info(&client->dev, "rtc information is %s\n",
        (ret & HYM8563_SEC_VL) ? "invalid" : "valid");
    // ⑥ 如果时间无效或超出范围，重置为默认时间 (2021-01-01 12:00:00)
    hym8563_rtc_read_time(&client->dev, &tm_read);
    if ((ret & HYM8563_SEC_VL) || (tm_read.tm_year < 70) ||
        (tm_read.tm_year > 200) || (rtc_valid_tm(&tm_read) != 0))
        hym8563_rtc_set_time(&client->dev, &tm);
    // ⑦ 注册 RTC 设备到 Linux RTC 核心框架
    hym8563->rtc->ops = &hym8563_rtc_ops;
    clear_bit(RTC_FEATURE_UPDATE_INTERRUPT, hym8563->rtc->features);
    return devm_rtc_register_device(hym8563->rtc);
}

static int hym8563_init_device(struct i2c_client *client)
{
    int ret;
    ret = i2c_smbus_read_byte_data(client, HYM8563_CTL1);
    // ... error check ...
    // 清除 STOP 位（如果 RTC 之前被停止过）
    ret = i2c_smbus_write_byte_data(client, HYM8563_CTL1, 0);
    if (ret < 0) return ret;
    ret = i2c_smbus_read_byte_data(client, HYM8563_CTL2);
    if (ret < 0) return ret;
    // 禁用闹钟中断 (AIE) 和定时器中断 (TIE)
    ret &= ~HYM8563_CTL2_AIE;
    ret &= ~HYM8563_CTL2_TIE;
    // 清除任何待处理的闹钟/定时器标志
    if (ret & HYM8563_CTL2_AF) ret &= ~HYM8563_CTL2_AF;
    if (ret & HYM8563_CTL2_TF) ret &= ~HYM8563_CTL2_TF;
    // 复位定时器（写回配置）
    i2c_smbus_write_byte_data(client, HYM8563_TMR_CNT, 0);
    i2c_smbus_write_byte_data(client, HYM8563_TMR_CTL, HYM8563_TMR_CFG);
    // HYM8563_TMR_CFG = TE(使能) | 01(时钟源=64Hz)
    //                      ↑每 1/64 秒减1
    return i2c_smbus_write_byte_data(client, HYM8563_CTL2, ret);
}

static irqreturn_t hym8563_irq(int irq, void *dev_id)
{
    struct hym8563 *hym8563 = (struct hym8563 *)dev_id;
    struct i2c_client *client = hym8563->client;
    int data, ret;
    rtc_lock(hym8563->rtc);
    // 读取 CTL2，获取中断状态
    data = i2c_smbus_read_byte_data(client, HYM8563_CTL2);
    // 清除闹钟标志 (AF) 和定时器标志 (TF)
    data &= ~HYM8563_CTL2_AF;
    data &= ~HYM8563_CTL2_TF;
    // 复位定时器计数器
    i2c_smbus_write_byte_data(client, HYM8563_TMR_CNT, 0);
    // 写回清除后的 CTL2
    ret = i2c_smbus_write_byte_data(client, HYM8563_CTL2, data);
out:
    rtc_unlock(hym8563->rtc);
    return IRQ_HANDLED;
}
// 中断注册参数：
// IRQF_TRIGGER_LOW  — INT 引脚为低电平触发
// IRQF_ONESHOT      — 线程化中断，中断线在handler运行期间保持屏蔽

static int hym8563_rtc_set_alarm(struct device *dev, struct rtc_wkalrm *alm)
{
    // ...
    interval = alarm - now;  // 计算到闹钟的秒数
    if (interval < HYM8563_TMR_MAXCNT) {  // < 255 秒
        // ---- 定时器模式（1秒精度） ----
        // 使用硬件定时器做短间隔唤醒
        // 精度高，但最长只能 255 秒
        hym8563->alarm_or_timer_irq = 1;
        i2c_smbus_write_byte_data(client, HYM8563_TMR_CNT, (u8)interval);
    } else {
        // ---- 闹钟模式（分钟精度） ----
        // 使用硬件闹钟做长间隔唤醒
        // 没有秒级精度（tm_sec 被强制设为 0）
        // 但可以设置任意未来的时间
        hym8563->alarm_or_timer_irq = 0;
        alm_tm->tm_sec = 0;  // 秒强制归零
    }
    // ...
}

#ifdef CONFIG_COMMON_CLK
static int clkout_rates[] = {
    32768,      // FD[1:0] = 00
    1024,       // FD[1:0] = 01
    32,         // FD[1:0] = 10
    1,          // FD[1:0] = 11
};
static int hym8563_clkout_control(struct clk_hw *hw, bool enable)
{
    // 读 CLKOUT 寄存器 → 设置/清除 OE 位 → 写回
    int ret = i2c_smbus_read_byte_data(client, HYM8563_CLKOUT);
    if (enable)
        ret |= HYM8563_CLKOUT_ENABLE;
    else
        ret &= ~HYM8563_CLKOUT_ENABLE;
    return i2c_smbus_write_byte_data(client, HYM8563_CLKOUT, ret);
}
// 驱动标记为 CLK_IS_CRITICAL — 防止系统关闭 CLKOUT
// 某些 SoC 依赖此时钟源，关闭会导致系统问题
init.flags = CLK_IS_CRITICAL;
#endif

// 设备树匹配表 — 与 dts 中的 compatible 关联
static const struct of_device_id hym8563_dt_idtable[] = {
    { .compatible = "haoyu,hym8563" },
    {},
};
MODULE_DEVICE_TABLE(of, hym8563_dt_idtable);
// I2C 设备 ID 表（用于非设备树平台）
static const struct i2c_device_id hym8563_id[] = {
    { "hym8563", 0 },
    {},
};
MODULE_DEVICE_TABLE(i2c, hym8563_id);
// I2C 驱动结构体
static struct i2c_driver hym8563_driver = {
    .driver = {
        .name = "hym8563",
        .of_match_table = hym8563_dt_idtable,
    },
    .probe = hym8563_probe,
    .id_table = hym8563_id,
};
module_i2c_driver(hym8563_driver);
MODULE_DESCRIPTION("Haoyu HYM8563 RTC driver");
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Haoyu Microelectronics");