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 | #include <linux/uio.h> |
21 | |
22 | enum netfs_sreq_ref_trace; |
23 | |
24 | /* |
25 | * Overload PG_private_2 to give us PG_fscache - this is used to indicate that |
26 | * a page is currently backed by a local disk cache |
27 | */ |
28 | #define folio_test_fscache(folio) folio_test_private_2(folio) |
29 | #define PageFsCache(page) PagePrivate2((page)) |
30 | #define SetPageFsCache(page) SetPagePrivate2((page)) |
31 | #define ClearPageFsCache(page) ClearPagePrivate2((page)) |
32 | #define TestSetPageFsCache(page) TestSetPagePrivate2((page)) |
33 | #define TestClearPageFsCache(page) TestClearPagePrivate2((page)) |
34 | |
35 | /** |
36 | * folio_start_fscache - Start an fscache write on a folio. |
37 | * @folio: The folio. |
38 | * |
39 | * Call this function before writing a folio to a local cache. Starting a |
40 | * second write before the first one finishes is not allowed. |
41 | */ |
42 | static inline void folio_start_fscache(struct folio *folio) |
43 | { |
44 | VM_BUG_ON_FOLIO(folio_test_private_2(folio), folio); |
45 | folio_get(folio); |
46 | folio_set_private_2(folio); |
47 | } |
48 | |
49 | /** |
50 | * folio_end_fscache - End an fscache write on a folio. |
51 | * @folio: The folio. |
52 | * |
53 | * Call this function after the folio has been written to the local cache. |
54 | * This will wake any sleepers waiting on this folio. |
55 | */ |
56 | static inline void folio_end_fscache(struct folio *folio) |
57 | { |
58 | folio_end_private_2(folio); |
59 | } |
60 | |
61 | /** |
62 | * folio_wait_fscache - Wait for an fscache write on this folio to end. |
63 | * @folio: The folio. |
64 | * |
65 | * If this folio is currently being written to a local cache, wait for |
66 | * the write to finish. Another write may start after this one finishes, |
67 | * unless the caller holds the folio lock. |
68 | */ |
69 | static inline void folio_wait_fscache(struct folio *folio) |
70 | { |
71 | folio_wait_private_2(folio); |
72 | } |
73 | |
74 | /** |
75 | * folio_wait_fscache_killable - Wait for an fscache write on this folio to end. |
76 | * @folio: The folio. |
77 | * |
78 | * If this folio is currently being written to a local cache, wait |
79 | * for the write to finish or for a fatal signal to be received. |
80 | * Another write may start after this one finishes, unless the caller |
81 | * holds the folio lock. |
82 | * |
83 | * Return: |
84 | * - 0 if successful. |
85 | * - -EINTR if a fatal signal was encountered. |
86 | */ |
87 | static inline int folio_wait_fscache_killable(struct folio *folio) |
88 | { |
89 | return folio_wait_private_2_killable(folio); |
90 | } |
91 | |
92 | static inline void set_page_fscache(struct page *page) |
93 | { |
94 | folio_start_fscache(page_folio(page)); |
95 | } |
96 | |
97 | static inline void end_page_fscache(struct page *page) |
98 | { |
99 | folio_end_private_2(page_folio(page)); |
100 | } |
101 | |
102 | static inline void wait_on_page_fscache(struct page *page) |
103 | { |
104 | folio_wait_private_2(page_folio(page)); |
105 | } |
106 | |
107 | static inline int wait_on_page_fscache_killable(struct page *page) |
108 | { |
109 | return folio_wait_private_2_killable(page_folio(page)); |
110 | } |
111 | |
112 | enum netfs_io_source { |
113 | NETFS_FILL_WITH_ZEROES, |
114 | NETFS_DOWNLOAD_FROM_SERVER, |
115 | NETFS_READ_FROM_CACHE, |
116 | NETFS_INVALID_READ, |
117 | } __mode(byte); |
118 | |
119 | typedef void (*netfs_io_terminated_t)(void *priv, ssize_t transferred_or_error, |
120 | bool was_async); |
121 | |
122 | /* |
123 | * Per-inode context. This wraps the VFS inode. |
124 | */ |
125 | struct netfs_inode { |
126 | struct inode inode; /* The VFS inode */ |
127 | const struct netfs_request_ops *ops; |
128 | #if IS_ENABLED(CONFIG_FSCACHE) |
129 | struct fscache_cookie *cache; |
130 | #endif |
131 | loff_t remote_i_size; /* Size of the remote file */ |
132 | }; |
133 | |
134 | /* |
135 | * Resources required to do operations on a cache. |
136 | */ |
137 | struct netfs_cache_resources { |
138 | const struct netfs_cache_ops *ops; |
139 | void *cache_priv; |
140 | void *cache_priv2; |
141 | unsigned int debug_id; /* Cookie debug ID */ |
142 | unsigned int inval_counter; /* object->inval_counter at begin_op */ |
143 | }; |
144 | |
145 | /* |
146 | * Descriptor for a single component subrequest. |
147 | */ |
148 | struct netfs_io_subrequest { |
149 | struct netfs_io_request *rreq; /* Supervising I/O request */ |
150 | struct list_head rreq_link; /* Link in rreq->subrequests */ |
151 | loff_t start; /* Where to start the I/O */ |
152 | size_t len; /* Size of the I/O */ |
153 | size_t transferred; /* Amount of data transferred */ |
154 | refcount_t ref; |
155 | short error; /* 0 or error that occurred */ |
156 | unsigned short debug_index; /* Index in list (for debugging output) */ |
157 | enum netfs_io_source source; /* Where to read from/write to */ |
158 | unsigned long flags; |
159 | #define NETFS_SREQ_COPY_TO_CACHE 0 /* Set if should copy the data to the cache */ |
160 | #define NETFS_SREQ_CLEAR_TAIL 1 /* Set if the rest of the read should be cleared */ |
161 | #define NETFS_SREQ_SHORT_IO 2 /* Set if the I/O was short */ |
162 | #define NETFS_SREQ_SEEK_DATA_READ 3 /* Set if ->read() should SEEK_DATA first */ |
163 | #define NETFS_SREQ_NO_PROGRESS 4 /* Set if we didn't manage to read any data */ |
164 | #define NETFS_SREQ_ONDEMAND 5 /* Set if it's from on-demand read mode */ |
165 | }; |
166 | |
167 | enum netfs_io_origin { |
168 | NETFS_READAHEAD, /* This read was triggered by readahead */ |
169 | NETFS_READPAGE, /* This read is a synchronous read */ |
170 | NETFS_READ_FOR_WRITE, /* This read is to prepare a write */ |
171 | } __mode(byte); |
172 | |
173 | /* |
174 | * Descriptor for an I/O helper request. This is used to make multiple I/O |
175 | * operations to a variety of data stores and then stitch the result together. |
176 | */ |
177 | struct netfs_io_request { |
178 | struct work_struct work; |
179 | struct inode *inode; /* The file being accessed */ |
180 | struct address_space *mapping; /* The mapping being accessed */ |
181 | struct netfs_cache_resources cache_resources; |
182 | struct list_head subrequests; /* Contributory I/O operations */ |
183 | void *netfs_priv; /* Private data for the netfs */ |
184 | unsigned int debug_id; |
185 | atomic_t nr_outstanding; /* Number of ops in progress */ |
186 | atomic_t nr_copy_ops; /* Number of copy-to-cache ops in progress */ |
187 | size_t submitted; /* Amount submitted for I/O so far */ |
188 | size_t len; /* Length of the request */ |
189 | short error; /* 0 or error that occurred */ |
190 | enum netfs_io_origin origin; /* Origin of the request */ |
191 | loff_t i_size; /* Size of the file */ |
192 | loff_t start; /* Start position */ |
193 | pgoff_t no_unlock_folio; /* Don't unlock this folio after read */ |
194 | refcount_t ref; |
195 | unsigned long flags; |
196 | #define NETFS_RREQ_INCOMPLETE_IO 0 /* Some ioreqs terminated short or with error */ |
197 | #define NETFS_RREQ_COPY_TO_CACHE 1 /* Need to write to the cache */ |
198 | #define NETFS_RREQ_NO_UNLOCK_FOLIO 2 /* Don't unlock no_unlock_folio on completion */ |
199 | #define NETFS_RREQ_DONT_UNLOCK_FOLIOS 3 /* Don't unlock the folios on completion */ |
200 | #define NETFS_RREQ_FAILED 4 /* The request failed */ |
201 | #define NETFS_RREQ_IN_PROGRESS 5 /* Unlocked when the request completes */ |
202 | const struct netfs_request_ops *netfs_ops; |
203 | }; |
204 | |
205 | /* |
206 | * Operations the network filesystem can/must provide to the helpers. |
207 | */ |
208 | struct netfs_request_ops { |
209 | int (*init_request)(struct netfs_io_request *rreq, struct file *file); |
210 | void (*free_request)(struct netfs_io_request *rreq); |
211 | int (*begin_cache_operation)(struct netfs_io_request *rreq); |
212 | |
213 | void (*expand_readahead)(struct netfs_io_request *rreq); |
214 | bool (*clamp_length)(struct netfs_io_subrequest *subreq); |
215 | void (*issue_read)(struct netfs_io_subrequest *subreq); |
216 | bool (*is_still_valid)(struct netfs_io_request *rreq); |
217 | int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, |
218 | struct folio **foliop, void **_fsdata); |
219 | void (*done)(struct netfs_io_request *rreq); |
220 | }; |
221 | |
222 | /* |
223 | * How to handle reading from a hole. |
224 | */ |
225 | enum netfs_read_from_hole { |
226 | NETFS_READ_HOLE_IGNORE, |
227 | NETFS_READ_HOLE_CLEAR, |
228 | NETFS_READ_HOLE_FAIL, |
229 | }; |
230 | |
231 | /* |
232 | * Table of operations for access to a cache. This is obtained by |
233 | * rreq->ops->begin_cache_operation(). |
234 | */ |
235 | struct netfs_cache_ops { |
236 | /* End an operation */ |
237 | void (*end_operation)(struct netfs_cache_resources *cres); |
238 | |
239 | /* Read data from the cache */ |
240 | int (*read)(struct netfs_cache_resources *cres, |
241 | loff_t start_pos, |
242 | struct iov_iter *iter, |
243 | enum netfs_read_from_hole read_hole, |
244 | netfs_io_terminated_t term_func, |
245 | void *term_func_priv); |
246 | |
247 | /* Write data to the cache */ |
248 | int (*write)(struct netfs_cache_resources *cres, |
249 | loff_t start_pos, |
250 | struct iov_iter *iter, |
251 | netfs_io_terminated_t term_func, |
252 | void *term_func_priv); |
253 | |
254 | /* Expand readahead request */ |
255 | void (*expand_readahead)(struct netfs_cache_resources *cres, |
256 | loff_t *_start, size_t *_len, loff_t i_size); |
257 | |
258 | /* Prepare a read operation, shortening it to a cached/uncached |
259 | * boundary as appropriate. |
260 | */ |
261 | enum netfs_io_source (*prepare_read)(struct netfs_io_subrequest *subreq, |
262 | loff_t i_size); |
263 | |
264 | /* Prepare a write operation, working out what part of the write we can |
265 | * actually do. |
266 | */ |
267 | int (*prepare_write)(struct netfs_cache_resources *cres, |
268 | loff_t *_start, size_t *_len, loff_t i_size, |
269 | bool no_space_allocated_yet); |
270 | |
271 | /* Prepare an on-demand read operation, shortening it to a cached/uncached |
272 | * boundary as appropriate. |
273 | */ |
274 | enum netfs_io_source (*prepare_ondemand_read)(struct netfs_cache_resources *cres, |
275 | loff_t start, size_t *_len, |
276 | loff_t i_size, |
277 | unsigned long *_flags, ino_t ino); |
278 | |
279 | /* Query the occupancy of the cache in a region, returning where the |
280 | * next chunk of data starts and how long it is. |
281 | */ |
282 | int (*query_occupancy)(struct netfs_cache_resources *cres, |
283 | loff_t start, size_t len, size_t granularity, |
284 | loff_t *_data_start, size_t *_data_len); |
285 | }; |
286 | |
287 | struct readahead_control; |
288 | void netfs_readahead(struct readahead_control *); |
289 | int netfs_read_folio(struct file *, struct folio *); |
290 | int netfs_write_begin(struct netfs_inode *, struct file *, |
291 | struct address_space *, loff_t pos, unsigned int len, |
292 | struct folio **, void **fsdata); |
293 | |
294 | void netfs_subreq_terminated(struct netfs_io_subrequest *, ssize_t, bool); |
295 | void netfs_get_subrequest(struct netfs_io_subrequest *subreq, |
296 | enum netfs_sreq_ref_trace what); |
297 | void netfs_put_subrequest(struct netfs_io_subrequest *subreq, |
298 | bool was_async, enum netfs_sreq_ref_trace what); |
299 | void netfs_stats_show(struct seq_file *); |
300 | ssize_t (struct iov_iter *orig, size_t orig_len, |
301 | struct iov_iter *new, |
302 | iov_iter_extraction_t ); |
303 | |
304 | /** |
305 | * netfs_inode - Get the netfs inode context from the inode |
306 | * @inode: The inode to query |
307 | * |
308 | * Get the netfs lib inode context from the network filesystem's inode. The |
309 | * context struct is expected to directly follow on from the VFS inode struct. |
310 | */ |
311 | static inline struct netfs_inode *netfs_inode(struct inode *inode) |
312 | { |
313 | return container_of(inode, struct netfs_inode, inode); |
314 | } |
315 | |
316 | /** |
317 | * netfs_inode_init - Initialise a netfslib inode context |
318 | * @ctx: The netfs inode to initialise |
319 | * @ops: The netfs's operations list |
320 | * |
321 | * Initialise the netfs library context struct. This is expected to follow on |
322 | * directly from the VFS inode struct. |
323 | */ |
324 | static inline void netfs_inode_init(struct netfs_inode *ctx, |
325 | const struct netfs_request_ops *ops) |
326 | { |
327 | ctx->ops = ops; |
328 | ctx->remote_i_size = i_size_read(inode: &ctx->inode); |
329 | #if IS_ENABLED(CONFIG_FSCACHE) |
330 | ctx->cache = NULL; |
331 | #endif |
332 | } |
333 | |
334 | /** |
335 | * netfs_resize_file - Note that a file got resized |
336 | * @ctx: The netfs inode being resized |
337 | * @new_i_size: The new file size |
338 | * |
339 | * Inform the netfs lib that a file got resized so that it can adjust its state. |
340 | */ |
341 | static inline void netfs_resize_file(struct netfs_inode *ctx, loff_t new_i_size) |
342 | { |
343 | ctx->remote_i_size = new_i_size; |
344 | } |
345 | |
346 | /** |
347 | * netfs_i_cookie - Get the cache cookie from the inode |
348 | * @ctx: The netfs inode to query |
349 | * |
350 | * Get the caching cookie (if enabled) from the network filesystem's inode. |
351 | */ |
352 | static inline struct fscache_cookie *netfs_i_cookie(struct netfs_inode *ctx) |
353 | { |
354 | #if IS_ENABLED(CONFIG_FSCACHE) |
355 | return ctx->cache; |
356 | #else |
357 | return NULL; |
358 | #endif |
359 | } |
360 | |
361 | #endif /* _LINUX_NETFS_H */ |
362 | |