全志T113-S3点亮ST7789V SPI屏：设备树与内核配置全流程

做嵌入式Linux这几年，屏幕点亮这种事永远是新板卡bring-up的第一道门槛。尤其是SPI接口的小屏，原理上就那么几根线，可真到设备树、内核、驱动一层层往下翻的时候，细节多到足够熬一个通宵。这次完整记录一下我为100ASK T113-S3核心板点亮一块ST7789V SPI屏的过程，从硬件接线、设备树写法、内核配置到最后的fb-test验证，整条链路走一遍，方便以后少踩坑。

板子用的是百问网那套100ASK T113-S3核心板加底板，核心是全志T113-S3，双核Cortex-A7配一颗RISC-V协处理器，带64MB DDR3，跑Linux很典型的低成本方案。屏是常见的中景圆1.3寸240x320 ST7789V IPS小板，四线SPI接口。这套组合在工业屏显、智能家居面板、仪表盘项目里出镜率很高。这篇文章适合手里正好有T113-S3、或者在做类似全志平台SPI屏bring-up的朋友，就算你用的不是这块屏，只要驱动IC是ST7789、ILI9341、ST7735这些，思路一模一样。

1. 项目背景与硬件准备

1.1 T113-S3核心板与SPI屏选型

先简单交代一下硬件平台。全志T113-S3是一颗内置DDR3L的异构SoC，双核ARM Cortex-A7频率最高到1.2GHz，外加一颗主频200MHz的RISC-V核，主要用于跑E907 RTOS做实时控制。整个CPU封装里直接集成了内存，做核心板能把板子面积压得很小，集成度高的同时成本也低，所以很多百元级Linux Linux开发板、串口屏、HMI都选这颗料。

100ASK T113-S3核心板把电源、DDR、Flash都做好了，通过邮票孔引出一堆IO，外接底板扩展。我这里用的是他们配套的独立底板，板上引出了多路SPI、I2C、UART等接口。屏选的是ST7789V驱动的1.3寸IPS屏，分辨率240x320，四线SPI协议，模块上自带LDO稳压、SD卡槽（不用）、3.3V电平转换。SPI屏的好处就是IO占用少，CLK、MOSI、CS、DC、RESET、BL加起来六根线，对于核心板引线紧张的场景非常友好。

1.2 硬件接线与电平检查

拿到屏先不要急着通电，把模块原理图和数据手册的接线表抄下来，确认每个引脚的意义。ST7789V模块常见引脚包括VCC、GND、SCL（即SCK）、SDA（即MOSI）、CS、DC（也叫RS）、RESET、BL。我这次接线按以下表格来：

这里要特别提醒一句，DC引脚千万不能图省事接到GND或VCC上。ST7789V在四线SPI模式下没有单独的地址线，主控是用DC引脚的电平来区分当前发送的是命令还是显存数据。DC为低表示这个字节是命令，DC为高表示这个字节是数据。如果DC处理不对，驱动发的初始化命令和数据全乱套，屏要么白屏要么花屏。另外RESET引脚建议接一个真正的GPIO而不是直接接上拉，因为驱动在初始化前需要给一个完整的低脉冲时序，很多屏就是因为硬件复位时序不对，后面初始化指令怎么发都白搭。

接线完成后先检查一遍电压：用万用表确认屏模块VCC对GND是3.3V左右，再把背光引脚临时接3.3V，如果模块好，背光应该能亮起来，这时候屏是白屏是正常的，因为还没初始化。这个步骤能提前排除掉模块本身坏掉或者供电不足的问题。

1.3 初上电验证与SDK准备

硬件确认正常后，准备好Ubuntu下的交叉编译环境。T113-S3的Linux SDK通常有三种获取方式：百问网的资料包、全志公开的Tina SDK、或者用Buildroot从源码构建。我这边用的是SDK自带的Buildroot环境，交叉编译器用的是ARM Cortex-A7通用的arm-linux-gnueabihf-。

如果是从零开始，建议先把SDK解压出来，跑一遍官方的环境初始化脚本。确认环境变量ARCH=arm、CROSS_COMPILE=arm-linux-gnueabihf-已经export，然后进到kernel/目录，先编一次出厂默认配置，确认SDK本身没问题。这一步虽然耗时，但能确保后面报错的时候，不是因为你环境坏了，而是因为你自己改动引入的问题。

