Now that we've made these changes to the inode, document the reference count rules in the vfs documentation. Signed-off-by: Josef Bacik <josef@xxxxxxxxxxxxxx> --- Documentation/filesystems/vfs.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 229eb90c96f2..5bfe7863a5de 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -457,6 +457,29 @@ The Inode Object An inode object represents an object within the filesystem. +Reference counting rules +------------------------ + +The inode is reference counted in two distinct ways, an i_obj_count refcount and +an i_count refcount. These control two different lifetimes of the inode. The +i_obj_count is the simplest, think of it as a reference count on the object +itself. When the i_obj_count reaches zero, the inode is freed. Inode freeing +happens in the RCU context, so the inode is not freed immediately, but rather +after a grace period. + +The i_count reference is the indicator that the inode is "alive". That is to +say, it is available for use by all the ways that a user can access the inode. +Once this count reaches zero, we begin the process of evicting the inode. This +is where the final truncate of an unlinked inode will normally occur. Once +i_count has reached 0, only the final iput() is allowed to do things like +writeback, truncate, etc. All users that want to do these style of operation +must use igrab() or, in very rare and specific circumstances, use +inode_tryget(). + +Every access to an inode must include one of these two references. Generally +i_obj_count is reserved for internal VFS references, the s_inode_list for +example. All file systems should use igrab()/lookup() to get a live reference on +the inode, with very few exceptions. struct inode_operations ----------------------- -- 2.49.0
