Documentation/filesystems/porting.rst

5 ---
16 ---
20 New methods: ->alloc_inode() and ->destroy_inode().
22 Remove inode->u.foo_inode_i
27 		/* fs-private stuff */
35 Use FOO_I(inode) instead of &inode->u.foo_inode_i;
37 Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
38 foo_inode_info and return the address of ->vfs_inode, the latter should free
39 FOO_I(inode) (see in-tree filesystems for examples).
41 Make them ->alloc_inode and ->destroy_inode in your super_operations.
48 ---
52 Change of file_system_type method (->read_super to ->get_sb)
54 ->read_super() is no more.  Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
57 success and negative number in case of error (-EINVAL unless you have more
70 Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
73 ---
77 Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
79 global exclusion between renames for some internal purpose - you need to
83 ---
87 Now we have the exclusion between ->lookup() and directory removal (by
88 ->rmdir() and ->rename()).  If you used to need that exclusion and do
89 it by internal locking (most of filesystems couldn't care less) - you
92 ---
96 ->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
97 ->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
98 and ->readdir() are called without BKL now.  Grab it on entry, drop upon return
99 - that will guarantee the same locking you used to have.  If your method or its
100 parts do not need BKL - better yet, now you can shift lock_kernel() and
101 unlock_kernel() so that they would protect exactly what needs to be
104 ---
111 ---
115 check for ->link() target not being a directory is done by callers.  Feel
118 ---
122 ->link() callers hold ->i_mutex on the object we are linking to.  Some of your
125 ---
129 new file_system_type method - kill_sb(superblock).  If you are converting
130 an existing filesystem, set it according to ->fs_flags::
132 	FS_REQUIRES_DEV		-	kill_block_super
133 	FS_LITTER		-	kill_litter_super
134 	neither			-	kill_anon_super
136 FS_LITTER is gone - just remove it from fs_flags.
138 ---
142 FS_SINGLE is gone (actually, that had happened back when ->get_sb()
143 went in - and hadn't been documented ;-/).  Just remove it from fs_flags
144 (and see ->get_sb() entry for other actions).
146 ---
150 ->setattr() is called without BKL now.  Caller _always_ holds ->i_mutex, so
151 watch for ->i_mutex-grabbing code that might be used by your ->setattr().
152 Callers of notify_change() need ->i_mutex now.
154 ---
165 a standard helper function for decode_fh, and provide file-system specific
177 ---
191 should be a non-blocking function that initializes those parts of a
208 	if (inode->i_state & I_NEW) {
221 ---
225 ->getattr() finally getting used.  See instances in nfs, minix, etc.
227 ---
231 ->revalidate() is gone.  If your filesystem had it - provide ->getattr()
232 and let it call whatever you had as ->revlidate() + (for symlinks that
233 had ->revalidate()) add calls in ->follow_link()/->readlink().
235 ---
239 ->d_parent changes are not protected by BKL anymore.  Read access is safe
242 	* filesystem has no cross-directory rename()
244 	  ->d_parent of ->lookup() argument).
245 	* we are called from ->rename().
246 	* the child's ->d_lock is held
249 not protected by the conditions above is risky even in the old tree - you
251 a few holes of that kind - unprotected access to ->d_parent leading to
254 ---
258 FS_NOMOUNT is gone.  If you use it - just set SB_NOUSER in flags
261 ---
269 ---
273 ->permission() is called without BKL now. Grab it on entry, drop upon
274 return - that will guarantee the same locking you used to have.  If
275 your method or its parts do not need BKL - better yet, now you can
276 shift lock_kernel() and unlock_kernel() so that they would protect
279 ---
283 ->statfs() is now called without BKL held.  BKL should have been
287 ---
293 ---
299 ---
310 block truncatation on error exit from ->write_begin, and ->direct_IO
317 ->truncate is gone.  The whole truncate sequence needs to be
318 implemented in ->setattr, which is now mandatory for filesystems
319 implementing on-disk size changes.  Start with a copy of the old inode_setattr
322 size update and on finally on-disk truncation which should not fail.
324 for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
328 ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
330 remaining links or not.  Caller does *not* evict the pagecache or inode-associated
333 (or after) ->evict_inode() is called.
335 ->drop_inode() returns int now; it's called on final iput() with
336 inode->i_lock held and it returns true if filesystems wants the inode to be
340 ->drop_inode() returns.
343 ->evict_inode() (as it used to be for each call of ->delete_inode()).  Unlike
344 before, if you are using inode-associated metadata buffers (i.e.
348 NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
350 may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
351 free the on-disk inode, you may end up doing that while ->write_inode() is writing
354 ---
363 ---
371 ---
379 ---
384 for details of what locks to replace dcache_lock with in order to protect
385 particular things. Most of the time, a filesystem only needs ->d_lock, which
388 ---
392 Filesystems must RCU-free their inodes, if they can have been accessed
393 via rcu-walk path walk (basically, if the file can have had a path name in the
401 ---
405 vfs now tries to do path walking in "rcu-walk mode", which avoids
407 Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
409 filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
411 the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
412 are rcu-walk aware, shown below. Filesystems should take advantage of this
415 ---
420 the filesystem provides it), which requires dropping out of rcu-walk mode. This
421 may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
422 returned if the filesystem cannot handle rcu-walk. See
426 directory inodes on the way down a path walk (to check for exec permission). It
427 must now be rcu-walk aware (mask & MAY_NOT_BLOCK).  See
430 ---
434 In ->fallocate() you must check the mode option passed in.  If your
436 file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
441 ---
445 ->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
448 ->mnt_root to some pointer to returning that pointer.  On errors return
451 ---
455 ->permission() and generic_permission()have lost flags
459 has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
462 ---
466 If you implement your own ->llseek() you must handle SEEK_HOLE and
467 SEEK_DATA.  You can hanle this by returning -EINVAL, but it would be nicer to
472 of the file.  If the offset is i_size or greater return -ENXIO in either case.
476 If you have your own ->fsync() you must make sure to call
478 You must also keep in mind that ->fsync() is not called with i_mutex held
482 ---
495 	s->s_root = d_make_root(inode);
496 	if (!s->s_root)
498 		return -ENOMEM;
501 ---
505 The witch is dead!  Well, 2/3 of it, anyway.  ->d_revalidate() and
506 ->lookup() do *not* take struct nameidata anymore; just the flags.
508 ---
512 ->create() doesn't take ``struct nameidata *``; unlike the previous
514 local filesystems can ignore tha argument - they are guaranteed that the
517 ---
521 FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
524 ---
530 ---
534 ->readdir() is gone now; switch to ->iterate()
539 from ->follow_link for normal symlinks, or nd_jump_link for magic
542 ---
547 called with both ->i_lock and inode_hash_lock held; the former is *not*
549 of the in-tree instances did).  inode_hash_lock is still held,
553 ---
558 need now.  Remember that they have opposite orders of arguments ;-/
560 ---
567 ---
571 never call ->read() and ->write() directly; use __vfs_{read,write} or
572 wrappers; instead of checking for ->write or ->read being NULL, look for
573 FMODE_CAN_{WRITE,READ} in file->f_mode.
575 ---
579 do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
582 ---
585 	->aio_read/->aio_write are gone.  Use ->read_iter/->write_iter.
587 ---
591 for embedded ("fast") symlinks just set inode->i_link to wherever the
592 symlink body is and use simple_follow_link() as ->follow_link().
594 ---
598 calling conventions for ->follow_link() have changed.  Instead of returning
601 nameidata isn't passed at all - nd_jump_link() doesn't need it and
604 ---
608 calling conventions for ->put_link() have changed.  It gets inode instead of
610 is non-NULL.  Note that link body isn't available anymore, so if you need it,
613 ---
625 ---
629 ->follow_link() is replaced with ->get_link(); same API, except that
631 	* ->get_link() gets inode as a separate argument
632 	* ->get_link() may be called in RCU mode - in that case NULL
635 ---
639 ->get_link() gets struct delayed_call ``*done`` now, and should do
642 ->put_link() is gone - just give the destructor to set_delayed_call()
643 in ->get_link().
645 ---
649 ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
650 dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
654 ---
660 assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
661 it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
665 ---
669 ->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
670 they used to - they just take it exclusive.  However, ->lookup() may be
673 	* use d_instantiate) and d_rehash() separately - use d_add() or
675 	* use d_rehash() alone - call d_add(new_dentry, NULL) instead.
676 	* in the unlikely case when (read-only) access to filesystem
678 	  yourself.  None of the in-tree filesystems needed that.
679 	* rely on ->d_parent and ->d_name not changing after dentry has
681 	  in-tree instances relied upon that.
684 will not happen in parallel ("same" in the sense of your ->d_compare()).
688 ---
692 ->iterate_shared() is added; it's a parallel variant of ->iterate().
696 Exclusion between that method and all directory-modifying ones is
699 Often enough ->iterate() can serve as ->iterate_shared() without any
700 changes - it is a read-only operation, after all.  If you have any
701 per-inode or per-dentry in-core data structures modified by ->iterate(),
703 do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
704 that; look for in-tree examples.
709 ---
713 ->atomic_open() calls without O_CREAT may happen in parallel.
715 ---
719 ->setxattr() and xattr_handler.set() get dentry and inode passed separately.
720 dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
723 ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
725 ---
729 ->d_compare() doesn't get parent as a separate argument anymore.  If you
730 used it for finding the struct super_block involved, dentry->d_sb will
731 work just as well; if it's something more complicated, use dentry->d_parent.
733 the same value - in RCU mode it could change under you.
735 ---
739 ->rename() has an added flags argument.  Any flags not handled by the
742 ---
747 ->readlink is optional for symlinks.  Don't set, unless filesystem needs
750 ---
754 ->getattr() is now passed a struct path rather than a vfsmount and
757 supporting any statx-specific features may ignore the new arguments.
759 ---
763 ->atomic_open() calling conventions have changed.  Gone is ``int *opened``,
765 FMODE_OPENED/FMODE_CREATED, set in file->f_mode.  Additionally, return
768 does not need any changes in ->atomic_open() instances.
770 ---
783 original, on failure - ERR_PTR().
785 ---
789 ->clone_file_range() and ->dedupe_file_range have been replaced with
790 ->remap_file_range().  See Documentation/filesystems/vfs.rst for more
793 ---
797 ->lookup() instances doing an equivalent of::
803 don't need to bother with the check - d_splice_alias() will do the
809 ---
813 take the RCU-delayed parts of ->destroy_inode() into a new method -
814 ->free_inode().  If ->destroy_inode() becomes empty - all the better,
817 stack trace) *might* be movable to ->evict_inode(); however,
819 done by ->alloc_inode().  IOW, if it's cleaning up the stuff that
820 might have accumulated over the life of in-core inode, ->evict_inode()
825 	* if ->destroy_inode() is non-NULL, it gets called
826 	* if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
827 	* combination of NULL ->destroy_inode and NULL ->free_inode is
830 Note that the callback (be it via ->free_inode() or explicit call_rcu()
831 in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
838 ---
846 ---
850 d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
854 ---
859 failure exits in ->atomic_open() instances should *NOT* fput() the file,
862 ---