On Fri, Oct 9, 2020 at 11:28 AM Theodore Y. Ts'o <tytso@xxxxxxx> wrote: > > 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/ ack > > > + > > +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. As we discussed offline, the names "jbd2_fc_start()" and "jbd2_fc_stop()" are kind of confusing. I didn't mean to put any Ext4 specific information here and it sounds like the names "jbd2_fc_start/stop()" should be renamed to something like jbd2_fc_begin_commit() and jbd2_fc_end_commit(). My goal is to add documentation here that explains how a client FS can use JBD2 fast commits. > > 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? I like the first option. I'll update the docs accordingly in V10. Thanks, Harshad. > > - Ted
