尧图网页设计 
干这行久了Rockchip平台的板子刷过太多回了。不管是 RK3288、RK3399 还是现在火得一塌糊涂的 RK3588你迟早会遇到一个绕不过去的环节怎么把编译出来的镜像烧进板子里怎么把一堆散乱的分区镜像打包成一个能分发给别人的 update.img以及怎么在 Windows 和 Linux 两套环境下都高效地把固件刷下去。这篇文章我不打算写得像手册那样枯燥就按我实际干活的顺序来。先把烧写方案的思路讲清楚再分别拆 Windows 和 Linux 下的实操流程然后把 update.img 的打包原理和 parameter 配置这些容易踩坑的细节翻出来聊最后附上我这些年积累的问题排查速查表。内容会偏长但保证全是能直接抄作业的干货。1. 烧写方案的整体设计与思路拆解1.1 三种烧写模式Maskrom / Loader / Recovery接触 Rockchip 平台第一个要搞明白的就是它的启动和烧写模式。很多人第一次烧写失败不是命令敲错了而是根本没搞清楚板子处于什么模式。Rockchip 的 SoC 从上电到正常启动大致会经过一个固化在芯片内部 ROM 里的引导流程这段代码本身是写死的主要任务是检测外围存储介质或 USB 上有没有可用的引导镜像。基于这个机制实际工作中会遇到三种和烧写相关的模式第一是Maskrom 模式。当 SoC 既找不到 Boot 引脚上有效的外部存储引导也无法从 SPI Flash 或 SD 卡读到有效头信息时它就会老老实实地待在 Maskrom 模式里等待 USB 或者 JTAG 来“喂”代码。这个模式基本可以理解为芯片出厂时的兜底状态特点是设备管理器里能看到一个 Rockchip 相关的未识别设备但你无法通过 adb 这类应用层工具访问它。刷错引导、Flash 全空、eMMC 彻底损坏时板子大概率就会掉进这个模式。第二是Loader 模式。这个模式下芯片 ROM 已经从存储介质里读出了一小段 loader通常是 DDR 初始化代码和 USB 通信固件可以通过 Rockchip 官方烧写工具进行分区镜像的读写。开发板常见的按键组合、短接 eMMC 引脚甚至 adb reboot loader最终都是把芯片引导到这个状态。绝大多数正常烧写操作都需要先进入 Loader 模式。第三是Recovery 模式。严格来说这是 Android 系统层面的概念由 bootloader 引导进入 Recovery 分区。这个模式更多用于 Android 系统的恢复与 OTA在裸机 Linux 开发板场景下用得少但 RKDevTool 和部分量产工具也支持通过它进行烧写。这三种模式的取舍逻辑很简单能进 Loader 就用 LoaderLoader 坏了或者想彻底擦除存储就用 Maskrom。理解了这个后面无论 Windows 还是 Linux 下遇到设备识别问题你都多了一个排查方向。1.2 工具链的家族谱RKDevTool、upgrade_tool 与量产工具Rockchip 官方其实维护了一套覆盖不同平台的烧写工具虽然名字和交互方式不一样但底层协议是相通的。Windows 平台最常用的是RKDevTool也就是大家常说的瑞芯微开发工具。它有图形界面可以烧写整个 update.img也支持单独烧写某个分区镜像还能读取备份分区数据基本覆盖了开发阶段的所有需求。Linux 平台对应的是upgrade_tool这是一个命令行工具早期的源码和二进制发布在 Rockchip 的 GitHub 仓库和社区 SDK 里通常位于 SDK 的tools/linux目录下。它跟 Windows 的 RKDevTool 功能几乎一一对应但由于是命令行脚本化批量烧写非常方便生产效率厂挖机用的基本是这套东西的变体。此外还有工厂量产工具比如 Windows 下的 FactoryTool通常配合特定产线工装使用支持一键烧写、校验、测试。小批量试产时我们一般直接用 upgrade_tool 写脚本代替。工具选型上我的建议是个人开发和调试用 RKDevToolWindows或 upgrade_toolLinux就够了别一上来就上量产工具那玩意儿配置复杂出了问题反而不容易排查。工具本质上是调底层协议的壳核心还是你要搞清楚自己烧的是什么、烧到哪个分区。1.3 update.img 到底是什么很多人搞不清楚 update.img 和单分区镜像的区别拿到一个固件包就往工具里拖结果烧下去板子起不来还不知道哪里出了问题。update.img 其实是一个组合镜像可以简单理解为一把“打包好的钥匙串”。它内部通常包含loader 文件如rk3588_spl_loader_v1.08.113.bin、parameter 文件分区表、以及若干个分区镜像比如 uboot.img、boot.img、rootfs.img、oem.img 等等。打包工具会把它们按照规则封装成一个统一的镜像文件烧写工具拿到这个文件后再解析内部结构依次烧到对应的分区。为什么要用 update.img 而不是直接把散件撒给用户原因很实际分发简单一个文件对应一块板子的完整固件不容易漏烧某个分区。校验方便update.img 自带校验信息烧写过程中可以及时发现文件损坏或者传输错误。统一流程无论烧写工具是 Windows 还是 Linux只要解析同一个 update.img行为就能保持一致。但是update.img 也有一点“坑”它内部的 parameter 是打包时固化的。如果你改了分区表但没有重新打包 update.img烧写工具就会按旧的 parameter 去分区。这就是为什么很多人烧完自制的 update.img 后明明 rootfs 镜像没问题启动后却提示文件系统损坏或者分区大小不对的根本原因。后面我会专门讲 parameter 和打包的对应关系。2. Windows 端烧写实操驱动、Loader 模式与 RKDevTool2.1 驱动安装与设备识别Windows 下烧写的第一步永远是装驱动这一步卡住了后面全白搭。Rockchip 官方提供的驱动安装工具叫做DriverAssitant一般放在 SDK 的tools/windows/DriverAssitant_v5.1.1之类目录下或者从 Rockchip 维基下载。安装驱动有几个容易踩的坑第一以管理员身份运行 DriverInstall.exe。右键选择“以管理员身份运行”否则驱动加载会失败尤其是 Win10/Win11 对驱动的签名校验非常敏感。第二如果设备管理器里出现带黄色感叹号的设备例如Rockchip USB或者Class for rockusb不要慌右键更新驱动手动定位到 DriverAssitant 安装目录下的驱动文件夹强制安装一次即可。第三驱动安装顺序。最佳实践是先装好驱动再让板子进入 Loader 模式并插入 USB。如果你先插了板子再装驱动Win10 可能会自动给设备分配一个错误的驱动导致后面工具识别不到。遇到这个情况卸载设备驱动并勾选“删除此设备的驱动程序软件”然后重新插拔让系统重新识别。装好驱动后把板子接上 USB进入 Loader 模式打开设备管理器正常应该能看到一个Rockusb Device或者带 Rockchip 字样的设备。看到这个驱动这块就算过关了。2.2 进入 Loader 模式的标准姿势驱动没问题接下来就是让板子进入 Loader 模式。不同开发板进入方式不同但原理大同小异。最常见的几种方式物理按键方式开发板或者核心板上通常有一个RECOVERY或MASKROM按键部分板子叫 Boot 按键。按住 RECOVERY 键不放然后给板上电保持几秒后再松开系统就会进入 Loader 模式前提是 loader 没坏。如果按住的是 MASKROM 键再上电则会直接进入 Maskrom 模式。ADB 命令方式如果板子上已经跑起了 Android 或者 Linux 系统并且 USB 调试已开启可以直接执行adb reboot loader板子会重启并进入 Loader 模式。这个方式最稳不需要拆机短接推荐优先使用。短接引脚方式多数开发板在 PCB 上留有 CLK 短接点或者 eMMC 的 CMD 引脚测试点。用镊子短接对应引脚再上电让芯片认为 eMMC 不可用从而进入 Maskrom 模式。这个方式适合 loader 已经刷坏或者 Flash 全空的情况。实际操作时建议在设备管理器或者 RKDevTool 的设备列表里观察变化。RKDevTool 顶部会显示“发现一个设备”或者“设备类型Loader”看到这个提示再动手下一步避免板子没就绪就乱烧。2.3 RKDevTool 烧写 update.img 与单分区刷写RKDevTool 的主界面大概分成两个核心区域默认进来时是升级固件页这一页的操作很简单点击“固件”选择你要烧写的 update.img然后点击“升级”。工具会自动进入升级流程整个过程会显示进度条和日志例如Download gpt、Download loader、Download parameter一直到Download finished。用升级固件页烧整体包是最省事的方式但要注意几点烧写时会重写整个 Flash包括 loader 和 parameter所以板子上的所有数据都会丢失。如果烧写中途断电或者 USB 松动板子很容易变砖进入 Maskrom 模式这时候不要方重新插拔并短接进 Maskrom再烧一次就好了。升级固件页并不会去做内存擦除它默认分区表就是 update.img 里的 parameter如果你的开发板分区和固件包不一致建议先看一下工具日志确认分区烧写是否正确。除了整体烧写开发阶段更常用的是单分区刷写。切换到下载镜像页工具下面会列出一堆分区名称比如loader、parameter、uboot、boot、rootfs、misc等。你可以在每个分区旁选择对应的镜像文件然后在右侧设置烧写地址。这些地址不是随意的是parameter 文件里定义的分区起始地址。比如常见的 RK3588 parameter 里uboot 分区在0x00004000boot 分区在0x00008000等单位是扇区一个扇区 512 字节0x4000 扇区对应的就是 8MB 偏移。所以如果你只改了 kernel完全没必要重烧整个 update.img只需在下载镜像页把 boot 分区镜像传上去勾选后点击“执行”几秒钟就搞定了。这个方式对调试效率提升非常大我平时迭代内核就靠它。3. update.img 的制作打包原理、parameter 与 package-file3.1 打包工具和流程afptool 与 rkImageMaker如果只是拿别人编译好的固件玩你可能永远不需要自己打包 update.img。但做定制产品尤其是要改分区表、加入自己的 oem 分区或者裁剪 system 分区的时候你就必须搞懂打包流程了。在 Rockchip 的 Linux SDK 里打包 update.img 的脚本路径是SDK/rockdev/mkimage.sh核心逻辑会调用resource_tool和三个关键工具afptool、rkImageMaker、mkenvimage等。简单说一下流程构造一个临时打包目录把需要打包的分区镜像放进去例如boot.img、rootfs.img、oem.img、parameter、package-file。用afptool把临时目录里的所有文件封装成一个firmware 中间包通常后缀是firmware.img这个包把文件名和内容以及哈希信息都记录在里面。用rkImageMaker把上一部得到的中间包再加上 loader 文件如rk3588_spl_loader_v*.bin封装成最终可被烧写工具识别的 update.img。在 SDK 里直接跑的常用命令是cd SDK ./build.sh updateimg执行完会生成类似rockdev/Image-rk3588/update.img的文件。这个命令会把当前编译得到的 uboot、kernel、rootfs 都自动收集起来但前提是你之前已经编译过这些镜像并且 SDK 里的rockdev/目录结构完好。如果你用的是别人提供的 SDK 或者想独立打包也不必硬套 build.sh可以直接手动调用 afptool 和 rkImageMaker但前提是你要准备好 parameter、package-file 以及所有分区镜像文件。这个“手工打包”的能力在出固件包给生产或客户的时候特别有用因为你可能想从不同构建环境里拿现成的镜像来组合而不是每次都全量编译。3.2 parameter 文件与分区表parameter 文件是整个 update.img 的灵魂它本质上是一个文本文件定义了 Flash 的分区布局。打开一个典型的 RK3588 parameter 文件内容大概长这样FIRMWARE_VER: 1.0 MACHINE_MODEL: RK3588 MACHINE_ID: 007 MANUFACTURER: Rockchip MAGIC: 0x5041524B ATAG: 0x00200800 MACHINE: 0xffffffff CHECK_MASK: 0x80 PWR_HLD: 0,0,A,0,1 TYPE: GPT CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000100000x00018000(recovery),0x000400000x00028000(rootfs),0x000200000x00068000(oem),0x000200000x00088000(userdata),-0x000a8000(media)看懂这个文件对烧写和软件开发都至关重要。每条分区信息格式是大小起始地址(分区名)实际存储顺序是从前往后排列的。比如0x000020000x00004000(uboot)表示 uboot 分区从偏移0x4000扇区开始大小为0x2000扇区也就是从 8MB 开始占 4MB。为什么要留0x4000扇区因为前面那部分要放 GPT 头、loader、parameter、MISC 等启动关键数据工具烧写时并不会把整个存储从头占满。地址和大小都是以512 字节扇区为单位所以算真实字节数时把十六进制数字转换为十进制后乘以 512 即可。例如 rootfs 分区0x000400000x00028000起始偏移是0x28000 163840扇区也就是 80MB大小是0x40000 262144扇区也就是 128MB。这意味着 rootfs 镜像不能超过 128MB否则烧写会越界轻则覆盖后面的 oem 分区重则直接把分区表搞乱。改分区大小是定制产品最常见的需求。很多客户拿到的默认固件 rootfs 只有 128MB跑个容器或塞几个库文件就满了。此时你只需要修改 parameter 里 rootfs 分区的大小把0x00040000改大一点比如0x00080000256MB同时把后续分区的起始地址整体往后挪。注意改了分区表后必须重新打包 update.img并且如果你的 rootfs.img 本身就超出新分区大小烧写工具会报错或者隐含截断所以一定也要重新生成合适的 rootfs 镜像。3.3 package-file 文件与打包清单package-file 是打包清单告诉打包工具 update.img 里要包含哪些文件、分别对应什么分区。每个 SDK 里都能看到它例如SDK/tools/linux/Linux_Pack_Firmware/rockdev/rk3588/package-file。一份典型的 package-file 长这样# NAME Relative path package-file package-file parameter parameter.txt loader rk3588_spl_loader_v1.08.113.bin uboot uboot.img boot boot.img recovery recovery.img rootfs rootfs.img oem oem.img userdata userdata.img backup backup.img关键是要理解每一行的作用package-file和parameter两行是固定的打包工具会把这两个文件本身也打包进去烧写时工具会先读 parameter 来解析分区表。loader指向的 loader 文件会在烧写整体包时被写入存储介质启动区域后续芯片上电就会从它开始引导。其他行对应的就是各个分区了。打包工具会逐行解析这个文件把列表里的镜像文件写入中间包的索引表中。这里有三个常见问题必须强调第一package-file 里的文件名必须和实际镜像文件名一致否则打包会报找不到文件。我在 Linux 下经常遇到这种低级错误多半是拷贝文件时改名了却忘了更新 package-file。第二backup 和 uboot 的存放路径不能乱写。loader 和 uboot 的启动逻辑对地址非常敏感打包工具对这两类文件有特殊处理不要试图把 uboot.img 改个名字塞到 loader 的位置这会直接导致芯片无法启动。第三如果你不需要某个分区直接删掉对应行即可但不要把 parameter 和 loader 行删掉。例如不需要 recovery 分区镜像那 package-file 里去掉 recovery 行parameter 里也去掉 recovery 分区两者要同步修改否则烧完反而可能因分区表与镜像不一致导致启动流程出错。3.4 自定义分区与制作自己的 update.img把前面几节的内容串起来我来演示一个实际场景我想让 rootfs 从默认的 128MB 扩展到 256MB并且新增一个叫appdata的空分区用来存放用户数据。第一步修改 parameter 文件。假设原先是CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000400000x00018000(rootfs),0x000200000x00058000(oem),-0x00078000(userdata)我需要把 rootfs 大小从0x40000改成0x80000并调整后面分区的位置改成CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000800000x00018000(rootfs),0x000200000x00098000(oem),-0x000b8000(userdata)这样 rootfs 变成 256MBoem 的起始地址从 0x58000 挪到了 0x98000大小保持 128MBuserdata 从 0x78000 挪到 0xb8000 到结尾。第二步准备分区镜像。rootfs 默认是 ext4 格式我通常用make_ext4fs或者mke2fs生成一个新的空镜像大小在 256MB 以内或者用现有 rootfs 镜像直接扩大容量再重新打包。要注意的是ext4 镜像的大小并不等于文件实际占用而是等于你在 mke2fs 时指定的块数所以即使你只是改了分区表也最好用新参数重新生成 rootfs.img保证镜像文件大小和分区大小匹配。第三步修改 package-file 添加 appdata 分区。appdata appdata.img同时在 parameter 的 CMDLINE 末尾在 userdata 之前或之后添加0x000100000x000b8000(appdata)注意 appdata 镜像可以是零字节文件或者未格式化的小镜像具体看系统挂载策略。第四步执行打包脚本或者手动调用 afptool 和 rkImageMaker生成新的 update.img。这个过程我踩过很多次坑最常犯的错误就是改了 parameter 但忘了同步 package-file或者生成 rootfs.img 时大小没控制好导致工具烧写时报Data abort或Partition size mismatch之类的错误。后来我养成了一个习惯改完 parameter 之后在打包脚本里加一个自动检查分区的步骤脚本解析 parameter 文件逐个检查对应镜像的文件大小超过分区大小直接 fail。这一步能帮你挡住 90% 因为手误导致的砖机风险。4. Linux 端实战upgrade_tool 安装、常用命令与脚本化烧写4.1 upgrade_tool 的编译与安装Linux 下最常用的烧写工具是 upgrade_tool它没有图形界面但功能一点不比 Windows 版弱。如果你用的是 Rockchip 官方 Linux SDK工具一般已经预编译好放在SDK/tools/linux/目录下直接用即可。但如果你手里只有网上下载的源码或者目标机器是 x86 Ubuntu那就要自己编译。upgrade_tool 源码在 Rockchip 的 GitHub 上能找到rockchip-linux/rkdeveloptool编译依赖的库主要是libusb。在 Ubuntu 系统上安装依赖并编译的命令大致如下sudo apt-get install libusb-1.0-0-dev pkg-config git make g git clone https://github.com/rockchip-linux/rkdeveloptool.git cd rkdeveloptool make编译完成后会生成一个rkdeveloptool可执行文件你把它改名为upgrade_tool或者直接软链到/usr/local/bin/upgrade_tool方便全局调用。编译时我遇到过两个经典问题一是缺少libusb.h报错fatal error: libusb.h: No such file or directory解决办法就是安装libusb-1.0-0-dev。二是设备访问权限问题。Linux 默认不允许普通用户直接访问 USB 设备你插上开发板后运行upgrade_tool ld可能会什么都没有。解决办法是添加 udev 规则新建/etc/udev/rules.d/99-rockchip.rules内容写SUBSYSTEMusb, ATTR{idVendor}2207, MODE0666 SUBSYSTEMusb, ATTR{idVendor}2a70, MODE0666写好后sudo udevadm control --reload-rules重载规则重新插拔 USB普通用户就能看到设备了。4.2 常用命令解读与进阶用法upgrade_tool 的命令设计得非常简洁只要记住几个核心指令日常操作就够用了。我按使用频率列一下# 列出所有已连接的设备 upgrade_tool ld # 下载 loader 到设备 upgrade_tool db loader.bin # 烧写整个 update.img upgrade_tool uf update.img # 烧写单个分区镜像需要知道分区在 parameter 中的名字 upgrade_tool di -b boot.img upgrade_tool di -rootfs rootfs.img # 读取设备信息 upgrade_tool gld是 list device 的缩写输出设备编号和当前模式比如Loader或Maskrom。这个命令我几乎每次操作前都会先执行一遍就像开机先摸一下设备在不在。db是 download boot它的作用是往 Maskrom 状态的设备里下载一段 loader。注意db只是把 loader 下载到内存并运行并不会写入 Flash。它的主要用途是让 Maskrom 状态的设备加载完 loader 后变成一个可烧写的目标。所以操作顺序一般是设备处于 Maskrom - 执行db loader.bin- 设备进入 Loader 流程 - 再执行uf update.img或者其他烧写命令。uf是 update firmware直接烧写整个 update.img。这个命令执行时工具会解包 update.img按照内部 parameter 依次烧写各分区。如果你想烧完整体包后自动复位重启可以在命令后加上-s参数对应 Windows 版 RKDevTool 的“烧写后自动运行”选项upgrade_tool uf -s update.imgdi是 download image对应 Windows 版的下载镜像页。它可以单独烧写某个分区镜像但前提是工具能正确读取设备当前的分区表。g是获取设备信息包括芯片型号、Loader 版本、Flash 容量等。烧写前跑一条upgrade_tool g能快速确认芯片型号和当前棒子的状态避免拿错固件烧错板子。有一次客户拿回来一块核心板标签写的是 RK3568结果我刷 RK3568 固件怎么都不开机跑g一看芯片型号是 RK3566差点把板子搞报废。4.3 Maskrom 模式下的裸机烧写流程说一个开发中最常碰到的场景板子因刷错固件或者擦除了 eMMC彻底进不了 Loader 模式USB 枚举出来的设备是 Maskrom。这种状态下大多数人的第一反应是“完了返厂吧”。其实完全不用慌Rockchip 的芯片设计就留了这一手Maskrom 模式恰恰是最底层的烧写入口只要能枚举到设备它就还有救。操作流程非常固定首先用镊子短接 Maskrom 键或对应测试点并上电确认设备出现在设备管理器或upgrade_tool ld输出中。然后执行upgrade_tool db rk3588_spl_loader_v1.08.113.bin这一步很重要loader 会初始化 DDR 和 USB 通信设备会重新枚举并切换到可烧写状态。此时再执行upgrade_tool uf update.img把完整固件烧进去最后upgrade_tool rd复位设备板子就满血复活了。这里有个很容易被忽略的细节Maskrom 模式下必须先db再uf顺序不能反而且db的 loader 文件必须与你的芯片型号严格匹配。用 RK3588 的 loader 去 db 一个 RK3399 的设备绝大多数情况都会失败因为在 DDR 初始化阶段就崩了。所以建议在板子还健康的时候就用upgrade_tool g把 loader 版本和芯片型号保存下来或者至少把所有板型的 loader 文件按芯片型号分目录存放。另外Maskrom 模式下也可以直接烧写单个分区镜像比如 eMMC 里的 loader 坏了但还想抢救一下 rootfs 数据可以先db一个 loader再用di单独刷 uboot、boot 等分区的镜像数据还能保下来。这个“最小修复”思路在售后场景里非常实用。4.4 量产脚本思路如果你需要给几十块甚至上百块板子烧写系统一块一块点击工具按钮显然低效。upgrade_tool 是命令行工具这就给了脚本化极大的便利。我平时做产线烧写时会写一个简单的 shell 脚本循环处理多台设备#!/bin/bash IMG$1 [ -z $IMG ] echo Usage: $0 update.img exit 1 DEVICES$(upgrade_tool ld 2/dev/null | grep -c dev) if [ $DEVICES -eq 0 ]; then echo No device found exit 1 fi for i in $(seq 0 $((DEVICES - 1))); do upgrade_tool uf -s $IMG done wait echo All devices flashed OK把多台设备通过 USB Hub 连到同一台 Linux 主机上执行脚本后工具会自动识别所有设备并并行烧写。用这种方式一个 8 口的 USB Hub 一次能同时搞定多台机器产线效率比人工操作高出一大截。不过量产脚本要注意一个细节烧写完成后要检查每台设备的烧写结果。upgrade_tool 的返回码不总是可靠的脚本里最好解析日志确认每一台设备都出现了Reset Device OK类似的字段。不然遇到一个接触不良的 Hub某一路静默失败了你根本不知道板子出厂半天后用户才发现系统起不来那损失就大了。5. 常见问题排查与避坑速查5.1 Windows 端高频问题Windows 下用 RKDevTool 烧写常见问题我整理成了一张速查表现象可能原因解决办法设备管理器有黄色感叹号驱动未正确安装或签名问题管理员身份重装 DriverAssitant手动更新驱动指向驱动目录RKDevTool 找不到设备驱动问题或未进入 Loader/Maskrom检查设备管理器设备名用 RECOVERY 键或 adb reboot loader 重新进入设备识别为 Maskrom 而非 Loaderloader 损坏或 Flash 内容异常先烧 loaderRKDevTool 下载镜像页 loader 分区再烧整体包烧到一半卡住日志停在Download Bootloader 与芯片不匹配或 USB 供电不稳更换配套 loader 文件换线或加供电重试烧写成功但板子无法启动parameter 与镜像不匹配或 uboot 缺失打开日志确认分区烧写情况检查 update.img 完整性5.2 Linux 端高频问题Linux 下用 upgrade_tool 遇到的坑和 Windows 不太一样主要集中在权限和依赖上。现象可能原因解决办法upgrade_tool ld没有输出udev 规则未配置权限不足添加99-rockchip.rules重载 udev 规则后重新插拔 USB编译报libusb.h错误缺少 libusb 开发包sudo apt-get install libusb-1.0-0-devdb loader.bin报Download boot failedloader 型号不匹配或 Maskrom 状态下供电不足换 loader检查板子供电是否稳定尤其 3588 大板uf update.img报Update firmware failed分区表或镜像本身有问题优先用upgrade_tool g查看芯片信息换原厂固件验证脚本并行烧写时某个设备失败USB Hub 供电或带宽不足使用带独立供电的 Hub控制并行数量逐台打印日志5.3 烧写完无法启动的排查思路这是最让人头疼的问题烧写工具明明显示成功结果板子黑屏或者卡在 logo。我把排查思路按优先级列出来照着走基本能定位。第一确认loader 与 uboot 是否匹配。用upgrade_tool g查看 loader 版本再对照 SDK 里uboot.img对应的编译版本。loader 和 uboot 版本跨度太大经常会出现 DDR 初始化失败或者 USB 升级通道异常的问题表现为烧写能过但启动时卡死。第二检查parameter 与镜像是否匹配。这里的匹配不光是地址还包括分区数量。如果你烧了一个包含 recovery 分区的 update.img但 parameter 里没有这个分区那 bootloader 启动时会因无法解析下一级引导而卡死。同样如果 parameter 里定义了 oem 分区但 update.img 里没烧系统挂载 oem 时也会报错。第三检查内核 cmdline。有一部分启动问题出在内核 bootargs 上比如 root 分区指定错误。执行cat /proc/cmdline查看实际的root参数确认内核找的是root/dev/mmcblk0pX还是rootPARTLABELrootfs。Rockchip 平台默认一般用的是rootPARTUUID或者直接按分区名挂载到这一步基本能看出问题。第四看内核日志。接上串口按ctrlc打断内核启动读dmesg输出尤其关注mmc初始化和VFS: Cannot open root device这类关键字。这个信息量很大连早年我遇到的一个 rootfs 镜像和 kernel 的 ext4 版本不兼容的问题都是靠串口日志定位的。5.4 备份、恢复与镜像差异化技巧最后分享一个我长期受益的习惯烧写之前先用工具把原厂固件完整读出来备份无论块板子的原厂固件多烂它都是“能开机”的基准是你所有修改的对标。在 Windows 下RKDevTool 的“设备分区表”页面可以读取每个分区的镜像导出保存比如把 boot 分区和 rootfs 分区分别备份成文件。在 Linux 下可以用upgrade_tool rl命令读取 loader但我更常用的是直接dd整块 eMMC 或 SD 卡生成镜像存档。这样就算后面修改键出岔子随时能恢复到出厂状态不至于把自己折腾得焦头烂额。还有一个镜像差异化的技巧如果只是改了一遍内核完全不必要重新打包整个 update.img。直接在 Windows 下只烧 boot 分区或者在 Linux 下执行upgrade_tool di -b boot.img这样既快又降低风险更适合开发阶段的快速迭代。但这个前提是你要确保你手头的 boot.img 和当前板上的 rootfs 是兼容的接口变了或者驱动对不上照样起不来。最后再说一个容易被忽略的细节flashing 前的 USB 线质量。听起来像玄学但我真的遇到过烧写频繁失败换了一根带屏蔽层的 USB 线之后一切正常的案例。烧写到一半数据出错很多时候不是工具的问题而是线材或者供电导致的电平不稳定。这一点在 Windows 和 Linux 下都适用尤其当板子功耗比较大比如 RK3588 大屏时务必给开发板单独供电不要指望着 USB 口那点电。我对 Rockchip 烧写这块的体会是工具本身不难难的是理解烧写背后那一套分区和引导机制。只要把 Maskrom、Loader、parameter、package-file 这几个关键概念吃透Windows 和 Linux 只是表层交互不同底层逻辑是通用的。下次遇到新板子不要急着找图形工具点来点去先把 parameter 翻开看一眼再决定怎么烧你会少踩很多坑。 Rockchip平台固件烧写与update.img打包实战指南
干这行久了Rockchip平台的板子刷过太多回了。不管是 RK3288、RK3399 还是现在火得一塌糊涂的 RK3588你迟早会遇到一个绕不过去的环节怎么把编译出来的镜像烧进板子里怎么把一堆散乱的分区镜像打包成一个能分发给别人的 update.img以及怎么在 Windows 和 Linux 两套环境下都高效地把固件刷下去。这篇文章我不打算写得像手册那样枯燥就按我实际干活的顺序来。先把烧写方案的思路讲清楚再分别拆 Windows 和 Linux 下的实操流程然后把 update.img 的打包原理和 parameter 配置这些容易踩坑的细节翻出来聊最后附上我这些年积累的问题排查速查表。内容会偏长但保证全是能直接抄作业的干货。1. 烧写方案的整体设计与思路拆解1.1 三种烧写模式Maskrom / Loader / Recovery接触 Rockchip 平台第一个要搞明白的就是它的启动和烧写模式。很多人第一次烧写失败不是命令敲错了而是根本没搞清楚板子处于什么模式。Rockchip 的 SoC 从上电到正常启动大致会经过一个固化在芯片内部 ROM 里的引导流程这段代码本身是写死的主要任务是检测外围存储介质或 USB 上有没有可用的引导镜像。基于这个机制实际工作中会遇到三种和烧写相关的模式第一是Maskrom 模式。当 SoC 既找不到 Boot 引脚上有效的外部存储引导也无法从 SPI Flash 或 SD 卡读到有效头信息时它就会老老实实地待在 Maskrom 模式里等待 USB 或者 JTAG 来“喂”代码。这个模式基本可以理解为芯片出厂时的兜底状态特点是设备管理器里能看到一个 Rockchip 相关的未识别设备但你无法通过 adb 这类应用层工具访问它。刷错引导、Flash 全空、eMMC 彻底损坏时板子大概率就会掉进这个模式。第二是Loader 模式。这个模式下芯片 ROM 已经从存储介质里读出了一小段 loader通常是 DDR 初始化代码和 USB 通信固件可以通过 Rockchip 官方烧写工具进行分区镜像的读写。开发板常见的按键组合、短接 eMMC 引脚甚至 adb reboot loader最终都是把芯片引导到这个状态。绝大多数正常烧写操作都需要先进入 Loader 模式。第三是Recovery 模式。严格来说这是 Android 系统层面的概念由 bootloader 引导进入 Recovery 分区。这个模式更多用于 Android 系统的恢复与 OTA在裸机 Linux 开发板场景下用得少但 RKDevTool 和部分量产工具也支持通过它进行烧写。这三种模式的取舍逻辑很简单能进 Loader 就用 LoaderLoader 坏了或者想彻底擦除存储就用 Maskrom。理解了这个后面无论 Windows 还是 Linux 下遇到设备识别问题你都多了一个排查方向。1.2 工具链的家族谱RKDevTool、upgrade_tool 与量产工具Rockchip 官方其实维护了一套覆盖不同平台的烧写工具虽然名字和交互方式不一样但底层协议是相通的。Windows 平台最常用的是RKDevTool也就是大家常说的瑞芯微开发工具。它有图形界面可以烧写整个 update.img也支持单独烧写某个分区镜像还能读取备份分区数据基本覆盖了开发阶段的所有需求。Linux 平台对应的是upgrade_tool这是一个命令行工具早期的源码和二进制发布在 Rockchip 的 GitHub 仓库和社区 SDK 里通常位于 SDK 的tools/linux目录下。它跟 Windows 的 RKDevTool 功能几乎一一对应但由于是命令行脚本化批量烧写非常方便生产效率厂挖机用的基本是这套东西的变体。此外还有工厂量产工具比如 Windows 下的 FactoryTool通常配合特定产线工装使用支持一键烧写、校验、测试。小批量试产时我们一般直接用 upgrade_tool 写脚本代替。工具选型上我的建议是个人开发和调试用 RKDevToolWindows或 upgrade_toolLinux就够了别一上来就上量产工具那玩意儿配置复杂出了问题反而不容易排查。工具本质上是调底层协议的壳核心还是你要搞清楚自己烧的是什么、烧到哪个分区。1.3 update.img 到底是什么很多人搞不清楚 update.img 和单分区镜像的区别拿到一个固件包就往工具里拖结果烧下去板子起不来还不知道哪里出了问题。update.img 其实是一个组合镜像可以简单理解为一把“打包好的钥匙串”。它内部通常包含loader 文件如rk3588_spl_loader_v1.08.113.bin、parameter 文件分区表、以及若干个分区镜像比如 uboot.img、boot.img、rootfs.img、oem.img 等等。打包工具会把它们按照规则封装成一个统一的镜像文件烧写工具拿到这个文件后再解析内部结构依次烧到对应的分区。为什么要用 update.img 而不是直接把散件撒给用户原因很实际分发简单一个文件对应一块板子的完整固件不容易漏烧某个分区。校验方便update.img 自带校验信息烧写过程中可以及时发现文件损坏或者传输错误。统一流程无论烧写工具是 Windows 还是 Linux只要解析同一个 update.img行为就能保持一致。但是update.img 也有一点“坑”它内部的 parameter 是打包时固化的。如果你改了分区表但没有重新打包 update.img烧写工具就会按旧的 parameter 去分区。这就是为什么很多人烧完自制的 update.img 后明明 rootfs 镜像没问题启动后却提示文件系统损坏或者分区大小不对的根本原因。后面我会专门讲 parameter 和打包的对应关系。2. Windows 端烧写实操驱动、Loader 模式与 RKDevTool2.1 驱动安装与设备识别Windows 下烧写的第一步永远是装驱动这一步卡住了后面全白搭。Rockchip 官方提供的驱动安装工具叫做DriverAssitant一般放在 SDK 的tools/windows/DriverAssitant_v5.1.1之类目录下或者从 Rockchip 维基下载。安装驱动有几个容易踩的坑第一以管理员身份运行 DriverInstall.exe。右键选择“以管理员身份运行”否则驱动加载会失败尤其是 Win10/Win11 对驱动的签名校验非常敏感。第二如果设备管理器里出现带黄色感叹号的设备例如Rockchip USB或者Class for rockusb不要慌右键更新驱动手动定位到 DriverAssitant 安装目录下的驱动文件夹强制安装一次即可。第三驱动安装顺序。最佳实践是先装好驱动再让板子进入 Loader 模式并插入 USB。如果你先插了板子再装驱动Win10 可能会自动给设备分配一个错误的驱动导致后面工具识别不到。遇到这个情况卸载设备驱动并勾选“删除此设备的驱动程序软件”然后重新插拔让系统重新识别。装好驱动后把板子接上 USB进入 Loader 模式打开设备管理器正常应该能看到一个Rockusb Device或者带 Rockchip 字样的设备。看到这个驱动这块就算过关了。2.2 进入 Loader 模式的标准姿势驱动没问题接下来就是让板子进入 Loader 模式。不同开发板进入方式不同但原理大同小异。最常见的几种方式物理按键方式开发板或者核心板上通常有一个RECOVERY或MASKROM按键部分板子叫 Boot 按键。按住 RECOVERY 键不放然后给板上电保持几秒后再松开系统就会进入 Loader 模式前提是 loader 没坏。如果按住的是 MASKROM 键再上电则会直接进入 Maskrom 模式。ADB 命令方式如果板子上已经跑起了 Android 或者 Linux 系统并且 USB 调试已开启可以直接执行adb reboot loader板子会重启并进入 Loader 模式。这个方式最稳不需要拆机短接推荐优先使用。短接引脚方式多数开发板在 PCB 上留有 CLK 短接点或者 eMMC 的 CMD 引脚测试点。用镊子短接对应引脚再上电让芯片认为 eMMC 不可用从而进入 Maskrom 模式。这个方式适合 loader 已经刷坏或者 Flash 全空的情况。实际操作时建议在设备管理器或者 RKDevTool 的设备列表里观察变化。RKDevTool 顶部会显示“发现一个设备”或者“设备类型Loader”看到这个提示再动手下一步避免板子没就绪就乱烧。2.3 RKDevTool 烧写 update.img 与单分区刷写RKDevTool 的主界面大概分成两个核心区域默认进来时是升级固件页这一页的操作很简单点击“固件”选择你要烧写的 update.img然后点击“升级”。工具会自动进入升级流程整个过程会显示进度条和日志例如Download gpt、Download loader、Download parameter一直到Download finished。用升级固件页烧整体包是最省事的方式但要注意几点烧写时会重写整个 Flash包括 loader 和 parameter所以板子上的所有数据都会丢失。如果烧写中途断电或者 USB 松动板子很容易变砖进入 Maskrom 模式这时候不要方重新插拔并短接进 Maskrom再烧一次就好了。升级固件页并不会去做内存擦除它默认分区表就是 update.img 里的 parameter如果你的开发板分区和固件包不一致建议先看一下工具日志确认分区烧写是否正确。除了整体烧写开发阶段更常用的是单分区刷写。切换到下载镜像页工具下面会列出一堆分区名称比如loader、parameter、uboot、boot、rootfs、misc等。你可以在每个分区旁选择对应的镜像文件然后在右侧设置烧写地址。这些地址不是随意的是parameter 文件里定义的分区起始地址。比如常见的 RK3588 parameter 里uboot 分区在0x00004000boot 分区在0x00008000等单位是扇区一个扇区 512 字节0x4000 扇区对应的就是 8MB 偏移。所以如果你只改了 kernel完全没必要重烧整个 update.img只需在下载镜像页把 boot 分区镜像传上去勾选后点击“执行”几秒钟就搞定了。这个方式对调试效率提升非常大我平时迭代内核就靠它。3. update.img 的制作打包原理、parameter 与 package-file3.1 打包工具和流程afptool 与 rkImageMaker如果只是拿别人编译好的固件玩你可能永远不需要自己打包 update.img。但做定制产品尤其是要改分区表、加入自己的 oem 分区或者裁剪 system 分区的时候你就必须搞懂打包流程了。在 Rockchip 的 Linux SDK 里打包 update.img 的脚本路径是SDK/rockdev/mkimage.sh核心逻辑会调用resource_tool和三个关键工具afptool、rkImageMaker、mkenvimage等。简单说一下流程构造一个临时打包目录把需要打包的分区镜像放进去例如boot.img、rootfs.img、oem.img、parameter、package-file。用afptool把临时目录里的所有文件封装成一个firmware 中间包通常后缀是firmware.img这个包把文件名和内容以及哈希信息都记录在里面。用rkImageMaker把上一部得到的中间包再加上 loader 文件如rk3588_spl_loader_v*.bin封装成最终可被烧写工具识别的 update.img。在 SDK 里直接跑的常用命令是cd SDK ./build.sh updateimg执行完会生成类似rockdev/Image-rk3588/update.img的文件。这个命令会把当前编译得到的 uboot、kernel、rootfs 都自动收集起来但前提是你之前已经编译过这些镜像并且 SDK 里的rockdev/目录结构完好。如果你用的是别人提供的 SDK 或者想独立打包也不必硬套 build.sh可以直接手动调用 afptool 和 rkImageMaker但前提是你要准备好 parameter、package-file 以及所有分区镜像文件。这个“手工打包”的能力在出固件包给生产或客户的时候特别有用因为你可能想从不同构建环境里拿现成的镜像来组合而不是每次都全量编译。3.2 parameter 文件与分区表parameter 文件是整个 update.img 的灵魂它本质上是一个文本文件定义了 Flash 的分区布局。打开一个典型的 RK3588 parameter 文件内容大概长这样FIRMWARE_VER: 1.0 MACHINE_MODEL: RK3588 MACHINE_ID: 007 MANUFACTURER: Rockchip MAGIC: 0x5041524B ATAG: 0x00200800 MACHINE: 0xffffffff CHECK_MASK: 0x80 PWR_HLD: 0,0,A,0,1 TYPE: GPT CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000100000x00018000(recovery),0x000400000x00028000(rootfs),0x000200000x00068000(oem),0x000200000x00088000(userdata),-0x000a8000(media)看懂这个文件对烧写和软件开发都至关重要。每条分区信息格式是大小起始地址(分区名)实际存储顺序是从前往后排列的。比如0x000020000x00004000(uboot)表示 uboot 分区从偏移0x4000扇区开始大小为0x2000扇区也就是从 8MB 开始占 4MB。为什么要留0x4000扇区因为前面那部分要放 GPT 头、loader、parameter、MISC 等启动关键数据工具烧写时并不会把整个存储从头占满。地址和大小都是以512 字节扇区为单位所以算真实字节数时把十六进制数字转换为十进制后乘以 512 即可。例如 rootfs 分区0x000400000x00028000起始偏移是0x28000 163840扇区也就是 80MB大小是0x40000 262144扇区也就是 128MB。这意味着 rootfs 镜像不能超过 128MB否则烧写会越界轻则覆盖后面的 oem 分区重则直接把分区表搞乱。改分区大小是定制产品最常见的需求。很多客户拿到的默认固件 rootfs 只有 128MB跑个容器或塞几个库文件就满了。此时你只需要修改 parameter 里 rootfs 分区的大小把0x00040000改大一点比如0x00080000256MB同时把后续分区的起始地址整体往后挪。注意改了分区表后必须重新打包 update.img并且如果你的 rootfs.img 本身就超出新分区大小烧写工具会报错或者隐含截断所以一定也要重新生成合适的 rootfs 镜像。3.3 package-file 文件与打包清单package-file 是打包清单告诉打包工具 update.img 里要包含哪些文件、分别对应什么分区。每个 SDK 里都能看到它例如SDK/tools/linux/Linux_Pack_Firmware/rockdev/rk3588/package-file。一份典型的 package-file 长这样# NAME Relative path package-file package-file parameter parameter.txt loader rk3588_spl_loader_v1.08.113.bin uboot uboot.img boot boot.img recovery recovery.img rootfs rootfs.img oem oem.img userdata userdata.img backup backup.img关键是要理解每一行的作用package-file和parameter两行是固定的打包工具会把这两个文件本身也打包进去烧写时工具会先读 parameter 来解析分区表。loader指向的 loader 文件会在烧写整体包时被写入存储介质启动区域后续芯片上电就会从它开始引导。其他行对应的就是各个分区了。打包工具会逐行解析这个文件把列表里的镜像文件写入中间包的索引表中。这里有三个常见问题必须强调第一package-file 里的文件名必须和实际镜像文件名一致否则打包会报找不到文件。我在 Linux 下经常遇到这种低级错误多半是拷贝文件时改名了却忘了更新 package-file。第二backup 和 uboot 的存放路径不能乱写。loader 和 uboot 的启动逻辑对地址非常敏感打包工具对这两类文件有特殊处理不要试图把 uboot.img 改个名字塞到 loader 的位置这会直接导致芯片无法启动。第三如果你不需要某个分区直接删掉对应行即可但不要把 parameter 和 loader 行删掉。例如不需要 recovery 分区镜像那 package-file 里去掉 recovery 行parameter 里也去掉 recovery 分区两者要同步修改否则烧完反而可能因分区表与镜像不一致导致启动流程出错。3.4 自定义分区与制作自己的 update.img把前面几节的内容串起来我来演示一个实际场景我想让 rootfs 从默认的 128MB 扩展到 256MB并且新增一个叫appdata的空分区用来存放用户数据。第一步修改 parameter 文件。假设原先是CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000400000x00018000(rootfs),0x000200000x00058000(oem),-0x00078000(userdata)我需要把 rootfs 大小从0x40000改成0x80000并调整后面分区的位置改成CMDLINE: mtdpartsrkfiraw:0x000020000x00004000(uboot),0x000020000x00006000(misc),0x000100000x00008000(boot),0x000800000x00018000(rootfs),0x000200000x00098000(oem),-0x000b8000(userdata)这样 rootfs 变成 256MBoem 的起始地址从 0x58000 挪到了 0x98000大小保持 128MBuserdata 从 0x78000 挪到 0xb8000 到结尾。第二步准备分区镜像。rootfs 默认是 ext4 格式我通常用make_ext4fs或者mke2fs生成一个新的空镜像大小在 256MB 以内或者用现有 rootfs 镜像直接扩大容量再重新打包。要注意的是ext4 镜像的大小并不等于文件实际占用而是等于你在 mke2fs 时指定的块数所以即使你只是改了分区表也最好用新参数重新生成 rootfs.img保证镜像文件大小和分区大小匹配。第三步修改 package-file 添加 appdata 分区。appdata appdata.img同时在 parameter 的 CMDLINE 末尾在 userdata 之前或之后添加0x000100000x000b8000(appdata)注意 appdata 镜像可以是零字节文件或者未格式化的小镜像具体看系统挂载策略。第四步执行打包脚本或者手动调用 afptool 和 rkImageMaker生成新的 update.img。这个过程我踩过很多次坑最常犯的错误就是改了 parameter 但忘了同步 package-file或者生成 rootfs.img 时大小没控制好导致工具烧写时报Data abort或Partition size mismatch之类的错误。后来我养成了一个习惯改完 parameter 之后在打包脚本里加一个自动检查分区的步骤脚本解析 parameter 文件逐个检查对应镜像的文件大小超过分区大小直接 fail。这一步能帮你挡住 90% 因为手误导致的砖机风险。4. Linux 端实战upgrade_tool 安装、常用命令与脚本化烧写4.1 upgrade_tool 的编译与安装Linux 下最常用的烧写工具是 upgrade_tool它没有图形界面但功能一点不比 Windows 版弱。如果你用的是 Rockchip 官方 Linux SDK工具一般已经预编译好放在SDK/tools/linux/目录下直接用即可。但如果你手里只有网上下载的源码或者目标机器是 x86 Ubuntu那就要自己编译。upgrade_tool 源码在 Rockchip 的 GitHub 上能找到rockchip-linux/rkdeveloptool编译依赖的库主要是libusb。在 Ubuntu 系统上安装依赖并编译的命令大致如下sudo apt-get install libusb-1.0-0-dev pkg-config git make g git clone https://github.com/rockchip-linux/rkdeveloptool.git cd rkdeveloptool make编译完成后会生成一个rkdeveloptool可执行文件你把它改名为upgrade_tool或者直接软链到/usr/local/bin/upgrade_tool方便全局调用。编译时我遇到过两个经典问题一是缺少libusb.h报错fatal error: libusb.h: No such file or directory解决办法就是安装libusb-1.0-0-dev。二是设备访问权限问题。Linux 默认不允许普通用户直接访问 USB 设备你插上开发板后运行upgrade_tool ld可能会什么都没有。解决办法是添加 udev 规则新建/etc/udev/rules.d/99-rockchip.rules内容写SUBSYSTEMusb, ATTR{idVendor}2207, MODE0666 SUBSYSTEMusb, ATTR{idVendor}2a70, MODE0666写好后sudo udevadm control --reload-rules重载规则重新插拔 USB普通用户就能看到设备了。4.2 常用命令解读与进阶用法upgrade_tool 的命令设计得非常简洁只要记住几个核心指令日常操作就够用了。我按使用频率列一下# 列出所有已连接的设备 upgrade_tool ld # 下载 loader 到设备 upgrade_tool db loader.bin # 烧写整个 update.img upgrade_tool uf update.img # 烧写单个分区镜像需要知道分区在 parameter 中的名字 upgrade_tool di -b boot.img upgrade_tool di -rootfs rootfs.img # 读取设备信息 upgrade_tool gld是 list device 的缩写输出设备编号和当前模式比如Loader或Maskrom。这个命令我几乎每次操作前都会先执行一遍就像开机先摸一下设备在不在。db是 download boot它的作用是往 Maskrom 状态的设备里下载一段 loader。注意db只是把 loader 下载到内存并运行并不会写入 Flash。它的主要用途是让 Maskrom 状态的设备加载完 loader 后变成一个可烧写的目标。所以操作顺序一般是设备处于 Maskrom - 执行db loader.bin- 设备进入 Loader 流程 - 再执行uf update.img或者其他烧写命令。uf是 update firmware直接烧写整个 update.img。这个命令执行时工具会解包 update.img按照内部 parameter 依次烧写各分区。如果你想烧完整体包后自动复位重启可以在命令后加上-s参数对应 Windows 版 RKDevTool 的“烧写后自动运行”选项upgrade_tool uf -s update.imgdi是 download image对应 Windows 版的下载镜像页。它可以单独烧写某个分区镜像但前提是工具能正确读取设备当前的分区表。g是获取设备信息包括芯片型号、Loader 版本、Flash 容量等。烧写前跑一条upgrade_tool g能快速确认芯片型号和当前棒子的状态避免拿错固件烧错板子。有一次客户拿回来一块核心板标签写的是 RK3568结果我刷 RK3568 固件怎么都不开机跑g一看芯片型号是 RK3566差点把板子搞报废。4.3 Maskrom 模式下的裸机烧写流程说一个开发中最常碰到的场景板子因刷错固件或者擦除了 eMMC彻底进不了 Loader 模式USB 枚举出来的设备是 Maskrom。这种状态下大多数人的第一反应是“完了返厂吧”。其实完全不用慌Rockchip 的芯片设计就留了这一手Maskrom 模式恰恰是最底层的烧写入口只要能枚举到设备它就还有救。操作流程非常固定首先用镊子短接 Maskrom 键或对应测试点并上电确认设备出现在设备管理器或upgrade_tool ld输出中。然后执行upgrade_tool db rk3588_spl_loader_v1.08.113.bin这一步很重要loader 会初始化 DDR 和 USB 通信设备会重新枚举并切换到可烧写状态。此时再执行upgrade_tool uf update.img把完整固件烧进去最后upgrade_tool rd复位设备板子就满血复活了。这里有个很容易被忽略的细节Maskrom 模式下必须先db再uf顺序不能反而且db的 loader 文件必须与你的芯片型号严格匹配。用 RK3588 的 loader 去 db 一个 RK3399 的设备绝大多数情况都会失败因为在 DDR 初始化阶段就崩了。所以建议在板子还健康的时候就用upgrade_tool g把 loader 版本和芯片型号保存下来或者至少把所有板型的 loader 文件按芯片型号分目录存放。另外Maskrom 模式下也可以直接烧写单个分区镜像比如 eMMC 里的 loader 坏了但还想抢救一下 rootfs 数据可以先db一个 loader再用di单独刷 uboot、boot 等分区的镜像数据还能保下来。这个“最小修复”思路在售后场景里非常实用。4.4 量产脚本思路如果你需要给几十块甚至上百块板子烧写系统一块一块点击工具按钮显然低效。upgrade_tool 是命令行工具这就给了脚本化极大的便利。我平时做产线烧写时会写一个简单的 shell 脚本循环处理多台设备#!/bin/bash IMG$1 [ -z $IMG ] echo Usage: $0 update.img exit 1 DEVICES$(upgrade_tool ld 2/dev/null | grep -c dev) if [ $DEVICES -eq 0 ]; then echo No device found exit 1 fi for i in $(seq 0 $((DEVICES - 1))); do upgrade_tool uf -s $IMG done wait echo All devices flashed OK把多台设备通过 USB Hub 连到同一台 Linux 主机上执行脚本后工具会自动识别所有设备并并行烧写。用这种方式一个 8 口的 USB Hub 一次能同时搞定多台机器产线效率比人工操作高出一大截。不过量产脚本要注意一个细节烧写完成后要检查每台设备的烧写结果。upgrade_tool 的返回码不总是可靠的脚本里最好解析日志确认每一台设备都出现了Reset Device OK类似的字段。不然遇到一个接触不良的 Hub某一路静默失败了你根本不知道板子出厂半天后用户才发现系统起不来那损失就大了。5. 常见问题排查与避坑速查5.1 Windows 端高频问题Windows 下用 RKDevTool 烧写常见问题我整理成了一张速查表现象可能原因解决办法设备管理器有黄色感叹号驱动未正确安装或签名问题管理员身份重装 DriverAssitant手动更新驱动指向驱动目录RKDevTool 找不到设备驱动问题或未进入 Loader/Maskrom检查设备管理器设备名用 RECOVERY 键或 adb reboot loader 重新进入设备识别为 Maskrom 而非 Loaderloader 损坏或 Flash 内容异常先烧 loaderRKDevTool 下载镜像页 loader 分区再烧整体包烧到一半卡住日志停在Download Bootloader 与芯片不匹配或 USB 供电不稳更换配套 loader 文件换线或加供电重试烧写成功但板子无法启动parameter 与镜像不匹配或 uboot 缺失打开日志确认分区烧写情况检查 update.img 完整性5.2 Linux 端高频问题Linux 下用 upgrade_tool 遇到的坑和 Windows 不太一样主要集中在权限和依赖上。现象可能原因解决办法upgrade_tool ld没有输出udev 规则未配置权限不足添加99-rockchip.rules重载 udev 规则后重新插拔 USB编译报libusb.h错误缺少 libusb 开发包sudo apt-get install libusb-1.0-0-devdb loader.bin报Download boot failedloader 型号不匹配或 Maskrom 状态下供电不足换 loader检查板子供电是否稳定尤其 3588 大板uf update.img报Update firmware failed分区表或镜像本身有问题优先用upgrade_tool g查看芯片信息换原厂固件验证脚本并行烧写时某个设备失败USB Hub 供电或带宽不足使用带独立供电的 Hub控制并行数量逐台打印日志5.3 烧写完无法启动的排查思路这是最让人头疼的问题烧写工具明明显示成功结果板子黑屏或者卡在 logo。我把排查思路按优先级列出来照着走基本能定位。第一确认loader 与 uboot 是否匹配。用upgrade_tool g查看 loader 版本再对照 SDK 里uboot.img对应的编译版本。loader 和 uboot 版本跨度太大经常会出现 DDR 初始化失败或者 USB 升级通道异常的问题表现为烧写能过但启动时卡死。第二检查parameter 与镜像是否匹配。这里的匹配不光是地址还包括分区数量。如果你烧了一个包含 recovery 分区的 update.img但 parameter 里没有这个分区那 bootloader 启动时会因无法解析下一级引导而卡死。同样如果 parameter 里定义了 oem 分区但 update.img 里没烧系统挂载 oem 时也会报错。第三检查内核 cmdline。有一部分启动问题出在内核 bootargs 上比如 root 分区指定错误。执行cat /proc/cmdline查看实际的root参数确认内核找的是root/dev/mmcblk0pX还是rootPARTLABELrootfs。Rockchip 平台默认一般用的是rootPARTUUID或者直接按分区名挂载到这一步基本能看出问题。第四看内核日志。接上串口按ctrlc打断内核启动读dmesg输出尤其关注mmc初始化和VFS: Cannot open root device这类关键字。这个信息量很大连早年我遇到的一个 rootfs 镜像和 kernel 的 ext4 版本不兼容的问题都是靠串口日志定位的。5.4 备份、恢复与镜像差异化技巧最后分享一个我长期受益的习惯烧写之前先用工具把原厂固件完整读出来备份无论块板子的原厂固件多烂它都是“能开机”的基准是你所有修改的对标。在 Windows 下RKDevTool 的“设备分区表”页面可以读取每个分区的镜像导出保存比如把 boot 分区和 rootfs 分区分别备份成文件。在 Linux 下可以用upgrade_tool rl命令读取 loader但我更常用的是直接dd整块 eMMC 或 SD 卡生成镜像存档。这样就算后面修改键出岔子随时能恢复到出厂状态不至于把自己折腾得焦头烂额。还有一个镜像差异化的技巧如果只是改了一遍内核完全不必要重新打包整个 update.img。直接在 Windows 下只烧 boot 分区或者在 Linux 下执行upgrade_tool di -b boot.img这样既快又降低风险更适合开发阶段的快速迭代。但这个前提是你要确保你手头的 boot.img 和当前板上的 rootfs 是兼容的接口变了或者驱动对不上照样起不来。最后再说一个容易被忽略的细节flashing 前的 USB 线质量。听起来像玄学但我真的遇到过烧写频繁失败换了一根带屏蔽层的 USB 线之后一切正常的案例。烧写到一半数据出错很多时候不是工具的问题而是线材或者供电导致的电平不稳定。这一点在 Windows 和 Linux 下都适用尤其当板子功耗比较大比如 RK3588 大屏时务必给开发板单独供电不要指望着 USB 口那点电。我对 Rockchip 烧写这块的体会是工具本身不难难的是理解烧写背后那一套分区和引导机制。只要把 Maskrom、Loader、parameter、package-file 这几个关键概念吃透Windows 和 Linux 只是表层交互不同底层逻辑是通用的。下次遇到新板子不要急着找图形工具点来点去先把 parameter 翻开看一眼再决定怎么烧你会少踩很多坑。