On Fri, Sep 18, 2020 at 05:54:43PM -0700, Harshad Shirwadkar wrote: > This patch adds necessary documentation for fast commits. > > Signed-off-by: Harshad Shirwadkar <harshadshirwadkar@xxxxxxxxx> > --- > Documentation/filesystems/ext4/journal.rst | 66 ++++++++++++++++++++++ > Documentation/filesystems/journalling.rst | 28 +++++++++ > 2 files changed, 94 insertions(+) > > diff --git a/Documentation/filesystems/ext4/journal.rst b/Documentation/filesystems/ext4/journal.rst > index ea613ee701f5..c2e4d010a201 100644 > --- a/Documentation/filesystems/ext4/journal.rst > +++ b/Documentation/filesystems/ext4/journal.rst > @@ -609,3 +620,58 @@ bytes long (but uses a full block): > - h\_commit\_nsec > - Nanoseconds component of the above timestamp. > > +Fast commits > +~~~~~~~~~~~~ > + > +Fast commit area is organized as a log of tag tag length values. Each TLV has s/tag tag/tag/ > + > +File system is free to perform fast commits as and when it wants as long as it > +gets permission from JBD2 to do so by calling the function > +:c:func:`jbd2_fc_start()`. Once a fast commit is done, the client > +file system should tell JBD2 about it by calling :c:func:`jbd2_fc_stop()`. > +If file system wants JBD2 to perform a full commit immediately after stopping > +the fast commit it can do so by calling :c:func:`jbd2_fc_stop_do_commit()`. > +This is useful if fast commit operation fails for some reason and the only way > +to guarantee consistency is for JBD2 to perform the full traditional commit. One of the things which is a bit confusing is that there is a substantial part of the fast commit functionality which is implemented in ext4, and not in the jbd2 layer. We can't just talk about ext4_fc_start_update() and ext4_fc_stop_update() here, since it would be a vit of a layering violation. But some kind of explanation of how a file system would use the jbd2 fast commit framework would be useful, and the big picture view of how the ext4 fast commit infrastruction (which is currently documented in the top-level comments of fs/ext4/fast_commit.c) fit into jbd2 infrastructure. Maybe put the big picture explanation in fs/ext4/fast_commit.c and then put a pointer in journaling.rst to the comments in fs/ext4/fast_commit.c as an example of how the jbd2 fast_commit infrastructure would get used (for example, if ocfs2 ever got interested in doing something similar)? Or maybe we need to move some of the description from comments in fast_commit.c to a file in Documentation/filesystems/ext4/fast_commit.rst, perhaps? - Ted
