Documentation/filesystems/caching/backend-api.txt

   1                           ==========================
   2                           FS-CACHE CACHE BACKEND API
   3                           ==========================
   4
   5 The FS-Cache system provides an API by which actual caches can be supplied to
   6 FS-Cache for it to then serve out to network filesystems and other interested
   7 parties.
   8
   9 This API is declared in <linux/fscache-cache.h>.
  10
  11
  12 ====================================
  13 INITIALISING AND REGISTERING A CACHE
  14 ====================================
  15
  16 To start off, a cache definition must be initialised and registered for each
  17 cache the backend wants to make available.  For instance, CacheFS does this in
  18 the fill_super() operation on mounting.
  19
  20 The cache definition (struct fscache_cache) should be initialised by calling:
  21
  22         void fscache_init_cache(struct fscache_cache *cache,
  23                                 struct fscache_cache_ops *ops,
  24                                 const char *idfmt,
  25                                 ...)
  26
  27 Where:
  28
  29  (*) "cache" is a pointer to the cache definition;
  30
  31  (*) "ops" is a pointer to the table of operations that the backend supports on
  32      this cache;
  33
  34  (*) and a format and printf-style arguments for constructing a label for the
  35      cache.
  36
  37
  38 The cache should then be registered with FS-Cache by passing a pointer to the
  39 previously initialised cache definition to:
  40
  41         int fscache_add_cache(struct fscache_cache *cache,
  42                               struct fscache_object *fsdef,
  43                               const char *tagname);
  44
  45 Two extra arguments should also be supplied:
  46
  47  (*) "fsdef" which should point to the object representation for the FS-Cache
  48      master index in this cache.  Netfs primary index entries will be created
  49      here.
  50
  51  (*) "tagname" which, if given, should be a text string naming this cache.  If
  52      this is NULL, the identifier will be used instead.  For CacheFS, the
  53      identifier is set to name the underlying block device and the tag can be
  54      supplied by mount.
  55
  56 This function may return -ENOMEM if it ran out of memory or -EEXIST if the tag
  57 is already in use.  0 will be returned on success.
  58
  59
  60 =====================
  61 UNREGISTERING A CACHE
  62 =====================
  63
  64 A cache can be withdrawn from the system by calling this function with a
  65 pointer to the cache definition:
  66
  67         void fscache_withdraw_cache(struct fscache_cache *cache)
  68
  69 In CacheFS's case, this is called by put_super().
  70
  71
  72 ==================
  73 FS-CACHE UTILITIES
  74 ==================
  75
  76 FS-Cache provides some utilities that a cache backend may make use of:
  77
  78  (*) Find the parent of an object:
  79
  80         struct fscache_object *
  81         fscache_find_parent_object(struct fscache_object *object)
  82
  83      This allows a backend to find the logical parent of an index or data file
  84      in the cache hierarchy.
  85
  86  (*) Note occurrence of an I/O error in a cache:
  87
  88         void fscache_io_error(struct fscache_cache *cache)
  89
  90      This tells FS-Cache that an I/O error occurred in the cache.  After this
  91      has been called, only resource dissociation operations (object and page
  92      release) will be passed from the netfs to the cache backend for the
  93      specified cache.
  94
  95      This does not actually withdraw the cache.  That must be done separately.
  96
  97  (*) Get an extra reference to a read or write context:
  98
  99         void *fscache_get_context(struct fscache_cookie *cookie, void *context)
 100
 101      and release a reference:
 102
 103         void *fscache_put_context(struct fscache_cookie *cookie, void *context)
 104
 105      These should be used to maintain the presence of the read or write context
 106      passed to the cache read/write functions.  This context must then be
 107      passed to the I/O completion function.
 108
 109
 110 ========================
 111 RELEVANT DATA STRUCTURES
 112 ========================
 113
 114  (*) Index/Data file FS-Cache representation cookie:
 115
 116         struct fscache_cookie {
 117                 struct fscache_object_def       *def;
 118                 struct fscache_netfs            *netfs;
 119                 void                            *netfs_data;
 120                 ...
 121         };
 122
 123      The fields that might be of use to the backend describe the object
 124      definition, the netfs definition and the netfs's data for this cookie.
 125      The object definition contain functions supplied by the netfs for loading
 126      and matching index entries; these are required to provide some of the
 127      cache operations.
 128
 129  (*) In-cache object representation:
 130
 131         struct fscache_object {
 132                 struct fscache_cache            *cache;
 133                 struct fscache_cookie           *cookie;
 134                 unsigned long                   flags;
 135         #define FSCACHE_OBJECT_RECYCLING        1
 136                 ...
 137         };
 138
 139      Structures of this type should be allocated by the cache backend and
 140      passed to FS-Cache when requested by the appropriate cache operation.  In
 141      the case of CacheFS, they're embedded in CacheFS's internal object
 142      structures.
 143
 144      Each object contains a pointer to the cookie that represents the object it
 145      is backing.  It also contains a flag that indicates whether the object is
 146      being retired when put_object() is called.  This should be initialised by
 147      calling fscache_object_init(object).
 148
 149
 150 ================
 151 CACHE OPERATIONS
 152 ================
 153
 154 The cache backend provides FS-Cache with a table of operations that can be
 155 performed on the denizens of the cache.  These are held in a structure of type:
 156
 157         struct fscache_cache_ops
 158
 159  (*) Name of cache provider [mandatory]:
 160
 161         const char *name
 162
 163      This isn't strictly an operation, but should be pointed at a string naming
 164      the backend.
 165
 166  (*) Object lookup [mandatory]:
 167
 168         struct fscache_object *(*lookup_object)(struct fscache_cache *cache,
 169                                                 struct fscache_object *parent,
 170                                                 struct fscache_cookie *cookie)
 171
 172      This method is used to look up an object in the specified cache, given a
 173      pointer to the parent object and the cookie to which the object will be
 174      attached.  This should instantiate that object in the cache if it can, or
 175      return -ENOBUFS or -ENOMEM if it can't.
 176
 177  (*) Increment object refcount [mandatory]:
 178
 179         struct fscache_object *(*grab_object)(struct fscache_object *object)
 180
 181      This method is called to increment the reference count on an object.  It
 182      may fail (for instance if the cache is being withdrawn) by returning NULL.
 183      It should return the object pointer if successful.
 184
 185  (*) Lock/Unlock object [mandatory]:
 186
 187         void (*lock_object)(struct fscache_object *object)
 188         void (*unlock_object)(struct fscache_object *object)
 189
 190      These methods are used to exclusively lock an object.  It must be possible
 191      to schedule with the lock held, so a spinlock isn't sufficient.
 192
 193  (*) Pin/Unpin object [optional]:
 194
 195         int (*pin_object)(struct fscache_object *object)
 196         void (*unpin_object)(struct fscache_object *object)
 197
 198      These methods are used to pin an object into the cache.  Once pinned an
 199      object cannot be reclaimed to make space.  Return -ENOSPC if there's not
 200      enough space in the cache to permit this.
 201
 202  (*) Update object [mandatory]:
 203
 204         int (*update_object)(struct fscache_object *object)
 205
 206      This is called to update the index entry for the specified object.  The
 207      new information should be in object->cookie->netfs_data.  This can be
 208      obtained by calling object->cookie->def->get_aux()/get_attr().
 209
 210  (*) Release object reference [mandatory]:
 211
 212         void (*put_object)(struct fscache_object *object)
 213
 214      This method is used to discard a reference to an object.  The object may
 215      be destroyed when all the references held by FS-Cache are released.
 216
 217  (*) Synchronise a cache [mandatory]:
 218
 219         void (*sync)(struct fscache_cache *cache)
 220
 221      This is called to ask the backend to synchronise a cache with its backing
 222      device.
 223
 224  (*) Dissociate a cache [mandatory]:
 225
 226         void (*dissociate_pages)(struct fscache_cache *cache)
 227
 228      This is called to ask a cache to perform any page dissociations as part of
 229      cache withdrawal.
 230
 231  (*) Set the data size on a cache file [mandatory]:
 232
 233         int (*set_i_size)(struct fscache_object *object, loff_t i_size);
 234
 235      This is called to indicate to the cache the maximum size a file may reach.
 236      The cache may use this to reserve space on the cache.  It may also return
 237      -ENOBUFS to indicate that insufficient space is available to expand the
 238      metadata used to track the data.  It should return 0 if successful or
 239      -ENOMEM or -EIO on error.
 240
 241  (*) Reserve cache space for an object's data [optional]:
 242
 243         int (*reserve_space)(struct fscache_object *object, loff_t size);
 244
 245      This is called to request that cache space be reserved to hold the data
 246      for an object and the metadata used to track it.  Zero size should be
 247      taken as request to cancel a reservation.
 248
 249      This should return 0 if successful, -ENOSPC if there isn't enough space
 250      available, or -ENOMEM or -EIO on other errors.
 251
 252      The reservation may exceed the size of the object, thus permitting future
 253      expansion.  If the amount of space consumed by an object would exceed the
 254      reservation, it's permitted to refuse requests to allocate pages, but not
 255      required.  An object may be pruned down to its reservation size if larger
 256      than that already.
 257
 258  (*) Request page be read from cache [mandatory]:
 259
 260         int (*read_or_alloc_page)(struct fscache_object *object,
 261                                   struct page *page,
 262                                   fscache_rw_complete_t end_io_func,
 263                                   void *end_io_data,
 264                                   gfp_t gfp)
 265
 266      This is called to attempt to read a netfs page from the cache, or to
 267      reserve a backing block if not.  FS-Cache will have done as much checking
 268      as it can before calling, but most of the work belongs to the backend.
 269
 270      If there's no page in the cache, then -ENODATA should be returned if the
 271      backend managed to reserve a backing block; -ENOBUFS, -ENOMEM or -EIO if
 272      it didn't.
 273
 274      If there is a page in the cache, then a read operation should be queued
 275      and 0 returned.  When the read finishes, end_io_func() should be called
 276      with the following arguments:
 277
 278         (*end_io_func)(object->cookie->netfs_data,
 279                        page,
 280                        end_io_data,
 281                        error);
 282
 283      The mark_pages_cached() cookie operation should be called for the page if
 284      any cache metadata is retained.  This will indicate to the netfs that the
 285      page needs explicit uncaching.  This operation takes a pagevec, thus
 286      allowing several pages to be marked at once.
 287
 288  (*) Request pages be read from cache [mandatory]:
 289
 290         int (*read_or_alloc_pages)(struct fscache_object *object,
 291                                    struct address_space *mapping,
 292                                    struct list_head *pages,
 293                                    unsigned *nr_pages,
 294                                    fscache_rw_complete_t end_io_func,
 295                                    void *end_io_data,
 296                                    gfp_t gfp)
 297
 298      This is like the previous operation, except it will be handed a list of
 299      pages instead of one page.  Any pages on which a read operation is started
 300      must be added to the page cache for the specified mapping and also to the
 301      LRU.  Such pages must also be removed from the pages list and nr_pages
 302      decremented per page.
 303
 304      If there was an error such as -ENOMEM, then that should be returned; else
 305      if one or more pages couldn't be read or allocated, then -ENOBUFS should
 306      be returned; else if one or more pages couldn't be read, then -ENODATA
 307      should be returned.  If all the pages are dispatched then 0 should be
 308      returned.
 309
 310  (*) Request page be allocated in the cache [mandatory]:
 311
 312         int (*allocate_page)(struct fscache_object *object,
 313                              struct page *page,
 314                              gfp_t gfp)
 315
 316      This is like read_or_alloc_page(), except that it shouldn't read from the
 317      cache, even if there's data there that could be retrieved.  It should,
 318      however, set up any internal metadata required such that write_page() can
 319      write to the cache.
 320
 321      If there's no backing block available, then -ENOBUFS should be returned
 322      (or -ENOMEM or -EIO if there were other problems).  If a block is
 323      successfully allocated, then the netfs page should be marked and 0
 324      returned.
 325
 326  (*) Request page be written to cache [mandatory]:
 327
 328         int (*write_page)(struct fscache_object *object,
 329                           struct page *page,
 330                           fscache_rw_complete_t end_io_func,
 331                           void *end_io_data,
 332                           gfp_t gfp)
 333
 334      This is called to write from a page on which there was a previously
 335      successful read_or_alloc_page() call.  FS-Cache filters out pages that
 336      don't have mappings.
 337
 338      If there's no backing block available, then -ENOBUFS should be returned
 339      (or -ENOMEM or -EIO if there were other problems).
 340
 341      If the write operation could be queued, then 0 should be returned.  When
 342      the write completes, end_io_func() should be called with the following
 343      arguments:
 344
 345         (*end_io_func)(object->cookie->netfs_data,
 346                        page,
 347                        end_io_data,
 348                        error);
 349
 350  (*) Discard retained per-page metadata [mandatory]:
 351
 352         void (*uncache_pages)(struct fscache_object *object,
 353                               struct pagevec *pagevec)
 354
 355      This is called when one or more netfs pages are being evicted from the
 356      pagecache.  The cache backend should tear down any internal representation
 357      or tracking it maintains.