[PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[Alexander Mikhalitsyn]

Cc: linux-fsdevel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
---
 Documentation/filesystems/vfs.rst | 74 ++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 15 deletions(-)

diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index fab3bd702250..8671eafa745a 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -242,33 +242,42 @@ struct super_operations
 -----------------------
 
 This describes how the VFS can manipulate the superblock of your
-filesystem.  As of kernel 2.6.22, the following members are defined:
+filesystem.  As of kernel 6.1, the following members are defined:
 
 .. code-block:: c
 
 	struct super_operations {
 		struct inode *(*alloc_inode)(struct super_block *sb);
 		void (*destroy_inode)(struct inode *);
+		void (*free_inode)(struct inode *);
 
 		void (*dirty_inode) (struct inode *, int flags);
-		int (*write_inode) (struct inode *, int);
-		void (*drop_inode) (struct inode *);
-		void (*delete_inode) (struct inode *);
+		int (*write_inode) (struct inode *, struct writeback_control *wbc);
+		int (*drop_inode) (struct inode *);
+		void (*evict_inode) (struct inode *);
 		void (*put_super) (struct super_block *);
 		int (*sync_fs)(struct super_block *sb, int wait);
+		int (*freeze_super) (struct super_block *);
 		int (*freeze_fs) (struct super_block *);
+		int (*thaw_super) (struct super_block *);
 		int (*unfreeze_fs) (struct super_block *);
 		int (*statfs) (struct dentry *, struct kstatfs *);
 		int (*remount_fs) (struct super_block *, int *, char *);
-		void (*clear_inode) (struct inode *);
 		void (*umount_begin) (struct super_block *);
 
 		int (*show_options)(struct seq_file *, struct dentry *);
+		int (*show_devname)(struct seq_file *, struct dentry *);
+		int (*show_path)(struct seq_file *, struct dentry *);
+		int (*show_stats)(struct seq_file *, struct dentry *);
 
 		ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
 		ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
-		int (*nr_cached_objects)(struct super_block *);
-		void (*free_cached_objects)(struct super_block *, int);
+		struct dquot **(*get_dquots)(struct inode *);
+
+		long (*nr_cached_objects)(struct super_block *,
+					struct shrink_control *);
+		long (*free_cached_objects)(struct super_block *,
+					struct shrink_control *);
 	};
 
 All methods are called without any locks being held, unless otherwise
@@ -289,6 +298,11 @@ or bottom half).
 	->alloc_inode was defined and simply undoes anything done by
 	->alloc_inode.
 
+``free_inode``
+	this method is called from RCU callback. If you use call_rcu()
+	in ->destroy_inode to free 'struct inode' memory, then it's
+	better to release memory in this method.
+
 ``dirty_inode``
 	this method is called by the VFS when an inode is marked dirty.
 	This is specifically for the inode itself being marked dirty,
@@ -316,8 +330,12 @@ or bottom half).
 	practice of using "force_delete" in the put_inode() case, but
 	does not have the races that the "force_delete()" approach had.
 
-``delete_inode``
-	called when the VFS wants to delete an inode
+``evict_inode``
+	called when the VFS wants to evict an inode. Caller does
+	*not* evict the pagecache or inode-associated metadata buffers;
+	the method has to use truncate_inode_pages_final() to get rid
+	of those. Caller makes sure async writeback cannot be running for
+	the inode while (or after) ->evict_inode() is called. Optional.
 
 ``put_super``
 	called when the VFS wishes to free the superblock
@@ -328,14 +346,25 @@ or bottom half).
 	superblock.  The second parameter indicates whether the method
 	should wait until the write out has been completed.  Optional.
 
+``freeze_super``
+	Called instead of ->freeze_fs callback if provided.
+	Main difference is that ->freeze_super is called without taking
+	down_write(&sb->s_umount). If filesystem implements it and wants
+	->freeze_fs to be called too, then it has to call ->freeze_fs
+	explicitly from this callback. Optional.
+
 ``freeze_fs``
 	called when VFS is locking a filesystem and forcing it into a
 	consistent state.  This method is currently used by the Logical
-	Volume Manager (LVM).
+	Volume Manager (LVM) and ioctl(FIFREEZE). Optional.
+
+``thaw_super``
+	called when VFS is unlocking a filesystem and making it writable
+	again after ->freeze_super. Optional.
 
 ``unfreeze_fs``
 	called when VFS is unlocking a filesystem and making it writable
-	again.
+	again after ->freeze_fs. Optional.
 
 ``statfs``
 	called when the VFS needs to get filesystem statistics.
@@ -344,22 +373,37 @@ or bottom half).
 	called when the filesystem is remounted.  This is called with
 	the kernel lock held
 
-``clear_inode``
-	called then the VFS clears the inode.  Optional
-
 ``umount_begin``
 	called when the VFS is unmounting a filesystem.
 
 ``show_options``
-	called by the VFS to show mount options for /proc/<pid>/mounts.
+	called by the VFS to show mount options for /proc/<pid>/mounts
+	and /proc/<pid>/mountinfo.
 	(see "Mount Options" section)
 
+``show_devname``
+	Optional. Called by the VFS to show device name for
+	/proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then
+	'(struct mount).mnt_devname' will be used.
+
+``show_path``
+	Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show
+	the mount root dentry path relative to the filesystem root.
+
+``show_stats``
+	Optional. Called by the VFS (for /proc/<pid>/mountstats) to show
+	filesystem-specific mount statistics.
+
 ``quota_read``
 	called by the VFS to read from filesystem quota file.
 
 ``quota_write``
 	called by the VFS to write to filesystem quota file.
 
+``get_dquots``
+	called by quota to get 'struct dquot' array for a particular inode.
+	Optional.
+
 ``nr_cached_objects``
 	called by the sb cache shrinking function for the filesystem to
 	return the number of freeable cached objects it contains.
-- 
2.34.1

