LCOV - code coverage report
Current view: top level - include/linux - fscache.h (source / functions) Hit Total Coverage
Test: Real Lines: 1 40 2.5 %
Date: 2020-10-17 15:46:16 Functions: 0 8 0.0 %
Legend: Neither, QEMU, Real, Both Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /* SPDX-License-Identifier: GPL-2.0-or-later */
       2                 :            : /* General filesystem caching 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/netfs-api.txt
      10                 :            :  *
      11                 :            :  * for a description of the network filesystem interface declared here.
      12                 :            :  */
      13                 :            : 
      14                 :            : #ifndef _LINUX_FSCACHE_H
      15                 :            : #define _LINUX_FSCACHE_H
      16                 :            : 
      17                 :            : #include <linux/fs.h>
      18                 :            : #include <linux/list.h>
      19                 :            : #include <linux/pagemap.h>
      20                 :            : #include <linux/pagevec.h>
      21                 :            : #include <linux/list_bl.h>
      22                 :            : 
      23                 :            : #if defined(CONFIG_FSCACHE) || defined(CONFIG_FSCACHE_MODULE)
      24                 :            : #define fscache_available() (1)
      25                 :            : #define fscache_cookie_valid(cookie) (cookie)
      26                 :            : #else
      27                 :            : #define fscache_available() (0)
      28                 :            : #define fscache_cookie_valid(cookie) (0)
      29                 :            : #endif
      30                 :            : 
      31                 :            : 
      32                 :            : /*
      33                 :            :  * overload PG_private_2 to give us PG_fscache - this is used to indicate that
      34                 :            :  * a page is currently backed by a local disk cache
      35                 :            :  */
      36                 :            : #define PageFsCache(page)               PagePrivate2((page))
      37                 :            : #define SetPageFsCache(page)            SetPagePrivate2((page))
      38                 :            : #define ClearPageFsCache(page)          ClearPagePrivate2((page))
      39                 :            : #define TestSetPageFsCache(page)        TestSetPagePrivate2((page))
      40                 :            : #define TestClearPageFsCache(page)      TestClearPagePrivate2((page))
      41                 :            : 
      42                 :            : /* pattern used to fill dead space in an index entry */
      43                 :            : #define FSCACHE_INDEX_DEADFILL_PATTERN 0x79
      44                 :            : 
      45                 :            : struct pagevec;
      46                 :            : struct fscache_cache_tag;
      47                 :            : struct fscache_cookie;
      48                 :            : struct fscache_netfs;
      49                 :            : 
      50                 :            : typedef void (*fscache_rw_complete_t)(struct page *page,
      51                 :            :                                       void *context,
      52                 :            :                                       int error);
      53                 :            : 
      54                 :            : /* result of index entry consultation */
      55                 :            : enum fscache_checkaux {
      56                 :            :         FSCACHE_CHECKAUX_OKAY,          /* entry okay as is */
      57                 :            :         FSCACHE_CHECKAUX_NEEDS_UPDATE,  /* entry requires update */
      58                 :            :         FSCACHE_CHECKAUX_OBSOLETE,      /* entry requires deletion */
      59                 :            : };
      60                 :            : 
      61                 :            : /*
      62                 :            :  * fscache cookie definition
      63                 :            :  */
      64                 :            : struct fscache_cookie_def {
      65                 :            :         /* name of cookie type */
      66                 :            :         char name[16];
      67                 :            : 
      68                 :            :         /* cookie type */
      69                 :            :         uint8_t type;
      70                 :            : #define FSCACHE_COOKIE_TYPE_INDEX       0
      71                 :            : #define FSCACHE_COOKIE_TYPE_DATAFILE    1
      72                 :            : 
      73                 :            :         /* select the cache into which to insert an entry in this index
      74                 :            :          * - optional
      75                 :            :          * - should return a cache identifier or NULL to cause the cache to be
      76                 :            :          *   inherited from the parent if possible or the first cache picked
      77                 :            :          *   for a non-index file if not
      78                 :            :          */
      79                 :            :         struct fscache_cache_tag *(*select_cache)(
      80                 :            :                 const void *parent_netfs_data,
      81                 :            :                 const void *cookie_netfs_data);
      82                 :            : 
      83                 :            :         /* consult the netfs about the state of an object
      84                 :            :          * - this function can be absent if the index carries no state data
      85                 :            :          * - the netfs data from the cookie being used as the target is
      86                 :            :          *   presented, as is the auxiliary data and the object size
      87                 :            :          */
      88                 :            :         enum fscache_checkaux (*check_aux)(void *cookie_netfs_data,
      89                 :            :                                            const void *data,
      90                 :            :                                            uint16_t datalen,
      91                 :            :                                            loff_t object_size);
      92                 :            : 
      93                 :            :         /* get an extra reference on a read context
      94                 :            :          * - this function can be absent if the completion function doesn't
      95                 :            :          *   require a context
      96                 :            :          */
      97                 :            :         void (*get_context)(void *cookie_netfs_data, void *context);
      98                 :            : 
      99                 :            :         /* release an extra reference on a read context
     100                 :            :          * - this function can be absent if the completion function doesn't
     101                 :            :          *   require a context
     102                 :            :          */
     103                 :            :         void (*put_context)(void *cookie_netfs_data, void *context);
     104                 :            : 
     105                 :            :         /* indicate page that now have cache metadata retained
     106                 :            :          * - this function should mark the specified page as now being cached
     107                 :            :          * - the page will have been marked with PG_fscache before this is
     108                 :            :          *   called, so this is optional
     109                 :            :          */
     110                 :            :         void (*mark_page_cached)(void *cookie_netfs_data,
     111                 :            :                                  struct address_space *mapping,
     112                 :            :                                  struct page *page);
     113                 :            : };
     114                 :            : 
     115                 :            : /*
     116                 :            :  * fscache cached network filesystem type
     117                 :            :  * - name, version and ops must be filled in before registration
     118                 :            :  * - all other fields will be set during registration
     119                 :            :  */
     120                 :            : struct fscache_netfs {
     121                 :            :         uint32_t                        version;        /* indexing version */
     122                 :            :         const char                      *name;          /* filesystem name */
     123                 :            :         struct fscache_cookie           *primary_index;
     124                 :            : };
     125                 :            : 
     126                 :            : /*
     127                 :            :  * data file or index object cookie
     128                 :            :  * - a file will only appear in one cache
     129                 :            :  * - a request to cache a file may or may not be honoured, subject to
     130                 :            :  *   constraints such as disk space
     131                 :            :  * - indices are created on disk just-in-time
     132                 :            :  */
     133                 :            : struct fscache_cookie {
     134                 :            :         atomic_t                        usage;          /* number of users of this cookie */
     135                 :            :         atomic_t                        n_children;     /* number of children of this cookie */
     136                 :            :         atomic_t                        n_active;       /* number of active users of netfs ptrs */
     137                 :            :         spinlock_t                      lock;
     138                 :            :         spinlock_t                      stores_lock;    /* lock on page store tree */
     139                 :            :         struct hlist_head               backing_objects; /* object(s) backing this file/index */
     140                 :            :         const struct fscache_cookie_def *def;           /* definition */
     141                 :            :         struct fscache_cookie           *parent;        /* parent of this entry */
     142                 :            :         struct hlist_bl_node            hash_link;      /* Link in hash table */
     143                 :            :         void                            *netfs_data;    /* back pointer to netfs */
     144                 :            :         struct radix_tree_root          stores;         /* pages to be stored on this cookie */
     145                 :            : #define FSCACHE_COOKIE_PENDING_TAG      0               /* pages tag: pending write to cache */
     146                 :            : #define FSCACHE_COOKIE_STORING_TAG      1               /* pages tag: writing to cache */
     147                 :            : 
     148                 :            :         unsigned long                   flags;
     149                 :            : #define FSCACHE_COOKIE_LOOKING_UP       0       /* T if non-index cookie being looked up still */
     150                 :            : #define FSCACHE_COOKIE_NO_DATA_YET      1       /* T if new object with no cached data yet */
     151                 :            : #define FSCACHE_COOKIE_UNAVAILABLE      2       /* T if cookie is unavailable (error, etc) */
     152                 :            : #define FSCACHE_COOKIE_INVALIDATING     3       /* T if cookie is being invalidated */
     153                 :            : #define FSCACHE_COOKIE_RELINQUISHED     4       /* T if cookie has been relinquished */
     154                 :            : #define FSCACHE_COOKIE_ENABLED          5       /* T if cookie is enabled */
     155                 :            : #define FSCACHE_COOKIE_ENABLEMENT_LOCK  6       /* T if cookie is being en/disabled */
     156                 :            : #define FSCACHE_COOKIE_AUX_UPDATED      8       /* T if the auxiliary data was updated */
     157                 :            : #define FSCACHE_COOKIE_ACQUIRED         9       /* T if cookie is in use */
     158                 :            : #define FSCACHE_COOKIE_RELINQUISHING    10      /* T if cookie is being relinquished */
     159                 :            : 
     160                 :            :         u8                              type;           /* Type of object */
     161                 :            :         u8                              key_len;        /* Length of index key */
     162                 :            :         u8                              aux_len;        /* Length of auxiliary data */
     163                 :            :         u32                             key_hash;       /* Hash of parent, type, key, len */
     164                 :            :         union {
     165                 :            :                 void                    *key;           /* Index key */
     166                 :            :                 u8                      inline_key[16]; /* - If the key is short enough */
     167                 :            :         };
     168                 :            :         union {
     169                 :            :                 void                    *aux;           /* Auxiliary data */
     170                 :            :                 u8                      inline_aux[8];  /* - If the aux data is short enough */
     171                 :            :         };
     172                 :            : };
     173                 :            : 
     174                 :            : static inline bool fscache_cookie_enabled(struct fscache_cookie *cookie)
     175                 :            : {
     176                 :            :         return test_bit(FSCACHE_COOKIE_ENABLED, &cookie->flags);
     177                 :            : }
     178                 :            : 
     179                 :            : /*
     180                 :            :  * slow-path functions for when there is actually caching available, and the
     181                 :            :  * netfs does actually have a valid token
     182                 :            :  * - these are not to be called directly
     183                 :            :  * - these are undefined symbols when FS-Cache is not configured and the
     184                 :            :  *   optimiser takes care of not using them
     185                 :            :  */
     186                 :            : extern int __fscache_register_netfs(struct fscache_netfs *);
     187                 :            : extern void __fscache_unregister_netfs(struct fscache_netfs *);
     188                 :            : extern struct fscache_cache_tag *__fscache_lookup_cache_tag(const char *);
     189                 :            : extern void __fscache_release_cache_tag(struct fscache_cache_tag *);
     190                 :            : 
     191                 :            : extern struct fscache_cookie *__fscache_acquire_cookie(
     192                 :            :         struct fscache_cookie *,
     193                 :            :         const struct fscache_cookie_def *,
     194                 :            :         const void *, size_t,
     195                 :            :         const void *, size_t,
     196                 :            :         void *, loff_t, bool);
     197                 :            : extern void __fscache_relinquish_cookie(struct fscache_cookie *, const void *, bool);
     198                 :            : extern int __fscache_check_consistency(struct fscache_cookie *, const void *);
     199                 :            : extern void __fscache_update_cookie(struct fscache_cookie *, const void *);
     200                 :            : extern int __fscache_attr_changed(struct fscache_cookie *);
     201                 :            : extern void __fscache_invalidate(struct fscache_cookie *);
     202                 :            : extern void __fscache_wait_on_invalidate(struct fscache_cookie *);
     203                 :            : extern int __fscache_read_or_alloc_page(struct fscache_cookie *,
     204                 :            :                                         struct page *,
     205                 :            :                                         fscache_rw_complete_t,
     206                 :            :                                         void *,
     207                 :            :                                         gfp_t);
     208                 :            : extern int __fscache_read_or_alloc_pages(struct fscache_cookie *,
     209                 :            :                                          struct address_space *,
     210                 :            :                                          struct list_head *,
     211                 :            :                                          unsigned *,
     212                 :            :                                          fscache_rw_complete_t,
     213                 :            :                                          void *,
     214                 :            :                                          gfp_t);
     215                 :            : extern int __fscache_alloc_page(struct fscache_cookie *, struct page *, gfp_t);
     216                 :            : extern int __fscache_write_page(struct fscache_cookie *, struct page *, loff_t, gfp_t);
     217                 :            : extern void __fscache_uncache_page(struct fscache_cookie *, struct page *);
     218                 :            : extern bool __fscache_check_page_write(struct fscache_cookie *, struct page *);
     219                 :            : extern void __fscache_wait_on_page_write(struct fscache_cookie *, struct page *);
     220                 :            : extern bool __fscache_maybe_release_page(struct fscache_cookie *, struct page *,
     221                 :            :                                          gfp_t);
     222                 :            : extern void __fscache_uncache_all_inode_pages(struct fscache_cookie *,
     223                 :            :                                               struct inode *);
     224                 :            : extern void __fscache_readpages_cancel(struct fscache_cookie *cookie,
     225                 :            :                                        struct list_head *pages);
     226                 :            : extern void __fscache_disable_cookie(struct fscache_cookie *, const void *, bool);
     227                 :            : extern void __fscache_enable_cookie(struct fscache_cookie *, const void *, loff_t,
     228                 :            :                                     bool (*)(void *), void *);
     229                 :            : 
     230                 :            : /**
     231                 :            :  * fscache_register_netfs - Register a filesystem as desiring caching services
     232                 :            :  * @netfs: The description of the filesystem
     233                 :            :  *
     234                 :            :  * Register a filesystem as desiring caching services if they're available.
     235                 :            :  *
     236                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     237                 :            :  * description.
     238                 :            :  */
     239                 :            : static inline
     240                 :            : int fscache_register_netfs(struct fscache_netfs *netfs)
     241                 :            : {
     242                 :            :         if (fscache_available())
     243                 :          3 :                 return __fscache_register_netfs(netfs);
     244                 :            :         else
     245                 :            :                 return 0;
     246                 :            : }
     247                 :            : 
     248                 :            : /**
     249                 :            :  * fscache_unregister_netfs - Indicate that a filesystem no longer desires
     250                 :            :  * caching services
     251                 :            :  * @netfs: The description of the filesystem
     252                 :            :  *
     253                 :            :  * Indicate that a filesystem no longer desires caching services for the
     254                 :            :  * moment.
     255                 :            :  *
     256                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     257                 :            :  * description.
     258                 :            :  */
     259                 :            : static inline
     260                 :            : void fscache_unregister_netfs(struct fscache_netfs *netfs)
     261                 :            : {
     262                 :            :         if (fscache_available())
     263                 :          0 :                 __fscache_unregister_netfs(netfs);
     264                 :            : }
     265                 :            : 
     266                 :            : /**
     267                 :            :  * fscache_lookup_cache_tag - Look up a cache tag
     268                 :            :  * @name: The name of the tag to search for
     269                 :            :  *
     270                 :            :  * Acquire a specific cache referral tag that can be used to select a specific
     271                 :            :  * cache in which to cache an index.
     272                 :            :  *
     273                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     274                 :            :  * description.
     275                 :            :  */
     276                 :            : static inline
     277                 :            : struct fscache_cache_tag *fscache_lookup_cache_tag(const char *name)
     278                 :            : {
     279                 :            :         if (fscache_available())
     280                 :            :                 return __fscache_lookup_cache_tag(name);
     281                 :            :         else
     282                 :            :                 return NULL;
     283                 :            : }
     284                 :            : 
     285                 :            : /**
     286                 :            :  * fscache_release_cache_tag - Release a cache tag
     287                 :            :  * @tag: The tag to release
     288                 :            :  *
     289                 :            :  * Release a reference to a cache referral tag previously looked up.
     290                 :            :  *
     291                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     292                 :            :  * description.
     293                 :            :  */
     294                 :            : static inline
     295                 :            : void fscache_release_cache_tag(struct fscache_cache_tag *tag)
     296                 :            : {
     297                 :            :         if (fscache_available())
     298                 :          0 :                 __fscache_release_cache_tag(tag);
     299                 :            : }
     300                 :            : 
     301                 :            : /**
     302                 :            :  * fscache_acquire_cookie - Acquire a cookie to represent a cache object
     303                 :            :  * @parent: The cookie that's to be the parent of this one
     304                 :            :  * @def: A description of the cache object, including callback operations
     305                 :            :  * @index_key: The index key for this cookie
     306                 :            :  * @index_key_len: Size of the index key
     307                 :            :  * @aux_data: The auxiliary data for the cookie (may be NULL)
     308                 :            :  * @aux_data_len: Size of the auxiliary data buffer
     309                 :            :  * @netfs_data: An arbitrary piece of data to be kept in the cookie to
     310                 :            :  * represent the cache object to the netfs
     311                 :            :  * @object_size: The initial size of object
     312                 :            :  * @enable: Whether or not to enable a data cookie immediately
     313                 :            :  *
     314                 :            :  * This function is used to inform FS-Cache about part of an index hierarchy
     315                 :            :  * that can be used to locate files.  This is done by requesting a cookie for
     316                 :            :  * each index in the path to the file.
     317                 :            :  *
     318                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     319                 :            :  * description.
     320                 :            :  */
     321                 :            : static inline
     322                 :          0 : struct fscache_cookie *fscache_acquire_cookie(
     323                 :            :         struct fscache_cookie *parent,
     324                 :            :         const struct fscache_cookie_def *def,
     325                 :            :         const void *index_key,
     326                 :            :         size_t index_key_len,
     327                 :            :         const void *aux_data,
     328                 :            :         size_t aux_data_len,
     329                 :            :         void *netfs_data,
     330                 :            :         loff_t object_size,
     331                 :            :         bool enable)
     332                 :            : {
     333                 :          0 :         if (fscache_cookie_valid(parent) && fscache_cookie_enabled(parent))
     334                 :          0 :                 return __fscache_acquire_cookie(parent, def,
     335                 :            :                                                 index_key, index_key_len,
     336                 :            :                                                 aux_data, aux_data_len,
     337                 :            :                                                 netfs_data, object_size, enable);
     338                 :            :         else
     339                 :            :                 return NULL;
     340                 :            : }
     341                 :            : 
     342                 :            : /**
     343                 :            :  * fscache_relinquish_cookie - Return the cookie to the cache, maybe discarding
     344                 :            :  * it
     345                 :            :  * @cookie: The cookie being returned
     346                 :            :  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
     347                 :            :  * @retire: True if the cache object the cookie represents is to be discarded
     348                 :            :  *
     349                 :            :  * This function returns a cookie to the cache, forcibly discarding the
     350                 :            :  * associated cache object if retire is set to true.  The opportunity is
     351                 :            :  * provided to update the auxiliary data in the cache before the object is
     352                 :            :  * disconnected.
     353                 :            :  *
     354                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     355                 :            :  * description.
     356                 :            :  */
     357                 :            : static inline
     358                 :            : void fscache_relinquish_cookie(struct fscache_cookie *cookie,
     359                 :            :                                const void *aux_data,
     360                 :            :                                bool retire)
     361                 :            : {
     362                 :          0 :         if (fscache_cookie_valid(cookie))
     363                 :          0 :                 __fscache_relinquish_cookie(cookie, aux_data, retire);
     364                 :            : }
     365                 :            : 
     366                 :            : /**
     367                 :            :  * fscache_check_consistency - Request validation of a cache's auxiliary data
     368                 :            :  * @cookie: The cookie representing the cache object
     369                 :            :  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
     370                 :            :  *
     371                 :            :  * Request an consistency check from fscache, which passes the request to the
     372                 :            :  * backing cache.  The auxiliary data on the cookie will be updated first if
     373                 :            :  * @aux_data is set.
     374                 :            :  *
     375                 :            :  * Returns 0 if consistent and -ESTALE if inconsistent.  May also
     376                 :            :  * return -ENOMEM and -ERESTARTSYS.
     377                 :            :  */
     378                 :            : static inline
     379                 :            : int fscache_check_consistency(struct fscache_cookie *cookie,
     380                 :            :                               const void *aux_data)
     381                 :            : {
     382                 :            :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     383                 :            :                 return __fscache_check_consistency(cookie, aux_data);
     384                 :            :         else
     385                 :            :                 return 0;
     386                 :            : }
     387                 :            : 
     388                 :            : /**
     389                 :            :  * fscache_update_cookie - Request that a cache object be updated
     390                 :            :  * @cookie: The cookie representing the cache object
     391                 :            :  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
     392                 :            :  *
     393                 :            :  * Request an update of the index data for the cache object associated with the
     394                 :            :  * cookie.  The auxiliary data on the cookie will be updated first if @aux_data
     395                 :            :  * is set.
     396                 :            :  *
     397                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     398                 :            :  * description.
     399                 :            :  */
     400                 :            : static inline
     401                 :            : void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data)
     402                 :            : {
     403                 :            :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     404                 :            :                 __fscache_update_cookie(cookie, aux_data);
     405                 :            : }
     406                 :            : 
     407                 :            : /**
     408                 :            :  * fscache_pin_cookie - Pin a data-storage cache object in its cache
     409                 :            :  * @cookie: The cookie representing the cache object
     410                 :            :  *
     411                 :            :  * Permit data-storage cache objects to be pinned in the cache.
     412                 :            :  *
     413                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     414                 :            :  * description.
     415                 :            :  */
     416                 :            : static inline
     417                 :            : int fscache_pin_cookie(struct fscache_cookie *cookie)
     418                 :            : {
     419                 :            :         return -ENOBUFS;
     420                 :            : }
     421                 :            : 
     422                 :            : /**
     423                 :            :  * fscache_pin_cookie - Unpin a data-storage cache object in its cache
     424                 :            :  * @cookie: The cookie representing the cache object
     425                 :            :  *
     426                 :            :  * Permit data-storage cache objects to be unpinned from the cache.
     427                 :            :  *
     428                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     429                 :            :  * description.
     430                 :            :  */
     431                 :            : static inline
     432                 :            : void fscache_unpin_cookie(struct fscache_cookie *cookie)
     433                 :            : {
     434                 :            : }
     435                 :            : 
     436                 :            : /**
     437                 :            :  * fscache_attr_changed - Notify cache that an object's attributes changed
     438                 :            :  * @cookie: The cookie representing the cache object
     439                 :            :  *
     440                 :            :  * Send a notification to the cache indicating that an object's attributes have
     441                 :            :  * changed.  This includes the data size.  These attributes will be obtained
     442                 :            :  * through the get_attr() cookie definition op.
     443                 :            :  *
     444                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     445                 :            :  * description.
     446                 :            :  */
     447                 :            : static inline
     448                 :            : int fscache_attr_changed(struct fscache_cookie *cookie)
     449                 :            : {
     450                 :            :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     451                 :            :                 return __fscache_attr_changed(cookie);
     452                 :            :         else
     453                 :            :                 return -ENOBUFS;
     454                 :            : }
     455                 :            : 
     456                 :            : /**
     457                 :            :  * fscache_invalidate - Notify cache that an object needs invalidation
     458                 :            :  * @cookie: The cookie representing the cache object
     459                 :            :  *
     460                 :            :  * Notify the cache that an object is needs to be invalidated and that it
     461                 :            :  * should abort any retrievals or stores it is doing on the cache.  The object
     462                 :            :  * is then marked non-caching until such time as the invalidation is complete.
     463                 :            :  *
     464                 :            :  * This can be called with spinlocks held.
     465                 :            :  *
     466                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     467                 :            :  * description.
     468                 :            :  */
     469                 :            : static inline
     470                 :          0 : void fscache_invalidate(struct fscache_cookie *cookie)
     471                 :            : {
     472                 :          0 :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     473                 :          0 :                 __fscache_invalidate(cookie);
     474                 :          0 : }
     475                 :            : 
     476                 :            : /**
     477                 :            :  * fscache_wait_on_invalidate - Wait for invalidation to complete
     478                 :            :  * @cookie: The cookie representing the cache object
     479                 :            :  *
     480                 :            :  * Wait for the invalidation of an object to complete.
     481                 :            :  *
     482                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     483                 :            :  * description.
     484                 :            :  */
     485                 :            : static inline
     486                 :            : void fscache_wait_on_invalidate(struct fscache_cookie *cookie)
     487                 :            : {
     488                 :          0 :         if (fscache_cookie_valid(cookie))
     489                 :          0 :                 __fscache_wait_on_invalidate(cookie);
     490                 :            : }
     491                 :            : 
     492                 :            : /**
     493                 :            :  * fscache_reserve_space - Reserve data space for a cached object
     494                 :            :  * @cookie: The cookie representing the cache object
     495                 :            :  * @i_size: The amount of space to be reserved
     496                 :            :  *
     497                 :            :  * Reserve an amount of space in the cache for the cache object attached to a
     498                 :            :  * cookie so that a write to that object within the space can always be
     499                 :            :  * honoured.
     500                 :            :  *
     501                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     502                 :            :  * description.
     503                 :            :  */
     504                 :            : static inline
     505                 :            : int fscache_reserve_space(struct fscache_cookie *cookie, loff_t size)
     506                 :            : {
     507                 :            :         return -ENOBUFS;
     508                 :            : }
     509                 :            : 
     510                 :            : /**
     511                 :            :  * fscache_read_or_alloc_page - Read a page from the cache or allocate a block
     512                 :            :  * in which to store it
     513                 :            :  * @cookie: The cookie representing the cache object
     514                 :            :  * @page: The netfs page to fill if possible
     515                 :            :  * @end_io_func: The callback to invoke when and if the page is filled
     516                 :            :  * @context: An arbitrary piece of data to pass on to end_io_func()
     517                 :            :  * @gfp: The conditions under which memory allocation should be made
     518                 :            :  *
     519                 :            :  * Read a page from the cache, or if that's not possible make a potential
     520                 :            :  * one-block reservation in the cache into which the page may be stored once
     521                 :            :  * fetched from the server.
     522                 :            :  *
     523                 :            :  * If the page is not backed by the cache object, or if it there's some reason
     524                 :            :  * it can't be, -ENOBUFS will be returned and nothing more will be done for
     525                 :            :  * that page.
     526                 :            :  *
     527                 :            :  * Else, if that page is backed by the cache, a read will be initiated directly
     528                 :            :  * to the netfs's page and 0 will be returned by this function.  The
     529                 :            :  * end_io_func() callback will be invoked when the operation terminates on a
     530                 :            :  * completion or failure.  Note that the callback may be invoked before the
     531                 :            :  * return.
     532                 :            :  *
     533                 :            :  * Else, if the page is unbacked, -ENODATA is returned and a block may have
     534                 :            :  * been allocated in the cache.
     535                 :            :  *
     536                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     537                 :            :  * description.
     538                 :            :  */
     539                 :            : static inline
     540                 :          0 : int fscache_read_or_alloc_page(struct fscache_cookie *cookie,
     541                 :            :                                struct page *page,
     542                 :            :                                fscache_rw_complete_t end_io_func,
     543                 :            :                                void *context,
     544                 :            :                                gfp_t gfp)
     545                 :            : {
     546                 :          0 :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     547                 :          0 :                 return __fscache_read_or_alloc_page(cookie, page, end_io_func,
     548                 :            :                                                     context, gfp);
     549                 :            :         else
     550                 :            :                 return -ENOBUFS;
     551                 :            : }
     552                 :            : 
     553                 :            : /**
     554                 :            :  * fscache_read_or_alloc_pages - Read pages from the cache and/or allocate
     555                 :            :  * blocks in which to store them
     556                 :            :  * @cookie: The cookie representing the cache object
     557                 :            :  * @mapping: The netfs inode mapping to which the pages will be attached
     558                 :            :  * @pages: A list of potential netfs pages to be filled
     559                 :            :  * @nr_pages: Number of pages to be read and/or allocated
     560                 :            :  * @end_io_func: The callback to invoke when and if each page is filled
     561                 :            :  * @context: An arbitrary piece of data to pass on to end_io_func()
     562                 :            :  * @gfp: The conditions under which memory allocation should be made
     563                 :            :  *
     564                 :            :  * Read a set of pages from the cache, or if that's not possible, attempt to
     565                 :            :  * make a potential one-block reservation for each page in the cache into which
     566                 :            :  * that page may be stored once fetched from the server.
     567                 :            :  *
     568                 :            :  * If some pages are not backed by the cache object, or if it there's some
     569                 :            :  * reason they can't be, -ENOBUFS will be returned and nothing more will be
     570                 :            :  * done for that pages.
     571                 :            :  *
     572                 :            :  * Else, if some of the pages are backed by the cache, a read will be initiated
     573                 :            :  * directly to the netfs's page and 0 will be returned by this function.  The
     574                 :            :  * end_io_func() callback will be invoked when the operation terminates on a
     575                 :            :  * completion or failure.  Note that the callback may be invoked before the
     576                 :            :  * return.
     577                 :            :  *
     578                 :            :  * Else, if a page is unbacked, -ENODATA is returned and a block may have
     579                 :            :  * been allocated in the cache.
     580                 :            :  *
     581                 :            :  * Because the function may want to return all of -ENOBUFS, -ENODATA and 0 in
     582                 :            :  * regard to different pages, the return values are prioritised in that order.
     583                 :            :  * Any pages submitted for reading are removed from the pages list.
     584                 :            :  *
     585                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     586                 :            :  * description.
     587                 :            :  */
     588                 :            : static inline
     589                 :          0 : int fscache_read_or_alloc_pages(struct fscache_cookie *cookie,
     590                 :            :                                 struct address_space *mapping,
     591                 :            :                                 struct list_head *pages,
     592                 :            :                                 unsigned *nr_pages,
     593                 :            :                                 fscache_rw_complete_t end_io_func,
     594                 :            :                                 void *context,
     595                 :            :                                 gfp_t gfp)
     596                 :            : {
     597                 :          0 :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     598                 :          0 :                 return __fscache_read_or_alloc_pages(cookie, mapping, pages,
     599                 :            :                                                      nr_pages, end_io_func,
     600                 :            :                                                      context, gfp);
     601                 :            :         else
     602                 :            :                 return -ENOBUFS;
     603                 :            : }
     604                 :            : 
     605                 :            : /**
     606                 :            :  * fscache_alloc_page - Allocate a block in which to store a page
     607                 :            :  * @cookie: The cookie representing the cache object
     608                 :            :  * @page: The netfs page to allocate a page for
     609                 :            :  * @gfp: The conditions under which memory allocation should be made
     610                 :            :  *
     611                 :            :  * Request Allocation a block in the cache in which to store a netfs page
     612                 :            :  * without retrieving any contents from the cache.
     613                 :            :  *
     614                 :            :  * If the page is not backed by a file then -ENOBUFS will be returned and
     615                 :            :  * nothing more will be done, and no reservation will be made.
     616                 :            :  *
     617                 :            :  * Else, a block will be allocated if one wasn't already, and 0 will be
     618                 :            :  * returned
     619                 :            :  *
     620                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     621                 :            :  * description.
     622                 :            :  */
     623                 :            : static inline
     624                 :            : int fscache_alloc_page(struct fscache_cookie *cookie,
     625                 :            :                        struct page *page,
     626                 :            :                        gfp_t gfp)
     627                 :            : {
     628                 :            :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     629                 :            :                 return __fscache_alloc_page(cookie, page, gfp);
     630                 :            :         else
     631                 :            :                 return -ENOBUFS;
     632                 :            : }
     633                 :            : 
     634                 :            : /**
     635                 :            :  * fscache_readpages_cancel - Cancel read/alloc on pages
     636                 :            :  * @cookie: The cookie representing the inode's cache object.
     637                 :            :  * @pages: The netfs pages that we canceled write on in readpages()
     638                 :            :  *
     639                 :            :  * Uncache/unreserve the pages reserved earlier in readpages() via
     640                 :            :  * fscache_readpages_or_alloc() and similar.  In most successful caches in
     641                 :            :  * readpages() this doesn't do anything.  In cases when the underlying netfs's
     642                 :            :  * readahead failed we need to clean up the pagelist (unmark and uncache).
     643                 :            :  *
     644                 :            :  * This function may sleep as it may have to clean up disk state.
     645                 :            :  */
     646                 :            : static inline
     647                 :            : void fscache_readpages_cancel(struct fscache_cookie *cookie,
     648                 :            :                               struct list_head *pages)
     649                 :            : {
     650                 :            :         if (fscache_cookie_valid(cookie))
     651                 :            :                 __fscache_readpages_cancel(cookie, pages);
     652                 :            : }
     653                 :            : 
     654                 :            : /**
     655                 :            :  * fscache_write_page - Request storage of a page in the cache
     656                 :            :  * @cookie: The cookie representing the cache object
     657                 :            :  * @page: The netfs page to store
     658                 :            :  * @object_size: Updated size of object
     659                 :            :  * @gfp: The conditions under which memory allocation should be made
     660                 :            :  *
     661                 :            :  * Request the contents of the netfs page be written into the cache.  This
     662                 :            :  * request may be ignored if no cache block is currently allocated, in which
     663                 :            :  * case it will return -ENOBUFS.
     664                 :            :  *
     665                 :            :  * If a cache block was already allocated, a write will be initiated and 0 will
     666                 :            :  * be returned.  The PG_fscache_write page bit is set immediately and will then
     667                 :            :  * be cleared at the completion of the write to indicate the success or failure
     668                 :            :  * of the operation.  Note that the completion may happen before the return.
     669                 :            :  *
     670                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     671                 :            :  * description.
     672                 :            :  */
     673                 :            : static inline
     674                 :          0 : int fscache_write_page(struct fscache_cookie *cookie,
     675                 :            :                        struct page *page,
     676                 :            :                        loff_t object_size,
     677                 :            :                        gfp_t gfp)
     678                 :            : {
     679                 :          0 :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     680                 :          0 :                 return __fscache_write_page(cookie, page, object_size, gfp);
     681                 :            :         else
     682                 :            :                 return -ENOBUFS;
     683                 :            : }
     684                 :            : 
     685                 :            : /**
     686                 :            :  * fscache_uncache_page - Indicate that caching is no longer required on a page
     687                 :            :  * @cookie: The cookie representing the cache object
     688                 :            :  * @page: The netfs page that was being cached.
     689                 :            :  *
     690                 :            :  * Tell the cache that we no longer want a page to be cached and that it should
     691                 :            :  * remove any knowledge of the netfs page it may have.
     692                 :            :  *
     693                 :            :  * Note that this cannot cancel any outstanding I/O operations between this
     694                 :            :  * page and the cache.
     695                 :            :  *
     696                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     697                 :            :  * description.
     698                 :            :  */
     699                 :            : static inline
     700                 :            : void fscache_uncache_page(struct fscache_cookie *cookie,
     701                 :            :                           struct page *page)
     702                 :            : {
     703                 :          0 :         if (fscache_cookie_valid(cookie))
     704                 :          0 :                 __fscache_uncache_page(cookie, page);
     705                 :            : }
     706                 :            : 
     707                 :            : /**
     708                 :            :  * fscache_check_page_write - Ask if a page is being writing to the cache
     709                 :            :  * @cookie: The cookie representing the cache object
     710                 :            :  * @page: The netfs page that is being cached.
     711                 :            :  *
     712                 :            :  * Ask the cache if a page is being written to the cache.
     713                 :            :  *
     714                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     715                 :            :  * description.
     716                 :            :  */
     717                 :            : static inline
     718                 :            : bool fscache_check_page_write(struct fscache_cookie *cookie,
     719                 :            :                               struct page *page)
     720                 :            : {
     721                 :            :         if (fscache_cookie_valid(cookie))
     722                 :            :                 return __fscache_check_page_write(cookie, page);
     723                 :            :         return false;
     724                 :            : }
     725                 :            : 
     726                 :            : /**
     727                 :            :  * fscache_wait_on_page_write - Wait for a page to complete writing to the cache
     728                 :            :  * @cookie: The cookie representing the cache object
     729                 :            :  * @page: The netfs page that is being cached.
     730                 :            :  *
     731                 :            :  * Ask the cache to wake us up when a page is no longer being written to the
     732                 :            :  * cache.
     733                 :            :  *
     734                 :            :  * See Documentation/filesystems/caching/netfs-api.txt for a complete
     735                 :            :  * description.
     736                 :            :  */
     737                 :            : static inline
     738                 :            : void fscache_wait_on_page_write(struct fscache_cookie *cookie,
     739                 :            :                                 struct page *page)
     740                 :            : {
     741                 :          0 :         if (fscache_cookie_valid(cookie))
     742                 :          0 :                 __fscache_wait_on_page_write(cookie, page);
     743                 :            : }
     744                 :            : 
     745                 :            : /**
     746                 :            :  * fscache_maybe_release_page - Consider releasing a page, cancelling a store
     747                 :            :  * @cookie: The cookie representing the cache object
     748                 :            :  * @page: The netfs page that is being cached.
     749                 :            :  * @gfp: The gfp flags passed to releasepage()
     750                 :            :  *
     751                 :            :  * Consider releasing a page for the vmscan algorithm, on behalf of the netfs's
     752                 :            :  * releasepage() call.  A storage request on the page may cancelled if it is
     753                 :            :  * not currently being processed.
     754                 :            :  *
     755                 :            :  * The function returns true if the page no longer has a storage request on it,
     756                 :            :  * and false if a storage request is left in place.  If true is returned, the
     757                 :            :  * page will have been passed to fscache_uncache_page().  If false is returned
     758                 :            :  * the page cannot be freed yet.
     759                 :            :  */
     760                 :            : static inline
     761                 :          0 : bool fscache_maybe_release_page(struct fscache_cookie *cookie,
     762                 :            :                                 struct page *page,
     763                 :            :                                 gfp_t gfp)
     764                 :            : {
     765                 :          0 :         if (fscache_cookie_valid(cookie) && PageFsCache(page))
     766                 :          0 :                 return __fscache_maybe_release_page(cookie, page, gfp);
     767                 :            :         return true;
     768                 :            : }
     769                 :            : 
     770                 :            : /**
     771                 :            :  * fscache_uncache_all_inode_pages - Uncache all an inode's pages
     772                 :            :  * @cookie: The cookie representing the inode's cache object.
     773                 :            :  * @inode: The inode to uncache pages from.
     774                 :            :  *
     775                 :            :  * Uncache all the pages in an inode that are marked PG_fscache, assuming them
     776                 :            :  * to be associated with the given cookie.
     777                 :            :  *
     778                 :            :  * This function may sleep.  It will wait for pages that are being written out
     779                 :            :  * and will wait whilst the PG_fscache mark is removed by the cache.
     780                 :            :  */
     781                 :            : static inline
     782                 :            : void fscache_uncache_all_inode_pages(struct fscache_cookie *cookie,
     783                 :            :                                      struct inode *inode)
     784                 :            : {
     785                 :          0 :         if (fscache_cookie_valid(cookie))
     786                 :          0 :                 __fscache_uncache_all_inode_pages(cookie, inode);
     787                 :            : }
     788                 :            : 
     789                 :            : /**
     790                 :            :  * fscache_disable_cookie - Disable a cookie
     791                 :            :  * @cookie: The cookie representing the cache object
     792                 :            :  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
     793                 :            :  * @invalidate: Invalidate the backing object
     794                 :            :  *
     795                 :            :  * Disable a cookie from accepting further alloc, read, write, invalidate,
     796                 :            :  * update or acquire operations.  Outstanding operations can still be waited
     797                 :            :  * upon and pages can still be uncached and the cookie relinquished.
     798                 :            :  *
     799                 :            :  * This will not return until all outstanding operations have completed.
     800                 :            :  *
     801                 :            :  * If @invalidate is set, then the backing object will be invalidated and
     802                 :            :  * detached, otherwise it will just be detached.
     803                 :            :  *
     804                 :            :  * If @aux_data is set, then auxiliary data will be updated from that.
     805                 :            :  */
     806                 :            : static inline
     807                 :          0 : void fscache_disable_cookie(struct fscache_cookie *cookie,
     808                 :            :                             const void *aux_data,
     809                 :            :                             bool invalidate)
     810                 :            : {
     811                 :          0 :         if (fscache_cookie_valid(cookie) && fscache_cookie_enabled(cookie))
     812                 :          0 :                 __fscache_disable_cookie(cookie, aux_data, invalidate);
     813                 :          0 : }
     814                 :            : 
     815                 :            : /**
     816                 :            :  * fscache_enable_cookie - Reenable a cookie
     817                 :            :  * @cookie: The cookie representing the cache object
     818                 :            :  * @aux_data: The updated auxiliary data for the cookie (may be NULL)
     819                 :            :  * @object_size: Current size of object
     820                 :            :  * @can_enable: A function to permit enablement once lock is held
     821                 :            :  * @data: Data for can_enable()
     822                 :            :  *
     823                 :            :  * Reenable a previously disabled cookie, allowing it to accept further alloc,
     824                 :            :  * read, write, invalidate, update or acquire operations.  An attempt will be
     825                 :            :  * made to immediately reattach the cookie to a backing object.  If @aux_data
     826                 :            :  * is set, the auxiliary data attached to the cookie will be updated.
     827                 :            :  *
     828                 :            :  * The can_enable() function is called (if not NULL) once the enablement lock
     829                 :            :  * is held to rule on whether enablement is still permitted to go ahead.
     830                 :            :  */
     831                 :            : static inline
     832                 :          0 : void fscache_enable_cookie(struct fscache_cookie *cookie,
     833                 :            :                            const void *aux_data,
     834                 :            :                            loff_t object_size,
     835                 :            :                            bool (*can_enable)(void *data),
     836                 :            :                            void *data)
     837                 :            : {
     838                 :          0 :         if (fscache_cookie_valid(cookie) && !fscache_cookie_enabled(cookie))
     839                 :          0 :                 __fscache_enable_cookie(cookie, aux_data, object_size,
     840                 :            :                                         can_enable, data);
     841                 :          0 : }
     842                 :            : 
     843                 :            : #endif /* _LINUX_FSCACHE_H */
    

Generated by: LCOV version 1.14