[PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL=
From: Ismael Luceno
Date: Mon Nov 16 2026 - 17:44:19 EST
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@xxxxxxxxxxx>
Signed-off-by: Ismael Luceno <iluceno@xxxxxxx>
---
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);