Branch data     Line data    Source code

       1                 :            : /* SPDX-License-Identifier: GPL-2.0-or-later */
       2                 :            : /* General filesystem caching backing cache interface
       3                 :            :  *
       4                 :            :  * Copyright (C) 2004-2007 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.txt
      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                 :            : #include <linux/sched.h>
      19                 :            : #include <linux/workqueue.h>
      20                 :            : 
      21                 :            : #define NR_MAXCACHES BITS_PER_LONG
      22                 :            : 
      23                 :            : struct fscache_cache;
      24                 :            : struct fscache_cache_ops;
      25                 :            : struct fscache_object;
      26                 :            : struct fscache_operation;
      27                 :            : 
      28                 :            : enum fscache_obj_ref_trace {
      29                 :            :         fscache_obj_get_add_to_deps,
      30                 :            :         fscache_obj_get_queue,
      31                 :            :         fscache_obj_put_alloc_fail,
      32                 :            :         fscache_obj_put_attach_fail,
      33                 :            :         fscache_obj_put_drop_obj,
      34                 :            :         fscache_obj_put_enq_dep,
      35                 :            :         fscache_obj_put_queue,
      36                 :            :         fscache_obj_put_work,
      37                 :            :         fscache_obj_ref__nr_traces
      38                 :            : };
      39                 :            : 
      40                 :            : /*
      41                 :            :  * cache tag definition
      42                 :            :  */
      43                 :            : struct fscache_cache_tag {
      44                 :            :         struct list_head        link;
      45                 :            :         struct fscache_cache    *cache;         /* cache referred to by this tag */
      46                 :            :         unsigned long           flags;
      47                 :            : #define FSCACHE_TAG_RESERVED    0               /* T if tag is reserved for a cache */
      48                 :            :         atomic_t                usage;
      49                 :            :         char                    name[0];        /* tag name */
      50                 :            : };
      51                 :            : 
      52                 :            : /*
      53                 :            :  * cache definition
      54                 :            :  */
      55                 :            : struct fscache_cache {
      56                 :            :         const struct fscache_cache_ops *ops;
      57                 :            :         struct fscache_cache_tag *tag;          /* tag representing this cache */
      58                 :            :         struct kobject          *kobj;          /* system representation of this cache */
      59                 :            :         struct list_head        link;           /* link in list of caches */
      60                 :            :         size_t                  max_index_size; /* maximum size of index data */
      61                 :            :         char                    identifier[36]; /* cache label */
      62                 :            : 
      63                 :            :         /* node management */
      64                 :            :         struct work_struct      op_gc;          /* operation garbage collector */
      65                 :            :         struct list_head        object_list;    /* list of data/index objects */
      66                 :            :         struct list_head        op_gc_list;     /* list of ops to be deleted */
      67                 :            :         spinlock_t              object_list_lock;
      68                 :            :         spinlock_t              op_gc_list_lock;
      69                 :            :         atomic_t                object_count;   /* no. of live objects in this cache */
      70                 :            :         struct fscache_object   *fsdef;         /* object for the fsdef index */
      71                 :            :         unsigned long           flags;
      72                 :            : #define FSCACHE_IOERROR         0       /* cache stopped on I/O error */
      73                 :            : #define FSCACHE_CACHE_WITHDRAWN 1       /* cache has been withdrawn */
      74                 :            : };
      75                 :            : 
      76                 :            : extern wait_queue_head_t fscache_cache_cleared_wq;
      77                 :            : 
      78                 :            : /*
      79                 :            :  * operation to be applied to a cache object
      80                 :            :  * - retrieval initiation operations are done in the context of the process
      81                 :            :  *   that issued them, and not in an async thread pool
      82                 :            :  */
      83                 :            : typedef void (*fscache_operation_release_t)(struct fscache_operation *op);
      84                 :            : typedef void (*fscache_operation_processor_t)(struct fscache_operation *op);
      85                 :            : typedef void (*fscache_operation_cancel_t)(struct fscache_operation *op);
      86                 :            : 
      87                 :            : enum fscache_operation_state {
      88                 :            :         FSCACHE_OP_ST_BLANK,            /* Op is not yet submitted */
      89                 :            :         FSCACHE_OP_ST_INITIALISED,      /* Op is initialised */
      90                 :            :         FSCACHE_OP_ST_PENDING,          /* Op is blocked from running */
      91                 :            :         FSCACHE_OP_ST_IN_PROGRESS,      /* Op is in progress */
      92                 :            :         FSCACHE_OP_ST_COMPLETE,         /* Op is complete */
      93                 :            :         FSCACHE_OP_ST_CANCELLED,        /* Op has been cancelled */
      94                 :            :         FSCACHE_OP_ST_DEAD              /* Op is now dead */
      95                 :            : };
      96                 :            : 
      97                 :            : struct fscache_operation {
      98                 :            :         struct work_struct      work;           /* record for async ops */
      99                 :            :         struct list_head        pend_link;      /* link in object->pending_ops */
     100                 :            :         struct fscache_object   *object;        /* object to be operated upon */
     101                 :            : 
     102                 :            :         unsigned long           flags;
     103                 :            : #define FSCACHE_OP_TYPE         0x000f  /* operation type */
     104                 :            : #define FSCACHE_OP_ASYNC        0x0001  /* - async op, processor may sleep for disk */
     105                 :            : #define FSCACHE_OP_MYTHREAD     0x0002  /* - processing is done be issuing thread, not pool */
     106                 :            : #define FSCACHE_OP_WAITING      4       /* cleared when op is woken */
     107                 :            : #define FSCACHE_OP_EXCLUSIVE    5       /* exclusive op, other ops must wait */
     108                 :            : #define FSCACHE_OP_DEC_READ_CNT 6       /* decrement object->n_reads on destruction */
     109                 :            : #define FSCACHE_OP_UNUSE_COOKIE 7       /* call fscache_unuse_cookie() on completion */
     110                 :            : #define FSCACHE_OP_KEEP_FLAGS   0x00f0  /* flags to keep when repurposing an op */
     111                 :            : 
     112                 :            :         enum fscache_operation_state state;
     113                 :            :         atomic_t                usage;
     114                 :            :         unsigned                debug_id;       /* debugging ID */
     115                 :            : 
     116                 :            :         /* operation processor callback
     117                 :            :          * - can be NULL if FSCACHE_OP_WAITING is going to be used to perform
     118                 :            :          *   the op in a non-pool thread */
     119                 :            :         fscache_operation_processor_t processor;
     120                 :            : 
     121                 :            :         /* Operation cancellation cleanup (optional) */
     122                 :            :         fscache_operation_cancel_t cancel;
     123                 :            : 
     124                 :            :         /* operation releaser */
     125                 :            :         fscache_operation_release_t release;
     126                 :            : };
     127                 :            : 
     128                 :            : extern atomic_t fscache_op_debug_id;
     129                 :            : extern void fscache_op_work_func(struct work_struct *work);
     130                 :            : 
     131                 :            : extern void fscache_enqueue_operation(struct fscache_operation *);
     132                 :            : extern void fscache_op_complete(struct fscache_operation *, bool);
     133                 :            : extern void fscache_put_operation(struct fscache_operation *);
     134                 :            : extern void fscache_operation_init(struct fscache_cookie *,
     135                 :            :                                    struct fscache_operation *,
     136                 :            :                                    fscache_operation_processor_t,
     137                 :            :                                    fscache_operation_cancel_t,
     138                 :            :                                    fscache_operation_release_t);
     139                 :            : 
     140                 :            : /*
     141                 :            :  * data read operation
     142                 :            :  */
     143                 :            : struct fscache_retrieval {
     144                 :            :         struct fscache_operation op;
     145                 :            :         struct fscache_cookie   *cookie;        /* The netfs cookie */
     146                 :            :         struct address_space    *mapping;       /* netfs pages */
     147                 :            :         fscache_rw_complete_t   end_io_func;    /* function to call on I/O completion */
     148                 :            :         void                    *context;       /* netfs read context (pinned) */
     149                 :            :         struct list_head        to_do;          /* list of things to be done by the backend */
     150                 :            :         unsigned long           start_time;     /* time at which retrieval started */
     151                 :            :         atomic_t                n_pages;        /* number of pages to be retrieved */
     152                 :            : };
     153                 :            : 
     154                 :            : typedef int (*fscache_page_retrieval_func_t)(struct fscache_retrieval *op,
     155                 :            :                                              struct page *page,
     156                 :            :                                              gfp_t gfp);
     157                 :            : 
     158                 :            : typedef int (*fscache_pages_retrieval_func_t)(struct fscache_retrieval *op,
     159                 :            :                                               struct list_head *pages,
     160                 :            :                                               unsigned *nr_pages,
     161                 :            :                                               gfp_t gfp);
     162                 :            : 
     163                 :            : /**
     164                 :            :  * fscache_get_retrieval - Get an extra reference on a retrieval operation
     165                 :            :  * @op: The retrieval operation to get a reference on
     166                 :            :  *
     167                 :            :  * Get an extra reference on a retrieval operation.
     168                 :            :  */
     169                 :            : static inline
     170                 :            : struct fscache_retrieval *fscache_get_retrieval(struct fscache_retrieval *op)
     171                 :            : {
     172                 :          0 :         atomic_inc(&op->op.usage);
     173                 :            :         return op;
     174                 :            : }
     175                 :            : 
     176                 :            : /**
     177                 :            :  * fscache_enqueue_retrieval - Enqueue a retrieval operation for processing
     178                 :            :  * @op: The retrieval operation affected
     179                 :            :  *
     180                 :            :  * Enqueue a retrieval operation for processing by the FS-Cache thread pool.
     181                 :            :  */
     182                 :            : static inline void fscache_enqueue_retrieval(struct fscache_retrieval *op)
     183                 :            : {
     184                 :          0 :         fscache_enqueue_operation(&op->op);
     185                 :            : }
     186                 :            : 
     187                 :            : /**
     188                 :            :  * fscache_retrieval_complete - Record (partial) completion of a retrieval
     189                 :            :  * @op: The retrieval operation affected
     190                 :            :  * @n_pages: The number of pages to account for
     191                 :            :  */
     192                 :          0 : static inline void fscache_retrieval_complete(struct fscache_retrieval *op,
     193                 :            :                                               int n_pages)
     194                 :            : {
     195                 :          0 :         if (atomic_sub_return_relaxed(n_pages, &op->n_pages) <= 0)
     196                 :          0 :                 fscache_op_complete(&op->op, false);
     197                 :          0 : }
     198                 :            : 
     199                 :            : /**
     200                 :            :  * fscache_put_retrieval - Drop a reference to a retrieval operation
     201                 :            :  * @op: The retrieval operation affected
     202                 :            :  *
     203                 :            :  * Drop a reference to a retrieval operation.
     204                 :            :  */
     205                 :            : static inline void fscache_put_retrieval(struct fscache_retrieval *op)
     206                 :            : {
     207                 :          0 :         fscache_put_operation(&op->op);
     208                 :            : }
     209                 :            : 
     210                 :            : /*
     211                 :            :  * cached page storage work item
     212                 :            :  * - used to do three things:
     213                 :            :  *   - batch writes to the cache
     214                 :            :  *   - do cache writes asynchronously
     215                 :            :  *   - defer writes until cache object lookup completion
     216                 :            :  */
     217                 :            : struct fscache_storage {
     218                 :            :         struct fscache_operation op;
     219                 :            :         pgoff_t                 store_limit;    /* don't write more than this */
     220                 :            : };
     221                 :            : 
     222                 :            : /*
     223                 :            :  * cache operations
     224                 :            :  */
     225                 :            : struct fscache_cache_ops {
     226                 :            :         /* name of cache provider */
     227                 :            :         const char *name;
     228                 :            : 
     229                 :            :         /* allocate an object record for a cookie */
     230                 :            :         struct fscache_object *(*alloc_object)(struct fscache_cache *cache,
     231                 :            :                                                struct fscache_cookie *cookie);
     232                 :            : 
     233                 :            :         /* look up the object for a cookie
     234                 :            :          * - return -ETIMEDOUT to be requeued
     235                 :            :          */
     236                 :            :         int (*lookup_object)(struct fscache_object *object);
     237                 :            : 
     238                 :            :         /* finished looking up */
     239                 :            :         void (*lookup_complete)(struct fscache_object *object);
     240                 :            : 
     241                 :            :         /* increment the usage count on this object (may fail if unmounting) */
     242                 :            :         struct fscache_object *(*grab_object)(struct fscache_object *object,
     243                 :            :                                               enum fscache_obj_ref_trace why);
     244                 :            : 
     245                 :            :         /* pin an object in the cache */
     246                 :            :         int (*pin_object)(struct fscache_object *object);
     247                 :            : 
     248                 :            :         /* unpin an object in the cache */
     249                 :            :         void (*unpin_object)(struct fscache_object *object);
     250                 :            : 
     251                 :            :         /* check the consistency between the backing cache and the FS-Cache
     252                 :            :          * cookie */
     253                 :            :         int (*check_consistency)(struct fscache_operation *op);
     254                 :            : 
     255                 :            :         /* store the updated auxiliary data on an object */
     256                 :            :         void (*update_object)(struct fscache_object *object);
     257                 :            : 
     258                 :            :         /* Invalidate an object */
     259                 :            :         void (*invalidate_object)(struct fscache_operation *op);
     260                 :            : 
     261                 :            :         /* discard the resources pinned by an object and effect retirement if
     262                 :            :          * necessary */
     263                 :            :         void (*drop_object)(struct fscache_object *object);
     264                 :            : 
     265                 :            :         /* dispose of a reference to an object */
     266                 :            :         void (*put_object)(struct fscache_object *object,
     267                 :            :                            enum fscache_obj_ref_trace why);
     268                 :            : 
     269                 :            :         /* sync a cache */
     270                 :            :         void (*sync_cache)(struct fscache_cache *cache);
     271                 :            : 
     272                 :            :         /* notification that the attributes of a non-index object (such as
     273                 :            :          * i_size) have changed */
     274                 :            :         int (*attr_changed)(struct fscache_object *object);
     275                 :            : 
     276                 :            :         /* reserve space for an object's data and associated metadata */
     277                 :            :         int (*reserve_space)(struct fscache_object *object, loff_t i_size);
     278                 :            : 
     279                 :            :         /* request a backing block for a page be read or allocated in the
     280                 :            :          * cache */
     281                 :            :         fscache_page_retrieval_func_t read_or_alloc_page;
     282                 :            : 
     283                 :            :         /* request backing blocks for a list of pages be read or allocated in
     284                 :            :          * the cache */
     285                 :            :         fscache_pages_retrieval_func_t read_or_alloc_pages;
     286                 :            : 
     287                 :            :         /* request a backing block for a page be allocated in the cache so that
     288                 :            :          * it can be written directly */
     289                 :            :         fscache_page_retrieval_func_t allocate_page;
     290                 :            : 
     291                 :            :         /* request backing blocks for pages be allocated in the cache so that
     292                 :            :          * they can be written directly */
     293                 :            :         fscache_pages_retrieval_func_t allocate_pages;
     294                 :            : 
     295                 :            :         /* write a page to its backing block in the cache */
     296                 :            :         int (*write_page)(struct fscache_storage *op, struct page *page);
     297                 :            : 
     298                 :            :         /* detach backing block from a page (optional)
     299                 :            :          * - must release the cookie lock before returning
     300                 :            :          * - may sleep
     301                 :            :          */
     302                 :            :         void (*uncache_page)(struct fscache_object *object,
     303                 :            :                              struct page *page);
     304                 :            : 
     305                 :            :         /* dissociate a cache from all the pages it was backing */
     306                 :            :         void (*dissociate_pages)(struct fscache_cache *cache);
     307                 :            : };
     308                 :            : 
     309                 :            : extern struct fscache_cookie fscache_fsdef_index;
     310                 :            : 
     311                 :            : /*
     312                 :            :  * Event list for fscache_object::{event_mask,events}
     313                 :            :  */
     314                 :            : enum {
     315                 :            :         FSCACHE_OBJECT_EV_NEW_CHILD,    /* T if object has a new child */
     316                 :            :         FSCACHE_OBJECT_EV_PARENT_READY, /* T if object's parent is ready */
     317                 :            :         FSCACHE_OBJECT_EV_UPDATE,       /* T if object should be updated */
     318                 :            :         FSCACHE_OBJECT_EV_INVALIDATE,   /* T if cache requested object invalidation */
     319                 :            :         FSCACHE_OBJECT_EV_CLEARED,      /* T if accessors all gone */
     320                 :            :         FSCACHE_OBJECT_EV_ERROR,        /* T if fatal error occurred during processing */
     321                 :            :         FSCACHE_OBJECT_EV_KILL,         /* T if netfs relinquished or cache withdrew object */
     322                 :            :         NR_FSCACHE_OBJECT_EVENTS
     323                 :            : };
     324                 :            : 
     325                 :            : #define FSCACHE_OBJECT_EVENTS_MASK ((1UL << NR_FSCACHE_OBJECT_EVENTS) - 1)
     326                 :            : 
     327                 :            : /*
     328                 :            :  * States for object state machine.
     329                 :            :  */
     330                 :            : struct fscache_transition {
     331                 :            :         unsigned long events;
     332                 :            :         const struct fscache_state *transit_to;
     333                 :            : };
     334                 :            : 
     335                 :            : struct fscache_state {
     336                 :            :         char name[24];
     337                 :            :         char short_name[8];
     338                 :            :         const struct fscache_state *(*work)(struct fscache_object *object,
     339                 :            :                                             int event);
     340                 :            :         const struct fscache_transition transitions[];
     341                 :            : };
     342                 :            : 
     343                 :            : /*
     344                 :            :  * on-disk cache file or index handle
     345                 :            :  */
     346                 :            : struct fscache_object {
     347                 :            :         const struct fscache_state *state;      /* Object state machine state */
     348                 :            :         const struct fscache_transition *oob_table; /* OOB state transition table */
     349                 :            :         int                     debug_id;       /* debugging ID */
     350                 :            :         int                     n_children;     /* number of child objects */
     351                 :            :         int                     n_ops;          /* number of extant ops on object */
     352                 :            :         int                     n_obj_ops;      /* number of object ops outstanding on object */
     353                 :            :         int                     n_in_progress;  /* number of ops in progress */
     354                 :            :         int                     n_exclusive;    /* number of exclusive ops queued or in progress */
     355                 :            :         atomic_t                n_reads;        /* number of read ops in progress */
     356                 :            :         spinlock_t              lock;           /* state and operations lock */
     357                 :            : 
     358                 :            :         unsigned long           lookup_jif;     /* time at which lookup started */
     359                 :            :         unsigned long           oob_event_mask; /* OOB events this object is interested in */
     360                 :            :         unsigned long           event_mask;     /* events this object is interested in */
     361                 :            :         unsigned long           events;         /* events to be processed by this object
     362                 :            :                                                  * (order is important - using fls) */
     363                 :            : 
     364                 :            :         unsigned long           flags;
     365                 :            : #define FSCACHE_OBJECT_LOCK             0       /* T if object is busy being processed */
     366                 :            : #define FSCACHE_OBJECT_PENDING_WRITE    1       /* T if object has pending write */
     367                 :            : #define FSCACHE_OBJECT_WAITING          2       /* T if object is waiting on its parent */
     368                 :            : #define FSCACHE_OBJECT_IS_LIVE          3       /* T if object is not withdrawn or relinquished */
     369                 :            : #define FSCACHE_OBJECT_IS_LOOKED_UP     4       /* T if object has been looked up */
     370                 :            : #define FSCACHE_OBJECT_IS_AVAILABLE     5       /* T if object has become active */
     371                 :            : #define FSCACHE_OBJECT_RETIRED          6       /* T if object was retired on relinquishment */
     372                 :            : #define FSCACHE_OBJECT_KILLED_BY_CACHE  7       /* T if object was killed by the cache */
     373                 :            : #define FSCACHE_OBJECT_RUN_AFTER_DEAD   8       /* T if object has been dispatched after death */
     374                 :            : 
     375                 :            :         struct list_head        cache_link;     /* link in cache->object_list */
     376                 :            :         struct hlist_node       cookie_link;    /* link in cookie->backing_objects */
     377                 :            :         struct fscache_cache    *cache;         /* cache that supplied this object */
     378                 :            :         struct fscache_cookie   *cookie;        /* netfs's file/index object */
     379                 :            :         struct fscache_object   *parent;        /* parent object */
     380                 :            :         struct work_struct      work;           /* attention scheduling record */
     381                 :            :         struct list_head        dependents;     /* FIFO of dependent objects */
     382                 :            :         struct list_head        dep_link;       /* link in parent's dependents list */
     383                 :            :         struct list_head        pending_ops;    /* unstarted operations on this object */
     384                 :            : #ifdef CONFIG_FSCACHE_OBJECT_LIST
     385                 :            :         struct rb_node          objlist_link;   /* link in global object list */
     386                 :            : #endif
     387                 :            :         pgoff_t                 store_limit;    /* current storage limit */
     388                 :            :         loff_t                  store_limit_l;  /* current storage limit */
     389                 :            : };
     390                 :            : 
     391                 :            : extern void fscache_object_init(struct fscache_object *, struct fscache_cookie *,
     392                 :            :                                 struct fscache_cache *);
     393                 :            : extern void fscache_object_destroy(struct fscache_object *);
     394                 :            : 
     395                 :            : extern void fscache_object_lookup_negative(struct fscache_object *object);
     396                 :            : extern void fscache_obtained_object(struct fscache_object *object);
     397                 :            : 
     398                 :            : static inline bool fscache_object_is_live(struct fscache_object *object)
     399                 :            : {
     400                 :            :         return test_bit(FSCACHE_OBJECT_IS_LIVE, &object->flags);
     401                 :            : }
     402                 :            : 
     403                 :            : static inline bool fscache_object_is_dying(struct fscache_object *object)
     404                 :            : {
     405                 :          0 :         return !fscache_object_is_live(object);
     406                 :            : }
     407                 :            : 
     408                 :            : static inline bool fscache_object_is_available(struct fscache_object *object)
     409                 :            : {
     410                 :            :         return test_bit(FSCACHE_OBJECT_IS_AVAILABLE, &object->flags);
     411                 :            : }
     412                 :            : 
     413                 :            : static inline bool fscache_cache_is_broken(struct fscache_object *object)
     414                 :            : {
     415                 :          0 :         return test_bit(FSCACHE_IOERROR, &object->cache->flags);
     416                 :            : }
     417                 :            : 
     418                 :            : static inline bool fscache_object_is_active(struct fscache_object *object)
     419                 :            : {
     420                 :          0 :         return fscache_object_is_available(object) &&
     421                 :          0 :                 fscache_object_is_live(object) &&
     422                 :            :                 !fscache_cache_is_broken(object);
     423                 :            : }
     424                 :            : 
     425                 :            : /**
     426                 :            :  * fscache_object_destroyed - Note destruction of an object in a cache
     427                 :            :  * @cache: The cache from which the object came
     428                 :            :  *
     429                 :            :  * Note the destruction and deallocation of an object record in a cache.
     430                 :            :  */
     431                 :          0 : static inline void fscache_object_destroyed(struct fscache_cache *cache)
     432                 :            : {
     433                 :          0 :         if (atomic_dec_and_test(&cache->object_count))
     434                 :          0 :                 wake_up_all(&fscache_cache_cleared_wq);
     435                 :          0 : }
     436                 :            : 
     437                 :            : /**
     438                 :            :  * fscache_object_lookup_error - Note an object encountered an error
     439                 :            :  * @object: The object on which the error was encountered
     440                 :            :  *
     441                 :            :  * Note that an object encountered a fatal error (usually an I/O error) and
     442                 :            :  * that it should be withdrawn as soon as possible.
     443                 :            :  */
     444                 :            : static inline void fscache_object_lookup_error(struct fscache_object *object)
     445                 :            : {
     446                 :          0 :         set_bit(FSCACHE_OBJECT_EV_ERROR, &object->events);
     447                 :            : }
     448                 :            : 
     449                 :            : /**
     450                 :            :  * fscache_set_store_limit - Set the maximum size to be stored in an object
     451                 :            :  * @object: The object to set the maximum on
     452                 :            :  * @i_size: The limit to set in bytes
     453                 :            :  *
     454                 :            :  * Set the maximum size an object is permitted to reach, implying the highest
     455                 :            :  * byte that may be written.  Intended to be called by the attr_changed() op.
     456                 :            :  *
     457                 :            :  * See Documentation/filesystems/caching/backend-api.txt for a complete
     458                 :            :  * description.
     459                 :            :  */
     460                 :            : static inline
     461                 :            : void fscache_set_store_limit(struct fscache_object *object, loff_t i_size)
     462                 :            : {
     463                 :          0 :         object->store_limit_l = i_size;
     464                 :          0 :         object->store_limit = i_size >> PAGE_SHIFT;
     465                 :          0 :         if (i_size & ~PAGE_MASK)
     466                 :          0 :                 object->store_limit++;
     467                 :            : }
     468                 :            : 
     469                 :            : /**
     470                 :            :  * fscache_end_io - End a retrieval operation on a page
     471                 :            :  * @op: The FS-Cache operation covering the retrieval
     472                 :            :  * @page: The page that was to be fetched
     473                 :            :  * @error: The error code (0 if successful)
     474                 :            :  *
     475                 :            :  * Note the end of an operation to retrieve a page, as covered by a particular
     476                 :            :  * operation record.
     477                 :            :  */
     478                 :            : static inline void fscache_end_io(struct fscache_retrieval *op,
     479                 :            :                                   struct page *page, int error)
     480                 :            : {
     481                 :          0 :         op->end_io_func(page, op->context, error);
     482                 :            : }
     483                 :            : 
     484                 :            : static inline void __fscache_use_cookie(struct fscache_cookie *cookie)
     485                 :            : {
     486                 :          0 :         atomic_inc(&cookie->n_active);
     487                 :            : }
     488                 :            : 
     489                 :            : /**
     490                 :            :  * fscache_use_cookie - Request usage of cookie attached to an object
     491                 :            :  * @object: Object description
     492                 :            :  * 
     493                 :            :  * Request usage of the cookie attached to an object.  NULL is returned if the
     494                 :            :  * relinquishment had reduced the cookie usage count to 0.
     495                 :            :  */
     496                 :            : static inline bool fscache_use_cookie(struct fscache_object *object)
     497                 :            : {
     498                 :          0 :         struct fscache_cookie *cookie = object->cookie;
     499                 :          0 :         return atomic_inc_not_zero(&cookie->n_active) != 0;
     500                 :            : }
     501                 :            : 
     502                 :            : static inline bool __fscache_unuse_cookie(struct fscache_cookie *cookie)
     503                 :            : {
     504                 :          0 :         return atomic_dec_and_test(&cookie->n_active);
     505                 :            : }
     506                 :            : 
     507                 :            : static inline void __fscache_wake_unused_cookie(struct fscache_cookie *cookie)
     508                 :            : {
     509                 :          0 :         wake_up_var(&cookie->n_active);
     510                 :            : }
     511                 :            : 
     512                 :            : /**
     513                 :            :  * fscache_unuse_cookie - Cease usage of cookie attached to an object
     514                 :            :  * @object: Object description
     515                 :            :  * 
     516                 :            :  * Cease usage of the cookie attached to an object.  When the users count
     517                 :            :  * reaches zero then the cookie relinquishment will be permitted to proceed.
     518                 :            :  */
     519                 :          0 : static inline void fscache_unuse_cookie(struct fscache_object *object)
     520                 :            : {
     521                 :          0 :         struct fscache_cookie *cookie = object->cookie;
     522                 :          0 :         if (__fscache_unuse_cookie(cookie))
     523                 :            :                 __fscache_wake_unused_cookie(cookie);
     524                 :          0 : }
     525                 :            : 
     526                 :            : /*
     527                 :            :  * out-of-line cache backend functions
     528                 :            :  */
     529                 :            : extern __printf(3, 4)
     530                 :            : void fscache_init_cache(struct fscache_cache *cache,
     531                 :            :                         const struct fscache_cache_ops *ops,
     532                 :            :                         const char *idfmt, ...);
     533                 :            : 
     534                 :            : extern int fscache_add_cache(struct fscache_cache *cache,
     535                 :            :                              struct fscache_object *fsdef,
     536                 :            :                              const char *tagname);
     537                 :            : extern void fscache_withdraw_cache(struct fscache_cache *cache);
     538                 :            : 
     539                 :            : extern void fscache_io_error(struct fscache_cache *cache);
     540                 :            : 
     541                 :            : extern void fscache_mark_page_cached(struct fscache_retrieval *op,
     542                 :            :                                      struct page *page);
     543                 :            : 
     544                 :            : extern void fscache_mark_pages_cached(struct fscache_retrieval *op,
     545                 :            :                                       struct pagevec *pagevec);
     546                 :            : 
     547                 :            : extern bool fscache_object_sleep_till_congested(signed long *timeoutp);
     548                 :            : 
     549                 :            : extern enum fscache_checkaux fscache_check_aux(struct fscache_object *object,
     550                 :            :                                                const void *data,
     551                 :            :                                                uint16_t datalen,
     552                 :            :                                                loff_t object_size);
     553                 :            : 
     554                 :            : extern void fscache_object_retrying_stale(struct fscache_object *object);
     555                 :            : 
     556                 :            : enum fscache_why_object_killed {
     557                 :            :         FSCACHE_OBJECT_IS_STALE,
     558                 :            :         FSCACHE_OBJECT_NO_SPACE,
     559                 :            :         FSCACHE_OBJECT_WAS_RETIRED,
     560                 :            :         FSCACHE_OBJECT_WAS_CULLED,
     561                 :            : };
     562                 :            : extern void fscache_object_mark_killed(struct fscache_object *object,
     563                 :            :                                        enum fscache_why_object_killed why);
     564                 :            : 
     565                 :            : #endif /* _LINUX_FSCACHE_CACHE_H */