^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 Cache backend 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) The FS-Cache system provides an API by which actual caches can be supplied to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) FS-Cache for it to then serve out to network filesystems and other interested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) parties.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This API is declared in <linux/fscache-cache.h>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Initialising and Registering a Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) To start off, a cache definition must be initialised and registered for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) cache the backend wants to make available. For instance, CacheFS does this in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) the fill_super() operation on mounting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) The cache definition (struct fscache_cache) should be initialised by calling::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) void fscache_init_cache(struct fscache_cache *cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) struct fscache_cache_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) const char *idfmt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Where:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) * "cache" is a pointer to the cache definition;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) * "ops" is a pointer to the table of operations that the backend supports on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) this cache; and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) * "idfmt" is a format and printf-style arguments for constructing a label
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) for the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) The cache should then be registered with FS-Cache by passing a pointer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) previously initialised cache definition to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) int fscache_add_cache(struct fscache_cache *cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) struct fscache_object *fsdef,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) const char *tagname);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Two extra arguments should also be supplied:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) * "fsdef" which should point to the object representation for the FS-Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) master index in this cache. Netfs primary index entries will be created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) here. FS-Cache keeps the caller's reference to the index object if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) successful and will release it upon withdrawal of the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) * "tagname" which, if given, should be a text string naming this cache. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) this is NULL, the identifier will be used instead. For CacheFS, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) identifier is set to name the underlying block device and the tag can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) supplied by mount.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) is already in use. 0 will be returned on success.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Unregistering a Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) A cache can be withdrawn from the system by calling this function with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) pointer to the cache definition::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) void fscache_withdraw_cache(struct fscache_cache *cache);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) In CacheFS's case, this is called by put_super().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) Security
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The cache methods are executed one of two contexts:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) (1) that of the userspace process that issued the netfs operation that caused
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) the cache method to be invoked, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) (2) that of one of the processes in the FS-Cache thread pool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) In either case, this may not be an appropriate context in which to access the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) The calling process's fsuid, fsgid and SELinux security identities may need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) be masqueraded for the duration of the cache driver's access to the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) This is left to the cache to handle; FS-Cache makes no effort in this regard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Control and Statistics Presentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) The cache may present data to the outside world through FS-Cache's interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) in sysfs and procfs - the former for control and the latter for statistics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) A sysfs directory called /sys/fs/fscache/<cachetag>/ is created if CONFIG_SYSFS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) is enabled. This is accessible through the kobject struct fscache_cache::kobj
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) and is for use by the cache as it sees fit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Relevant Data Structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) * Index/Data file FS-Cache representation cookie::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) struct fscache_cookie {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) struct fscache_object_def *def;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) struct fscache_netfs *netfs;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) void *netfs_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) The fields that might be of use to the backend describe the object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) definition, the netfs definition and the netfs's data for this cookie.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) The object definition contain functions supplied by the netfs for loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) and matching index entries; these are required to provide some of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) cache operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) * In-cache object representation::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) struct fscache_object {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) int debug_id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) enum {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) FSCACHE_OBJECT_RECYCLING,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) } state;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) spinlock_t lock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) struct fscache_cache *cache;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) struct fscache_cookie *cookie;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Structures of this type should be allocated by the cache backend and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) passed to FS-Cache when requested by the appropriate cache operation. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) the case of CacheFS, they're embedded in CacheFS's internal object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) structures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) The debug_id is a simple integer that can be used in debugging messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) that refer to a particular object. In such a case it should be printed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) using "OBJ%x" to be consistent with FS-Cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Each object contains a pointer to the cookie that represents the object it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) is backing. An object should retired when put_object() is called if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) in state FSCACHE_OBJECT_RECYCLING. The fscache_object struct should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) initialised by calling fscache_object_init(object).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) * FS-Cache operation record::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) struct fscache_operation {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) atomic_t usage;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) struct fscache_object *object;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) unsigned long flags;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) #define FSCACHE_OP_EXCLUSIVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) void (*processor)(struct fscache_operation *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) void (*release)(struct fscache_operation *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) FS-Cache has a pool of threads that it uses to give CPU time to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) various asynchronous operations that need to be done as part of driving
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) the cache. These are represented by the above structure. The processor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) method is called to give the op CPU time, and the release method to get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) rid of it when its usage count reaches 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) An operation can be made exclusive upon an object by setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) appropriate flag before enqueuing it with fscache_enqueue_operation(). If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) an operation needs more processing time, it should be enqueued again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) * FS-Cache retrieval operation record::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) struct fscache_retrieval {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) struct fscache_operation op;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) struct address_space *mapping;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) struct list_head *to_do;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) A structure of this type is allocated by FS-Cache to record retrieval and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) allocation requests made by the netfs. This struct is then passed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) backend to do the operation. The backend may get extra refs to it by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) calling fscache_get_retrieval() and refs may be discarded by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) fscache_put_retrieval().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) A retrieval operation can be used by the backend to do retrieval work. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) do this, the retrieval->op.processor method pointer should be set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) appropriately by the backend and fscache_enqueue_retrieval() called to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) submit it to the thread pool. CacheFiles, for example, uses this to queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) page examination when it detects PG_lock being cleared.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) The to_do field is an empty list available for the cache backend to use as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) it sees fit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) * FS-Cache storage operation record::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) struct fscache_storage {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) struct fscache_operation op;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) pgoff_t store_limit;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) A structure of this type is allocated by FS-Cache to record outstanding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) writes to be made. FS-Cache itself enqueues this operation and invokes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) the write_page() method on the object at appropriate times to effect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) storage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) Cache Operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) The cache backend provides FS-Cache with a table of operations that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) performed on the denizens of the cache. These are held in a structure of type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) struct fscache_cache_ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) * Name of cache provider [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) const char *name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) This isn't strictly an operation, but should be pointed at a string naming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) the backend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) * Allocate a new object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) struct fscache_cookie *cookie)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) This method is used to allocate a cache object representation to back a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) cookie in a particular cache. fscache_object_init() should be called on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) the object to initialise it prior to returning.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) This function may also be used to parse the index key to be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) multiple lookup calls to turn it into a more convenient form. FS-Cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) will call the lookup_complete() method to allow the cache to release the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) form once lookup is complete or aborted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) * Look up and create object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) void (*lookup_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) This method is used to look up an object, given that the object is already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) allocated and attached to the cookie. This should instantiate that object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) in the cache if it can.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) The method should call fscache_object_lookup_negative() as soon as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) possible if it determines the object doesn't exist in the cache. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) object is found to exist and the netfs indicates that it is valid then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) fscache_obtained_object() should be called once the object is in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) position to have data stored in it. Similarly, fscache_obtained_object()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) should also be called once a non-present object has been created.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) If a lookup error occurs, fscache_object_lookup_error() should be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) to abort the lookup of that object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) * Release lookup data [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) void (*lookup_complete)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) This method is called to ask the cache to release any resources it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) using to perform a lookup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) * Increment object refcount [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) struct fscache_object *(*grab_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) This method is called to increment the reference count on an object. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) may fail (for instance if the cache is being withdrawn) by returning NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) It should return the object pointer if successful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) * Lock/Unlock object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) void (*lock_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) void (*unlock_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) These methods are used to exclusively lock an object. It must be possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) to schedule with the lock held, so a spinlock isn't sufficient.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) * Pin/Unpin object [optional]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) int (*pin_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) void (*unpin_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) These methods are used to pin an object into the cache. Once pinned an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) object cannot be reclaimed to make space. Return -ENOSPC if there's not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) enough space in the cache to permit this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) * Check coherency state of an object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) int (*check_consistency)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) This method is called to have the cache check the saved auxiliary data of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) the object against the netfs's idea of the state. 0 should be returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) if they're consistent and -ESTALE otherwise. -ENOMEM and -ERESTARTSYS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) may also be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) * Update object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) int (*update_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) This is called to update the index entry for the specified object. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) new information should be in object->cookie->netfs_data. This can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) obtained by calling object->cookie->def->get_aux()/get_attr().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) * Invalidate data object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) int (*invalidate_object)(struct fscache_operation *op)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) This is called to invalidate a data object (as pointed to by op->object).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) All the data stored for this object should be discarded and an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) attr_changed operation should be performed. The caller will follow up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) with an object update operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) fscache_op_complete() must be called on op before returning.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) * Discard object [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) void (*drop_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) This method is called to indicate that an object has been unbound from its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) cookie, and that the cache should release the object's resources and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) retire it if it's in state FSCACHE_OBJECT_RECYCLING.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) This method should not attempt to release any references held by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) caller. The caller will invoke the put_object() method as appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) * Release object reference [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) void (*put_object)(struct fscache_object *object)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) This method is used to discard a reference to an object. The object may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) be freed when all the references to it are released.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) * Synchronise a cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) void (*sync)(struct fscache_cache *cache)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) This is called to ask the backend to synchronise a cache with its backing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) * Dissociate a cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) void (*dissociate_pages)(struct fscache_cache *cache)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) This is called to ask a cache to perform any page dissociations as part of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) cache withdrawal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) * Notification that the attributes on a netfs file changed [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) int (*attr_changed)(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) This is called to indicate to the cache that certain attributes on a netfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) file have changed (for example the maximum size a file may reach). The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) cache can read these from the netfs by calling the cookie's get_attr()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) method.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) The cache may use the file size information to reserve space on the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) It should also call fscache_set_store_limit() to indicate to FS-Cache the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) highest byte it's willing to store for an object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) This method may return -ve if an error occurred or the cache object cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) be expanded. In such a case, the object will be withdrawn from service.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) This operation is run asynchronously from FS-Cache's thread pool, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) storage and retrieval operations from the netfs are excluded during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) execution of this operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) * Reserve cache space for an object's data [optional]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) int (*reserve_space)(struct fscache_object *object, loff_t size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) This is called to request that cache space be reserved to hold the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) for an object and the metadata used to track it. Zero size should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) taken as request to cancel a reservation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) This should return 0 if successful, -ENOSPC if there isn't enough space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) available, or -ENOMEM or -EIO on other errors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) The reservation may exceed the current size of the object, thus permitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) future expansion. If the amount of space consumed by an object would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) exceed the reservation, it's permitted to refuse requests to allocate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) pages, but not required. An object may be pruned down to its reservation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) size if larger than that already.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) * Request page be read from cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) int (*read_or_alloc_page)(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) gfp_t gfp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) This is called to attempt to read a netfs page from the cache, or to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) reserve a backing block if not. FS-Cache will have done as much checking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) as it can before calling, but most of the work belongs to the backend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) If there's no page in the cache, then -ENODATA should be returned if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) backend managed to reserve a backing block; -ENOBUFS or -ENOMEM if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) didn't.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) If there is suitable data in the cache, then a read operation should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) queued and 0 returned. When the read finishes, fscache_end_io() should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) The fscache_mark_pages_cached() should be called for the page if any cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) metadata is retained. This will indicate to the netfs that the page needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) explicit uncaching. This operation takes a pagevec, thus allowing several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) pages to be marked at once.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) The retrieval record pointed to by op should be retained for each page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) queued and released when I/O on the page has been formally ended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) fscache_get/put_retrieval() are available for this purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) The retrieval record may be used to get CPU time via the FS-Cache thread
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) pool. If this is desired, the op->op.processor should be set to point to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) the appropriate processing routine, and fscache_enqueue_retrieval() should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) be called at an appropriate point to request CPU time. For instance, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) retrieval routine could be enqueued upon the completion of a disk read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) The to_do field in the retrieval record is provided to aid in this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) returned if possible or fscache_end_io() called with a suitable error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) fscache_put_retrieval() should be called after a page or pages are dealt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) with. This will complete the operation when all pages are dealt with.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) * Request pages be read from cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) int (*read_or_alloc_pages)(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) struct list_head *pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) unsigned *nr_pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) gfp_t gfp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) This is like the read_or_alloc_page() method, except it is handed a list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) of pages instead of one page. Any pages on which a read operation is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) started must be added to the page cache for the specified mapping and also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) to the LRU. Such pages must also be removed from the pages list and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) ``*nr_pages`` decremented per page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) If there was an error such as -ENOMEM, then that should be returned; else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) if one or more pages couldn't be read or allocated, then -ENOBUFS should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) be returned; else if one or more pages couldn't be read, then -ENODATA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) should be returned. If all the pages are dispatched then 0 should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) * Request page be allocated in the cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) int (*allocate_page)(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) gfp_t gfp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) This is like the read_or_alloc_page() method, except that it shouldn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) read from the cache, even if there's data there that could be retrieved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) It should, however, set up any internal metadata required such that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) the write_page() method can write to the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) If there's no backing block available, then -ENOBUFS should be returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) (or -ENOMEM if there were other problems). If a block is successfully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) allocated, then the netfs page should be marked and 0 returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) * Request pages be allocated in the cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) int (*allocate_pages)(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) struct list_head *pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) unsigned *nr_pages,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) gfp_t gfp)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) This is an multiple page version of the allocate_page() method. pages and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) nr_pages should be treated as for the read_or_alloc_pages() method.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) * Request page be written to cache [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) int (*write_page)(struct fscache_storage *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) struct page *page);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) This is called to write from a page on which there was a previously
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) successful read_or_alloc_page() call or similar. FS-Cache filters out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) pages that don't have mappings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) This method is called asynchronously from the FS-Cache thread pool. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) not required to actually store anything, provided -ENODATA is then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) returned to the next read of this page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) If an error occurred, then a negative error code should be returned,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) otherwise zero should be returned. FS-Cache will take appropriate action
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) in response to an error, such as withdrawing this object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) If this method returns success then FS-Cache will inform the netfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) appropriately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) * Discard retained per-page metadata [mandatory]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) void (*uncache_page)(struct fscache_object *object, struct page *page)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) This is called when a netfs page is being evicted from the pagecache. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) cache backend should tear down any internal representation or tracking it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) maintains for this page.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) FS-Cache Utilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) FS-Cache provides some utilities that a cache backend may make use of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) * Note occurrence of an I/O error in a cache::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) void fscache_io_error(struct fscache_cache *cache)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) This tells FS-Cache that an I/O error occurred in the cache. After this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) has been called, only resource dissociation operations (object and page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) release) will be passed from the netfs to the cache backend for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) specified cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) This does not actually withdraw the cache. That must be done separately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) * Invoke the retrieval I/O completion function::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) void fscache_end_io(struct fscache_retrieval *op, struct page *page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) int error);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) This is called to note the end of an attempt to retrieve a page. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) error value should be 0 if successful and an error otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) * Record that one or more pages being retrieved or allocated have been dealt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) void fscache_retrieval_complete(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) int n_pages);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) This is called to record the fact that one or more pages have been dealt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) with and are no longer the concern of this operation. When the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) pages remaining in the operation reaches 0, the operation will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) completed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) * Record operation completion::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) void fscache_op_complete(struct fscache_operation *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) This is called to record the completion of an operation. This deducts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) this operation from the parent object's run state, potentially permitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) one or more pending operations to start running.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) * Set highest store limit::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) void fscache_set_store_limit(struct fscache_object *object,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) loff_t i_size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) This sets the limit FS-Cache imposes on the highest byte it's willing to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) try and store for a netfs. Any page over this limit is automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) rejected by fscache_read_alloc_page() and co with -ENOBUFS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) * Mark pages as being cached::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) void fscache_mark_pages_cached(struct fscache_retrieval *op,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) struct pagevec *pagevec);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) This marks a set of pages as being cached. After this has been called,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) the netfs must call fscache_uncache_page() to unmark the pages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) * Perform coherency check on an object::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) const void *data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) uint16_t datalen);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) This asks the netfs to perform a coherency check on an object that has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) just been looked up. The cookie attached to the object will determine the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) netfs to use. data and datalen should specify where the auxiliary data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) retrieved from the cache can be found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) One of three values will be returned:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) FSCACHE_CHECKAUX_OKAY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) The coherency data indicates the object is valid as is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) FSCACHE_CHECKAUX_NEEDS_UPDATE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) The coherency data needs updating, but otherwise the object is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) valid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) FSCACHE_CHECKAUX_OBSOLETE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) The coherency data indicates that the object is obsolete and should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) be discarded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) * Initialise a freshly allocated object::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) void fscache_object_init(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) This initialises all the fields in an object representation.
^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) * Indicate the destruction of an object::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) void fscache_object_destroyed(struct fscache_cache *cache);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) This must be called to inform FS-Cache that an object that belonged to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) cache has been destroyed and deallocated. This will allow continuation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) of the cache withdrawal process when it is stopped pending destruction of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) all the objects.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) * Indicate negative lookup on an object::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) void fscache_object_lookup_negative(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) This is called to indicate to FS-Cache that a lookup process for an object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) found a negative result.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) This changes the state of an object to permit reads pending on lookup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) completion to go off and start fetching data from the netfs server as it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) known at this point that there can't be any data in the cache.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) This may be called multiple times on an object. Only the first call is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) significant - all subsequent calls are ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) * Indicate an object has been obtained::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) void fscache_obtained_object(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) This is called to indicate to FS-Cache that a lookup process for an object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) produced a positive result, or that an object was created. This should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) only be called once for any particular object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) This changes the state of an object to indicate:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) (1) if no call to fscache_object_lookup_negative() has been made on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) this object, that there may be data available, and that reads can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) now go and look for it; and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) (2) that writes may now proceed against this object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) * Indicate that object lookup failed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) void fscache_object_lookup_error(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) This marks an object as having encountered a fatal error (usually EIO)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) and causes it to move into a state whereby it will be withdrawn as soon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) * Indicate that a stale object was found and discarded::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) void fscache_object_retrying_stale(struct fscache_object *object);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) This is called to indicate that the lookup procedure found an object in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) the cache that the netfs decided was stale. The object has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) discarded from the cache and the lookup will be performed again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) * Indicate that the caching backend killed an object::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) void fscache_object_mark_killed(struct fscache_object *object,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) enum fscache_why_object_killed why);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) This is called to indicate that the cache backend preemptively killed an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) object. The why parameter should be set to indicate the reason:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) FSCACHE_OBJECT_IS_STALE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) - the object was stale and needs discarding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) FSCACHE_OBJECT_NO_SPACE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) - there was insufficient cache space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) FSCACHE_OBJECT_WAS_RETIRED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) - the object was retired when relinquished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) FSCACHE_OBJECT_WAS_CULLED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) - the object was culled to make space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) * Get and release references on a retrieval record::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) void fscache_get_retrieval(struct fscache_retrieval *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) void fscache_put_retrieval(struct fscache_retrieval *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) These two functions are used to retain a retrieval record while doing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) asynchronous data retrieval and block allocation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) * Enqueue a retrieval record for processing::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) void fscache_enqueue_retrieval(struct fscache_retrieval *op);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) This enqueues a retrieval record for processing by the FS-Cache thread
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) pool. One of the threads in the pool will invoke the retrieval record's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) op->op.processor callback function. This function may be called from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) within the callback function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) * List of object state names::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) const char *fscache_object_states[];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) For debugging purposes, this may be used to turn the state that an object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) is in into a text string for display purposes.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags