btrfs: uapi: Add warning for btrfs_qgroup_inherit usage for snapshot creation

Commit Message

Qu Wenruo May 8, 2020, 5:47 a.m. UTC

Snapshot creation with btrfs_qgroup_inherit structure can easily lead to
qgroup inconsistent.

The inconsistency itself is not a big deal, but due to the limitation of
the ioctl, we can't inform user space to do a rescan.

Thus it's recommended to use BTRFS_IOC_QGROUP_ASSIGN to assign qgroup
relation other than do it in snapshot creation.

Signed-off-by: Qu Wenruo <[e-mail]>
---
 include/uapi/linux/btrfs.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

Patch

diff --git a/include/uapi/linux/btrfs.h b/include/uapi/linux/btrfs.h
index dc8675d892a4..b8881910bde3 100644
--- a/include/uapi/linux/btrfs.h
+++ b/include/uapi/linux/btrfs.h
@@ -132,6 +132,17 @@  struct btrfs_ioctl_vol_args_v2 {
 	union {
 		struct {
 			__u64 size;
+			/*
+			 * WARNING: Don't use this structure to assign qgroup
+			 * for snapshot creation.
+			 *
+			 * Such inheritance for snapshot can lead to qgroup
+			 * inconsistent due to massive extent ownership change.
+			 *
+			 * Due to the limitation of snapshot creation ioctl, we
+			 * can't inform user space to do a rescan.
+			 * Please use BTRFS_IOC_QGROUP_ASSIGN instead.
+			 */
 			struct btrfs_qgroup_inherit __user *qgroup_inherit;
 		};
 		__u64 unused[4];