NanoPi M5 26.5.1 UFS install: btrfs root does not boot and manual partition layout is not available

[Gabriel Becker]

Hi,

I would like to report an issue I encountered while testing the new NanoPi M5 UFS boot support in Armbian 26.5.1.

Board: NanoPi M5
Boot media for installation: SD card
Target storage: onboard UFS
BOOT switch after installation: UFS/SD
Tested images:

* `Armbian_26.5.1_Nanopi-m5_trixie_vendor_6.1.115_minimal.img.xz`
* `Armbian_26.5.1_Nanopi-m5_trixie_current_6.18.33_minimal.img.xz`

My current NVMe setup uses a custom layout:

* `ext4` `/boot`
* `btrfs` `/`

I had to use this layout because, in my previous NVMe tests, installing the system directly to NVMe with btrfs using `armbian-install` did not boot when `/boot` was also located on btrfs. With a separate ext4 `/boot` partition and a btrfs root filesystem, the NVMe setup works correctly.

When testing the new UFS installation path, I noticed that the UFS option in `armbian-install` seems to only install the whole system to `/dev/sda1` on the UFS General LUN. Unlike the NVMe installation path, I could not find a way to select an existing target partition or use a manually prepared partition layout.

I tried the following UFS layout manually:

* `/dev/sda1` as `ext4` for `/boot`
* `/dev/sda2` as `btrfs` for `/`

However, after splitting the UFS General LUN this way, the system did not boot at all.

I also tested the default UFS installation path without manually changing the partition layout. I booted from SD card, ran `armbian-install`, selected the UFS install option, and selected btrfs as the filesystem.

With both tested images listed above, the installation process completed, but after removing the SD card and booting from UFS with the BOOT switch set to UFS/SD, the system did not boot.

So the behavior I observed is:

* UFS installation creates and uses only `/dev/sda1` as the system partition.
* UFS installation with btrfs selected completes, but the installed system does not boot afterward.
* A manual layout with separate `ext4 /boot` and `btrfs /` on UFS also does not boot.
* The UFS install path does not seem to provide the same manual partition selection behavior as the NVMe install path.

My questions are:

1. Is btrfs on UFS expected to be bootable at this stage?
2. Or should ext4 currently be considered the only supported/recommended filesystem for UFS boot on NanoPi M5?

 

[Igor]

1. At this stage you should be extremly happy if it generally works trouble free.

2. Yes.

 

[eselarm]

root@nanopi-m5:~# grep BTRFS /usr/lib/u-boot/nanopi-m5-rk3576_defconfig
# CONFIG_CMD_BTRFS is not set
# CONFIG_FS_BTRFS is not set

So no direct Btrfs rootfs support. It is image Armbian_26.5.1_Nanopi-m5_trixie_current_6.18.33_minimal.img run as container quick test.

 

# gdisk -l Armbian_26.5.1_Nanopi-m5_trixie_current_6.18.33_minimal.img
GPT fdisk (gdisk) version 1.0.10

Partition table scan:
 MBR: protective
 BSD: not present
 APM: not present
 GPT: present

Found valid GPT with protective MBR; using GPT.
Disk armbian.img: 3252224 sectors, 1.6 GiB
Sector size (logical): 512 bytes
Disk identifier (GUID): 1F37D403-5DE7-4F81-AB22-D9825AE1EFEB
Partition table holds up to 128 entries
Main partition table begins at sector 2 and ends at sector 33
First usable sector is 2048, last usable sector is 3252190
Partitions will be aligned on 2048-sector boundaries
Total free space is 32735 sectors (16.0 MiB)

Number  Start (sector)    End (sector)  Size       Code  Name
  1           32768         3250175   1.5 GiB     8305  rootfs
 

There is no 4K sector 'awareness', that is the whole reason I ran this testing; If that is an issue with the M5, I don't own and don't know, but I have encountered quite some issues in Linux in general w.r.t. that, so I would for sure scan armbian-install script to see what is done. Risk with 6.1.115 kernel is that is messes up 512/4k things when Btrfs as kernel 6.7 or later is needed to handle it transparently. Check all yourself, as is long time ago I checked it and I use mostly latest Linux, so kernel > 6.18 currently.

[Gabriel Becker]

Thanks for the replies.

I understand that native UFS boot support is still very new, and that ext4 is currently the safest and expected path.

