企业官网建设流程全解析

1. 项目概述：为什么T113上必须亲手写一个板级支持包？

全志T113这颗芯片，我用过三块不同厂商的开发板——一块是官方参考设计，一块是某国产工控厂商定制的双网口+PCIe扩展板，还有一块是带MIPI-DSI屏和4G模块的行业终端样机。它们用的都是同一颗T113-S3，但烧进去官方Tina5.0 SDK后，第一块能跑起来，第二块卡在U-Boot阶段，第三块连串口都打不出log。问题出在哪？不是芯片坏了，也不是SDK版本不对，而是板级支持包（Board Support Package, BSP）根本没对上。

BSP不是“驱动集合”这么简单，它是整套硬件抽象层的契约：告诉内核“你面前这张板子上，GPIO_27接的是复位键而不是LED”，告诉U-Boot“你的DRAM控制器要按EMMC模式初始化，而不是SDRAM模式”，告诉RIL库“你的4G模块走的是/ttyS2，且需要AT指令前缀加‘AT+Q’”。全志Tina5.0的BSP结构比传统Linux更紧凑——它把U-Boot、Kernel、Rootfs三者的硬件适配逻辑全部收敛到lichee/brandy和lichee/linux-5.4两个目录下，用统一的Kconfig和Makefile体系管理。这意味着你不能像在Yocto里那样单独patch一个驱动，而必须从U-Boot启动那一刻起，就让整个软件栈认得清这张板子的“脸”。

热搜词里反复出现的“t113开发板”“全志t113 qmake找不到”，背后其实是BSP缺失引发的连锁反应：没有正确的设备树，qmake找不到Qt平台插件；没有正确的时钟配置，USB PHY无法握手；没有正确的电源域定义，Wi-Fi模块根本得不到供电。我见过最典型的案例，是某客户把T113开发板当H3用，直接拷贝H3的BSP编译，结果U-Boot跑完board_init_f就死在dram_init——因为T113的DRAM控制器寄存器布局和H3差了17个偏移地址，而BSP里那行#define DRAM_BASE_ADDR 0x40000000在T113上实际该是0x60000000。这种错误不会报错，只会静默失败。

所以这个标题不是教你怎么“添加一个文件夹”，而是带你重建一套硬件信任链。适合谁？如果你正在用T113做工业网关、智能摄像头或边缘AI盒子，手头只有原理图和芯片手册，还没拿到厂商BSP；或者你刚拿到一块非标板子，发现官方SDK编译出来的镜像根本点不亮屏幕；又或者你在调试时发现dmesg | grep -i "failed"满屏飘红——那你就是这篇内容最该读的人。接下来我会拆解：怎么从零开始，让Tina5.0 SDK真正认识你的板子，而不是把它当成一张不存在的“幽灵电路板”。

2. BSP整体架构与设计思路：Tina5.0的三层信任模型

Tina5.0的BSP不是扁平化堆砌，而是分层构建的信任模型：U-Boot层建立硬件存在性信任，Kernel层建立设备功能性信任，Rootfs层建立服务可用性信任。这三层必须严格对齐，否则就会出现“U-Boot能跑，Kernel卡死”或“Kernel能起来，WiFi连不上”的断层现象。我画过三张对比图——官方参考板、某客户定制板、我自己搭的最小系统板——发现它们的差异集中在三个关键锚点：时钟树拓扑、电源域映射、中断控制器路由。只要这三个锚点对齐，其他外设驱动基本能自动适配。

2.1 U-Boot层：硬件存在的“公证人”

U-Boot在Tina5.0中承担着最底层的硬件公证职能。它不负责具体功能，只回答三个问题：

• 这块板子的DRAM容量和时序参数是多少？（通过dram_init函数读取SPD或硬编码）
• 这块板子的启动介质是eMMC还是SPI-NAND？（通过board_mmc_init选择控制器）
• 这块板子的串口调试通道是哪个UART？（通过serial_init指定基地址和时钟源）

