[PATCH] fs/9p: Add new options to Documentation

[PATCH] fs/9p: Add new options to Documentation

[Eric Van Hensbergen]

Need to update the documentation for new mount flags
and cache modes.

Signed-off-by: Eric Van Hensbergen <ericvh@kernel.org>
---
 Documentation/filesystems/9p.rst | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
index 0e800b8f73cc..6d257854a02a 100644
--- a/Documentation/filesystems/9p.rst
+++ b/Documentation/filesystems/9p.rst
@@ -78,19 +78,18 @@ Options
   		offering several exported file systems.
 
   cache=mode	specifies a caching policy.  By default, no caches are used.
-
-                        none
-				default no cache policy, metadata and data
-                                alike are synchronous.
-			loose
-				no attempts are made at consistency,
-                                intended for exclusive, read-only mounts
-                        fscache
-				use FS-Cache for a persistent, read-only
-				cache backend.
-                        mmap
-				minimal cache that is only used for read-write
-                                mmap.  Northing else is cached, like cache=none
+		Modes are progressive and inclusive.  For example, specifying fscache
+		will use loose caches, writeback, and readahead.  Due to their
+		inclusive nature, only one cache mode can be specified per mount.
+
+			=========	=============================================
+			none		no cache of file or metadata
+			readahead	readahead caching of files
+			writeback	delayed writeback of files
+			mmap		support mmap operations read/write with cache
+			loose		meta-data and file cache with no coherency
+			fscache		use FS-Cache for a persistent cache backend
+			=========	=============================================
 
   debug=n	specifies debug level.  The debug level is a bitmask.
 
@@ -137,6 +136,10 @@ Options
   		This can be used to share devices/named pipes/sockets between
 		hosts.  This functionality will be expanded in later versions.
 
+  directio	bypass page cache on all read/write operations
+
+  ignoreqv	ignore qid.version==0 as a marker to ignore cache
+
   noxattr	do not offer xattr functions on this mount.
 
   access	there are four access modes.
-- 
2.39.2

Re: [PATCH] fs/9p: Add new options to Documentation

[Christian Schoenebeck]

On Monday, March 27, 2023 5:05:52 AM CEST Eric Van Hensbergen wrote:
> Need to update the documentation for new mount flags
> and cache modes.
> 
> Signed-off-by: Eric Van Hensbergen <ericvh@kernel.org>
> ---
>  Documentation/filesystems/9p.rst | 29 ++++++++++++++++-------------
>  1 file changed, 16 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
> index 0e800b8f73cc..6d257854a02a 100644
> --- a/Documentation/filesystems/9p.rst
> +++ b/Documentation/filesystems/9p.rst
> @@ -78,19 +78,18 @@ Options
>    		offering several exported file systems.
>  
>    cache=mode	specifies a caching policy.  By default, no caches are used.
> -
> -                        none
> -				default no cache policy, metadata and data
> -                                alike are synchronous.
> -			loose
> -				no attempts are made at consistency,
> -                                intended for exclusive, read-only mounts
> -                        fscache
> -				use FS-Cache for a persistent, read-only
> -				cache backend.
> -                        mmap
> -				minimal cache that is only used for read-write
> -                                mmap.  Northing else is cached, like cache=none
> +		Modes are progressive and inclusive.  For example, specifying fscache
> +		will use loose caches, writeback, and readahead.  Due to their
> +		inclusive nature, only one cache mode can be specified per mount.

I would highly recommend to rather specify below for each option "this option
implies writeback, readahead ..." etc., as it is not obvious otherwise which
option would exactly imply what. It is worth those extra few lines IMO to
avoid confusion.

> +
> +			=========	=============================================
> +			none		no cache of file or metadata
> +			readahead	readahead caching of files
> +			writeback	delayed writeback of files
> +			mmap		support mmap operations read/write with cache
> +			loose		meta-data and file cache with no coherency
> +			fscache		use FS-Cache for a persistent cache backend
> +			=========	=============================================
>  
>    debug=n	specifies debug level.  The debug level is a bitmask.
>  
> @@ -137,6 +136,10 @@ Options
>    		This can be used to share devices/named pipes/sockets between
>  		hosts.  This functionality will be expanded in later versions.
>  
> +  directio	bypass page cache on all read/write operations
> +
> +  ignoreqv	ignore qid.version==0 as a marker to ignore cache
> +
>    noxattr	do not offer xattr functions on this mount.
>  
>    access	there are four access modes.
> 

