干过一段时间嵌入式 Linux 驱动开发的人对 I2C 总线大概都是又爱又恨。爱的是它结构简单两根线就能挂上一堆外设恨的是真调起问题来波形、地址、时序、设备树各种因素搅在一起没点系统性认识很容易被绕进去。我当年从裸机 I2C 程序跳到 Linux 驱动第一反应是这不就是打开设备、写几个寄存器吗后来被实际项目教育了几次才认识到 Linux 下的 I2C 总线驱动是一个分层分得很清楚的框架每个环节都有自己的职责边界乱踩边界就会出各种奇怪问题。这篇东西不打算把内核源码逐行抄一遍而是想从我实际做过的传感器、存储芯片、触摸屏这类外设移植和调试经验出发把 I2C 总线驱动的整体脉络、核心数据结构和实操要点讲透尤其是那些文档里不会明说、但踩坑之后才真正理解的东西。适合谁看呢正在接触 Linux 驱动开发但被 I2C 框架绕晕的初学者以及能把设备调通但遇到偶发性通信失败probe 不到设备这类问题就头皮发麻的同学。我会尽量把概念、代码、实操顺序和排障思路串成一条线保证你看完能对I2C 总线驱动到底由几块组成、每块该干什么、遇到问题往哪个方向排查有一个清晰的地图。1. 先把 I2C 总线的框架拆开别再把驱动混为一谈1.1 总线驱动、适配器、客户端各自的职责很多人刚开始看内核代码时会在目录drivers/i2c/下面看到一堆文件很容易糊涂。其实先记住一个结论Linux 的 I2C 框架由三大部分组成它们各管一段。第一部分是I2C 总线控制器驱动Adapter Driver它直接面对的是芯片上的硬件 I2C 控制器也就是主机控制器Controller。这块驱动要做的事情是初始化控制器的时钟、中断、引脚配置把寄存器操作封装成可收发数据的函数并注册成一个i2c_adapter。你可以把它理解为总线本身的驱动它不知道总线上挂了几个设备也不关心设备是谁只负责把一条条传输请求真实地发到物理总线上。第二部分是I2C 客户端驱动Client Driver它面对的是挂在总线上的具体外设比如温度传感器、EEPROM、触摸屏控制芯片。这块驱动要处理的是设备的寄存器地址、配置流程、数据格式并且只通过通用的i2c_transfer或者 SMBus 接口向适配器发请求。真正的硬件细节在适配器那边完成客户端驱动不关心控制器寄存器长什么样。第三部分是I2C 核心I2C Core它管的是适配器和客户端如何匹配总线锁该怎么上设备如何注册到框架里这些公共逻辑。核心层提供了枚举设备、注册驱动、解析设备树的标准过程让适配器和客户端两边不直接耦合。这三个角色一句话总结核心负责牵线适配器负责发消息客户端负责解释消息内容。1.2 为什么要把控制器和设备拆成两套驱动有些从裸机转过来的朋友会不理解以前写单片机 I2C 程序直接在工程里写一个I2C_WriteReg(addr, reg, val)函数控制器操作和设备流程全在一块干净利索。为什么 Linux 非要拆成两层一个很实际的原因是共用和替换。同一颗主控芯片今天挂温度传感器明天挂加速度计后天换成一款新的触摸屏。如果设备逻辑和控制器逻辑耦合在一起每次换外设都要把总线的底层寄存器代码重新抄一遍出错的概率会成倍上升。拆开之后控制器驱动写一次被多个客户端驱动复用客户端驱动针对具体芯片写可以挂在不同主控上只要对方的适配器接口符合内核规范。这也是为什么你在drivers/i2c/busses/里能看到针对各种主控的适配器驱动又在drivers/i2c/chips/或各种厂商驱动目录下找到一大堆客户端驱动它们通过struct i2c_adapter和struct i2c_client松耦合连接。这里还要说一个容易混淆的点很多人把总线驱动理解成那根总线本身以为要写一个驱动程序去管理两根电线。实际上内核里的i2c_bus只是一个抽象的总线类型负责给挂在同一控制器下的客户端提供一个匹配和管理的空间。你真正要写的驱动要么是适配器驱动很少除非你换主控或控制器硬件比较特殊要么是客户端驱动绝大多数项目的工作量都在这。搞清了这个边界后面看哪份源码、改哪个文件就一目了然。2. 适配器驱动是怎么撑起一条总线的2.1 核心结构i2c_adapter 与 i2c_algorithm适配器驱动在代码里的核心是struct i2c_adapter但光有这个结构还不够它必须带一个struct i2c_algorithm里面放着真正干活的函数指针。演示一下最精简的结构struct i2c_algorithm { int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num); int (*smbus_xfer)(struct i2c_adapter *adap, u16 addr, unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data); u32 (*functionality)(struct i2c_adapter *adap); ... };master_xfer是普通 I2C 传输的入口客户端驱动调用一次i2c_transfer时最终会走到这里。smbus_xfer是SMBus 通信模式的专用入口很多电源管理芯片和电池芯片用的是 SMBus 协议可以理解为 I2C 的一种严格变体。functionality则用来告诉核心层和客户端这个适配器支持哪些传输功能比如是否支持 10 位地址、是否支持块读取。适配器驱动要做的就是把这片 SoC 上 I2C 控制器的初始化、时钟设置、中断注册、收发状态机都封装好然后在master_xfer里根据传入的struct i2c_msg数组去操作控制器的发送/接收寄存器和状态寄存器一条条把消息发完最终返回成功发送的消息条数。这里有个特别重要的约定返回值的细节决定了总线行为的正确性。如果所有消息都完成就返回num如果中途仲裁失败或 NACK要返回负的错误码一条都没发出时返回 0。内核上层就是依赖这个返回值来判断重试策略的。2.2 适配器的注册与解除注册写完这些函数接下来是注册动作。一般通过i2c_add_adapter()把适配器加入系统并把它和设备模型关联起来。实际代码常见流程如下static struct i2c_algorithm my_controller_algo { .master_xfer my_master_xfer, .functionality my_functionality, }; static struct i2c_adapter my_adap { .owner THIS_MODULE, .class I2C_CLASS_HWMON | I2C_CLASS_SPD, .algo my_controller_algo, .dev.parent pdev-dev, .name my-i2c-controller, }; static int my_controller_probe(struct platform_device *pdev) { struct my_i2c_dev *i2c platform_get_drvdata(pdev); ... i2c-adap my_adap; i2c-adap.nr pdev-id 0 ? pdev-id : 0; i2c-adap.dev.of_node pdev-dev.of_node; return i2c_add_adapter(i2c-adap); }这里我要特别提一句.class字段。它声明的是这个总线上可能挂什么类型的设备比如I2C_CLASS_HWMON表示可能挂硬件监测外设。你如果让老式的内核全总线探测机制工作这个字段会参与设备地址扫描。但现在大部分设备都走设备树class对实际枚举的影响已经弱了很多可它也不是完全没意义用户空间的某些自动加载机制还会看它。我见过有人把所有客户端都改成设备树匹配后把class随手清成 0结果某些平台在系统启动阶段探测设备时行为变得非常奇怪所以建议保留合理的 class别乱删。2.3 设备树如何把适配器和外设接起来设备树在现代 Linux I2C 驱动开发中占了绝对主导地位。一个典型的设备树节点长这样i2c1 { clock-frequency 400000; pinctrl-names default; pinctrl-0 pinctrl_i2c1; status okay; sensor48 { compatible vendor,temperature-sensor; reg 0x48; vdd-supply reg_3v3; interrupt-parent gpio1; interrupts 5 IRQ_TYPE_EDGE_FALLING; }; };适配器驱动在 probe 时会通过i2c_add_adapter把dev.of_node关联到总线上。之后核心层会在系统解析设备树时遍历i2c1节点下的每个地址子节点为每个外设创建一个struct i2c_client并在合适的时机调用对应的客户端驱动 probe。整个流程是自动的这也是为什么移植一个新外设在现代驱动开发里往往意味着写一个匹配 compatible 的客户端驱动 在设备树里加一个节点。注意设备树里reg填的是 7 位从机地址不要填成带读写位拼出来的 8 位值。比如芯片手册写地址 0x90含读写位的写法实际在设备树里应该填 0x48。这地方我见过不止一个同事踩坑规则就一条内核里 I2C 地址一律以 7 位为准。3. 客户端驱动的核心细节与 API 实操3.1 i2c_client、i2c_driver 和 probe 的匹配关系客户端驱动核心是两个结构体struct i2c_client和struct i2c_driver。前者代表一个真实的、挂在总线上的外设实例里面有addr、adapter、dev、name等字段后者代表驱动本身里面有probe、remove、id_table和detect等回调。匹配过程其实很直接当核心层创建设备时会检查设备的compatible字符串是否在该总线上已注册的某个i2c_driver的of_match_table里。匹配命中后系统会调用驱动的probe函数。所以客户端驱动最基本的骨架是static const struct of_device_id my_sensor_of_match[] { { .compatible vendor,temperature-sensor }, { } }; MODULE_DEVICE_TABLE(of, my_sensor_of_match); static int my_sensor_probe(struct i2c_client *client) { struct my_sensor_data *data; struct device *dev client-dev; data devm_kzalloc(dev, sizeof(*data), GFP_KERNEL); if (!data) return -ENOMEM; >struct device *dev client-dev; reset_gpio devm_gpiod_get_optional(dev, reset, GPIOD_OUT_HIGH); int_pin devm_gpiod_get_optional(dev, int, GPIOD_IN); vdd devm_regulator_get_optional(dev, vdd); rate device_property_read_u32(dev, poll-interval-ms, val); irq client-irq; // 中断资源由核心根据 interrupts 属性自动挂到 clientgpiod系列函数读节点里带-gpios后缀的属性regulator框架读*-supply属性。读取失败时函数会返回错误指针可以用devm_版本省去手动释放。这里要留个心眼只要可选的属性没失败就继续跑别把get_optional的错误当成致命错误处理。有些芯片没有复位脚你非要在驱动里强制要求reset引脚存在probe 就会因为找不到属性直接失败这在其他板卡上复用驱动时就显得很蠢。3.3 数据收发i2c_transfer 和 SMBus 的取舍客户端驱动里真正跑数据的地方一般是i2c_transfer和 SMBus 辅助函数。i2c_transfer是最底层的通用接口传入一个struct i2c_msg数组struct i2c_msg { __u16 addr; // 从机地址7位 __u16 flags; // 0 表示写I2C_M_RD 表示读 __u16 len; // 数据长度 __u8 *buf; // 数据缓冲 }; static int sensor_write_reg(struct i2c_client *client, u8 reg, u8 val) { u8 buf[2] { reg, val }; struct i2c_msg msgs[] { { .addr client-addr, .flags 0, .len 2, .buf buf }, }; int ret i2c_transfer(client-adapter, msgs, ARRAY_SIZE(msgs)); if (ret ! ARRAY_SIZE(msgs)) return ret 0 ? ret : -EIO; return 0; }这个模式是先写寄存器地址再由控制器直接读回数据在 I2C 协议里是通过重复起始条件Restart连接的内核会按同一批次i2c_msg自动处理。注意我这里把两段消息放在同一个数组里数量和最后返回值要仔细核对。i2c_transfer返回的是成功处理的消息数目不是字节数。拿到返回值先和ARRAY_SIZE(msgs)比较不等再判断正负这种写法能避免很多误判。SMBus 接口在linux/i2c.h里封装得更加友好。比如i2c_smbus_read_byte_data(client, reg)、i2c_smbus_write_byte_data(client, reg, val)、i2c_smbus_read_block_data()适合处理大多数遵循 SMBus 格式的存储器件和传感器。它们的底层会调用adapter的smbus_xfer如果没有实现这个回调就退化走master_xfer拼成普通 I2C 消息再做模拟。只要芯片协议没有超出 SMBus 定义的范围用这类接口比手动构造i2c_msg省事得多代码可读性也高。至于选哪种我的原则是这样寄存器访问一律优先i2c_smbus_*系列因为简洁清晰涉及到页写、连续读、或一次操作多条消息时直接上i2c_transfer。但要注意某些时序敏感的芯片比如部分触摸屏控制器的固件升级模式对中间是否会多插入一个停止条件非常敏感SMBus 模拟路径可能不满足这时必须使用显式的i2c_msg数组来强控消息边界。4. 从零写一个客户端驱动的实操流程4.1 最小可用版本的落地步骤我不爱对着空文件教人怎么写干脆拿一个典型的某环境传感器假设需求来演示。芯片只有一个寄存器地址一个 ID 寄存器一个温湿度数据寄存器。你拿到的需求可能是让它在系统里表现为一个 hwmon 或 IIO 设备这里为了聚焦 I2C 部分先用最简单的方式把数据读出来放到 sysfs 里。一步步来确认设备树找到对应 I2C 控制器节点增加子节点sensor48compatible填一个内核驱动能匹配的字符串。新建驱动文件在drivers/i2c/chips/下或厂商目录下建my_sensor.c写好of_match_table、i2c_driver结构体和module_i2c_driver。实现probe读取芯片 ID 校验匹配保存client指针注册sysfs接口或提交到 IIO/hwmon 框架。实现读数据函数利用i2c_smbus_read_word_data读回 16 位数据再根据手册拆出温度和湿度字段。编译、运行、验证启动内核后查看ls /sys/bus/i2c/devices/下是否出现2-0048这类目录再用cat读取自定义文件。这里我想强调第 1 步里容易翻车的地方设备树里address-cells和size-cells的写法取决于上级节点reg只写地址不写长度一般没问题但如果你直接把别的平台整棵i2c1节点拷贝过来很有可能会带上冲突的时钟或 pinmux 配置。我建议只拷贝最小子节点适配器父节点的配置单独核对。4.2 老式无设备树设备的探测路径detect 与 addr_list如果你的内核跑在没有设备树或者不支持设备树的古老环境里还有一个老派机制叫在全总线上按地址探测。i2c_driver结构里有两个相关字段class和detect。当适配器的class与i2c_driver.class有交集时内核会对驱动指定的addr_list里的每个地址发一个探测消息然后调用detect回调来进一步确认设备。static const unsigned short my_sensor_addr_list[] { 0x48, 0x49, I2C_CLIENT_END }; static int my_sensor_detect(struct i2c_client *client, struct i2c_board_info *info) { struct i2c_adapter *adapter client-adapter; if (i2c_smbus_read_byte_data(client, MY_SENSOR_ID_REG) ! 0x1234) return -ENODEV; strscpy(info-type, my-sensor, sizeof(info-type)); return 0; } static struct i2c_driver my_sensor_driver { .class I2C_CLASS_HWMON, .detect my_sensor_detect, .address_list my_sensor_addr_list, ... };这个机制有个明显的副作用——探测时会对每个地址实际发起传输。如果总线上某个地址恰好被一个一旦收到数据就执行动作的设备占用探测就可能引发不可预期行为。所以现代内核开发中只要带设备树我就尽量不依赖detect探测让设备树直接生成i2c_client。老方案不是不能用只是你得清楚它的代价。4.3 上线验证从日志到波形的一整套检查写完驱动加完设备树不代表事情结束了。上板后第一件事是确认总线枚举是否成功ls /sys/bus/i2c/devices/ i2cdetect -l i2cdetect -y 2i2cdetect -y 2会在第 2 号总线上扫描所有地址。如果地址 0x48 位置出现48说明总线能通信且设备回复 ACK。如果显示--或者UU需要分别处理--代表 NACK 或者无设备优先确认电源、上拉电阻和从机地址UU表示该地址已经被某个驱动占用这本身不是错误但如果你扫描时觉得明明设备在怎么标了 UU说明要查注册流程里i2c_new_device或设备树节点是否重复声明了地址。设备枚举成功后我还会用逻辑分析仪抓一次实际波形。这是我认为最靠谱的验证方式。观察启动阶段是否出现 START、设备地址字节、ACK、寄存器地址、数据字节、STOP 的完整序列。使用 400kHz 传输时时钟高电平宽度约 1.2 微秒低电平也要相应成比例如果看到时钟高电平被拉得很短、SDA 跳变点贴近 SCL 边沿往往是上拉电阻阻值偏大或总线电容过高导致的边沿变缓。注意总线空闲时 SDA 和 SCL 都应该处于高电平这是由外部上拉电阻保证的。上板发现总线忙时既可能是别的主机正在通信也可能是某根线被故障设备拉死。这时优先断电检查硬件再考虑软件问题顺序不要反了。5. 用户态调试与内核态驱动的边界5.1 用 i2c-dev 和用户态工具快速确认芯片行为调试 I2C 外设时最痛苦的事是第一个版本驱动还没写完芯片行为就先要摸清楚。这个阶段没必要急着写内核代码。Linux 专门开放了i2c-dev用户态接口内核编译CONFIG_I2C_CHARDEV后每个适配器会对应一个/dev/i2c-N节点。用户态可以用标准open、ioctl、read、write直接操作总线上任意地址配合命令行工具i2cget、i2cset、i2cdump能很快验证芯片手册上的寄存器行为。例如# 从 2 号总线的 0x48 设备读取 0x00 寄存器 i2cget -y 2 0x48 0x00 # 向某个控制寄存器写值 i2cset -y 2 0x48 0x10 0x01在写正式内核驱动之前我一般会先拿这些命令把芯片完整盘一遍能不能读到 ID、寄存器地址是递增还是固定、写寄存器后数据是否立即生效、有没有需要等待的转换时间。这些信息虽然芯片手册会写但实际芯片行为与手册有出入的情况多得是用用户态工具在真机上验证过驱动 probe 的把握就大了很多。5.2 什么时候必须写内核驱动什么时候留在用户态更划算也许你会想既然用户态已经能操作 I2C那我还写内核驱动干什么这个选择要具体看场景。如果你的外设只是项目上线前调试一下或者设备数量少、访问频率低、不需要和内核其他子系统协同直接用i2c-dev在用户态写一个小工具完全够用。可一旦设备要面向生产环境、要支持 poll 中断、要注册成输入子系统或 hwmon、要和电源管理框架联动、要被多个进程安全共享那就必须写内核驱动。内核驱动带来的不仅是性能更关键的是统一的设备模型生命周期管理、中断上下文的处理能力以及通过设备树声明依赖资源后自动解决时序问题的能力。我自己踩过一个教训为了图快把一个小传感器的读取逻辑全部放在用户态脚本里跑后来系统休眠唤醒流程里需要重新初始化传感器用户态脚本拿不到内核休眠通知的时序导致唤醒后传感器状态不一致最后还是回归内核驱动解决。凡是和系统级电源管理、休眠唤醒、中断事件绑定的外设老老实实走内核驱动才是正路。6. 常见问题与排查技巧实录6.1 总线不通时的几个经典信号驱动调试中I2C 不通的现场表现很固定基本逃不出下面几种probe 里读 ID 失败返回 -ENODEV优先看设备地址是否有误其次看供电稳定。i2cdetect 显示全--说明对应地址没有 ACK。先量总线静态电平SDA 和 SCL 是否都在高再查设备是否处于复位状态、使能脚是否拉对。i2cdetect 一扫描就死机卡住多半是总线上存在时钟拉伸问题或者某个设备响应异常把 SCL 拉低不放导致主机一直等待。这种情况需要示波器同时抓 SCL 波形看拉低时间必要时降低通信速率到 100kHz 再试。扫描时某个地址总是跳变时而有时而无可能是总线上有多个设备地址重叠或者设备内部工作状态会导致 ACK 不稳定比如电源欠压、晶振没起振。这种问题最容易让人误判软件建议先从电源纹波查。6.2 一张表把典型问题和处理方向理清我习惯把常见问题整理成一张速查表排查时对照着走效率高很多现象可能原因排查方向所有地址都 NACK上拉电阻缺失、总线电容过大、设备未上电量 SCL/SDA 静态电平检查电源和上拉单个地址 NACK从机地址配置错误、设备未使能核对设备树 reg/硬件拨码查设备手册 bit0 位处理偶发通信失败供电波动、速率过高、边沿过缓降速到 100kHz 试抓波形看时序余量probe 里读到全 0xFF设备不在线、复位引脚未拉高检查使能和复位逻辑先用户态 i2cget 验证probe 里读到全 0x00SDA 可能被拉死或设备处于错误模式断电重新上电检查是否有地址冲突能读到设备但写寄存器无效写使能时序未满足、寄存器地址大小端问题对比手册时序图用 i2cset 逐步验证总线扫描出现 UU该地址已被驱动占用确认设备树节点重复或先卸载占用驱动这张表不能覆盖所有场景但能覆盖掉大概九成的 I2C 初查工作。遇到表外问题我的经验是先抓波形再动代码别凭空猜。6.3 几条写在最后的排障心得最后分享几个我个人的习惯未必是教科书上的标准做法但实战中确实救过我很多次。第一任何 I2C 通信问题先确认地址没有算错。7 位地址、8 位地址、带读写位的地址这三者之间差一个 bit非常容易写错。我后来在代码里都用宏定义统一管理设备地址并注释清楚来源避免临时换算。第二调试用的打印要带上下文。不要只在错误路径打一行i2c error。要把寄存器地址、期望值、实际读到的值、传输返回码一起打印这样一次串口日志就能定位问题否则就得反复加打印重新编译效率太低。内核里dev_dbg、dev_err的格式可以参考这种风格dev_err(client-dev, read chip id failed: reg%02x ret%d id%04x\n, reg, ret, id);第三当总线行为诡异时把通信速率主动降下来试。很多硬件问题在低速下会消失这能快速区分是时序不满足还是芯片逻辑错误。软件上可以在设备树clock-frequency或适配器初始化里临时改成 100000有效排除边沿过缓的问题。第四善用CONFIG_I2C_DEBUG_BUS和CONFIG_I2C_DEBUG_CORE。开启后内核会在每次传输前后打印消息数组和返回值这对理解i2c_transfer实际发了几条消息、每条消息的目标地址和长度是非常直观的辅助。缺点是日志量很大调试完记得关掉。结尾这套 I2C 总线驱动的框架思路我用在不止一个项目上从最初的传感器读取到后来调触摸屏的固件升级流程再到排查电池管理芯片的 SMBus 通信问题基本上都靠适配器管传输、客户端管语义、核心管匹配这个主线来定位方向。真要说最深的体会那就是别让设备树、地址、上拉电阻这些基础问题把精力消耗光先把地图画清楚再一头扎进细节。最后再分享一个小技巧如果你在调试一个没见过的新传感器拿到开发板的第一天不要急着写驱动文件先用i2cdetect扫描地址再用i2cget/i2cset把芯片手册里的关键寄存器全部访问一遍把结果截图存档。这个先验真机行为再写软件逻辑的顺序能帮你省掉后面至少一半的排障时间。I2C 这个东西说难是难在细节多说简单也简单因为只要总线物理正常绝大多数问题都能通过一步一步的读写实验定位出来。