Merge tag 'media/v4.7-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...

[cascardo/linux.git] / Documentation / filesystems / porting

diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
index f1b87d8..46f3bb7 100644 (file)
--- a/Documentation/filesystems/porting
+++ b/Documentation/filesystems/porting
@@ -525,3 +525,56 @@ in your dentry operations instead.
        set_delayed_call() where it used to set *cookie.
        ->put_link() is gone - just give the destructor to set_delayed_call()
        in ->get_link().
+--
+[mandatory]
+       ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+       dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+       in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
+       called before we attach dentry to inode.
+--
+[mandatory]
+       symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+       i_pipe/i_link union zeroed out at inode eviction.  As the result, you can't
+       assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+       it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
+       to fix shmem_destroy_callback() that used to take that kind of shortcut;
+       watch out, since that shortcut is no longer valid.
+--
+[mandatory]
+       ->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
+       they used to - they just take it exclusive.  However, ->lookup() may be
+       called with parent locked shared.  Its instances must not
+               * use d_instantiate) and d_rehash() separately - use d_add() or
+                 d_splice_alias() instead.
+               * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+               * in the unlikely case when (read-only) access to filesystem
+                 data structures needs exclusion for some reason, arrange it
+                 yourself.  None of the in-tree filesystems needed that.
+               * rely on ->d_parent and ->d_name not changing after dentry has
+                 been fed to d_add() or d_splice_alias().  Again, none of the
+                 in-tree instances relied upon that.
+       We are guaranteed that lookups of the same name in the same directory
+       will not happen in parallel ("same" in the sense of your ->d_compare()).
+       Lookups on different names in the same directory can and do happen in
+       parallel now.
+--
+[recommended]
+       ->iterate_shared() is added; it's a parallel variant of ->iterate().
+       Exclusion on struct file level is still provided (as well as that
+       between it and lseek on the same struct file), but if your directory
+       has been opened several times, you can get these called in parallel.
+       Exclusion between that method and all directory-modifying ones is
+       still provided, of course.
+
+       Often enough ->iterate() can serve as ->iterate_shared() without any
+       changes - it is a read-only operation, after all.  If you have any
+       per-inode or per-dentry in-core data structures modified by ->iterate(),
+       you might need something to serialize the access to them.  If you
+       do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+       that; look for in-tree examples.
+
+       Old method is only used if the new one is absent; eventually it will
+       be removed.  Switch while you still can; the old one won't stay.
+--
+[mandatory]
+       ->atomic_open() calls without O_CREAT may happen in parallel.