Re: [PATCH] fs/9p: Add new options to Documentation

[Eric Van Hensbergen]

As I work through the documentation rework and to some extent the
testing matrix -- I am reconsidering some choices and wanted to open
up the discussion here.

TLDR; I'm thinking of reworking the cache options before the merge
window to keep things simple while setting up for some of the future
options.

While we have a bunch of new options, in practice I expect users to
probably consolidate around three models: no caching, tight caches,
and expiring caches with fscache being an orthogonal add-on to the
last two.

The ultimate goal is to simplify the options based on expected use models:

- cache=[ none, file, all ] (none is currently default)
- write_policy = [ *writethrough, writeback ] (writethrough would be default)
- cache_validate = [ never, *open, x (seconds) ]  (cache_validate
would default to open)
- fscache

So, mapping of existing (deprecated) legacy modes:
- none (obvious) write_policy=writethrough
- *readahead -> cache=file cache_validate_open write_policy=writethrough
- mmap -> cache=file cache_validate=open write_policy=writeback
- loose -> cache=all cache_validate=never write_policy=writeback
- fscache -> cache=all cache_validate=never write_policy=writeback &
fscache enabled

Some things I'm less certain of: cache_validation is probably an
imperfect term as is using 'open' as one of the options, in this case
I'm envisioning 'open' to mean open-to-close coherency for file
caching (cache is only validated on open) and validation on lookup for
dir-cache coherency (using qid.version). Specifying a number here
expires existing caches and requires validation after a certain number
of seconds (is that the right granularity)?

So, I think this is more clear from a documentation standpoint, but
unfortuantely I haven't reduced the test matrix much - in fact I've
probably made it worse. I expect the common cases to basically be:
- cache=none
- new default? (cache=all, write_policy=writeback, cache_validate=open)
- fscache w/(cache=all, write_policy=writeback, cache_validate=5)

Which would give us 3 configurations to test against versus 25
(assuming testing for one time value for cache-validate=x). Important
to remember that this is just cache mode tests, the other mount
options act as multipliers.

Thoughts?  Alternatives?

        -eric

On Mon, Mar 27, 2023 at 10:38 AM Christian Schoenebeck
<linux_oss@crudebyte.com> wrote:
>
> On Monday, March 27, 2023 5:05:52 AM CEST Eric Van Hensbergen wrote:
> > Need to update the documentation for new mount flags
> > and cache modes.
> >
> > Signed-off-by: Eric Van Hensbergen <ericvh@kernel.org>
> > ---
> >  Documentation/filesystems/9p.rst | 29 ++++++++++++++++-------------
> >  1 file changed, 16 insertions(+), 13 deletions(-)
> >
> > diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
> > index 0e800b8f73cc..6d257854a02a 100644
> > --- a/Documentation/filesystems/9p.rst
> > +++ b/Documentation/filesystems/9p.rst
> > @@ -78,19 +78,18 @@ Options
> >               offering several exported file systems.
> >
> >    cache=mode specifies a caching policy.  By default, no caches are used.
> > -
> > -                        none
> > -                             default no cache policy, metadata and data
> > -                                alike are synchronous.
> > -                     loose
> > -                             no attempts are made at consistency,
> > -                                intended for exclusive, read-only mounts
> > -                        fscache
> > -                             use FS-Cache for a persistent, read-only
> > -                             cache backend.
> > -                        mmap
> > -                             minimal cache that is only used for read-write
> > -                                mmap.  Northing else is cached, like cache=none
> > +             Modes are progressive and inclusive.  For example, specifying fscache
> > +             will use loose caches, writeback, and readahead.  Due to their
> > +             inclusive nature, only one cache mode can be specified per mount.
>
> I would highly recommend to rather specify below for each option "this option
> implies writeback, readahead ..." etc., as it is not obvious otherwise which
> option would exactly imply what. It is worth those extra few lines IMO to
> avoid confusion.
>
> > +
> > +                     =========       =============================================
> > +                     none            no cache of file or metadata
> > +                     readahead       readahead caching of files
> > +                     writeback       delayed writeback of files
> > +                     mmap            support mmap operations read/write with cache
> > +                     loose           meta-data and file cache with no coherency
> > +                     fscache         use FS-Cache for a persistent cache backend
> > +                     =========       =============================================
> >
> >    debug=n    specifies debug level.  The debug level is a bitmask.
> >
> > @@ -137,6 +136,10 @@ Options
> >               This can be used to share devices/named pipes/sockets between
> >               hosts.  This functionality will be expanded in later versions.
> >
> > +  directio   bypass page cache on all read/write operations
> > +
> > +  ignoreqv   ignore qid.version==0 as a marker to ignore cache
> > +
> >    noxattr    do not offer xattr functions on this mount.
> >
> >    access     there are four access modes.
> >
>
>
>
>

