Linux Btrfs filesystem development
 help / color / mirror / Atom feed
* [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd
@ 2026-11-16 22:43 Ismael Luceno
  2026-11-16 22:43 ` [PATCH 1/8] btrfs: add config options for the root device scan Ismael Luceno
                   ` (5 more replies)
  0 siblings, 6 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel, linux-btrfs
  Cc: Ismael Luceno, David Sterba, Chris Mason, Christian Brauner,
	Alexander Viro, Jan Kara, linux-fsdevel, linux-doc

A multi-device btrfs root filesystem is normally assembled by the device
scanner that an initrd runs before mounting the root.  Without an initrd
nothing runs that scanner, so the root mount names a single device and
the rest of the array is left out.

This series lets btrfs assemble such a root filesystem in the kernel:

  * mount devtmpfs on the initial root before the root filesystem, so
    device nodes exist to open the other devices by name (init);
  * let a filesystem tell whether it is mounting the root device and read
    rootwait, and resolve root=UUID=/root=LABEL= values that name the
    filesystem rather than a partition (init/VFS);
  * scan all block devices for the remaining members of a btrfs root
    filesystem, and wait for all of them to appear before mounting.

The scan and wait are gated on CONFIG_BTRFS_ROOT_SCAN (default y) and
only act on the root mount when the user asked for it with rootwait, so
non-root mounts and systems without the option are unchanged.


Ismael Luceno (8):
  btrfs: add config options for the root device scan
  init: mount devtmpfs before the root filesystem
  init: let filesystems ask whether they are mounting the root device
  btrfs: add a helper to scan all block devices
  btrfs: wait for the root filesystem to have all its devices
  Documentation: btrfs: document waiting for the root filesystem devices
  init: let a filesystem resolve a root device by UUID or label
  btrfs: resolve root=UUID= and root=LABEL=

 Documentation/filesystems/btrfs.rst |  31 +++++
 fs/btrfs/Kconfig                    |  25 ++++
 fs/btrfs/super.c                    | 165 +++++++++++++++++++++++
 fs/btrfs/volumes.c                  | 196 ++++++++++++++++++++++++++++
 fs/btrfs/volumes.h                  |  25 ++++
 fs/filesystems.c                    |  37 ++++++
 include/linux/fs.h                  |  10 ++
 include/linux/root_dev.h            |  14 ++
 init/do_mounts.c                    |  51 +++++++-
 9 files changed, 553 insertions(+), 1 deletion(-)


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH 1/8] btrfs: add config options for the root device scan
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
@ 2026-11-16 22:43 ` Ismael Luceno
  2026-11-16 22:43 ` [PATCH 4/8] btrfs: add a helper to scan all block devices Ismael Luceno
                   ` (4 subsequent siblings)
  5 siblings, 0 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel
  Cc: Ismael Luceno, Ismael Luceno, David Sterba, Chris Mason,
	open list:BTRFS FILE SYSTEM

Add Kconfig options to enable scanning all block devices for the remaining
members of a multi-device btrfs root filesystem when no initrd is available
to run the device scanner, plus a configurable polling interval for the scan.

The scan relies on devtmpfs device nodes and is used by the root-device wait
logic that follows in this series.

Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 fs/btrfs/Kconfig | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/fs/btrfs/Kconfig b/fs/btrfs/Kconfig
index 4b10d78ed99b..c8ce06c9c3e7 100644
--- a/fs/btrfs/Kconfig
+++ b/fs/btrfs/Kconfig
@@ -82,6 +82,31 @@ config BTRFS_ASSERT
 
 	  If unsure, say N.
 
+config BTRFS_ROOT_SCAN
+	bool "Btrfs multi-device root scan support"
+	select DEVTMPFS
+	depends on BTRFS_FS
+	default y
+	help
+	  When btrfs is the root filesystem and rootwait is given, look in the
+	  kernel for the rest of a multi-device filesystem.  This is for systems
+	  without an initrd to run the device scanner.  It finds devices through
+	  the device nodes that devtmpfs provides.
+
+	  If unsure, say Y.
+
+config BTRFS_ROOT_SCAN_INTERVAL_MS
+	int "Interval between device scans while waiting for root devices (ms)"
+	depends on BTRFS_ROOT_SCAN
+	range 1 10000
+	default 100
+	help
+	  How often, in milliseconds, to re-scan the block devices while
+	  waiting for all of a multi-device root filesystem's devices to
+	  appear.  Only used together with CONFIG_BTRFS_ROOT_SCAN.
+
+	  If unsure, say 100.
+
 config BTRFS_EXPERIMENTAL
 	bool "Btrfs experimental features"
 	depends on BTRFS_FS

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH 4/8] btrfs: add a helper to scan all block devices
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
  2026-11-16 22:43 ` [PATCH 1/8] btrfs: add config options for the root device scan Ismael Luceno
@ 2026-11-16 22:43 ` Ismael Luceno
  2026-11-17 13:10   ` kernel test robot
  2026-11-16 22:43 ` [PATCH 5/8] btrfs: wait for the root filesystem to have all its devices Ismael Luceno
                   ` (3 subsequent siblings)
  5 siblings, 1 reply; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel
  Cc: Ismael Luceno, Ismael Luceno, David Sterba, Chris Mason,
	open list:BTRFS FILE SYSTEM

btrfs learns about the devices of a filesystem from the mount source,
from the device= mount options, or from userspace running the device
scanner through the BTRFS_IOC_SCAN_DEV ioctl.  When btrfs is the root
filesystem and there is no initrd, none of those is there: the root
mount names one device and the rest of the array is left out.

