1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* Network filesystem support services. 3 * 4 * Copyright (C) 2021 Red Hat, Inc. All Rights Reserved. 5 * Written by David Howells (dhowells@redhat.com) 6 * 7 * See: 8 * 9 * Documentation/filesystems/netfs_library.rst 10 * 11 * for a description of the network filesystem interface declared here. 12 */ 13 14 #ifndef _LINUX_NETFS_H 15 #define _LINUX_NETFS_H 16 17 #include <linux/workqueue.h> 18 #include <linux/fs.h> 19 #include <linux/pagemap.h> 20 21 /* 22 * Overload PG_private_2 to give us PG_fscache - this is used to indicate that 23 * a page is currently backed by a local disk cache 24 */ 25 #define folio_test_fscache(folio) folio_test_private_2(folio) 26 #define PageFsCache(page) PagePrivate2((page)) 27 #define SetPageFsCache(page) SetPagePrivate2((page)) 28 #define ClearPageFsCache(page) ClearPagePrivate2((page)) 29 #define TestSetPageFsCache(page) TestSetPagePrivate2((page)) 30 #define TestClearPageFsCache(page) TestClearPagePrivate2((page)) 31 32 /** 33 * folio_start_fscache - Start an fscache write on a folio. 34 * @folio: The folio. 35 * 36 * Call this function before writing a folio to a local cache. Starting a 37 * second write before the first one finishes is not allowed. 38 */ 39 static inline void folio_start_fscache(struct folio *folio) 40 { 41 VM_BUG_ON_FOLIO(folio_test_private_2(folio), folio); 42 folio_get(folio); 43 folio_set_private_2(folio); 44 } 45 46 /** 47 * folio_end_fscache - End an fscache write on a folio. 48 * @folio: The folio. 49 * 50 * Call this function after the folio has been written to the local cache. 51 * This will wake any sleepers waiting on this folio. 52 */ 53 static inline void folio_end_fscache(struct folio *folio) 54 { 55 folio_end_private_2(folio); 56 } 57 58 /** 59 * folio_wait_fscache - Wait for an fscache write on this folio to end. 60 * @folio: The folio. 61 * 62 * If this folio is currently being written to a local cache, wait for 63 * the write to finish. Another write may start after this one finishes, 64 * unless the caller holds the folio lock. 65 */ 66 static inline void folio_wait_fscache(struct folio *folio) 67 { 68 folio_wait_private_2(folio); 69 } 70 71 /** 72 * folio_wait_fscache_killable - Wait for an fscache write on this folio to end. 73 * @folio: The folio. 74 * 75 * If this folio is currently being written to a local cache, wait 76 * for the write to finish or for a fatal signal to be received. 77 * Another write may start after this one finishes, unless the caller 78 * holds the folio lock. 79 * 80 * Return: 81 * - 0 if successful. 82 * - -EINTR if a fatal signal was encountered. 83 */ 84 static inline int folio_wait_fscache_killable(struct folio *folio) 85 { 86 return folio_wait_private_2_killable(folio); 87 } 88 89 static inline void set_page_fscache(struct page *page) 90 { 91 folio_start_fscache(page_folio(page)); 92 } 93 94 static inline void end_page_fscache(struct page *page) 95 { 96 folio_end_private_2(page_folio(page)); 97 } 98 99 static inline void wait_on_page_fscache(struct page *page) 100 { 101 folio_wait_private_2(page_folio(page)); 102 } 103 104 static inline int wait_on_page_fscache_killable(struct page *page) 105 { 106 return folio_wait_private_2_killable(page_folio(page)); 107 } 108 109 enum netfs_read_source { 110 NETFS_FILL_WITH_ZEROES, 111 NETFS_DOWNLOAD_FROM_SERVER, 112 NETFS_READ_FROM_CACHE, 113 NETFS_INVALID_READ, 114 } __mode(byte); 115 116 typedef void (*netfs_io_terminated_t)(void *priv, ssize_t transferred_or_error, 117 bool was_async); 118 119 /* 120 * Resources required to do operations on a cache. 121 */ 122 struct netfs_cache_resources { 123 const struct netfs_cache_ops *ops; 124 void *cache_priv; 125 void *cache_priv2; 126 unsigned int debug_id; /* Cookie debug ID */ 127 }; 128 129 /* 130 * Descriptor for a single component subrequest. 131 */ 132 struct netfs_read_subrequest { 133 struct netfs_read_request *rreq; /* Supervising read request */ 134 struct list_head rreq_link; /* Link in rreq->subrequests */ 135 loff_t start; /* Where to start the I/O */ 136 size_t len; /* Size of the I/O */ 137 size_t transferred; /* Amount of data transferred */ 138 refcount_t usage; 139 short error; /* 0 or error that occurred */ 140 unsigned short debug_index; /* Index in list (for debugging output) */ 141 enum netfs_read_source source; /* Where to read from */ 142 unsigned long flags; 143 #define NETFS_SREQ_WRITE_TO_CACHE 0 /* Set if should write to cache */ 144 #define NETFS_SREQ_CLEAR_TAIL 1 /* Set if the rest of the read should be cleared */ 145 #define NETFS_SREQ_SHORT_READ 2 /* Set if there was a short read from the cache */ 146 #define NETFS_SREQ_SEEK_DATA_READ 3 /* Set if ->read() should SEEK_DATA first */ 147 #define NETFS_SREQ_NO_PROGRESS 4 /* Set if we didn't manage to read any data */ 148 }; 149 150 /* 151 * Descriptor for a read helper request. This is used to make multiple I/O 152 * requests on a variety of sources and then stitch the result together. 153 */ 154 struct netfs_read_request { 155 struct work_struct work; 156 struct inode *inode; /* The file being accessed */ 157 struct address_space *mapping; /* The mapping being accessed */ 158 struct netfs_cache_resources cache_resources; 159 struct list_head subrequests; /* Requests to fetch I/O from disk or net */ 160 void *netfs_priv; /* Private data for the netfs */ 161 unsigned int debug_id; 162 atomic_t nr_rd_ops; /* Number of read ops in progress */ 163 atomic_t nr_wr_ops; /* Number of write ops in progress */ 164 size_t submitted; /* Amount submitted for I/O so far */ 165 size_t len; /* Length of the request */ 166 short error; /* 0 or error that occurred */ 167 loff_t i_size; /* Size of the file */ 168 loff_t start; /* Start position */ 169 pgoff_t no_unlock_folio; /* Don't unlock this folio after read */ 170 refcount_t usage; 171 unsigned long flags; 172 #define NETFS_RREQ_INCOMPLETE_IO 0 /* Some ioreqs terminated short or with error */ 173 #define NETFS_RREQ_WRITE_TO_CACHE 1 /* Need to write to the cache */ 174 #define NETFS_RREQ_NO_UNLOCK_FOLIO 2 /* Don't unlock no_unlock_folio on completion */ 175 #define NETFS_RREQ_DONT_UNLOCK_FOLIOS 3 /* Don't unlock the folios on completion */ 176 #define NETFS_RREQ_FAILED 4 /* The request failed */ 177 #define NETFS_RREQ_IN_PROGRESS 5 /* Unlocked when the request completes */ 178 const struct netfs_read_request_ops *netfs_ops; 179 }; 180 181 /* 182 * Operations the network filesystem can/must provide to the helpers. 183 */ 184 struct netfs_read_request_ops { 185 bool (*is_cache_enabled)(struct inode *inode); 186 void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); 187 int (*begin_cache_operation)(struct netfs_read_request *rreq); 188 void (*expand_readahead)(struct netfs_read_request *rreq); 189 bool (*clamp_length)(struct netfs_read_subrequest *subreq); 190 void (*issue_op)(struct netfs_read_subrequest *subreq); 191 bool (*is_still_valid)(struct netfs_read_request *rreq); 192 int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, 193 struct folio *folio, void **_fsdata); 194 void (*done)(struct netfs_read_request *rreq); 195 void (*cleanup)(struct address_space *mapping, void *netfs_priv); 196 }; 197 198 /* 199 * Table of operations for access to a cache. This is obtained by 200 * rreq->ops->begin_cache_operation(). 201 */ 202 struct netfs_cache_ops { 203 /* End an operation */ 204 void (*end_operation)(struct netfs_cache_resources *cres); 205 206 /* Read data from the cache */ 207 int (*read)(struct netfs_cache_resources *cres, 208 loff_t start_pos, 209 struct iov_iter *iter, 210 bool seek_data, 211 netfs_io_terminated_t term_func, 212 void *term_func_priv); 213 214 /* Write data to the cache */ 215 int (*write)(struct netfs_cache_resources *cres, 216 loff_t start_pos, 217 struct iov_iter *iter, 218 netfs_io_terminated_t term_func, 219 void *term_func_priv); 220 221 /* Expand readahead request */ 222 void (*expand_readahead)(struct netfs_cache_resources *cres, 223 loff_t *_start, size_t *_len, loff_t i_size); 224 225 /* Prepare a read operation, shortening it to a cached/uncached 226 * boundary as appropriate. 227 */ 228 enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, 229 loff_t i_size); 230 231 /* Prepare a write operation, working out what part of the write we can 232 * actually do. 233 */ 234 int (*prepare_write)(struct netfs_cache_resources *cres, 235 loff_t *_start, size_t *_len, loff_t i_size); 236 }; 237 238 struct readahead_control; 239 extern void netfs_readahead(struct readahead_control *, 240 const struct netfs_read_request_ops *, 241 void *); 242 extern int netfs_readpage(struct file *, 243 struct folio *, 244 const struct netfs_read_request_ops *, 245 void *); 246 extern int netfs_write_begin(struct file *, struct address_space *, 247 loff_t, unsigned int, unsigned int, struct folio **, 248 void **, 249 const struct netfs_read_request_ops *, 250 void *); 251 252 extern void netfs_subreq_terminated(struct netfs_read_subrequest *, ssize_t, bool); 253 extern void netfs_stats_show(struct seq_file *); 254 255 #endif /* _LINUX_NETFS_H */ 256