^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) FS-Cache Network Filesystem API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) There's an API by which a network filesystem can make use of the FS-Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) facilities. This is based around a number of principles:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) (1) Caches can store a number of different object types. There are two main
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) object types: indices and files. The first is a special type used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) FS-Cache to make finding objects faster and to make retiring of groups of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) objects easier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) (2) Every index, file or other object is represented by a cookie. This cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) may or may not have anything associated with it, but the netfs doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) need to care.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) (3) Barring the top-level index (one entry per cached netfs), the index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) hierarchy for each netfs is structured according the whim of the netfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) This API is declared in <linux/fscache.h>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) .. This document contains the following sections:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) (1) Network filesystem definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) (2) Index definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) (3) Object definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) (4) Network filesystem (un)registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) (5) Cache tag lookup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) (6) Index registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) (7) Data file registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) (8) Miscellaneous object registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) (9) Setting the data file size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) (10) Page alloc/read/write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) (11) Page uncaching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) (12) Index and data file consistency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) (13) Cookie enablement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) (14) Miscellaneous cookie operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) (15) Cookie unregistration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) (16) Index invalidation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) (17) Data file invalidation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) (18) FS-Cache specific page flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Network Filesystem Definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) FS-Cache needs a description of the network filesystem. This is specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) using a record of the following structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) struct fscache_netfs {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) uint32_t version;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) struct fscache_cookie *primary_index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) This first two fields should be filled in before registration, and the third
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) will be filled in by the registration function; any other fields should just be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) ignored and are for internal use only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) The fields are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) (1) The name of the netfs (used as the key in the toplevel index).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) (2) The version of the netfs (if the name matches but the version doesn't, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) entire in-cache hierarchy for this netfs will be scrapped and begun
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) afresh).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) (3) The cookie representing the primary index will be allocated according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) another parameter passed into the registration function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) For example, kAFS (linux/fs/afs/) uses the following definitions to describe
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) itself::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) struct fscache_netfs afs_cache_netfs = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) .version = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) .name = "afs",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Index Definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) Indices are used for two purposes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) (1) To aid the finding of a file based on a series of keys (such as AFS's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) "cell", "volume ID", "vnode ID").
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) (2) To make it easier to discard a subset of all the files cached based around
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) a particular key - for instance to mirror the removal of an AFS volume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) However, since it's unlikely that any two netfs's are going to want to define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) their index hierarchies in quite the same way, FS-Cache tries to impose as few
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) restraints as possible on how an index is structured and where it is placed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) the tree. The netfs can even mix indices and data files at the same level, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) it's not recommended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Each index entry consists of a key of indeterminate length plus some auxiliary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) data, also of indeterminate length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) There are some limits on indices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) (1) Any index containing non-index objects should be restricted to a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) cache. Any such objects created within an index will be created in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) first cache only. The cache in which an index is created can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) controlled by cache tags (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) (2) The entry data must be atomically journallable, so it is limited to about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 400 bytes at present. At least 400 bytes will be available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) (3) The depth of the index tree should be judged with care as the search
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) function is recursive. Too many layers will run the kernel out of stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Object Definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) To define an object, a structure of the following type should be filled out::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) struct fscache_cookie_def
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) uint8_t name[16];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) uint8_t type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) struct fscache_cache_tag *(*select_cache)(
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) const void *parent_netfs_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) const void *cookie_netfs_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) const void *data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) uint16_t datalen,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) loff_t object_size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) void (*get_context)(void *cookie_netfs_data, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) void (*put_context)(void *cookie_netfs_data, void *context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) void (*mark_pages_cached)(void *cookie_netfs_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) struct address_space *mapping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) struct pagevec *cached_pvec);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) This has the following fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) (1) The type of the object [mandatory].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) This is one of the following values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) FSCACHE_COOKIE_TYPE_INDEX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) This defines an index, which is a special FS-Cache type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) FSCACHE_COOKIE_TYPE_DATAFILE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) This defines an ordinary data file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Any other value between 2 and 255
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) This defines an extraordinary object such as an XATTR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) (2) The name of the object type (NUL terminated unless all 16 chars are used)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) [optional].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) (3) A function to select the cache in which to store an index [optional].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) This function is invoked when an index needs to be instantiated in a cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) during the instantiation of a non-index object. Only the immediate index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) parent for the non-index object will be queried. Any indices above that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) in the hierarchy may be stored in multiple caches. This function does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) need to be supplied for any non-index object or any index that will only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) have index children.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) If this function is not supplied or if it returns NULL then the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) cache in the parent's list will be chosen, or failing that, the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) cache in the master list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) (4) A function to check the auxiliary data [optional].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) This function will be called to check that a match found in the cache for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) this object is valid. For instance with AFS it could check the auxiliary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) data against the data version number returned by the server to determine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) whether the index entry in a cache is still valid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) If this function is absent, it will be assumed that matching objects in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) cache are always valid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) The function is also passed the cache's idea of the object size and may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) use this to manage coherency also.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) If present, the function should return one of the following values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) FSCACHE_CHECKAUX_OKAY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) - the entry is okay as is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) FSCACHE_CHECKAUX_NEEDS_UPDATE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) - the entry requires update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) FSCACHE_CHECKAUX_OBSOLETE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) - the entry should be deleted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) This function can also be used to extract data from the auxiliary data in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) the cache and copy it into the netfs's structures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) (5) A pair of functions to manage contexts for the completion callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) [optional].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) The cache read/write functions are passed a context which is then passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) to the I/O completion callback function. To ensure this context remains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) valid until after the I/O completion is called, two functions may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) provided: one to get an extra reference on the context, and one to drop a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) reference to it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) If the context is not used or is a type of object that won't go out of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) scope, then these functions are not required. These functions are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) required for indices as indices may not contain data. These functions may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) be called in interrupt context and so may not sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) (6) A function to mark a page as retaining cache metadata [optional].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) This is called by the cache to indicate that it is retaining in-memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) information for this page and that the netfs should uncache the page when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) it has finished. This does not indicate whether there's data on the disk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) or not. Note that several pages at once may be presented for marking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) The PG_fscache bit is set on the pages before this function would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) called, so the function need not be provided if this is sufficient.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) This function is not required for indices as they're not permitted data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) (7) A function to unmark all the pages retaining cache metadata [mandatory].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) This is called by FS-Cache to indicate that a backing store is being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) unbound from a cookie and that all the marks on the pages should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) cleared to prevent confusion. Note that the cache will have torn down all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) its tracking information so that the pages don't need to be explicitly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) uncached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) This function is not required for indices as they're not permitted data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) Network Filesystem (Un)registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) The first step is to declare the network filesystem to the cache. This also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) involves specifying the layout of the primary index (for AFS, this would be the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) "cell" level).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) The registration function is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) int fscache_register_netfs(struct fscache_netfs *netfs);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) It just takes a pointer to the netfs definition. It returns 0 or an error as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) For kAFS, registration is done as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) ret = fscache_register_netfs(&afs_cache_netfs);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) The last step is, of course, unregistration::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) void fscache_unregister_netfs(struct fscache_netfs *netfs);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) Cache Tag Lookup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) FS-Cache permits the use of more than one cache. To permit particular index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) subtrees to be bound to particular caches, the second step is to look up cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) representation tags. This step is optional; it can be left entirely up to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) FS-Cache as to which cache should be used. The problem with doing that is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) FS-Cache will always pick the first cache that was registered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) To get the representation for a named tag::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) This takes a text string as the name and returns a representation of a tag. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) will never return an error. It may return a dummy tag, however, if it runs out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) of memory; this will inhibit caching with this tag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) Any representation so obtained must be released by passing it to this function::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) void fscache_release_cache_tag(struct fscache_cache_tag *tag);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) The tag will be retrieved by FS-Cache when it calls the object definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) operation select_cache().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) Index Registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) The third step is to inform FS-Cache about part of an index hierarchy that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) be used to locate files. This is done by requesting a cookie for each index in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) the path to the file::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) struct fscache_cookie *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) fscache_acquire_cookie(struct fscache_cookie *parent,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) const struct fscache_object_def *def,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) const void *index_key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) size_t index_key_len,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) const void *aux_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) size_t aux_data_len,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) void *netfs_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) loff_t object_size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) bool enable);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) This function creates an index entry in the index represented by parent,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) filling in the index entry by calling the operations pointed to by def.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) A unique key that represents the object within the parent must be pointed to by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) index_key and is of length index_key_len.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) An optional blob of auxiliary data that is to be stored within the cache can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) pointed to with aux_data and should be of length aux_data_len. This would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) typically be used for storing coherency data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) The netfs may pass an arbitrary value in netfs_data and this will be presented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) to it in the event of any calling back. This may also be used in tracing or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) logging of messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) The cache tracks the size of the data attached to an object and this set to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) object_size. For indices, this should be 0. This value will be passed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) ->check_aux() callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) Note that this function never returns an error - all errors are handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) internally. It may, however, return NULL to indicate no cookie. It is quite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) acceptable to pass this token back to this function as the parent to another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) acquisition (or even to the relinquish cookie, read page and write page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) functions - see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) Note also that no indices are actually created in a cache until a non-index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) object needs to be created somewhere down the hierarchy. Furthermore, an index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) may be created in several different caches independently at different times.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) This is all handled transparently, and the netfs doesn't see any of it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) A cookie will be created in the disabled state if enabled is false. A cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) must be enabled to do anything with it. A disabled cookie can be enabled by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) calling fscache_enable_cookie() (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) For example, with AFS, a cell would be added to the primary index. This index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) entry would have a dependent inode containing volume mappings within this cell::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) cell->cache =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) fscache_acquire_cookie(afs_cache_netfs.primary_index,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) &afs_cell_cache_index_def,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) cell->name, strlen(cell->name),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) NULL, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) cell, 0, true);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) And then a particular volume could be added to that index by ID, creating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) another index for vnodes (AFS inode equivalents)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) volume->cache =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) fscache_acquire_cookie(volume->cell->cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) &afs_volume_cache_index_def,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) &volume->vid, sizeof(volume->vid),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) NULL, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) volume, 0, true);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) Data File Registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) The fourth step is to request a data file be created in the cache. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) identical to index cookie acquisition. The only difference is that the type in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) the object definition should be something other than index type::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) vnode->cache =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) fscache_acquire_cookie(volume->cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) &afs_vnode_cache_object_def,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) &key, sizeof(key),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) &aux, sizeof(aux),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) vnode, vnode->status.size, true);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) Miscellaneous Object Registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) An optional step is to request an object of miscellaneous type be created in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) the cache. This is almost identical to index cookie acquisition. The only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) difference is that the type in the object definition should be something other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) than index type. While the parent object could be an index, it's more likely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) it would be some other type of object such as a data file::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) xattr->cache =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) fscache_acquire_cookie(vnode->cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) &afs_xattr_cache_object_def,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) &xattr->name, strlen(xattr->name),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) NULL, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) xattr, strlen(xattr->val), true);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) Miscellaneous objects might be used to store extended attributes or directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) entries for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) Setting the Data File Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) The fifth step is to set the physical attributes of the file, such as its size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) This doesn't automatically reserve any space in the cache, but permits the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) cache to adjust its metadata for data tracking appropriately::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) int fscache_attr_changed(struct fscache_cookie *cookie);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) The cache will return -ENOBUFS if there is no backing cache or if there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) space to allocate any extra metadata required in the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) Note that attempts to read or write data pages in the cache over this size may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) be rebuffed with -ENOBUFS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) This operation schedules an attribute adjustment to happen asynchronously at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) some point in the future, and as such, it may happen after the function returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) to the caller. The attribute adjustment excludes read and write operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) Page alloc/read/write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) And the sixth step is to store and retrieve pages in the cache. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) three functions that are used to do this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) (1) A page should not be re-read or re-allocated without uncaching it first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) (2) A read or allocated page must be uncached when the netfs page is released
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) from the pagecache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) (3) A page should only be written to the cache if previous read or allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) This permits the cache to maintain its page tracking in proper order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) PAGE READ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) Firstly, the netfs should ask FS-Cache to examine the caches and read the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) contents cached for a particular page of a particular file if present, or else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) allocate space to store the contents if not::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) typedef
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) void (*fscache_rw_complete_t)(struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) void *context,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) int error);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) fscache_rw_complete_t end_io_func,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) void *context,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) gfp_t gfp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) The cookie argument must specify a cookie for an object that isn't an index,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) the page specified will have the data loaded into it (and is also used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) specify the page number), and the gfp argument is used to control how any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) memory allocations made are satisfied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) If the cookie indicates the inode is not cached:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) (1) The function will return -ENOBUFS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) Else if there's a copy of the page resident in the cache:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) (1) The mark_pages_cached() cookie operation will be called on that page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) (2) The function will submit a request to read the data from the cache's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) backing device directly into the page specified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) (3) The function will return 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) (4) When the read is complete, end_io_func() will be invoked with:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) * The netfs data supplied when the cookie was created.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) * The page descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) * The context argument passed to the above function. This will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) maintained with the get_context/put_context functions mentioned above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) * An argument that's 0 on success or negative for an error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) If an error occurs, it should be assumed that the page contains no usable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) data. fscache_readpages_cancel() may need to be called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) end_io_func() will be called in process context if the read is results in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) an error, but it might be called in interrupt context if the read is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) successful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) Otherwise, if there's not a copy available in cache, but the cache may be able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) to store the page:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) (1) The mark_pages_cached() cookie operation will be called on that page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) (2) A block may be reserved in the cache and attached to the object at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) appropriate place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) (3) The function will return -ENODATA.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) This function may also return -ENOMEM or -EINTR, in which case it won't have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) read any data from the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) Page Allocate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) Alternatively, if there's not expected to be any data in the cache for a page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) because the file has been extended, a block can simply be allocated instead::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) int fscache_alloc_page(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) gfp_t gfp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) This is similar to the fscache_read_or_alloc_page() function, except that it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) never reads from the cache. It will return 0 if a block has been allocated,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) rather than -ENODATA as the other would. One or the other must be performed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) before writing to the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) The mark_pages_cached() cookie operation will be called on the page if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) successful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) Page Write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) Secondly, if the netfs changes the contents of the page (either due to an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) initial download or if a user performs a write), then the page should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) written back to the cache::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) int fscache_write_page(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) loff_t object_size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) gfp_t gfp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) The cookie argument must specify a data file cookie, the page specified should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) contain the data to be written (and is also used to specify the page number),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) object_size is the revised size of the object and the gfp argument is used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) control how any memory allocations made are satisfied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) The page must have first been read or allocated successfully and must not have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) been uncached before writing is performed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) If the cookie indicates the inode is not cached then:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) (1) The function will return -ENOBUFS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) Else if space can be allocated in the cache to hold this page:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) (1) PG_fscache_write will be set on the page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) (2) The function will submit a request to write the data to cache's backing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) device directly from the page specified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) (3) The function will return 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) (4) When the write is complete PG_fscache_write is cleared on the page and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) anyone waiting for that bit will be woken up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) Else if there's no space available in the cache, -ENOBUFS will be returned. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) is also possible for the PG_fscache_write bit to be cleared when no write took
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) place if unforeseen circumstances arose (such as a disk error).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) Writing takes place asynchronously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) Multiple Page Read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) A facility is provided to read several pages at once, as requested by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) readpages() address space operation::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) struct address_space *mapping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) struct list_head *pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) int *nr_pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) fscache_rw_complete_t end_io_func,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) void *context,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) gfp_t gfp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) This works in a similar way to fscache_read_or_alloc_page(), except:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) (1) Any page it can retrieve data for is removed from pages and nr_pages and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) dispatched for reading to the disk. Reads of adjacent pages on disk may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) be merged for greater efficiency.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) (2) The mark_pages_cached() cookie operation will be called on several pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) at once if they're being read or allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) (3) If there was an general error, then that error will be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) Else if some pages couldn't be allocated or read, then -ENOBUFS will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) Else if some pages couldn't be read but were allocated, then -ENODATA will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) Otherwise, if all pages had reads dispatched, then 0 will be returned, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) list will be empty and ``*nr_pages`` will be 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) (4) end_io_func will be called once for each page being read as the reads
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) complete. It will be called in process context if error != 0, but it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) be called in interrupt context if there is no error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) Note that a return of -ENODATA, -ENOBUFS or any other error does not preclude
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) some of the pages being read and some being allocated. Those pages will have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) been marked appropriately and will need uncaching.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) Cancellation of Unread Pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) If one or more pages are passed to fscache_read_or_alloc_pages() but not then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) read from the cache and also not read from the underlying filesystem then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) those pages will need to have any marks and reservations removed. This can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) done by calling::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) void fscache_readpages_cancel(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) struct list_head *pages);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) prior to returning to the caller. The cookie argument should be as passed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) fscache_read_or_alloc_pages(). Every page in the pages list will be examined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) and any that have PG_fscache set will be uncached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) Page Uncaching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) To uncache a page, this function should be called::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) void fscache_uncache_page(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) struct page *page);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) This function permits the cache to release any in-memory representation it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) might be holding for this netfs page. This function must be called once for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) each page on which the read or write page functions above have been called to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) make sure the cache's in-memory tracking information gets torn down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) Note that pages can't be explicitly deleted from the a data file. The whole
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) data file must be retired (see the relinquish cookie function below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) Furthermore, note that this does not cancel the asynchronous read or write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) operation started by the read/alloc and write functions, so the page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) invalidation functions must use::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) bool fscache_check_page_write(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) struct page *page);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) to see if a page is being written to the cache, and::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) void fscache_wait_on_page_write(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) struct page *page);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) to wait for it to finish if it is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) When releasepage() is being implemented, a special FS-Cache function exists to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) manage the heuristics of coping with vmscan trying to eject pages, which may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) conflict with the cache trying to write pages to the cache (which may itself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) need to allocate memory)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) bool fscache_maybe_release_page(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) gfp_t gfp);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) This takes the netfs cookie, and the page and gfp arguments as supplied to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) releasepage(). It will return false if the page cannot be released yet for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) some reason and if it returns true, the page has been uncached and can now be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) released.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) To make a page available for release, this function may wait for an outstanding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) storage request to complete, or it may attempt to cancel the storage request -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) in which case the page will not be stored in the cache this time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) Bulk Image Page Uncache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) A convenience routine is provided to perform an uncache on all the pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) attached to an inode. This assumes that the pages on the inode correspond on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) 1:1 basis with the pages in the cache::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) struct inode *inode);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) This takes the netfs cookie that the pages were cached with and the inode that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) the pages are attached to. This function will wait for pages to finish being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) written to the cache and for the cache to finish with the page generally. No
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) error is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) Index and Data File consistency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) To find out whether auxiliary data for an object is up to data within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) cache, the following function can be called::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) int fscache_check_consistency(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) const void *aux_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) This will call back to the netfs to check whether the auxiliary data associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) with a cookie is correct; if aux_data is non-NULL, it will update the auxiliary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) data buffer first. It returns 0 if it is and -ESTALE if it isn't; it may also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) return -ENOMEM and -ERESTARTSYS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) To request an update of the index data for an index or other object, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) following function should be called::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) void fscache_update_cookie(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) const void *aux_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) This function will update the cookie's auxiliary data buffer from aux_data if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) that is non-NULL and then schedule this to be stored on disk. The update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) method in the parent index definition will be called to transfer the data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) Note that partial updates may happen automatically at other times, such as when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) data blocks are added to a data file object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) Cookie Enablement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) Cookies exist in one of two states: enabled and disabled. If a cookie is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) disabled, it ignores all attempts to acquire child cookies; check, update or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) invalidate its state; allocate, read or write backing pages - though it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) still possible to uncache pages and relinquish the cookie.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) The initial enablement state is set by fscache_acquire_cookie(), but the cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) can be enabled or disabled later. To disable a cookie, call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) void fscache_disable_cookie(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) const void *aux_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) bool invalidate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) If the cookie is not already disabled, this locks the cookie against other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) enable and disable ops, marks the cookie as being disabled, discards or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) invalidates any backing objects and waits for cessation of activity on any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) associated object before unlocking the cookie.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) All possible failures are handled internally. The caller should consider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) calling fscache_uncache_all_inode_pages() afterwards to make sure all page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) markings are cleared up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) Cookies can be enabled or reenabled with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) void fscache_enable_cookie(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) const void *aux_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) loff_t object_size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) bool (*can_enable)(void *data),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) void *data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) If the cookie is not already enabled, this locks the cookie against other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) enable and disable ops, invokes can_enable() and, if the cookie is not an index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) cookie, will begin the procedure of acquiring backing objects.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) The optional can_enable() function is passed the data argument and returns a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) ruling as to whether or not enablement should actually be permitted to begin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) All possible failures are handled internally. The cookie will only be marked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) as enabled if provisional backing objects are allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) The object's data size is updated from object_size and is passed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) ->check_aux() function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) In both cases, the cookie's auxiliary data buffer is updated from aux_data if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) that is non-NULL inside the enablement lock before proceeding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) Miscellaneous Cookie operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) There are a number of operations that can be used to control cookies:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) * Cookie pinning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) int fscache_pin_cookie(struct fscache_cookie *cookie);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) void fscache_unpin_cookie(struct fscache_cookie *cookie);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) These operations permit data cookies to be pinned into the cache and to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) have the pinning removed. They are not permitted on index cookies.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) The pinning function will return 0 if successful, -ENOBUFS in the cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) isn't backed by a cache, -EOPNOTSUPP if the cache doesn't support pinning,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) -EIO if there's any other problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) * Data space reservation::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) This permits a netfs to request cache space be reserved to store up to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) given amount of a file. It is permitted to ask for more than the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) size of the file to allow for future file expansion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) If size is given as zero then the reservation will be cancelled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) The function will return 0 if successful, -ENOBUFS in the cookie isn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) backed by a cache, -EOPNOTSUPP if the cache doesn't support reservations,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) -ENOSPC if there isn't enough space to honour the operation, -ENOMEM or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) -EIO if there's any other problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) Note that this doesn't pin an object in a cache; it can still be culled to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) make space if it's not in use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) Cookie Unregistration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) To get rid of a cookie, this function should be called::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) void fscache_relinquish_cookie(struct fscache_cookie *cookie,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) const void *aux_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) bool retire);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) If retire is non-zero, then the object will be marked for recycling, and all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) copies of it will be removed from all active caches in which it is present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) Not only that but all child objects will also be retired.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) If retire is zero, then the object may be available again when next the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) acquisition function is called. Retirement here will overrule the pinning on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) cookie.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) The cookie's auxiliary data will be updated from aux_data if that is non-NULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) so that the cache can lazily update it on disk.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) One very important note - relinquish must NOT be called for a cookie unless all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) the cookies for "child" indices, objects and pages have been relinquished
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) Index Invalidation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) There is no direct way to invalidate an index subtree. To do this, the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) should relinquish and retire the cookie they have, and then acquire a new one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) Data File Invalidation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) Sometimes it will be necessary to invalidate an object that contains data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) Typically this will be necessary when the server tells the netfs of a foreign
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) change - at which point the netfs has to throw away all the state it had for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) inode and reload from the server.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) To indicate that a cache object should be invalidated, the following function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) can be called::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) void fscache_invalidate(struct fscache_cookie *cookie);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) This can be called with spinlocks held as it defers the work to a thread pool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) All extant storage, retrieval and attribute change ops at this point are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) cancelled and discarded. Some future operations will be rejected until the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) cache has had a chance to insert a barrier in the operations queue. After
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) that, operations will be queued again behind the invalidation operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) The invalidation operation will perform an attribute change operation and an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) auxiliary data update operation as it is very likely these will have changed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) Using the following function, the netfs can wait for the invalidation operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) to have reached a point at which it can start submitting ordinary operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) once again::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) void fscache_wait_on_invalidate(struct fscache_cookie *cookie);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) FS-cache Specific Page Flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) FS-Cache makes use of a page flag, PG_private_2, for its own purpose. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) given the alternative name PG_fscache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) PG_fscache is used to indicate that the page is known by the cache, and that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) the cache must be informed if the page is going to go away. It's an indication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) to the netfs that the cache has an interest in this page, where an interest may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) be a pointer to it, resources allocated or reserved for it, or I/O in progress
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) upon it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) The netfs can use this information in methods such as releasepage() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) determine whether it needs to uncache a page or update it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) Furthermore, if this bit is set, releasepage() and invalidatepage() operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) will be called on a page to get rid of it, even if PG_private is not set. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) allows caching to attempted on a page before read_cache_pages() to be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) after fscache_read_or_alloc_pages() as the former will try and release pages it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) was given under certain circumstances.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) This bit does not overlap with such as PG_private. This means that FS-Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) can be used with a filesystem that uses the block buffering code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) There are a number of operations defined on this flag::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) int PageFsCache(struct page *page);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) void SetPageFsCache(struct page *page)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) void ClearPageFsCache(struct page *page)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) int TestSetPageFsCache(struct page *page)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) int TestClearPageFsCache(struct page *page)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) These functions are bit test, bit set, bit clear, bit test and set and bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) test and clear operations on PG_fscache.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags