Re: [PATCH] btrfs: Add intrudoction to dev-replace.

[Anand Jain <anand.jain@oracle.com>]

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(
>