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