docs: filesystems: vfs: actualize struct super_operations description

Added/updated descriptions for super_operations:
- free_inode method
- evict_inode method
- freeze_super/thaw_super method
- show_{devname,path,stats} procfs-related methods
- get_dquots method

Cc: Eric Biggers <ebiggers@kernel.org>
Cc: Miklos Szeredi <mszeredi@redhat.com>
Cc: Al Viro <viro@zeniv.linux.org.uk>
Cc: Christian Brauner <brauner@kernel.org>
Cc: linux-fsdevel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: Alexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
Reviewed-by: Christian Brauner <brauner@kernel.org>
Link: https://lore.kernel.org/r/20230313130718.253708-3-aleksandr.mikhalitsyn@canonical.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 120c428..769be52 100644 (file)
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -245,33 +245,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.  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
@@ -292,6 +301,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,
@@ -319,8 +333,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
@@ -331,14 +349,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.
@@ -347,22 +376,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.