linux-kernel - Re: [PATCH] Updating the documentation of struct file_system

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] [day] [month] [year] [list]

Message-ID: <20201203155203.4dd2736c@lwn.net>
Date:   Thu, 3 Dec 2020 15:52:03 -0700
From:   Jonathan Corbet <corbet@....net>
To:     info@...ocraticnet.de
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Joris Gutjahr <joris.gutjahr@...tonmail.com>,
        Al Viro <viro@...IV.linux.org.uk>,
        linux-fsdevel@...r.kernel.org
Subject: Re: [PATCH] Updating the documentation of struct file_system_type

On Tue,  1 Dec 2020 22:05:51 +0100
info@...ocraticnet.de wrote:

> From: Joris Gutjahr <joris.gutjahr@...tonmail.com>
> 
> In the documentation of struct file_system_type,
> using the definition of the struct of the kernel v5.10-rc6.
> 
> Signed-off-by: Joris Gutjahr <joris.gutjahr@...tonmail.com>

So I applaud any effort to update this file, but I have a couple of
requests.  First is that any patch like this needs to be run past the
filesystem folks; I've added Al and the fsdevel list to CC as a starting
point.

>  Documentation/filesystems/vfs.rst | 28 +++++++++++++++++++++++-----
>  1 file changed, 23 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
> index ca52c82e5bb5..364ef3dcb649 100644
> --- a/Documentation/filesystems/vfs.rst
> +++ b/Documentation/filesystems/vfs.rst
> @@ -107,22 +107,30 @@ file /proc/filesystems.
>  struct file_system_type
>  -----------------------
>  
> -This describes the filesystem.  As of kernel 2.6.39, the following
> -members are defined:
> +This describes the filesystem.  As of kernel v5.10, the following
> +members are defined: (compare: include/linux/fs.h)
>  
>  .. code-block:: c
>  
> -	struct file_system_operations {
> +	struct file_system_type {
>  		const char *name;
>  		int fs_flags;
> +        int (*init_fs_context)(struct fs_context*);
> +        const struct fs_parameter_spec *parameters;
>  		struct dentry *(*mount) (struct file_system_type *, int,
>  					 const char *, void *);
>  		void (*kill_sb) (struct super_block *);
>  		struct module *owner;
>  		struct file_system_type * next;
> -		struct list_head fs_supers;
> +		struct hlist_head fs_supers;
>  		struct lock_class_key s_lock_key;
>  		struct lock_class_key s_umount_key;
> +        struct lock_class_key s_vfs_rename_key;
> +        struct lock_class_key s_writers_key[SB_FREEZE_LEVELS];
> +
> +        struct lock_class_key i_lock_key;
> +        struct lock_class_key i_mutex_key;
> +        struct lock_class_key i_mutex_dir_key;
>  	};
>  
>  ``name``
> @@ -132,6 +140,12 @@ members are defined:
>  ``fs_flags``
>  	various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.)
>  
> +``init_fs_context``
> +    TODO
> +
> +``fs_parameter_spec``
> +    TODO

These are ... not particularly helpful.  If we're going to update the
documentation for this structure, we should actually update the
documentation, methinks.

>  ``mount``
>  	the method to call when a new instance of this filesystem should
>  	be mounted
> @@ -148,7 +162,11 @@ members are defined:
>  ``next``
>  	for internal VFS use: you should initialize this to NULL
>  
> -  s_lock_key, s_umount_key: lockdep-specific
> +``fs_supers``
> +    TODO
> +
> +
> +  s_lock_key, s_umount_key, s_vfs_rename_key, s_writers_key, i_lock_key, i_mutex_key, i_mutex_dir_key: lockdep-specific

You should maintain the RST description-list formatting here.

>  The mount() method has the following arguments:

Thanks,

jon