btrfs-progs: rescue: add new command fix-data-checksum

adam900710 · kdave · commit 5ec0cf77e8af · 2025-05-30T12:41:29.000+02:00
It's a long known problem that direct IO can lead to data checksum
mismatches if the user space is also modifying its buffer during
writeback.

Although it's being fixed in the recent v6.15 release (and backported to
older kernels), we still need a user friendly way to fix those problems.

This patch introduces the dryrun version of "btrfs rescue
fix-data-checksum", which reports the logical bytenr and corrupted
mirrors.

Signed-off-by: Qu Wenruo &lt;wqu@suse.com&gt;
Signed-off-by: David Sterba &lt;dsterba@suse.com&gt;
diff --git a/Documentation/btrfs-rescue.rst b/Documentation/btrfs-rescue.rst
@@ -50,6 +50,25 @@ fix-device-size <device>
 
                 WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs]
 
+fix-data-checksum <device>
+	fix data checksum mismatch
+
+	There is a long existing problem that if a user space program is doing
+	direct IO and modifies the buffer before the write back finished, it
+	can lead to data checksum mismatches.
+
+	This problem is known but not fixed until upstream release v6.15
+	(backported to older kernels). So it's possible to hit false data
+	checksum mismatch for any long running btrfs.
+
+	In that case this program can be utilized to repair such problem.
+
+        ``Options``
+
+	-r|--readonly
+		readonly mode, only scan for and report data checksum mismatches,
+		do not repair
+
 .. _man-rescue-clear-ino-cache:
 
 clear-ino-cache <device>
diff --git a/Makefile b/Makefile
@@ -256,7 +256,7 @@ cmds_objects = cmds/subvolume.o cmds/subvolume-list.o \
 	       cmds/inspect.o cmds/balance.o cmds/send.o cmds/receive.o \
 	       cmds/quota.o cmds/qgroup.o cmds/replace.o check/main.o \
 	       cmds/restore.o cmds/rescue.o cmds/rescue-chunk-recover.o \
-	       cmds/rescue-super-recover.o \
+	       cmds/rescue-super-recover.o cmds/rescue-fix-data-checksum.o \
 	       cmds/property.o cmds/filesystem-usage.o cmds/inspect-dump-tree.o \
 	       cmds/inspect-dump-super.o cmds/inspect-tree-stats.o cmds/filesystem-du.o \
 	       cmds/reflink.o \
