Ubuntu 24.04 LTS (Noble Numbat) for TaishanPi-3M RK3576 开发板

# 在 SDK 根目录
./build.sh tspi_3m_rk3576_ubuntu_noble_gnome_defconfig
./build.sh all

# 或者单独构建 Ubuntu rootfs
./build.sh tspi_3m_rk3576_ubuntu_noble_gnome_defconfig
cd ubuntu
sudo ./mk-rootfs.sh

ubuntu/
├── ubuntu-base-arm64.tar.gz          # 下载的 Ubuntu base
├── ubuntu-rootfs.img                 # 构建的 rootfs 镜像
└── binary/                           # 临时构建目录

---

┌─────────────────────────────────────────────────────────────┐
│ 1. 准备阶段 (mk-base-ubuntu.sh)                             │
├─────────────────────────────────────────────────────────────┤
│ • 下载 Ubuntu base (ubuntu-base-24.04.4-base-arm64.tar.gz) │
│ • 解压到 binary/ 目录                                        │
│ • 设置 QEMU 用户模式模拟 (binfmt_misc)                      │
│ • 挂载 /proc, /sys, /dev 等                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Chroot 配置阶段 (chroot-script.sh)                       │
├─────────────────────────────────────────────────────────────┤
│ • 配置 APT 源 (支持镜像加速)                                │
│ • 安装 essential 包 (python3, systemd, etc.)               │
│ • 系统升级 (apt upgrade)                                    │
│ • 安装软件包 (从 config/package-lists/)                    │
│ • 安装 Rockchip 硬件包 (从 packages/arm64/)                │
│   - libmali (GPU)                                           │
│   - mpp (视频编解码)                                        │
│   - camera_engine_rkaiq (相机)                              │
│   - rkwifibt (WiFi/蓝牙)                                    │
│   - gst-rkmpp (GStreamer 硬件加速)                          │
│ • 创建用户 (lckfb)                                          │
│ • 系统配置 (locale, timezone, hostname)                     │
│ • 清理缓存                                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Overlay 应用阶段 (post-build.sh)                         │
├─────────────────────────────────────────────────────────────┤
│ • 复制 overlay/ 到 rootfs                                   │
│   - 系统配置文件 (/etc/)                                    │
│   - systemd 服务                                            │
│   - 脚本和工具                                              │
│ • 复制 overlay-firmware/ 到 rootfs                          │
│   - Rockchip 固件文件                                       │
│ • 设置文件权限                                              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 打包阶段 (mk-image.sh)                                   │
├─────────────────────────────────────────────────────────────┤
│ • 创建 ext4 镜像文件                                        │
│ • 复制 rootfs 到镜像                                        │
│ • 卸载 chroot 环境                                          │
│ • 生成 ubuntu-rootfs.img                                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. 首次启动配置 (rockchip.service)                          │
├─────────────────────────────────────────────────────────────┤
│ • 检测芯片型号 (RK3576)                                     │
│ • 安装芯片特定包 (libmali, camera_engine_rkaiq)            │
│ • 配置 GPU 环境                                             │
│ • 创建 first_boot_flag                                      │
│ • 同步文件系统 (sync)                                       │
│ • 自动重启                                                  │
└─────────────────────────────────────────────────────────────┘

阶段	时间	说明
下载 Ubuntu base	1-5 分钟	取决于网络速度
解压和挂载	30 秒
Chroot 配置	10-30 分钟	取决于网络和 CPU
Overlay 应用	10 秒
打包镜像	2-5 分钟	取决于存储速度
总计	15-40 分钟

---