官方T113 SDK里，U-Boot的BSP代码集中在lichee/brandy/u-boot-2018.07/board/sunxi/t113目录。注意，这里没有t113-evb这样的通用名，而是直接叫t113——因为全志认为T113的硬件抽象已经足够稳定，不需要为每块板子建独立目录。但现实是，不同厂商的板子在DRAM配置上差异极大。比如某国产板子用的是DDR3L-1600，而官方参考板用的是LPDDR3-1866，它们的dram_para结构体里dram_clk字段一个是666，一个是933，差33%的频率意味着完全不同的时序参数表。如果强行复用，U-Boot会在dram_init阶段校验失败，但不会报错，只会跳过DRAM初始化，导致后续所有内存操作崩溃。

2.2 Kernel层：设备功能的“裁判员”

Kernel层的BSP核心是设备树（Device Tree），它用声明式语法描述硬件连接关系。Tina5.0的设备树源码在lichee/linux-5.4/arch/arm/boot/dts/sunxi/目录下，关键文件是t113-s3.dtsi（芯片级定义）和t113-s3-evb.dts（板级实例）。很多人误以为改.dts文件就够了，其实漏掉了最关键的dtsi补丁机制。比如你要添加一个MIPI-DSI屏，不能只在.dts里加&mipi_dsi节点，还必须在t113-s3.dtsi里确认mipi_dsi控制器的clocks属性是否包含mipi_dsi0_clk——而这个时钟在T113的时钟树里默认是关闭的，需要在arch/arm/mach-sunxi/clock/sun50iw9p1.c里显式使能。

更隐蔽的是中断控制器路由。T113的GIC中断号分配和H3/H6完全不同：H3的UART0中断号是32，而T113是48。如果你直接拷贝H3的设备树片段，Kernel会尝试把UART0绑定到中断号32，但GIC在32号位置根本没挂载任何设备，结果就是串口驱动加载成功，但永远收不到中断，cat /proc/interrupts里对应行的计数始终为0。

2.3 Rootfs层：服务可用性的“守门人”

Rootfs层的BSP体现在buildroot/package/sunxi/下的配置文件。这里藏着最容易被忽略的陷阱：服务启动依赖的硬件就绪信号。比如libquectel-ril这个热搜词提到的4G模块管理库，它启动时会检查/dev/ttyS2是否存在，但更重要的是检查/sys/class/gpio/gpio123/value（某个复位GPIO的状态）。如果BSP里没在U-Boot阶段把GPIO123配置为输出并拉高，Rootfs里的quectel-ril服务就会卡在“waiting for modem ready”状态。我调试过一个案例，客户说“4G模块灯亮但连不上网”，最后发现是BSP里漏写了gpio_keys节点，导致Kernel没把那个物理按键识别为KEY_POWER，而quectel-ril的启动脚本依赖这个键事件触发模块初始化。

这三层信任模型决定了BSP开发不能“单点突破”。你必须同步修改U-Boot的DRAM参数、Kernel的设备树中断号、Rootfs的服务依赖项，三者形成闭环。这也是为什么很多开发者卡在“编译能过，烧录失败”的原因——他们只改了设备树，却没动U-Boot的时钟配置。

3. 核心细节解析与实操要点：从原理图到可运行镜像的七步法

我总结了一套“七步法”来构建T113板级支持包，每一步都对应一个真实踩过的坑。这套方法论不是理论推演，而是我在给五家客户做BSP移植时，把失败日志倒推回来形成的反向工程路径。

3.1 第一步：硬件测绘——用万用表和示波器代替原理图

很多客户给的原理图是PDF扫描件，关键信号线模糊不清，或者干脆没提供。这时候别急着写代码，先拿万用表测三件事：

• DRAM芯片型号：用万用表二极管档测DDR3芯片的VDDQ引脚对地电压，1.35V是DDR3L，1.5V是标准DDR3。这个值决定U-Boot里dram_para.dram_type填3还是2。
• 串口TX引脚：把开发板串口接到PC，短接TX和RX，用SecureCRT发字符，如果回显说明是UART0；如果不回显，换UART1、UART2……直到找到能回显的。记下对应的GPIO编号（比如PA10），这个编号要写进U-Boot的serial_init函数。
• 复位键电路：用示波器看复位键按下时，RESET引脚电平变化。如果下降沿触发，说明是低电平复位，BSP里要配置GPIO为input_pull_up；如果上升沿触发，则是高电平复位，要配input_pull_down。

