include/linux/fscache-cache.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /* General filesystem caching backing cache interface
   3  *
   4  * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved.
   5  * Written by David Howells (dhowells@redhat.com)
   6  *
   7  * NOTE!!! See:
   8  *
   9  *      Documentation/filesystems/caching/backend-api.rst
  10  *
  11  * for a description of the cache backend interface declared here.
  12  */
  13
  14 #ifndef _LINUX_FSCACHE_CACHE_H
  15 #define _LINUX_FSCACHE_CACHE_H
  16
  17 #include <linux/fscache.h>
  18
  19 enum fscache_cache_trace;
  20 enum fscache_cookie_trace;
  21 enum fscache_access_trace;
  22
  23 enum fscache_cache_state {
  24         FSCACHE_CACHE_IS_NOT_PRESENT,   /* No cache is present for this name */
  25         FSCACHE_CACHE_IS_PREPARING,     /* A cache is preparing to come live */
  26         FSCACHE_CACHE_IS_ACTIVE,        /* Attached cache is active and can be used */
  27         FSCACHE_CACHE_GOT_IOERROR,      /* Attached cache stopped on I/O error */
  28         FSCACHE_CACHE_IS_WITHDRAWN,     /* Attached cache is being withdrawn */
  29 #define NR__FSCACHE_CACHE_STATE (FSCACHE_CACHE_IS_WITHDRAWN + 1)
  30 };
  31
  32 /*
  33  * Cache cookie.
  34  */
  35 struct fscache_cache {
  36         const struct fscache_cache_ops *ops;
  37         struct list_head        cache_link;     /* Link in cache list */
  38         void                    *cache_priv;    /* Private cache data (or NULL) */
  39         refcount_t              ref;
  40         atomic_t                n_volumes;      /* Number of active volumes; */
  41         atomic_t                n_accesses;     /* Number of in-progress accesses on the cache */
  42         atomic_t                object_count;   /* no. of live objects in this cache */
  43         unsigned int            debug_id;
  44         enum fscache_cache_state state;
  45         char                    *name;
  46 };
  47
  48 /*
  49  * cache operations
  50  */
  51 struct fscache_cache_ops {
  52         /* name of cache provider */
  53         const char *name;
  54
  55         /* Acquire a volume */
  56         void (*acquire_volume)(struct fscache_volume *volume);
  57
  58         /* Free the cache's data attached to a volume */
  59         void (*free_volume)(struct fscache_volume *volume);
  60
  61         /* Look up a cookie in the cache */
  62         bool (*lookup_cookie)(struct fscache_cookie *cookie);
  63
  64         /* Withdraw an object without any cookie access counts held */
  65         void (*withdraw_cookie)(struct fscache_cookie *cookie);
  66
  67         /* Change the size of a data object */
  68         void (*resize_cookie)(struct netfs_cache_resources *cres,
  69                               loff_t new_size);
  70
  71         /* Invalidate an object */
  72         bool (*invalidate_cookie)(struct fscache_cookie *cookie);
  73
  74         /* Begin an operation for the netfs lib */
  75         bool (*begin_operation)(struct netfs_cache_resources *cres,
  76                                 enum fscache_want_state want_state);
  77
  78         /* Prepare to write to a live cache object */
  79         void (*prepare_to_write)(struct fscache_cookie *cookie);
  80 };
  81
  82 extern struct workqueue_struct *fscache_wq;
  83 extern wait_queue_head_t fscache_clearance_waiters;
  84
  85 /*
  86  * out-of-line cache backend functions
  87  */
  88 extern struct rw_semaphore fscache_addremove_sem;
  89 extern struct fscache_cache *fscache_acquire_cache(const char *name);
  90 extern void fscache_relinquish_cache(struct fscache_cache *cache);
  91 extern int fscache_add_cache(struct fscache_cache *cache,
  92                              const struct fscache_cache_ops *ops,
  93                              void *cache_priv);
  94 extern void fscache_withdraw_cache(struct fscache_cache *cache);
  95 extern void fscache_withdraw_volume(struct fscache_volume *volume);
  96 extern void fscache_withdraw_cookie(struct fscache_cookie *cookie);
  97
  98 extern void fscache_io_error(struct fscache_cache *cache);
  99
 100 extern void fscache_end_volume_access(struct fscache_volume *volume,
 101                                       struct fscache_cookie *cookie,
 102                                       enum fscache_access_trace why);
 103
 104 extern struct fscache_cookie *fscache_get_cookie(struct fscache_cookie *cookie,
 105                                                  enum fscache_cookie_trace where);
 106 extern void fscache_put_cookie(struct fscache_cookie *cookie,
 107                                enum fscache_cookie_trace where);
 108 extern void fscache_end_cookie_access(struct fscache_cookie *cookie,
 109                                       enum fscache_access_trace why);
 110 extern void fscache_cookie_lookup_negative(struct fscache_cookie *cookie);
 111 extern void fscache_resume_after_invalidation(struct fscache_cookie *cookie);
 112 extern void fscache_caching_failed(struct fscache_cookie *cookie);
 113 extern bool fscache_wait_for_operation(struct netfs_cache_resources *cred,
 114                                        enum fscache_want_state state);
 115
 116 /**
 117  * fscache_cookie_state - Read the state of a cookie
 118  * @cookie: The cookie to query
 119  *
 120  * Get the state of a cookie, imposing an ordering between the cookie contents
 121  * and the state value.  Paired with fscache_set_cookie_state().
 122  */
 123 static inline
 124 enum fscache_cookie_state fscache_cookie_state(struct fscache_cookie *cookie)
 125 {
 126         return smp_load_acquire(&cookie->state);
 127 }
 128
 129 /**
 130  * fscache_get_key - Get a pointer to the cookie key
 131  * @cookie: The cookie to query
 132  *
 133  * Return a pointer to the where a cookie's key is stored.
 134  */
 135 static inline void *fscache_get_key(struct fscache_cookie *cookie)
 136 {
 137         if (cookie->key_len <= sizeof(cookie->inline_key))
 138                 return cookie->inline_key;
 139         else
 140                 return cookie->key;
 141 }
 142
 143 static inline struct fscache_cookie *fscache_cres_cookie(struct netfs_cache_resources *cres)
 144 {
 145         return cres->cache_priv;
 146 }
 147
 148 /**
 149  * fscache_count_object - Tell fscache that an object has been added
 150  * @cache: The cache to account to
 151  *
 152  * Tell fscache that an object has been added to the cache.  This prevents the
 153  * cache from tearing down the cache structure until the object is uncounted.
 154  */
 155 static inline void fscache_count_object(struct fscache_cache *cache)
 156 {
 157         atomic_inc(&cache->object_count);
 158 }
 159
 160 /**
 161  * fscache_uncount_object - Tell fscache that an object has been removed
 162  * @cache: The cache to account to
 163  *
 164  * Tell fscache that an object has been removed from the cache and will no
 165  * longer be accessed.  After this point, the cache cookie may be destroyed.
 166  */
 167 static inline void fscache_uncount_object(struct fscache_cache *cache)
 168 {
 169         if (atomic_dec_and_test(&cache->object_count))
 170                 wake_up_all(&fscache_clearance_waiters);
 171 }
 172
 173 /**
 174  * fscache_wait_for_objects - Wait for all objects to be withdrawn
 175  * @cache: The cache to query
 176  *
 177  * Wait for all extant objects in a cache to finish being withdrawn
 178  * and go away.
 179  */
 180 static inline void fscache_wait_for_objects(struct fscache_cache *cache)
 181 {
 182         wait_event(fscache_clearance_waiters,
 183                    atomic_read(&cache->object_count) == 0);
 184 }
 185
 186 #ifdef CONFIG_FSCACHE_STATS
 187 extern atomic_t fscache_n_read;
 188 extern atomic_t fscache_n_write;
 189 extern atomic_t fscache_n_no_write_space;
 190 extern atomic_t fscache_n_no_create_space;
 191 extern atomic_t fscache_n_culled;
 192 #define fscache_count_read() atomic_inc(&fscache_n_read)
 193 #define fscache_count_write() atomic_inc(&fscache_n_write)
 194 #define fscache_count_no_write_space() atomic_inc(&fscache_n_no_write_space)
 195 #define fscache_count_no_create_space() atomic_inc(&fscache_n_no_create_space)
 196 #define fscache_count_culled() atomic_inc(&fscache_n_culled)
 197 #else
 198 #define fscache_count_read() do {} while(0)
 199 #define fscache_count_write() do {} while(0)
 200 #define fscache_count_no_write_space() do {} while(0)
 201 #define fscache_count_no_create_space() do {} while(0)
 202 #define fscache_count_culled() do {} while(0)
 203 #endif
 204
 205 #endif /* _LINUX_FSCACHE_CACHE_H */