linux-ext4 - Re: [PATCH 50/50] fs: add documentation explaining the reference count rules for inodes

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250825-evakuieren-ansetzen-105f384692dc@brauner>
Date: Mon, 25 Aug 2025 13:56:06 +0200
From: Christian Brauner <brauner@...nel.org>
To: Josef Bacik <josef@...icpanda.com>
Cc: linux-fsdevel@...r.kernel.org, linux-btrfs@...r.kernel.org, 
	kernel-team@...com, linux-ext4@...r.kernel.org, linux-xfs@...r.kernel.org, 
	viro@...iv.linux.org.uk
Subject: Re: [PATCH 50/50] fs: add documentation explaining the reference
 count rules for inodes

On Thu, Aug 21, 2025 at 04:19:01PM -0400, Josef Bacik wrote:
> 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@...icpanda.com>
> ---
>  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.

It would be awesome if you could document in more detail how LRU
handling and reference counts works.

I_FREEING | I_WILL_FREE was tightly interconnected with LRU handling and
it was frankly a mess to understand so having the new stuff clearly
documented would help us all a lot. Thanks!