@@ -1312,6 +1312,24 @@ static void sb_freeze_to_level(struct super_block *sb, int level)
* Syncs the super to make sure the filesystem is consistent and calls the fs's
* freeze_fs. Subsequent calls to this without first thawing the fs will return
* -EBUSY.
+ *
+ * During this function, sb->s_frozen goes through these values:
+ *
+ * SB_UNFROZEN: File system is normal, all writes progress as usual.
+ *
+ * SB_FREEZE_WRITE: The file system is in the process of being frozen.
+ * New writes should be blocked, we wait for in-progress writes (using
+ * s_writers[SB_FREEZE_WRITE-1]) and then sync the file system.
+ *
+ * SB_FREEZE_TRANS: The file system is frozen. We wait for all metadata writes
+ * to finish using s_writers[SB_FREEZE_TRANS-1] and after that call ->freeze_fs
+ * to finish filesystem freezing. After ->freeze_fs is done nothing should be
+ * dirty and all modifications are blocked until the file system is thawed.
+ *
+ * sb->s_frozen is protected by sb->s_umount. Additionally,
+ * SB_FREEZE_WRITE is only temporarily set during freeze/thaw while
+ * holding sb->s_umount for writing, so any other callers holding
+ * sb->s_umount will never see this state.
*/
int freeze_super(struct super_block *sb)
{