diff --git a/cmds/rescue-fix-data-checksum.c b/cmds/rescue-fix-data-checksum.c
@@ -0,0 +1,288 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public
+ * License v2 as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public
+ * License along with this program; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 021110-1307, USA.
+ */
+
+#include "kerncompat.h"
+#include "kernel-shared/disk-io.h"
+#include "kernel-shared/ctree.h"
+#include "kernel-shared/volumes.h"
+#include "common/messages.h"
+#include "common/open-utils.h"
+#include "cmds/rescue.h"
+
+/*
+ * Record one corrupted data block.
+ *
+ * We do not report immediately, this is for future file deleting support.
+ */
+struct corrupted_block {
+	struct list_head list;
+	/* The logical bytenr of the exact corrupted block. */
+	u64 logical;
+
+	/* The amount of mirrors above logical have. */
+	unsigned int num_mirrors;
+
+	/*
+	 * Which mirror failed.
+	 *
+	 * Note, bit 0 means mirror 1, since mirror 0 means choosing a
+	 * live mirror, and we never utilized that mirror 0.
+	 */
+	unsigned long *error_mirror_bitmap;
+};
+
+static int global_repair_mode;
+LIST_HEAD(corrupted_blocks);
+
+static int add_corrupted_block(struct btrfs_fs_info *fs_info, u64 logical,
+			       unsigned int mirror, unsigned int num_mirrors)
+{
+	struct corrupted_block *last;
+
+	if (list_empty(&corrupted_blocks))
+		goto add;
+
+	last = list_entry(corrupted_blocks.prev, struct corrupted_block, list);
+	/* The last entry is the same, just set update the error mirror bitmap. */
+	if (last->logical == logical) {
+		UASSERT(last->error_mirror_bitmap);
+		set_bit(mirror, last->error_mirror_bitmap);
+		return 0;
+	}
+add:
+	last = calloc(1, sizeof(*last));
+	if (!last)
+		return -ENOMEM;
+	last->error_mirror_bitmap = calloc(1, BITS_TO_LONGS(num_mirrors));
+	if (!last->error_mirror_bitmap) {
+		free(last);
+		return -ENOMEM;
+	}
+	set_bit(mirror - 1, last->error_mirror_bitmap);
+	last->logical = logical;
+	last->num_mirrors = num_mirrors;
+
+	list_add_tail(&last->list, &corrupted_blocks);
+	return 0;
+}
+
+/*
+ * Verify all mirrors for @logical.
+ *
+ * If something critical happened, return <0 and should end the run immediately.
+ * Otherwise return 0, including data checksum mismatch or read failure.
+ */
+static int verify_one_data_block(struct btrfs_fs_info *fs_info,
+				 struct extent_buffer *leaf,
+				 unsigned long leaf_offset, u64 logical,
+				 unsigned int num_mirrors)
+{
+	const u32 blocksize = fs_info->sectorsize;
+	const u32 csum_size = fs_info->csum_size;
+	u8 *buf;
+	u8 csum[BTRFS_CSUM_SIZE];
+	u8 csum_expected[BTRFS_CSUM_SIZE];
+	int ret = 0;
+
+	buf = malloc(blocksize);
+	if (!buf)
+		return -ENOMEM;
+
+	for (int mirror = 1; mirror <= num_mirrors; mirror++) {
+		u64 read_len = blocksize;
+
+		ret = read_data_from_disk(fs_info, buf, logical, &read_len, mirror);
+		if (ret < 0) {
+			/* IO error, add one record. */
+			ret = add_corrupted_block(fs_info, logical, mirror, num_mirrors);
+			if (ret < 0)
+				break;
+		}
+		/* Verify the data checksum. */
+		btrfs_csum_data(fs_info, fs_info->csum_type, buf, csum, blocksize);
+		read_extent_buffer(leaf, csum_expected, leaf_offset, csum_size);
+		if (memcmp(csum_expected, csum, csum_size) != 0) {
+			ret = add_corrupted_block(fs_info, logical, mirror, num_mirrors);
+			if (ret < 0)
+				break;
+		}
+	}
+
+	free(buf);
+	return ret;
+}
+
+static int iterate_one_csum_item(struct btrfs_fs_info *fs_info, struct btrfs_path *path)
+{
+	struct btrfs_key key;
+	const unsigned long item_ptr_off = btrfs_item_ptr_offset(path->nodes[0],
+								 path->slots[0]);
+	const u32 blocksize = fs_info->sectorsize;
+	int num_mirrors;
+	u64 data_size;
+	u64 cur;
+	char *buf;
+	int ret = 0;
+
+	buf = malloc(blocksize);
+	if (!buf)
+		return -ENOMEM;
+
+	btrfs_item_key_to_cpu(path->nodes[0], &key, path->slots[0]);
+	data_size = btrfs_item_size(path->nodes[0], path->slots[0]) /
+		    fs_info->csum_size * blocksize;
+	num_mirrors = btrfs_num_copies(fs_info, key.offset, data_size);
+
+	for (cur = 0; cur < data_size; cur += blocksize) {
+		const unsigned long leaf_offset = item_ptr_off +
+			cur / blocksize * fs_info->csum_size;
+
+		ret = verify_one_data_block(fs_info, path->nodes[0], leaf_offset,
+					    key.offset + cur, num_mirrors);
+		if (ret < 0)
+			break;
+	}
+	free(buf);
+	return ret;
+}
+
+static int iterate_csum_root(struct btrfs_fs_info *fs_info, struct btrfs_root *csum_root)
+{
+	struct btrfs_path path = { 0 };
+	struct btrfs_key key;
+	int ret;
+
+	key.objectid = 0;
+	key.type = 0;
+	key.offset = 0;
+
+	ret = btrfs_search_slot(NULL, csum_root, &key, &path, 0, 0);
+	if (ret < 0) {
+		errno = -ret;
+		error("failed to get the first tree block of csum tree: %m");
+		return ret;
+	}
+	UASSERT(ret > 0);
+	while (true) {
+		btrfs_item_key_to_cpu(path.nodes[0], &key, path.slots[0]);
+		if (key.type != BTRFS_EXTENT_CSUM_KEY)
+			goto next;
+		ret = iterate_one_csum_item(fs_info, &path);
+		if (ret < 0)
+			break;
+next:
+		ret = btrfs_next_item(csum_root, &path);
+		if (ret > 0) {
+			ret = 0;
+			break;
+		}
+		if (ret < 0) {
+			errno = -ret;
+			error("failed to get next csum item: %m");
+		}
+	}
+	btrfs_release_path(&path);
+	return ret;
+}
+
+static void report_corrupted_blocks(void)
+{
+	struct corrupted_block *entry;
+
+	if (list_empty(&corrupted_blocks)) {
+		pr_verbose(LOG_DEFAULT, "no data checksum mismatch found\n");
+		return;
+	}
+
+	list_for_each_entry(entry, &corrupted_blocks, list) {
+		bool has_printed = false;
+
+		pr_verbose(LOG_DEFAULT, "logical=%llu corrtuped mirrors=", entry->logical);
+		/* Open coded bitmap print. */
+		for (int i = 0; i < entry->num_mirrors; i++) {
+			if (test_bit(i, entry->error_mirror_bitmap)) {
+				if (has_printed)
+					pr_verbose(LOG_DEFAULT, ",");
+				/*
+				 * Bit 0 means mirror 1, thus we need to increase
+				 * the value by 1.
+				 */
+				pr_verbose(LOG_DEFAULT, "%d", i + 1);
+				has_printed=true;
+			}
+		}
+		pr_verbose(LOG_DEFAULT, "\n");
+	}
+}
+
+static void free_corrupted_blocks(void)
+{
+	while (!list_empty(&corrupted_blocks)) {
+		struct corrupted_block *entry;
+
+		entry = list_entry(corrupted_blocks.next, struct corrupted_block, list);
+		list_del_init(&entry->list);
+		free(entry->error_mirror_bitmap);
+		free(entry);
+	}
+}
+
+int btrfs_recover_fix_data_checksum(const char *path, enum btrfs_fix_data_checksum_mode mode)
+{
+	struct btrfs_fs_info *fs_info;
+	struct btrfs_root *csum_root;
+	struct open_ctree_args oca = { 0 };
+	int ret;
+
+	if (mode >= BTRFS_FIX_DATA_CSUMS_LAST)
+		return -EINVAL;
+
+	ret = check_mounted(path);
+	if (ret < 0) {
+		errno = -ret;
+		error("could not check mount status: %m");
+		return ret;
+	}
+	if (ret > 0) {
+		error("%s is currently mounted", path);
+		return -EBUSY;
+	}
+
+	global_repair_mode = mode;
+	oca.filename = path;
+	oca.flags = OPEN_CTREE_WRITES;
+	fs_info = open_ctree_fs_info(&oca);
+	if (!fs_info) {
+		error("failed to open btrfs at %s", path);
+		return -EIO;
+	}
+	csum_root = btrfs_csum_root(fs_info, 0);
+	if (!csum_root) {
+		error("failed to get csum root");
+		ret = -EIO;
+		goto out_close;
+	}
+	ret = iterate_csum_root(fs_info, csum_root);
+	if (ret) {
+		errno = -ret;
+		error("failed to iterate csum tree: %m");
+	}
+	report_corrupted_blocks();
+out_close:
+	free_corrupted_blocks();
+	close_ctree_fs_info(fs_info);
+	return ret;
+}
diff --git a/cmds/rescue.c b/cmds/rescue.c
@@ -22,6 +22,7 @@
 #include <errno.h>
 #include <stdbool.h>
 #include <unistd.h>
