全志D1s开发板RT-Smart环境搭建：从工具链到烧录的完整实践指南

1. 项目概述与核心价值最近在折腾一块搭载了全志D1s芯片的开发板目标是在上面跑RT-Smart实时操作系统。这听起来像是一个标准的嵌入式开发流程但实际操作下来从环境搭建到第一个程序跑起来中间踩的坑一个接一个远不是官方文档里轻描淡写的“几步搞定”。D1s作为一款集成了RISC-V核心的SoC生态还在快速成长中而RT-Smart作为一款面向物联网的实时操作系统其开发环境的搭建本身就涉及交叉编译工具链、系统镜像构建、烧录调试等多个环节的深度整合。这篇笔记就是把我从零开始在Linux环境下搭建D1s RT-Smart开发环境的完整过程、遇到的典型问题以及最终的解决方案记录下来。如果你也正准备或正在这个领域摸索希望这篇详尽的踩坑实录能帮你节省大量时间少走弯路。这个环境搭建的核心是构建一个能够将你的C/C源代码编译成能在D1s芯片上、RT-Smart系统下运行的二进制程序的“桥梁”。整个过程涉及工具链的获取与验证、RT-Smart源码的配置与编译、以及最终镜像的生成与烧录。任何一个环节的版本不匹配、路径设置错误或依赖缺失都可能导致编译失败或运行异常。我将在下文拆解每一个步骤并重点标注那些容易让人“卡壳”的地方。2. 开发环境整体设计与思路拆解在开始动手之前明确整个开发环境的架构和依赖关系至关重要。这能帮助你在遇到问题时快速定位是哪个环节出了岔子。2.1 环境架构与组件依赖整个开发环境可以看作一个三层流水线宿主环境Host即你用来写代码、执行编译的电脑通常是x86_64架构的Linux系统如Ubuntu 20.04/22.04。这是所有工作的起点。构建工具链Toolchain这是一套运行在宿主机上但专门用于生成目标机D1s RISC-V架构可执行代码的编译器、链接器等工具集合。它是连接宿主和目标的关键。目标系统Target即D1s开发板及其上运行的RT-Smart操作系统。我们需要构建出它的内核镜像、文件系统以及应用程序。核心依赖组件包括RISC-V GNU工具链必须选择支持rv64imafdcv架构即GCV扩展的版本因为D1s的C906核心支持向量扩展(V)。版本不匹配是后续编译失败的常见元凶。RT-Smart源代码需要从官方仓库获取其中包含了内核、驱动、库文件以及构建系统。D1s相关的板级支持包BSP这部分通常集成在RT-Smart的源码树中包含了D1s的启动代码、内存映射、外设驱动初始化等硬件相关代码。构建系统RT-Smart使用scons作为构建工具。你需要确保scons版本合适并且Python环境正常。烧录工具用于将编译好的镜像文件写入D1s开发板的存储设备通常是SPI Nor Flash或SD卡。全志官方提供了xboot下的xfel工具这是一个非常关键的工具。注意强烈建议在纯净的Linux虚拟机或物理机中操作避免因宿主系统环境过于复杂如存在多个版本的gcc、python导致难以排查的依赖冲突。我使用的是Ubuntu 22.04 LTS。2.2 方案选型与目录规划为什么选择scons而不是更常见的make或cmakeRT-Smart项目历史沿用了RT-Thread的构建体系scons基于Python在描述复杂的构建规则、特别是针对多种工具链和BSP时更为灵活。对于开发者而言我们只需要配置好环境变量然后执行scons命令即可构建系统会帮我们处理好内核、组件和应用程序的编译链接顺序。目录结构规划也很重要清晰的布局能让你后续的维护和问题排查更轻松。我建议采用如下结构~/workspace/d1s_rt-smart/ ├── tools/ # 存放工具链 │ └── riscv64-unknown-elf-gcc/ ├── rt-smart/ # RT-Smart源代码 │ ├── bsp/ # 板级支持包 │ │ └── allwinner/ # 全志相关BSPD1s在此 │ └── ... # 其他内核、组件目录 ├── output/ # 编译输出目录可设置 └── projects/ # 你自己的应用程序项目目录将工具链和源码分开存放并通过环境变量让它们关联起来是业界通用做法。3. 核心细节解析与实操要点这一部分我们深入到每个核心组件的获取、配置和验证环节这些都是搭建环境的基石。3.1 RISC-V工具链的获取与验证这是第一步也是坑最多的一步。你不能随便下载一个RISC-V工具链就用。1. 获取正确的工具链官方或社区预编译的工具链可能不包含GCV扩展或者版本太旧。最可靠的方式是从RT-Smart或全志相关的生态仓库获取。通常你可以在RT-Smart的bsp/allwinner/d1s目录下的README或rtconfig.py文件中找到工具链的下载线索。例如可能需要使用https://occ.t-head.cn/平头哥芯片开放社区提供的工具链。我实际使用的命令如下请以实际项目指引为准# 假设我们在 ~/workspace/d1s_rt-smart/tools 目录下操作 wget https://occ-oss-prod.oss-cn-hangzhou.aliyuncs.com/resource/1663142515362/Xuantie-900-gcc-elf-newlib-x86_64-V2.6.1.tar.gz tar -xzf Xuantie-900-gcc-elf-newlib-x86_64-V2.6.1.tar.gz解压后你会得到一个类似riscv64-unknown-elf-gcc的目录。2. 验证工具链关键特性下载后不要急于配置环境变量先验证其支持的架构。cd ~/workspace/d1s_rt-smart/tools/riscv64-unknown-elf-gcc/bin ./riscv64-unknown-elf-gcc -v查看输出末尾的--target和--with-arch参数。你必须确认包含rv64imafdcv或至少rv64imafdc并且有v向量扩展支持。同时检查其gcc版本需要与RT-Smart源码兼容例如我使用的版本是10.2.0。3. 配置环境变量将工具链路径加入系统的PATH并设置一个RTT_EXEC_PATH变量这是RT-Smart构建系统查找工具链的常用变量。# 编辑 ~/.bashrc 或 ~/.zshrc export RTT_EXEC_PATH~/workspace/d1s_rt-smart/tools/riscv64-unknown-elf-gcc/bin export PATH$RTT_EXEC_PATH:$PATH保存后执行source ~/.bashrc然后在终端输入riscv64-unknown-elf-gcc -v确保可以正确调用并且显示的路径是你刚添加的。实操心得工具链的版本和路径是环境搭建的“命门”。我曾因为使用了不包含v扩展的工具链导致编译内核时一堆关于向量寄存器的错误排查了很久。务必第一步就确认好。3.2 RT-Smart源码获取与初步配置1. 克隆源码使用git克隆RT-Smart的主仓库。建议克隆后切换到与D1s BSP兼容的稳定分支或标签Tag而不是直接使用master分支因为master可能处于活跃开发状态。cd ~/workspace/d1s_rt-smart git clone https://github.com/RT-Thread/rt-smart.git cd rt-smart # 查看有哪些标签或分支选择一个稳定的例如某个发布版本 git tag -l git checkout v1.0.0 # 假设v1.0.0是一个稳定版本2. 定位D1s BSP进入BSP目录你会发现很多芯片厂商的文件夹。全志Allwinner的通常在bsp/allwinner/下D1s的BSP可能以d1s或tina-d1s命名。cd bsp/allwinner/ ls -la # 你可能会看到 d1s-mq-pro 或类似目录 cd d1s-mq-pro这个目录就是你的主战场里面包含了该开发板的特定配置、链接脚本、驱动初始化代码等。3. 关键配置文件解析在BSP目录下有几个文件至关重要rtconfig.py: 这是scons构建的配置文件。你需要在这里指定工具链前缀、编译选项、链接选项等。通常你只需要修改工具链路径相关的变量确保它指向你刚才设置的工具链。例如找到EXEC_PATH或RTT_EXEC_PATH相关的设置进行修改。.config: 内核功能配置。你可以通过menuconfig工具来图形化配置内核组件、驱动使能等。对于初次尝试可以使用BSP自带的默认配置。board/Kconfig: 板级硬件配置菜单。4. 实操过程与核心环节实现现在我们开始实际的编译和构建流程。4.1 构建系统配置与内核编译1. 进入BSP目录并配置环境确保你的终端当前路径在D1s的BSP目录下例如~/workspace/d1s_rt-smart/rt-smart/bsp/allwinner/d1s-mq-pro。2. 执行菜单配置可选但建议运行scons --menuconfig。这会启动一个基于ncurses的配置界面你可以在这里浏览和修改内核配置。对于第一次你可以先退出并保存默认配置熟悉后再进行深度定制。这个命令会生成或更新.config文件。3. 清理与编译内核首次编译前建议先清理一下旧的构建文件如果有的话scons -c然后开始编译内核scons如果一切顺利scons会开始编译内核、库和组件。这个过程可能会持续几分钟。编译成功后你会在BSP目录下看到生成的关键文件最重要的是rtthread.elfELF格式的内核文件和rtthread.bin纯二进制镜像。4. 生成完整可烧录镜像仅有内核还不够我们需要一个包含Bootloader和内核的完整镜像。D1s通常使用xboot作为一级Bootloader。在BSP目录下应该有一个脚本或scons目标来完成这个工作。例如可能需要运行scons --bootstrap或者执行一个单独的打包脚本mkimage.sh。这个步骤会调用xboot的工具mksunxi将Bootloader和rtthread.bin打包成一个sunxi_f1c100s_rtthread.bin名称可能不同的镜像文件。这是你需要烧录到Flash中的最终文件。踩坑实录我第一次编译时scons顺利通过但执行打包脚本时报错提示找不到mksunxi命令。这是因为xboot的工具没有安装或不在PATH中。解决方案是要么从xboot仓库编译安装mksunxi工具要么在打包脚本中指定其绝对路径。我选择了从https://github.com/xboot/xboot克隆代码在其tools目录下编译mksunxi然后将其路径加入环境变量。4.2 烧录工具准备与镜像下载1. 安装并配置xfel工具xfel是全志系列芯片的USB烧录/调试工具。我们需要从源码编译安装。git clone https://github.com/xboot/xfel.git cd xfel make sudo make install安装后在终端输入xfel应该能看到帮助信息。2. 连接开发板进入FEL模式D1s开发板通常有一个“FEL”按键或通过短接测试点进入FEL模式一种通过USB接受命令的底层烧录模式。操作步骤一般是断开开发板电源。按住“FEL”按键不放。连接开发板的USB-OTG口到电脑。给开发板上电。等待2-3秒后松开“FEL”键。 此时在Linux终端执行lsusb应该能看到一个全志Allwinner相关的USB设备ID可能为1f3a:efe8。3. 擦除与烧录首先查看xfel是否能识别设备xfel version如果显示芯片信息如AWUSBFEX ID:0x00185900说明连接成功。 然后进行SPI Flash的擦除和烧录。注意以下操作会擦除Flash原有数据请谨慎确认设备。# 擦除整个SPI Flash (假设Flash大小为16MB) xfel spinor erase 0 0x1000000 # 将编译好的镜像烧录到Flash起始地址 xfel spinor write 0 sunxi_f1c100s_rtthread.bin烧录过程会有进度显示。完成后给开发板断电再重新上电退出FEL模式系统应该就从新的RT-Smart镜像启动了。4.3 串口调试与系统启动验证1. 连接串口开发板通常有UART串口引出如UART0。你需要一个USB转TTL串口模块将其RX/TX/GND分别连接到开发板的TX/RX/GND。切记RX接TXTX接RX。2. 配置串口终端在Linux上可以使用minicom、picocom或screen。我习惯用picocomsudo apt install picocom # 查看串口设备通常是 /dev/ttyUSB0 或 /dev/ttyACM0 ls /dev/ttyUSB* # 以115200波特率常见连接 picocom -b 115200 /dev/ttyUSB03. 观察启动日志给开发板上电如果一切正常你将在串口终端看到RT-Smart的启动信息包括Banner、内存初始化、驱动加载、文件系统挂载等最后出现命令提示符例如msh /。这表明RT-Smart内核已成功启动并运行。5. 常见问题与排查技巧实录环境搭建过程中几乎不可能一帆风顺。下面是我遇到的一些典型问题及解决方法整理成表方便速查。问题现象可能原因排查步骤与解决方案执行scons编译时报错找不到riscv64-unknown-elf-gcc1. 工具链路径未正确添加到PATH。2.rtconfig.py中的EXEC_PATH设置错误。1. 终端执行echo $PATH和which riscv64-unknown-elf-gcc确认路径。2. 检查rtconfig.py确保EXEC_PATH r‘你的工具链bin目录绝对路径’。编译过程中出现undefined reference to ‘xxx’链接错误1. 缺少某个库或模块。2. 编译顺序或依赖问题。3. 工具链库不匹配。1. 在menuconfig中检查相关功能是否已启用。2. 尝试执行scons -c清理后重新编译。3. 确认使用的工具链是否为RT-Smart社区推荐的版本。执行打包脚本时报错mksunxi: command not foundxboot的打包工具未安装或不在PATH中。1. 从xboot仓库编译mksunxi。2. 将其所在目录加入PATH或直接修改打包脚本使用其绝对路径调用。xfel version无法识别设备或提示No FEL device found1. 开发板未进入FEL模式。2. USB线或接口问题。3. 系统缺少USB驱动权限。1. 严格按照步骤操作进入FEL模式观察开发板指示灯变化。2. 换USB线或端口执行lsusb查看是否有全志设备。3. 将当前用户加入dialout组sudo usermod -aG dialout $USER注销后重登。烧录成功但串口无任何输出1. 串口接线错误RX/TX接反。2. 波特率设置不正确。3. 镜像启动失败如DRAM初始化失败。1. 检查RX/TX交叉连接。2. 尝试常见的波特率115200, 57600, 9600。3. 检查编译时配置的内存参数board.h中的DRAM大小和地址是否与开发板匹配。这是最隐蔽的坑之一。系统启动后运行程序出现非法指令错误工具链的架构与芯片实际支持指令集不匹配最常见是缺少向量(V)扩展支持。根本解决方案更换为支持rv64imafdcv架构的工具链并重新编译整个项目。独家避坑技巧版本锁定记录下所有成功组件的具体版本号工具链GCC版本、RT-Smart提交哈希、xfel版本等。当需要重建环境或帮助他人时这些信息是无价的。逐层验证不要一次性做完所有步骤。完成工具链安装后写一个简单的helloworld.c用riscv64-unknown-elf-gcc交叉编译一下用file命令和readelf -a查看生成文件的信息确认架构正确。这能最早发现问题。善用-j参数编译内核时可以使用scons -jNN为你的CPU核心数进行并行编译大幅缩短时间。串口日志是生命线没有串口输出调试就像盲人摸象。确保串口连接可靠终端软件配置正确。如果完全没有输出优先检查电源、复位电路和最基本的Bootloader是否工作。有时需要尝试短接Flash的特定引脚来强制进入FEL模式。整个环境搭建的过程本质上是一个不断解决依赖和兼容性问题的过程。耐心和细致的记录是关键。当你第一次在串口终端看到RT-Smart的欢迎信息并成功运行一个自己的程序时之前所有的折腾都是值得的。这个环境将成为你探索RISC-V和实时操作系统世界的坚实起点。后续你可以基于此环境开发驱动、移植软件包、优化系统性能真正把这块开发板用起来。