Skip to main content

SDK 使用自定义 Rootfs 打包固件

概述​

在 Tina Linux SDK 开发过程中，有时需要使用自定义的 rootfs 文件系统，例如：

  • 使用 Buildroot 构建的 rootfs
  • 使用 debootstrap 构建的 Debian 系 rootfs
  • 其他自定义 Linux 发行版
  • 调试使用，需要使用之前打包的 rootfs 文件

本文档介绍如何在保持 Tina SDK 内核和引导程序不变的情况下，使用自定义 rootfs 进行固件打包。

前提条件​

  • 已配置好的 Tina Linux SDK 环境
  • 准备好的自定义 rootfs 镜像文件

操作步骤​

1. 准备 rootfs 镜像​

首先需要准备一个可用的 rootfs 镜像文件。以下是几种常见方式：

Buildroot 构建：

# Buildroot 构建完成后生成的镜像
output/images/rootfs.ext4

Debian debootstrap 构建：

# 创建 ext4 镜像
dd if=/dev/zero of=debian_rootfs.img bs=1M count=512
mkfs.ext4 debian_rootfs.img
mount debian_rootfs.img /mnt
# 使用 debootstrap 安装 Debian
debootstrap --arch=riscv64 sid /mnt http://mirrors.tuna.tsinghua.edu.cn/debian
umount /mnt

2. 放置 rootfs 文件到板级配置目录​

将准备好的 rootfs 镜像文件复制到板级配置目录，并将后缀名改为 .fex：

# 以 bga_perf1 板级为例
cp debian_rootfs.img device/config/chips/v861/configs/bga_perf1/debian_rootfs.fex

注意： 打包系统要求 downloadfile 字段指定的文件必须以 .fex 结尾。

image-20260326151952694

3. 修改分区表配置​

编辑板级分区表文件 sys_partition.fex，修改 rootfs 分区的 downloadfile 字段：

文件路径：

device/config/chips/v861/configs/bga_perf1/sys_partition.fex

SPI NOR 方案：

device/config/chips/v861/configs/bga_perf1/sys_partition_nor.fex

修改前：

[partition]
    name         = rootfs
    size         = 1048576
    downloadfile = "rootfs.fex"
    user_type    = 0x8000

修改后：

[partition]
    name         = rootfs
    size         = 1048576
    downloadfile = "debian_rootfs.fex"
    user_type    = 0x8000

image-20260326151933560

4. 执行打包​

完成上述配置后，执行打包命令生成固件：

# 初始化环境
source build/envsetup.sh

# 选择目标板配置
lunch
# 选择 v861_bga_perf1-openwrt 或对应配置

# 执行打包
pack

打包完成后，固件输出路径为：

out

原理说明​

为什么必须放到 device 目录下？​

打包脚本 build/pack 在执行时，会从预定义的文件列表中复制资源文件到打包输出目录。关键代码如下：

文件： build/pack（第 200 行）

configs_file_list=(
    ...
    ${LICHEE_CHIP_CONFIG_DIR}/configs/${PACK_BOARD}/*.fex
    ...
)

文件： build/pack（第 707-709 行）

LOGD "copying configs file"
for file in ${configs_file_list[@]} ; do
    cp -f $file ${LICHEE_PACK_OUT_DIR} 2> /dev/null
done

变量解析：

  • LICHEE_CHIP_CONFIG_DIR = device/config/chips/v861
  • PACK_BOARD = bga_perf1（示例）
  • LICHEE_PACK_OUT_DIR = out/v861/perf1/openwrt/image

打包流程：

┌─────────────────────────────────────────┐
│  device/config/chips/v861/configs/      │
│  └── bga_perf1/                         │
│      ├── sys_partition.fex              │
│      ├── debian_rootfs.fex  ◄── 你的文件 │
│      └── ...                            │
└─────────────────┬───────────────────────┘
                  │ pack 脚本复制 *.fex
                  ▼
┌─────────────────────────────────────────┐
│  out/v861/perf1/openwrt/image/          │
│  ├── sys_partition.fex                  │
│  ├── debian_rootfs.fex                  │
│  └── ...                                │
└─────────────────────────────────────────┘

因此，pack 命令会自动将 device/config/chips/v861/configs/bga_perf1/ 目录下的所有 .fex 文件复制到打包输出目录。如果将 rootfs 文件放到 out 目录下，它不会被自动复制，打包时会因找不到文件而报错。

分区表字段说明​

字段说明
name分区名称，必须唯一，最大 12 个字符
size分区大小，单位为扇区（512 字节）
downloadfile要烧录的文件名，必须以 .fex 结尾
user_type分区类型标识

注意事项​

分区大小设置​

确保分区大小足够容纳 rootfs 镜像：

  • size 字段单位为扇区（512 字节）

计算公式：

扇区数 = 镜像大小(字节) / 512

例如，512MB 的 rootfs 镜像：

size = 1048576    # 512MB = 512 * 1024 * 1024 / 512

文件格式要求​

  • 文件名必须以 .fex 结尾
  • 支持 ext4、squashfs 等常见 Linux 文件系统格式
  • 如使用 squashfs，确保内核已启用相应支持

恢复默认配置​

如需恢复使用 Tina 默认 rootfs，将 downloadfile 改回 rootfs.fex 即可：

downloadfile = "rootfs.fex"

常见问题​

Q: 打包时报错找不到文件？​

检查文件是否正确放置在板级配置目录：

ls device/config/chips/v861/configs/bga_perf1/*.fex

Q: 烧录后无法启动？​

  1. 检查 rootfs 是否与内核架构匹配
  2. 确认 rootfs 包含正确的 init 程序
  3. 检查设备树配置是否与 rootfs 兼容，init 程序调用是否正确

Q: 如何查看当前分区表配置？​

cat device/config/chips/v861/configs/bga_perf1/sys_partition.fex

Q: 支持哪些 rootfs 格式？​

  • ext4（推荐，可读写）
  • squashfs（只读，压缩，节省空间）
  • ubifs（适用于 NAND Flash）
  • 其他 rootfs（内核开启驱动即可支持）