拿到一块新板子系统起不来第一个要解决的不是内核而是U-Boot。U-Boot移植本质上是把处理器上电之后的前几百毫秒从头到尾搞清楚ROM里跑完是谁接管、DDR什么时候初始化、存储介质能不能读写、环境变量放哪、最后怎么把控制权交给内核。这篇东西相当于我多年做BSP适配的U-Boot移植索引从准备环境到跑通启动链再到产品化收尾把整个流程和里面最容易踩的坑都串了一遍。适合正在给板卡做bring-up的工程师也适合想真正弄懂Linux启动链的嵌入式开发者。1. 移植前先想明白U-Boot在整个启动链里扮演什么角色1.1 从复位到内核启动链每一环都在干什么很多人觉得U-Boot就是个引导程序但其实它更像一个“硬件体检员加搬运工”。在典型的ARM平台里上电后第一段代码是SoC内部ROM Code这段代码固化在芯片里没得改。ROM Code会从预设的启动介质里找程序有的芯片先看SD卡有的先看SPI NOR有的看USB下载。找到之后通常会把一个很小的程序加载进SRAM这个程序叫SPLSecondary Program Loader。SPL的作用很纯粹把DDR初始化好再把完整的U-Boot从存储介质搬进内存。为什么需要两步因为很多SoC内部SRAM只有几十到几百KB装不下完整的U-Boot而DDR在上电瞬间频率和时序都还没配置直接访问就是死机。所以必须有小程序先把DDR“激活”才能让大个子程序有地方住。U-Boot proper启动后会去执行bootcmd里的命令比如从eMMC加载内核和设备树到DDR指定地址然后用bootm/booti跳进去。到这个点U-Boot的使命才算完成。理解这层关系特别重要因为你在移植时面对的很多怪问题本质都是“某个阶段的前置条件没满足”。比如U-Boot起来了但内核不跑先怀疑是内核加载地址不对还是设备树不对SPL卡住不出打印先怀疑DDR没初始化好还是波特率不对。启动链的每一环都有明确的职责边界排查时按阶段切分就能很快缩小范围。1.2 U-Boot移植和FreeRTOS、LVGL这类移植不是一回事网上搜U-Boot经常混着一堆“FreeRTOS移植LVGL”“LVGL移植STM32”“nanomodbus移植裸机”的词条。得说清楚U-Boot移植跟这类应用层移植完全是两个维度。LVGL移植是在已有的Cortex-M平台上加一套图形库工作重心是适配显示驱动、触摸输入和内存分配FreeRTOS移植是让一个RTOS内核在MCU上跑起来核心是改底层上下文切换和中断向量。U-Boot移植属于BSP里最底层的那部分工作对象直接影响整块板子的生存DDR控制器寄存器配错一个数板子可能永远黑屏设备树里的mmc节点时钟写错内核阶段才发现盘符找不到。它的特点是“出错了你连一点提示都没有”因为此时串口可能还没初始化操作系统更谈不上。所以做U-Boot移植的思维方式和做应用移植完全不同——应用移植靠日志和调试器就能推进U-Boot移植很多时候要靠示波器、逻辑分析仪、反复阅读SoC手册来推进。1.3 移植前必备用具清单实战里工具没备齐就开干十有八九会中途卡住。我这里列个清单都是踩过坑总结出来的SoC参考手册查寄存器地址、时钟树、引脚复用表、启动设备优先级。DDR颗粒手册DDR初始化要填时序参数CAS、tRCD、tRP这些不能乱写颗粒手册上有标准值。板级原理图确认串口引脚、SD卡检测脚、LED、电源时序对应的GPIO。厂商SDK里的DDR初始化源码很多SoC厂商会在SDK里放DDR training代码这是最省力的参考。USB转串口工具建议带隔离的开发板供电不稳时隔离模块能救你的电脑USB口。JTAG调试器J-Link、OpenOCD、STM32CubeProgrammer用来在U-Boot起不来时强制烧写和查看寄存器。示波器或逻辑分析仪排查时钟有没有起来、SD卡CMD线有没有波形有时比看代码更快。有这些再做后面几步才有底气说自己在“移植”否则就是在瞎试。2. 搭建环境先把“能编译”这个伪目标跑通2.1 工具链选型别一上来就纠结用哪个ARM平台U-Boot编译工具链就两个套路32位ARM用arm-linux-gnueabihf-64位用aarch64-linux-gnu-。理论上用厂商SDK里自带的工具链最稳版本经过验证不会莫名其妙踩坑。但如果你的板子型号比较新SDK工具链太老可能编出告警甚至报错这时候优先考虑Linaro的gcc-arm-系列或者直接用发行版自带的交叉工具链。# 安装工具链Ubuntu/Debian 系 sudo apt install gcc-arm-linux-gnueabihf # 32位ARM sudo apt install gcc-aarch64-linux-gnu # 64位ARM需要特别说明U-Boot本身对编译器版本不算敏感但linux/compiler-gcc.h这类头文件会在新编译器下触发新的告警个别老版本U-Boot在新gcc下是编不过的。所以如果你用的是老版本源码尽量配老一点工具链用新源码工具链也别太老。这是一个“相互匹配”的关系不是越新越好。2.2 源码选择主线U-Boot还是厂商BSP主线U-Boot的好处是社区活跃新SoC支持不断合入代码风格统一出了问题可以对着邮件列表找答案。坏处是它支持的板型有限很多量产的配置不在主线里。厂商BSP比如Rockchip、Allwinner、NXP、STM32的开源包的好处是板级文件和DDR初始化都是现成的你只需要在它基础上改坏处是代码往往落后主线若干个版本而且可能夹杂着厂商自己的一堆补丁可读性差。我的建议是如果芯片厂商在主线里有对应板型或者同系列板型直接用主线如果厂商只有私有BSP先以BSP为起点把系统跑起来再考虑是否反向移植到主线。不要一上来就追求纯主线那是大佬做的事先让板子活下来。# 拉取主线U-Boot git clone https://github.com/u-boot/u-boot.git cd u-boot git checkout v2024.04分支选择上建议挑一个稳定tag而不是最新代码。最新代码可能在你板子之外的其他平台上有夜间构建问题稳定tag至少经过一轮验证。2.3 用现有defconfig先“编一个能跑的”新手移植最容易犯的错是一上来就自己建board目录、写Kconfig结果连编译都过不了。正确姿势是先找一块跟你板子最接近的已有板型编译烧录确认环境本身没问题。怎么找接近的板型看SoC是否同型号或同系列看存储介质是否一致看DDR是LPDDR4还是DDR3看网络PHY型号。比如你在做基于全志T113的板子那就先找sun8i系列里T113相关的板型如果你在做STM32MP157就先找stm32mp15_*系列的defconfig。ls configs/ | grep -i 你的芯片型号关键词 make CROSS_COMPILEarm-linux-gnueabihf- stm32mp15_defconfig make CROSS_COMPILEarm-linux-gnueabihf- -j8编完先不要急着烧去include/configs/和设备树目录里看参考板的配置确认串口引脚、存储分区、启动命令这些跟你的板子差距大不大。差距不大就直接烧能起来就说明环境是通的起不来优先检查串口引脚复用和波特率。2.4 确认“最小可观测”串口有没有输出很多人在这一步就卡住。U-Boot烧进去完全没有输出其实问题不一定在U-Boot本身有可能工具链编出来的镜像根本就没被烧到正确位置也有可能串口接错了引脚。我第一次给A20的板子做bring-up时折腾一晚上没输出最后发现是USB转串口的TX/RX接反了。这种低级错误在开发初期非常普遍所以建议在烧录前先用万用表量一下串口引脚电平、确认地线连通甚至先用一个带loopback的例子验证串口线路本身。如果确定线路没问题还没输出再看启动介质和SPL。很多SoC要求在烧录时对镜像加头部比如全志的mksunxi头部、STM32的header直接烧裸的u-boot.bin是认不到的。厂商SDK里一般有烧录脚本先照着脚本原封不动走一遍不要自作聪明改镜像格式。3. 正式移植动作新建板级描述过DDR这个鬼门关3.1 不写全部代码先把板子“登记”进构建系统U-Boot的构建系统靠Kconfig和Makefile层层嵌套。你的新板子想被make xxx_defconfig认到至少要在几个地方留下名字arch/arm/mach-xxx/Kconfig里增加TARGET_你的板名条目。arch/arm/mach-xxx/Makefile里增加对应board/你的厂商/你的板名的编译路径。新建configs/你的板名_defconfig。新建或者复用board/你的厂商/你的板名/目录放置Kconfig、MAINTAINERS、Makefile、xx.c。新建或者修改arch/arm/dts/你的板名.dts和对应的.dtsi。假如你完全参考同系列的现有板子最快的办法是直接复制整个board目录和defconfig全局替换名字再一点点改差异。这比从零手写靠谱得多因为U-Boot构建体系里的隐式依赖太多了少一个CONFIG_TARGET_XXX定义Kconfig就会报错而这种报错对新手来说很难看懂。# 一个典型的参考流程 cp -r board/vendor/similar_board board/vendor/my_board cp configs/similar_defconfig configs/my_board_defconfig3.2 Kconfig依赖和defconfig内容你要改的其实是指纹很多人以为defconfig里面就是CONFIG_XXXy一行行很直白其实它只是用户可见配置的一小部分。defconfig定义完之后U-Boot的kconfig会根据依赖关系推导出大量默认值。你真正要确认的是串口用的是哪个UART、环境变量保存在哪个分区、SPL要不要带DDR初始化、网络芯片用的什么驱动。以串口为例你需要在defconfig里指定CONFIG_SYS_MALLOC_F_LEN、CONFIG_SYS_CACHELINE_SIZE这些基础宏还要确保CONFIG_DM_SERIAL、CONFIG_CONS_INDEX和设备树里的stdout-path匹配。U-Boot的驱动模型(DM)是从设备树获取串口信息不再靠老式的CONFIG_SYS_NS16550_COM1硬编码。这个迁移让“换串口”从改头文件变成了改设备树更灵活但也更容易漏——比如你只改了设备树status忘了pinctrl串口照样没有输出。3.3 设备树能打印一个字符就算第一阶段的胜利U-Boot的设备树有两个作用一是给U-Boot自身驱动模型用二是启动内核时传递给内核。早期可以先只关注前者让chosen节点、/soc里的UART和GPIO节点、memory节点合法即可。/dts-v1/; / { model MyBoard; compatible vendor,myboard; #address-cells 1; #size-cells 1; chosen { stdout-path uart0; }; memory80000000 { device_type memory; reg 0x80000000 0x20000000; }; };U-Boot在早期竟然用的是CONFIG_SYS_NS16550_COM1那种硬编码后来全面改成设备树后很多资料还停留在老写法特别容易误导人。强烈建议打开源码里的doc/device-tree-bindings/目录对照你的UART型号看绑定规范别抄别人的dts当万灵丹。3.4 DDR初始化U-Boot移植的第一个分水岭DDR初始化是所有U-Boot移植里最“硬”的部分。如果SPL阶段DDR没配好现象是卡死甚至串口都没输出——因为串口控制器可能就在DDR所依赖的时钟域里。调试手段十分有限只能靠JTAG读寄存器或者一行行插printf。我自己的经验是DDR初始化务必以厂商SDK的代码为准不要自己发明参数。你需要的不是理解DDR控制器每个寄存器的物理意义而是确认三组东西硬件连接板子上DDR的位宽16bit还是32bit、片选数、die堆叠数。DDR颗粒类型DDR3、DDR4、LPDDR2、LPDDR3对应不同的控制器设置。时序参数从DDR颗粒手册里查到的CL、tRCD、tRP等SDK一般已经按某一款颗粒调好你换了颗粒供应商就必须重新核。厂商SDK里常见的DDR初始化代码往往是一大段寄存器赋值改起来风险极高。改一个位板子可能从“完全正常”变成“偶尔启动失败”这种不稳定问题最难查。所以尽量做到能用SDK原厂内存配置就先不换必须换时每次只改一个参数并记录改动前后是否还能启动别指望一次猜中。3.5 从没输出到有输出串口是怎么一步步调通的如果SPL阶段卡在DDR初始化串口打印会停在一个固定位置。这时检查机制是先用JTAG确认CPU PC指针停在哪里如果PC卡在DDR控制器初始化函数里说明前面都过了就差这一步如果PC根本没跑到SPL入口那可能是SPL压根没被加载问题在启动介质或头部信息。一种更粗犷但很有效的方式是在DDR初始化前后各加一句原始的寄存器写操作直接操作UART寄存器输出一个字符不走任何驱动抽象static void putc_early(char c) { uart_base-THR c; while (!(uart_base-LSR UART_LSR_THRE)) ; }这招在调试最早期特别好用因为普通的printf可能依赖设备树和串口驱动驱动本身还没初始化时什么都看不到。等能看到字符了再去调printf和普通日志。4. 存储和网络驱动跑通内核前最常卡住的两个环节4.1 eMMC/SD控制器从识别不到卡到内核启动U-Boot里识别存储卡的命令就三个mmc list、mmc dev、mmc info。如果mmc list看不到设备优先查设备树里的mmc节点有没有被U-Boot编进去CONFIG_MMC和对应的控制器驱动开没开。如果能看到设备但mmc dev报错常见原因还是时钟。MMC控制器需要IO时钟和总线时钟两个频率配错一个就握手不成功。调试时可以把时钟频率降低测试比如SD卡跑25MHz不跑50MHz排除是高速模式时序问题。另一个容易忽略的是电压转换芯片很多板子SD卡电源域是独立的如果GPIO控制的VMMC没拉高卡供电不足同样识别不到。内核阶段找不到rootfs但U-Boot阶段mmc info很正常这种问题多半是内核设备树里mmc节点和U-Boot不一致。建议先用mmc part和fatls mmc 0:1这类U-Boot命令确认分区和文件能访问至少把问题边界确认在“U-Boot能读、内核不能读”或反过来。4.2 SPI NOR/NAND与mtdparts分区如果用SPI NOR启动整个流程会更简单体积小、随机读快但要注意你板子上的Flash大小。U-Boot镜像如果超过Flash容量那就是灾难环境变量保存区和内核镜像存储区也要预留足够空间。环境变量的默认位置在include/configs/里的CONFIG_ENV_OFFSET或设备树里partitions节点指定这个偏移量一旦和镜像重叠后果就是启动后环境变量被自身数据覆盖每次都像第一次启动。NAND则复杂一些需要处理坏块、擦除和ECC。U-Boot里NAND驱动通常由CONFIG_NAND_*控制但厂商的NAND控制器接口千差万别建议直接参考厂商BSP不要通用框架上来就上很多NAND控制器驱动没有完全接入DM模型。分区管理上最稳妥的方案是在设备树里明确写出partitions节点同时在U-Boot里使用固定mtdparts命令行参数这样内核和U-Boot对Flash分区的认知才能一致。partitions { compatible fixed-partitions; #address-cells 1; #size-cells 1; uboot0 { label u-boot; reg 0x0 0x20000; }; env20000 { label env; reg 0x20000 0x20000; }; };4.3 网络驱动MAC地址是个容易被忽略的产品问题网络在开发阶段的主要用途是网络启动tftp写内核到内存再跑起来。调网络驱动第一件事是让ethaddr有效。很多SoC内部有mac地址寄存器出厂可能全FFFF。如果MAC地址没配tftp能通但设备在内网里和其他没配MAC的板子冲突。方案分两种一是把MAC地址烧到SoC的eFuse/OTP区适用于正式批量产品二是从板载EEPROM读取适用于小批量开发。最忌讳的是把MAC地址硬编码在环境变量里然后saveenv这种板子的MAC每个都一样交到客户手里很容易出网络冲突。U-Boot的include/configs/里默认会有CONFIG_NET_RANDOM_ETHADDR开关开发阶段临时用没问题量产必须改成正式方案。排查网络问题还有个技巧先用md命令看看PHY寄存器的值确认PHY没有处于复位状态。很多板子的PHY复位脚接在某个GPIO上如果这个GPIO在上电时被拉低PHY就一直复位mii info根本看不到PHY ID。4.4 排查链路从U-Boot命令到信号完整性U-Boot最强的地方在于它是一个交互式环境比内核好排查太多。答题思路是分级help看看命令列表里有没有你要用的命令没有就加CONFIG_CMD_*。dm tree查看设备树节点有没有被驱动绑定成功。clk dump部分平台支持看某个外设时钟是否开启。mii info看PHY有没有被识别到。mmc info、sf probe、nand info看存储介质是否正常。每一步都不顺手时回到设备树和defconfig确认驱动确实编进去了。如果以上都正常但实际读写失败才轮得到怀疑信号完整性和电源稳定性这时才需要示波器去看波形。很多接触不良、过孔断裂的问题在软件层面就是“时而能启动时而不能”这种问题最耗时间尽早拿出硬件工具介入才是正解。5. 启动参数、环境变量和产品化收尾5.1 bootargs和bootcmd把控制权正式交给内核U-Boot本身不启动操作系统时它只是一个交互shell。要让Linux跑起来必须在环境变量里组织好bootcmd。我的习惯是把这个过程写成脚本放在环境变量里不要用零散命令。setenv bootcmd mmc dev 0; fatload mmc 0:1 0x82000000 zImage; fatload mmc 0:1 0x88000000 board.dtb; bootz 0x82000000 - 0x88000000 setenv bootargs consolettyS0,115200 root/dev/mmcblk0p2 rw rootwait panic1 saveenvbootargs里三个关键参数console决定内核日志输出到哪个串口波特率必须和你的调试口一致root指定根文件系统所在设备rootwait针对mmc/ufs这类慢速设备必须加否则内核可能在设备初始化完之前就尝试挂载根fs。memsize一般不需要手动设除非内核内存映射有问题手动设了反而可能掩盖真实内存大小。5.2 环境变量存储为什么冗余环境变量不是可选项U-Boot环境变量默认保存在存储介质中你在命令行改完不saveenv重启就丢了。这本身不是问题问题是存储介质有坏块或者写一半掉电环境变量就会损坏进而导致U-Boot启动行为异常。所以量产板子建议开启冗余环境变量用两个存储区保存环境变量互为备份。U-Boot里对应CONFIG_ENV_IS_IN_FLASH或CONFIG_ENV_IS_IN_MMC加CONFIG_ENV_ADDR_REDUND这类配置组合。具体配置不同平台差异很大但原则一致“坏了一个还有另一个可以用”。5.3 SPL体积、启动时间和裁剪思路产品最终是要交付的启动时间太长、SPL体积超限都不行。这里有几个可以优化的点裁剪驱动用menuconfig把用不上的命令和驱动都关掉。CONFIG_CMD_NET如果量产不用网络启动直接关能省不少字符串和命令分发开销。SPL只保留最核心功能SPL里可以关闭设备树传递之外的大量特性。CONFIG_SPL_*里关掉不需要的驱动体积会明显下降。减少延时常见的CONFIG_BOOTDELAY如果是3每次启动多等3秒。产品化后设成0或者极短。提高DDR频率如果SPL初始化DDR在533MHz而内核又能跑在800MHz可以考虑让SPL就切换到最终频率减少一次频率切换的时间。但这个操作属于高频风险区间没有把握就不要动。裁剪完了务必验证三件事网络启动还能不能用不用于生产也留条后路saveenv保存后重启配置还在整机冷启动和热启动反复各20次不出错。5.4 维护一份移植索引比代码本身更值钱这里的“索引”对应项目标题里的“_索引”我想强调的是U-Boot移植不会一次结束同一份BSP往往要支撑内核升级、DDR颗粒更换、底板迭代。如果只是“代码能跑”三个月后你自己都看不懂当初为什么在某个寄存器上写了一个魔数。我现在每做一个板子都会维护一个移植索引文档内容大致是板级配置的初始参考来源哪块板子的defconfig、哪个版本SDK。DDR时序参数的出处和颗粒型号。每个关键配置项改动前后的现象比如“改了MMC时钟之后U-Boot能识别卡但内核识别不到”。烧录头信息格式和烧录命令这个特别重要因为换电脑换工具链后很容易忘。启动参数演进历史哪些参数是量产加的、哪些是调试时临时加的。这个习惯帮我节省了大量“重新踩一遍坑”的时间。你要是有多个项目并行这种索引比任何代码注释都管用因为注释只讲“代码在干什么”索引能讲“为什么变成这样”。最后再分享一个小经验调U-Boot时不要“单点验证”——串口通了就继续调DDRDDR好了就赶紧调存储每过一个阶段就把前一阶段重复验证一遍。我就遇见过串口单独调通了但DDR初始化代码里改了频率之后串口波特率被连带影响结果板子起来后日志全是乱码。前后环节其实是相互耦合的进度走得再快也要定期回头做一次完整的冷启动验证。