Skip to contentSkip to conversation

btrfs: Document some invariants of seed code

PATCH In review Nikolay Borisov 3 participants 3 messages Aug 12, 2020 – Aug 26, 2020 Btrfs file system

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 btrfs: Document some invariants of seed code

Without good understanding of how seed devices works it's hard to grok some of what the code in open_seed_devices or btrfs_prepare_sprout does.

Add comments hopefully reducing some of the cognitive load.

---
 fs/btrfs/volumes.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
fs/btrfs/volumes.c +15 -0
index 631cb03b3513..f7ee7837e6bc 100644
@@ -2361,10 +2361,20 @@ static int btrfs_prepare_sprout(struct btrfs_fs_info *fs_info)
 	if (!fs_devices->seeding)
 		return -EINVAL;
 
+	/*
+	 * Private copy of the seed devices, anchored at
+	 * fs_info->fs_devices->seed_list
+	 */
 	seed_devices = alloc_fs_devices(NULL, NULL);
 	if (IS_ERR(seed_devices))
 		return PTR_ERR(seed_devices);
 
+	/*
+	 * It's necessary to retain a copy of the original seed fs_devices in
+	 * fs_uuids so that filesystems which have been seeded can be
+	 * successfully reference the seed device from open_seed_devices. This
+	 * also supports multiple fs seed.
+	 */
 	old_devices = clone_fs_devices(fs_devices);
 	if (IS_ERR(old_devices)) {
 		kfree(seed_devices);
@@ -6713,6 +6723,7 @@ static struct btrfs_fs_devices *open_seed_devices(struct btrfs_fs_info *fs_info,
 	lockdep_assert_held(&uuid_mutex);
 	ASSERT(fsid);
 
+	/* This will match only for multi-device seed fs */
 	list_for_each_entry(fs_devices, &fs_info->fs_devices->seed_list, seed_list)
 		if (!memcmp(fs_devices->fsid, fsid, BTRFS_FSID_SIZE))
 			return fs_devices;
@@ -6732,6 +6743,10 @@ static struct btrfs_fs_devices *open_seed_devices(struct btrfs_fs_info *fs_info,
 		return fs_devices;
 	}
 
+	/*
+	 * Upon first call for a seed fs fsid just create a private copy of the
+	 * respective fs_devices and anchor it at fs_info->fs_devices->seed_list
+	 */
 	fs_devices = clone_fs_devices(fs_devices);
 	if (IS_ERR(fs_devices))
 		return fs_devices;
Signature · 1 line
2.17.1
#1 lore raw
Quoted 6 lines · Nikolay Borisov

Without good understanding of how seed devices works it's hard to grok some of what the code in open_seed_devices or btrfs_prepare_sprout does.

Add comments hopefully reducing some of the cognitive load.

I'll add this patch to the seed list api patchset.

Reviewed-by on v1 1/1
#2 lore raw
In reply to Nikolay Borisov
Quoted 46 lines · Nikolay Borisov

Without good understanding of how seed devices works it's hard to grok some of what the code in open_seed_devices or btrfs_prepare_sprout does.

Add comments hopefully reducing some of the cognitive load.

---
  fs/btrfs/volumes.c | 15 +++++++++++++++
  1 file changed, 15 insertions(+)
fs/btrfs/volumes.c +10 -0
index 631cb03b3513..f7ee7837e6bc 100644
@@ -2361,10 +2361,20 @@ static int btrfs_prepare_sprout(struct btrfs_fs_info *fs_info)
  	if (!fs_devices->seeding)
  		return -EINVAL;
 
+	/*
+	 * Private copy of the seed devices, anchored at
+	 * fs_info->fs_devices->seed_list
+	 */
  	seed_devices = alloc_fs_devices(NULL, NULL);
  	if (IS_ERR(seed_devices))
  		return PTR_ERR(seed_devices);
 
+	/*
+	 * It's necessary to retain a copy of the original seed fs_devices in
+	 * fs_uuids so that filesystems which have been seeded can be
+	 * successfully reference the seed device from open_seed_devices. This
+	 * also supports multiple fs seed.
+	 */
 
  	old_devices = clone_fs_devices(fs_devices);
  	if (IS_ERR(old_devices)) {
  		kfree(seed_devices);
fs/btrfs/volumes.c +1 -0
@@ -6713,6 +6723,7 @@ static struct btrfs_fs_devices *open_seed_devices(struct btrfs_fs_info *fs_info,
  	lockdep_assert_held(&uuid_mutex);
  	ASSERT(fsid);
 
+	/* This will match only for multi-device seed fs */
  	list_for_each_entry(fs_devices, &fs_info->fs_devices->seed_list, seed_list)
  		if (!memcmp(fs_devices->fsid, fsid, BTRFS_FSID_SIZE))
  			return fs_devices;

fs/btrfs/volumes.c static struct btrfs_fs_devices *open_seed_devices(struct btrfs_fs_info *fs_info, · line 6752

Quoted 10 lines
fs/btrfs/volumes.c +4 -0
@@ -6732,6 +6743,10 @@ static struct btrfs_fs_devices *open_seed_devices(struct btrfs_fs_info *fs_info,
  		return fs_devices;
  	}
 
+	/*
+	 * Upon first call for a seed fs fsid just create a private copy of the
+	 * respective fs_devices and anchor it at fs_info->fs_devices->seed_list
+	 */
  	fs_devices = clone_fs_devices(fs_devices);
  	if (IS_ERR(fs_devices))
  		return fs_devices;

Looks good. Thanks