Commit | Line | Data |
---|---|---|
ae5e165d JL |
1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | #ifndef _LINUX_IVERSION_H | |
3 | #define _LINUX_IVERSION_H | |
4 | ||
5 | #include <linux/fs.h> | |
6 | ||
7 | /* | |
f02a9ad1 JL |
8 | * The inode->i_version field: |
9 | * --------------------------- | |
ae5e165d JL |
10 | * The change attribute (i_version) is mandated by NFSv4 and is mostly for |
11 | * knfsd, but is also used for other purposes (e.g. IMA). The i_version must | |
12 | * appear different to observers if there was a change to the inode's data or | |
13 | * metadata since it was last queried. | |
14 | * | |
15 | * Observers see the i_version as a 64-bit number that never decreases. If it | |
16 | * remains the same since it was last checked, then nothing has changed in the | |
17 | * inode. If it's different then something has changed. Observers cannot infer | |
18 | * anything about the nature or magnitude of the changes from the value, only | |
19 | * that the inode has changed in some fashion. | |
20 | * | |
21 | * Not all filesystems properly implement the i_version counter. Subsystems that | |
22 | * want to use i_version field on an inode should first check whether the | |
23 | * filesystem sets the SB_I_VERSION flag (usually via the IS_I_VERSION macro). | |
24 | * | |
25 | * Those that set SB_I_VERSION will automatically have their i_version counter | |
26 | * incremented on writes to normal files. If the SB_I_VERSION is not set, then | |
27 | * the VFS will not touch it on writes, and the filesystem can use it how it | |
28 | * wishes. Note that the filesystem is always responsible for updating the | |
29 | * i_version on namespace changes in directories (mkdir, rmdir, unlink, etc.). | |
30 | * We consider these sorts of filesystems to have a kernel-managed i_version. | |
31 | * | |
32 | * It may be impractical for filesystems to keep i_version updates atomic with | |
33 | * respect to the changes that cause them. They should, however, guarantee | |
34 | * that i_version updates are never visible before the changes that caused | |
35 | * them. Also, i_version updates should never be delayed longer than it takes | |
36 | * the original change to reach disk. | |
37 | * | |
f02a9ad1 JL |
38 | * This implementation uses the low bit in the i_version field as a flag to |
39 | * track when the value has been queried. If it has not been queried since it | |
40 | * was last incremented, we can skip the increment in most cases. | |
41 | * | |
42 | * In the event that we're updating the ctime, we will usually go ahead and | |
43 | * bump the i_version anyway. Since that has to go to stable storage in some | |
44 | * fashion, we might as well increment it as well. | |
45 | * | |
46 | * With this implementation, the value should always appear to observers to | |
47 | * increase over time if the file has changed. It's recommended to use | |
c472c07b | 48 | * inode_eq_iversion() helper to compare values. |
f02a9ad1 | 49 | * |
ae5e165d JL |
50 | * Note that some filesystems (e.g. NFS and AFS) just use the field to store |
51 | * a server-provided value (for the most part). For that reason, those | |
52 | * filesystems do not set SB_I_VERSION. These filesystems are considered to | |
53 | * have a self-managed i_version. | |
f02a9ad1 JL |
54 | * |
55 | * Persistently storing the i_version | |
56 | * ---------------------------------- | |
57 | * Queries of the i_version field are not gated on them hitting the backing | |
58 | * store. It's always possible that the host could crash after allowing | |
59 | * a query of the value but before it has made it to disk. | |
60 | * | |
61 | * To mitigate this problem, filesystems should always use | |
62 | * inode_set_iversion_queried when loading an existing inode from disk. This | |
63 | * ensures that the next attempted inode increment will result in the value | |
64 | * changing. | |
65 | * | |
66 | * Storing the value to disk therefore does not count as a query, so those | |
67 | * filesystems should use inode_peek_iversion to grab the value to be stored. | |
68 | * There is no need to flag the value as having been queried in that case. | |
ae5e165d JL |
69 | */ |
70 | ||
f02a9ad1 JL |
71 | /* |
72 | * We borrow the lowest bit in the i_version to use as a flag to tell whether | |
73 | * it has been queried since we last incremented it. If it has, then we must | |
74 | * increment it on the next change. After that, we can clear the flag and | |
75 | * avoid incrementing it again until it has again been queried. | |
76 | */ | |
77 | #define I_VERSION_QUERIED_SHIFT (1) | |
78 | #define I_VERSION_QUERIED (1ULL << (I_VERSION_QUERIED_SHIFT - 1)) | |
79 | #define I_VERSION_INCREMENT (1ULL << I_VERSION_QUERIED_SHIFT) | |
80 | ||
ae5e165d JL |
81 | /** |
82 | * inode_set_iversion_raw - set i_version to the specified raw value | |
83 | * @inode: inode to set | |
f02a9ad1 | 84 | * @val: new i_version value to set |
ae5e165d | 85 | * |
f02a9ad1 | 86 | * Set @inode's i_version field to @val. This function is for use by |
ae5e165d JL |
87 | * filesystems that self-manage the i_version. |
88 | * | |
89 | * For example, the NFS client stores its NFSv4 change attribute in this way, | |
90 | * and the AFS client stores the data_version from the server here. | |
91 | */ | |
92 | static inline void | |
f02a9ad1 JL |
93 | inode_set_iversion_raw(struct inode *inode, u64 val) |
94 | { | |
95 | atomic64_set(&inode->i_version, val); | |
96 | } | |
97 | ||
98 | /** | |
99 | * inode_peek_iversion_raw - grab a "raw" iversion value | |
100 | * @inode: inode from which i_version should be read | |
101 | * | |
102 | * Grab a "raw" inode->i_version value and return it. The i_version is not | |
103 | * flagged or converted in any way. This is mostly used to access a self-managed | |
104 | * i_version. | |
105 | * | |
106 | * With those filesystems, we want to treat the i_version as an entirely | |
107 | * opaque value. | |
108 | */ | |
109 | static inline u64 | |
110 | inode_peek_iversion_raw(const struct inode *inode) | |
ae5e165d | 111 | { |
f02a9ad1 | 112 | return atomic64_read(&inode->i_version); |
ae5e165d JL |
113 | } |
114 | ||
115 | /** | |
116 | * inode_set_iversion - set i_version to a particular value | |
117 | * @inode: inode to set | |
f02a9ad1 | 118 | * @val: new i_version value to set |
ae5e165d | 119 | * |
f02a9ad1 JL |
120 | * Set @inode's i_version field to @val. This function is for filesystems with |
121 | * a kernel-managed i_version, for initializing a newly-created inode from | |
122 | * scratch. | |
ae5e165d | 123 | * |
f02a9ad1 JL |
124 | * In this case, we do not set the QUERIED flag since we know that this value |
125 | * has never been queried. | |
ae5e165d JL |
126 | */ |
127 | static inline void | |
f02a9ad1 | 128 | inode_set_iversion(struct inode *inode, u64 val) |
ae5e165d | 129 | { |
f02a9ad1 | 130 | inode_set_iversion_raw(inode, val << I_VERSION_QUERIED_SHIFT); |
ae5e165d JL |
131 | } |
132 | ||
133 | /** | |
f02a9ad1 | 134 | * inode_set_iversion_queried - set i_version to a particular value as quereied |
ae5e165d | 135 | * @inode: inode to set |
f02a9ad1 | 136 | * @val: new i_version value to set |
ae5e165d | 137 | * |
f02a9ad1 JL |
138 | * Set @inode's i_version field to @val, and flag it for increment on the next |
139 | * change. | |
ae5e165d | 140 | * |
f02a9ad1 JL |
141 | * Filesystems that persistently store the i_version on disk should use this |
142 | * when loading an existing inode from disk. | |
ae5e165d | 143 | * |
f02a9ad1 JL |
144 | * When loading in an i_version value from a backing store, we can't be certain |
145 | * that it wasn't previously viewed before being stored. Thus, we must assume | |
146 | * that it was, to ensure that we don't end up handing out the same value for | |
147 | * different versions of the same inode. | |
ae5e165d JL |
148 | */ |
149 | static inline void | |
f02a9ad1 | 150 | inode_set_iversion_queried(struct inode *inode, u64 val) |
ae5e165d | 151 | { |
f02a9ad1 JL |
152 | inode_set_iversion_raw(inode, (val << I_VERSION_QUERIED_SHIFT) | |
153 | I_VERSION_QUERIED); | |
ae5e165d JL |
154 | } |
155 | ||
156 | /** | |
157 | * inode_maybe_inc_iversion - increments i_version | |
158 | * @inode: inode with the i_version that should be updated | |
f02a9ad1 | 159 | * @force: increment the counter even if it's not necessary? |
ae5e165d JL |
160 | * |
161 | * Every time the inode is modified, the i_version field must be seen to have | |
162 | * changed by any observer. | |
163 | * | |
f02a9ad1 JL |
164 | * If "force" is set or the QUERIED flag is set, then ensure that we increment |
165 | * the value, and clear the queried flag. | |
ae5e165d | 166 | * |
f02a9ad1 JL |
167 | * In the common case where neither is set, then we can return "false" without |
168 | * updating i_version. | |
169 | * | |
170 | * If this function returns false, and no other metadata has changed, then we | |
171 | * can avoid logging the metadata. | |
ae5e165d JL |
172 | */ |
173 | static inline bool | |
174 | inode_maybe_inc_iversion(struct inode *inode, bool force) | |
175 | { | |
f02a9ad1 JL |
176 | u64 cur, old, new; |
177 | ||
178 | /* | |
179 | * The i_version field is not strictly ordered with any other inode | |
180 | * information, but the legacy inode_inc_iversion code used a spinlock | |
181 | * to serialize increments. | |
182 | * | |
183 | * Here, we add full memory barriers to ensure that any de-facto | |
184 | * ordering with other info is preserved. | |
185 | * | |
186 | * This barrier pairs with the barrier in inode_query_iversion() | |
187 | */ | |
188 | smp_mb(); | |
189 | cur = inode_peek_iversion_raw(inode); | |
190 | for (;;) { | |
191 | /* If flag is clear then we needn't do anything */ | |
192 | if (!force && !(cur & I_VERSION_QUERIED)) | |
193 | return false; | |
7594c461 | 194 | |
f02a9ad1 JL |
195 | /* Since lowest bit is flag, add 2 to avoid it */ |
196 | new = (cur & ~I_VERSION_QUERIED) + I_VERSION_INCREMENT; | |
197 | ||
198 | old = atomic64_cmpxchg(&inode->i_version, cur, new); | |
199 | if (likely(old == cur)) | |
200 | break; | |
201 | cur = old; | |
202 | } | |
ae5e165d JL |
203 | return true; |
204 | } | |
205 | ||
7594c461 | 206 | |
ae5e165d JL |
207 | /** |
208 | * inode_inc_iversion - forcibly increment i_version | |
209 | * @inode: inode that needs to be updated | |
210 | * | |
211 | * Forcbily increment the i_version field. This always results in a change to | |
212 | * the observable value. | |
213 | */ | |
214 | static inline void | |
215 | inode_inc_iversion(struct inode *inode) | |
216 | { | |
217 | inode_maybe_inc_iversion(inode, true); | |
218 | } | |
219 | ||
220 | /** | |
221 | * inode_iversion_need_inc - is the i_version in need of being incremented? | |
222 | * @inode: inode to check | |
223 | * | |
224 | * Returns whether the inode->i_version counter needs incrementing on the next | |
f02a9ad1 | 225 | * change. Just fetch the value and check the QUERIED flag. |
ae5e165d JL |
226 | */ |
227 | static inline bool | |
228 | inode_iversion_need_inc(struct inode *inode) | |
229 | { | |
f02a9ad1 | 230 | return inode_peek_iversion_raw(inode) & I_VERSION_QUERIED; |
ae5e165d JL |
231 | } |
232 | ||
233 | /** | |
234 | * inode_inc_iversion_raw - forcibly increment raw i_version | |
235 | * @inode: inode that needs to be updated | |
236 | * | |
237 | * Forcbily increment the raw i_version field. This always results in a change | |
238 | * to the raw value. | |
239 | * | |
240 | * NFS will use the i_version field to store the value from the server. It | |
241 | * mostly treats it as opaque, but in the case where it holds a write | |
242 | * delegation, it must increment the value itself. This function does that. | |
243 | */ | |
244 | static inline void | |
245 | inode_inc_iversion_raw(struct inode *inode) | |
246 | { | |
f02a9ad1 | 247 | atomic64_inc(&inode->i_version); |
ae5e165d JL |
248 | } |
249 | ||
250 | /** | |
251 | * inode_peek_iversion - read i_version without flagging it to be incremented | |
252 | * @inode: inode from which i_version should be read | |
253 | * | |
254 | * Read the inode i_version counter for an inode without registering it as a | |
255 | * query. | |
256 | * | |
257 | * This is typically used by local filesystems that need to store an i_version | |
258 | * on disk. In that situation, it's not necessary to flag it as having been | |
259 | * viewed, as the result won't be used to gauge changes from that point. | |
260 | */ | |
261 | static inline u64 | |
262 | inode_peek_iversion(const struct inode *inode) | |
263 | { | |
f02a9ad1 | 264 | return inode_peek_iversion_raw(inode) >> I_VERSION_QUERIED_SHIFT; |
ae5e165d JL |
265 | } |
266 | ||
267 | /** | |
268 | * inode_query_iversion - read i_version for later use | |
269 | * @inode: inode from which i_version should be read | |
270 | * | |
271 | * Read the inode i_version counter. This should be used by callers that wish | |
272 | * to store the returned i_version for later comparison. This will guarantee | |
273 | * that a later query of the i_version will result in a different value if | |
274 | * anything has changed. | |
275 | * | |
f02a9ad1 JL |
276 | * In this implementation, we fetch the current value, set the QUERIED flag and |
277 | * then try to swap it into place with a cmpxchg, if it wasn't already set. If | |
278 | * that fails, we try again with the newly fetched value from the cmpxchg. | |
ae5e165d JL |
279 | */ |
280 | static inline u64 | |
281 | inode_query_iversion(struct inode *inode) | |
282 | { | |
f02a9ad1 JL |
283 | u64 cur, old, new; |
284 | ||
285 | cur = inode_peek_iversion_raw(inode); | |
286 | for (;;) { | |
287 | /* If flag is already set, then no need to swap */ | |
288 | if (cur & I_VERSION_QUERIED) { | |
289 | /* | |
290 | * This barrier (and the implicit barrier in the | |
291 | * cmpxchg below) pairs with the barrier in | |
292 | * inode_maybe_inc_iversion(). | |
293 | */ | |
294 | smp_mb(); | |
295 | break; | |
296 | } | |
297 | ||
298 | new = cur | I_VERSION_QUERIED; | |
299 | old = atomic64_cmpxchg(&inode->i_version, cur, new); | |
300 | if (likely(old == cur)) | |
301 | break; | |
302 | cur = old; | |
303 | } | |
304 | return cur >> I_VERSION_QUERIED_SHIFT; | |
ae5e165d JL |
305 | } |
306 | ||
307 | /** | |
c472c07b | 308 | * inode_eq_iversion_raw - check whether the raw i_version counter has changed |
ae5e165d JL |
309 | * @inode: inode to check |
310 | * @old: old value to check against its i_version | |
311 | * | |
c472c07b GB |
312 | * Compare the current raw i_version counter with a previous one. Returns true |
313 | * if they are the same or false if they are different. | |
ae5e165d | 314 | */ |
c0cef30e | 315 | static inline bool |
c472c07b | 316 | inode_eq_iversion_raw(const struct inode *inode, u64 old) |
ae5e165d | 317 | { |
c472c07b | 318 | return inode_peek_iversion_raw(inode) == old; |
ae5e165d JL |
319 | } |
320 | ||
321 | /** | |
c472c07b | 322 | * inode_eq_iversion - check whether the i_version counter has changed |
ae5e165d JL |
323 | * @inode: inode to check |
324 | * @old: old value to check against its i_version | |
325 | * | |
c472c07b GB |
326 | * Compare an i_version counter with a previous one. Returns true if they are |
327 | * the same, and false if they are different. | |
f02a9ad1 JL |
328 | * |
329 | * Note that we don't need to set the QUERIED flag in this case, as the value | |
330 | * in the inode is not being recorded for later use. | |
ae5e165d | 331 | */ |
c0cef30e | 332 | static inline bool |
c472c07b | 333 | inode_eq_iversion(const struct inode *inode, u64 old) |
ae5e165d | 334 | { |
c472c07b | 335 | return inode_peek_iversion(inode) == old; |
ae5e165d JL |
336 | } |
337 | #endif |