Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <d5048f3d-fe17-72f8-0d61-a5ec5a1a9f43@infradead.org>
Date:   Sat, 1 Apr 2023 18:32:42 -0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.9.0
Subject: Re: [PATCH] fs/9p: Rework cache modes and add new options to
 Documentation
Content-Language: en-US
To:     Eric Van Hensbergen <ericvh@kernel.org>,
        Latchesar Ionkov <lucho@ionkov.net>,
        Dominique Martinet <asmadeus@codewreck.org>,
        Christian Schoenebeck <linux_oss@crudebyte.com>,
        v9fs@lists.linux.dev
Cc:     v9fs-developer@lists.sourceforge.net, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
References: <20230401-ericvh-dev-rework-cache-options-v1-1-12d3adbdd33a@kernel.org>
From:   Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <20230401-ericvh-dev-rework-cache-options-v1-1-12d3adbdd33a@kernel.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

Hi--

On 4/1/23 16:16, Eric Van Hensbergen wrote:
> diff --git a/Documentation/filesystems/9p.rst b/Documentation/filesystems/9p.rst
> index 0e800b8f73cc..d79bf4e41a71 100644
> --- a/Documentation/filesystems/9p.rst
> +++ b/Documentation/filesystems/9p.rst
> @@ -78,19 +78,39 @@ 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
> +		The mode can be specified as a bitmask or by using one of the
> +		prexisting common 'shortcuts'.
> +		The bitmask is described below: (unspecified bits are reserved)
> +
> +			==========	================================================
> +			0b00000000	all caches disabled, mmap disabled
> +			0b00000001	file caches enabled
> +			0b00000010	meta-data caches enabled
> +			0b00000100	writeback behavior (as opposed to writethrough)
> +			0b00001000	loose caches (no explicit consistency with server)
> +			0b10000000	fscache enabled for persistent caching
> +			=========	================================================
> +

Extend the === lines to that no text extends beyond the last '=' character,
both above and below.
Otherwise there will be warnings.

> +		The current shortcuts and their associated bitmask are:
> +
> +			=========	=============================================
> +			none		0b00000000 (no caching)
> +			readahead	0b00000001 (only read-ahead file caching)
> +			mmap		0b00000101 (read-ahead + writeback file cache)
> +			loose		0b00001111 (non-coherent file and meta-data caches)
> +			fscache		0b10001111 (persistent loose cache)
> +			=========	=============================================
> +
> +		NOTE: only these shortcuts are tested modes of operation at the
> +		moment, so using other combinations of bit-patterns is not
> +		known to work.  Work on better cache support is in progress.
> +
> +		IMPORTANT: loose caches (and by extension at the moment fscache)
> +		do not necessarily validate cached values on the server.  In other
> +		words changes on the server are not guaranteed to be reflected
> +		on the client system.  Only use this mode of operation if you
> +		have an exclusive mount and the server will modify the filesystem
> +		underneath you.
>  
>    debug=n	specifies debug level.  The debug level is a bitmask.
>  
> @@ -137,6 +157,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.

-- 
~Randy