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@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. 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!