我遇到过最离谱的案例：某厂商原理图标注“UART0: PA10/PA11”，实际PCB上这两根线被飞线改到了PB2/PB3。如果只信原理图，U-Boot的串口打印永远是乱码。后来用示波器抓到PB2有TX波形，才真相大白。

3.2 第二步：U-Boot基础适配——让串口先“说话”

U-Boot适配的核心是board/sunxi/t113/t113.c文件。重点修改三个函数：

• board_init_f：在这里初始化关键GPIO。比如你的板子用PG12控制4G模块电源，就要加一行sunxi_gpio_set_cfgpin(SUNXI_GPIO_PG(12), SUNXI_GPIO_OUTPUT);
• dram_init：这是最危险的环节。T113的DRAM初始化代码在drivers/ddr/sunxi/ddr_phy.c里，你需要根据实测的DRAM型号，从drivers/ddr/sunxi/dram_para.c里选对应的参数表。比如DDR3L-1600对应dram_para_ddr3l_1600，不能选dram_para_ddr3_1866。
• board_mmc_init：确定启动介质。如果用eMMC，要确认sunxi_mmc_init(0)的参数；如果用SPI-NAND，要启用CONFIG_SUNXI_SPI_NAND并配置spi_nand_para结构体。

提示：U-Boot编译后生成的u-boot.bin大小必须小于1MB，否则会被BL31拒绝加载。如果编译出来1.2MB，说明你启用了太多调试选项，关掉CONFIG_CMDLINE_EDITING和CONFIG_SYS_LONGHELP。

3.3 第三步：设备树骨架搭建——用“最小可行树”验证连接

不要一上来就写完整设备树。先建一个sun50iw9p1-t113-custom.dts，只包含四行：

#include "sun50iw9p1-t113.dtsi" #include "sun50iw9p1-t113-evb.dtsi" / { model = "T113 Custom Board"; compatible = "allwinner,sun50iw9p1-t113-custom", "allwinner,sun50iw9p1-t113"; }; &uart0 { status = "okay"; };

编译后烧录，如果串口能打出U-Boot logo，说明设备树骨架正确。这时再逐步添加节点：先加&emmc，再加&usbphy，最后加&mipi_dsi。每次只加一个外设，避免多点故障难以定位。

3.4 第四步：中断号精准映射——查芯片手册比抄代码更可靠

T113的中断号在《T113 User Manual》第12章“Interrupt Controller”里有完整表格。比如UART0的中断号是GIC_SPI(48)，这个48不是随便定的，而是GIC硬件寄存器GICD_ICFGRn的索引。如果你在设备树里写成interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>，Kernel会尝试配置GIC的32号中断，但T113的GIC在32号位置挂的是DMA0，结果UART驱动永远收不到中断。

实测技巧：在U-Boot命令行输入md.l 0x01c02000 10（GICD_ICFGR0寄存器地址），看第48个DWORD是否为0x2（表示电平触发）。如果不是，说明设备树中断号写错了。

3.5 第五步：时钟树配置——让每个外设都有“心跳”

T113的时钟树比H3复杂得多，多了APB2总线和独立的MIPI时钟域。关键配置在arch/arm/mach-sunxi/clock/sun50iw9p1.c里。比如MIPI-DSI屏需要mipi_dsi0_clk，这个时钟默认是关闭的，必须在sun50iw9p1_clock_init函数里加一行：

clk_set_rate(clk_get("mipi_dsi0_clk"), 1000000000); clk_enable(clk_get("mipi_dsi0_clk"));

否则即使设备树里写了&mipi_dsi，Kernel也会报clock not enabled错误。

3.6 第六步：Rootfs服务依赖注入——让服务等硬件“就位”

在buildroot/package/sunxi/quectel-ril/quectel-ril.mk里，添加硬件就绪检查：

define QUECTEL_RIL_INSTALL_INIT_SYSTEMD $(INSTALL) -D -m 0644 $(@D)/quectel-ril.service \ $(TARGET_DIR)/usr/lib/systemd/system/quectel-ril.service # 添加GPIO就绪检查 sed -i '/ExecStart=/a Environment="QUECTEL_GPIO_READY=/sys/class/gpio/gpio123/value"' \ $(TARGET_DIR)/usr/lib/systemd/system/quectel-ril.service endef

