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 */
folio_start_fscache(struct folio * folio)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 */
folio_end_fscache(struct folio * folio)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 */
folio_wait_fscache(struct folio * folio)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 */
folio_wait_fscache_killable(struct folio * folio)84 static inline int folio_wait_fscache_killable(struct folio *folio)
85 {
86 return folio_wait_private_2_killable(folio);
87 }
88
set_page_fscache(struct page * page)89 static inline void set_page_fscache(struct page *page)
90 {
91 folio_start_fscache(page_folio(page));
92 }
93
end_page_fscache(struct page * page)94 static inline void end_page_fscache(struct page *page)
95 {
96 folio_end_private_2(page_folio(page));
97 }
98
wait_on_page_fscache(struct page * page)99 static inline void wait_on_page_fscache(struct page *page)
100 {
101 folio_wait_private_2(page_folio(page));
102 }
103
wait_on_page_fscache_killable(struct page * page)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