include/linux/netfs.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /* Network filesystem support services.
0003  *
0004  * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved.
0005  * Written by David Howells (dhowells@redhat.com)
0006  *
0007  * See:
0008  *
0009  *  Documentation/filesystems/netfs_library.rst
0010  *
0011  * for a description of the network filesystem interface declared here.
0012  */
0013
0014 #ifndef _LINUX_NETFS_H
0015 #define _LINUX_NETFS_H
0016
0017 #include <linux/workqueue.h>
0018 #include <linux/fs.h>
0019 #include <linux/pagemap.h>
0020
0021 enum netfs_sreq_ref_trace;
0022
0023 /*
0024  * Overload PG_private_2 to give us PG_fscache - this is used to indicate that
0025  * a page is currently backed by a local disk cache
0026  */
0027 #define folio_test_fscache(folio)   folio_test_private_2(folio)
0028 #define PageFsCache(page)       PagePrivate2((page))
0029 #define SetPageFsCache(page)        SetPagePrivate2((page))
0030 #define ClearPageFsCache(page)      ClearPagePrivate2((page))
0031 #define TestSetPageFsCache(page)    TestSetPagePrivate2((page))
0032 #define TestClearPageFsCache(page)  TestClearPagePrivate2((page))
0033
0034 /**
0035  * folio_start_fscache - Start an fscache write on a folio.
0036  * @folio: The folio.
0037  *
0038  * Call this function before writing a folio to a local cache.  Starting a
0039  * second write before the first one finishes is not allowed.
0040  */
0041 static inline void folio_start_fscache(struct folio *folio)
0042 {
0043     VM_BUG_ON_FOLIO(folio_test_private_2(folio), folio);
0044     folio_get(folio);
0045     folio_set_private_2(folio);
0046 }
0047
0048 /**
0049  * folio_end_fscache - End an fscache write on a folio.
0050  * @folio: The folio.
0051  *
0052  * Call this function after the folio has been written to the local cache.
0053  * This will wake any sleepers waiting on this folio.
0054  */
0055 static inline void folio_end_fscache(struct folio *folio)
0056 {
0057     folio_end_private_2(folio);
0058 }
0059
0060 /**
0061  * folio_wait_fscache - Wait for an fscache write on this folio to end.
0062  * @folio: The folio.
0063  *
0064  * If this folio is currently being written to a local cache, wait for
0065  * the write to finish.  Another write may start after this one finishes,
0066  * unless the caller holds the folio lock.
0067  */
0068 static inline void folio_wait_fscache(struct folio *folio)
0069 {
0070     folio_wait_private_2(folio);
0071 }
0072
0073 /**
0074  * folio_wait_fscache_killable - Wait for an fscache write on this folio to end.
0075  * @folio: The folio.
0076  *
0077  * If this folio is currently being written to a local cache, wait
0078  * for the write to finish or for a fatal signal to be received.
0079  * Another write may start after this one finishes, unless the caller
0080  * holds the folio lock.
0081  *
0082  * Return:
0083  * - 0 if successful.
0084  * - -EINTR if a fatal signal was encountered.
0085  */
0086 static inline int folio_wait_fscache_killable(struct folio *folio)
0087 {
0088     return folio_wait_private_2_killable(folio);
0089 }
0090
0091 static inline void set_page_fscache(struct page *page)
0092 {
0093     folio_start_fscache(page_folio(page));
0094 }
0095
0096 static inline void end_page_fscache(struct page *page)
0097 {
0098     folio_end_private_2(page_folio(page));
0099 }
0100
0101 static inline void wait_on_page_fscache(struct page *page)
0102 {
0103     folio_wait_private_2(page_folio(page));
0104 }
0105
0106 static inline int wait_on_page_fscache_killable(struct page *page)
0107 {
0108     return folio_wait_private_2_killable(page_folio(page));
0109 }
0110
0111 enum netfs_io_source {
0112     NETFS_FILL_WITH_ZEROES,
0113     NETFS_DOWNLOAD_FROM_SERVER,
0114     NETFS_READ_FROM_CACHE,
0115     NETFS_INVALID_READ,
0116 } __mode(byte);
0117
0118 typedef void (*netfs_io_terminated_t)(void *priv, ssize_t transferred_or_error,
0119                       bool was_async);
0120
0121 /*
0122  * Per-inode context.  This wraps the VFS inode.
0123  */
0124 struct netfs_inode {
0125     struct inode        inode;      /* The VFS inode */
0126     const struct netfs_request_ops *ops;
0127 #if IS_ENABLED(CONFIG_FSCACHE)
0128     struct fscache_cookie   *cache;
0129 #endif
0130     loff_t          remote_i_size;  /* Size of the remote file */
0131 };
0132
0133 /*
0134  * Resources required to do operations on a cache.
0135  */
0136 struct netfs_cache_resources {
0137     const struct netfs_cache_ops    *ops;
0138     void                *cache_priv;
0139     void                *cache_priv2;
0140     unsigned int            debug_id;   /* Cookie debug ID */
0141     unsigned int            inval_counter;  /* object->inval_counter at begin_op */
0142 };
0143
0144 /*
0145  * Descriptor for a single component subrequest.
0146  */
0147 struct netfs_io_subrequest {
0148     struct netfs_io_request *rreq;      /* Supervising I/O request */
0149     struct list_head    rreq_link;  /* Link in rreq->subrequests */
0150     loff_t          start;      /* Where to start the I/O */
0151     size_t          len;        /* Size of the I/O */
0152     size_t          transferred;    /* Amount of data transferred */
0153     refcount_t      ref;
0154     short           error;      /* 0 or error that occurred */
0155     unsigned short      debug_index;    /* Index in list (for debugging output) */
0156     enum netfs_io_source    source;     /* Where to read from/write to */
0157     unsigned long       flags;
0158 #define NETFS_SREQ_COPY_TO_CACHE    0   /* Set if should copy the data to the cache */
0159 #define NETFS_SREQ_CLEAR_TAIL       1   /* Set if the rest of the read should be cleared */
0160 #define NETFS_SREQ_SHORT_IO     2   /* Set if the I/O was short */
0161 #define NETFS_SREQ_SEEK_DATA_READ   3   /* Set if ->read() should SEEK_DATA first */
0162 #define NETFS_SREQ_NO_PROGRESS      4   /* Set if we didn't manage to read any data */
0163 #define NETFS_SREQ_ONDEMAND     5   /* Set if it's from on-demand read mode */
0164 };
0165
0166 enum netfs_io_origin {
0167     NETFS_READAHEAD,        /* This read was triggered by readahead */
0168     NETFS_READPAGE,         /* This read is a synchronous read */
0169     NETFS_READ_FOR_WRITE,       /* This read is to prepare a write */
0170 } __mode(byte);
0171
0172 /*
0173  * Descriptor for an I/O helper request.  This is used to make multiple I/O
0174  * operations to a variety of data stores and then stitch the result together.
0175  */
0176 struct netfs_io_request {
0177     struct work_struct  work;
0178     struct inode        *inode;     /* The file being accessed */
0179     struct address_space    *mapping;   /* The mapping being accessed */
0180     struct netfs_cache_resources cache_resources;
0181     struct list_head    subrequests;    /* Contributory I/O operations */
0182     void            *netfs_priv;    /* Private data for the netfs */
0183     unsigned int        debug_id;
0184     atomic_t        nr_outstanding; /* Number of ops in progress */
0185     atomic_t        nr_copy_ops;    /* Number of copy-to-cache ops in progress */
0186     size_t          submitted;  /* Amount submitted for I/O so far */
0187     size_t          len;        /* Length of the request */
0188     short           error;      /* 0 or error that occurred */
0189     enum netfs_io_origin    origin;     /* Origin of the request */
0190     loff_t          i_size;     /* Size of the file */
0191     loff_t          start;      /* Start position */
0192     pgoff_t         no_unlock_folio; /* Don't unlock this folio after read */
0193     refcount_t      ref;
0194     unsigned long       flags;
0195 #define NETFS_RREQ_INCOMPLETE_IO    0   /* Some ioreqs terminated short or with error */
0196 #define NETFS_RREQ_COPY_TO_CACHE    1   /* Need to write to the cache */
0197 #define NETFS_RREQ_NO_UNLOCK_FOLIO  2   /* Don't unlock no_unlock_folio on completion */
0198 #define NETFS_RREQ_DONT_UNLOCK_FOLIOS   3   /* Don't unlock the folios on completion */
0199 #define NETFS_RREQ_FAILED       4   /* The request failed */
0200 #define NETFS_RREQ_IN_PROGRESS      5   /* Unlocked when the request completes */
0201     const struct netfs_request_ops *netfs_ops;
0202 };
0203
0204 /*
0205  * Operations the network filesystem can/must provide to the helpers.
0206  */
0207 struct netfs_request_ops {
0208     int (*init_request)(struct netfs_io_request *rreq, struct file *file);
0209     void (*free_request)(struct netfs_io_request *rreq);
0210     int (*begin_cache_operation)(struct netfs_io_request *rreq);
0211
0212     void (*expand_readahead)(struct netfs_io_request *rreq);
0213     bool (*clamp_length)(struct netfs_io_subrequest *subreq);
0214     void (*issue_read)(struct netfs_io_subrequest *subreq);
0215     bool (*is_still_valid)(struct netfs_io_request *rreq);
0216     int (*check_write_begin)(struct file *file, loff_t pos, unsigned len,
0217                  struct folio **foliop, void **_fsdata);
0218     void (*done)(struct netfs_io_request *rreq);
0219 };
0220
0221 /*
0222  * How to handle reading from a hole.
0223  */
0224 enum netfs_read_from_hole {
0225     NETFS_READ_HOLE_IGNORE,
0226     NETFS_READ_HOLE_CLEAR,
0227     NETFS_READ_HOLE_FAIL,
0228 };
0229
0230 /*
0231  * Table of operations for access to a cache.  This is obtained by
0232  * rreq->ops->begin_cache_operation().
0233  */
0234 struct netfs_cache_ops {
0235     /* End an operation */
0236     void (*end_operation)(struct netfs_cache_resources *cres);
0237
0238     /* Read data from the cache */
0239     int (*read)(struct netfs_cache_resources *cres,
0240             loff_t start_pos,
0241             struct iov_iter *iter,
0242             enum netfs_read_from_hole read_hole,
0243             netfs_io_terminated_t term_func,
0244             void *term_func_priv);
0245
0246     /* Write data to the cache */
0247     int (*write)(struct netfs_cache_resources *cres,
0248              loff_t start_pos,
0249              struct iov_iter *iter,
0250              netfs_io_terminated_t term_func,
0251              void *term_func_priv);
0252
0253     /* Expand readahead request */
0254     void (*expand_readahead)(struct netfs_cache_resources *cres,
0255                  loff_t *_start, size_t *_len, loff_t i_size);
0256
0257     /* Prepare a read operation, shortening it to a cached/uncached
0258      * boundary as appropriate.
0259      */
0260     enum netfs_io_source (*prepare_read)(struct netfs_io_subrequest *subreq,
0261                          loff_t i_size);
0262
0263     /* Prepare a write operation, working out what part of the write we can
0264      * actually do.
0265      */
0266     int (*prepare_write)(struct netfs_cache_resources *cres,
0267                  loff_t *_start, size_t *_len, loff_t i_size,
0268                  bool no_space_allocated_yet);
0269
0270     /* Query the occupancy of the cache in a region, returning where the
0271      * next chunk of data starts and how long it is.
0272      */
0273     int (*query_occupancy)(struct netfs_cache_resources *cres,
0274                    loff_t start, size_t len, size_t granularity,
0275                    loff_t *_data_start, size_t *_data_len);
0276 };
0277
0278 struct readahead_control;
0279 void netfs_readahead(struct readahead_control *);
0280 int netfs_read_folio(struct file *, struct folio *);
0281 int netfs_write_begin(struct netfs_inode *, struct file *,
0282         struct address_space *, loff_t pos, unsigned int len,
0283         struct folio **, void **fsdata);
0284
0285 void netfs_subreq_terminated(struct netfs_io_subrequest *, ssize_t, bool);
0286 void netfs_get_subrequest(struct netfs_io_subrequest *subreq,
0287               enum netfs_sreq_ref_trace what);
0288 void netfs_put_subrequest(struct netfs_io_subrequest *subreq,
0289               bool was_async, enum netfs_sreq_ref_trace what);
0290 void netfs_stats_show(struct seq_file *);
0291
0292 /**
0293  * netfs_inode - Get the netfs inode context from the inode
0294  * @inode: The inode to query
0295  *
0296  * Get the netfs lib inode context from the network filesystem's inode.  The
0297  * context struct is expected to directly follow on from the VFS inode struct.
0298  */
0299 static inline struct netfs_inode *netfs_inode(struct inode *inode)
0300 {
0301     return container_of(inode, struct netfs_inode, inode);
0302 }
0303
0304 /**
0305  * netfs_inode_init - Initialise a netfslib inode context
0306  * @ctx: The netfs inode to initialise
0307  * @ops: The netfs's operations list
0308  *
0309  * Initialise the netfs library context struct.  This is expected to follow on
0310  * directly from the VFS inode struct.
0311  */
0312 static inline void netfs_inode_init(struct netfs_inode *ctx,
0313                     const struct netfs_request_ops *ops)
0314 {
0315     ctx->ops = ops;
0316     ctx->remote_i_size = i_size_read(&ctx->inode);
0317 #if IS_ENABLED(CONFIG_FSCACHE)
0318     ctx->cache = NULL;
0319 #endif
0320 }
0321
0322 /**
0323  * netfs_resize_file - Note that a file got resized
0324  * @ctx: The netfs inode being resized
0325  * @new_i_size: The new file size
0326  *
0327  * Inform the netfs lib that a file got resized so that it can adjust its state.
0328  */
0329 static inline void netfs_resize_file(struct netfs_inode *ctx, loff_t new_i_size)
0330 {
0331     ctx->remote_i_size = new_i_size;
0332 }
0333
0334 /**
0335  * netfs_i_cookie - Get the cache cookie from the inode
0336  * @ctx: The netfs inode to query
0337  *
0338  * Get the caching cookie (if enabled) from the network filesystem's inode.
0339  */
0340 static inline struct fscache_cookie *netfs_i_cookie(struct netfs_inode *ctx)
0341 {
0342 #if IS_ENABLED(CONFIG_FSCACHE)
0343     return ctx->cache;
0344 #else
0345     return NULL;
0346 #endif
0347 }
0348
0349 #endif /* _LINUX_NETFS_H */