After some more testing, I managed to get a separate ext4 /boot + btrfs / layout working on my NanoPi M5 with the onboard 64GB UFS.

This is not a request for official support, and I do not want to imply that this is a recommended or fully tested solution. I am only sharing it as an experimental helper script for users who may want to test a similar layout.

============================================================
WORKING LAYOUT
==============

The layout I tested successfully is:

* /dev/sda1: ext4, mounted as /boot, LABEL=BOOT
* /dev/sda2: btrfs, mounted as /, LABEL=ROOT
* btrfs subvolume @ mounted as /
* btrfs subvolume @snapshots mounted as /.snapshots

The reason this works is that U-Boot only needs to read /boot from ext4. The Linux kernel and initramfs can then mount the root filesystem as btrfs.

============================================================
WHAT THE SCRIPT DOES
====================

The attached script does the following:

1. Checks that it is running as root.

2. Checks that the system is not currently running from UFS.

3. Checks that the expected UFS LUN devices exist.

4. Mounts an official Armbian NanoPi M5 image read-only through a loop device.

5. Creates a minimal safety backup.

6. Wipes and repartitions the UFS General LUN.

7. Creates an ext4 /boot partition starting at 32MiB.

8. Creates a btrfs root partition after /boot.

9. Creates btrfs subvolumes @ and @snapshots.

10. Sets @ as the default btrfs subvolume.

11. Copies the root filesystem from the Armbian image to the btrfs root.

12. Copies /boot from the Armbian image to the ext4 /boot partition.

13. Writes /etc/fstab.

14. Updates /boot/armbianEnv.txt with:

    rootdev=LABEL=ROOT
    rootfstype=btrfs

15. Ensures btrfs support is included in the target initramfs.

16. Regenerates /boot/boot.scr.

17. Uses the official write_uboot_platform_ufs() function from the image to write the UFS bootloader.

18. Performs some basic validation before finishing.

The script does not patch boot.cmd. Instead, it relies on:

* rootdev=LABEL=ROOT
* rootfstype=btrfs
* btrfs default subvolume set to @

This keeps the boot script closer to the official Armbian files.

============================================================
IMPORTANT NOTES
===============

This script is destructive.

It wipes the UFS General LUN.

It assumes the usual NanoPi M5 UFS mapping:

* /dev/sda = UFS General LUN
* /dev/sdb = UFS Boot LUN A
* /dev/sdc = UFS Boot LUN B
* /dev/sdd = vendor/config LUN

It was only tested on my NanoPi M5 with onboard 64GB UFS.

Please review the script carefully before running it.

I am attaching it only as an experimental helper for testing, not as an official solution.

============================================================
BASIC USAGE
===========

Boot from an SD card maintenance system first.

Make sure the Armbian image is already decompressed to .img.

Example:

sudo ./flash-nanopi-m5-ufs-btrfs.sh 
--image /path/to/Armbian_26.5.1_Nanopi-m5_trixie_vendor_6.1.115_minimal.img

For a dry run:

sudo ./flash-nanopi-m5-ufs-btrfs.sh 
--image /path/to/Armbian_26.5.1_Nanopi-m5_trixie_vendor_6.1.115_minimal.img 
--dry-run 
--yes-i-understand

The script requires typing:

YES_FLASH_UFS

before it performs the destructive flashing operation, unless --yes-i-understand is used.

============================================================
RESULT
======

With this layout, the system boots successfully from UFS on my NanoPi M5 with the BOOT switch set to UFS/SD.

After booting, I verified that:

* / is btrfs from LABEL=ROOT
* /boot is ext4 from LABEL=BOOT
* /.snapshots is a btrfs subvolume
* the system boots without requiring U-Boot to read btrfs directly

I hope this may help other users who want a btrfs root filesystem on UFS while keeping /boot on ext4.

flash-nanopi-m5-ufs-btrfs.sh

Edited 5 hours ago by Gabriel Becker

[eselarm]

I was curious and looked into your script, I see parted uses sizes like 32MiB instead of sector numbers I tend to do when using gdisk or fdisk

It is only the function write_uboot_platform_ufs() in the image that deals with 512/4k and then it is no issue for Btrfs as this is not related to CPU page-size issues I hinted earlier. So also older kernel is no issue and also RK3576 cannot do e.g. 16k page-size.