[PATCH v2] btrfs: add comment about BTRFS_FS_EXCL_OP

[PATCH v2] btrfs: add comment about BTRFS_FS_EXCL_OP

[Anand Jain]

Adds comments about BTRFS_FS_EXCL_OP to existing comments
about the device locks.

Signed-off-by: Anand Jain <anand.jain@oracle.com>
---
v1->v2: add more clarity to the comments added.

 fs/btrfs/volumes.c | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/fs/btrfs/volumes.c b/fs/btrfs/volumes.c
index 3a3912a9dec9..6d7f10729713 100644
--- a/fs/btrfs/volumes.c
+++ b/fs/btrfs/volumes.c
@@ -202,6 +202,38 @@ static int __btrfs_map_block(struct btrfs_fs_info *fs_info,
  *   device_list_mutex
  *     chunk_mutex
  *   balance_mutex
+ *
+ * BTRFS_FS_EXCL_OP
+ * ----------------
+ * Maintains the exclusivity of the following device operations.
+ *
+ * - Balance (*)
+ * - Device add
+ * - Device remove
+ * - Device Replace (*)
+ * - Resize
+ *
+ * The device operations (as above) can be in one of the following states.
+ *
+ * - Running state
+ * - Paused state
+ * - Completed state
+ *
+ * Only device operations marked with (*) can go into the Paused state for the
+ * following reasons.
+ *
+ * - Ioctl (only Balance can be Paused through Ioctl)
+ * - FS re-mounted as read-only
+ * - FS un-mounted and mounted as read-only
+ * - System power-recycle and mounted as read-only
+ * - FS or device errors leading to read-only FS
+ *
+ * BTRFS_FS_EXCL_OP flag is set and cleared using atomic functions.
+ * During the course of Paused state, the BTRFS_FS_EXCL_OP remains set.
+ * A device operation in Paused or Running state can be canceled or resumed
+ * either by Ioctl (Balance only) or when re-mounted as read-write FS.
+ * BTRFS_FS_EXCL_OP flag is cleared when the device operation is canceled or
+ * completed.
  */
 
 DEFINE_MUTEX(uuid_mutex);
-- 
2.15.0

Re: [PATCH v2] btrfs: add comment about BTRFS_FS_EXCL_OP

[David Sterba]

On Wed, Apr 18, 2018 at 02:59:25PM +0800, Anand Jain wrote:
> Adds comments about BTRFS_FS_EXCL_OP to existing comments
> about the device locks.
> 
> Signed-off-by: Anand Jain <anand.jain@oracle.com>

Reviewed-by: David Sterba <dsterba@suse.com>