2. 驱动框架选型与内核配置

2.1 fbtft还是DRM panel？

Linux内核里驱动SPI屏，目前能看到两条路线。一条是老的fbtft框架，对应的内核配置项是CONFIG_FB_TFT_ST7789V，注册出来的节点直接就是/dev/fbN，用起来很直接，fb-test、fbset这些工具开箱即用。另一条是DRM框架下的panel驱动，对应配置项是CONFIG_DRM_PANEL_SITRONIX_ST7789V，走的是drm_panel+drm_connector这套标准流程，同时通过DRM的fbdev仿真层也能生成/dev/fb0。

那到底选哪个？我的建议是新内核、新SDK直接用DRM panel。原因有三个：第一，fbtft内核维护者已经很少更新，在5.10以上的内核里很多功能有明显的滞后感；第二，DRM panel是显示子系统未来的标准，后面如果要把这个屏和RGB屏做多屏、叠加、旋转这些高级操作，DRM支持得更好；第三，T113-S3自带的显示引擎默认就和DRM接轨，走DRM驱动可以减少很多冲突。唯一的小麻烦是DRM框架概念多一些，需要理解panel和connector的关系。

如果你的SDK内核版本还停留在4.9、5.4这种老内核，而且你只是想快速出图，走fbtft也不是不行，设备树写法差不多，只是最终节点不依赖DRM。这篇文章后续以DRM panel为主线来写。

2.2 内核配置项逐条说明

确认使用DRM panel之后，在内核源码目录运行make menuconfig，把下面几个关键项配置好：

• CONFIG_DRM=y或者CONFIG_DRM=m，DRM核心框架，必须开
• CONFIG_DRM_PANEL=y，panel框架层的总开关
• CONFIG_DRM_PANEL_SITRONIX_ST7789V=y，这是ST7789V的panel驱动，如果驱动IC是ILI9341则选对应的CONFIG_DRM_PANEL_ILITEK_ILI9341
• CONFIG_DRM_FBDEV_EMULATION=y，这个非常关键，不开的话DRM框架不会生成/dev/fb0，后续fb-test就没法用
• CONFIG_FB=y，fbdev基础框架，配合DRM emulation使用
• CONFIG_BACKLIGHT_CLASS_DEVICE=y，背光设备class框架，如果背光走GPIO或PWM都需要依赖它
• CONFIG_BACKLIGHT_PWM=y，仅当使用PWM背光时开

配置路径大概在Device Drivers -> Graphics support -> DRM -> Panel drivers -> Sitronix ST7789V panel driver。菜单里不一定能看到中文，但英文名字就是上面这些。如果使用make t113_100ask_defconfig这种SDK默认配置，一般DRM框架默认已经打开了，你只需要确认panel驱动和fbdev emulation有没有被选上。

配置的时候顺便看一眼有没有把多个panel驱动都编进内核。比如你内核默认带了RGB屏的驱动，可能影响DRM device的创建顺序，带来莫名的问题。我这里关闭了不需要的显示控制器相关驱动，减少变量。

2.3 交叉编译环境验证

在Ubuntu上编译内核前，先检查交叉编译工具链是否可用。比较稳的命令：

source /your/sdk/path/build/envsetup.sh export ARCH=arm export CROSS_COMPILE=arm-linux-gnueabihf- arm-linux-gnueabihf-gcc -v

看到版本信息后，进入kernel/目录，先编译一次原来的配置确保链路是通的：

make t113_100ask_defconfig make -j$(nproc)

这一步能过，说明你的工具链和SDK源码基本没有大问题。如果我按官方教程第一次编译就卡在头文件缺失、找不到lib等报错，优先检查是不是SDK里带了固定的toolchain路径，别自己乱装了一个新工具链就硬编。很多“最坑”的编译错误，其实都是交叉编译器版本和老内核头文件不匹配导致的。

3. 设备树配置详解

3.1 SPI控制器与pinctrl配置

设备树是整个SPI屏bring-up的核心环节。T113-S3内部有多个SPI控制器，具体哪个可以用要看SoC的引脚复用关系。我这边选用了SPI1，对应设备树节点为&spi1。在设备树里做两件事：一是打开SPI控制器，二是设置引脚复用为SPI功能。