Re: [PATCH] fs/9p: Add new options to Documentation

[Christian Schoenebeck]

+CC: Jeff for experience on this caching issue with NFS ...

On Tuesday, March 28, 2023 5:51:51 PM CEST Eric Van Hensbergen wrote:
> As I work through the documentation rework and to some extent the
> testing matrix -- I am reconsidering some choices and wanted to open
> up the discussion here.
> 
> TLDR; I'm thinking of reworking the cache options before the merge
> window to keep things simple while setting up for some of the future
> options.

Yeah, revising the 9p cache options highly makes sense!

So what is the plan on this now? I saw you sent a new patch with the "old"
options today? So is this one here deferred?

> While we have a bunch of new options, in practice I expect users to
> probably consolidate around three models: no caching, tight caches,
> and expiring caches with fscache being an orthogonal add-on to the
> last two.

Actually as of today I don't know why somebody would want to use fscache
instead of loose. Does it actually make sense to keep fscache and if yes why?

> The ultimate goal is to simplify the options based on expected use models:
> 
> - cache=[ none, file, all ] (none is currently default)

dir?

> - write_policy = [ *writethrough, writeback ] (writethrough would be default)
> - cache_validate = [ never, *open, x (seconds) ]  (cache_validate
> would default to open)

Jeff came up with the point that NFS uses a slicing time window for NFS. So
the question is, would it make sense to add an option x seconds that might be
dropped soon anyway?

> - fscache
> 
> So, mapping of existing (deprecated) legacy modes:
> - none (obvious) write_policy=writethrough
> - *readahead -> cache=file cache_validate_open write_policy=writethrough
> - mmap -> cache=file cache_validate=open write_policy=writeback

Mmm, why is that "file"? To me "file" sounds like any access to files is
cached, whereas cache=mmap just uses the cache if mmap() was called, not for
any other file access.

> - loose -> cache=all cache_validate=never write_policy=writeback
> - fscache -> cache=all cache_validate=never write_policy=writeback &
> fscache enabled
> 
> Some things I'm less certain of: cache_validation is probably an
> imperfect term as is using 'open' as one of the options, in this case
> I'm envisioning 'open' to mean open-to-close coherency for file
> caching (cache is only validated on open) and validation on lookup for
> dir-cache coherency (using qid.version). Specifying a number here
> expires existing caches and requires validation after a certain number
> of seconds (is that the right granularity)?

Personally I would then really call it open-to-close or opentoclose and waste
some more characters in favour of clarity.

