tests/block_cloning: rename and document get_same_blocks helper

`get_same_blocks` is a helper to compare two files and return a list of
the blocks that are clones of each other. Its very necessary for block
cloning tests.

Previously it was incorrectly called `unique_blocks`, which is the
_inverse_ of what it does (an early version did list unique blocks; it
was changed but the name was not). So if nothing else, it should be
called `duplicate_blocks`.

But, keeping the details of a clone operation in your head is actually
quite difficult, without the additional overhead of wondering how the
tools work. So I've renamed it to better describe what it does, added a
usage note, and changed it to return block indexes from 0 instead of 1,
to match how L0 blocks are normally counted.

Reviewed-by: Umer Saleem <usaleem@ixsystems.com>
Reviewed-by:  Kay Pedersen <mail@mkwg.de>
Signed-off-by: Rob Norris <robn@despairlabs.com>
Closes openzfs#15181

tests/zfs-tests/tests/functional/block_cloning/block_cloning.kshlib

@@ -34,13 +34,21 @@ function have_same_content
 	log_must [ "$hash1" = "$hash2" ]
 }
 
-function unique_blocks
+#
+# get_same_blocks dataset1 path/to/file1 dataset2 path/to/file2
+#
+# Returns a space-separated list of the indexes (starting at 0) of the L0
+# blocks that are shared between both files (by first DVA and checksum).
+# Assumes that the two files have the same content, use have_same_content to
+# confirm that.
+#
+function get_same_blocks
 {
 	typeset zdbout=${TMPDIR:-$TEST_BASE_DIR}/zdbout.$$
 	zdb -vvvvv $1 -O $2 | \
-	    awk '/ L0 / { print ++l " " $3 " " $7 }' > $zdbout.a
+	    awk '/ L0 / { print l++ " " $3 " " $7 }' > $zdbout.a
 	zdb -vvvvv $3 -O $4 | \
-	    awk '/ L0 / { print ++l " " $3 " " $7 }' > $zdbout.b
+	    awk '/ L0 / { print l++ " " $3 " " $7 }' > $zdbout.b
 	echo $(sort $zdbout.a $zdbout.b | uniq -d | cut -f1 -d' ')
 }
 

tests/zfs-tests/tests/functional/block_cloning/block_cloning_copyfilerange.ksh

@@ -54,7 +54,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
-log_must [ "$blocks" = "1 2 3 4" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
+log_must [ "$blocks" = "0 1 2 3" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_copyfilerange_cross_dataset.ksh

@@ -58,8 +58,8 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/$TESTFS1/file1 /$TESTPOOL/$TESTFS2/file2
 
-typeset blocks=$(unique_blocks \
+typeset blocks=$(get_same_blocks \
   $TESTPOOL/$TESTFS1 file1 $TESTPOOL/$TESTFS2 file2)
-log_must [ "$blocks" = "1 2 3 4" ]
+log_must [ "$blocks" = "0 1 2 3" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_copyfilerange_fallback.ksh

@@ -58,8 +58,8 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file /$TESTPOOL/clone
 
-typeset blocks=$(unique_blocks $TESTPOOL file $TESTPOOL clone)
-log_must [ "$blocks" = "1 2 3 4" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file $TESTPOOL clone)
+log_must [ "$blocks" = "0 1 2 3" ]
 
 
 log_note "Copying within a block with copy_file_range"
@@ -69,8 +69,8 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file /$TESTPOOL/clone
 
-typeset blocks=$(unique_blocks $TESTPOOL file $TESTPOOL clone)
-log_must [ "$blocks" = "2 3 4" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file $TESTPOOL clone)
+log_must [ "$blocks" = "1 2 3" ]
 
 
 log_note "Copying across a block with copy_file_range"
@@ -80,7 +80,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file /$TESTPOOL/clone
 
-typeset blocks=$(unique_blocks $TESTPOOL file $TESTPOOL clone)
-log_must [ "$blocks" = "2" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file $TESTPOOL clone)
+log_must [ "$blocks" = "1" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_copyfilerange_fallback_same_txg.ksh

@@ -59,7 +59,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file /$TESTPOOL/clone
 
-typeset blocks=$(unique_blocks $TESTPOOL file $TESTPOOL clone)
+typeset blocks=$(get_same_blocks $TESTPOOL file $TESTPOOL clone)
 log_must [ "$blocks" = "" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_copyfilerange_partial.ksh

@@ -54,15 +54,15 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
 log_must [ "$blocks" = "" ]
 
 log_must clonefile -f /$TESTPOOL/file1 /$TESTPOOL/file2 131072 131072 262144
 log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
-log_must [ "$blocks" = "2 3" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
+log_must [ "$blocks" = "1 2" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_disabled_copyfilerange.ksh

@@ -54,7 +54,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
 log_must [ "$blocks" = "" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_ficlone.ksh

@@ -50,7 +50,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
-log_must [ "$blocks" = "1 2 3 4" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
+log_must [ "$blocks" = "0 1 2 3" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_ficlonerange.ksh

@@ -50,7 +50,7 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
-log_must [ "$blocks" = "1 2 3 4" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
+log_must [ "$blocks" = "0 1 2 3" ]
 
 log_pass $claim

tests/zfs-tests/tests/functional/block_cloning/block_cloning_ficlonerange_partial.ksh

@@ -50,15 +50,15 @@ log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
 log_must [ "$blocks" = "" ]
 
 log_must clonefile -r /$TESTPOOL/file1 /$TESTPOOL/file2 131072 131072 262144
 log_must sync_pool $TESTPOOL
 
 log_must have_same_content /$TESTPOOL/file1 /$TESTPOOL/file2
 
-typeset blocks=$(unique_blocks $TESTPOOL file1 $TESTPOOL file2)
-log_must [ "$blocks" = "2 3" ]
+typeset blocks=$(get_same_blocks $TESTPOOL file1 $TESTPOOL file2)
+log_must [ "$blocks" = "1 2" ]
 
 log_pass $claim