Add btrfs_scan_all_devices(), which walks the block class and hands
every candidate to btrfs_scan_one_device(), the same path the ioctl
takes.  It is the kernel side of the scanner userspace would normally
run, so that the devices can be found without userspace.

A whole disk carrying a partition table is skipped.  btrfs reads its
superblock from a fixed offset near the start of the device, which on
a partitioned disk can fall inside the first partition, and picking the
disk up as a btrfs device when the partition is the real one would be
wrong.  Partitions themselves, and disks with no partition table, are
scanned as before.

The device is opened by its /dev name, which is what the rest of btrfs
records in device->name.

This adds no behaviour on its own; a caller is added separately.

Partitions are registered with part_type and disks with disk_type, so
iterating with a type filter for either skips the other.  Iterate
everything and let btrfs_can_scan_disk() decide, so a partition is
scanned and a disk that only holds partitions is not.

Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 fs/btrfs/volumes.c | 79 ++++++++++++++++++++++++++++++++++++++++++++++
 fs/btrfs/volumes.h |  3 ++
 2 files changed, 82 insertions(+)

diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index f1305f68b1f8..55f11c9fe24c 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
@@ -1531,6 +1531,85 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 	return device;
 }
 
+#ifdef CONFIG_BTRFS_ROOT_SCAN
+/*
+ * Return true if @disk is worth handing to btrfs_scan_one_device().
+ *
+ * A partition always is.  A whole disk only is when it carries no partition
+ * table: if it does, the first partition may well have a signature in the
+ * area btrfs reads from, and picking the disk up as a btrfs device would be
+ * wrong.
+ */
+static bool btrfs_can_scan_disk(struct gendisk *disk, struct block_device *bdev)
+{
+	struct block_device *part;
+	unsigned long idx;
+
+	if (!get_capacity(disk) || (disk->flags & GENHD_FL_HIDDEN))
+		return false;
+	if (bdev_is_partition(bdev))
+		return true;
+
+	rcu_read_lock();
+	xa_for_each_start(&disk->part_tbl, idx, part, 1) {
+		if (bdev_nr_sectors(part)) {
+			rcu_read_unlock();
+			return false;
+		}
+	}
+	rcu_read_unlock();
+
+	return true;
+}
+
+/*
+ * Register every block device that holds a btrfs superblock.
+ *
+ * This is the kernel side of the device scanner userspace normally drives with
+ * the BTRFS_IOC_SCAN_DEV ioctl.  It exists for the case where there is no
+ * userspace around to do it, e.g. a multi-device root filesystem mounted
+ * without an initrd.
+ *
+ * Devices are opened by their /dev name, which is what the rest of btrfs
+ * records in device->name.
+ */
+void btrfs_scan_all_devices(void)
+{
+	struct class_dev_iter iter;
+	struct device *dev;
+
+	lockdep_assert_held(&uuid_mutex);
+
+	/*
+	 * Every block device, not just whole disks: partitions are registered
+	 * with part_type rather than disk_type, and a btrfs filesystem usually
+	 * lives on one, so a type filter here would skip exactly the devices
+	 * we are looking for.  A disk that has partitions is filtered out by
+	 * btrfs_can_scan_disk() below, which can say why.
+	 */
+	class_dev_iter_init(&iter, &block_class, NULL, NULL);
+	while ((dev = class_dev_iter_next(&iter))) {
+		struct gendisk *disk = dev_to_disk(dev);
+		struct block_device *bdev = dev_to_bdev(dev);
+
+		if (btrfs_can_scan_disk(disk, bdev)) {
+			/* Longest is "/dev/" plus a BDEVNAME_SIZE name. */
+			char path[sizeof("/dev/") + BDEVNAME_SIZE];
+			struct btrfs_device *device;
+
+			snprintf(path, sizeof(path), "/dev/%s", dev_name(dev));
+
+			device = btrfs_scan_one_device(path, false);
+			if (IS_ERR(device))
+				btrfs_debug(NULL, "skipping %s: %ld\n", path,
+					    PTR_ERR(device));
+		}
+	}
+	class_dev_iter_exit(&iter);
+}
+
+#endif /* CONFIG_BTRFS_ROOT_SCAN */
+
 /*
  * Find the first pending extent intersecting a range.
  *
diff --git a/fs/btrfs/volumes.h b/fs/btrfs/volumes.h
index 1c4cfb21ad12..814d801db2e8 100644
--- a/fs/btrfs/volumes.h
+++ b/fs/btrfs/volumes.h
@@ -744,6 +744,9 @@ #define BTRFS_DEV_LOOKUP_ARGS(name) \
 int btrfs_open_devices(struct btrfs_fs_devices *fs_devices,
 		       blk_mode_t flags, void *holder);
 struct btrfs_device *btrfs_scan_one_device(const char *path, bool mount_arg_dev);
+#ifdef CONFIG_BTRFS_ROOT_SCAN
+void btrfs_scan_all_devices(void);
+#endif
 int btrfs_forget_devices(dev_t devt);
 void btrfs_close_devices(struct btrfs_fs_devices *fs_devices);
 void btrfs_release_device_allow_freeze(struct file *bdev_file);

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH 5/8] btrfs: wait for the root filesystem to have all its devices
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
  2026-11-16 22:43 ` [PATCH 1/8] btrfs: add config options for the root device scan Ismael Luceno
  2026-11-16 22:43 ` [PATCH 4/8] btrfs: add a helper to scan all block devices Ismael Luceno
@ 2026-11-16 22:43 ` Ismael Luceno
  2026-11-16 22:43 ` [PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices Ismael Luceno
                   ` (2 subsequent siblings)
  5 siblings, 0 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel
  Cc: Ismael Luceno, Ismael Luceno, David Sterba, Chris Mason,
	open list:BTRFS FILE SYSTEM

A multi-device btrfs filesystem is normally assembled by the device
scanner in userspace, which the initrd runs before mounting the root
filesystem.  Without an initrd nothing runs that scanner, so the root
mount names a single device and the rest of the array is left out, and
the mount then fails on a missing device.

Find the rest of the devices in the kernel instead.  How many devices a
filesystem needs is only knowable from its superblock, so the search
cannot be done by init/ and has to live here, where the scan and the
device bookkeeping already are.

Do this only for the root mount, and only when the user asked for it
with rootwait.  Any other mount of a multi-device filesystem has been
given the devices it needs, or is being asked to mount degraded, and
delaying those would change behaviour for reasons that have nothing to
do with boot.

A mount that is not the root one is not delayed, and a root one that
did not ask to be waited for is not either.  rootwait= with no value
waits indefinitely, which a root mount is entitled to.

The loop re-scans the block devices every 100ms until the number of
registered devices reaches the number the superblock says there should
be, or until the wait runs out.  It holds uuid_mutex across each scan
but releases it before sleeping, so a scan of a slow device does not
block other btrfs work, and the sleeping task holds up nothing but its
own mount.

A degraded mount skips the wait; without that, mounting a filesystem that
is missing a device on purpose would stall before doing what it was asked
to do.  On timeout the mount proceeds with whatever was found, which for
a redundant profile usually means it fails, but that is the behaviour
the caller had before.  A warning is printed first so the failure is
attributable.

The wait is only built with CONFIG_BTRFS_ROOT_SCAN, and the call to it is
only made when that is set.

Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 fs/btrfs/super.c   | 164 +++++++++++++++++++++++++++++++++++++++++++++
 fs/btrfs/volumes.c |  55 ++++++++++++---
 fs/btrfs/volumes.h |  23 ++++++-
 3 files changed, 232 insertions(+), 10 deletions(-)

diff --git a/fs/btrfs/super.c b/fs/btrfs/super.c
index b424cc836bd4..fb407361bbaf 100644
--- a/fs/btrfs/super.c
+++ b/fs/btrfs/super.c
@@ -9,6 +9,8 @@
 #include <linux/pagemap.h>
 #include <linux/highmem.h>
 #include <linux/time.h>
+#include <linux/delay.h>
+#include <linux/jiffies.h>
 #include <linux/init.h>
 #include <linux/seq_file.h>
 #include <linux/string.h>
@@ -19,6 +21,7 @@
 #include <linux/compat.h>
 #include <linux/parser.h>
 #include <linux/ctype.h>
+#include <linux/root_dev.h>
 #include <linux/namei.h>
 #include <linux/miscdevice.h>
 #include <linux/magic.h>
@@ -65,6 +68,7 @@
 #define CREATE_TRACE_POINTS
 #include <trace/events/btrfs.h>
 
+
 static const struct super_operations btrfs_super_ops;
 static struct file_system_type btrfs_fs_type;
 
@@ -1849,6 +1853,133 @@ #define btrfs_info_if_unset(fs_info, old_ctx, opt, fmt, args...)	\
 	return fs_info->fs_devices == p->fs_devices;
 }
 
+#ifdef CONFIG_BTRFS_ROOT_SCAN
+/*
+ * How many devices of the filesystem are not registered yet.
+ *
+ * Caller must hold uuid_mutex.
+ */
+static u64 btrfs_missing_devices(struct btrfs_fs_devices *fs_devices)
+{
+	if (fs_devices->num_devices >= fs_devices->total_devices)
+		return 0;
+
+	return fs_devices->total_devices - fs_devices->num_devices;
+}
+
+/*
+ * Scan the block devices until every device of the filesystem is registered,
+ * or until @timeout_ms has passed.
+ *
+ * btrfs only knows about the devices it was handed: the mount source, the
+ * device= mount options, or the device scanner running in userspace.  When
+ * btrfs is the root filesystem and no initrd is around to run that scanner,
+ * the remaining devices have to be discovered here, and they may not have
+ * shown up yet when we are first called.
+ *
+ * The filesystem is left in whatever state it is in when this returns, so the
+ * caller can still mount it in a degraded fashion.
+ */
+static void btrfs_wait_for_devices(struct btrfs_fs_devices *fs_devices,
+				   long timeout_ms)
+{
+	unsigned long end;
+	struct btrfs_scan_result res;
+	unsigned int last_opened = ~0U;
+	unsigned int last_candidates = ~0U;
+	u64 last_missing = ~0ULL;
+	bool explained = false;
+	u64 missing;
+
+	mutex_lock(&uuid_mutex);
+	missing = btrfs_missing_devices(fs_devices);
+	mutex_unlock(&uuid_mutex);
+
+	if (!missing)
+		return;
+
+	/*
+	 * A negative timeout is rootwait without a value, which means wait
+	 * indefinitely; the loop then has no end.
+	 */
+	end = timeout_ms < 0 ? jiffies + MAX_JIFFY_OFFSET :
+			      jiffies + msecs_to_jiffies(timeout_ms);
+
+	if (timeout_ms < 0)
+		btrfs_info(NULL, "fsid %pU is missing %llu device(s), waiting indefinitely",
+			   fs_devices->fsid, missing);
+	else
+		btrfs_info(NULL, "fsid %pU is missing %llu device(s), waiting up to %ld ms",
+			   fs_devices->fsid, missing, timeout_ms);
+
+	while (!time_after(jiffies, end)) {
+		mutex_lock(&uuid_mutex);
+		btrfs_scan_all_devices(&res);
+		missing = btrfs_missing_devices(fs_devices);
+		mutex_unlock(&uuid_mutex);
+
+		if (!missing)
+			break;
+
+		/*
+		 * One line, and only when it says something new.  A wait that
+		 * prints the same numbers every scan interval tells a reader nothing
+		 * that the first line did not, and the console is the scarce
+		 * resource here.  Devices arriving one at a time is the case
+		 * worth seeing, and that is exactly when the numbers move.
+		 */
+		if (res.opened != last_opened ||
+		    res.candidates != last_candidates ||
+		    missing != last_missing) {
+			btrfs_info(NULL,
+				   "fsid %pU: %u of %u device(s) scanned, %u btrfs, %llu missing (%u block devices, %u passed over)",
+				   fs_devices->fsid, res.opened,
+				   res.candidates, res.found, missing,
+				   res.seen, res.skipped);
+			last_opened = res.opened;
+			last_candidates = res.candidates;
+			last_missing = missing;
+		}
+
+		/*
+		 * Say why a scan came back with nothing, once.  The detail is
+		 * what a reader needs and cannot guess from the counts.
+		 */
+		if (!res.opened && !explained) {
+			explained = true;
+			btrfs_warn(NULL,
+				   "fsid %pU: no device could be opened; %u of %u have no node under /dev (e.g. %u:%u: %ld)",
+				   fs_devices->fsid, res.unreachable,
+				   res.candidates, MAJOR(res.first_unreachable),
+				   MINOR(res.first_unreachable), res.first_errno);
+			btrfs_warn(NULL,
+				   "fsid %pU: enable CONFIG_DEVTMPFS_MOUNT, or boot an initrd, to mount a multi-device root filesystem",
+				   fs_devices->fsid);
+			/*
+			 * The device this filesystem was mounted from is always
+			 * a candidate, so opening none of them is not a
+			 * filesystem that is merely incomplete: there is
+			 * nothing here to wait for, and under a bare rootwait
+			 * that would be forever.
+			 */
+			return;
+		}
+
+		msleep(CONFIG_BTRFS_ROOT_SCAN_INTERVAL_MS);
+
+	}
+
+	if (missing)
+		btrfs_warn(NULL,
+			   "fsid %pU: %u of %u device(s) scanned, %u btrfs, still missing %llu; mounting anyway (%u block devices, %u passed over)",
+			   fs_devices->fsid, res.opened, res.candidates, res.found,
+			   missing, res.seen, res.skipped);
+	else
+		btrfs_info(NULL, "all devices of fsid %pU found", fs_devices->fsid);
+}
+
+#endif /* CONFIG_BTRFS_ROOT_SCAN */
+
 static int btrfs_get_tree_super(struct fs_context *fc)
 {
 	struct btrfs_fs_info *fs_info = fc->s_fs_info;
@@ -1884,6 +2015,39 @@ #define btrfs_info_if_unset(fs_info, old_ctx, opt, fmt, args...)	\
 	fs_info->fs_devices = fs_devices;
 	mutex_unlock(&uuid_mutex);
 
+	/*
+	 * Only the root filesystem needs this, and only when the user asked
+	 * for a rootwait: any other mount of a multi-device filesystem has
+	 * either been given all its devices or is being asked to mount
+	 * degraded, and neither should be delayed.  A "degraded" mount is one
+	 * where the user knows a device is missing and wants the filesystem
+	 * anyway, so it skips the wait too.
+	 */
+#ifdef CONFIG_BTRFS_ROOT_SCAN
+	if (root_wait && is_root_dev(device->devt) &&
+	    !btrfs_raw_test_opt(ctx->mount_opt, DEGRADED)) {
+		btrfs_wait_for_devices(fs_devices, root_wait);
+	} else {
+		u64 missing;
+
+		mutex_lock(&uuid_mutex);
+		missing = btrfs_missing_devices(fs_devices);
+		mutex_unlock(&uuid_mutex);
+
+		/*
+		 * A filesystem that is missing devices but is not being
+		 * waited for is either going to mount degraded, which is
+		 * what was asked for, or is about to fail.  Say which, so a
+		 * wait that did not happen is not a mystery either.
+		 */
+		if (missing)
+			btrfs_info(NULL,
+				   "not waiting for %llu missing device(s): is_root_dev=%u root_wait=%d degraded=%u",
+				   missing, is_root_dev(device->devt), root_wait,
+				   !!btrfs_raw_test_opt(ctx->mount_opt, DEGRADED));
+	}
+#endif
+
 	fc->sb_flags |= SB_NOSEC;
 
 	sb = sget_fc(fc, btrfs_fc_test_super, set_anon_super_fc);
diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index 55f11c9fe24c..9eedf6ef1383 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
@@ -1571,15 +1571,26 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
  * without an initrd.
  *
  * Devices are opened by their /dev name, which is what the rest of btrfs
- * records in device->name.
+ * records in device->name, so the scan depends on the device nodes being
+ * there.  That is what res->opened is for: the caller needs to tell a
+ * filesystem that is merely not complete yet from one where the nodes are
+ * missing, and no amount of waiting will help the latter.
+ *
+ * Returns the number of devices that held a btrfs superblock, and fills in
+ * @res.
  */
-void btrfs_scan_all_devices(void)
+unsigned int btrfs_scan_all_devices(struct btrfs_scan_result *res)
 {
 	struct class_dev_iter iter;
 	struct device *dev;
+	unsigned int found = 0;
+	unsigned int opened = 0;
+	unsigned int candidates = 0;
 
 	lockdep_assert_held(&uuid_mutex);
 
+	memset(res, 0, sizeof(*res));
+
 	/*
 	 * Every block device, not just whole disks: partitions are registered
 	 * with part_type rather than disk_type, and a btrfs filesystem usually
@@ -1591,21 +1602,47 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 	while ((dev = class_dev_iter_next(&iter))) {
 		struct gendisk *disk = dev_to_disk(dev);
 		struct block_device *bdev = dev_to_bdev(dev);
+		struct btrfs_device *device;
 
-		if (btrfs_can_scan_disk(disk, bdev)) {
-			/* Longest is "/dev/" plus a BDEVNAME_SIZE name. */
-			char path[sizeof("/dev/") + BDEVNAME_SIZE];
-			struct btrfs_device *device;
+		res->seen++;
+		if (!btrfs_can_scan_disk(disk, bdev)) {
+			res->skipped++;
+			continue;
+		}
 
-			snprintf(path, sizeof(path), "/dev/%s", dev_name(dev));
+		/* Longest is "/dev/" plus a BDEVNAME_SIZE name. */
+		char path[sizeof("/dev/") + BDEVNAME_SIZE];
 
-			device = btrfs_scan_one_device(path, false);
-			if (IS_ERR(device))
+		candidates++;
+		snprintf(path, sizeof(path), "/dev/%s", dev_name(dev));
+
+		device = btrfs_scan_one_device(path, false);
+		if (IS_ERR(device)) {
+			/*
+			 * ENOENT is the node not being there, as opposed to
+			 * the node being there and not holding a btrfs
+			 * filesystem.  Keep one of each to explain a scan
+			 * that reaches nothing, rather than one line each.
+			 */
+			if (!res->unreachable++) {
+				res->first_unreachable = dev_to_bdev(dev)->bd_dev;
+				res->first_errno = PTR_ERR(device);
+			}
+			if (PTR_ERR(device) != -ENOENT)
 				btrfs_debug(NULL, "skipping %s: %ld\n", path,
 					    PTR_ERR(device));
+		} else {
+			opened++;
+			found++;
 		}
 	}
 	class_dev_iter_exit(&iter);
+
+	res->candidates = candidates;
+	res->opened = opened;
+	res->found = found;
+
+	return found;
 }
 
 #endif /* CONFIG_BTRFS_ROOT_SCAN */
