iversion.h 12 KB

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