Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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 */
39static 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 */
53static 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 */
66static 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 */
84static inline int folio_wait_fscache_killable(struct folio *folio)
85{
86 return folio_wait_private_2_killable(folio);
87}
88
89static inline void set_page_fscache(struct page *page)
90{
91 folio_start_fscache(page_folio(page));
92}
93
94static inline void end_page_fscache(struct page *page)
95{
96 folio_end_private_2(page_folio(page));
97}
98
99static inline void wait_on_page_fscache(struct page *page)
100{
101 folio_wait_private_2(page_folio(page));
102}
103
104static inline int wait_on_page_fscache_killable(struct page *page)
105{
106 return folio_wait_private_2_killable(page_folio(page));
107}
108
109enum 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
116typedef 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 */
122struct 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 */
132struct 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 */
154struct 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 */
184struct 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 */
202struct 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
238struct readahead_control;
239extern void netfs_readahead(struct readahead_control *,
240 const struct netfs_read_request_ops *,
241 void *);
242extern int netfs_readpage(struct file *,
243 struct folio *,
244 const struct netfs_read_request_ops *,
245 void *);
246extern 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
252extern void netfs_subreq_terminated(struct netfs_read_subrequest *, ssize_t, bool);
253extern void netfs_stats_show(struct seq_file *);
254
255#endif /* _LINUX_NETFS_H */