Re: [PATCH v2] Documentation: filesystems: update filesystem locking documentation

[Jeff Layton <jlayton@redhat.com>]

On Tue, 2017-08-01 at 07:09 -0400, Sean Anderson wrote:
> Documentation/filesystems/Locking no longer reflects current locking
> semantics. i_mutex is no longer used for locking, and has been superseded
> by i_rwsem. Additionally, ->iterate_shared() was not documented.
> 
> Signed-off-by: Sean Anderson <seanga2@gmail.com>
> ---
> v2: changed 'yes's to 'exclusive's when describing i_rwsem usage
> 
>  Documentation/filesystems/Locking | 43 ++++++++++++++++++++++-----------------
>  1 file changed, 24 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
> index fe25787ff6d4..c0cab97d2b1a 100644
> --- a/Documentation/filesystems/Locking
> +++ b/Documentation/filesystems/Locking
> @@ -69,31 +69,31 @@ prototypes:
>  
>  locking rules:
>  	all may block
> -		i_mutex(inode)
> -lookup:		yes
> -create:		yes
> -link:		yes (both)
> -mknod:		yes
> -symlink:	yes
> -mkdir:		yes
> -unlink:		yes (both)
> -rmdir:		yes (both)	(see below)
> -rename:	yes (all)	(see below)
> +		i_rwsem(inode)
> +lookup:		shared
> +create:		exclusive
> +link:		exclusive (both)
> +mknod:		exclusive
> +symlink:	exclusive
> +mkdir:		exclusive
> +unlink:		exclusive (both)
> +rmdir:		exclusive (both)(see below)
> +rename:		exclusive (all)	(see below)
>  readlink:	no
>  get_link:	no
> -setattr:	yes
> +setattr:	exclusive
>  permission:	no (may not block if called in rcu-walk mode)
>  get_acl:	no
>  getattr:	no
>  listxattr:	no
>  fiemap:		no
>  update_time:	no
> -atomic_open:	yes
> +atomic_open:	exclusive
>  tmpfile:	no
>  
>  
> -	Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on
> -victim.
> +	Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
> +	exclusive on victim.
>  	cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
>  
>  See Documentation/filesystems/directory-locking for more detailed discussion
> @@ -111,10 +111,10 @@ prototypes:
>  
>  locking rules:
>  	all may block
> -		i_mutex(inode)
> +		i_rwsem(inode)
>  list:		no
>  get:		no
> -set:		yes
> +set:		exclusive
>  
>  --------------------------- super_operations ---------------------------
>  prototypes:
> @@ -217,14 +217,14 @@ prototypes:
>  locking rules:
>  	All except set_page_dirty and freepage may block
>  
> -			PageLocked(page)	i_mutex
> +			PageLocked(page)	i_rwsem
>  writepage:		yes, unlocks (see below)
>  readpage:		yes, unlocks
>  writepages:
>  set_page_dirty		no
>  readpages:
> -write_begin:		locks the page		yes
> -write_end:		yes, unlocks		yes
> +write_begin:		locks the page		exclusive
> +write_end:		yes, unlocks		exclusive
>  bmap:
>  invalidatepage:		yes
>  releasepage:		yes
> @@ -439,6 +439,7 @@ prototypes:
>  	ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
>  	ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
>  	int (*iterate) (struct file *, struct dir_context *);
> +	int (*iterate_shared) (struct file *, struct dir_context *);
>  	unsigned int (*poll) (struct file *, struct poll_table_struct *);
>  	long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
>  	long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
> @@ -480,6 +481,10 @@ mutex or just to use i_size_read() instead.
>  Note: this does not protect the file->f_pos against concurrent modifications
>  since this is something the userspace has to take care about.
>  
> +->iterate() is called with i_rwsem exclusive.
> +
> +->iterate_shared() is called with i_rwsem at least shared.
> +
>  ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
>  Most instances call fasync_helper(), which does that maintenance, so it's
>  not normally something one needs to worry about.  Return values > 0 will be

Reviewed-by: Jeff Layton <jlayton@redhat.com>