Linux下GT115x触摸屏驱动移植实战：从设备树到中断排查-北京尧图网络

这块 Mini Linux 板子在我手里已经跑了好几个项目唯一让我折腾到半夜的就是那块4.3寸800x480触摸屏。显示屏的 RGB 信号接上就能亮但触摸一直没动静后来才发现触摸用的是一颗 GT115x 电容触控芯片驱动链路跟我想的完全不一样。这篇文章就把我从内核配置、设备树、驱动时序到三个真实故障的完整排查过程记下来给同样在做嵌入式 Linux 触摸屏移植的朋友做个参考。文章不会讲太多玄学都是可以直接抄作业的命令和配置适合正在调板子、或者正准备把 4.3 寸电容屏接到 Linux 平台的开发者。1. GT115x在这块屏里的真实角色显示和触摸是两条独立的链路很多人第一次拿到 4.3 寸 RGB 屏下意识以为屏亮了触摸就应该跟着好。实际上屏总成内部是两套完全独立的子系统显示部分由主控的 LCD 控制器通过并行 RGB 接口驱动负责按时序把像素数据打给面板触摸部分则是一颗独立的电容触控芯片也就是 GT115x通过 I2C 总线跟主控通信。两者之间除了共用一块玻璃和一根 FPC信号链路上没有半点关系。1.1 屏幕总成里有两套“芯片级”系统显示链路这边主控需要配置 LCDC 的时序参数比如像素时钟、行场同步、DE 极性这些在 800x480 分辨率下有一套相对固定的经验值一般照着屏幕手册填就行。我调试时直接把板卡默认的 800x480 参数拿来用画面正常说明显示侧根本没花什么时间。触摸链路这边则完全是另一套逻辑。GT115x 内部自带一颗小 MCU 和电容扫描矩阵它自己负责向触摸屏的感应电极打激励信号、检测电容变化、计算触摸坐标然后等主控来读取。主控这边要做的不是驱动扫描而是三件事把芯片配置好、接收中断、按 I2C 协议把坐标数据读回来。搞清楚这个模型之后我就把调试重心从怎么写驱动转移到了怎么把芯片供好电、接对线、配好设备树上。1.2 电源、I2C、INT、RST触摸这五根线决定了百分之八十的问题GT115x 对外就引出五根关键信号VCC、GND、SDA、SCL、INT。另外还有一个 RST 复位脚严格来说也算一根。很多屏模组会把触摸部分单独用一段 FPC 引出来排线座子上直接标好了丝印。这里最容易踩的第一个坑是供电电压。GT115x 的 VCC 是 3.3V不能直接接 5V。我见过有朋友把屏的背光供电和触摸供电搞混背光 5V 没事触摸芯片 5V 一上去直接冒烟或者完全没响应。第二个坑是 I2C 上拉电阻SDA 和 SCL 必须有上拉板子上的 I2C 控制器一般已经带了但如果你用的是飞线连出来的软串口记得自己补两颗 4.7kΩ 上拉。INT 是芯片通知主控有新数据的中断脚低有效。RST 是复位脚低有效。主控通过 RST 控制芯片的复位时机通过 INT 感知触摸事件通过 I2C 读写配置和数据。后面所有调试问题最后几乎都能归到这五根线上。2. 正式移植前的身份确认内核开关、I2C地址和芯片型号我一开始犯了个错误拿到板子就直接改设备树加了一堆属性然后编译烧录结果驱动根本没被编译进内核设备树写得再对也没用。所以后来我养成了一个习惯动手改代码之前先花十分钟做三件事确认内核开关、扫描 I2C 地址、读取芯片 Product ID。2.1 先确认内核有没有编译 Goodix 触摸驱动Linux 内核里对应 GT115x 的驱动源码在drivers/input/touchscreen/goodix.c配置项是CONFIG_TOUCHSCREEN_GOODIX。这块 Mini Linux 板使用的是 4.x 内核的 BSP默认配置里居然没有开这个选项。判断方法很简单在板子串口终端里执行zcat /proc/config.gz | grep GOODIX如果没有/proc/config.gz就去/boot/下找配置文件或者直接看内核源码里的.config。如果输出是空说明这个驱动根本没编进去需要重新配置内核make menuconfig # 路径Device Drivers - Input device support - Touchscreens - Goodix touchscreen driver这一项依赖CONFIG_INPUT_TOUCHSCREEN和CONFIG_I2C一般默认都是打开的主要确认 GOODIX 这一项选成y或者m。我是在 BSP 基础上直接改成y因为触摸屏驱动没有做成模块的必要开机即用的体验最好。改完重新编译内核烧录后先别急着高兴看看/proc/interrupts里有没有多出中断以及/proc/bus/input/devices里有没有新的输入设备。2.2 i2cdetect 扫地址0x5d、0x14、0x55 到底哪个是你的内核里 Goodix 驱动默认会去两个 I2C 地址上探测0x5d和0x14。这两个地址是由芯片的 ADDR/ID 引脚决定的模组出厂时通过上拉或下拉电阻把地址固定了所以你实际用哪个地址不能靠猜必须实测。首先要确认触摸芯片接在哪条 I2C 总线上。看板子原理图触摸 FPC 的 SDA/SCL 一般会接到某个硬件 I2C 控制器上比如 I2C1 或 I2C2。用下面的命令列出系统里所有 I2C 总线i2cdetect -l然后对每条总线做扫描i2cdetect -y -r 2-y是跳过交互确认-r使用 SMBus 读字节方式扫描有些触摸芯片对普通 quick write 不响应加-r更稳。扫描结果里如果出现5d说明 GT115x 在地址 0x5d如果出现14那就是 0x14。某些模组还可能出现55这是我遇到过一次的例外情况所以一定不要只认 0x5d。还有一点容易把人搞晕I2C 地址有 7 位和 8 位两种写法。你在数据手册里看到0xBA、0x28那是 8 位地址含读写位实际 7 位地址就是0x5d、0x14。i2cdetect 默认显示 7 位地址所以看到5d是对的别看到ba才对不上号。2.3 读 Product ID别再靠猜知道地址之后还能进一步确认芯片具体是 GT1151 还是 GT1158。GT115x 系列里最常用的是 GT1151但也有 GT1158 存在两者的寄存器协议几乎一致但 Product ID 不同。内核驱动在 probe 阶段会去读 Product ID 来匹配芯片参数所以让驱动知道自己面对的是哪一颗出问题的概率就小很多。用 i2ctransfer 直接读 ID 寄存器最直观。以地址 0x5d、总线 2 为例i2ctransfer -f -y 2 w20x5d 0x81 0x40 r4这条命令的含义是先写两个字节寄存器地址 0x8140再连续读 4 个字节。正常 GT1151 返回的十六进制是0x31 0x31 0x35 0x31也就是 ASCII 码的 1151。如果是 GT1158返回0x31 0x31 0x35 0x38。如果读出来全是0xFF或者0x00大概率是复位引脚没释放、I2C 地址不对或者供电有问题先回去检查硬件链路。这一步非常重要因为它同时验证了三件事I2C 通信正常、芯片供电正常、复位时序正确。这三件事全过了后面改设备树才有意义。3. 设备树节点控制驱动生死的四个字段确认内核开关、I2C 地址、芯片型号都没问题之后就该写设备树了。设备树是 Linux 下描述硬件拓扑的标准方式Goodix 驱动在 probe 阶段会从设备树节点里解析 GPIO、中断、坐标范围等信息。我把这一小节的重点放在四个字段上reg、interrupts/irq-gpios、reset-gpios、touchscreen-*坐标属性。3.1 一个经过实测的 GT1151 设备树样板下面这份设备树节点是我在这块 Mini Linux 板子上最终跑通的配置触摸芯片接在 I2C1 总线上INT 用 GPIO1_9RST 用 GPIO1_10i2c1 { status okay; clock-frequency 400000; gt1151: gt11515d { compatible goodix,gt1151; reg 0x5d; interrupt-parent gpio1; interrupts 9 IRQ_TYPE_EDGE_FALLING; irq-gpios gpio1 9 GPIO_ACTIVE_LOW; reset-gpios gpio1 10 GPIO_ACTIVE_HIGH; touchscreen-size-x 800; touchscreen-size-y 480; wakeup-source; }; };有几个细节值得解释一下。compatible必须和驱动里的匹配表对得上mainline 的 Goodix 驱动同时支持goodix,gt911、goodix,gt9147、goodix,gt1151等字符串。如果你们的内核版本比较老匹配表里没有goodix,gt1151可以临时用goodix,gt911顶替因为这两个型号的寄存器协议非常接近驱动走的是同一条初始化路径。interrupts和irq-gpios其实是指向同一根线的两种描述方式。驱动源码里的逻辑是如果设备树提供了irq-gpios就用它转换出中断号否则退回使用interrupts指定的中断。我建议两个都写上但内容必须一致避免出现设备树里irq-gpios指向 GPIO_A、interrupts指向 GPIO_B 这种自相矛盾。3.2 中断触发类型默认下降沿但别当成万能药GT115x 的 INT 脚默认是低有效芯片检测到触摸后会把 INT 拉低所以最常见的配置是IRQ_TYPE_EDGE_FALLING。我一开始也是这么写的触摸也确实能工作。但要注意一个细节有些屏模组在出厂配置里会把 INT 设置为电平触发模式芯片在有数据时把 INT 一直拉低而不是拉低一下再释放。这种情况下如果还用边沿触发就会出现第一次触摸正常、之后完全没反应的怪现象。后面我会专门讲这个案例。所以在排错阶段如果发现断裂式的丢失事件不妨把触发类型改成IRQ_TYPE_LEVEL_LOW试试。3.3 reset-gpios 的极性是重灾区reset-gpios的写法非常容易翻车。Goodix 的 mainline 驱动在复位时执行的是先写 0、再写 1gpiod_set_value_cansleep(ts-gpiod_rst, 0); // 进入复位 usleep_range(20000, 21000); gpiod_set_value_cansleep(ts-gpiod_rst, 1); // 释放复位这里有个关键点gpiod 接口里 set_value(0) 产生的物理电平取决于设备树里 GPIO 的极性标志。GT115x 的 RST 引脚是低有效要让 set_value(0) 真正把引脚拉到低电平设备树里应该写GPIO_ACTIVE_HIGH。如果你写成GPIO_ACTIVE_LOWset_value(0) 输出的是物理高电平芯片从头到尾就没被复位过。这个逻辑反直觉我当初也卡了很久。但现在有个简单的判断方法先把驱动代码里的 set_value 序列背下来再看你想让哪一段对应复位生效最后反推出设备树里该写哪个极性标志。如果你用的是厂商自己写的旧版驱动它的复位逻辑可能是先写 1、再写 0那设备树里的标志就得反过来。所以从别的板子抄设备树时一定要连驱动的源码一起看不能只抄 dts。3.4 坐标尺寸与方向属性touchscreen-size-x和touchscreen-size-y告诉驱动芯片坐标的最大范围。内核的 touchscreen 解析代码会把size减 1 当作最大值所以size-x 800对应坐标上限 799。这个值必须和芯片内部配置的坐标范围一致。如果触摸坐标出现方向问题就用以下三个属性修正touchscreen-inverted-x: X 轴镜像touchscreen-inverted-y: Y 轴镜像touchscreen-swapped-x-y: X 与 Y 交换需要注意的是方向错误不一定是属性没加对更可能是芯片配置区的坐标分辨率方向写反了。比如芯片里的配置是 480x800竖屏而你的屏实际是 800x480 横屏那坐标一定会交换和镜像同时出现。这种情况光加inverted-x是不够的还要加swapped-x-y甚至要重写芯片配置。所以遇到方向问题先别急着加属性先把原始坐标数据测出来再说。4. 上电后的“初始化仪式”复位、读ID、写配置、再软复位GT115x 不是那种焊上去就能用的普通外设它每次上电都需要主控配合完成一套初始化流程。理解这套流程比记住几个设备树字段有用得多因为所有疑难杂症最后都能追溯到流程里某一步没走对。4.1 probe 阶段的完整动作序列内核 Goodix 驱动的 probe 流程大致如下获取reset和irq两个 GPIO 描述符。将 RST 拉低保持一段时间后释放等待芯片内部上电初始化完成。读取 0x8140 到 0x8143 的 Product ID确认芯片型号。根据型号匹配配置区起始地址等参数。把内核里内置的默认配置数据写入芯片配置寄存器。计算配置区所有字节的累加和把结果写入校验寄存器。再执行一次软复位让新配置生效。注册中断注册 input 设备进入等待触摸状态。这套流程里最容易被忽视的是第 5 步到第 7 步。GT115x 内部没有掉电保存的 Flash所有工作参数都存放在易失的 RAM 里。也就是说每次上电芯片用的都是出厂默认配置主控必须在每次启动时主动把匹配这块屏的参数覆盖进去。默认配置可能来自芯片参考设计未必匹配你的 4.3 寸 800x480 模组所以驱动写配置这一步不是可有可无是必须执行的。4.2 为什么驱动每次启动都要“重新写配置”我把这个机制类比成一台没有 BIOS 的电脑CPU 上电后直接执行内存里的程序而内存里的程序需要由另一个更高权限的设备先加载进去。GT115x 就是这台没有 BIOS 的电脑主控就是更高权限的设备。如果主控不写配置芯片就用内置的一小段默认代码跑参数既不保证正确也不保证稳定。这也是为什么你在切换不同内核版本、或者从厂商 BSP 换到 mainline 内核之后触摸表现会变。不同版本的驱动内置的默认配置数据可能不同有的是针对 800x480 写的有的是针对 480x800 写的这会直接导致坐标方向、灵敏度和最大点数的差异。遇到换个内核触摸就不对的情况不要怀疑硬件损坏先看驱动内置配置和你的屏是否匹配。4.3 坐标数据帧从 0x814E 寄存器开始的数据包芯片把触摸坐标放在一段连续的寄存器里主控收到 INT 中断后从 0x814E 开始读取。数据帧格式大致如下偏移寄存器内容0x000x814E状态bit7 为 buffer readybit3~bit0 为触点数0x010x814F第 1 个触点的 Track ID0x02~0x030x8150~0x8151第 1 个触点的 X 坐标小端0x04~0x050x8152~0x8153第 1 个触点的 Y 坐标小端0x060x8154第 1 个触点的面积/大小0x07~0x0F0x8155~0x8157保留依次类推到第 5 个触点GT1151 最多支持 5 点触摸所以驱动一次最多读取 1 个状态字节加 5 组 8 字节数据。驱动把原始坐标解析出来后通过内核的 multi-touch protocol B 上报给 input 子系统也就是input_mt_report_slot_state加input_report_abs这一套。这里有一个非常重要的细节读完之后要不要清状态寄存器。有些厂商的旧版驱动在读取坐标后会向 0x814E 写一个 0作为对芯片的应答。如果你换用 mainline 驱动后出现第一次触摸正常、之后完全不响应很可能就是这个应答动作没有做芯片认为上一次数据还没被收走不再产生新的 INT。这个问题的信号特征非常明显我放在下一节详细讲。5. 三个实测问题从无响应到坐标乱飞的排查链路这一节是我最想写的内容。三个问题都是我在实际调试中遇到的而且都不是改一行代码就能好的级别需要完整走一遍排查链路才能定位。排查思路比最终答案更重要所以我会把每一步检查的逻辑讲清楚。5.1 问题一probe 成功、evtest 毫无反应现象内核日志里 Goodix 驱动 probe 成功/dev/input/下也出现了对应事件节点但手指摸上去evtest一个事件都不打/proc/interrupts里对应中断号计数纹丝不动。第一步确认驱动确实 probe 成功。用dmesg | grep -i goodix查看正常会看到读取到 Product ID 和配置版本号的日志。如果没有任何日志说明 driver 的 compatible 没匹配上或者设备树节点根本没被解析。第二步找到正确的 input 节点。用cat /proc/bus/input/devices查看设备列表通过设备名字或者物理地址确认触摸屏对应eventX编号。这一步很容易被忽略因为有些板子可能同时注册了多个 input 设备触摸屏可能不是 event0。第三步确认中断有没有触发。在触摸的同时执行cat /proc/interrupts | grep gpio看中断计数是否增长。如果计数不变说明中断线根本没把信号送到 CPU问题在硬件链路而不是驱动上报。我这块板子的最终根因是 pinctrl 里把 INT 对应的 GPIO 配置成了bias-pull-down。GT115x 的 INT 是低有效空闲状态应该是高电平芯片检测到触摸后把它拉低来触发下降沿中断。但由于 GPIO 被下拉电阻强制拉低INT 一直处于低电平芯片再也没法产生从高到低的边沿于是中断永远不来。驱动 probe 能成功是因为 probe 阶段只用 I2C 通信不需要 INT 拉出边沿。修复方法是在 pinctrl 节点里把 INT 引脚改为bias-pull-up或者去掉 biaspinctrl_touch { fsl,pins MX6UL_PAD_GPIO1_IO09__GPIO1_IO09 0x1b0b0 ; };这里0x1b0b0里包含了上拉配置具体数值要查你对应平台 pinctrl 的编码规则。如果原理图上已经有外部上拉电阻直接在 dts 里写bias-disable也行。这个案例给我的教训是触摸芯片的 INT 空闲电平一定要用万用表或者逻辑分析仪实测不要想当然认为它一定是高。5.2 问题二第一次触摸正常之后完全没反应现象上电后第一次触摸evtest 能打出一两个事件然后无论怎么摸都没反应了/proc/interrupts计数停留在第一次触摸时的数字。如果你用的是厂商旧版 BSP 驱动这个现象十有八九是状态寄存器没有清除导致的。GT115x 的协议规定主控读完坐标后需要向 0x814E 写 0 来应答芯片告诉它数据我已经收走了你可以准备下一帧。旧版驱动一般会做这个动作但有些精简版或者移植的驱动漏掉了芯片发现状态寄存器还停在有数据的状态就认为主控还在处理于是不再触发新的 INT。排查链路先说结论这是中断触发模式和数据应答共同作用的结果。把设备树里的中断触发类型从IRQ_TYPE_EDGE_FALLING改成IRQ_TYPE_LEVEL_LOW问题会立即缓解因为只要芯片还拉着 INT 低电平电平触发的中断就能反复进入。但这只是绕过了 symptom不是修复根因。真正的修复是在驱动里补上读后清状态的操作在读完坐标数据后向 0x814E 写一个字节的 0。补充一点如果你在改设备树之前先验证过这个问题还可以用 i2ctransfer 手动清一次状态寄存器看触摸是否恢复i2ctransfer -f -y 2 w30x5d 0x81 0x4e 0x00这条命令把 0x814E 写为 0。如果执行后触摸立刻恢复基本就坐实了是应答缺失的问题。这个验证方法在排错现场非常管用建议记下来。5.3 问题三坐标镜像加 XY 对调现象触摸能用但手指往右滑光标往左跑手指往上滑光标往左跑总之坐标方向和屏幕方向对不上。这个问题的排查链路不是一上来就加设备树属性而是先读原始坐标。用 evtest 在屏幕上依次点击四个角记录每个角上报的ABS_MT_POSITION_X和ABS_MT_POSITION_Y值跟屏的实际分辨率做对比手指点击位置期望坐标实际坐标结论左上角(0,0)(799,0)X 轴镜像右下角(799,479)(0,479)X 轴镜像右上角(799,0)(799,479)Y 轴镜像左下角(0,479)(0,0)Y 轴镜像如果左上角报到右下角的位置也就是 X 和 Y 同时反了那很可能是芯片配置区把坐标分辨率写成了竖屏 480x800而你实际是横屏 800x480。这时候需要同时加touchscreen-swapped-x-y和两个方向属性因为不是单纯一个轴反了是整个坐标系旋转了 90 度。如果只有单个轴反了加对应的touchscreen-inverted-x或者touchscreen-inverted-y就行。这个属性在 mainline 的 touchscreen 解析框架里是标准支持直接在设备树里写不需要改驱动代码。还有个容易被忽略的细节如果屏幕模组本身有物理上的安装方向问题比如你把屏反过来装到外壳上那么坐标系镜像是正常的。遇到这种情况改软件坐标方向前先确认屏的物理方向别让软件去迁就硬件的错误安装。5.4 快速排查表把上面三节的经验整理成一张表方便以后遇到类似问题快速对照现象先查什么常见根因处理方式probe 无日志内核配置、compatible 字符串驱动没编译、匹配表不对开 CONFIG_TOUCHSCREEN_GOODIX检查驱动匹配表probe 成功但无事件/proc/interrupts 计数INT 引脚被下拉、中断触发类型不对检查 pinctrl bias改用 LEVEL_LOW 验证第一次正常之后失灵清状态寄存器读后未应答 0x814E补写 0 应答或改用旧版驱动坐标镜像evtest 角落坐标设备树方向属性缺失按实测结果加 inverted/swapped坐标 X/Y 对调芯片配置区的分辨率方向配置是竖屏 480x800重写芯片配置或加 swapped-x-y休眠后唤醒不可用wakeup-source 属性、suspend 回调配置在休眠后丢失加 wakeup-source确认复位重发配置6. 收尾把触摸调试当成一次外设验收而不是修驱动最后分享三点我这几轮调试下来的体会。第一所有驱动问题最终都是通信或者时序问题。GT115x 的 I2C 通信本身不复杂一旦出现诡异现象先回退到最基础的三项检查供电是不是 3.3V、SDA/SCL 能不能读出 Product ID、RST 释放后的延时够不够。三项全过再往设备树属性和驱动配置的方向排查不要一上来就怀疑内核驱动有 bug。第二把调试过程做成脚本。我在板子上留了一个简单测试脚本每次改完设备树重启后自动执行i2cdetect和evtest把输出存到日志文件里。这样前后两次改动之间的差异一目了然不用靠记忆对比。坐标方向问题用脚本打印四角坐标比肉眼判断可靠得多。第三给触摸芯片做一次配置快照。GT115x 的配置是易失的但调试时你可以通过 I2C 把芯片当前生效的配置读出来存成文件比如用i2ctransfer读配置区并保存到cfg.bin。以后如果换了驱动版本导致触摸表现变化把新旧配置比对一下能快速定位是不是配置数据引起的差异。这块 4.3 寸 800x480 屏现在在我手里已经稳定跑了一个多月触摸跟手、五点多点都没有问题。其实把原理讲透了GT115x 的移植并没有想象中那么玄乎它只是一颗需要主控伺候的触控协处理器。希望这篇记录能帮你少走几个弯路早点把屏调顺手。

Linux下GT115x触摸屏驱动移植实战：从设备树到中断排查

相关推荐

解决虚拟机IP漂移：手把手配置静态IP（CentOS/Ubuntu）

open-code-review：构建自动化代码评审工作流

从零构建代码评审自动化机器人：open-code-review 实战与避坑指南

更多资讯

2026图文带货必备：五款AI去水印与图文排版工具实测

Windows下Docker部署openclaw：从环境配置到迁移实战

本地化AI工作流：OpenAI协议兼容的私有化部署实践

校园食堂订餐系统毕业设计：Java+Spring Boot+MySQL完整实战指南

MySQL事务底层机制：从redo/undo到MVCC与锁的实践解析

大模型重塑移动端自动化测试：从痛点破局到智能落地实践

今日更新

悟空开源无代码平台实战：从实体建模到应用设计避坑指南

基于.NET9的多租户权限系统：数据权限与动态API落地实践

场地预约小程序毕设实战：SSM+微信小程序+MySQL数据库设计到避坑

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？