Ubuntu 24.04 LTS (Noble Numbat) for TaishanPi-3M RK3576 Development Board

# In SDK root directory
./build.sh tspi_3m_rk3576_ubuntu_noble_gnome_defconfig
./build.sh all

# Or build Ubuntu rootfs separately
./build.sh tspi_3m_rk3576_ubuntu_noble_gnome_defconfig
cd ubuntu
sudo ./mk-rootfs.sh

ubuntu/
├── ubuntu-base-arm64.tar.gz          # Downloaded Ubuntu base
├── ubuntu-rootfs.img                 # Built rootfs image
└── binary/                           # Temporary build directory

---

┌─────────────────────────────────────────────────────────────┐
│ 1. Preparation Stage (mk-base-ubuntu.sh)                    │
├─────────────────────────────────────────────────────────────┤
│ • Download Ubuntu base (ubuntu-base-24.04.4-base-arm64)    │
│ • Extract to binary/ directory                              │
│ • Setup QEMU user mode emulation (binfmt_misc)             │
│ • Mount /proc, /sys, /dev, etc.                             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Chroot Configuration Stage (chroot-script.sh)            │
├─────────────────────────────────────────────────────────────┤
│ • Configure APT sources (mirror acceleration support)       │
│ • Install essential packages (python3, systemd, etc.)      │
│ • System upgrade (apt upgrade)                              │
│ • Install packages (from config/package-lists/)            │
│ • Install Rockchip hardware packages (from packages/arm64/)│
│   - libmali (GPU)                                           │
│   - mpp (video codec)                                       │
│   - camera_engine_rkaiq (camera)                            │
│   - rkwifibt (WiFi/Bluetooth)                               │
│   - gst-rkmpp (GStreamer hardware acceleration)            │
│ • Create user (lckfb)                                       │
│ • System configuration (locale, timezone, hostname)         │
│ • Clean cache                                               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Overlay Application Stage (post-build.sh)                │
├─────────────────────────────────────────────────────────────┤
│ • Copy overlay/ to rootfs                                   │
│   - System configuration files (/etc/)                      │
│   - systemd services                                        │
│   - Scripts and tools                                       │
│ • Copy overlay-firmware/ to rootfs                          │
│   - Rockchip firmware files                                 │
│ • Set file permissions                                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Packaging Stage (mk-image.sh)                            │
├─────────────────────────────────────────────────────────────┤
│ • Create ext4 image file                                    │
│ • Copy rootfs to image                                      │
│ • Unmount chroot environment                                │
│ • Generate ubuntu-rootfs.img                                │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. First Boot Configuration (rockchip.service)              │
├─────────────────────────────────────────────────────────────┤
│ • Detect chip model (RK3576)                                │
│ • Install chip-specific packages (libmali, camera_engine)  │
│ • Configure GPU environment                                 │
│ • Create first_boot_flag                                    │
│ • Sync filesystem (sync)                                    │
│ • Auto reboot                                               │
└─────────────────────────────────────────────────────────────┘

Stage	Time	Notes
Download Ubuntu base	1-5 min	Depends on network speed
Extract and mount	30 sec
Chroot configuration	10-30 min	Depends on network and CPU
Overlay application	10 sec
Package image	2-5 min	Depends on storage speed
Total	15-40 min

---

ubuntu/
├── README.md                          # This document
├── .gitignore                         # Git ignore rules
│
├── mk-rootfs.sh                       # Main build script (entry point)
├── mk-rootfs-noble.sh                 # Noble-specific build script
├── mk-base-ubuntu.sh                  # Prepare Ubuntu base
├── mk-image.sh                        # Package rootfs image
├── ch-mount.sh                        # Chroot mount helper script
├── chroot-script.sh                   # Configuration script executed in chroot
├── post-build.sh                      # Post-processing script (apply overlay)
├── clean.sh                           # Clean build artifacts
│
├── config/                            # Configuration files
│   ├── README.md                      # Configuration documentation
│   ├── package-lists/                 # Package lists
│   │   ├── essential.list             # Essential packages (python3, systemd)
│   │   ├── base.list                  # Base packages (udev, network)
│   │   └── hardware.list              # Hardware acceleration packages (gstreamer)
│   └── hooks/                         # Custom hook scripts
│       └── *.sh                       # Executed after chroot
│
├── overlay/                           # Filesystem overlay
│   ├── etc/                           # System configuration
│   │   ├── init.d/rockchip.sh         # Rockchip initialization script
│   │   ├── systemd/system/            # Systemd services
│   │   ├── NetworkManager/            # Network configuration
│   │   ├── profile.d/                 # Environment variables
│   │   └── update-motd.d/             # Login welcome message
│   └── usr/
│       ├── local/bin/                 # Custom scripts
│       │   └── rockchip-wrapper.sh    # First boot log wrapper
│       └── lib/systemd/system/        # Systemd service files
│
├── overlay-firmware/                  # Firmware overlay
│   └── usr/
│       ├── bin/                       # Rockchip tools
│       ├── lib/firmware/rockchip/     # Rockchip firmware
│       └── share/alsa/                # ALSA configuration
│
├── packages/                          # Rockchip proprietary packages
│   └── arm64/                         # ARM64 architecture packages
│       ├── libmali/                   # Mali GPU driver
│       ├── mpp/                       # Video codec
│       ├── rga2/                      # 2D graphics acceleration
│       ├── gst-rkmpp/                 # GStreamer hardware acceleration
│       ├── rkaiq/                     # Camera ISP
│       ├── rkwifibt/                  # WiFi/Bluetooth firmware
│       ├── chromium/                  # Chromium browser
│       └── ...
│
├── binary/                            # Temporary build directory (auto-generated)
│   ├── bin/, lib/, usr/, ...          # Ubuntu rootfs
│   ├── packages/                      # Copied packages (visible in chroot)
│   └── config/                        # Copied configuration (visible in chroot)
│
├── ubuntu-base-arm64.tar.gz           # Ubuntu base tarball
└── ubuntu-rootfs.img                  # Final rootfs image

