Re: [PATCH v4 2/9] fs: add infrastructure for multigrain inode i_m/ctime

["Theodore Ts'o" <tytso@mit.edu>]

On Thu, May 18, 2023 at 07:47:35AM -0400, Jeff Layton wrote:
> Use the 31st bit of the ctime tv_nsec field to indicate that something
> has queried the inode for the i_mtime or i_ctime. When this flag is set,
> on the next timestamp update, the kernel can fetch a fine-grained
> timestamp instead of the usual coarse-grained one.

TIL....  that atomic_long_fetch_or() and atomic_long_fetch_andnot()
exist.  :-)

When I went looking for documentation about why they do or this
particular usage pattern found in the patch, I didn't find any --- at
least, certainly not in the Documentation in the kernel sources.  The
closest that I fond was this LWN article written by Neil Brown from
2016:

	https://lwn.net/Articles/698315/

... and this only covered the use atomic_fetch_or(); I wasn't able to
find anything discussing atomic_fetch_andnot().

It looks like Peter Zijlstra added some bare-bones documentation in
2017, in commit: 706eeb3e9c6f ("Documentation/locking/atomic: Add
documents for new atomic_t APIs") so we do have Documentation that
these functions *exist*, but there is nothing explaining what they do,
or how they can be used (e.g., in this rather clever way to set and
clear a flag in the high bits of the nsec field).

I know that it's best to report missing documentation in the form of a
patch, but I fear I don't have the time or the expertise to really do
this topic justice, so I'd just thought I'd just note this lack for
now, and maybe in my copious spare time I'll try to get at least
something that will no doubt contain errors, but might inspire some
folks to correct the text.  (Or maybe on someone on linux-doc will
feel inspired and get there ahead of me.  :-)

					- Ted