引脚复用由pinctrl子系统完成。需要根据原理图确认CLK、MOSI、CS这块实际连到T113-S3的哪个pad，我这里是PE0-PE3四根线。设备树中先定义一组pinctrl：

&pio { spi1_pins: spi1-pins { pins = "PE0", "PE1", "PE2", "PE3"; function = "spi1"; bias-pull-up; }; };

然后SPI控制器节点改成这样：

&spi1 { pinctrl-names = "default"; pinctrl-0 = <&spi1_pins>; status = "okay"; };

为什么必须写pinctrl-names和pinctrl-0？因为Linux驱动在probe阶段会主动去解析这两个属性，主动把引脚复用切到spi1功能。如果只写了status = "okay"而没配pinctrl，默认引脚可能还是GPIO输入模式，时钟和数据信号完全出不去，屏怎么都不可能亮。

注意，如果SPI控制器挂的是Nor Flash而不是屏，不要再往同一个控制器下面加panel节点，片选和内容会冲突。T113-S3的SPI0在很多板卡上被系统Flash占用，所以SPI屏尽量挂在SPI1上，这是一个很实用的经验。

3.2 SPI屏panel节点配置

在&spi1节点下添加一个panel子节点。ST7789V DRM面板驱动的绑定说明，compatible字符串应该写成sitronix,st7789v。完整写法如下：

&spi1 { pinctrl-names = "default"; pinctrl-0 = <&spi1_pins>; status = "okay"; st7789v_panel: st7789v@0 { compatible = "sitronix,st7789v"; reg = <0>; spi-max-frequency = <20000000>; rotate = <90>; rgb-order = "rgb"; fps = <30>; reset-gpios = <&pio PE 5 GPIO_ACTIVE_LOW>; dc-gpios = <&pio PE 4 GPIO_ACTIVE_LOW>; backlight = <&backlight>; status = "okay"; }; };

逐个属性说清楚：

• reg = <0>对应接在SPI控制器的CS0上，也就是硬件上片选线连的引脚。如果接CS1，这里写成1。
• spi-max-frequency是软件告诉Linux SPI主控制器给这个设备发送数据时的最高时钟。ST7789V手册标称四线SPI最高到32MHz，但实际用杜邦线连接时，我一般都先降到20MHz，等确认没问题再往上提。为什么？因为杜邦线、排针的寄生电容和串扰很大，高频下波形明显畸变，信号质量差到一定程度就会出现花屏，而且这个花屏还是偶发的，排查起来非常折磨人。
• rotate是驱动支持的面板旋转角度，可选0/90/180/270。如果你的屏画面上下面倒置，不要急着在应用层翻转，直接把这里改成90或者270就行，驱动会通过MADCTL寄存器把扫描方向调对。
• rgb-order控制颜色分量是RGB还是BGR。有些屏模块的像素排布就是BGR，如果这里配置错，画面颜色会偏，红蓝互换。
• reset-gpios配PE5，低有效，驱动在初始化前会先拉低再拉高，完成硬件复位。
• dc-gpios配PE4，低有效这个说法容易误解，实际DC引脚是“低=命令、高=数据”，属性里的GPIO_ACTIVE_LOW仅表示驱动框架如何逻辑取反，最关键的是这个引脚必须确实被面板驱动控制，才能正确发送命令/数据。

3.3 背光节点配置

背光有两条路：PWM背光和GPIO背光。PWM效果细腻，亮度可调，但需要额外确认T113-S3的PWM控制器配置。GPIO背光简单粗暴，一个GPIO就能决定亮灭，非常适合先把屏点亮这个阶段。

我这里先用GPIO背光，设备树顶层节点这样写：

/ { backlight: gpio-backlight { compatible = "gpio-backlight"; gpios = <&pio PE 6 GPIO_ACTIVE_HIGH>; default-on; status = "okay"; }; };

然后在panel节点里已经用backlight = <&backlight>挂上了这个背光设备。这样做的意义在于，用户空间可以通过标准的/sys/class/backlight/gpio-backlight/brightness接口直接开关背光，驱动也会在probe后自动把背光设备enable起来。

