拿到一块STM32MP157D-DK1烧了官方镜像系统能跑但真到给板子加外设时设备树这关绕不开。我最初的想法是偷懒直接在运行中的系统里改/boot下的dtb结果发现开发板用的SD卡根本没有传统的/boot目录所有文件都放在FAT分区里没有任何“现成设备树编辑器”可用。上网一搜大部分教程都在让你走Yocto、bitbake光下载源码就能等半个下午。其实ST官方提供了Developer Package就是专门干这个的在PC本地编译U-Boot、内核和设备树再把产物拷到SD卡。这篇文章就是我基于STM32MP157D-DK1用Developer Package从零编译设备树的完整记录包括为什么需要它、环境怎么搭、命令怎么敲、怎么验证以及我实际踩过的几个坑。1. 双包机制下编译设备树的真实场景为什么不用bitbake1.1 开发者包与发行包的分工接触STM32MP1系列一段时间后会发现官方资料里反复出现两个名字Distribution Package和Developer Package。前者是完整的Yocto发行版源码下载下来好几个GB第一次构建镜像至少两小时起步好处是所有软件包都能从源码定制后者则面向只改BSP的场景里面包含一个成熟的交叉编译SDK、内核源码、U-Boot源码以及一堆预设好的配置文件。很多新手会误以为“改设备树必须用发行包”其实不是。设备树编译只依赖内核源码、交叉编译工具链和内核的构建脚本完全不需要Yocto那一整套环境。Developer Package的精妙之处在于它把SDK单独抽出来让你像平时编译普通Linux内核一样直接make一个.dtb文件。所以如果你的需求只是“把某个外设打开”“调整引脚复用”“加一个设备节点”根本不需要陷入bitbake的依赖地狱。但也要说清楚Developer Package不是万能钥匙。它更适合做BSP级别的增量修改比如设备树、内核驱动模块、U-Boot配置。如果你要裁剪rootfs、添加系统服务、定制整个镜像那还是回到Distribution Package更靠谱。设备树编译这件事恰恰是Developer Package的主场。1.2 设备树在STM32MP157上管哪些事STM32MP157D-DK1虽然是块评估板但硬件布线和资源占用并不简单。SoC内部有多个Cortex-A7核心、大量外设控制器系统起来后哪个引脚给I2C、哪个引脚给UART、哪个节点被禁用全都由设备树描述。在Linux下这不是一个配置文件的问题而是一组.dts和.dtsi源文件的问题。设备树主要描述四类信息SoC级IP信息寄存器基地址、中断号、时钟、板级硬件差异外设是否启用、GPIO扩展器地址、引脚复用状态pinmux、以及设备特定属性比如SPI设备的mode。在STM32MP157上最常见的修改就是第三种把某个引脚从默认的UART功能改成I2C或者把一个本来disabled的外设通过status okay打开。还有一个容易忽略的点STM32MP157D-DK1的设备树里led和button是官方默认启用的。如果你要把这些GPIO用来控制其他硬件就需要手动把对应的GPIO节点改掉或禁用否则两个驱动会争抢同一组引脚启动日志里会出现一串pin already requested警告。1.3 什么时候你必须走这条手动流程我在实际项目里总结出了三条“必须手动编译设备树”的路标。第一你需要在官方硬件上外接一颗传感器、或启用一个默认没打开的接口比如在DK1上点I2C4接一个触摸屏。官方镜像里的设备树已经把引脚分给其他功能了不改设备树基本没法用。第二你用自己的KiCad或者设计工具画了底板硬件布局和DK1不完全一致。哪怕只差一个GPIO的上下拉你也得自己维护一套板级设备树。第三你在做产品原型需要在同一份内核源码下同时管理DK1、DK2或者自己的板卡用不同dtb文件区分硬件版本。这个时候手动编译流程每天要跑很多次纯靠Yocto显然低效。如果你属于这三种情况之一下面这套操作就是给你准备的。2. 环境准备SDK安装、交叉工具链与容器化方案2.1 下载对应生态版本的Developer Package SDK从ST官网进入STM32MP1系列嵌入式软件页面下载Developer Package时会看到一个巨大的.sh文件通常叫en.SDK-x86_64-stm32mp1-openstlinux-5.10-xxx-linux-gnueabihf.sh。这个文件就是SDK安装脚本。我建议在干净目录下安装mkdir -p /opt/stm32mp1-sdk sudo sh ./en.SDK-x86_64-stm32mp1-openstlinux-5.10-*.sh -d /opt/stm32mp1-sdk安装完成后目录里会出现一个以environment-setup-开头的文件比如environment-setup-cortexa7t2hf-neon-vfpv4-openstlinux_weston-linux-gnueabihf。这个文件就是整个SDK的“总开关”后面所有编译工作都要先source它。有一点必须留意版本要跟你目标镜像的内核版本对应。如果你用OpenSTLinux 4.1生态内核是5.10换了其他生态版本SDK的内核头文件和工具链也会变。版本混用最典型的症状是设备树编译能过但板子启动后外设行为诡异因为生成的dtb格式或宏定义可能不匹配。2.2 source SDK环境后确认哪些变量变了每次打开新终端第一步都是source /opt/stm32mp1-sdk/environment-setup-cortexa7t2hf-neon-vfpv4-openstlinux_weston-linux-gnueabihf执行完后CC会变成arm-openstlinux_weston-linux-gnueabihf-gccPATH里也会加入SDK的交叉工具链目录。可以用which arm-openstlinux_weston-linux-gnueabihf-gcc验证能看到实际路径就是成功。不过我遇到过几次情况这个环境脚本不一定帮你设好ARCH和CROSS_COMPILE。编译内核设备树时我习惯手动再显式指定一次避免Makefile走到宿主机的x86默认配置上去export ARCHarm export CROSS_COMPILEarm-openstlinux_weston-linux-gnueabihf-这两个变量是整个编译流程的地基。ARCHarm告诉内核构建系统你编的是32位ARM平台CROSS_COMPILE指定交叉编译器的前缀。缺了哪一个都会出现奇怪错误比如生成的.dtb里混进x86架构的头文件。2.3 容器化编译方案懒人做法如果你不想在主力开发机上装一堆SDKDocker是个不错的选择。我自己就维护了一个编译用的Ubuntu 20.04容器把SDK安装脚本映射进去容器内完成后退出宿主环境保持干净。命令大致是这样docker run -it --rm -v /opt/stm32mp1-sdk:/sdk -v ~/work:/work ubuntu:20.04 bash进容器后装好基础运行库然后apt update apt install -y libncurses5-dev u-boot-tools bash /sdk/en.SDK-x86_64-stm32mp1-openstlinux-*.sh -d /opt/sdk-install后面所有编译步骤和宿主机完全一样。容器方案最大优势是方便CI把编译命令写进Dockerfile团队其他成员拉下来就能复现。但我个人的建议是如果你只是短期折腾直接装在Ubuntu宿主机上反而更省心因为SDK本身就是独立sysroot很少污染系统环境。2.4 工具链与内核版本的匹配问题STM32MP1系列使用Cortex-A7核心默认工具链是32位ARM版本所以编译器前缀里有arm而不是aarch64。这点经常有刚从ARM64平台转过来的朋友踩坑拿着aarch64-none-linux-gnu-gcc去编设备树虽然能编出来但某些内联汇编和头文件路径会不匹配导致启动时内核无法解析设备树。更稳妥的做法是只用Developer Package自带的工具链。这个工具链经过ST官方验证与内核源码中的stm32mp157*.dts所依赖的头文件是一致的。用其他工具链不是不行但没必要在环境这种基础环节上给自己增加变量。还有一种情况是系统里同时装了很多交叉编译器CROSS_COMPILE指定为arm-none-linux-gnueabihf-也可能会导致头文件路径不同。所以每次编译前我用echo $CROSS_COMPILE确认一下已经变成了一种肌肉记忆。3. 定位并修改DK1板级设备树源码树中的关键文件3.1 拉取内核源码并checkout到正确分支环境就绪后需要拿到内核源码。两种途径一是从Developer Package页面下载linux-*.tar.xz源码包二是从ST的GitHub镜像拉取linux仓库切到对应的v5.10-stm32mp-r1这类分支。如果从GitHub拉取建议加--depth 1 --branch限制历史不然仓库很大git clone --depth 1 --branch v5.10-stm32mp-r1 https://github.com/STMicroelectronics/linux.git kernel-source如果你下载的是tar.xz包直接解压到工作目录即可。接下来建议先看一眼源码树根目录确认里面确实有arch/arm/boot/dts/stm32mp157d-dk1.dts。如果该文件不存在检查一下你拉的分支是不是面向STM32MP157家族的。3.2 stm32mp157d-dk1.dts的继承关系与include图在arch/arm/boot/dts目录下stm32mp157d-dk1.dts这个文件本身通常很小也就几十行。它做的事情主要是#include一堆公共文件再定义model和compatible属性。打开它你会看到类似这样的结构/dts-v1/; #include stm32mp157.dtsi #include stm32mp157d.dtsi #include stm32mp15xx-dkx.dtsi ...真正管板级外设的配置大部分在stm32mp15xx-dkx.dtsi这个公共板级文件里。DK1和DK2的不少外设配置是共享的所以当你需要改I2C、SPI、UART、GPIO时第一反应不应该是打开stm32mp157d-dk1.dts而是先去公共文件里搜索对应节点。另一个常用操作是搜索别名。比如想找i2c4直接grep -n i2c4 arch/arm/boot/dts/stm32mp15xx-dkx.dtsi这个命令能帮你快速看到节点是在哪个层级定义的、当前status是什么、引用了哪个pinctrl。我调试外设时超过一半的时间都在做这类搜索。3.3 用STM32CubeMX的.ioc输出直接覆盖ST官方推荐的硬件配置方式是STM32CubeMX。你在图形界面里勾选引脚、配置外设时钟然后生成设备树源文件生成的位置一般在项目的/Src目录下文件名和板卡相关。但这里有个大坑CubeMX生成的设备树文件是针对你在图形界面中选的板卡配置的它不一定完整包含内核源码中所有的SoC级节点。如果你直接把整个stm32mp157d-dk1.dts覆盖到内核里大概率会丢掉一些默认必需的内容比如clocks、soc的某些子节点。我的经验是只用CubeMX生成的文件作为“引脚复用参考”。它生成的pinctrl片段通常很干净格式直接对应内核的stm32-pinfunc.h宏。我会把需要的i2c4_pins_b之类的节点片段复制到内核源码的板级pinctrl文件中而不是整篇替换。3.4 手工改pinmux的一个简单例子假设我要在DK1上启用I2C4并且把引脚改到PD12和PD13。首先需要在pinctrl头文件里确认这两个脚的复用功能编号比如i2c4_pins_b: i2c4-1 { pins { pinmux STM32_PINMUX(D, 12, AF4), STM32_PINMUX(D, 13, AF4); bias-disable; drive-open-drain; slew-rate 0; }; };然后在板级文件里找到i2c4节点并覆盖i2c4 { pinctrl-names default; pinctrl-0 i2c4_pins_b; status okay; };这类修改看起来简单但很容易因为拼写错误导致编译出来的dtb不包含某个节点。建议修改后先编译、再反编译确认节点确实以status okay形式存在而不是靠肉眼猜。4. 编译设备树的完整命令与输出物解析4.1 先配置内核multi_v7_defconfig和stm32_defconfig怎么选进入内核源码目录先执行source /opt/stm32mp1-sdk/environment-setup-cortexa7t2hf-neon-vfpv4-openstlinux_weston-linux-gnueabihf export ARCHarm export CROSS_COMPILEarm-openstlinux_weston-linux-gnueabihf- make multi_v7_defconfig这一步是生成内核构建基础目录结构比如include/generated等头文件。很多人会问我只是编设备树为什么要配置内核因为设备树编译依赖Kconfig生成的autoconf.h和一些编译规则没有.config构建系统不知道当前架构和设备树使能情况。multi_v7_defconfig是ST官方镜像使用的配置覆盖大量ARMv7平台设备编译出来的dtb也最多stm32_defconfig是针对STM32MP1的精简配置启动更干净。对于DK1开发我推荐先用multi_v7_defconfig因为和官方镜像内核行为最接近排查问题时参考资料最多。4.2 单独编译dtb的命令与作用机制配置完成后的核心命令非常简单make stm32mp157d-dk1.dtb这条命令会让内核构建系统进入arch/arm/boot/dts/目录找到stm32mp157d-dk1.dts先通过C预处理器处理#include再调用内核自带的dtc编译成二进制.dtb文件最后输出到arch/arm/boot/dts/stm32mp157d-dk1.dtb。如果报错找不到generated/utsrelease.h之类文件说明上一步的defconfig或prepare没有跑完整可以执行make ARCHarm prepare然后再编译。正常情况下整个编译过程不会超过一分钟比整个镜像的构建时间快了几个量级。如果不想把编译产物混在源码目录里也可以指定外部构建目录make O$PWD/build ARCHarm multi_v7_defconfig make O$PWD/build ARCHarm stm32mp157d-dk1.dtb输出文件会在build/arch/arm/boot/dts/下。推荐在需要同时管理多块板卡时用这种方式能保留多个构建目录。4.3 内核scripts和dtc的依赖设备树编译过程中dtc编译器是关键工具。内核源码里自带一份dtc源码构建系统会自动编译scripts/dtc/dtc来使用。所以如果你在源码树里执行make stm32mp157d-dk1.dtb第一次运行时它会顺带编译dtc你不用担心系统有没有安装。但如果你的PATH里刚好有另一个旧版dtc比如某些系统包自带的内核构建脚本可能会优先找到它并提示版本太低。解决方法是确保sourceSDK环境后PATH最前面是SDK的sysroots目录也可以执行which dtc确认路径。还有一个小细节设备树源文件用到了很多#define宏这些宏头文件放在内核源码的include/dt-bindings/下。如果你手动调用dtc而不是通过内核Makefile经常会因为宏被展开导致语法错误。所以我始终建议只要不是在做实验就老老实实用make来编。4.4 另一种方式直接调用dtc编译如果你只是临时做一个语法验证不想搭完整内核配置确实可以手动拼接cpp和dtccpp -nostdinc -I arch/arm/boot/dts -I include -I include/uapi -undef -D__DTS__ -x assembler-with-cpp arch/arm/boot/dts/stm32mp157d-dk1.dts | dtc -I dts -O dtb -o /tmp/test.dtb -这个命令的本质是把设备树源文件先做C语言预处理器展开再交给dtc。问题在于手动拼的include路径稍微漏一个宏就展开不出来报错信息又非常不直观。我踩过一次后就没再用它做正经事只用来快速验证某个.dtsi语法是否正确。5. 部署到DK1的SD卡并验证加载结果5.1 理解DK1启动流程中dtb的加载位置STM32MP157D-DK1从SD卡启动时BootROM会执行FSBL通常是TF-A或U-Boot SPL然后由U-Boot读取第二分区中的设备树再启动Linux内核。这就是为什么你改完.dtb后要放到SD卡的FAT分区而不是rootfs分区。把SD卡插入读卡器用lsblk查看设备节点。常见布局是/dev/sdb1为FAT32的bootfs分区/dev/sdb2为rootfs。挂载bootfsmkdir -p /mnt/bootfs sudo mount /dev/sdb1 /mnt/bootfs查看目录你会看到uImage、stm32mp157d-dk1.dtb、*.scr之类的文件。不同官方镜像版本文件名略有差异但原则一致。5.2 替换bootfs中的dtb并保证文件权限替换之前我强烈建议先备份原版sudo cp /mnt/bootfs/stm32mp157d-dk1.dtb /mnt/bootfs/stm32mp157d-dk1.dtb.bak然后把编译产物拷贝过去sudo cp arch/arm/boot/dts/stm32mp157d-dk1.dtb /mnt/bootfs/ sync sudo umount /mnt/bootfs这里有个经验FAT分区虽然不感知Unix权限但拷贝完后sync非常重要不然直接拔卡很容易导致文件系统不一致。我遇到过两次卡插回板子上启动后U-Boot报FAT read error重新插到电脑上执行fsck.vfat才修好都是因为没等写盘完成。拷贝完成后可以在宿主机上md5sum校验一下源文件和目标文件防止Windows系统或者读卡器造成内容错乱。如果你是在Windows下拷贝一定要选“快速删除”策略避免写入缓存丢失。5.3 系统起来后确认设备树是否加载了你的修改板子启动后进入Linux终端。设备树被内核解析后会以“扁平设备树”形式展现在/sys/firmware/devicetree/base目录下。如果你改的是I2C4节点可以这样检查ls /sys/firmware/devicetree/base/soc/i2c40012000/或者用属性名来确认statuscat /sys/firmware/devicetree/base/soc/i2c40012000/status更直观的方式是把运行时设备树反编译出来dtc -I fs -O dts /sys/firmware/devicetree/base -o /tmp/current.dts然后打开/tmp/current.dts搜索你修改的节点看status、pinctrl-0和pinmux是否都在。这个方法还有个好处它能看出系统实际使用的引脚参数是否被内核进一步修正过避免你改了半天但节点没生效。5.4 启动失败时的原始备件恢复如果新dtb有问题最常见的现象是U-Boot启动后立刻重启或者内核起来后某个外设疯狂打印错误。这时把SD卡插回电脑挂载bootfs直接把刚才的.bak复制回去即可sudo cp /mnt/bootfs/stm32mp157d-dk1.dtb.bak /mnt/bootfs/stm32mp157d-dk1.dtb sync我甚至建议准备第二张SD卡烧录官方出厂镜像作为“复活卡”专门用于对比验证。因为有些问题是设备树本身没坏但和当前U-Boot版本不匹配导致U-Boot解析dtb直接失败。这时候手边有一张已知正常的SD卡能快速排除硬件或启动链路故障。6. 设备树编译踩坑Top5从准备到落地最容易翻车的地方6.1 没先跑prepare指令导致dtc报头文件缺失第一次编译时最常见的错是类似fatal error: generated/utsrelease.h: No such file or directory主要原因是没有先执行make multi_v7_defconfig或者执行后.config被后续操作覆盖掉了。内核Makefile里很多生成头文件依赖prepare阶段如果跳过设备树编译虽然调用的是dtc但预处理器还是会找include/generated/下的文件。解决办法也很简单回到源码根目录执行make ARCHarm multi_v7_defconfig make ARCHarm prepare再重新编dtb。不要自己手动创建一个空generated/utsrelease.h这样虽然能骗过预处理器但版本信息缺失后续排查问题会绕弯路。6.2 选错内核defconfig导致目标dtb根本没有被编入还有一次我在一个精简的stm32_defconfig下执行make stm32mp157d-dk1.dtb结果报“No rule to make target”。原因是这个配置没有使能某些设备树目标对应的Kconfig项导致arch/arm/boot/dts/Makefile里对应的dtb-$(CONFIG_XXX)没有值构建系统自然找不到规则。所以遇到“No rule”时第一反应不是去硬改Makefile而是回看.config里相关配置项。最省事的方法是用multi_v7_defconfigST官方已经把STM32MP157家族的所有板级设备树都纳入了编译列表。你也可以用grep -n stm32mp157d-dk1 arch/arm/boot/dts/Makefile确认目标确实由哪个Kconfig控制。6.3 CubeMX生成文件与当前内核版本不匹配使用STM32CubeMX的人大概都有过这种体验图形界面里配置挺顺利生成出来一大摞文件但拷到内核源码里一编译各种宏找不到。原因通常是CubeMX自动生成时使用的内核版本和当前源码树不一致。STM32MP1系列不同版本头文件里的宏名会变化。比如老版本使用STM32_PIN新版本改成STM32_PINMUX有些时钟节点属性也会从clocks改为clock-names。最简单的规避方式是把官方内核自带的dts作为基准只从CubeMX生成文件里“抄”你新增的引脚组定义而不是整体覆盖。如果必须使用CubeMX整套输出建议先做一次make stm32mp157d-dk1.dtb验证确认它和当前内核能映射上。否则你后续所有修改都可能建立在一个虚浮的基础上启动时很难定位错误。6.4 同名dtsi覆盖顺序导致修改“不见”设备树的#include本质上是文本级别的展开多个文件里如果定义同一个节点后面的定义会覆盖前面同名的属性。SoC级文件里可能已经给i2c4设置了pinctrl-0 i2c4_pins_a而你在板级文件里又设置了pinctrl-0 i2c4_pins_b如果板级文件在include顺序中靠前事后再被SoC级文件覆盖你的修改就会静默丢失。排查这类问题最有效的方法是直接看预处理后的完整设备树源文件。可以手动执行make ARCHarm stm32mp157d-dk1.dt.bin或者用dtc -O dts反编译生成的dtb再搜索你期望的引脚节点。如果你发现编译出来的dtb里仍然是i2c4_pins_a那就说明在某个层级上有同名覆盖。建议把自定义修改直接放到顶层stm32mp157d-dk1.dts中那里优先级最高不会被其他板级文件覆盖。6.5 板卡版本RevB/RevD差异导致的引脚冲突STM32MP157D-DK1本身有硬件版本迭代我在调试时发现官方内核里有些引脚配置其实是按新版板卡来的比如LED2、按键、部分扩展GPIO的默认状态。如果你手里的板子丝印是旧版直接烧官方dtb可能表现为某个按键失灵、或者某个外设上电状态不对。处理方式是拿到设备树源文件后先查一下当前板卡型号和版本。可以根据板卡丝印上的编号在stm32mp15xx-dkx.dtsi里搜索对应的GPIO定义和原理图对比。大多数情况下新旧版本差异并不大但一旦遇到差异调试成本很高因为问题看起来像驱动不工作其实是引脚资源冲突。我现在的习惯是拿到任何一块STM32MP1板子后第一时间把原厂dtb反编译并存档同时在源码仓库里建立一个board-rev分支专门记录不同硬件版本的差异。这样后续硬件改版时设备树管理不会变成一团浆糊。设备树编译这件事看起来就是两条make命令但真正决定你能不能顺利跑起来的还是对平台启动流程和源码结构的理解。我现在改DK1设备树的标准流程是先用CubeMX生成pinctrl片段当参考再在源码树里搜索内核已有的相似pin group复制过来做微调编译只用multi_v7_defconfig加make board.dtb部署前永远备份原版dtb启动后用/sys/firmware/devicetree/base确认节点状态。这套流程跑顺之后改一个引脚从修改到验证基本控制在几分钟内。希望这篇记录能让你少走我走过的弯路。