1. 移植这件事先想清楚再动手U-Boot移植说白了就是让一套通用代码在你自己板子上跑起来。没做过的人觉得它是天书做过的人回头看其实就三件事让串口能打印、让DDR能初始化、让镜像能加载起来。Kbuild则是你这趟旅程里随时要打交道的构建系统你改了什么文件、加了什么驱动最终都是通过Kbuild这套规则变成一颗能烧写的镜像。把这两件事串起来看整个移植过程才会清晰。很多人上来就急着改代码、翻芯片手册结果往往卡在编译报错、链接不过、启动无输出这些地方。我倒建议先停下来搞清楚U-Boot这套代码从make到u-boot.bin到底发生了什么以及你的板子在整棵代码树里处于什么位置。这篇文章就是带你走完这条路的适合刚接触U-Boot、或者对Kbuild规则一知半解的同学。我自己在几块不同架构的板子上都做过移植踩过的坑不少下面写的都是实际动过手的东西。先交代一个认识U-Boot不是为某一款开发板写的它是一套面向几千块开发板的“通用引导程序”。你的板子能不能被支持取决于它是否属于某个已支持SoC片上系统的参考设计。移植的本质不是从零写引导代码而是“声明我的板子存在然后告诉构建系统该编译哪些文件”。# 经典的三步曲移植阶段你每天都要执行无数遍 make defconfig_name make -j$(nproc)这里有个很多人没想透的问题make defconfig_name到底做了什么它和直接make menuconfig是什么关系后面我会专门用一节讲清楚因为这是Kbuild的核心逻辑也是新手最容易懵的地方。2. 为什么U-Boot要用Kbuild这套构建体系Kbuild最初是Linux内核的构建系统U-Boot在2012年前后全面迁移到了它。你可能会问U-Boot代码量才几千个文件为什么不直接用Makefile一个一个列出来原因在于规模。U-Boot支持的架构有十余种板级目录几百个驱动数量上千如果每个文件都手写进Makefile维护成本会失控。Kbuild的核心理念是一个目录下的Makefile只描述本目录的编译目标顶层Makefile负责全局调度配置系统通过obj-y、obj-m、obj-$(CONFIG_XXX)这些变量决定“哪些文件进镜像”。这样可以做到增量式构建改一个驱动只需要重新编译相关目录而不是全量重建。Kbuild在U-Boot里的架构分四个层次层次职责关键内容顶层Makefile版本号、架构设置、输出目录、终极目标调用 scripts/Makefile.buildscripts/Makefile.build递归进入各子目录解析obj-y核心的编译逻辑架构Makefile架构相关的链接脚本、特有编译选项arch/arm/Makefile各目录Makefile声明本目录要编译哪些源文件drivers/net/Makefile等对移植来说你主要关心的是顶层Makefile里的ARCH、CROSS_COMPILE以及架构Makefile里链接脚本的指定。其余细节由Kbuild自动处理。我记得第一次看Kbuild时也被这堆变量绕晕过。后来用了个生活化的类比才通透起来把Kbuild想象成一份餐厅菜单。厨房Makefile拿到客人defconfig的点单决定哪些菜源文件进厨房去做不同客人偏好不同CONFIG选项菜单结构是固定的目录树你要做的只是往菜单上添加你的菜名并告诉顾客你的店叫什么board目录。一旦理解这个角度再看obj-y foo.o这类语句就顺多了。3. 移植前的准备把四大件理清楚开始动代码之前先把你的板子硬件信息摸清楚。U-Boot移植里最怕的不是代码难写而是硬件参数不明确。下面这四件事每一项都必须有确切的答案否则后续调试会让你怀疑人生。3.1 芯片与开发板的对应关系首先要确认SoC型号。U-Boot的代码树里arch/arm/mach-xxx/这层就是按照SoC厂商和系列分的。比如你用NXP的i.MX6ULL对应目录就是arch/arm/mach-imx/板级目录放在board/freescale/mx6ul_14x14_evk/官方EVK板。如果你的板子是基于某个开发板改的最好的策略是先找一块官方板上已有的、同系列SoC的移植示例。找对应目录的方法很简单# 查一下U-Boot支持的板子列表里有没有你的SoC make help | grep -i imx # 或者直接看板级目录 ls board/freescale/3.2 内存颗粒参数DDR初始化的参数是U-Boot移植里最考验耐心的环节。你得知道板子上DDR颗粒的型号、位宽、容量、频率、时序参数。这些参数在SoC的DDR控制器驱动里通常以结构体形式配置比如struct mx6_ddr3_cfg你需要根据颗粒手册里的tRCD、tRP、tRFC等数值填入。很多开发板出厂时厂商会提供一份DDR初始化脚本或寄存器表如果手里有直接对比着填效率高得多。没有也没关系先拿官方同系列板子的参数跑起来再用内存测试命令mtest验证稳定性。3.3 启动介质与引脚复用你的板子是从SD卡启动、eMMC启动、还是SPI Nor启动这决定了你在U-Boot里需要配置哪些驱动以及板级初始化时要设置哪些引脚复用寄存器。我遇到过最坑的情况是SD卡能跑但eMMC驱动死活不工作最后发现是引脚复用配置里面一个上拉电阻选项错了导致数据线信号质量不过关。引脚复用一般在board.c的iomuxc相关函数里配置。建议对照芯片手册里的IOMUXC章节逐一核对不要盲抄官方板子的配置因为你的板子可能改了某些引脚的用途。3.4 调试手段最少要有串口U-Boot的早期输出全部依赖串口。移植阶段的调试基本靠串口打印没有串口的话寸步难行这句话不是夸张。我在调试时习惯用逻辑分析仪抓启动时序但大多数时候不需要那么复杂的工具一根USB转串口线就够了。串口参数通常是115200 8N1但这取决于你的板载晶振和UART时钟配置。如果串口没有输出第一个要查的就是波特率是否正确、串口引脚是否复用对了。这块我后面会专门写一个排查清单。4. Kbuild目录结构与配置体系逐层拆解4.1 一棵树看明白文件归属U-Boot源码在根目录下有这些与Kbuild相关的重点. ├── Makefile # 顶层Makefile ├── configs/ # 所有 defconfig 文件集中地 ├── arch/arm/ # 架构相关代码 │ ├── Makefile │ ├── dts/ # 设备树源文件 │ ├── include/ # 架构相关头文件内存布局、寄存器定义 │ └── mach-imx/ # i.MX系列SoC支持 ├── board/ # 板级目录 │ └── freescale/ │ └── mx6ul_14x14_evk/ ├── include/configs/ # 老式配置头文件一个板子一个.h ├── drivers/ # 驱动目录串口、网络、MMC等 ├── scripts/ # Kbuild核心脚本 │ ├── Makefile.build │ ├── kconfig/ # Kconfig配置解析工具 │ └── dtc/ # 设备树编译工具 ├── arch/arm/dts/ # ARM设备树源文件 └── tools/ # mkimage等工具移植时你真正要动的目录configs/、board/厂商/板名/、arch/arm/dts/有时需要改include/configs/下的头文件老式配置方式以及设备树。4.2 defconfig、Kconfig和 .config 三者的关系这是Kbuild里你必须搞懂的第一组关系。很多人糊涂在改menuconfig和改defconfig到底啥区别简单说defconfig是一份“初始配置单”放在configs/目录下。make defconfig_name的工作就是读取这份配置单结合各目录Kconfig里的默认值生成完整的.config。.config是Kbuild后续编译时真正读取的配置文件。关系图用文字描述一下defconfig精简配置单 ↓ make xxx_defconfig .config完整配置包含所有未指定选项的默认值 ↓ make 读取 编译系统决定编译哪些文件在Kconfig体系里每个配置项都有默认值defconfig只需要指定你要打开或关闭的项其余全部沿用默认值。这就是为什么一个defconfig往往只有几十行但生成的.config有两千多行。举个例子你在configs/myboard_defconfig里看到的CONFIG_SYS_EXTRA_OPTIONSIMX_CONFIGarch/arm/dts/fsl-imx6ul.dtsi CONFIG_ARMy CONFIG_ARCH_MX6ULy CONFIG_DEFAULT_DEVICE_TREEmyboard CONFIG_NETy CONFIG_DM_GPIOy而对应的.config里则是CONFIG_ARMy CONFIG_ARCH_MX6ULy CONFIG_MX6ULy CONFIG_SYS_EXTRA_OPTIONSIMX_CONFIGarch/arm/dts/fsl-imx6ul.dtsi CONFIG_DEFAULT_DEVICE_TREEmyboard CONFIG_DMy CONFIG_DM_GPIOy CONFIG_DM_MMCy CONFIG_DM_SERIALy # 还有几百个你压根没写但被Kconfig默认值填上的选项这里有个容易忽视的点当你用make menuconfig改配置后如果重新执行make defconfig_name你的改动会被覆盖。正确做法是配置完以后用make savedefconfig生成精简defconfig再替换掉原文件。# 正确的配置修改姿势 make myboard_defconfig make menuconfig # ... 修改配置 ... make savedefconfig cp defconfig configs/myboard_defconfig4.3 obj-y 变量与编译顺序Kbuild在编译时会从顶层make开始根据obj-y指定的顺序递归进入目录。那么问题来了obj-y里的顺序能控制编译的先后吗答案是能而且链接顺序也会参考它。U-Boot的链接脚本和链接顺序在arch/arm/cpu/u-boot.lds里定义它把所有目标文件的.o按照一定顺序放在镜像的各个段里。你的board目录里的libboard.o以及board.o会在非常靠前的位置被链接这意味着它的初始化函数会被放在U-Boot入口后的早期位置。看一个实际例子NXP板级目录下的Makefile就非常简单# board/freescale/mx6ul_14x14_evk/Makefile obj-y : mx6ul_14x14_evk.o这行代码的意思就是编译当前目录下的mx6ul_14x14_evk.c生成目标文件并链接进U-Boot镜像。你新加一个板子如果board目录下的源文件名和Makefile里不一致编译时就会报找不到文件这是最常见的新手错误。4.4 include/configs/ 老式头文件的角色这里要区分两个概念的配置Kconfig是新时代的“菜单配置”而include/configs/板名.h是老式U-Boot一直沿用的“宏配置文件”。虽然U-Boot在慢慢向Kconfig迁移但大量板级参数——内存基址、环境变量默认值、串口波特率、boot命令等——仍然放在这个头文件里。就以include/configs/mx6ul_14x14_evk.h为例里面有#define CONFIG_SYS_SDRAM_BASE 0x80000000 #define CONFIG_SYS_INIT_RAM_ADDR 0x00900000 #define CONFIG_SYS_MALLOC_LEN (16 * 1024 * 1024) #define CONFIG_BOOTCOMMAND run distro_bootcmd对移植来说这个文件是板级行为的主要“控制面板”。Kconfig决定了“编译什么”这个头文件决定了“运行时行为”。两者要配合使用缺一不可。5. 第一个移植任务让U-Boot在你的板子上跑起来5.1 第一步确定你的 defconfig 并用它编译假设你手里的板子用的是NXP i.MX6ULL我们就拿最典型的mx6ull_14x14_evk官方板配置做底子。移植第一步永远是“先复现官方板的成功启动”再改造成你的板子。具体做法# 1. 设置交叉编译工具链 export ARCHarm export CROSS_COMPILEarm-linux-gnueabihf- # 2. 找到并测试官方defconfig ls configs/ | grep mx6ull make mx6ull_14x14_evk_defconfig # 3. 编译 make -j4 # 4. 查看输出文件 ls -lh u-boot.bin u-boot.imx如果编译报错通常是工具链版本问题。老版本U-Boot对新gcc会有一些警告被升级成错误我建议先用Ubuntu 18.04时代常用的gcc 7或者9等熟悉了再挑战新工具链。5.2 第二步新建board目录和defconfig现在开始动刀。你需要做三件事复制官方板级目录、复制defconfig并改名、复制设备树源文件。# 以厂商目录为例 cd board/freescale/ cp -r mx6ul_14x14_evk myboard # 改Makefile里的目标文件名 cd myboard/ mv mx6ul_14x14_evk.c myboard.c修改Makefileobj-y : myboard.o修改defconfigcp configs/mx6ull_14x14_evk_defconfig configs/myboard_defconfig vi configs/myboard_defconfig重点改这两行CONFIG_DEFAULT_DEVICE_TREEmyboard CONFIG_SYS_EXTRA_OPTIONSIMX_CONFIGarch/arm/dts/fsl-imx6ul.dtsiCONFIG_DEFAULT_DEVICE_TREE告诉U-Boot默认使用哪个设备树。你需要在arch/arm/dts/下新建或修改对应的dts文件cp arch/arm/dts/mx6ull-14x14-evk.dts arch/arm/dts/myboard.dts然后在arch/arm/dts/Makefile里找到类似这样的行把新的dts加入编译列表dtb-$(CONFIG_TARGET_MYBOARD) myboard.dtb这里有个容易踩的坑U-Boot的设备树Makefile不是按文件名自动收集的你必须手动加到列表里。漏了这步编译不会报错但烧到板子上起不来因为u-boot.bin里根本没嵌入dtb。5.3 第三步修改板级初始化与内存参数以i.MX6UL为例myboard.c里的board_init函数和DDR初始化是重头戏。你从EVK板复制过来的代码可以跑但参数基本要跟着你板子的实际情况改。最常见的内存参数修改位置static struct mx6ul_iomux_grp_regs myboard_grp_regs { /* 根据实际原理图设置 */ }; static struct mx6ul_iomux_pad_regs myboard_pad_regs { /* 对应DDR数据线、地址线、控制线的引脚 */ };内存时序参数在另一个结构体里一般写在myboard.c中static struct mx6_ddr3_cfg myboard_mem_cfg { .mem_speed 800, .density 4, /* 4Gb颗粒 */ .width 16, /* 16位宽度 */ .banks 8, .row 15, .col 10, /* ... 时序参数 ... */ };这里没有捷径只能对照DDR颗粒手册一个个核。有些厂商给你的DDR初始化源码里包含完整的寄存器配置表那就直接用。如果是从零调我建议先用一个保守频率比如533MHz跑通再用mtest或Linux下的memtester压测稳定后再逐步提频。5.4 第四步串口引脚与时钟的核对串口通常不是移植的主要难点但却是第一个拦路虎。板子拿到手烧写了U-Boot上电后串口毫无反应这时候十有八九是串口的引脚复用或时钟配置问题。检查这三个位置// 1. 引脚复用iomuxc设置 // 2. 时钟配置uart clock使能 // 3. 设备树中的串口节点如果使能了DM_SERIAL在i.MX6UL里设备树中的串口节点看起来像这样uart1 { pinctrl-names default; pinctrl-0 pinctrl_uart1; status okay; };如果你在设备树里改了串口号但代码里CONFIG_CONS_INDEX没跟着改也会出现串口没输出的情况。这个宏在include/configs的头文件里定义#define CONFIG_CONS_INDEX 1 /* 第一个串口 */我调过一块板子串口接到的是UART4但默认配置里CONFIG_CONS_INDEX1结果所有输出都跑到UART1去了用转接板接UART4当然什么都看不到。查了半小时才发现这个问题非常羞辱。5.5 最终检查把u-boot.imx烧进去对于i.MX系列最终烧写的镜像是u-boot.imx因为它带有IVT头Image Vector TableBoot ROM能识别并加载。烧写方法取决于你的启动介质SD卡用dd命令写入SD卡的偏移位置。i.MX6UL默认偏移是1KB0x400。eMMC在U-Boot里通过ums或mmc write命令烧写。SPI Nor用sf write命令烧写。Nand用nand write命令烧写。以SD卡为例sudo dd ifu-boot.imx of/dev/sdb bs1k seek1 convfsync把卡插到板子上连接串口上电如果能看见U-Boot的启动日志恭喜移植第一步已经完成。6. 在Kbuild里扩展自己的代码一个驱动接入实例6.1 驱动放在哪、Makefile怎么写U-Boot的驱动模型Driver Model简称DM把驱动分散在drivers/下每个子目录一个Makefile。假设你想给板子加一个自定义的LED驱动可以在drivers/led/目录下新建文件然后在同目录的Makefile里加一行obj-$(CONFIG_LED_MYBOARD) myboard_led.o这行代码的含义是如果配置项CONFIG_LED_MYBOARD被定义成y就编译myboard_led.c并链接进U-Boot。那么怎么让这个配置项出现在menuconfig里在Kconfig文件里定义它。比如drivers/led/Kconfig里加config LED_MYBOARD bool MyBoard LED driver depends on LED default n help Support the LED on MyBoard.这样你在make menuconfig里就能看到这一项。需要注意的是U-Boot的Kconfig体系不会自动读取目录下所有Kconfig你需要确认父目录的Kconfig文件里有source语句。不过在U-Boot的现代版本里大部分目录都已全局source这步通常不用你操心。6.2 用Kconfig和 Makefile控制一个设备的启用流程结合串口驱动举个完整例子。假设你要让U-Boot支持你的板载USB转串口调试芯片而不是SoC自带UART这种情况在量产板上很少见但用来理解流程很直观。首先在drivers/serial/Kconfig里config MYBOARD_SERIAL bool Support MyBoard USB serial default n help Say Y here to support the USB serial adapter on MyBoard.然后在drivers/serial/Makefileobj-$(CONFIG_MYBOARD_SERIAL) myboard_serial.o配置项、源文件、编译开关三者通过Kbuild体系串起来。你改配置后需要重新生成.configmake myboard_defconfig make menuconfig # 勾选或者取消 MYBOARD_SERIAL make savedefconfig cp defconfig configs/myboard_defconfig make -j4这就是Kbuild体系中一次标准的“增删驱动”流程。你不需要手动修改顶层Makefile也不用担心哪个目录漏编译Kbuild会按照配置自动处理。6.3 在设备树里声明硬件资源U-Boot启用DM驱动后驱动的probe函数会从设备树读取硬件资源。还是以上面自定义串口为例在你的板级dts里添加节点iomuxc { pinctrl_myboard_serial: myboardserialgrp { fsl,pins MX6UL_PAD_UART1_TX_DATA__UART1_DCE_TX 0x1b0b1 MX6UL_PAD_UART1_RX_DATA__UART1_DCE_RX 0x1b0b1 ; }; }; uart1 { pinctrl-names default; pinctrl-0 pinctrl_myboard_serial; status okay; };设备树和驱动是配合工作的驱动只负责行为逻辑硬件资源全部从dtb里获取。这样做的好处是同一个驱动替换板级配置时往往不需要改C代码只改dts即可。7. 常见问题速查与排查思路7.1 编译错误篇问题1找不到libboard.o或链接时board相关的符号未定义原因几乎永远是board/厂商/板名/Makefile里的obj-y写的源文件名与实际c文件不一致。检查文件名拼写注意大小写。问题2CONFIG_SYS_EXTRA_OPTIONS里的IMX_CONFIG路径不对这个路径是相对U-Boot顶层目录的而且末尾是.dtsi文件不是.dtb。写错了会在链接阶段报错因为imx_config工具找不到文件。问题3olddefconfig 或 syncconfig 报错通常是Kconfig文件语法错误。U-Boot的Kconfig继承自内核语法要求在scripts/kconfig/文档里有写。最常见的错误是depends on写错了依赖项或者缺少help文字。检查你的Kconfig缩进是否有Tab和空格混用Kconfig对缩进非常敏感这是血泪教训。7.2 编译通过但无启动输出篇现象检查项上电后串口全无反应串口接线是否接错波特率是否正确CONFIG_CONS_INDEX是否对应实际串口设备树中串口节点是否statusokay引脚复用是否设置了输出到一半卡住DDR没有初始化成功代码里访问了不存在的硬件地址看门狗复位循环反复重启循环检查image加载地址是否超过DDR实际大小检查启动介质配置是否正确能到U-Boot命令行但环境变量无法保存检查环境变量存储设备如CONFIG_ENV_IS_IN_MMC、CONFIG_ENV_OFFSET配置是否正确7.3 DDR初始化相关的排查逻辑DDR问题是U-Boot移植中排查难度最大的类型之一。现象上看通常是启动日志打印到Initializing DDR...就停滞。实际排查我通常按这个顺序确认板子的DDR供电电压DDR3一般是1.5VDDR3L是1.35V。电压不对初始化经常性时好时坏。确认位宽和密度参数16位宽颗粒写成了8位宽初始化可能会过但内存测试全失败。用逻辑分析仪抓DDR时钟和片选信号如果DDR控制器时钟都没出来那问题在上游clock tree配置。尝试降低频率有些板子布线质量一般标称800MHz的颗粒跑不到800降一档可能就稳定。我调过一块板子DDR3L颗粒默认参数跑533MHz稳定跑到800MHz就随机死机。最后发现是板子上DDR VREF的分压电阻只焊了一路精度不够换了电阻才好。硬件问题不要第一时间怀疑软件但软件参数也要交叉验证。7.4 网络驱动移植的那点事网络是U-Boot里仅次于DDR的“问题高发区”。以太网驱动移植后最常见的问题是ping不通、SDBoot卡在NetInitialization或者不断打印PHY地址不对。排查要点PHY地址看原理图上PHY芯片的地址引脚拉高拉低确定PHY地址。常见值是0x00、0x01、0x04等。在设备树的fec1节点里设置phy-handle时node的reg值必须对齐。时钟频率FECFast Ethernet Controller的工作时钟来自系统PLL检查时钟树里FEC时钟频率是否为50MHz或25MHz取决于PHY。复位脚很多PHY需要由GPIO控制复位时序必须在驱动probe时先释放复位。有些板子复位脚没接GPIO而是直接接了RC上电复位这种一般没问题但如果是GPIO控制漏了就会导致PHY读不到ID。MDIO时序如果PHY ID能读到、但link不起来检查MDC/MDIO的上拉电阻是否焊接MDIO时钟频率是否过高。U-Boot里的MDC频率一般建议低于2.5MHz。7.5 设备树与驱动不匹配的常见坑坑1U-Boot里的设备树和Linux设备树不完全等同有些节点如u-boot,dm-pre-reloc是U-Boot专用标签。如果你直接拿Linux设备树放在U-Boot编译可能会导致某些驱动在reloc前阶段不生效。解决方法是参考现有板子的dts确认关键节点带有U-Boot需要的特性。坑2修改dts后忘记重新生成dtb。U-Boot构建系统会检查依赖理论上会自动重建但如果你手动改了dts源文件却只单独跑make u-boot.bin偶尔会碰到设备树没更新进的尴尬。保险做法是删掉对应的dtb中间文件再重编rm arch/arm/dts/myboard.dtb make -j4坑3多个板子共用同一颗SoC但设备树里model和compatible字符串配错。这个会导致内核启动时选错machine descriptionU-Boot本身不敏感但Linux会报错。移植时务必保证model与你板子实际芯片/板级匹配。8. 个人经验总结与几个备用技巧做U-Boot移植这几年有个体会非常深刻U-Boot移植的最大门槛不是代码量而是对板卡硬件的理解。你代码写得再漂亮原理图看错了、电阻焊错了、DDR时序没抠准一切白搭。所以拿到一块新板子我强烈建议先把原理图彻头彻尾看一遍特别是电源树、时钟树、启动配置脚、串口本脚和DDR连接关系。这些信息比所有文档都值钱。另外一个技巧是尽量在新板子上先找到一颗能启动的“底子”的软件。很多开发板厂商都会提供一个可以跑的出厂U-Boot或裸机程序先把它烧进去用串口抓日志确认串口打印正常。有了正常打印后面你的移植就能一步步对上症状。最后再分享一个非常实用的小命令。当你改了一堆配置后不确定最终生效的配置值是什么可以直接查grep CONFIG_MYBOARD .config这个比反复看menuconfig快得多。你要是想基于现有配置改出一份干净的最小配置强烈推荐make savedefconfig cat defconfig这一行命令能帮你把当前的.config精简成一个defconfig形式拿去分享给同事或者扔进git里都很干净不会出现几百行配置改动无从review的情况。祝你的板子早日跑起来。真调不动时候睡一觉再看原理图比熬夜硬怼代码效率高得多。