Skip to content

PLATFORM_NOTES.md

Latest commit

 

History

History
220 lines (171 loc) · 5.54 KB

PLATFORM_NOTES.md

File metadata and controls

220 lines (171 loc) · 5.54 KB
Raw

Platform-Specific Build Notes

macOS

What Works Natively

✅ All build commands except UBI/UBIFS:

  • lf build loader - Boot loader (download.bin)
  • lf build env - U-Boot environment (env.img)
  • lf build pack - Final firmware assembly
  • lf flash - Device flashing
  • lf firmware info - Image inspection

What Requires Docker/Linux

❌ UBI/UBIFS rootfs building (SPI-NAND devices only):

  • lf build rootfs - Needs mkfs.ubifs and ubinize from mtd-utils
  • These are Linux kernel subsystem tools, not available on macOS

Solutions for SPI-NAND Builds

Option 1: Docker (Recommended)

# One-time setup: pull Ubuntu image
docker pull ubuntu:22.04

# For each build session:
docker run -it --rm \
  -v "$PWD:/work" \
  -w /work \
  ubuntu:22.04 bash

# Inside container:
apt-get update && apt-get install -y mtd-utils
./lf build rootfs rootfs-alpine.tar.gz --device pico-pro-max -o images/rootfs.img
exit

Option 2: Remote Linux Build Server

# Copy files to Linux machine
scp -r . user@linux-server:~/build/

# SSH and build
ssh user@linux-server 'cd ~/build && lf build rootfs ...'

# Copy back
scp user@linux-server:~/build/images/rootfs.img images/

Option 3: GitHub Actions / CI

# .github/workflows/build-firmware.yml
name: Build Firmware
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install tools
        run: sudo apt-get install -y mtd-utils u-boot-tools
      - name: Build rootfs
        run: lf build rootfs rootfs.tar.gz --device pico-pro-max -o rootfs.img
      - uses: actions/upload-artifact@v3
        with:
          name: rootfs.img
          path: rootfs.img

SD Card Builds (No Docker Needed!)

For SD Card devices (pico, pico-pi, pico-zero), use ext4 instead of UBI:

# Install ext4 tools (if not already available)
brew install e2fsprogs

# Create ext4 rootfs image
dd if=/dev/zero of=images/rootfs.img bs=1M count=2048
mkfs.ext4 images/rootfs.img

# Mount and populate (requires sudo)
mkdir -p /tmp/mnt
sudo mount -o loop images/rootfs.img /tmp/mnt
sudo tar -xzf rootfs-alpine.tar.gz -C /tmp/mnt
sudo umount /tmp/mnt

# Continue with normal build
lf build pack images/package-file --device pico-pi -o update.img

Linux

What Works

✅ Everything works natively:

  • All build commands
  • All device types (SPI-NAND and SD Card)

Prerequisites

# Ubuntu/Debian
sudo apt-get install u-boot-tools mtd-utils

# Arch
sudo pacman -S uboot-tools mtd-utils

# Fedora
sudo dnf install uboot-tools mtd-utils

Windows

Using WSL2 (Recommended)

# Install WSL2 with Ubuntu
wsl --install

# Inside WSL:
sudo apt-get update
sudo apt-get install u-boot-tools mtd-utils

# Build as normal
lf build rootfs rootfs.tar.gz --device pico-pro-max -o rootfs.img

Native Windows

  • Most tools not available
  • Use WSL2 or Docker Desktop with Linux containers
  • Or use a Linux VM

Cross-Platform Workflow

Recommended Approach: Hybrid

On macOS/Windows (development):

# Build what works natively
lf build loader ~/rkbin/RKBOOT/RV1106MINIALL.ini --rkbin-base ~/rkbin -o images/download.bin
lf build env pico-pro-max -o images/env.img

# Copy pre-built components
cp kernel/boot.img images/
cp uboot/uboot.img images/

On Linux (rootfs only):

# Just build the UBI image
lf build rootfs rootfs-alpine.tar.gz --device pico-pro-max -o images/rootfs.img

Back on macOS/Windows:

# Final assembly (works everywhere)
lf build pack images/package-file --device pico-pro-max -o update.img
lf flash update.img

Device Type Recommendations by Platform

macOS Users

Easy (no Docker):

  • ✅ Pico (SD Card)
  • ✅ Pico Pi / Pi W (SD Card)
  • ✅ Pico Zero (SD Card)

Requires Docker/Linux:

  • ⚠️ Pico Mini / Mini B (SPI-NAND)
  • ⚠️ Pico Plus (SPI-NAND)
  • ⚠️ Pico Pro Max (SPI-NAND)
  • ⚠️ Pico Ultra / Ultra W (SPI-NAND)
  • ⚠️ Pico WebBee (SPI-NAND)

Linux Users

All devices work natively:

  • ✅ All SPI-NAND devices
  • ✅ All SD Card devices

Quick Decision Tree

Are you building for SPI-NAND device?
├─ Yes → Need UBI/UBIFS
│  ├─ On Linux? → Works natively ✅
│  ├─ On macOS? → Use Docker 🐳
│  └─ On Windows? → Use WSL2 or Docker 🐳
│
└─ No (SD Card) → ext4 only
   ├─ On Linux? → Works natively ✅
   ├─ On macOS? → Works natively ✅
   └─ On Windows? → Use WSL2 (for loop mount)

Tool Availability Matrix

Tool macOS Native Linux Native Windows WSL2 Windows Native
lf binary ✅ ✅ ✅ ✅
mkenvimage ✅ (brew) ✅ (apt) ✅ (apt) ❌
mkfs.ubifs ❌ ✅ ✅ ❌
ubinize ❌ ✅ ✅ ❌
mkfs.ext4 ✅ (brew) ✅ ✅ ❌

Best Practices

  1. Develop on your platform - Use what works natively
  2. Use CI for full builds - GitHub Actions, GitLab CI
  3. Keep Linux for final builds - Most compatible
  4. Test on real hardware - Cross-platform build issues rare with lf

Future: Pure Rust Implementation?

The lf tool already implements the complex Rockchip-specific formats in pure Rust. The only remaining external dependencies are standard Linux tools:

  • mkenvimage - Could be implemented in Rust (U-Boot env format is simple)
  • mkfs.ubifs + ubinize - Complex, better to shell out
  • mkfs.ext4 - Complex, better to shell out

For now, Docker provides excellent cross-platform compatibility for the Linux-specific tools.