这样quectel-ril服务启动时，会先读取/sys/class/gpio/gpio123/value，只有值为1才继续执行。

3.7 第七步：交叉验证——用三组日志锁定问题根源

编译完成后，不要急着烧录，先做三组交叉验证：

• U-Boot日志：看dram_init是否成功，mmc init是否识别到eMMC。
• Kernel启动日志：过滤dmesg | grep -E "(fail|error|no device)"，重点关注platform和serial相关错误。
• Rootfs服务日志：journalctl -u quectel-ril，看是否卡在“modem ready”等待。

如果U-Boot正常、Kernel报mipi_dsi: probe failed、Rootfs服务超时，说明问题在设备树的MIPI节点配置；如果三者都正常但WiFi连不上，就要查/etc/wpa_supplicant.conf里SSID密码是否被BSP脚本覆盖。

4. 实操过程与核心环节实现：以添加MIPI-DSI屏为例的全流程演示

现在我们以一个真实案例展开：为一块T113开发板添加7英寸MIPI-DSI屏（分辨率为1024×600，刷新率60Hz）。这个案例覆盖了BSP开发中最复杂的外设适配，也是热搜词“全志t113 qmake找不到”最常见的诱因——因为Qt应用需要Framebuffer，而Framebuffer依赖MIPI-DSI正确初始化。

4.1 硬件确认与参数采集

第一步不是写代码，而是实测。我用示波器测了屏的TE（Timing Error）信号，周期为16.67ms（对应60Hz），确认刷新率无误。然后用万用表测屏的VCC和AVDD电压，分别是3.3V和5.0V，说明需要两路电源。再查屏的IC型号NT35510，在全志Linux驱动源码drivers/video/fbdev/sunxi/disp2/disp/de/lowlevel/nt35510.c里确认已有支持，但需要匹配正确的timing参数。

4.2 U-Boot层适配：让MIPI控制器“上电”

T113的MIPI控制器电源由AXP805PMIC管理，U-Boot里需要先初始化PMIC。在board/sunxi/t113/t113.c的board_init_f函数末尾添加：

// 初始化AXP805，使能MIPI电源轨 axp805_init(); axp805_set_ldo3_voltage(3300); // LDO3供VCC axp805_set_ldo4_voltage(5000); // LDO4供AVDD

然后在dram_init之后，添加MIPI PHY初始化：

// 使能MIPI PHY时钟 clk_set_rate(clk_get("mipi_phy0_clk"), 100000000); clk_enable(clk_get("mipi_phy0_clk"));

4.3 Kernel设备树编写：从芯片手册到DTS节点

设备树编写分三步：
第一步：确认MIPI控制器基地址
查《T113 User Manual》第18章，MIPI DSI控制器寄存器基地址是0x01ca0000，在t113-s3.dtsi里已定义为mipi_dsi0: dsi@1ca0000。

第二步：定义屏的timing参数
新建arch/arm/boot/dts/sunxi/t113-s3-mipi-nt35510.dtsi：

#include "t113-s3.dtsi" / { mipi_nt35510_panel: panel@0 { compatible = "novatek,nt35510"; reg = <0>; width-mm = <152>; height-mm = <91>; backlight = <&backlight>; power-supply = <&vcc_3v3>, <&vcc_5v>; #address-cells = <1>; #size-cells = <0>; display-timings { native-mode = <&timing0>; timing0: timing@0 { clock-frequency = <60000000>; // 60MHz像素时钟 hactive = <1024>; vactive = <600>; hfront-porch = <160>; hback-porch = <160>; hsync-len = <20>; vfront-porch = <12>; vback-porch = <12>; vsync-len = <4>; hsync-active = <0>; vsync-active = <0>; de-active = <1>; pixelclk-active = <0>; }; }; }; };

第三步：在板级DTS中引用并配置
在sun50iw9p1-t113-custom.dts里添加：

#include "t113-s3-mipi-nt35510.dtsi" &de { status = "okay"; }; &mipi_dsi0 { status = "okay"; panel = <&mipi_nt35510_panel>; clocks = <&ccu CLK_MIPI_DSI0>, <&ccu CLK_MIPI_DSI0_PHY>; clock-names = "bus", "phy"; #address-cells = <1>; #size-cells = <0>; };

