porting - OpenGrok cross reference for /linux-3.3/Documentation/filesystems/porting

3 ---
13 ---
16 New methods: ->alloc_inode() and ->destroy_inode().
18 Remove inode->u.foo_inode_i
21 		/* fs-private stuff */
29 Use FOO_I(inode) instead of &inode->u.foo_inode_i;
31 Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
32 foo_inode_info and return the address of ->vfs_inode, the latter should free
33 FOO_I(inode) (see in-tree filesystems for examples).
35 Make them ->alloc_inode and ->destroy_inode in your super_operations.
42 ---
45 Change of file_system_type method (->read_super to ->get_sb)
47 ->read_super() is no more.  Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
50 success and negative number in case of error (-EINVAL unless you have more
63 Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
66 ---
69 Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
71 global exclusion between renames for some internal purpose - you need to
75 ---
78 Now we have the exclusion between ->lookup() and directory removal (by
79 ->rmdir() and ->rename()).  If you used to need that exclusion and do
80 it by internal locking (most of filesystems couldn't care less) - you
83 ---
86 ->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
87 ->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
88 and ->readdir() are called without BKL now.  Grab it on entry, drop upon return
89 - that will guarantee the same locking you used to have.  If your method or its
90 parts do not need BKL - better yet, now you can shift lock_kernel() and
94 ---
97 BKL is also moved from around sb operations.  ->write_super() Is now called
98 without BKL held.  BKL should have been shifted into individual fs sb_op
101 ---
104 check for ->link() target not being a directory is done by callers.  Feel
107 ---
110 ->link() callers hold ->i_mutex on the object we are linking to.  Some of your
113 ---
116 new file_system_type method - kill_sb(superblock).  If you are converting
117 an existing filesystem, set it according to ->fs_flags:
118 	FS_REQUIRES_DEV		-	kill_block_super
119 	FS_LITTER		-	kill_litter_super
120 	neither			-	kill_anon_super
121 FS_LITTER is gone - just remove it from fs_flags.
123 ---
126 	FS_SINGLE is gone (actually, that had happened back when ->get_sb()
127 went in - and hadn't been documented ;-/).  Just remove it from fs_flags
128 (and see ->get_sb() entry for other actions).
130 ---
133 ->setattr() is called without BKL now.  Caller _always_ holds ->i_mutex, so
134 watch for ->i_mutex-grabbing code that might be used by your ->setattr().
135 Callers of notify_change() need ->i_mutex now.
137 ---
142 documented at its declaration in include/linux/fs.h, and in
147 a standard helper function for decode_fh, and provide file-system specific
159 ---
172 should be a non-blocking function that initializes those parts of a
188 	if (inode->i_state & I_NEW) {
201 ---
204 ->getattr() finally getting used.  See instances in nfs, minix, etc.
206 ---
209 ->revalidate() is gone.  If your filesystem had it - provide ->getattr()
210 and let it call whatever you had as ->revlidate() + (for symlinks that
211 had ->revalidate()) add calls in ->follow_link()/->readlink().
213 ---
216 ->d_parent changes are not protected by BKL anymore.  Read access is safe
218 	* filesystem has no cross-directory rename()
220 ->d_parent of ->lookup() argument).
221 	* we are called from ->rename().
222 	* the child's ->d_lock is held
223 Audit your code and add locking if needed.  Notice that any place that is
224 not protected by the conditions above is risky even in the old tree - you
226 a few holes of that kind - unprotected access to ->d_parent leading to
229 ---
232 	FS_NOMOUNT is gone.  If you use it - just set MS_NOUSER in flags
235 ---
242 ---
245 ->permission() is called without BKL now. Grab it on entry, drop upon
246 return - that will guarantee the same locking you used to have.  If
247 your method or its parts do not need BKL - better yet, now you can
251 ---
254 ->statfs() is now called without BKL held.  BKL should have been
255 shifted into individual fs sb_op functions where it's not clear that
258 ---
263 ---
268 ---
278 	block truncatation on error exit from ->write_begin, and ->direct_IO
285 	->truncate is going away.  The whole truncate sequence needs to be
286 implemented in ->setattr, which is now mandatory for filesystems
287 implementing on-disk size changes.  Start with a copy of the old inode_setattr
290 size update and on finally on-disk truncation which should not fail.
292 in the beginning of ->setattr unconditionally.
296 	->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
298 remaining links or not.  Caller does *not* evict the pagecache or inode-associated
300 been for ->delete_inode().
302 	->drop_inode() returns int now; it's called on final iput() with
303 inode->i_lock held and it returns true if filesystems wants the inode to be
307 ->drop_inode() returns.
310 be called exactly once on each call of ->evict_inode() (as it used to be for
311 each call of ->delete_inode()).  Unlike before, if you are using inode-associated
314 	No async writeback (and thus no calls of ->write_inode()) will happen
315 after end_writeback() returns, so actions that should not overlap with ->write_inode()
316 (e.g. freeing on-disk inode if i_nlink is 0) ought to be done after that call.
318 	NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
320 may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
321 free the on-disk inode, you may end up doing that while ->write_inode() is writing
324 ---
332 ---
339 ---
346 ---
348 	dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
350 particular things. Most of the time, a filesystem only needs ->d_lock, which
353 --
356 	Filesystems must RCU-free their inodes, if they can have been accessed
357 via rcu-walk path walk (basically, if the file can have had a path name in the
363   INIT_LIST_HEAD(&inode->i_dentry);
367 --
369 	vfs now tries to do path walking in "rcu-walk mode", which avoids
371 Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
373 filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
375 the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
376 are rcu-walk aware, shown below. Filesystems should take advantage of this
379 --
382 the filesystem provides it), which requires dropping out of rcu-walk mode. This
383 may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
384 returned if the filesystem cannot handle rcu-walk. See
389 exec permission). These must now be rcu-walk aware (flags & IPERM_FLAG_RCU).
392 --
394 	In ->fallocate() you must check the mode option passed in.  If your
396 file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
401 --
403 	->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
405 function type.  If you were doing it manually, just switch from setting ->mnt_root
408 --
410 	->permission() and generic_permission()have lost flags
411 argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
413 has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
416 --
418 	If you implement your own ->llseek() you must handle SEEK_HOLE and
419 SEEK_DATA.  You can hanle this by returning -EINVAL, but it would be nicer to
424 of the file.  If the offset is i_size or greater return -ENXIO in either case.
427 	If you have your own ->fsync() you must make sure to call
429 You must also keep in mind that ->fsync() is not called with i_mutex held