diff --git a/fs/btrfs/volumes.h b/fs/btrfs/volumes.h
index 814d801db2e8..6f2cf43d1038 100644
--- a/fs/btrfs/volumes.h
+++ b/fs/btrfs/volumes.h
@@ -743,9 +743,30 @@ #define BTRFS_DEV_LOOKUP_ARGS(name) \
 void btrfs_mapping_tree_free(struct btrfs_fs_info *fs_info);
 int btrfs_open_devices(struct btrfs_fs_devices *fs_devices,
 		       blk_mode_t flags, void *holder);
+#ifdef CONFIG_BTRFS_ROOT_SCAN
+/*
+ * What a pass of btrfs_scan_all_devices() made of the block devices.
+ *
+ * A scan that finds nothing has to be explained, and the usual reason is
+ * either that the device nodes are not there or that the devices hold no
+ * btrfs filesystem.  Keeping one device and one errno of each is enough to
+ * say which, and costs two lines of output instead of one per device.
+ */
+struct btrfs_scan_result {
+	unsigned int seen;	/* devices the iterator returned at all */
+	unsigned int candidates;
+	unsigned int opened;
+	unsigned int found;
+	unsigned int unreachable;
+	dev_t first_unreachable;
+	long first_errno;
+	unsigned int skipped;
+};
+#endif
+
 struct btrfs_device *btrfs_scan_one_device(const char *path, bool mount_arg_dev);
 #ifdef CONFIG_BTRFS_ROOT_SCAN