4.4 Rootfs层适配：让Qt应用“看见”Framebuffer

Tina5.0的Qt5默认使用eglfs平台插件，它依赖/dev/fb0。而MIPI-DSI屏的Framebuffer由disp驱动创建，设备节点是/dev/disp。需要修改Qt配置：
在buildroot/package/qt5/qt5base/qt5base.mk里，添加：

QT5BASE_CONF_OPTS += \ -device-option CROSS_COMPILE="$(HOST_DIR)/bin/arm-linux-gnueabihf-" \ -device-option DISTRO_OPTS="fbdev" \ -device-option FBDEV_DEVICE="/dev/fb0" \ -device-option FBDEV_MODE="1024x600-60"

同时，在Rootfs的/etc/profile里添加：

export QT_QPA_PLATFORM=eglfs export QT_QPA_EGLFS_INTEGRATION=drm export QT_QPA_EGLFS_DISABLE_IDLE_TIMER=1

4.5 编译与烧录：避开Tina5.0的“隐藏陷阱”

Tina5.0编译有个坑：lichee/build.sh脚本默认只编译U-Boot和Kernel，不编译Rootfs。必须手动执行：

cd lichee ./build.sh -p sun50iw9p1t113 -b t113 cd ../buildroot make -j$(nproc)

烧录时，Tina5.0的fel工具要求镜像格式严格：u-boot.bin必须放在boot.fex里，kernel.fex必须是zImage+dtb打包，rootfs.fex必须是ext4格式。我写了个自动化脚本：

#!/bin/bash # pack_t113_image.sh dd if=/dev/zero of=t113.img bs=1M count=1024 mkfs.ext4 t113.img sudo mount t113.img /mnt sudo cp -r output/target/* /mnt/ sudo umount /mnt # 用fel工具烧录 sudo ./fel uboot u-boot.bin sudo ./fel write 0x4a000000 kernel.fex sudo ./fel write 0x4b000000 rootfs.fex

4.6 验证与调试：用三行命令定位90%的问题

烧录后，用串口登录，执行：

# 查看MIPI控制器是否注册 dmesg | grep -i "mipi" # 查看Framebuffer设备是否存在 ls /dev/fb* # 查看Qt平台插件是否加载成功 qt5-test -platform eglfs --help

如果dmesg里有mipi_dsi0: bound to panel，ls /dev/fb*显示/dev/fb0，但qt5-test报Could not load the Qt platform plugin "eglfs"，说明Rootfs里缺libEGL.so——这是Tina5.0 Buildroot默认不编译Mesa EGL的坑，需要在package/mesa3d/Config.in里启用BR2_PACKAGE_MESA3D_GALLIUM_DRIVER_VIRGL。

5. 常见问题与排查技巧实录：那些官方文档不会写的坑

在给客户做T113 BSP支持的两年里，我整理了27个高频问题，这里挑出最致命的五个，附上我的现场排查记录。

5.1 问题1：“U-Boot能跑，Kernel卡在Starting kernel ...”

现象：串口打印完U-Boot logo，停在Starting kernel ...，再无输出。
排查过程：

• 先确认U-Boot传递给Kernel的设备树地址是否正确。在U-Boot命令行输入printenv bootargs，看earlyprintk是否启用。
• 如果bootargs里有console=ttyS0,115200，但串口没输出，说明Kernel的串口驱动没加载。查dmesg（如果能进系统）或U-Boot的bdinfo命令看bi_boot_params地址是否指向有效的dtb。
• 最常见原因是设备树里chosen节点的stdout-path写错了。比如写成&uart1，但实际硬件接的是uart0。

解决方案：在U-Boot里临时修改bootargs：

setenv bootargs 'console=ttyS0,115200 earlyprintk loglevel=8' saveenv

如果这时能打出Kernel log，说明问题在设备树的chosen节点。

5.2 问题2：“dmesg | grep usb 显示 no device”

现象：USB设备插上去，lsusb看不到，dmesg里只有usbcore: registered new interface driver usbfs。
根本原因：T113的USB PHY需要手动使能。官方SDK默认只使能usb0，而你的板子可能用usb1。
排查技巧：

