RK3399在Linux下烧录镜像与Bringup全流程：踩坑实录与方案总结

最近在准备BSP系列内容时，对一块RK3399开发板进行Bringup，过程中在Linux下的烧录环节遇到了不少问题。这篇文章旨在完整分享从获取官方镜像、编译开源烧录工具，到最终成功刷入系统的全过程，并会结合遇到的问题，聊聊背后的原因与通用的排查思路。

1. 获取官方镜像与工具

RK3399是一款成熟的嵌入式SoC，曾广泛应用于各类中高端设备。我使用的开发板是友善之臂（FriendlyElec）的NanoPC-T4。拿到开发板后，首要任务就是学会如何烧录系统镜像。

官方提供了多种系统镜像可供选择。我选择了一个基于Ubuntu 20.04的friendlycore镜像进行演示。

下载后的镜像包解压，其内容是一个比较标准的SDK镜像包，包含了SPL、uboot、rootfs、分区表等关键文件。

2. 探索官方提供的Linux工具

在官方的资料中，主要推荐使用图形化的Windows工具RKDevTool进行烧录。

然而，作为BSP开发者，开发环境多在Linux中，频繁切换系统并不方便。实际上，官方工具包中也提供了Linux下的命令行工具upgrade_tool。

但配套的文档描述非常简单，对于镜像文件的用途、命令的具体操作场景，以及“问题处理”到底针对何种问题，都语焉不详，直接照做困难重重。

按照文档尝试，当开发板进入Maskrom模式后（NanoPC-T4进入方法：断电后按住Boot键超过5秒再上电），使用upgrade_tool LD命令可以识别到设备。

但当继续执行后续烧录命令时，就会遇到各种错误。

查看工具生成的日志，错误信息也比较模糊，仅提示USB初始化失败。

3. 转向开源方案：rkdeveloptool

既然主机厂提供的工具不好用，我们转向芯片原厂Rockchip的开源工具——rkdeveloptool。它是upgrade_tool的一个开源版本，功能基本一致。

其工作原理是：当SoC进入Maskrom模式并通过USB连接到主机后，需要先下载一个初始化DDR和USB的Loader文件（即rkxx_loader_vx.xx.bin），为后续的大镜像传输提供内存空间。如果不执行这一步，其他命令都无法执行。

3.1 下载与编译

首先安装编译依赖：

sudo apt-get install libudev-dev libusb-1.0-0-dev dh-autoreconf pkg-config libusb-1.0 autoconf

克隆代码仓库：

git clone https://github.com/rockchip-linux/rkdeveloptool.git --depth 1

进入目录，生成configure脚本：

cd rkdeveloptool
autoreconf -i

执行./configure时，可能会遇到如下错误：

configure: error: working directory cannot be determined

这是由于工具版本与系统环境不兼容所致。需要修改configure.ac文件，应用以下补丁：

diff --git a/configure.ac b/configure.ac
index c21355d..63710d2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,11 +1,23 @@
 dnl Copyright (C) 2017  Trevor Woerner <twoerner@gmail.com>

+dnl Override _AC_INIT_DIRCHECK to handle cases where ls -di returns non-zero exit code
+dnl but still produces valid output (e.g., when stdout is redirected)
+m4_defun([_AC_INIT_DIRCHECK],
+[ac_pwd=`pwd` && test -n "$ac_pwd" &&
+ac_ls_di=`ls -di . 2>/dev/null`; test $? -eq 0 || test -n "$ac_ls_di" || ac_ls_di=`stat -c %i . 2>/dev/null` || ac_ls_di= &&
+ac_pwd_ls_di=`cd "$ac_pwd" && ls -di . 2>/dev/null`; test $? -eq 0 || test -n "$ac_pwd_ls_di" || ac_pwd_ls_di=`stat -c %i . 2>/dev/null` || ac_pwd_ls_di= &&
+test -n "$ac_ls_di" && test -n "$ac_pwd_ls_di" ||
+  AC_MSG_ERROR([working directory cannot be determined])
+test "X$ac_ls_di" = "X$ac_pwd_ls_di" ||
+  AC_MSG_ERROR([pwd does not report name of working directory])
+])
+
 AC_INIT([Rockchip rkdeveloptool], 1.32, [Eddie Cai <eddie.cai.linux@gmail.com>], rkdeveloptool)
 AC_PREREQ([2.68])
 AC_CONFIG_SRCDIR(main.cpp)
 AC_CONFIG_AUX_DIR(cfg)
 AM_INIT_AUTOMAKE([foreign no-dist-gzip dist-bzip2 1.9])