Re: [PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[Jonathan Corbet]

Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com> writes:

> Cc: linux-fsdevel@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
> ---
>  Documentation/filesystems/vfs.rst | 74 ++++++++++++++++++++++++-------
>  1 file changed, 59 insertions(+), 15 deletions(-)

Thanks for updating this document!  That said, could I ask you, please,
to resubmit these with a proper changelog?  I'd also suggest copying Al
Viro, who will surely have comments on the changes you have made.

> diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
> index fab3bd702250..8671eafa745a 100644
> --- a/Documentation/filesystems/vfs.rst
> +++ b/Documentation/filesystems/vfs.rst
> @@ -242,33 +242,42 @@ struct super_operations
>  -----------------------
>  
>  This describes how the VFS can manipulate the superblock of your
> -filesystem.  As of kernel 2.6.22, the following members are defined:
> +filesystem.  As of kernel 6.1, the following members are defined:

Why not 6.2 while you're at it?  We might as well be as current as we
can while we're updating things.

Thanks,

jon

Re: [PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[Aleksandr Mikhalitsyn]

On Tue, Jan 31, 2023 at 8:56 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com> writes:
>
> > Cc: linux-fsdevel@vger.kernel.org
> > Cc: linux-doc@vger.kernel.org
> > Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
> > ---
> >  Documentation/filesystems/vfs.rst | 74 ++++++++++++++++++++++++-------
> >  1 file changed, 59 insertions(+), 15 deletions(-)
>
> Thanks for updating this document!  That said, could I ask you, please,
> to resubmit these with a proper changelog?  I'd also suggest copying Al
> Viro, who will surely have comments on the changes you have made.

Hi, Jonathan!

Sure. Have done and of course I've to add Al Viro to CC, but forgot to do that,
cause scripts/get_maintainer.pl have didn't remind me (-:

>
> > diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
> > index fab3bd702250..8671eafa745a 100644
> > --- a/Documentation/filesystems/vfs.rst
> > +++ b/Documentation/filesystems/vfs.rst
> > @@ -242,33 +242,42 @@ struct super_operations
> >  -----------------------
> >
> >  This describes how the VFS can manipulate the superblock of your
> > -filesystem.  As of kernel 2.6.22, the following members are defined:
> > +filesystem.  As of kernel 6.1, the following members are defined:
>
> Why not 6.2 while you're at it?  We might as well be as current as we
> can while we're updating things.

I'm on 6.2, but for some reason decided to put 6.1. Will fix it :)

Thanks,
Alex

>
> Thanks,
>
> jon

Re: [PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[Eric Biggers]

On Tue, Jan 31, 2023 at 10:12:42PM +0100, Aleksandr Mikhalitsyn wrote:
> On Tue, Jan 31, 2023 at 8:56 PM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com> writes:
> >
> > > Cc: linux-fsdevel@vger.kernel.org
> > > Cc: linux-doc@vger.kernel.org
> > > Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
> > > ---
> > >  Documentation/filesystems/vfs.rst | 74 ++++++++++++++++++++++++-------
> > >  1 file changed, 59 insertions(+), 15 deletions(-)
> >
> > Thanks for updating this document!  That said, could I ask you, please,
> > to resubmit these with a proper changelog?  I'd also suggest copying Al
> > Viro, who will surely have comments on the changes you have made.
> 
> Hi, Jonathan!
> 
> Sure. Have done and of course I've to add Al Viro to CC, but forgot to do that,
> cause scripts/get_maintainer.pl have didn't remind me (-:
> 
> >
> > > diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
> > > index fab3bd702250..8671eafa745a 100644
> > > --- a/Documentation/filesystems/vfs.rst
> > > +++ b/Documentation/filesystems/vfs.rst
> > > @@ -242,33 +242,42 @@ struct super_operations
> > >  -----------------------
> > >
> > >  This describes how the VFS can manipulate the superblock of your
> > > -filesystem.  As of kernel 2.6.22, the following members are defined:
> > > +filesystem.  As of kernel 6.1, the following members are defined:
> >
> > Why not 6.2 while you're at it?  We might as well be as current as we
> > can while we're updating things.
> 
> I'm on 6.2, but for some reason decided to put 6.1. Will fix it :)
> 

It would be better to just remove the version number.  Whenever documentation
says something like "as of vX.Y.Z", people usually forget to update the version
number when updating the documentation.  So then we end up in the situation
where the documentation actually describes the latest kernel version, but it
claims to be describing an extremely old kernel version.

- Eric

Re: [PATCH 2/2] docs: filesystems: vfs: actualize struct super_operations description

[Aleksandr Mikhalitsyn]

On Thu, Feb 2, 2023 at 6:25 AM Eric Biggers <ebiggers@kernel.org> wrote:
>
> On Tue, Jan 31, 2023 at 10:12:42PM +0100, Aleksandr Mikhalitsyn wrote:
> > On Tue, Jan 31, 2023 at 8:56 PM Jonathan Corbet <corbet@lwn.net> wrote:
> > >
> > > Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com> writes:
> > >
> > > > Cc: linux-fsdevel@vger.kernel.org
> > > > Cc: linux-doc@vger.kernel.org
> > > > Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
> > > > ---
> > > >  Documentation/filesystems/vfs.rst | 74 ++++++++++++++++++++++++-------
> > > >  1 file changed, 59 insertions(+), 15 deletions(-)
> > >
> > > Thanks for updating this document!  That said, could I ask you, please,
> > > to resubmit these with a proper changelog?  I'd also suggest copying Al
> > > Viro, who will surely have comments on the changes you have made.
> >
> > Hi, Jonathan!
> >
> > Sure. Have done and of course I've to add Al Viro to CC, but forgot to do that,
> > cause scripts/get_maintainer.pl have didn't remind me (-:
> >
> > >
> > > > diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
> > > > index fab3bd702250..8671eafa745a 100644
> > > > --- a/Documentation/filesystems/vfs.rst
> > > > +++ b/Documentation/filesystems/vfs.rst
> > > > @@ -242,33 +242,42 @@ struct super_operations
> > > >  -----------------------
> > > >
> > > >  This describes how the VFS can manipulate the superblock of your
> > > > -filesystem.  As of kernel 2.6.22, the following members are defined:
> > > > +filesystem.  As of kernel 6.1, the following members are defined:
> > >
> > > Why not 6.2 while you're at it?  We might as well be as current as we
> > > can while we're updating things.
> >
> > I'm on 6.2, but for some reason decided to put 6.1. Will fix it :)
> >
>
> It would be better to just remove the version number.  Whenever documentation
> says something like "as of vX.Y.Z", people usually forget to update the version
> number when updating the documentation.  So then we end up in the situation
> where the documentation actually describes the latest kernel version, but it
> claims to be describing an extremely old kernel version.

Hi, Eric!

Agree. Will remove version specifiers in the next resend after Al
Viro's and other folks reviews. :)

Kind regards,
Alex

>
> - Eric