Re: [PATCH v9 1/9] doc: update ext4 and journalling docs to include fast commit feature

[harshad shirwadkar <harshadshirwadkar@gmail.com>]

On Fri, Oct 9, 2020 at 11:28 AM Theodore Y. Ts'o <tytso@mit.edu> 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@gmail.com>
> > ---
> >  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