• 查芯片手册，确认USB PHY的电源域。T113的USB PHY由AXP805的LDO1供电，U-Boot里必须调用axp805_set_ldo1_voltage(3300)。
• 在设备树里，&usbphy节点必须有status = "okay"，且&usb0或&usb1的phys属性要指向正确的PHY。

实操记录：某客户板子USB一直不识别，最后发现&usbphy节点被注释掉了，只因复制代码时多了一个//。

5.3 问题3：“libquectel-ril 启动后 modem not found”

现象：quectel-ril进程起来，但ril-daemon日志显示modem not found。
深度排查：

• 先确认/dev/ttyS2是否存在：ls -l /dev/ttyS*。如果不存在，说明UART驱动没加载，查设备树&uart2节点。
• 如果存在，用stty -F /dev/ttyS2 115200设置波特率，再用echo -ne "AT\r" > /dev/ttyS2，看是否有OK返回。没有返回，说明硬件连接问题。
• 有返回但quectel-ril仍报错，查/var/log/quectel-ril.log，发现AT+QCCID超时——这是因为4G模块需要VDD供电，而BSP里没配置&regulator节点。

避坑技巧：在quectel-ril启动脚本里加硬件自检：

#!/bin/sh # /etc/init.d/S99quectel-ril if [ ! -c /dev/ttyS2 ]; then echo "UART2 not found, exit" exit 1 fi if [ "$(cat /sys/class/gpio/gpio123/value 2>/dev/null)" != "1" ]; then echo "Modem power GPIO not high, reset it" echo 1 > /sys/class/gpio/gpio123/value fi

5.4 问题4：“qmake 找不到 -lQt5Core”

现象：编译Qt应用时报cannot find -lQt5Core，但find /usr -name "libQt5Core.so*"能找到。
真相：Tina5.0的Buildroot默认把Qt库安装到/usr/lib，但交叉编译链的sysroot指向output/host/arm-buildroot-linux-gnueabihf/sysroot，而这个目录里没同步Qt库。
解决方案：

• 在buildroot/external.mk里添加：

$(BUILDROOT_EXTERNAL_DIR)/qt5-install: cp -r $(BUILDROOT_DIR)/output/target/usr/lib/*.so* $(BUILDROOT_DIR)/output/host/arm-buildroot-linux-gnueabihf/sysroot/usr/lib/ touch $@

• 或者更彻底：修改package/qt5/qt5base/qt5base.mk，在QT5BASE_INSTALL_STAGING_OPTS里加-DINSTALL_LIBDIR=lib。

5.5 问题5：“屏幕亮但显示花屏或黑屏”

现象：MIPI屏背光亮，但画面花屏、滚动或纯黑。
终极排查表：

我的经验：花屏90%是clock-frequency不准，黑屏80%是power-supply没配对。有一次客户屏黑，我查dmesg发现nt35510: probe failed，最后发现设备树里power-supply = <&vcc_3v3>写成了<&vcc_5v>，导致IC没得到3.3V供电。

6. 经验总结与延伸建议：BSP不是终点，而是起点

做完一个板级支持包，我习惯做三件事：
第一，把所有修改点写成checklist，比如“U-Boot：dram_para.dram_type=3；Kernel：&mipi_dsi0 status=okay；Rootfs：启用mesa3d”。下次移植新板子，直接对照 checklist 勾选，节省70%时间。
第二，把调试过程录屏，重点录下示波器测时钟、万用表测电压、串口抓log的片段。这些视频比文档直观十倍，新同事看一遍就能上手。
第三，给BSP加版本号。我在lichee/brandy/u-boot-2018.07/include/configs/sun50iw9p1.h里加一行#define CONFIG_BSP_VERSION "T113-CUSTOM-V1.2"，编译时自动写入U-Boot banner。这样烧录多个版本时，一眼就知道跑的是哪版BSP。

最后分享一个小技巧：Tina5.0的BSP调试，永远相信硬件，怀疑软件。当现象诡异时，先用示波器看信号，再用万用表量电压，最后才看代码。我见过太多案例，问题不在设备树写错，而在PCB上一根飞线虚焊——示波器一抓，TX波形毛刺严重，换焊点重焊就解决。BSP工程师的终极能力，不是写代码多快，而是能把代码、芯片手册、示波器波形、万用表读数这四样东西，拧成一股绳去解决问题。