> So, I think this is more clear from a documentation standpoint, but
> unfortuantely I haven't reduced the test matrix much - in fact I've
> probably made it worse. I expect the common cases to basically be:
> - cache=none
> - new default? (cache=all, write_policy=writeback, cache_validate=open)
> - fscache w/(cache=all, write_policy=writeback, cache_validate=5)
> 
> Which would give us 3 configurations to test against versus 25
> (assuming testing for one time value for cache-validate=x). Important
> to remember that this is just cache mode tests, the other mount
> options act as multipliers.
> 
> Thoughts?  Alternatives?
> 
>         -eric
> 
> On Mon, Mar 27, 2023 at 10:38 AM Christian Schoenebeck
> <linux_oss@crudebyte.com> wrote:
> >
> > On Monday, March 27, 2023 5:05:52 AM CEST Eric Van Hensbergen wrote:
> > > Need to update the documentation for new mount flags
> > > and cache modes.
> > >
> > > Signed-off-by: Eric Van Hensbergen <ericvh@kernel.org>
> > > ---
> > >  Documentation/filesystems/9p.rst | 29 ++++++++++++++++-------------
> > >  1 file changed, 16 insertions(+), 13 deletions(-)
> > >
> > > diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
> > > index 0e800b8f73cc..6d257854a02a 100644
> > > --- a/Documentation/filesystems/9p.rst
> > > +++ b/Documentation/filesystems/9p.rst
> > > @@ -78,19 +78,18 @@ Options
> > >               offering several exported file systems.
> > >
> > >    cache=mode specifies a caching policy.  By default, no caches are used.
> > > -
> > > -                        none
> > > -                             default no cache policy, metadata and data
> > > -                                alike are synchronous.
> > > -                     loose
> > > -                             no attempts are made at consistency,
> > > -                                intended for exclusive, read-only mounts
> > > -                        fscache
> > > -                             use FS-Cache for a persistent, read-only
> > > -                             cache backend.
> > > -                        mmap
> > > -                             minimal cache that is only used for read-write
> > > -                                mmap.  Northing else is cached, like cache=none
> > > +             Modes are progressive and inclusive.  For example, specifying fscache
> > > +             will use loose caches, writeback, and readahead.  Due to their
> > > +             inclusive nature, only one cache mode can be specified per mount.
> >
> > I would highly recommend to rather specify below for each option "this option
> > implies writeback, readahead ..." etc., as it is not obvious otherwise which
> > option would exactly imply what. It is worth those extra few lines IMO to
> > avoid confusion.
> >
> > > +
> > > +                     =========       =============================================
> > > +                     none            no cache of file or metadata
> > > +                     readahead       readahead caching of files
> > > +                     writeback       delayed writeback of files
> > > +                     mmap            support mmap operations read/write with cache
> > > +                     loose           meta-data and file cache with no coherency
> > > +                     fscache         use FS-Cache for a persistent cache backend
> > > +                     =========       =============================================
> > >
> > >    debug=n    specifies debug level.  The debug level is a bitmask.
> > >
> > > @@ -137,6 +136,10 @@ Options
> > >               This can be used to share devices/named pipes/sockets between
> > >               hosts.  This functionality will be expanded in later versions.
> > >
> > > +  directio   bypass page cache on all read/write operations
> > > +
> > > +  ignoreqv   ignore qid.version==0 as a marker to ignore cache
> > > +
> > >    noxattr    do not offer xattr functions on this mount.
> > >
> > >    access     there are four access modes.
> > >
> >
> >
> >
> >
> 

Re: [PATCH] fs/9p: Add new options to Documentation

[asmadeus]

Christian Schoenebeck wrote on Sun, Apr 02, 2023 at 04:07:51PM +0200:
> > So, mapping of existing (deprecated) legacy modes:
> > - none (obvious) write_policy=writethrough
> > - *readahead -> cache=file cache_validate_open write_policy=writethrough
> > - mmap -> cache=file cache_validate=open write_policy=writeback
> 
> Mmm, why is that "file"? To me "file" sounds like any access to files is
> cached, whereas cache=mmap just uses the cache if mmap() was called, not for
> any other file access.