-AM_CONFIG_HEADER(cfg/config.h)
+AC_CONFIG_HEADERS([cfg/config.h])

 SUBDIRS="

修改后，删除之前生成的configure文件，重新执行autoreconf -i生成新的配置脚本，再次执行./configure即可成功。

最后进行编译和安装：

make
sudo make install

4. 使用rkdeveloptool烧录镜像

rkdeveloptool的官方使用说明清晰了许多。

其中提到的rkxx_loader_vx.xx.bin文件，在友善之臂的镜像包中对应的是MiniLoaderAll.bin，两者功能相同。完整的烧录步骤一般如下：

1. 使设备进入Maskrom模式并连接USB。
2. 下载Bootloader初始化DDR和USB：

   sudo rkdeveloptool db MiniLoaderAll.bin

3. 写入各分区镜像（此处命令和分区名需根据实际镜像包调整）：

   sudo rkdeveloptool wl 0x40 idbLoader.img
   sudo rkdeveloptool wl 0x4000 uboot.img
   sudo rkdeveloptool wl 0x8000 boot.img
   sudo rkdeveloptool wl 0x40000 rootfs.img

4. 写入GPT分区表（如果有parameter_gpt.txt文件）：

   sudo rkdeveloptool gpt parameter_gpt.txt

5. 重启设备：

   sudo rkdeveloptool rd

回到之前upgrade_tool报错的问题：错误日志显示libusb_open()失败，错误码-3。这通常是Linux系统下USB设备权限不足的典型表现。最简单的解决方法就是在命令前加上sudo以获取root权限。这也解释了为什么使用rkdeveloptool时，我们全程都需要sudo。

另一种常见错误是libusb_claim_interface failed，这通常是因为设备接口被其他进程（如其他烧录工具、ADB服务等）占用，需要关闭相关进程后重新插拔设备。

烧录成功后，系统即可正常启动，通过串口可以看到内核启动日志，HDMI也能输出图形界面。

5. 思考与总结

通过这个具体的案例，我们不禁要问：为什么有些主机厂提供的SDK和文档指导性不强？根据在芯片原厂的工作经验，我认为有几个可能的原因：

1. 技术能力从芯片原厂到主机厂存在衰减，影响了代码和文档的最终质量。
2. 开发任务繁重，文档编写往往被排在较低优先级，且缺乏有效验收。
3. 特定模块可能由经验尚浅的工程师负责，其对全局的理解和文档表达能力有限。

那么，作为开发者，遇到文档不清、工具难用时该怎么办？

1. 溯源：尽可能查找芯片原厂（如Rockchip）发布的官方资料和开源代码，它们通常更权威、更完整。
2. 获取源码：工具遇到问题，尽量寻找其开源版本。有了源码，即使你不熟悉该领域，也可以编译调试或借助AI辅助分析，定位问题的根源。没有源码的黑盒工具，在出问题时最难排查。
3. 分解问题：Bringup的难点在于软硬件环境复杂，出问题后不易定位。这时需要将问题拆解。例如，当Linux下烧录失败时，可以先用Windows工具尝试，以此快速排除USB物理连接、线材、设备基本功能等硬件层问题。始终保持一个已知可用的基准环境，在此基础上逐个引入变量进行变更和测试，是高效排错的关键。

希望这篇基于真实踩坑经历的流程总结，能为你进行RK3399或其他嵌入式平台的Linux环境开发带来一些切实的帮助。如果你有更多嵌入式系统相关的问题或心得，欢迎在技术社区进行交流。