如果你确定要用PWM背光，节点改成这样：

/ { backlight: pwm-backlight { compatible = "pwm-backlight"; pwms = <&pwm 0 5000000 0>; brightness-levels = <0 10 20 30 50 70 90 255>; default-brightness-level = <7>; }; };

这里pwms里的5000000单位是纳秒，对应200Hz的PWM频率，屏幕背光在200Hz以上基本看不到闪烁。还是那句话，先把GPIO背光跑通，后面再换PWM不迟。

3.4 设备树编译与检查

设备树写好后，不能直接在源码目录里肉眼检查就完事，要编译成dtb再逆编译验证。命令如下：

make dtbs

如果有语法错误，编译过程会直接报错。编译通过后，用dtc工具把dtb转回dts看看内容：

dtc -I dtb -O dts arch/arm/boot/dts/sun8i-t113s3-100ask.dtb | grep -A 20 "st7789v"

确认面板节点、背光节点都在。这个步骤很值得做，因为设备树编译有时候会把不合法属性默默地丢掉，或者被__overrides__机制改了，肉眼看不出来，逆编译之后能看到真实生效的树结构。

如果板子已经能启动，也可以启动后在板子端用ls /proc/device-tree/st7789v@0确认设备树有没有加载到内核里。不过这一步通常等烧录后再说。

4. 内核编译与烧录启动

4.1 menuconfig开启选项

进入内核源码目录，执行：

make menuconfig

逐项确认：

Device Drivers -> Graphics support -> <*> DRM driver support for Allwinner SoCs [*] Enable legacy fbdev support <*> Panel driver -> Sitronix ST7789V panel driver Device Drivers -> Backlight & LCD device support -> <*> Lowlevel Backlight controls <*> GPIO Backlight Driver

如果SDK默认CONFIG_DRM_*已经开了，但panel驱动没开，这里手动选上就行。选完保存退出，最好diff一下.config确认改动的位置。这一步我建议每次改配置前备份.config，因为make的时候偶尔会静默地把一些依赖项改掉，出问题回溯很麻烦。

4.2 编译内核并生成boot镜像

配置完成后开始编译：

make zImage -j8 make dtbs

zImage生成位置在arch/arm/boot/zImage，设备树文件在arch/arm/boot/dts/。如果需要打包成Android风格的boot.img，可以用SDK自带的mkbootimg工具：

mkbootimg --kernel arch/arm/boot/zImage \ --dtb arch/arm/boot/dts/sun8i-t113s3-100ask.dtb \ --output boot.img

如果直接使用Buildroot整包编译，一般make之后会在output/images里生成完整的烧录镜像。我觉得SPI屏调试阶段最好别每次烧整个系统镜像，太慢了。直接把boot.img单独打包替换启动分区，启动链路不变，调试循环会快非常多。

4.3 烧录启动并盯dmesg

烧录方式取决于你的板卡支持SD卡启动还是EMMC写入。100ASK T113-S3底板一般提供PhoenixUSB烧录口，用PhoenixSuit软件可以直接烧录整个镜像；如果只是更新内核，也可以接SD卡启动，把boot.img放到SD卡对应分区。

烧录后上电，立刻在串口终端盯内核日志，重点关注两行：

dmesg | grep -i st7789 dmesg | grep -i panel

正常情况下能看到类似：

st7789v spi1.0: probed panel-st7789v spi1.0: fb0: ST7789V frame buffer device

如果只看到设备被注册但报failed to get GPIO之类，说明设备树里的reset-gpios、dc-gpios引脚的宏写错了，回去翻include/dt-bindings/gpio/gpio.h确认GPIO_ACTIVE_LOW宏的数值和含义。

再把/sys/class/drm/目录列出来：

ls /sys/class/drm/

能看到card0-DSI-1或者card0-DPANEL-1这种节点，说明DRM面板已经注册成功。到这里内核侧基本就结束了，剩下就是应用层测试。

5. fb-test测试与显示验证

5.1 确认framebuffer设备

前面开了DRM fbdev emulation，启动后查看：

ls -l /dev/fb* cat /proc/fb

