btrfs: Add intrudoction to dev-replace.
diff mbox series

Message ID 20200123074450.24328-1-wqu@suse.com
State New
Headers show
Series
  • btrfs: Add intrudoction to dev-replace.
Related show

Commit Message

Qu Wenruo Jan. 23, 2020, 7:44 a.m. UTC
The overview of btrfs dev-replace is not that complex.
But digging into the code directly can waste some extra time, so add
such introduction to help later guys.

Also, it mentions some corner cases caused by the write duplication and
scrub based data copy, to inform new comers not to get trapped by that
pitfall.

Signed-off-by: Qu Wenruo <wqu@suse.com>
---
 fs/btrfs/dev-replace.c | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

Comments

Anand Jain Jan. 23, 2020, 8 a.m. UTC | #1
On 1/23/20 3:44 PM, Qu Wenruo wrote:
> The overview of btrfs dev-replace is not that complex.
> But digging into the code directly can waste some extra time, so add
> such introduction to help later guys.
> 
> Also, it mentions some corner cases caused by the write duplication and
> scrub based data copy, to inform new comers not to get trapped by that
> pitfall.
> 

looks good.
Reviewed-by: Anand Jain <anand.jain@oracle.com>

nits below.

> Signed-off-by: Qu Wenruo <wqu@suse.com>
> ---
>   fs/btrfs/dev-replace.c | 38 ++++++++++++++++++++++++++++++++++++++
>   1 file changed, 38 insertions(+)
> 
> diff --git a/fs/btrfs/dev-replace.c b/fs/btrfs/dev-replace.c
> index f639dde2a679..5889c10ed8d2 100644
> --- a/fs/btrfs/dev-replace.c
> +++ b/fs/btrfs/dev-replace.c
> @@ -22,6 +22,44 @@
>   #include "dev-replace.h"
>   #include "sysfs.h"
>   
> +/*
> + * Introduction for dev-replace.
> + *
> + * [Objective]
> + * To copy all extents (both runtime and on-disk) from source device
> + * to target device, while still keeps the fs RW.
> + *
> + * [Method]
> + * There are two main methods involved:
> + * - Write duplication
> + *   All newer write will to written to both target and source devices.
                           ^^^^^^^^^

> + *   So that even replace get canceled, old device is still valid.
> + *
> + *   Location:		handle_ops_on_dev_replace() from __btrfs_map_block()

Term Location is bit confusing, instead Functions will do?

Thanks, Anand

> + *   Start timing:	btrfs_dev_replace_start()
> + *   End timing:	btrfs_dev_replace_finishing()
> + *   Content:		Latest data/meta
> + *
> + * - Existing extents copy
> + *   This happens by re-using scrub facility, as scrub also iterates through
> + *   exiting extents from commit root.
> + *
> + *   Location:		scrub_write_block_to_dev_replace() from
> + *   			scrub_block_complete()
> + *   Content:		Data/meta from commit root.
> + *
> + * Due to the content difference, we need to avoid nocow write when dev-replace
> + * is happening.
> + * This is done by marking the block group RO and wait for nocow writes.
> + *
> + * After replace is done, the finishing part is done by:
> + * - Swap target and source device
> + *   When the scrub finishes, swap the source device with target device.
> + *
> + *   Location:		btrfs_dev_replace_update_device_in_mapping_tree() from
> + *   			btrfs_dev_replace_finishing()
> + */
> +
>   static int btrfs_dev_replace_finishing(struct btrfs_fs_info *fs_info,
>   				       int scrub_ret);
>   static void btrfs_dev_replace_update_device_in_mapping_tree(
>
David Sterba Jan. 30, 2020, 12:46 p.m. UTC | #2
On Thu, Jan 23, 2020 at 03:44:50PM +0800, Qu Wenruo wrote:
> The overview of btrfs dev-replace is not that complex.
> But digging into the code directly can waste some extra time, so add
> such introduction to help later guys.
> 
> Also, it mentions some corner cases caused by the write duplication and
> scrub based data copy, to inform new comers not to get trapped by that
> pitfall.
> 
> Signed-off-by: Qu Wenruo <wqu@suse.com>

Thanks for the docs, I've adjusted some wording and fixed a few typos.
Please try to proofread it before sending, also reviews should catch
and point that out.

Patch
diff mbox series

diff --git a/fs/btrfs/dev-replace.c b/fs/btrfs/dev-replace.c
index f639dde2a679..5889c10ed8d2 100644
--- a/fs/btrfs/dev-replace.c
+++ b/fs/btrfs/dev-replace.c
@@ -22,6 +22,44 @@ 
 #include "dev-replace.h"
 #include "sysfs.h"
 
+/*
+ * Introduction for dev-replace.
+ *
+ * [Objective]
+ * To copy all extents (both runtime and on-disk) from source device
+ * to target device, while still keeps the fs RW.
+ *
+ * [Method]
+ * There are two main methods involved:
+ * - Write duplication
+ *   All newer write will to written to both target and source devices.
+ *   So that even replace get canceled, old device is still valid.
+ *
+ *   Location:		handle_ops_on_dev_replace() from __btrfs_map_block()
+ *   Start timing:	btrfs_dev_replace_start()
+ *   End timing:	btrfs_dev_replace_finishing()
+ *   Content:		Latest data/meta
+ *
+ * - Existing extents copy
+ *   This happens by re-using scrub facility, as scrub also iterates through
+ *   exiting extents from commit root.
+ *
+ *   Location:		scrub_write_block_to_dev_replace() from
+ *   			scrub_block_complete()
+ *   Content:		Data/meta from commit root.
+ *
+ * Due to the content difference, we need to avoid nocow write when dev-replace
+ * is happening.
+ * This is done by marking the block group RO and wait for nocow writes.
+ *
+ * After replace is done, the finishing part is done by:
+ * - Swap target and source device
+ *   When the scrub finishes, swap the source device with target device.
+ *
+ *   Location:		btrfs_dev_replace_update_device_in_mapping_tree() from
+ *   			btrfs_dev_replace_finishing()
+ */
+
 static int btrfs_dev_replace_finishing(struct btrfs_fs_info *fs_info,
 				       int scrub_ret);
 static void btrfs_dev_replace_update_device_in_mapping_tree(