include/linux/iversion.h

/* SPDX-License-Identifier: GPL-2.0 */
#ifndef _LINUX_IVERSION_H
#define _LINUX_IVERSION_H

#include <linux/fs.h>

/*
 * The change attribute (i_version) is mandated by NFSv4 and is mostly for
 * knfsd, but is also used for other purposes (e.g. IMA). The i_version must
 * appear different to observers if there was a change to the inode's data or
 * metadata since it was last queried.
 *
 * Observers see the i_version as a 64-bit number that never decreases. If it
 * remains the same since it was last checked, then nothing has changed in the
 * inode. If it's different then something has changed. Observers cannot infer
 * anything about the nature or magnitude of the changes from the value, only
 * that the inode has changed in some fashion.
 *
 * Not all filesystems properly implement the i_version counter. Subsystems that
 * want to use i_version field on an inode should first check whether the
 * filesystem sets the SB_I_VERSION flag (usually via the IS_I_VERSION macro).
 *
 * Those that set SB_I_VERSION will automatically have their i_version counter
 * incremented on writes to normal files. If the SB_I_VERSION is not set, then
 * the VFS will not touch it on writes, and the filesystem can use it how it
 * wishes. Note that the filesystem is always responsible for updating the
 * i_version on namespace changes in directories (mkdir, rmdir, unlink, etc.).
 * We consider these sorts of filesystems to have a kernel-managed i_version.
 *
 * It may be impractical for filesystems to keep i_version updates atomic with
 * respect to the changes that cause them.  They should, however, guarantee
 * that i_version updates are never visible before the changes that caused
 * them.  Also, i_version updates should never be delayed longer than it takes
 * the original change to reach disk.
 *
 * Note that some filesystems (e.g. NFS and AFS) just use the field to store
 * a server-provided value (for the most part). For that reason, those
 * filesystems do not set SB_I_VERSION. These filesystems are considered to
 * have a self-managed i_version.
 */

/**
 * inode_set_iversion_raw - set i_version to the specified raw value
 * @inode: inode to set
 * @new: new i_version value to set
 *
 * Set @inode's i_version field to @new. This function is for use by
 * filesystems that self-manage the i_version.
 *
 * For example, the NFS client stores its NFSv4 change attribute in this way,
 * and the AFS client stores the data_version from the server here.
 */
static inline void
inode_set_iversion_raw(struct inode *inode, u64 new)
{
	inode->i_version = new;
}

/**
 * inode_set_iversion - set i_version to a particular value
 * @inode: inode to set
 * @new: new i_version value to set
 *
 * Set @inode's i_version field to @new. This function is for filesystems with
 * a kernel-managed i_version.
 *
 * For now, this just does the same thing as the _raw variant.
 */
static inline void
inode_set_iversion(struct inode *inode, u64 new)
{
	inode_set_iversion_raw(inode, new);
}

/**
 * inode_set_iversion_queried - set i_version to a particular value and set
 *                              flag to indicate that it has been viewed
 * @inode: inode to set
 * @new: new i_version value to set
 *
 * When loading in an i_version value from a backing store, we typically don't
 * know whether it was previously viewed before being stored or not. Thus, we
 * must assume that it was, to ensure that any changes will result in the
 * value changing.
 *
 * This function will set the inode's i_version, and possibly flag the value
 * as if it has already been viewed at least once.
 *
 * For now, this just does what inode_set_iversion does.
 */
static inline void
inode_set_iversion_queried(struct inode *inode, u64 new)
{
	inode_set_iversion(inode, new);
}

/**
 * inode_maybe_inc_iversion - increments i_version
 * @inode: inode with the i_version that should be updated
 * @force: increment the counter even if it's not necessary
 *
 * Every time the inode is modified, the i_version field must be seen to have
 * changed by any observer.
 *
 * In this implementation, we always increment it after taking the i_lock to
 * ensure that we don't race with other incrementors.
 *
 * Returns true if counter was bumped, and false if it wasn't.
 */
static inline bool
inode_maybe_inc_iversion(struct inode *inode, bool force)
{
	spin_lock(&inode->i_lock);
	inode->i_version++;
	spin_unlock(&inode->i_lock);
	return true;
}

/**
 * inode_inc_iversion - forcibly increment i_version
 * @inode: inode that needs to be updated
 *
 * Forcbily increment the i_version field. This always results in a change to
 * the observable value.
 */
static inline void
inode_inc_iversion(struct inode *inode)
{
	inode_maybe_inc_iversion(inode, true);
}

/**
 * inode_iversion_need_inc - is the i_version in need of being incremented?
 * @inode: inode to check
 *
 * Returns whether the inode->i_version counter needs incrementing on the next
 * change.
 *
 * For now, we assume that it always does.
 */
static inline bool
inode_iversion_need_inc(struct inode *inode)
{
	return true;
}

/**
 * inode_peek_iversion_raw - grab a "raw" iversion value
 * @inode: inode from which i_version should be read
 *
 * Grab a "raw" inode->i_version value and return it. The i_version is not
 * flagged or converted in any way. This is mostly used to access a self-managed
 * i_version.
 *
 * With those filesystems, we want to treat the i_version as an entirely
 * opaque value.
 */
static inline u64
inode_peek_iversion_raw(const struct inode *inode)
{
	return inode->i_version;
}

/**
 * inode_inc_iversion_raw - forcibly increment raw i_version
 * @inode: inode that needs to be updated
 *
 * Forcbily increment the raw i_version field. This always results in a change
 * to the raw value.
 *
 * NFS will use the i_version field to store the value from the server. It
 * mostly treats it as opaque, but in the case where it holds a write
 * delegation, it must increment the value itself. This function does that.
 */
static inline void
inode_inc_iversion_raw(struct inode *inode)
{
	inode_inc_iversion(inode);
}

/**
 * inode_peek_iversion - read i_version without flagging it to be incremented
 * @inode: inode from which i_version should be read
 *
 * Read the inode i_version counter for an inode without registering it as a
 * query.
 *
 * This is typically used by local filesystems that need to store an i_version
 * on disk. In that situation, it's not necessary to flag it as having been
 * viewed, as the result won't be used to gauge changes from that point.
 */
static inline u64
inode_peek_iversion(const struct inode *inode)
{
	return inode_peek_iversion_raw(inode);
}

/**
 * inode_query_iversion - read i_version for later use
 * @inode: inode from which i_version should be read
 *
 * Read the inode i_version counter. This should be used by callers that wish
 * to store the returned i_version for later comparison. This will guarantee
 * that a later query of the i_version will result in a different value if
 * anything has changed.
 *
 * This implementation just does a peek.
 */
static inline u64
inode_query_iversion(struct inode *inode)
{
	return inode_peek_iversion(inode);
}

/**
 * inode_cmp_iversion_raw - check whether the raw i_version counter has changed
 * @inode: inode to check
 * @old: old value to check against its i_version
 *
 * Compare the current raw i_version counter with a previous one. Returns 0 if
 * they are the same or non-zero if they are different.
 */
static inline s64
inode_cmp_iversion_raw(const struct inode *inode, u64 old)
{
	return (s64)inode_peek_iversion_raw(inode) - (s64)old;
}

/**
 * inode_cmp_iversion - check whether the i_version counter has changed
 * @inode: inode to check
 * @old: old value to check against its i_version
 *
 * Compare an i_version counter with a previous one. Returns 0 if they are
 * the same or non-zero if they are different.
 */
static inline s64
inode_cmp_iversion(const struct inode *inode, u64 old)
{
	return (s64)inode_peek_iversion(inode) - (s64)old;
}
#endif