public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-08-05 16:54:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/caching/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/cfe4cb1bf8e1f0093d44c30801ec42e74721e543.1588021877.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2020-04-27 23:16:55 +02:00 • committed by Jonathan Corbet
parent fd299b2a73
commit efc930fa1d
5 changed files with 103 additions and 116 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Documentation/filesystems/caching/fscache.rst
View file

@ -183,7 +183,7 @@ reside in one cache.
The netfs API to FS-Cache can be found in: 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: The cache backend API to FS-Cache can be found in:

1
Documentation/filesystems/caching/index.rst
View file

@ -8,3 +8,4 @@ Filesystem Caching
fscache fscache
object object
netfs-api

168
Documentation/filesystems/caching/netfs-api.txt → Documentation/filesystems/caching/netfs-api.rst
View file

@ -1,5 +1,7 @@
.. 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 There's an API by which a network filesystem can make use of the FS-Cache
@ -19,7 +21,7 @@ facilities. This is based around a number of principles:
This API is declared in <linux/fscache.h>. This API is declared in <linux/fscache.h>.
This document contains the following sections: .. This document contains the following sections:
(1) Network filesystem definition (1) Network filesystem definition
(2) Index definition (2) Index definition
@ -41,12 +43,11 @@ This document contains the following sections:
(18) FS-Cache specific page flags. (18) FS-Cache specific page flags.
============================= Network Filesystem Definition
NETWORK FILESYSTEM DEFINITION
============================= =============================
FS-Cache needs a description of the network filesystem. This is specified 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 { struct fscache_netfs {
uint32_t version; uint32_t version;
@ -71,7 +72,7 @@ The fields are:
another parameter passed into the registration function. another parameter passed into the registration function.
For example, kAFS (linux/fs/afs/) uses the following definitions to describe For example, kAFS (linux/fs/afs/) uses the following definitions to describe
itself: itself::
struct fscache_netfs afs_cache_netfs = { struct fscache_netfs afs_cache_netfs = {
.version = 0, .version = 0,
@ -79,8 +80,7 @@ itself:
}; };
================ Index Definition
INDEX DEFINITION
================ ================
Indices are used for two purposes: Indices are used for two purposes:
@ -114,11 +114,10 @@ There are some limits on indices:
function is recursive. Too many layers will run the kernel out of stack. 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 struct fscache_cookie_def
{ {
@ -149,16 +148,13 @@ This has the following fields:
This is one of the following values: 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. 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. 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. This defines an extraordinary object such as an XATTR.
(2) The name of the object type (NUL terminated unless all 16 chars are used) (2) The name of the object type (NUL terminated unless all 16 chars are used)
@ -192,9 +188,14 @@ This has the following fields:
If present, the function should return one of the following values: If present, the function should return one of the following values:
(*) FSCACHE_CHECKAUX_OKAY - the entry is okay as is FSCACHE_CHECKAUX_OKAY
(*) FSCACHE_CHECKAUX_NEEDS_UPDATE - the entry requires update - the entry is okay as is
(*) FSCACHE_CHECKAUX_OBSOLETE - the entry should be deleted
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 This function can also be used to extract data from the auxiliary data in
the cache and copy it into the netfs's structures. the cache and copy it into the netfs's structures.
@ -236,32 +237,30 @@ This has the following fields:
This function is not required for indices as they're not permitted data. 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 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 involves specifying the layout of the primary index (for AFS, this would be the
"cell" level). "cell" level).
The registration function is: The registration function is::
int fscache_register_netfs(struct fscache_netfs *netfs); int fscache_register_netfs(struct fscache_netfs *netfs);
It just takes a pointer to the netfs definition. It returns 0 or an error as It just takes a pointer to the netfs definition. It returns 0 or an error as
appropriate. appropriate.
For kAFS, registration is done as follows: For kAFS, registration is done as follows::
ret = fscache_register_netfs(&afs_cache_netfs); 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); 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 permits the use of more than one cache. To permit particular index
@ -270,7 +269,7 @@ representation tags. This step is optional; it can be left entirely up to
FS-Cache as to which cache should be used. The problem with doing that is that 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. 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); struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name);
@ -278,7 +277,7 @@ This takes a text string as the name and returns a representation of a tag. It
will never return an error. It may return a dummy tag, however, if it runs out 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. 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); void fscache_release_cache_tag(struct fscache_cache_tag *tag);
@ -286,13 +285,12 @@ The tag will be retrieved by FS-Cache when it calls the object definition
operation select_cache(). operation select_cache().
================== Index Registration
INDEX REGISTRATION
================== ==================
The third step is to inform FS-Cache about part of an index hierarchy that can 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 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 * struct fscache_cookie *
fscache_acquire_cookie(struct fscache_cookie *parent, fscache_acquire_cookie(struct fscache_cookie *parent,
@ -339,7 +337,7 @@ must be enabled to do anything with it. A disabled cookie can be enabled by
calling fscache_enable_cookie() (see below). calling fscache_enable_cookie() (see below).
For example, with AFS, a cell would be added to the primary index. This index 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 = cell->cache =
fscache_acquire_cookie(afs_cache_netfs.primary_index, fscache_acquire_cookie(afs_cache_netfs.primary_index,
@ -349,7 +347,7 @@ entry would have a dependent inode containing volume mappings within this cell:
cell, 0, true); cell, 0, true);
And then a particular volume could be added to that index by ID, creating 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 = volume->cache =
fscache_acquire_cookie(volume->cell->cache, fscache_acquire_cookie(volume->cell->cache,
@ -359,13 +357,12 @@ another index for vnodes (AFS inode equivalents):
volume, 0, true); 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 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 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 = vnode->cache =
fscache_acquire_cookie(volume->cache, fscache_acquire_cookie(volume->cache,
@ -375,15 +372,14 @@ the object definition should be something other than index type.
vnode, vnode->status.size, true); 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 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 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 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 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 = xattr->cache =
fscache_acquire_cookie(vnode->cache, fscache_acquire_cookie(vnode->cache,
@ -396,13 +392,12 @@ Miscellaneous objects might be used to store extended attributes or directory
entries for example. 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. 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 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); int fscache_attr_changed(struct fscache_cookie *cookie);
@ -417,8 +412,7 @@ some point in the future, and as such, it may happen after the function returns
to the caller. The attribute adjustment excludes read and write operations. 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 And the sixth step is to store and retrieve pages in the cache. There are
@ -441,7 +435,7 @@ PAGE READ
Firstly, the netfs should ask FS-Cache to examine the caches and read the 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 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 typedef
void (*fscache_rw_complete_t)(struct page *page, void (*fscache_rw_complete_t)(struct page *page,
@ -474,14 +468,14 @@ Else if there's a copy of the page resident in the cache:
(4) When the read is complete, end_io_func() will be invoked with: (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. 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 If an error occurs, it should be assumed that the page contains no usable
data. fscache_readpages_cancel() may need to be called. data. fscache_readpages_cancel() may need to be called.
@ -504,11 +498,11 @@ This function may also return -ENOMEM or -EINTR, in which case it won't have
read any data from the cache. 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 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, int fscache_alloc_page(struct fscache_cookie *cookie,
struct page *page, struct page *page,
@ -523,12 +517,12 @@ The mark_pages_cached() cookie operation will be called on the page if
successful. successful.
PAGE WRITE Page Write
---------- ----------
Secondly, if the netfs changes the contents of the page (either due to an 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 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, int fscache_write_page(struct fscache_cookie *cookie,
struct page *page, struct page *page,
@ -566,11 +560,11 @@ place if unforeseen circumstances arose (such as a disk error).
Writing takes place asynchronously. Writing takes place asynchronously.
MULTIPLE PAGE READ Multiple Page Read
------------------ ------------------
A facility is provided to read several pages at once, as requested by the 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, int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
struct address_space *mapping, struct address_space *mapping,
@ -598,7 +592,7 @@ This works in a similar way to fscache_read_or_alloc_page(), except:
be returned. be returned.
Otherwise, if all pages had reads dispatched, then 0 will be returned, the 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 (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 complete. It will be called in process context if error != 0, but it may
@ -609,13 +603,13 @@ some of the pages being read and some being allocated. Those pages will have
been marked appropriately and will need uncaching. 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 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 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 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, void fscache_readpages_cancel(struct fscache_cookie *cookie,
struct list_head *pages); struct list_head *pages);
@ -625,11 +619,10 @@ fscache_read_or_alloc_pages(). Every page in the pages list will be examined
and any that have PG_fscache set will be uncached. 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, void fscache_uncache_page(struct fscache_cookie *cookie,
struct page *page); struct page *page);
@ -644,12 +637,12 @@ data file must be retired (see the relinquish cookie function below).
Furthermore, note that this does not cancel the asynchronous read or write Furthermore, note that this does not cancel the asynchronous read or write
operation started by the read/alloc and write functions, so the page 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, bool fscache_check_page_write(struct fscache_cookie *cookie,
struct page *page); 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, void fscache_wait_on_page_write(struct fscache_cookie *cookie,
struct page *page); struct page *page);
@ -660,7 +653,7 @@ to wait for it to finish if it is.
When releasepage() is being implemented, a special FS-Cache function exists to 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 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 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, bool fscache_maybe_release_page(struct fscache_cookie *cookie,
struct page *page, struct page *page,
@ -676,12 +669,12 @@ storage request to complete, or it may attempt to cancel the storage request -
in which case the page will not be stored in the cache this time. 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 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 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, void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
struct inode *inode); struct inode *inode);
@ -692,12 +685,11 @@ written to the cache and for the cache to finish with the page generally. No
error is returned. 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 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, int fscache_check_consistency(struct fscache_cookie *cookie,
const void *aux_data); const void *aux_data);
@ -708,7 +700,7 @@ data buffer first. It returns 0 if it is and -ESTALE if it isn't; it may also
return -ENOMEM and -ERESTARTSYS. return -ENOMEM and -ERESTARTSYS.
To request an update of the index data for an index or other object, the 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, void fscache_update_cookie(struct fscache_cookie *cookie,
const void *aux_data); const void *aux_data);
@ -721,8 +713,7 @@ Note that partial updates may happen automatically at other times, such as when
data blocks are added to a data file object. 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 Cookies exist in one of two states: enabled and disabled. If a cookie is
@ -731,7 +722,7 @@ invalidate its state; allocate, read or write backing pages - though it is
still possible to uncache pages and relinquish the cookie. still possible to uncache pages and relinquish the cookie.
The initial enablement state is set by fscache_acquire_cookie(), but 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, void fscache_disable_cookie(struct fscache_cookie *cookie,
const void *aux_data, const void *aux_data,
@ -746,7 +737,7 @@ All possible failures are handled internally. The caller should consider
calling fscache_uncache_all_inode_pages() afterwards to make sure all page calling fscache_uncache_all_inode_pages() afterwards to make sure all page
markings are cleared up. 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, void fscache_enable_cookie(struct fscache_cookie *cookie,
const void *aux_data, const void *aux_data,
@ -771,13 +762,12 @@ In both cases, the cookie's auxiliary data buffer is updated from aux_data if
that is non-NULL inside the enablement lock before proceeding. 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: 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); int fscache_pin_cookie(struct fscache_cookie *cookie);
void fscache_unpin_cookie(struct fscache_cookie *cookie); void fscache_unpin_cookie(struct fscache_cookie *cookie);
@ -790,7 +780,7 @@ There are a number of operations that can be used to control cookies:
-ENOSPC if there isn't enough space to honour the operation, -ENOMEM or -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
-EIO if there's any other problem. -EIO if there's any other problem.
(*) Data space reservation: * Data space reservation::
int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size); int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
@ -809,11 +799,10 @@ There are a number of operations that can be used to control cookies:
make space if it's not in use. 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, void fscache_relinquish_cookie(struct fscache_cookie *cookie,
const void *aux_data, const void *aux_data,
@ -835,16 +824,14 @@ the cookies for "child" indices, objects and pages have been relinquished
first. first.
================== Index Invalidation
INDEX INVALIDATION
================== ==================
There is no direct way to invalidate an index subtree. To do this, the caller 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. 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. Sometimes it will be necessary to invalidate an object that contains data.
@ -853,7 +840,7 @@ change - at which point the netfs has to throw away all the state it had for an
inode and reload from the server. inode and reload from the server.
To indicate that a cache object should be invalidated, the following function 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); void fscache_invalidate(struct fscache_cookie *cookie);
@ -868,13 +855,12 @@ auxiliary data update operation as it is very likely these will have changed.
Using the following function, the netfs can wait for the invalidation operation 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 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); 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 FS-Cache makes use of a page flag, PG_private_2, for its own purpose. This is
@ -898,7 +884,7 @@ was given under certain circumstances.
This bit does not overlap with such as PG_private. This means that FS-Cache 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. 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); int PageFsCache(struct page *page);
void SetPageFsCache(struct page *page) void SetPageFsCache(struct page *page)

2
fs/fscache/cookie.c
View file

@ -4,7 +4,7 @@
* Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved. * Copyright (C) 2004-2007 Red Hat, Inc. All Rights Reserved.
* Written by David Howells (dhowells@redhat.com) * 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. * the netfs API.
*/ */

42
include/linux/fscache.h
View file

@ -6,7 +6,7 @@
* *
* NOTE!!! See: * NOTE!!! See:
* *
* Documentation/filesystems/caching/netfs-api.txt * Documentation/filesystems/caching/netfs-api.rst
* *
* for a description of the network filesystem interface declared here. * for a description of the network filesystem interface declared here.
*/ */
@ -233,7 +233,7 @@ extern void __fscache_enable_cookie(struct fscache_cookie *, const void *, loff_
* *
* Register a filesystem as desiring caching services if they're available. * 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. * description.
*/ */
static inline static inline
@ -253,7 +253,7 @@ int fscache_register_netfs(struct fscache_netfs *netfs)
* Indicate that a filesystem no longer desires caching services for the * Indicate that a filesystem no longer desires caching services for the
* moment. * moment.
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline
@ -270,7 +270,7 @@ void fscache_unregister_netfs(struct fscache_netfs *netfs)
* Acquire a specific cache referral tag that can be used to select a specific * Acquire a specific cache referral tag that can be used to select a specific
* cache in which to cache an index. * 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. * description.
*/ */
static inline static inline
@ -288,7 +288,7 @@ struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
* *
* Release a reference to a cache referral tag previously looked up. * 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. * description.
*/ */
static inline static inline
@ -315,7 +315,7 @@ void fscache_release_cache_tag(struct fscache_cache_tag *tag)
* that can be used to locate files. This is done by requesting a cookie for * that can be used to locate files. This is done by requesting a cookie for
* each index in the path to the file. * 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. * description.
*/ */
static inline static inline
@ -351,7 +351,7 @@ struct fscache_cookie *fscache_acquire_cookie(
* provided to update the auxiliary data in the cache before the object is * provided to update the auxiliary data in the cache before the object is
* disconnected. * disconnected.
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline
@ -394,7 +394,7 @@ int fscache_check_consistency(struct fscache_cookie *cookie,
* cookie. The auxiliary data on the cookie will be updated first if @aux_data * cookie. The auxiliary data on the cookie will be updated first if @aux_data
* is set. * is set.
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline
@ -410,7 +410,7 @@ void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data)
* *
* Permit data-storage cache objects to be pinned in the cache. * 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. * description.
*/ */
static inline static inline
@ -425,7 +425,7 @@ int fscache_pin_cookie(struct fscache_cookie *cookie)
* *
* Permit data-storage cache objects to be unpinned from the cache. * 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. * description.
*/ */
static inline static inline
@ -441,7 +441,7 @@ void fscache_unpin_cookie(struct fscache_cookie *cookie)
* changed. This includes the data size. These attributes will be obtained * changed. This includes the data size. These attributes will be obtained
* through the get_attr() cookie definition op. * 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. * description.
*/ */
static inline static inline
@ -463,7 +463,7 @@ int fscache_attr_changed(struct fscache_cookie *cookie)
* *
* This can be called with spinlocks held. * 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. * description.
*/ */
static inline static inline
@ -479,7 +479,7 @@ void fscache_invalidate(struct fscache_cookie *cookie)
* *
* Wait for the invalidation of an object to complete. * 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. * description.
*/ */
static inline static inline
@ -498,7 +498,7 @@ void fscache_wait_on_invalidate(struct fscache_cookie *cookie)
* cookie so that a write to that object within the space can always be * cookie so that a write to that object within the space can always be
* honoured. * honoured.
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline
@ -533,7 +533,7 @@ int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
* Else, if the page is unbacked, -ENODATA is returned and a block may have * Else, if the page is unbacked, -ENODATA is returned and a block may have
* been allocated in the cache. * 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. * description.
*/ */
static inline static inline
@ -582,7 +582,7 @@ int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
* regard to different pages, the return values are prioritised in that order. * regard to different pages, the return values are prioritised in that order.
* Any pages submitted for reading are removed from the pages list. * 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. * description.
*/ */
static inline static inline
@ -617,7 +617,7 @@ int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
* Else, a block will be allocated if one wasn't already, and 0 will be * Else, a block will be allocated if one wasn't already, and 0 will be
* returned * returned
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline
@ -667,7 +667,7 @@ void fscache_readpages_cancel(struct fscache_cookie *cookie,
* be cleared at the completion of the write to indicate the success or failure * 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. * 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. * description.
*/ */
static inline static inline
@ -693,7 +693,7 @@ int fscache_write_page(struct fscache_cookie *cookie,
* Note that this cannot cancel any outstanding I/O operations between this * Note that this cannot cancel any outstanding I/O operations between this
* page and the cache. * 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. * description.
*/ */
static inline static inline
@ -711,7 +711,7 @@ void fscache_uncache_page(struct fscache_cookie *cookie,
* *
* Ask the cache if a page is being written to the cache. * 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. * description.
*/ */
static inline static inline
@ -731,7 +731,7 @@ bool fscache_check_page_write(struct fscache_cookie *cookie,
* Ask the cache to wake us up when a page is no longer being written to the * Ask the cache to wake us up when a page is no longer being written to the
* cache. * cache.
* *
* See Documentation/filesystems/caching/netfs-api.txt for a complete * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description. * description.
*/ */
static inline static inline