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/* 8 * The inode->i_version field: 9 * --------------------------- 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 * 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 48 * inode_eq_iversion() helper to compare values. 49 * 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. 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. 69 */ 70 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 81/** 82 * inode_set_iversion_raw - set i_version to the specified raw value 83 * @inode: inode to set 84 * @val: new i_version value to set 85 * 86 * Set @inode's i_version field to @val. This function is for use by 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 */ 92static inline void 93inode_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 */ 109static inline u64 110inode_peek_iversion_raw(const struct inode *inode) 111{ 112 return atomic64_read(&inode->i_version); 113} 114 115/** 116 * inode_set_iversion - set i_version to a particular value 117 * @inode: inode to set 118 * @val: new i_version value to set 119 * 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. 123 * 124 * In this case, we do not set the QUERIED flag since we know that this value 125 * has never been queried. 126 */ 127static inline void 128inode_set_iversion(struct inode *inode, u64 val) 129{ 130 inode_set_iversion_raw(inode, val << I_VERSION_QUERIED_SHIFT); 131} 132 133/** 134 * inode_set_iversion_queried - set i_version to a particular value as quereied 135 * @inode: inode to set 136 * @val: new i_version value to set 137 * 138 * Set @inode's i_version field to @val, and flag it for increment on the next 139 * change. 140 * 141 * Filesystems that persistently store the i_version on disk should use this 142 * when loading an existing inode from disk. 143 * 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. 148 */ 149static inline void 150inode_set_iversion_queried(struct inode *inode, u64 val) 151{ 152 inode_set_iversion_raw(inode, (val << I_VERSION_QUERIED_SHIFT) | 153 I_VERSION_QUERIED); 154} 155 156/** 157 * inode_maybe_inc_iversion - increments i_version 158 * @inode: inode with the i_version that should be updated 159 * @force: increment the counter even if it's not necessary? 160 * 161 * Every time the inode is modified, the i_version field must be seen to have 162 * changed by any observer. 163 * 164 * If "force" is set or the QUERIED flag is set, then ensure that we increment 165 * the value, and clear the queried flag. 166 * 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. 172 */ 173static inline bool 174inode_maybe_inc_iversion(struct inode *inode, bool force) 175{ 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; 194 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 } 203 return true; 204} 205 206 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 */ 214static inline void 215inode_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 225 * change. Just fetch the value and check the QUERIED flag. 226 */ 227static inline bool 228inode_iversion_need_inc(struct inode *inode) 229{ 230 return inode_peek_iversion_raw(inode) & I_VERSION_QUERIED; 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 */ 244static inline void 245inode_inc_iversion_raw(struct inode *inode) 246{ 247 atomic64_inc(&inode->i_version); 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 */ 261static inline u64 262inode_peek_iversion(const struct inode *inode) 263{ 264 return inode_peek_iversion_raw(inode) >> I_VERSION_QUERIED_SHIFT; 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 * 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. 279 */ 280static inline u64 281inode_query_iversion(struct inode *inode) 282{ 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; 305} 306 307/** 308 * inode_eq_iversion_raw - check whether the raw i_version counter has changed 309 * @inode: inode to check 310 * @old: old value to check against its i_version 311 * 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. 314 */ 315static inline bool 316inode_eq_iversion_raw(const struct inode *inode, u64 old) 317{ 318 return inode_peek_iversion_raw(inode) == old; 319} 320 321/** 322 * inode_eq_iversion - check whether the i_version counter has changed 323 * @inode: inode to check 324 * @old: old value to check against its i_version 325 * 326 * Compare an i_version counter with a previous one. Returns true if they are 327 * the same, and false if they are different. 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. 331 */ 332static inline bool 333inode_eq_iversion(const struct inode *inode, u64 old) 334{ 335 return inode_peek_iversion(inode) == old; 336} 337#endif 338