-void btrfs_scan_all_devices(void);
+unsigned int btrfs_scan_all_devices(struct btrfs_scan_result *res);
 #endif
 int btrfs_forget_devices(dev_t devt);
 void btrfs_close_devices(struct btrfs_fs_devices *fs_devices);

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
                   ` (2 preceding siblings ...)
  2026-11-16 22:43 ` [PATCH 5/8] btrfs: wait for the root filesystem to have all its devices Ismael Luceno
@ 2026-11-16 22:43 ` Ismael Luceno
  2026-11-16 22:43 ` [PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL= Ismael Luceno
  2026-11-16 23:41 ` [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Qu Wenruo
  5 siblings, 0 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel
  Cc: Ismael Luceno, Ismael Luceno, David Sterba, Chris Mason,
	Jonathan Corbet, Shuah Khan, Randy Dunlap,
	open list:BTRFS FILE SYSTEM, open list:DOCUMENTATION

Document the whole feature, including the part btrfs opens devices by
their /dev name and so cannot run the search at all without devtmpfs
mounted.  Say that too, and what happens when it is not, rather than
leaving a boot that stops with nothing in the log.

Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 Documentation/filesystems/btrfs.rst | 31 +++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/filesystems/btrfs.rst b/Documentation/filesystems/btrfs.rst
index a81db8f54d68..9dcdb87a53c3 100644
--- a/Documentation/filesystems/btrfs.rst
+++ b/Documentation/filesystems/btrfs.rst
@@ -33,6 +33,37 @@ The main Btrfs features include:
     * Read/write metadata verification
     * Online resize (shrink, grow)
 
+Multi-device root filesystem without an initrd
+----------------------------------------------
+
+A multi-device btrfs filesystem is normally assembled by the device scanner in
+userspace, which the initrd runs before mounting the root filesystem.  Without
+an initrd there is nothing to run that scanner, so the root filesystem is
+mounted from the single device named by ``root=`` and the remaining devices are
+left out.
+
+Given ``rootwait``, btrfs finds the rest of them during the root mount.
+
+    root=/dev/sda1 rootwait
+
+The devices are then given the time ``rootwait=`` specifies, or indefinite for
+``rootwait`` with no value.  The search repeats at the interval set by
+CONFIG_BTRFS_ROOT_SCAN_INTERVAL_MS (100 ms by default) until they are
+all found, and is not made for any other mount: a filesystem mounted later has
+been given the devices it needs, or is being mounted degraded on purpose.
+
+When the wait runs out btrfs mounts whatever it has, which for a redundant
+profile usually means the mount fails and the kernel panics; a warning is
+printed before that happens.  Without ``rootwait`` there is no wait at all, and
+an incomplete filesystem is mounted as usual.
+
+The search needs the device nodes in ``/dev``, which come from devtmpfs.  Where
+that is not mounted the search cannot start, and btrfs says so and gives up
+rather than waiting for something it can never find.
+
+The search is built with ``CONFIG_BTRFS_ROOT_SCAN``, which depends on
+``CONFIG_DEVTMPFS`` and is on by default.
+
 For more information please refer to the documentation site or wiki
 
   https://btrfs.readthedocs.io

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL=
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
                   ` (3 preceding siblings ...)
  2026-11-16 22:43 ` [PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices Ismael Luceno
@ 2026-11-16 22:43 ` Ismael Luceno
  2026-11-16 23:41 ` [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Qu Wenruo
  5 siblings, 0 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-16 22:43 UTC (permalink / raw)
  To: linux-kernel
  Cc: Ismael Luceno, Ismael Luceno, David Sterba, Chris Mason,
	open list:BTRFS FILE SYSTEM

A btrfs filesystem UUID and label are in its superblock, so the block
layer cannot resolve them the way it resolves PARTUUID= and PARTLABEL=:
root=UUID=... reaches parse_root_device() as something that is not a
device name, and the mount fails with a message that gives no hint that
a filesystem UUID was what was being asked for.

Walk the block devices the way the device scan does and offer each one
its filesystem UUID or label.  Whole disks without partitions and the
partitions themselves are both candidates, since a btrfs filesystem is
usually on a partition and the disks are then passed over.

btrfs_can_scan_disk() is built regardless of CONFIG_BTRFS_ROOT_SCAN,
since this lookup needs it too.  The lookup does not depend on devtmpfs, so
it is not gated by that option.

Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 fs/btrfs/super.c   |  1 +
 fs/btrfs/volumes.c | 92 +++++++++++++++++++++++++++++++++++++++++++---
 fs/btrfs/volumes.h |  1 +
 3 files changed, 88 insertions(+), 6 deletions(-)

diff --git a/fs/btrfs/super.c b/fs/btrfs/super.c
index fb407361bbaf..a9f07e06f6ae 100644
--- a/fs/btrfs/super.c
+++ b/fs/btrfs/super.c
@@ -2379,6 +2379,7 @@ #define btrfs_info_if_unset(fs_info, old_ctx, opt, fmt, args...)	\
 	.owner			= THIS_MODULE,
 	.name			= "btrfs",
 	.init_fs_context	= btrfs_init_fs_context,
+	.find_by_spec		= btrfs_find_dev_by_spec,
 	.parameters		= btrfs_fs_parameters,
 	.kill_sb		= btrfs_kill_super,
 	.fs_flags		= FS_REQUIRES_DEV | FS_BINARY_MOUNTDATA |
diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index 9eedf6ef1383..12d9dd6d0737 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
@@ -1531,7 +1531,6 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 	return device;
 }
 
-#ifdef CONFIG_BTRFS_ROOT_SCAN
 /*
  * Return true if @disk is worth handing to btrfs_scan_one_device().
  *
@@ -1562,6 +1561,7 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 	return true;
 }
 
+#ifdef CONFIG_BTRFS_ROOT_SCAN
 /*
  * Register every block device that holds a btrfs superblock.
  *
@@ -1592,11 +1592,10 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 	memset(res, 0, sizeof(*res));
 
 	/*
-	 * Every block device, not just whole disks: partitions are registered
-	 * with part_type rather than disk_type, and a btrfs filesystem usually
-	 * lives on one, so a type filter here would skip exactly the devices
-	 * we are looking for.  A disk that has partitions is filtered out by
-	 * btrfs_can_scan_disk() below, which can say why.
+	 * Iterate every block device, not just whole disks: partitions are
+	 * registered with part_type rather than disk_type, and a btrfs
+	 * filesystem usually lives on one, so filtering on disk_type here
+	 * would skip exactly the devices we are looking for.
 	 */
 	class_dev_iter_init(&iter, &block_class, NULL, NULL);
 	while ((dev = class_dev_iter_next(&iter))) {
@@ -1647,6 +1646,87 @@ btrfs_get_bdev_and_sb(const char *device_path, blk_mode_t flags, void *holder,
 
 #endif /* CONFIG_BTRFS_ROOT_SCAN */
 
+/*
+ * Format the filesystem UUID of a disk superblock, in the same textual form
+ * blkid and the rest of btrfs print it as.
+ */
+static const char *btrfs_sb_uuid_string(struct btrfs_super_block *disk_super)
+{
+	static char buf[UUID_STRING_LEN + 1];
+
+	/* The fsid is stored in the same layout a uuid_t is printed from. */
+	snprintf(buf, sizeof(buf), "%pU", (uuid_t *)disk_super->fsid);
+	return buf;
+}
+
+/*
+ * Read the primary superblock of @bdev and compare the field named by @key
+ * against @value.  @value is in the usual textual form: a UUID, or a label.
+ *
+ * Return 0 on a match, -ENOENT if the device is not btrfs or does not match,
+ * or an error.
+ */
+static int btrfs_dev_spec_matches(struct block_device *bdev, const char *key,
+				  const char *value)
+{
+	struct btrfs_super_block *disk_super;
+	bool matches;
+	int ret;
+
+	disk_super = btrfs_read_disk_super(bdev, 0, false);
+	if (IS_ERR(disk_super))
+		return PTR_ERR(disk_super);
+
+	if (!strcmp(key, "UUID"))
+		matches = !strcasecmp(value, btrfs_sb_uuid_string(disk_super));
+	else
+		matches = !strncmp(value, disk_super->label,
+				   BTRFS_LABEL_SIZE);
+
+	ret = matches ? 0 : -ENOENT;
+
+	btrfs_release_disk_super(disk_super);
+	return ret;
+}
+
+/*
+ * Find the block device holding the btrfs filesystem identified by @key and
+ * @value, for "root=UUID=" and "root=LABEL=".  Both are in the superblock
+ * rather than in the partition table, so unlike PARTUUID= and PARTLABEL= they
+ * can only be recognised by reading devices, and it has to be done by btrfs
+ * rather than by init/.
+ *
+ * Return 0 and the dev_t on a match, -ENODEV if no device matches.
+ */
+int btrfs_find_dev_by_spec(const char *key, const char *value, dev_t *devt)
+{
+	struct class_dev_iter iter;
+	struct device *dev;
+	int ret = -ENODEV;
+
+	if (!key || !value || !value[0])
+		return -EINVAL;
+
+	/* Every block device, disks and partitions alike: see the comment on
+	 * btrfs_scan_all_devices() for why the type filter cannot be used. */
+	class_dev_iter_init(&iter, &block_class, NULL, NULL);
+	while ((dev = class_dev_iter_next(&iter))) {
+		struct gendisk *disk = dev_to_disk(dev);
+		struct block_device *bdev = dev_to_bdev(dev);
+
+		if (!btrfs_can_scan_disk(disk, bdev))
+			continue;
+		if (btrfs_dev_spec_matches(bdev, key, value) == 0) {
+			*devt = bdev->bd_dev;
+			ret = 0;
+			break;
+		}
+	}
+	class_dev_iter_exit(&iter);
+
+	return ret;
+}
+
 /*
  * Find the first pending extent intersecting a range.
  *
diff --git a/fs/btrfs/volumes.h b/fs/btrfs/volumes.h
index 6f2cf43d1038..8b550a5a2d6f 100644
--- a/fs/btrfs/volumes.h
+++ b/fs/btrfs/volumes.h
@@ -768,6 +768,7 @@ #define BTRFS_DEV_LOOKUP_ARGS(name) \
 #ifdef CONFIG_BTRFS_ROOT_SCAN
 unsigned int btrfs_scan_all_devices(struct btrfs_scan_result *res);
 #endif
+int btrfs_find_dev_by_spec(const char *key, const char *value, dev_t *devt);
 int btrfs_forget_devices(dev_t devt);
 void btrfs_close_devices(struct btrfs_fs_devices *fs_devices);
 void btrfs_release_device_allow_freeze(struct file *bdev_file);

^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd
  2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
                   ` (4 preceding siblings ...)
  2026-11-16 22:43 ` [PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL= Ismael Luceno
@ 2026-11-16 23:41 ` Qu Wenruo
  2026-11-17 17:36   ` Ismael Luceno
  5 siblings, 1 reply; 9+ messages in thread
From: Qu Wenruo @ 2026-11-16 23:41 UTC (permalink / raw)
  To: Ismael Luceno, linux-kernel, linux-btrfs
  Cc: David Sterba, Chris Mason, Christian Brauner, Alexander Viro,
	Jan Kara, linux-fsdevel, linux-doc



在 2026/11/17 09:13, Ismael Luceno 写道:
> A multi-device btrfs root filesystem is normally assembled by the device
> scanner that an initrd runs before mounting the root.

What is the problem here?

Is generating an initramfs really that complex?

Multi-device filesystems/storage solution requires initramfs to do the 
scan, no matter if it's btrfs or device-mapper, it's already the common 
knowledge.

I just see no strong reasons to do this at all.

And Sashiko is already reporting over 10 high level problems, which is 
not a good sign either.
>  Without an initrd
> nothing runs that scanner, so the root mount names a single device and
> the rest of the array is left out.
> 
> This series lets btrfs assemble such a root filesystem in the kernel:
> 
>    * mount devtmpfs on the initial root before the root filesystem, so
>      device nodes exist to open the other devices by name (init);
>    * let a filesystem tell whether it is mounting the root device and read
>      rootwait, and resolve root=UUID=/root=LABEL= values that name the
>      filesystem rather than a partition (init/VFS);
>    * scan all block devices for the remaining members of a btrfs root
>      filesystem, and wait for all of them to appear before mounting.
> 
> The scan and wait are gated on CONFIG_BTRFS_ROOT_SCAN (default y) and
> only act on the root mount when the user asked for it with rootwait, so
> non-root mounts and systems without the option are unchanged.
> 
> 
> Ismael Luceno (8):
>    btrfs: add config options for the root device scan
>    init: mount devtmpfs before the root filesystem
>    init: let filesystems ask whether they are mounting the root device
>    btrfs: add a helper to scan all block devices
>    btrfs: wait for the root filesystem to have all its devices
>    Documentation: btrfs: document waiting for the root filesystem devices
>    init: let a filesystem resolve a root device by UUID or label
>    btrfs: resolve root=UUID= and root=LABEL=
> 
>   Documentation/filesystems/btrfs.rst |  31 +++++
>   fs/btrfs/Kconfig                    |  25 ++++
>   fs/btrfs/super.c                    | 165 +++++++++++++++++++++++
>   fs/btrfs/volumes.c                  | 196 ++++++++++++++++++++++++++++
>   fs/btrfs/volumes.h                  |  25 ++++
>   fs/filesystems.c                    |  37 ++++++
>   include/linux/fs.h                  |  10 ++
>   include/linux/root_dev.h            |  14 ++
>   init/do_mounts.c                    |  51 +++++++-
>   9 files changed, 553 insertions(+), 1 deletion(-)


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 4/8] btrfs: add a helper to scan all block devices
  2026-11-16 22:43 ` [PATCH 4/8] btrfs: add a helper to scan all block devices Ismael Luceno
@ 2026-11-17 13:10   ` kernel test robot
  0 siblings, 0 replies; 9+ messages in thread
From: kernel test robot @ 2026-11-17 13:10 UTC (permalink / raw)
  To: Ismael Luceno, linux-kernel
  Cc: llvm, oe-kbuild-all, Ismael Luceno, David Sterba, Chris Mason,
	open list:BTRFS FILE SYSTEM

Hi Ismael,

kernel test robot noticed the following build errors:

[auto build test ERROR on kdave/for-next]
[also build test ERROR on btrfs/for-next brauner-vfs/vfs.all linus/master v7.4-rc3 next-20261116]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Ismael-Luceno/btrfs-add-config-options-for-the-root-device-scan/20261116-234317
base:   https://git.kernel.org/pub/scm/linux/kernel/git/kdave/linux.git for-next
patch link:    https://lore.kernel.org/r/20261116224316.11237-14-ismael%40iodev.co.uk
patch subject: [PATCH 4/8] btrfs: add a helper to scan all block devices
config: x86_64-kexec (https://download.01.org/0day-ci/archive/20261117/202611172034.2xFLZZpu-lkp@intel.com/config)
compiler: clang version 22.1.8 (https://github.com/llvm/llvm-project ca7933e47d3a3451d81e72ac174dcb5aa28b59d1)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20261117/202611172034.2xFLZZpu-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202611172034.2xFLZZpu-lkp@intel.com/

All errors (new ones prefixed by >>, old ones prefixed by <<):

>> ERROR: modpost: fs/btrfs/btrfs.ko: symbol 'block_class' undefined!

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd
  2026-11-16 23:41 ` [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Qu Wenruo
@ 2026-11-17 17:36   ` Ismael Luceno
  0 siblings, 0 replies; 9+ messages in thread
From: Ismael Luceno @ 2026-11-17 17:36 UTC (permalink / raw)
  To: Qu Wenruo
  Cc: linux-kernel, linux-btrfs, David Sterba, Chris Mason,
	Christian Brauner, Alexander Viro, Jan Kara, linux-fsdevel,
	linux-doc

On Tue, 17 Nov 2026 10:11:46 +1030
Qu Wenruo <wqu@suse.com> wrote:
> 在 2026/11/17 09:13, Ismael Luceno 写道:
> > A multi-device btrfs root filesystem is normally assembled by the
> > device scanner that an initrd runs before mounting the root.  
> 
> What is the problem here?
> 
> Is generating an initramfs really that complex?

Why depend on an initramfs?

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2026-11-17 17:36 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
2026-11-16 22:43 ` [PATCH 1/8] btrfs: add config options for the root device scan Ismael Luceno
2026-11-16 22:43 ` [PATCH 4/8] btrfs: add a helper to scan all block devices Ismael Luceno
2026-11-17 13:10   ` kernel test robot
2026-11-16 22:43 ` [PATCH 5/8] btrfs: wait for the root filesystem to have all its devices Ismael Luceno
2026-11-16 22:43 ` [PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices Ismael Luceno
2026-11-16 22:43 ` [PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL= Ismael Luceno
2026-11-16 23:41 ` [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Qu Wenruo
2026-11-17 17:36   ` Ismael Luceno

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox