干这行久了你会发现，Linux I2C驱动几乎就是嵌入式开发里的“万金油”。板子上挂个EEPROM、加速度计、温湿度传感器，都靠这条两线制总线跑数据。Linux I2C驱动说起来很模式化，结构常年稳定，但真要动手写，设备树、总线匹配、并发访问、地址换算这些坑还是能绊倒不少人。这篇文章我以一次实际开发经历为主线，从总线模型讲到设备树，再给出可运行的最小驱动代码，最后把调试手段和踩坑记录一并交代清楚。适合已经会写内核模块基础程序、但对I2C子系统还不太熟悉的朋友，看完基本可以独立开始写自己的客户端驱动。
1. 先站在总线模型角度看I2C驱动
1.1 物理线背后的角色分工
I2C物理层简单得离谱，就两根线：SCL时钟线和SDA数据线。但先别急着写代码，把逻辑角色搞清楚比背API更重要。总线上有三个角色：主机控制器（Adapter）、从设备（Client）、通信算法（Algorithm）。主机控制器是SoC内部那个I2C外设，负责把寄存器配置变成SCL和SDA上的实际时序；从设备就是我们天天要驱动的传感器、EEPROM、RTC之类的东西；算法这一层则是控制器和上层驱动之间的翻译器，决定时钟频率、ACK处理、起始停止位怎么生成，一般跟着SoC的IP核走，不需要你改。
内核里这三位分别对应struct i2c_adapter、struct i2c_client、struct i2c_algorithm。对你来说，控制器和算法早就由芯片厂商写好了，你真正要打交道的是i2c_client和i2c_driver这两个东西。很多人刚开始学I2C驱动时老往硬件寄存器里钻，纠结某个控制器的FIFO怎么配，其实方向就偏了。大多数场景下你不需要碰控制器寄存器，把总线上“设备”和“驱动”的关系搞定，活儿就完成了八成。
1.2 总线模型里的三个角色
Linux设备模型里最基本的三个概念是bus、device、driver。I2C子系统完全沿用这套框架：bus对应i2c总线本身，device分成两类，一类是控制器设备也就是adapter，另一类是挂在i2c总线上的从设备client，driver自然就是我们自己写的i2c_driver。bus核心负责把device和driver匹配起来，匹配成功的瞬间会调用driver里的probe函数，这就是一切初始化的入口。
这个过程可以打个比方。设备树就像是小区物业的住户登记表，写明哪栋楼哪个房间住着谁；i2c_driver像物业经理，擅长服务某一类住户；总线模型就是物业柜台，负责在住户和经理之间做匹配。三方能对上，才正式签合同上岗。如果住户登记表上写的房号跟经理手里的客户档案对不上，那就算住户住在眼前，经理也不会去服务他——对应到代码里就是probe永远不执行。
1.3 匹配机制：probe是怎么被调起来的
匹配过程有两种触发方向。系统启动或者设备热插拔时，从设备被注册到i2c总线上；驱动加载时，i2c_driver也被注册到同一条总线。之后总线核心开始遍历，比对驱动维护的匹配表和设备携带的信息。主流的匹配依据有三条路径：
- 设备树
compatible属性与驱动of_match_table中的compatible字符串匹配，这是目前ARM平台最常用的一条。 - 驱动
id_table里的name字段与从设备名称匹配，主要用于无设备树的老式平台或者ACPI环境。 - 通过
i2c_new_client_device这类接口手动创建的i2c_client，靠device ID信息进行匹配。
第一条是你最该盯紧的。很多新人写了of_match_table却忘了在设备树里加compatible，或者两边字符串差了一个字母，结果probe就是不跑。排查这类问题的诀窍，不是反复看代码，而是把设备树里的compatible字段和驱动里的匹配表放一起逐字符比对。
1.4 你需要写哪一部分
看清了模型，你的工作范围其实很清楚：在设备树里正确声明从设备节点；实现一个i2c_driver并注册到i2c总线；在probe里完成设备初始化；向用户态提供数据接口。adapter和algorithm都不需要碰，那是SoC厂商的事。站在这个高度上想问题，就不会被一些底层的寄存器实现细节带偏方向，写代码的路径也清晰很多。
2. 动手前：环境、内核配置与设备树
2.1 内核选项和基础工具
开工前先确认内核把I2C核心支持编进去了。一般需要CONFIG_I2C和对应的控制器驱动，具体选项名字随SoC平台变化，大多数开发板默认已经开启。开发调试期间还有两个配置建议打开：CONFIG_I2C_CHARDEV，它会在用户态生成/dev/i2c-N节点，方便后面用工具直接扫总线；再就是CONFIG_I2C_DEBUG_CORE和CONFIG_I2C_DEBUG_ALGO这类调试开关，会在内核日志里打印总线收发细节，开发期非常有用。
源码方面，你主要面对的头文件是include/linux/i2c.h，里面定义了全部核心结构体和API。我习惯的做法是随时保持一份与当前内核版本一致的源码树，写之前先grep一下相关结构体，确认字段没变，比硬记API可靠得多。内核版本升级频繁，不少接口都有过调整，源码本身才是最权威的文档。
2.2 设备树里怎么声明一个从设备
以一颗挂在一号I2C控制器上的从设备为例，一个最简的节点是这样写的：
&i2c1 { status = "okay"; clock-frequency = <100000>; myi2c@18 { compatible = "vendor,myi2c-dev"; reg = <0x18>; }; };这段话说得很直白：我把一颗兼容vendor,myi2c-dev协议描述的从设备，挂到了i2c1总线上，它在总线上的地址是0x18。status = "okay"确保控制器被使能，clock-frequency指定控制器跑100kHz标准模式，这是绝大多数低速传感器都能接受的速度。节点名myi2c@18只是人类可读的名字，内核真正看的是compatible和reg这两个属性，名字怎么起不影响功能，但最好和reg保持一致，方便人眼排查。
2.3 reg到底是7位还是8位
地址换算这个坑，我当年结结实实踩进去过。I2C从设备地址本质上只有7位有效位，读写位是单独控制的。很多数据手册里写的“设备地址0x30”，指的是包含写位的8位地址，翻译到设备树时要右移一位，变成0x18。如果手册明确写的是“7位地址0x18”，那设备树直接写0x18就行。
判断依据很简单：I2C总线上实际发送的第一字节，是7位地址左移一位，再拼上读写位。而设备树里的reg属性会被内核直接填到i2c_client的addr字段里，内核内部使用的是7位地址。写完设备树后，用i2cdetect扫描出来的地址如果和reg不一致，先检查是不是换算问题，别急着怀疑驱动。这个换算关系要是记不牢，probe匹配不上的时候排查半天都找不到方向。
3. 核心代码解析：从匹配到数据收发
3.1 驱动主体结构和两个匹配表
一个标准I2C驱动骨架包含三个核心部分：of_device_id匹配表、i2c_device_id匹配表、i2c_driver本体。先看两个匹配表怎么写：
#include <linux/module.h> #include <linux/i2c.h> #include <linux/of_device.h> #include <linux/miscdevice.h> #include <linux/uaccess.h> #include <linux/mutex.h> #define DRV_NAME "myi2c-demo" static const struct i2c_device_id myi2c_id[] = { { DRV_NAME, 0 }, { } }; MODULE_DEVICE_TABLE(i2c, myi2c_id); static const struct of_device_id myi2c_of_match[] = { { .compatible = "vendor,myi2c-dev" }, { } }; MODULE_DEVICE_TABLE(of, myi2c_of_match);i2c_device_id表用于非设备树环境，of_device_id表用于设备树环境，两个都写上兼容性最好。MODULE_DEVICE_TABLE这行容易被忽视，它的作用是把匹配表信息导出到模块的元数据区，modprobe才能根据设备节点上的信息自动加载对应模块。少了这行，模块只能手动insmod，系统重启后驱动不会自己起来，体验差距很大。
i2c_driver本体长这样：
static struct i2c_driver myi2c_driver = { .driver = { .name = DRV_NAME, .of_match_table = myi2c_of_match, }, .probe = myi2c_probe, .remove = myi2c_remove, .id_table = myi2c_id, }; module_i2c_driver(myi2c_driver); MODULE_LICENSE("GPL");module_i2c_driver宏帮我们完成了模块装载时的注册和卸载时的注销，比手写module_init和module_exit短一截。这里有个细节：.driver.name和id_table里的name并不会直接影响设备树匹配，但它决定了/sys/bus/i2c/drivers/myi2c-demo这个目录的名字，后面查设备状态时按这个名字找，挺重要。
3.2 probe里该做什么
probe在设备匹配成功后触发，入口参数就是已经匹配上的i2c_client。这个函数的核心任务通常有三步：分配私有数据结构、初始化锁或者状态机、确认设备在线。
struct myi2c_dev { struct i2c_client *client; struct mutex lock; u8 id; }; static int myi2c_probe(struct i2c_client *client) { struct myi2c_dev *dev; int ret; dev = devm_kzalloc(&client->dev, sizeof(*dev), GFP_KERNEL); if (!dev) return -ENOMEM; dev->client = client; mutex_init(&dev->lock); ret = i2c_smbus_read_byte_data(client, 0x00); if (ret < 0) { dev_err(&client->dev, "device not responding: %d\n", ret); return ret; } dev->id = (u8)ret; dev_info(&client->dev, "probe ok, id=0x%02x\n", dev->id); i2c_set_clientdata(client, dev); return 0; }两个点值得单独讲。第一，devm_kzalloc是设备资源管理接口，probe失败、设备移除时内核会自动释放内存，省掉一大堆手动清理代码；第二，probe里做一次“读ID验证”看起来多余，实际价值很大。很多硬件层面的问题，比如虚焊、地址错、总线没上拉，都会在读ID这一步暴露出来，比上层应用运行到一半报怪错好排查得多。一个probe就能把绝大多数硬件问题挡在门口。
3.3 数据收发API怎么选
I2C收发接口分两层。底层是i2c_transfer()，它组织一条或者多条i2c_msg消息进行传输；上层是smbus系列封装，比如i2c_smbus_read_byte_data()、i2c_smbus_write_word_data()，内部也是基于i2c_transfer实现的。
日常写驱动，优先用smbus封装。比如读一个寄存器，物理上要发一个寄存器地址字节、再读一个数据字节，i2c_smbus_read_byte_data(client, reg)一句话搞定。遇到一次读一大块连续数据，或者设备的读写协议不是标准smbus格式，再考虑用底层接口。看一个裸的i2c_msg例子：
u8 reg = 0x10; u8 val; struct i2c_msg msgs[2] = { { .addr = client->addr, .flags = 0, .len = 1, .buf = ® }, { .addr = client->addr, .flags = I2C_M_RD, .len = 1, .buf = &val }, }; ret = i2c_transfer(client->adapter, msgs, 2); if (ret != 2) { dev_err(&client->dev, "transfer failed: %d\n", ret); return ret; }这条消息序列的逻辑是：先发一个字节的寄存器地址，然后发重复起始位，再以读模式收一个字节。flags为0表示写，I2C_M_RD表示读。特别注意i2c_transfer的第一个参数是adapter而不是client，可以从client->adapter取到。返回值和预期消息数量不一致时，大概率是设备NACK或者总线异常，不要把返回值当普通错误码一丢了事。
必须牢记的是，这两类接口都是会睡眠的，内部要等总线空闲、等事务完成，所以绝不能在自旋锁临界区、中断上下文里面调用。这是驱动挂死最常见的原因之一。
3.4 把数据暴露给用户态
驱动最终要服务应用层，接口形式一般有三种：往/sys里挂属性节点、注册miscdevice字符设备、或者用regmap加上debugfs辅助。我常用的是注册一个miscdevice，配合ioctl或者read/write操作。这样应用层代码写起来简单，驱动侧也不麻烦。
ioctl里处理一次读操作的样子：
static long myi2c_ioctl(struct file *file, unsigned int cmd, unsigned long arg) { struct myi2c_dev *dev = file->private_data; u8 val; int ret; switch (cmd) { case MYI2C_READ_ID: ret = i2c_smbus_read_byte_data(dev->client, 0x00); if (ret < 0) return ret; val = (u8)ret; if (copy_to_user((u8 __user *)arg, &val, sizeof(val))) return -EFAULT; return 0; default: return -EINVAL; } }这里有个非常容易踩的坑：i2c_smbus_read_byte_data返回的是int，小于0是错误码，大于等于0才是读到的数据。如果你用u8去接返回值，-1会变成255，错误被包装成合法数据，bug极其隐蔽。我在review代码时看到好几个人犯过这个错，务必记牢。
3.5 最小完整驱动，直接抄
把上面的碎片拼起来，一份能编译的最小模块主体就出来了。省略了文件操作结构体和部分初始化细节，核心骨架就是这样。对照你自己的内核版本看头文件，把结构和字段确认一遍，把这个框架搭通之后，往里加IRQ、加regmap、加批量读写都只是工作量问题。这个骨架本身不复杂，难的是理解为什么每一步都这么写——匹配表、probe、收发接口，每条线索都串在第一节讲的总线模型上。
4. 调试三板斧：日志、扫描、实测
4.1 打开内核的I2C调试日志
驱动跑起来没反应，第一件事不是改代码，是开日志。内核里的I2C调试开关有这么几个：
CONFIG_I2C_DEBUG_CORE：打印设备和驱动的匹配、注册过程，probe有没有被调用一看便知。CONFIG_I2C_DEBUG_ALGO：打印算法层的收发细节，能看到消息被组织成什么样子。CONFIG_I2C_DEBUG_BUS：打印总线消息的字节内容，最详细也最吵。
打开之后，dmesg里会出现类似i2c i2c-1: master_xfer[0] ...的输出，虽然格式看着乱，但能精确告诉你消息有没有发出、错误码是什么。开发阶段全开没问题，生产环境别开，日志刷屏会把其他信息全淹没。
4.2 用i2c-tools校准设备地址
内核驱动还没写好的时候，先用用户态工具确认硬件在线，比闷头写代码重要得多。i2c-tools这套工具里，i2cdetect -l列出系统里所有adapter，i2cdetect -y -r 1扫描1号总线上的设备地址。扫描出地址，说明硬件链路健康；扫不出来，大概率是上拉电阻缺失、供电没到位、SDA和SCL接反，或者总线上地址冲突。
i2cget、i2cset、i2cdump还能直接读写寄存器，帮你确认设备内部行为。这个环节必须熟练，它能帮你把问题一刀切成两半：到底是软件没写对，还是硬件根本不对。先扫总线再调驱动，是效率最高的顺序。
4.3 逻辑分析仪和示波器才是终审
软件日志只能反映内核认为发生了什么，物理线上真正发生了什么，还是得上仪器。I2C是慢速总线，几百kHz以内的信号用常见的逻辑分析仪就能抓得很清楚。抓一次地址帧和ACK位，基本能判断设备地址、时序、ACK行为是否符合预期。
这里有个容易忽略的硬件问题：I2C总线必须接上拉电阻，常见阻值在1k到10k欧姆之间，上拉到电源。板子设计偷懒，上拉没接或者阻值过大，会出现偶发NACK和丢数据。这种问题靠日志排查特别费劲，波形抓一次就现原形。
4.4 一个典型的排查顺序
我遇到“驱动不工作”时的排查路径是这样：先i2cdetect -l确认adapter节点存在，再i2cdetect -r扫描看设备挂在哪个地址，然后用逻辑分析仪抓启动位和ACK，最后才回头查内核驱动代码。这个顺序千万别反过来，否则你会花大量时间在一个本身没问题的驱动上反复改配置，越改越乱。先硬件后软件，先用户态后内核态，这条原则适用于绝大多数外设驱动调试。
5. 我踩过的坑和给你的避坑清单
5.1 compatible不匹配
最频繁的坑，没有之一。设备树里写的compatible和of_match_table里的字符串，只是差一个大小写字符，probe就不调用。排查办法是把两边内容复制出来逐字符对比，比盯着屏幕苦想效率高得多。别忘了compatible推荐格式是“厂商,型号”，比如vendor,myi2c-dev，中间是逗号，不是别的符号。
5.2 地址换算错
7位地址和8位地址的混用，我已经在设备树小节里强调过。这里再补充一个习惯：设备树里的reg与i2cdetect扫出来的地址必须互相印证，两个值一致才继续往下走。如果设备树写了0x30而扫描显示0x18，先想想是不是换算没做，不要急着改驱动里的地址。这种错误一旦发生，排查成本远高于写代码时多花一分钟确认。
5.3 并发访问导致时序错乱
驱动能跑通之后，并发问题才慢慢浮出水面。用户态多个进程同时打开同一个misc设备时，如果文件操作里的读写路径不加锁，两次I2C事务就可能交错执行，读到的寄存器数据张冠李戴。解决方法就是给每个client配一把mutex，在read、write、ioctl这些入口加锁开锁。I2C事务本身很短，锁开销几乎可以忽略，但不加锁的后果有时要跑很久才能复现，调试体验极差。
5.4 睡眠上下文和超时问题
I2C收发是可能睡眠的操作，内部要等待适配器完成一次事务。如果你在自旋锁保护的临界区或者中断处理函数里调用i2c_smbus相关API，内核调度器会直接报错，表现为驱动挂死或者oops。这种情况在低成本传感器驱动里出现频率极高，因为很多人习惯在中断里读数据。正确做法是中断里只置标志位或者唤醒工作队列，把真正的I2C传输放到进程上下文或者专用内核线程里完成。
5.5 几个实用工作习惯
长期和I2C驱动打交道，我攒了几个习惯，分享出来也许能帮你少走弯路。设备树节点先只写compatible和reg，能成功匹配再加其他属性，这样一旦probe没跑，问题只在最小范围内。改代码后先rmmod再insmod，重载失败先翻dmesg看是不是设备被占用。多利用i2c_set_clientdata和i2c_get_clientdata保存自己的私有数据结构，避免为每个设备开一个全局变量，否则挂多个同型号设备时数据会互相覆盖。打印地址时十六进制和十进制都打出来，跟工具扫描结果对应更直观。
5.6 内核版本差异是个沉默杀手
新内核里有些接口已经变了，网上很多老教程的代码在新内核上根本编译不过。比如i2c_driver的remove回调返回值类型、i2c_new_device到i2c_new_client_device的命名变化，不同版本之间都有过调整。我的做法是每次升级内核后，先打开include/linux/i2c.h把用到的结构体字段确认一遍，再动代码。这个习惯帮我省过很多个下午，建议你也养成。看代码、查源码、动手验证，永远比记忆可靠。
