Interactive SD-card-to-eMMC flasher for Arch Linux on the Banana Pi BPI-F3 (riscv64).

Keywords: #archlinux #riscv64 #risc-v #bpif3 #bananapi #spacemitk1 #emmc #sdcard #flasher #migration #installer #rsync

This repository migrates a running BPI-F3 Arch Linux installation from its SD card to an already provisioned internal eMMC boot layout.

The script supports English and 한국어 prompts. It preserves the existing eMMC boot hardware area and firmware partitions, replaces the eMMC boot files with the current Arch boot tree, creates a fresh eMMC root filesystem, and copies the live Arch system with two verified rsync passes.

• Board: Banana Pi BPI-F3 / SpacemiT K1
• Architecture: riscv64
• Operating system: Arch Linux with the BPI-F3 6.1.15-legacy-k1 boot stack
• Running SD root: /dev/mmcblk0p2 using EXT4
• Unmounted SD boot filesystem: /dev/mmcblk0p1 using FAT
• Target eMMC: /dev/mmcblk2
• Target eMMC boot area: /dev/mmcblk2boot0
• Required eMMC GPT partition names: env, opensbi, uboot, bootfs, and rootfs
• Required eMMC boot filesystem: FAT on /dev/mmcblk2p4
• Validated eMMC filesystem use: 1,369,931,776 bytes across the root and boot filesystems
• Validated minimum eMMC p5 capacity: 2.5 GiB, or 2,684,354,560 bytes
• Validated minimum whole-eMMC user capacity: 2,957,001,216 bytes
• Recommended nominal eMMC capacity: 4 GB or larger
• Destructive migration targets: /dev/mmcblk2p4 contents and /dev/mmcblk2p5

The eMMC GPT, boot0, and firmware partitions 1 through 3 must already contain a working BPI-F3 eMMC boot chain. The vendor-firmware provisioning workflow is available in itinfra7/bpi-f3-sdcard-emmc-flasher. This Arch Linux flasher validates and preserves that boot chain instead of flashing it again.

Run the script from the Arch Linux SD installation as root. Install the required Arch packages before migration.

pacman -S --needed rsync binutils e2fsprogs util-linux gawk grep sed findutils

Keep /dev/mmcblk0p1 unmounted and leave /boot as an empty directory. Persistent data to be migrated must reside on the /dev/mmcblk0p2 root filesystem; separately mounted filesystems are not copied across filesystem boundaries.

The capacity floor is based on the validated near-stock installation's measured eMMC filesystem use, not on the size of its source image. A real migration copy into a 2.5 GiB EXT4 p5 left 1,251,340,288 bytes available after filesystem metadata and reserved blocks, exceeding the required 1 GiB free-space margin. Adding the fixed pre-p5 layout and backup GPT sectors produces the 2,957,001,216-byte whole-eMMC minimum, so a nominal 4 GB eMMC has sufficient capacity.

The preflight still measures the running installation with du -sx -B1 /. If it has grown beyond the validated baseline, the script raises the p5 requirement using a 10 percent filesystem allowance and verifies after copying that at least 1 GiB remains available.

Keep a backup of important data. The source SD is not reformatted and should remain available until the first independent eMMC boot succeeds.

chmod +x bpi-f3-sdcard-emmc-flasher-archlinux.sh
./bpi-f3-sdcard-emmc-flasher-archlinux.sh --check
./bpi-f3-sdcard-emmc-flasher-archlinux.sh

The migration is interactive by default and powers the board off after all checks pass. Remove the SD card only after shutdown, then power the board on to test eMMC boot.

--check          Run preflight and source-boot checks without writing eMMC data.
--yes            Accept the destructive confirmation non-interactively.
--lang en|ko     Select English or Korean messages.
--no-poweroff    Leave the board running after verified migration.
--help           Show command help.

1. Verify Arch Linux, riscv64, the BPI-F3 kernel marker, source SD devices, and target eMMC identity.
2. Verify the fixed GPT sectors, partition names, unmounted target state, validated capacity floor or a larger dynamically calculated requirement, and nonempty preserved boot-chain regions.
3. Mount the SD boot filesystem read-only and validate the current kernel, initramfs, device tree, and dynamic rootfs selection files.
4. Record SHA-256 values for boot0, env, OpenSBI, and U-Boot.
5. Reformat only eMMC p5 as EXT4 and mount the existing eMMC p4 FAT filesystem.
6. Copy the live root with ACLs, xattrs, hard links, sparse files, numeric ownership, and filesystem boundaries preserved.
7. Mirror the current SD boot tree into eMMC p4 while retaining its filesystem UUID.
8. Rewrite the target fstab and boot environment for the new eMMC root UUID and refresh the target random seed.
9. Run checksum reconciliation, chroot validation, offline EXT4 verification, GPT validation, read-only boot remount checks, and boot-chain hash comparison.
10. Power off and wait for manual SD removal unless --no-poweroff was selected.

The root copy includes users, account password hashes, SSH host keys, NetworkManager profiles, and other persistent system configuration. Protect the eMMC to the same standard as the source SD.

No network credential is requested or embedded by the script. Existing NetworkManager profile files are accepted only when they retain root ownership and mode 0600.

Virtual filesystems, temporary files, persistent journal content, and the systemd-timesync clock file are excluded. Required empty runtime directories are recreated, and the eMMC system receives a new random seed.

If independent eMMC boot does not succeed, power the board off, reinsert the untouched source SD, and boot the original Arch installation. The script never writes eMMC boot0 or partitions 1 through 3, and it verifies that their SHA-256 values remain unchanged.

The source SD used for validation was created from Banana Pi's 2024-09-08-archriscv-lite-bpi-f3-3356MB.img system image, whose image file is 3,519,021,056 bytes. That file size is reference metadata rather than a target-capacity rule because the flasher operates on the resulting running installation and does not consume the image file directly.

The workflow was validated on a Banana Pi BPI-F3 with Arch Linux riscv64 and kernel 6.1.15-legacy-k1. Capacity validation reproduced the migration into a 2.5 GiB p5, including the production EXT4 format and root rsync, and confirmed 1,251,340,288 bytes of usable free space. Functional validation covered an offline EXT4 check, a read-only boot-filesystem remount, and a subsequent boot with the SD card physically absent.

• bpi-f3-sdcard-emmc-flasher-archlinux.sh performs preflight, migration, verification, and optional poweroff.

MIT License. See LICENSE.

Banana Pi and the BPI-F3 / SpacemiT K1 platform provide the target hardware context.

Arch Linux provides the operating system environment used by this migration workflow.

itinfra7 maintains the original BPI-F3 SD-card-to-eMMC flashing workflow and this Arch Linux flasher variant.