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 unsigned int inval_counter; /* object->inval_counter at begin_op */ 128 }; 129 130 /* 131 * Descriptor for a single component subrequest. 132 */ 133 struct netfs_read_subrequest { 134 struct netfs_read_request *rreq; /* Supervising read request */ 135 struct list_head rreq_link; /* Link in rreq->subrequests */ 136 loff_t start; /* Where to start the I/O */ 137 size_t len; /* Size of the I/O */ 138 size_t transferred; /* Amount of data transferred */ 139 refcount_t usage; 140 short error; /* 0 or error that occurred */ 141 unsigned short debug_index; /* Index in list (for debugging output) */ 142 enum netfs_read_source source; /* Where to read from */ 143 unsigned long flags; 144 #define NETFS_SREQ_WRITE_TO_CACHE 0 /* Set if should write to cache */ 145 #define NETFS_SREQ_CLEAR_TAIL 1 /* Set if the rest of the read should be cleared */ 146 #define NETFS_SREQ_SHORT_READ 2 /* Set if there was a short read from the cache */ 147 #define NETFS_SREQ_SEEK_DATA_READ 3 /* Set if ->read() should SEEK_DATA first */ 148 #define NETFS_SREQ_NO_PROGRESS 4 /* Set if we didn't manage to read any data */ 149 }; 150 151 /* 152 * Descriptor for a read helper request. This is used to make multiple I/O 153 * requests on a variety of sources and then stitch the result together. 154 */ 155 struct netfs_read_request { 156 struct work_struct work; 157 struct inode *inode; /* The file being accessed */ 158 struct address_space *mapping; /* The mapping being accessed */ 159 struct netfs_cache_resources cache_resources; 160 struct list_head subrequests; /* Requests to fetch I/O from disk or net */ 161 void *netfs_priv; /* Private data for the netfs */ 162 unsigned int debug_id; 163 atomic_t nr_rd_ops; /* Number of read ops in progress */ 164 atomic_t nr_wr_ops; /* Number of write ops in progress */ 165 size_t submitted; /* Amount submitted for I/O so far */ 166 size_t len; /* Length of the request */ 167 short error; /* 0 or error that occurred */ 168 loff_t i_size; /* Size of the file */ 169 loff_t start; /* Start position */ 170 pgoff_t no_unlock_folio; /* Don't unlock this folio after read */ 171 refcount_t usage; 172 unsigned long flags; 173 #define NETFS_RREQ_INCOMPLETE_IO 0 /* Some ioreqs terminated short or with error */ 174 #define NETFS_RREQ_WRITE_TO_CACHE 1 /* Need to write to the cache */ 175 #define NETFS_RREQ_NO_UNLOCK_FOLIO 2 /* Don't unlock no_unlock_folio on completion */ 176 #define NETFS_RREQ_DONT_UNLOCK_FOLIOS 3 /* Don't unlock the folios on completion */ 177 #define NETFS_RREQ_FAILED 4 /* The request failed */ 178 #define NETFS_RREQ_IN_PROGRESS 5 /* Unlocked when the request completes */ 179 const struct netfs_read_request_ops *netfs_ops; 180 }; 181 182 /* 183 * Operations the network filesystem can/must provide to the helpers. 184 */ 185 struct netfs_read_request_ops { 186 bool (*is_cache_enabled)(struct inode *inode); 187 void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); 188 int (*begin_cache_operation)(struct netfs_read_request *rreq); 189 void (*expand_readahead)(struct netfs_read_request *rreq); 190 bool (*clamp_length)(struct netfs_read_subrequest *subreq); 191 void (*issue_op)(struct netfs_read_subrequest *subreq); 192 bool (*is_still_valid)(struct netfs_read_request *rreq); 193 int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, 194 struct folio *folio, void **_fsdata); 195 void (*done)(struct netfs_read_request *rreq); 196 void (*cleanup)(struct address_space *mapping, void *netfs_priv); 197 }; 198 199 /* 200 * How to handle reading from a hole. 201 */ 202 enum netfs_read_from_hole { 203 NETFS_READ_HOLE_IGNORE, 204 NETFS_READ_HOLE_CLEAR, 205 NETFS_READ_HOLE_FAIL, 206 }; 207 208 /* 209 * Table of operations for access to a cache. This is obtained by 210 * rreq->ops->begin_cache_operation(). 211 */ 212 struct netfs_cache_ops { 213 /* End an operation */ 214 void (*end_operation)(struct netfs_cache_resources *cres); 215 216 /* Read data from the cache */ 217 int (*read)(struct netfs_cache_resources *cres, 218 loff_t start_pos, 219 struct iov_iter *iter, 220 enum netfs_read_from_hole read_hole, 221 netfs_io_terminated_t term_func, 222 void *term_func_priv); 223 224 /* Write data to the cache */ 225 int (*write)(struct netfs_cache_resources *cres, 226 loff_t start_pos, 227 struct iov_iter *iter, 228 netfs_io_terminated_t term_func, 229 void *term_func_priv); 230 231 /* Expand readahead request */ 232 void (*expand_readahead)(struct netfs_cache_resources *cres, 233 loff_t *_start, size_t *_len, loff_t i_size); 234 235 /* Prepare a read operation, shortening it to a cached/uncached 236 * boundary as appropriate. 237 */ 238 enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, 239 loff_t i_size); 240 241 /* Prepare a write operation, working out what part of the write we can 242 * actually do. 243 */ 244 int (*prepare_write)(struct netfs_cache_resources *cres, 245 loff_t *_start, size_t *_len, loff_t i_size, 246 bool no_space_allocated_yet); 247 248 /* Query the occupancy of the cache in a region, returning where the 249 * next chunk of data starts and how long it is. 250 */ 251 int (*query_occupancy)(struct netfs_cache_resources *cres, 252 loff_t start, size_t len, size_t granularity, 253 loff_t *_data_start, size_t *_data_len); 254 }; 255 256 struct readahead_control; 257 extern void netfs_readahead(struct readahead_control *, 258 const struct netfs_read_request_ops *, 259 void *); 260 extern int netfs_readpage(struct file *, 261 struct folio *, 262 const struct netfs_read_request_ops *, 263 void *); 264 extern int netfs_write_begin(struct file *, struct address_space *, 265 loff_t, unsigned int, unsigned int, struct folio **, 266 void **, 267 const struct netfs_read_request_ops *, 268 void *); 269 270 extern void netfs_subreq_terminated(struct netfs_read_subrequest *, ssize_t, bool); 271 extern void netfs_stats_show(struct seq_file *); 272 273 #endif /* _LINUX_NETFS_H */ 274