docs: filesystems: caching/netfs-api.txt: convert it to ReST

The netfs API to FS-Cache can be found in:

	Documentation/filesystems/caching/netfs-api.txt

	Documentation/filesystems/caching/netfs-api.rst

The cache backend API to FS-Cache can be found in:

   fscache

   object

   netfs-api

.. SPDX-License-Identifier: GPL-2.0

===============================

			FS-CACHE NETWORK FILESYSTEM API

FS-Cache Network Filesystem API

===============================

There's an API by which a network filesystem can make use of the FS-Cache

This API is declared in <linux/fscache.h>.

This document contains the following sections:

.. This document contains the following sections:

	 (1) Network filesystem definition

	 (2) Index definition

	(18) FS-Cache specific page flags.

=============================

NETWORK FILESYSTEM DEFINITION

Network Filesystem Definition

=============================

FS-Cache needs a description of the network filesystem.  This is specified

using a record of the following structure:

using a record of the following structure::

	struct fscache_netfs {

		uint32_t			version;

     another parameter passed into the registration function.

For example, kAFS (linux/fs/afs/) uses the following definitions to describe

itself:

itself::

	struct fscache_netfs afs_cache_netfs = {

		.version	= 0,

	};

================

INDEX DEFINITION

Index Definition

================

Indices are used for two purposes:

     function is recursive.  Too many layers will run the kernel out of stack.

=================

OBJECT DEFINITION

Object Definition

=================

To define an object, a structure of the following type should be filled out:

To define an object, a structure of the following type should be filled out::

	struct fscache_cookie_def

	{

     This is one of the following values:

	(*) FSCACHE_COOKIE_TYPE_INDEX

	FSCACHE_COOKIE_TYPE_INDEX

	    This defines an index, which is a special FS-Cache type.

	(*) FSCACHE_COOKIE_TYPE_DATAFILE

	FSCACHE_COOKIE_TYPE_DATAFILE

	    This defines an ordinary data file.

	(*) Any other value between 2 and 255

	Any other value between 2 and 255

	    This defines an extraordinary object such as an XATTR.

 (2) The name of the object type (NUL terminated unless all 16 chars are used)

     If present, the function should return one of the following values:

	(*) FSCACHE_CHECKAUX_OKAY		- the entry is okay as is

	(*) FSCACHE_CHECKAUX_NEEDS_UPDATE	- the entry requires update

	(*) FSCACHE_CHECKAUX_OBSOLETE		- the entry should be deleted

	FSCACHE_CHECKAUX_OKAY

	    - the entry is okay as is

	FSCACHE_CHECKAUX_NEEDS_UPDATE

	    - the entry requires update

	FSCACHE_CHECKAUX_OBSOLETE

	    - the entry should be deleted

     This function can also be used to extract data from the auxiliary data in

     the cache and copy it into the netfs's structures.

     This function is not required for indices as they're not permitted data.

===================================

NETWORK FILESYSTEM (UN)REGISTRATION

Network Filesystem (Un)registration

===================================

The first step is to declare the network filesystem to the cache.  This also

involves specifying the layout of the primary index (for AFS, this would be the

"cell" level).

The registration function is:

The registration function is::

	int fscache_register_netfs(struct fscache_netfs *netfs);

It just takes a pointer to the netfs definition.  It returns 0 or an error as

appropriate.

For kAFS, registration is done as follows:

For kAFS, registration is done as follows::

	ret = fscache_register_netfs(&afs_cache_netfs);

The last step is, of course, unregistration:

The last step is, of course, unregistration::

	void fscache_unregister_netfs(struct fscache_netfs *netfs);

================

CACHE TAG LOOKUP

Cache Tag Lookup

================

FS-Cache permits the use of more than one cache.  To permit particular index

FS-Cache as to which cache should be used.  The problem with doing that is that

FS-Cache will always pick the first cache that was registered.

To get the representation for a named tag:

To get the representation for a named tag::

	struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name);

will never return an error.  It may return a dummy tag, however, if it runs out

of memory; this will inhibit caching with this tag.

Any representation so obtained must be released by passing it to this function:

Any representation so obtained must be released by passing it to this function::

	void fscache_release_cache_tag(struct fscache_cache_tag *tag);

operation select_cache().

==================

INDEX REGISTRATION

Index Registration

==================

The third step is to inform FS-Cache about part of an index hierarchy that can

be used to locate files.  This is done by requesting a cookie for each index in

the path to the file:

the path to the file::

	struct fscache_cookie *

	fscache_acquire_cookie(struct fscache_cookie *parent,

calling fscache_enable_cookie() (see below).

For example, with AFS, a cell would be added to the primary index.  This index

entry would have a dependent inode containing volume mappings within this cell:

entry would have a dependent inode containing volume mappings within this cell::

	cell->cache =

		fscache_acquire_cookie(afs_cache_netfs.primary_index,

				       cell, 0, true);

And then a particular volume could be added to that index by ID, creating

another index for vnodes (AFS inode equivalents):

another index for vnodes (AFS inode equivalents)::

	volume->cache =

		fscache_acquire_cookie(volume->cell->cache,

				       volume, 0, true);

======================

DATA FILE REGISTRATION

Data File Registration

======================

The fourth step is to request a data file be created in the cache.  This is

identical to index cookie acquisition.  The only difference is that the type in

the object definition should be something other than index type.

the object definition should be something other than index type::

	vnode->cache =

		fscache_acquire_cookie(volume->cache,

				       vnode, vnode->status.size, true);

=================================

MISCELLANEOUS OBJECT REGISTRATION

Miscellaneous Object Registration

=================================

An optional step is to request an object of miscellaneous type be created in

the cache.  This is almost identical to index cookie acquisition.  The only

difference is that the type in the object definition should be something other

than index type.  While the parent object could be an index, it's more likely

it would be some other type of object such as a data file.

it would be some other type of object such as a data file::

	xattr->cache =

		fscache_acquire_cookie(vnode->cache,

entries for example.

==========================

SETTING THE DATA FILE SIZE

Setting the Data File Size

==========================

The fifth step is to set the physical attributes of the file, such as its size.

This doesn't automatically reserve any space in the cache, but permits the

cache to adjust its metadata for data tracking appropriately:

cache to adjust its metadata for data tracking appropriately::

	int fscache_attr_changed(struct fscache_cookie *cookie);

to the caller.  The attribute adjustment excludes read and write operations.

=====================

PAGE ALLOC/READ/WRITE

Page alloc/read/write

=====================

And the sixth step is to store and retrieve pages in the cache.  There are

Firstly, the netfs should ask FS-Cache to examine the caches and read the

contents cached for a particular page of a particular file if present, or else

allocate space to store the contents if not:

allocate space to store the contents if not::

	typedef

	void (*fscache_rw_complete_t)(struct page *page,

 (4) When the read is complete, end_io_func() will be invoked with:

     (*) The netfs data supplied when the cookie was created.

       * The netfs data supplied when the cookie was created.

     (*) The page descriptor.

       * The page descriptor.

     (*) The context argument passed to the above function.  This will be

       * The context argument passed to the above function.  This will be

         maintained with the get_context/put_context functions mentioned above.

     (*) An argument that's 0 on success or negative for an error code.

       * An argument that's 0 on success or negative for an error code.

     If an error occurs, it should be assumed that the page contains no usable

     data.  fscache_readpages_cancel() may need to be called.

read any data from the cache.

PAGE ALLOCATE

Page Allocate

-------------

Alternatively, if there's not expected to be any data in the cache for a page

because the file has been extended, a block can simply be allocated instead:

because the file has been extended, a block can simply be allocated instead::

	int fscache_alloc_page(struct fscache_cookie *cookie,

			       struct page *page,

successful.

PAGE WRITE

Page Write

----------

Secondly, if the netfs changes the contents of the page (either due to an

initial download or if a user performs a write), then the page should be

written back to the cache:

written back to the cache::

	int fscache_write_page(struct fscache_cookie *cookie,

			       struct page *page,

Writing takes place asynchronously.

MULTIPLE PAGE READ

Multiple Page Read

------------------

A facility is provided to read several pages at once, as requested by the

readpages() address space operation:

readpages() address space operation::

	int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,

					struct address_space *mapping,

     be returned.

     Otherwise, if all pages had reads dispatched, then 0 will be returned, the

     list will be empty and *nr_pages will be 0.

     list will be empty and ``*nr_pages`` will be 0.

 (4) end_io_func will be called once for each page being read as the reads

     complete.  It will be called in process context if error != 0, but it may

been marked appropriately and will need uncaching.

CANCELLATION OF UNREAD PAGES

Cancellation of Unread Pages

----------------------------

If one or more pages are passed to fscache_read_or_alloc_pages() but not then

read from the cache and also not read from the underlying filesystem then

those pages will need to have any marks and reservations removed.  This can be

done by calling:

done by calling::

	void fscache_readpages_cancel(struct fscache_cookie *cookie,

				      struct list_head *pages);

and any that have PG_fscache set will be uncached.

==============

PAGE UNCACHING

Page Uncaching

==============

To uncache a page, this function should be called:

To uncache a page, this function should be called::

	void fscache_uncache_page(struct fscache_cookie *cookie,

				  struct page *page);

Furthermore, note that this does not cancel the asynchronous read or write

operation started by the read/alloc and write functions, so the page

invalidation functions must use:

invalidation functions must use::

	bool fscache_check_page_write(struct fscache_cookie *cookie,

				      struct page *page);

to see if a page is being written to the cache, and:

to see if a page is being written to the cache, and::

	void fscache_wait_on_page_write(struct fscache_cookie *cookie,

					struct page *page);

When releasepage() is being implemented, a special FS-Cache function exists to

manage the heuristics of coping with vmscan trying to eject pages, which may

conflict with the cache trying to write pages to the cache (which may itself

need to allocate memory):

need to allocate memory)::

	bool fscache_maybe_release_page(struct fscache_cookie *cookie,

					struct page *page,

in which case the page will not be stored in the cache this time.

BULK INODE PAGE UNCACHE

Bulk Image Page Uncache

-----------------------

A convenience routine is provided to perform an uncache on all the pages

attached to an inode.  This assumes that the pages on the inode correspond on a

1:1 basis with the pages in the cache.

1:1 basis with the pages in the cache::

	void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,

					     struct inode *inode);

error is returned.

===============================

INDEX AND DATA FILE CONSISTENCY

Index and Data File consistency

===============================

To find out whether auxiliary data for an object is up to data within the

cache, the following function can be called:

cache, the following function can be called::

	int fscache_check_consistency(struct fscache_cookie *cookie,

				      const void *aux_data);

return -ENOMEM and -ERESTARTSYS.

To request an update of the index data for an index or other object, the

following function should be called:

following function should be called::

	void fscache_update_cookie(struct fscache_cookie *cookie,

				   const void *aux_data);

data blocks are added to a data file object.

=================

COOKIE ENABLEMENT

Cookie Enablement

=================

Cookies exist in one of two states: enabled and disabled.  If a cookie is

still possible to uncache pages and relinquish the cookie.

The initial enablement state is set by fscache_acquire_cookie(), but the cookie

can be enabled or disabled later.  To disable a cookie, call:

can be enabled or disabled later.  To disable a cookie, call::

	void fscache_disable_cookie(struct fscache_cookie *cookie,

				    const void *aux_data,

calling fscache_uncache_all_inode_pages() afterwards to make sure all page

markings are cleared up.

Cookies can be enabled or reenabled with:

Cookies can be enabled or reenabled with::

    	void fscache_enable_cookie(struct fscache_cookie *cookie,

				   const void *aux_data,

that is non-NULL inside the enablement lock before proceeding.

===============================

MISCELLANEOUS COOKIE OPERATIONS

Miscellaneous Cookie operations

===============================

There are a number of operations that can be used to control cookies:

 (*) Cookie pinning:

     * Cookie pinning::

	int fscache_pin_cookie(struct fscache_cookie *cookie);

	void fscache_unpin_cookie(struct fscache_cookie *cookie);

     -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or

     -EIO if there's any other problem.

 (*) Data space reservation:

   * Data space reservation::

	int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);

     make space if it's not in use.

=====================

COOKIE UNREGISTRATION

Cookie Unregistration

=====================

To get rid of a cookie, this function should be called.

To get rid of a cookie, this function should be called::

	void fscache_relinquish_cookie(struct fscache_cookie *cookie,

				       const void *aux_data,

first.

==================

INDEX INVALIDATION

Index Invalidation

==================

There is no direct way to invalidate an index subtree.  To do this, the caller

should relinquish and retire the cookie they have, and then acquire a new one.

======================

DATA FILE INVALIDATION

Data File Invalidation

======================

Sometimes it will be necessary to invalidate an object that contains data.

inode and reload from the server.

To indicate that a cache object should be invalidated, the following function

can be called:

can be called::

	void fscache_invalidate(struct fscache_cookie *cookie);

Using the following function, the netfs can wait for the invalidation operation

to have reached a point at which it can start submitting ordinary operations

once again:

once again::

	void fscache_wait_on_invalidate(struct fscache_cookie *cookie);

===========================

FS-CACHE SPECIFIC PAGE FLAG

FS-cache Specific Page Flag

===========================

FS-Cache makes use of a page flag, PG_private_2, for its own purpose.  This is

This bit does not overlap with such as PG_private.  This means that FS-Cache

can be used with a filesystem that uses the block buffering code.

There are a number of operations defined on this flag:

There are a number of operations defined on this flag::

	int PageFsCache(struct page *page);

	void SetPageFsCache(struct page *page)

 * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.

 * Written by David Howells (dhowells@redhat.com)

 *

 * See Documentation/filesystems/caching/netfs-api.txt for more information on

 * See Documentation/filesystems/caching/netfs-api.rst for more information on

 * the netfs API.

 */

 *

 * NOTE!!! See:

 *

 *	Documentation/filesystems/caching/netfs-api.txt

 *	Documentation/filesystems/caching/netfs-api.rst

 *

 * for a description of the network filesystem interface declared here.

 */

 *

 * Register a filesystem as desiring caching services if they're available.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Indicate that a filesystem no longer desires caching services for the

 * moment.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Acquire a specific cache referral tag that can be used to select a specific

 * cache in which to cache an index.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * Release a reference to a cache referral tag previously looked up.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * that can be used to locate files.  This is done by requesting a cookie for

 * each index in the path to the file.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * provided to update the auxiliary data in the cache before the object is

 * disconnected.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * cookie.  The auxiliary data on the cookie will be updated first if @aux_data

 * is set.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * Permit data-storage cache objects to be pinned in the cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * Permit data-storage cache objects to be unpinned from the cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * changed.  This includes the data size.  These attributes will be obtained

 * through the get_attr() cookie definition op.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * This can be called with spinlocks held.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * Wait for the invalidation of an object to complete.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * cookie so that a write to that object within the space can always be

 * honoured.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Else, if the page is unbacked, -ENODATA is returned and a block may have

 * been allocated in the cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * regard to different pages, the return values are prioritised in that order.

 * Any pages submitted for reading are removed from the pages list.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Else, a block will be allocated if one wasn't already, and 0 will be

 * returned

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * be cleared at the completion of the write to indicate the success or failure

 * of the operation.  Note that the completion may happen before the return.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Note that this cannot cancel any outstanding I/O operations between this

 * page and the cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 *

 * Ask the cache if a page is being written to the cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline

 * Ask the cache to wake us up when a page is no longer being written to the

 * cache.

 *

 * See Documentation/filesystems/caching/netfs-api.txt for a complete

 * See Documentation/filesystems/caching/netfs-api.rst for a complete

 * description.

 */

static inline