The semantics are slightly different but I don't think anyone would
mind; mmap was introduced as a way of having minimal caching but file
caching + /sys/class/bdi/9p*/max_bytes to 0 should be almost identical
once we've made sure our cache code sends bigger than 4k writes at a
time (I *think* that's still a problem and there was netfs work in the
ways, but you'd have noticed?)

--
Dominique

Re: [PATCH] fs/9p: Add new options to Documentation

[Eric Van Hensbergen]

On Sun, Apr 2, 2023 at 9:07 AM Christian Schoenebeck
<linux_oss@crudebyte.com> wrote:
>
> +CC: Jeff for experience on this caching issue with NFS ...
>
> On Tuesday, March 28, 2023 5:51:51 PM CEST Eric Van Hensbergen wrote:
> > As I work through the documentation rework and to some extent the
> > testing matrix -- I am reconsidering some choices and wanted to open
> > up the discussion here.
> >
> > TLDR; I'm thinking of reworking the cache options before the merge
> > window to keep things simple while setting up for some of the future
> > options.
>
> Yeah, revising the 9p cache options highly makes sense!
>
> So what is the plan on this now? I saw you sent a new patch with the "old"
> options today? So is this one here deferred?
>

Yes - I decided to just bite the bullet and try and have a new
approach to things that was less confusing and try and reduce the test
matrix.
Unfortunately, I was also switching over to trying to use b4 to manage
these things and didn't see a way to relate the patch to the original
one.
I figured the increase in scope justified a new thread.

> > While we have a bunch of new options, in practice I expect users to
> > probably consolidate around three models: no caching, tight caches,
> > and expiring caches with fscache being an orthogonal add-on to the
> > last two.
>
> Actually as of today I don't know why somebody would want to use fscache
> instead of loose. Does it actually make sense to keep fscache and if yes why?
>

Persistent caches make sense in certain scenarios, it basically gives
a way to lazy populate a local cache of the remote server.  I wouldn't
use it in qemu
or a VM, but I'd definitely use it in cluster scenarios.  Its also
potentially useful for unstable connections -- but this is more
challenging to deal with in 9p although solutions have been proposed
in the past.

> > The ultimate goal is to simplify the options based on expected use models:
> >
> > - cache=[ none, file, all ] (none is currently default)
>
> dir?
>

That was what I was originally going to do, but 'all' makes the
inclusivity of file explicit.   The more I thought about it, the less
I saw a use case for caching meta data and not file data.  Of course,
in the new patch series I have a bit for meta-data (which is a bit
more accurate than just saying dir) at least in the current
implementation.  However, if I did a shortcut, it probably
would be all and not dir (there isn't one yet in the new patch as I'm
holding off until I fix consistency for meta-data -- which is in
progress and I think imperfect but closer than loose).  And actually
once we are convinced this is working, the shortcut for all may be
better represented as 'default' (hopefully).

> > - write_policy = [ *writethrough, writeback ] (writethrough would be default)
> > - cache_validate = [ never, *open, x (seconds) ]  (cache_validate
> > would default to open)
>
> Jeff came up with the point that NFS uses a slicing time window for NFS. So
> the question is, would it make sense to add an option x seconds that might be
> dropped soon anyway?
>

I had thought about that, and in fact in the new patch series I
haven't implemented either yet.  In the bitmask version I could used
one of the reserved bits to specify adaptive timeouts like Jeff said
NFS does and then the high bits to specify the base timeout or 0 if
you never want to validate (current loose).  Loose mode itself
specifies look at the base timeout for how much temporal consistency
to apply.

Looking ahead at implementing this there is going to be ripple effects
through the code, probably changing the way we use the cache_validity
field in inode.  But seems straightforward enough.

> > - fscache
> >
> > So, mapping of existing (deprecated) legacy modes:
> > - none (obvious) write_policy=writethrough
> > - *readahead -> cache=file cache_validate_open write_policy=writethrough
> > - mmap -> cache=file cache_validate=open write_policy=writeback
>
> Mmm, why is that "file"? To me "file" sounds like any access to files is
> cached, whereas cache=mmap just uses the cache if mmap() was called, not for
> any other file access.
>

Well, not technically true -- because if the file is mmaped and it is
accessed another way other than the mmap then we need to basically
treat it as cached or we'll get inconsistencies between the mmap
version and the uncached read/write version.  So the code ends up
using open-to-close file caching for everything.  In any case, mmap
was there for compatibility reasons before we had a non-loose caching
option.  With tight caches, its better to just incorporate mmap with
it (given the above concerns on behavior).  Otherwise we'd have to
enforce a non-posix semantic of the only way to access an mmaped file
is with mmap and force invalidations of others that might already have
a file open when someonebody else mmaps it...would be messy.

> > - loose -> cache=all cache_validate=never write_policy=writeback
> > - fscache -> cache=all cache_validate=never write_policy=writeback &
> > fscache enabled
> >
> > Some things I'm less certain of: cache_validation is probably an
> > imperfect term as is using 'open' as one of the options, in this case
> > I'm envisioning 'open' to mean open-to-close coherency for file
> > caching (cache is only validated on open) and validation on lookup for
> > dir-cache coherency (using qid.version). Specifying a number here
> > expires existing caches and requires validation after a certain number
> > of seconds (is that the right granularity)?
>
> Personally I would then really call it open-to-close or opentoclose and waste
> some more characters in favour of clarity.
>

I had open2close in the new version and then reverted it to the
inverse of loose because it made checking the bit pattern much easier.
But the plan is for loose to cover no-consistency (when
cache-timeout==0, and temporal consistency when cache-timeout > 0, and
then augment that with Jeff's suggestion of an adaptive bit).
Perhaps the new loose shortcut will cover NFS-like semantics with a
base-timeout of 5s and adaptivity bit set.

      -eric

Re: [PATCH] fs/9p: Add new options to Documentation

[Jeff Layton]

On Sun, 2023-04-02 at 16:07 +0200, Christian Schoenebeck wrote:
> +CC: Jeff for experience on this caching issue with NFS ...
> 
> On Tuesday, March 28, 2023 5:51:51 PM CEST Eric Van Hensbergen wrote:
> > As I work through the documentation rework and to some extent the
> > testing matrix -- I am reconsidering some choices and wanted to open
> > up the discussion here.
> > 
> > TLDR; I'm thinking of reworking the cache options before the merge
> > window to keep things simple while setting up for some of the future
> > options.
> 
> Yeah, revising the 9p cache options highly makes sense!
> 
> So what is the plan on this now? I saw you sent a new patch with the "old"
> options today? So is this one here deferred?
> 
> > While we have a bunch of new options, in practice I expect users to
> > probably consolidate around three models: no caching, tight caches,
> > and expiring caches with fscache being an orthogonal add-on to the
> > last two.
> 
> Actually as of today I don't know why somebody would want to use fscache
> instead of loose. Does it actually make sense to keep fscache and if yes why?
> 
> > The ultimate goal is to simplify the options based on expected use models:
> > 
> > - cache=[ none, file, all ] (none is currently default)
> 
> dir?
> 
> > - write_policy = [ *writethrough, writeback ] (writethrough would be default)
> > - cache_validate = [ never, *open, x (seconds) ]  (cache_validate
> > would default to open)
> 
> Jeff came up with the point that NFS uses a slicing time window for NFS. So
> the question is, would it make sense to add an option x seconds that might be
> dropped soon anyway?

See the acregmin/acregmax/acdirmin/acdirmax settings in nfs(5). What
you're talking about is basically adding an actimeo= option.

If you're revising options for this stuff, then consider following NFS's
naming. Not that they are better in any sense, but they are at least
familiar to administrators.

As far as the sliding window goes, the way it tracks that is a bit
arcane, but in include/linux/nfs_fs.h:


        /*
         * read_cache_jiffies is when we started read-caching this inode.
         * attrtimeo is for how long the cached information is assumed
         * to be valid. A successful attribute revalidation doubles
         * attrtimeo (up to acregmax/acdirmax), a failure resets it to
         * acregmin/acdirmin.
         *
         * We need to revalidate the cached attrs for this inode if
         *
         *      jiffies - read_cache_jiffies >= attrtimeo
         *
         * Please note the comparison is greater than or equal
         * so that zero timeout values can be specified.
         */


That's probably what I'd aim for here.

> > - fscache
> > 
> > So, mapping of existing (deprecated) legacy modes:
> > - none (obvious) write_policy=writethrough
> > - *readahead -> cache=file cache_validate_open write_policy=writethrough
> > - mmap -> cache=file cache_validate=open write_policy=writeback
> 
> Mmm, why is that "file"? To me "file" sounds like any access to files is
> cached, whereas cache=mmap just uses the cache if mmap() was called, not for
> any other file access.
> 
> > - loose -> cache=all cache_validate=never write_policy=writeback
> > - fscache -> cache=all cache_validate=never write_policy=writeback &
> > fscache enabled
> > 
> > Some things I'm less certain of: cache_validation is probably an
> > imperfect term as is using 'open' as one of the options, in this case
> > I'm envisioning 'open' to mean open-to-close coherency for file
> > caching (cache is only validated on open) and validation on lookup for
> > dir-cache coherency (using qid.version). Specifying a number here
> > expires existing caches and requires validation after a certain number
> > of seconds (is that the right granularity)?
> 
> Personally I would then really call it open-to-close or opentoclose and waste
> some more characters in favour of clarity.
> 
> > So, I think this is more clear from a documentation standpoint, but
> > unfortuantely I haven't reduced the test matrix much - in fact I've
> > probably made it worse. I expect the common cases to basically be:
> > - cache=none
> > - new default? (cache=all, write_policy=writeback, cache_validate=open)
> > - fscache w/(cache=all, write_policy=writeback, cache_validate=5)
> > 
> > Which would give us 3 configurations to test against versus 25
> > (assuming testing for one time value for cache-validate=x). Important
> > to remember that this is just cache mode tests, the other mount
> > options act as multipliers.
> > 
> > Thoughts?  Alternatives?
> > 
> >         -eric
> > 
> > On Mon, Mar 27, 2023 at 10:38 AM Christian Schoenebeck
> > <linux_oss@crudebyte.com> wrote:
> > > 
> > > On Monday, March 27, 2023 5:05:52 AM CEST Eric Van Hensbergen wrote:
> > > > Need to update the documentation for new mount flags
> > > > and cache modes.
> > > > 
> > > > Signed-off-by: Eric Van Hensbergen <ericvh@kernel.org>
> > > > ---
> > > >  Documentation/filesystems/9p.rst | 29 ++++++++++++++++-------------
> > > >  1 file changed, 16 insertions(+), 13 deletions(-)
> > > > 
> > > > diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
> > > > index 0e800b8f73cc..6d257854a02a 100644
> > > > --- a/Documentation/filesystems/9p.rst
> > > > +++ b/Documentation/filesystems/9p.rst
> > > > @@ -78,19 +78,18 @@ Options
> > > >               offering several exported file systems.
> > > > 
> > > >    cache=mode specifies a caching policy.  By default, no caches are used.
> > > > -
> > > > -                        none
> > > > -                             default no cache policy, metadata and data
> > > > -                                alike are synchronous.
> > > > -                     loose
> > > > -                             no attempts are made at consistency,
> > > > -                                intended for exclusive, read-only mounts
> > > > -                        fscache
> > > > -                             use FS-Cache for a persistent, read-only
> > > > -                             cache backend.
> > > > -                        mmap
> > > > -                             minimal cache that is only used for read-write
> > > > -                                mmap.  Northing else is cached, like cache=none
> > > > +             Modes are progressive and inclusive.  For example, specifying fscache
> > > > +             will use loose caches, writeback, and readahead.  Due to their
> > > > +             inclusive nature, only one cache mode can be specified per mount.
> > > 
> > > I would highly recommend to rather specify below for each option "this option
> > > implies writeback, readahead ..." etc., as it is not obvious otherwise which
> > > option would exactly imply what. It is worth those extra few lines IMO to
> > > avoid confusion.
> > > 
> > > > +
> > > > +                     =========       =============================================
> > > > +                     none            no cache of file or metadata
> > > > +                     readahead       readahead caching of files
> > > > +                     writeback       delayed writeback of files
> > > > +                     mmap            support mmap operations read/write with cache
> > > > +                     loose           meta-data and file cache with no coherency
> > > > +                     fscache         use FS-Cache for a persistent cache backend
> > > > +                     =========       =============================================
> > > > 
> > > >    debug=n    specifies debug level.  The debug level is a bitmask.
> > > > 
> > > > @@ -137,6 +136,10 @@ Options
> > > >               This can be used to share devices/named pipes/sockets between
> > > >               hosts.  This functionality will be expanded in later versions.
> > > > 
> > > > +  directio   bypass page cache on all read/write operations
> > > > +
> > > > +  ignoreqv   ignore qid.version==0 as a marker to ignore cache
> > > > +
> > > >    noxattr    do not offer xattr functions on this mount.
> > > > 
> > > >    access     there are four access modes.
> > > > 
> > > 
> > > 
> > > 
> > > 
> > 
> 
> 
> 
> 

-- 
Jeff Layton <jlayton@kernel.org>