+#include <getopt.h>
 #include "kernel-lib/list.h"
 #include "kernel-shared/ctree.h"
 #include "kernel-shared/volumes.h"
@@ -275,6 +276,55 @@ static int cmd_rescue_fix_device_size(const struct cmd_struct *cmd,
 }
 static DEFINE_SIMPLE_COMMAND(rescue_fix_device_size, "fix-device-size");
 
+static const char * const cmd_rescue_fix_data_checksum_usage[] = {
+	"btrfs rescue fix-data-checksum <device>",
+	"Fix data checksum mismatches.",
+	"",
+	OPTLINE("-r", "readonly mode, only report errors without repair"),
+	HELPINFO_INSERT_GLOBALS,
+	HELPINFO_INSERT_VERBOSE,
+	NULL
+};
+
+static int cmd_rescue_fix_data_checksum(const struct cmd_struct *cmd,
+					int argc, char **argv)
+{
+	enum btrfs_fix_data_checksum_mode mode = BTRFS_FIX_DATA_CSUMS_READONLY;
+	int ret;
+
+	optind = 0;
+	while (1) {
+		int c;
+		enum { GETOPT_VAL_DRYRUN = GETOPT_VAL_FIRST };
+		static const struct option long_options [] = {
+			{"readonly", no_argument, NULL, 'r'},
+			{"NULL", 0, NULL, 0},
+		};
+
+		c = getopt_long(argc, argv, "r", long_options, NULL);
+		if (c < 0)
+			break;
+		switch (c) {
+		case 'r':
+			mode = BTRFS_FIX_DATA_CSUMS_READONLY;
+			break;
+		default:
+			usage_unknown_option(cmd, argv);
+		}
+	}
+
+	if (check_argc_min(argc - optind, 1))
+		return 1;
+
+	ret = btrfs_recover_fix_data_checksum(argv[optind], mode);
+	if (ret < 0) {
+		errno = -ret;
+		error("failed to fix data checksums: %m");
+	}
+	return !!ret;
+}
+static DEFINE_SIMPLE_COMMAND(rescue_fix_data_checksum, "fix-data-checksum");
+
 static const char * const cmd_rescue_create_control_device_usage[] = {
 	"btrfs rescue create-control-device",
 	"Create /dev/btrfs-control (see 'CONTROL DEVICE' in btrfs(5))",
@@ -527,6 +577,7 @@ static const struct cmd_group rescue_cmd_group = {
 		&cmd_struct_rescue_super_recover,
 		&cmd_struct_rescue_zero_log,
 		&cmd_struct_rescue_fix_device_size,
+		&cmd_struct_rescue_fix_data_checksum,
 		&cmd_struct_rescue_create_control_device,
 		&cmd_struct_rescue_clear_ino_cache,
 		&cmd_struct_rescue_clear_space_cache,
diff --git a/cmds/rescue.h b/cmds/rescue.h