ubuntu/
├── README.md                          # 本文档
├── .gitignore                         # Git 忽略规则
│
├── mk-rootfs.sh                       # 主构建脚本（入口）
├── mk-rootfs-noble.sh                 # Noble 特定构建脚本
├── mk-base-ubuntu.sh                  # 准备 Ubuntu base
├── mk-image.sh                        # 打包 rootfs 镜像
├── ch-mount.sh                        # Chroot 挂载辅助脚本
├── chroot-script.sh                   # Chroot 内执行的配置脚本
├── post-build.sh                      # 后处理脚本（应用 overlay）
├── clean.sh                           # 清理构建产物
│
├── config/                            # 配置文件
│   ├── README.md                      # 配置说明
│   ├── package-lists/                 # 软件包列表
│   │   ├── essential.list             # 必需包（python3, systemd）
│   │   ├── base.list                  # 基础包（udev, network）
│   │   └── hardware.list              # 硬件加速包（gstreamer）
│   └── hooks/                         # 自定义钩子脚本
│       └── *.sh                       # 在 chroot 后执行
│
├── overlay/                           # 文件系统覆盖层
│   ├── etc/                           # 系统配置
│   │   ├── init.d/rockchip.sh         # Rockchip 初始化脚本
│   │   ├── systemd/system/            # Systemd 服务
│   │   ├── NetworkManager/            # 网络配置
│   │   ├── profile.d/                 # 环境变量
│   │   └── update-motd.d/             # 登录欢迎信息
│   └── usr/
│       ├── local/bin/                 # 自定义脚本
│       │   └── rockchip-wrapper.sh    # 首次启动日志包装器
│       └── lib/systemd/system/        # Systemd 服务文件
│
├── overlay-firmware/                  # 固件文件覆盖层
│   └── usr/
│       ├── bin/                       # Rockchip 工具
│       ├── lib/firmware/rockchip/     # Rockchip 固件
│       └── share/alsa/                # ALSA 配置
│
├── packages/                          # Rockchip 专有包
│   └── arm64/                         # ARM64 架构包
│       ├── libmali/                   # Mali GPU 驱动
│       ├── mpp/                       # 视频编解码
│       ├── rga2/                      # 2D 图形加速
│       ├── gst-rkmpp/                 # GStreamer 硬件加速
│       ├── rkaiq/                     # 相机 ISP
│       ├── rkwifibt/                  # WiFi/蓝牙固件
│       ├── chromium/                  # Chromium 浏览器
│       └── ...
│
├── binary/                            # 临时构建目录（自动生成）
│   ├── bin/, lib/, usr/, ...          # Ubuntu rootfs
│   ├── packages/                      # 复制的包（chroot 内可见）
│   └── config/                        # 复制的配置（chroot 内可见）
│
├── ubuntu-base-arm64.tar.gz           # Ubuntu base 压缩包
└── ubuntu-rootfs.img                  # 最终 rootfs 镜像

---

软件包列表使用简单的文本格式，每行一个包名，支持注释。

# Essential packages for minimal Ubuntu base system
python3
python3-minimal
ca-certificates
apt-transport-https
systemd
systemd-sysv
dbus
adduser
passwd
sudo
lsb-release
libcap2-bin

安装时机: 最先安装，在 apt upgrade 之前

# System utilities
udev
network-manager
wireless-tools
wpasupplicant

# Desktop environment
ubuntu-gnome-desktop
gdm3
gnome-shell
gnome-terminal

# Fonts
fonts-noto-cjk
fonts-wqy-zenhei

安装时机: 在 essential 包之后

# Video codec (GStreamer)
gstreamer1.0-plugins-bad
gstreamer1.0-plugins-good
gstreamer1.0-plugins-ugly
gstreamer1.0-tools

# Audio
pipewire
pipewire-pulse
pipewire-alsa

安装时机: 在 base 包之后

编辑对应的 .list 文件：

# 编辑 base.list
vim config/package-lists/base.list

# 添加包名
vim
htop
tmux

在 chroot 配置完成后执行自定义脚本：

# 创建钩子脚本
cat > config/hooks/01-custom-config.sh << 'EOF'
#!/bin/bash
echo "Running custom configuration..."

# 安装额外软件
apt-get install -y neofetch

# 自定义配置
echo "export EDITOR=vim" >> /etc/profile.d/custom.sh
EOF

chmod +x config/hooks/01-custom-config.sh

执行顺序: 按文件名字母顺序执行

---

#!/bin/bash -e
RELEASE=${RELEASE:-noble}
ARCH=${ARCH:-arm64}
./mk-rootfs-noble.sh

用法:

sudo ./mk-rootfs.sh

主要构建逻辑：

1. 调用 mk-base-ubuntu.sh 准备 base
2. 复制 packages 和 config 到 binary/
3. Chroot 执行 chroot-script.sh
4. 调用 post-build.sh 应用 overlay
5. 调用 mk-image.sh 打包镜像

环境变量:

UBUNTU_MIRROR=mirrors.tuna.tsinghua.edu.cn  # APT 镜像
ARCH=arm64                                   # 架构
VERSION=debug                                # 构建版本