如果看到0 st7789v或者0 panel-uixxxxx，说明fb0已经属于这块屏了。/proc/fb输出第一列数字就是fb设备编号，后面的名字是驱动identify里注册的。假如fb0被其他显示设备抢占了，你得去查有没有多个DRM设备，或者把不需要的显示控制器在内核里关掉。

查看分辨率信息：

fbset -fb /dev/fb0 -xres 240 -yres 320 -vxres 240 -vyres 320 -depth 16 fbset -fb /dev/fb0

-depth 16是ST7789V最常见也是驱动默认的RGB565格式，每个像素16bit，高5位红、中间6位绿、低5位蓝。如果你的屏是18bit RGB666，某些场景下颜色饱和度和条纹问题会比较明显，先不管，16bit足够测试。

5.2 fb-test工具基本用法

fb-test是一个专门用来做framebuffer显示测试的小工具，在Buildroot里直接勾选fb-test，或者Ubuntu下apt install fb-test交叉编译。如果SDK没有带这个包，源码也就几百行，手动编译也不难。

板子端运行：

fb-test

屏幕上会依次呈现纯红、绿、蓝、白、黑等画面和一些条纹，按键切换。命令本身的参数不多，支持-r红色、-g绿色、-b蓝色、-w白色等：

fb-test -r fb-test -g fb-test -w

如果你只是要快速验证framer，不改fbset分辨率直接跑fb-test，画面可能只占了屏幕一角或者显示错乱。所以先跑一遍fbset把分辨率设对，再跑fb-test。很多朋友第一次测屏发现显示不全，问题就出在这。

5.3 不依赖工具直接写像素验证

有时候设备上没装fb-test，或者你更想验证自己在用户空间操作framebuffer的能力。可以写一个超级简单的C程序，往fb0里填纯色：

#include <stdio.h> #include <fcntl.h> #include <sys/mman.h> #include <sys/ioctl.h> #include <linux/fb.h> int main(void) { int fd = open("/dev/fb0", O_RDWR); if (fd < 0) { perror("open /dev/fb0"); return -1; } struct fb_var_screeninfo vinfo; ioctl(fd, FBIOGET_VSCREENINFO, &vinfo); unsigned short *fbp = mmap(NULL, vinfo.xres * vinfo.yres * vinfo.bits_per_pixel / 8, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); if (fbp == MAP_FAILED) { perror("mmap"); return -1; } unsigned short red = 0xf800; /* RGB565 红色 */ unsigned short green = 0x07e0; /* RGB565 绿色 */ unsigned short blue = 0x001f; /* RGB565 蓝色 */ for (int i = 0; i < vinfo.xres * vinfo.yres; i++) { if (i < vinfo.xres * vinfo.yres / 3) fbp[i] = red; else if (i < vinfo.xres * vinfo.yres * 2 / 3) fbp[i] = green; else fbp[i] = blue; } munmap(fbp, vinfo.xres * vinfo.yres * vinfo.bits_per_pixel / 8); close(fd); return 0; }

交叉编译后拷到板子运行：

arm-linux-gnueabihf-gcc -o fbcolor fbcolor.c adb push fbcolor /tmp/ chmod +x /tmp/fbcolor /tmp/fbcolor

如果横屏竖屏切换不对，可以顺便把设备树里rotate属性改一下重新编译。这个写像素的过程，比单纯看fb-test画面更能确认颜色排布是否正确，RGB565的高低字节顺序对不对，实测很管用。

还有一个更省事的方式，直接dd写一段数据到fb0，效果也很直观：

dd if=/dev/urandom of=/dev/fb0 bs=1024 count=50

看到雪花状的花屏，说明DMA路径和内存访问都正常，只是数据没有意义；看到纯色，说明framebuffer确实被映射到了屏上。如果你连这一步都没有任何显示变化，说明framebuffer数据根本没到屏上，问题多半在内核panel驱动或SPI通信，而不是用户空间。

6. 常见问题排查与避坑实录

6.1 白屏/黑屏问题

白屏在SPI屏调试里是最经典的现象。白屏说明背光和供电没问题，但panel没有接收到有效初始化命令，或者初始化过程中途失败了。排查顺序：

