filesystems/caching/backend-api.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 FS-Cache Cache backend API
7 The FS-Cache system provides an API by which actual caches can be supplied to
8 FS-Cache for it to then serve out to network filesystems and other interested
11 This API is declared in <linux/fscache-cache.h>.
18 cache the backend wants to make available.  For instance, CacheFS does this in
32    * "ops" is a pointer to the table of operations that the backend supports on
35    * "idfmt" is a format and printf-style arguments for constructing a label
39 The cache should then be registered with FS-Cache by passing a pointer to the
48    * "fsdef" which should point to the object representation for the FS-Cache
50      here.  FS-Cache keeps the caller's reference to the index object if
58 This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
81  (2) that of one of the processes in the FS-Cache thread pool.
88 This is left to the cache to handle; FS-Cache makes no effort in this regard.
94 The cache may present data to the outside world through FS-Cache's interfaces
95 in sysfs and procfs - the former for control and the latter for statistics.
105    * Index/Data file FS-Cache representation cookie::
114      The fields that might be of use to the backend describe the object
121    * In-cache object representation::
135      Structures of this type should be allocated by the cache backend and
136      passed to FS-Cache when requested by the appropriate cache operation.  In
142      using "OBJ%x" to be consistent with FS-Cache.
150    * FS-Cache operation record::
162      FS-Cache has a pool of threads that it uses to give CPU time to the
173    * FS-Cache retrieval operation record::
182      A structure of this type is allocated by FS-Cache to record retrieval and
184      backend to do the operation.  The backend may get extra refs to it by
188      A retrieval operation can be used by the backend to do retrieval work.  To
189      do this, the retrieval->op.processor method pointer should be set
190      appropriately by the backend and fscache_enqueue_retrieval() called to
194      The to_do field is an empty list available for the cache backend to use as
198    * FS-Cache storage operation record::
206      A structure of this type is allocated by FS-Cache to record outstanding
207      writes to be made.  FS-Cache itself enqueues this operation and invokes
215 The cache backend provides FS-Cache with a table of operations that can be
227      the backend.
240      multiple lookup calls to turn it into a more convenient form.  FS-Cache
258      should also be called once a non-present object has been created.
296      object cannot be reclaimed to make space.  Return -ENOSPC if there's not
306      if they're consistent and -ESTALE otherwise.  -ENOMEM and -ERESTARTSYS
314      new information should be in object->cookie->netfs_data.  This can be
315      obtained by calling object->cookie->def->get_aux()/get_attr().
322      This is called to invalidate a data object (as pointed to by op->object).
354      This is called to ask the backend to synchronise a cache with its backing
376      It should also call fscache_set_store_limit() to indicate to FS-Cache the
379      This method may return -ve if an error occurred or the cache object cannot
382      This operation is run asynchronously from FS-Cache's thread pool, and
395      This should return 0 if successful, -ENOSPC if there isn't enough space
396      available, or -ENOMEM or -EIO on other errors.
412      reserve a backing block if not.  FS-Cache will have done as much checking
413      as it can before calling, but most of the work belongs to the backend.
415      If there's no page in the cache, then -ENODATA should be returned if the
416      backend managed to reserve a backing block; -ENOBUFS or -ENOMEM if it
432      The retrieval record may be used to get CPU time via the FS-Cache thread
433      pool.  If this is desired, the op->op.processor should be set to point to
439      If an I/O error occurs, fscache_io_error() should be called and -ENOBUFS
460      If there was an error such as -ENOMEM, then that should be returned; else
461      if one or more pages couldn't be read or allocated, then -ENOBUFS should
462      be returned; else if one or more pages couldn't be read, then -ENODATA
478      If there's no backing block available, then -ENOBUFS should be returned
479      (or -ENOMEM if there were other problems).  If a block is successfully
500      successful read_or_alloc_page() call or similar.  FS-Cache filters out
503      This method is called asynchronously from the FS-Cache thread pool.  It is
504      not required to actually store anything, provided -ENODATA is then
508      otherwise zero should be returned.  FS-Cache will take appropriate action
511      If this method returns success then FS-Cache will inform the netfs
515    * Discard retained per-page metadata [mandatory]::
520      cache backend should tear down any internal representation or tracking it
524 FS-Cache Utilities
527 FS-Cache provides some utilities that a cache backend may make use of:
533      This tells FS-Cache that an I/O error occurred in the cache.  After this
535      release) will be passed from the netfs to the cache backend for the
576      This sets the limit FS-Cache imposes on the highest byte it's willing to
578      rejected by fscache_read_alloc_page() and co with -ENOBUFS.
626      This must be called to inform FS-Cache that an object that belonged to a
636      This is called to indicate to FS-Cache that a lookup process for an object
644      significant - all subsequent calls are ignored.
651      This is called to indicate to FS-Cache that a lookup process for an object
682    * Indicate that the caching backend killed an object::
687      This is called to indicate that the cache backend preemptively killed an
691 	    - the object was stale and needs discarding.
694 	    - there was insufficient cache space
697 	    - the object was retired when relinquished.
700 	    - the object was culled to make space.
716      This enqueues a retrieval record for processing by the FS-Cache thread
718      op->op.processor callback function.  This function may be called from
727      is in into a text string for display purposes.