# 下载 Ubuntu base
wget http://cdimage.ubuntu.com/ubuntu-base/releases/24.04/release/ubuntu-base-24.04.4-base-arm64.tar.gz

# 解压
sudo tar -xpf ubuntu-base-arm64.tar.gz -C binary/

# 设置 QEMU
sudo cp /usr/bin/qemu-aarch64-static binary/usr/bin/

# 挂载
sudo mount -t proc /proc binary/proc
sudo mount -t sysfs /sys binary/sys
sudo mount -o bind /dev binary/dev
sudo mount -o bind /dev/pts binary/dev/pts

在 chroot 环境内执行的配置脚本，主要步骤：

1. 配置 APT 源
2. 安装软件包
3. 安装 Rockchip 包
4. 创建用户
5. 系统配置

# 复制 overlay
sudo cp -rp overlay/* binary/

# 复制 overlay-firmware
sudo cp -rp overlay-firmware/* binary/

# 设置权限
sudo chmod +x binary/etc/init.d/rockchip.sh
sudo chmod +x binary/usr/local/bin/*.sh

# 创建 ext4 镜像
dd if=/dev/zero of=ubuntu-rootfs.img bs=1M count=4096
mkfs.ext4 ubuntu-rootfs.img

# 挂载并复制
sudo mount ubuntu-rootfs.img /mnt
sudo cp -a binary/* /mnt/
sudo umount /mnt

# 卸载 chroot
sudo umount binary/proc binary/sys binary/dev/pts binary/dev

# 删除临时文件
sudo rm -rf binary/
rm -f ubuntu-rootfs.img

---

包名	用途	大小
libmali	Mali GPU 驱动 (G52)	~50MB
mpp	视频编解码 (MPP)	~5MB
rga2	2D 图形加速	~2MB
gst-rkmpp	GStreamer 硬件加速插件	~1MB
rkaiq	相机 ISP (camera_engine_rkaiq)	~20MB
rkisp	相机驱动	~5MB
rkwifibt	WiFi/蓝牙固件和工具	~4MB
chromium	Chromium 浏览器（硬件加速）	~200MB
pipewire	音频服务器	~5MB
wireplumber	PipeWire 会话管理器	~2MB

1. Ubuntu 官方仓库

   • 通过 APT 安装
   • 例如：gnome-shell, network-manager

2. Rockchip 预编译包

   • 存储在 packages/arm64/
   • 通过 dpkg -i 安装
   • 例如：libmali, mpp, rkwifibt

# 1. 将 .deb 包放入对应目录
cp my-package.deb packages/arm64/my-package/

# 2. 在 chroot-script.sh 中添加安装命令
echo 'dpkg -i /packages/my-package/*.deb || apt-get install -fy' >> chroot-script.sh

# 3. 重新构建
sudo ./mk-rootfs.sh

---

Overlay 系统允许在不修改构建脚本的情况下自定义文件系统。

overlay/
├── etc/
│   ├── init.d/
│   │   └── rockchip.sh              # Rockchip 初始化脚本
│   ├── systemd/system/
│   │   ├── rockchip.service         # Rockchip 服务
│   │   ├── gpu-performance.service  # GPU 性能模式
│   │   └── btattach.service         # 蓝牙 UART 初始化
│   ├── NetworkManager/
│   │   └── NetworkManager.conf      # 网络管理器配置
│   ├── profile.d/
│   │   └── gsk-renderer.sh          # GTK4 渲染器配置
│   ├── environment.d/
│   │   └── gsk-renderer.conf        # 环境变量
│   └── update-motd.d/
│       └── 00-tspi                  # 登录欢迎信息
└── usr/
    └── local/bin/
        └── rockchip-wrapper.sh      # 首次启动日志包装器

overlay-firmware/
└── usr/
    ├── bin/
    │   ├── npu_upgrade               # NPU 升级工具
    │   └── upgrade_tool              # 固件升级工具
    ├── lib/firmware/rockchip/
    │   └── dptx.bin                  # DisplayPort 固件
    └── share/alsa/
        └── ucm/                      # ALSA 配置

首次启动时，rockchip.service 会记录详细日志：

# 查看首次启动日志
cat /var/log/rockchip-first-boot.log

# 查看 systemd journal
journalctl -u rockchip.service -b

日志内容:

• bash -x 输出（每条命令）
• 包安装详细输出
• 固件配置过程
• 执行时间和退出码