• 先看dmesg有没有st7789v的probe日志。如果没有，设备树compatible没对上，或者panel节点没挂进SPI总线，检查reg和status。
• 如果有probe日志但白屏，重点查reset时序。驱动拉低reset引脚后必须保持足够时间再拉高，有些屏模块的复位引脚接了个大电容，延时不够会复位不彻底，可以试试把驱动里reset delay调长，或者硬件上手动短接一下RESET到地再松开，看屏是否出了初始化效果。
• 检查DC引脚。DC接错会导致所有命令被当成数据送到显存，看起来就是屏白得发光。用万用表量一下驱动probe期间DC引脚有没有电平变化。
• 检查SPI时钟。把spi-max-frequency降到8MHz，排除信号完整性导致的初始化命令被误码。

6.2 花屏/颜色不对问题

花屏分两种：画面有内容但错乱，和颜色整体偏色。画面错乱一般是分辨率、扫描方向或SPI时序问题。先在设备树里把rotate调整一遍，常见是0和90的差异。如果旋转属性改完还是花，把spi-max-frequency降下来再测。为什么高频会花？ST7789V对SPI时序要求其实不高，但杜邦线连接时寄生电容会把上升沿拉慢，在高bitrate下一个bit的建立时间都不够，数据就采错了。工业底板如果走线短而均匀，上到30MHz都不一定有问题，调试期先用10-20MHz是稳的办法。

颜色偏色主要是rgb-order配置错误，把rgb改成bgr重新编译设备树就好。注意DRM panel驱动的rgb-order属性不是所有内核版本都支持，如果你内核较老，可能需要在内核的驱动源码里直接改panel->rgb_order，这个不太优雅，但能解决问题。

6.3 /dev/fb0未生成

/dev/fb0不存在，多半不是panel驱动问题，而是fbdev仿真层没开。确认内核配置里CONFIG_DRM_FBDEV_EMULATION=y、CONFIG_FB=y。有时候虽然编译进去了，但fbdev emulation要求在用户空间有/dev/dri/card0权限，跑fb-test时如果是root用户一般没问题，如果用的是普通用户，要先chmod 777 /dev/dri/card0或者使用udev规则。

也可能系统里存在多个显示设备，如RGB LCD、HDMI同时注册，fb0被非SPI屏占用。此时先用cat /proc/fb看清楚哪个fb是ST7789V，如果是fb1之类，直接fbset -fb /dev/fb1来测试。真正常用的办法还是在设备树里只保留SPI panel，把用不到的显示控制器全部disable，这样fb0一定是你的屏。

6.4 背光不亮问题

背光不亮有两种情况：一是背光控制的GPIO没有正确配置，二是背光设备树节点没被panel引用。如果用的是gpio-backlight，启动后执行：

cat /sys/class/backlight/gpio-backlight/brightness

默认应该是255，如果不是，手动写一下：

echo 255 > /sys/class/backlight/gpio-backlight/brightness

如果手动写完背光亮了，说明硬件通路没问题，是设备树里default-on属性没生效或者驱动probe失败。还有种情况最常见：屏模块的背光引脚直接接GPIO，但模块上背光串阻很大导致电流不足，这时候量一下背光引脚电压，如果驱动能力不够，用一个三极管或者MOS管做开关控制背光，不要直接让GPIO去推。

6.5 一个实操汇总表

把我在这个项目里遇到的关键问题整理成速查表：

调试的时候我习惯每改一次设备树，就把dtb逆编译一次对比差异，确认改动真的进了二进制镜像。这个方法虽然土，但在多个overlay叠加、SDK自动处理设备树的地方，能避免很多“明明改了却不生效”的诡异问题。

这次点亮过程中，我最大一个体会是：SPI屏bring-up，八成的坑不是驱动代码本身，而是硬件信号、引脚复用、设备树属性这些“看起来没技术含量”的地方。特别是GPIO背光和DC引脚，就两个电平的事，搞错了能折腾你一晚上。先把频率压低、把引脚核对清楚、把dmesg每一行都看明白，剩下的事情水到渠成。另外一个建议是，调试阶段尽量用相同品牌、相同接口的屏做替换验证，排除屏个体差异，很多花屏问题换一块屏就好了，别死磕代码。如果后面想做亮度调节、睡眠唤醒、局部刷新这些高级功能，只要这次设备树框架搭对了，都是顺水推舟的事。