---

Package lists use simple text format, one package per line, with comment support.

# 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

Installation timing: Installed first, before 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

Installation timing: After essential packages

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

# Audio
pipewire
pipewire-pulse
pipewire-alsa

Installation timing: After base packages

Edit the corresponding .list file:

# Edit base.list
vim config/package-lists/base.list

# Add package names
vim
htop
tmux

Execute custom scripts after chroot configuration:

# Create hook script
cat > config/hooks/01-custom-config.sh << 'EOF'
#!/bin/bash
echo "Running custom configuration..."

# Install additional software
apt-get install -y neofetch

# Custom configuration
echo "export EDITOR=vim" >> /etc/profile.d/custom.sh
EOF

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

Execution order: Executed in alphabetical order by filename

---

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

Usage:

sudo ./mk-rootfs.sh

Main build logic:

1. Call mk-base-ubuntu.sh to prepare base
2. Copy packages and config to binary/
3. Execute chroot-script.sh in chroot
4. Call post-build.sh to apply overlay
5. Call mk-image.sh to package image

Environment variables:

UBUNTU_MIRROR=mirrors.tuna.tsinghua.edu.cn  # APT mirror
ARCH=arm64                                   # Architecture
VERSION=debug                                # Build version

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

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

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

# Mount
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

Configuration script executed inside chroot environment, main steps:

1. Configure APT sources
2. Install packages
3. Install Rockchip packages
4. Create user
5. System configuration

# Copy overlay
sudo cp -rp overlay/* binary/

# Copy overlay-firmware
sudo cp -rp overlay-firmware/* binary/

# Set permissions
sudo chmod +x binary/etc/init.d/rockchip.sh
sudo chmod +x binary/usr/local/bin/*.sh

# Create ext4 image
dd if=/dev/zero of=ubuntu-rootfs.img bs=1M count=4096
mkfs.ext4 ubuntu-rootfs.img

# Mount and copy
sudo mount ubuntu-rootfs.img /mnt
sudo cp -a binary/* /mnt/
sudo umount /mnt

# Unmount chroot
sudo umount binary/proc binary/sys binary/dev/pts binary/dev

# Delete temporary files
sudo rm -rf binary/
rm -f ubuntu-rootfs.img

---

Package	Purpose	Size
libmali	Mali GPU driver (G52)	~50MB
mpp	Video codec (MPP)	~5MB
rga2	2D graphics acceleration	~2MB
gst-rkmpp	GStreamer hardware acceleration plugin	~1MB
rkaiq	Camera ISP (camera_engine_rkaiq)	~20MB
rkisp	Camera driver	~5MB
rkwifibt	WiFi/Bluetooth firmware and tools	~4MB
chromium	Chromium browser (hardware accelerated)	~200MB
pipewire	Audio server	~5MB
wireplumber	PipeWire session manager	~2MB

1. Ubuntu Official Repository

   • Installed via APT
   • Examples: gnome-shell, network-manager

2. Rockchip Precompiled Packages

   • Stored in packages/arm64/
   • Installed via dpkg -i
   • Examples: libmali, mpp, rkwifibt

# 1. Place .deb package in corresponding directory
cp my-package.deb packages/arm64/my-package/

# 2. Add installation command in chroot-script.sh
echo 'dpkg -i /packages/my-package/*.deb || apt-get install -fy' >> chroot-script.sh

# 3. Rebuild
sudo ./mk-rootfs.sh

---

The overlay system allows customizing the filesystem without modifying build scripts.

overlay/
├── etc/
│   ├── init.d/
│   │   └── rockchip.sh              # Rockchip initialization script
│   ├── systemd/system/
│   │   ├── rockchip.service         # Rockchip service
│   │   ├── gpu-performance.service  # GPU performance mode
│   │   └── btattach.service         # Bluetooth UART initialization
│   ├── NetworkManager/
│   │   └── NetworkManager.conf      # Network manager configuration
│   ├── profile.d/
│   │   └── gsk-renderer.sh          # GTK4 renderer configuration
│   ├── environment.d/
│   │   └── gsk-renderer.conf        # Environment variables
│   └── update-motd.d/
│       └── 00-tspi                  # Login welcome message
└── usr/
    └── local/bin/
        └── rockchip-wrapper.sh      # First boot log wrapper

overlay-firmware/
└── usr/
    ├── bin/
    │   ├── npu_upgrade               # NPU upgrade tool
    │   └── upgrade_tool              # Firmware upgrade tool
    ├── lib/firmware/rockchip/
    │   └── dptx.bin                  # DisplayPort firmware
    └── share/alsa/
        └── ucm/                      # ALSA configuration

On first boot, rockchip.service records detailed logs:

# View first boot log
cat /var/log/rockchip-first-boot.log

# View systemd journal
journalctl -u rockchip.service -b

Log contents:

• bash -x output (every command)
• Package installation detailed output
• Firmware configuration process
• Execution time and exit code