Loading...
1 The text below describes the locking rules for VFS-related methods.
2It is (believed to be) up-to-date. *Please*, if you change anything in
3prototypes or locking protocols - update this file. And update the relevant
4instances in the tree, don't leave that to maintainers of filesystems/devices/
5etc. At the very least, put the list of dubious cases in the end of this file.
6Don't turn it into log - maintainers of out-of-the-tree code are supposed to
7be able to use diff(1).
8 Thing currently missing here: socket operations. Alexey?
9
10--------------------------- dentry_operations --------------------------
11prototypes:
12 int (*d_revalidate)(struct dentry *, unsigned int);
13 int (*d_weak_revalidate)(struct dentry *, unsigned int);
14 int (*d_hash)(const struct dentry *, struct qstr *);
15 int (*d_compare)(const struct dentry *, const struct dentry *,
16 unsigned int, const char *, const struct qstr *);
17 int (*d_delete)(struct dentry *);
18 void (*d_release)(struct dentry *);
19 void (*d_iput)(struct dentry *, struct inode *);
20 char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
21 struct vfsmount *(*d_automount)(struct path *path);
22 int (*d_manage)(struct dentry *, bool);
23
24locking rules:
25 rename_lock ->d_lock may block rcu-walk
26d_revalidate: no no yes (ref-walk) maybe
27d_weak_revalidate:no no yes no
28d_hash no no no maybe
29d_compare: yes no no maybe
30d_delete: no yes no no
31d_release: no no yes no
32d_prune: no yes no no
33d_iput: no no yes no
34d_dname: no no no no
35d_automount: no no yes no
36d_manage: no no yes (ref-walk) maybe
37
38--------------------------- inode_operations ---------------------------
39prototypes:
40 int (*create) (struct inode *,struct dentry *,umode_t, bool);
41 struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
42 int (*link) (struct dentry *,struct inode *,struct dentry *);
43 int (*unlink) (struct inode *,struct dentry *);
44 int (*symlink) (struct inode *,struct dentry *,const char *);
45 int (*mkdir) (struct inode *,struct dentry *,umode_t);
46 int (*rmdir) (struct inode *,struct dentry *);
47 int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
48 int (*rename) (struct inode *, struct dentry *,
49 struct inode *, struct dentry *);
50 int (*rename2) (struct inode *, struct dentry *,
51 struct inode *, struct dentry *, unsigned int);
52 int (*readlink) (struct dentry *, char __user *,int);
53 const char *(*get_link) (struct dentry *, struct inode *, void **);
54 void (*truncate) (struct inode *);
55 int (*permission) (struct inode *, int, unsigned int);
56 int (*get_acl)(struct inode *, int);
57 int (*setattr) (struct dentry *, struct iattr *);
58 int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *);
59 int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
60 ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
61 ssize_t (*listxattr) (struct dentry *, char *, size_t);
62 int (*removexattr) (struct dentry *, const char *);
63 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
64 void (*update_time)(struct inode *, struct timespec *, int);
65 int (*atomic_open)(struct inode *, struct dentry *,
66 struct file *, unsigned open_flag,
67 umode_t create_mode, int *opened);
68 int (*tmpfile) (struct inode *, struct dentry *, umode_t);
69 int (*dentry_open)(struct dentry *, struct file *, const struct cred *);
70
71locking rules:
72 all may block
73 i_mutex(inode)
74lookup: yes
75create: yes
76link: yes (both)
77mknod: yes
78symlink: yes
79mkdir: yes
80unlink: yes (both)
81rmdir: yes (both) (see below)
82rename: yes (all) (see below)
83rename2: yes (all) (see below)
84readlink: no
85get_link: no
86setattr: yes
87permission: no (may not block if called in rcu-walk mode)
88get_acl: no
89getattr: no
90setxattr: yes
91getxattr: no
92listxattr: no
93removexattr: yes
94fiemap: no
95update_time: no
96atomic_open: yes
97tmpfile: no
98dentry_open: no
99
100 Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on
101victim.
102 cross-directory ->rename() and rename2() has (per-superblock)
103->s_vfs_rename_sem.
104
105See Documentation/filesystems/directory-locking for more detailed discussion
106of the locking scheme for directory operations.
107
108--------------------------- super_operations ---------------------------
109prototypes:
110 struct inode *(*alloc_inode)(struct super_block *sb);
111 void (*destroy_inode)(struct inode *);
112 void (*dirty_inode) (struct inode *, int flags);
113 int (*write_inode) (struct inode *, struct writeback_control *wbc);
114 int (*drop_inode) (struct inode *);
115 void (*evict_inode) (struct inode *);
116 void (*put_super) (struct super_block *);
117 int (*sync_fs)(struct super_block *sb, int wait);
118 int (*freeze_fs) (struct super_block *);
119 int (*unfreeze_fs) (struct super_block *);
120 int (*statfs) (struct dentry *, struct kstatfs *);
121 int (*remount_fs) (struct super_block *, int *, char *);
122 void (*umount_begin) (struct super_block *);
123 int (*show_options)(struct seq_file *, struct dentry *);
124 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
125 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
126 int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t);
127
128locking rules:
129 All may block [not true, see below]
130 s_umount
131alloc_inode:
132destroy_inode:
133dirty_inode:
134write_inode:
135drop_inode: !!!inode->i_lock!!!
136evict_inode:
137put_super: write
138sync_fs: read
139freeze_fs: write
140unfreeze_fs: write
141statfs: maybe(read) (see below)
142remount_fs: write
143umount_begin: no
144show_options: no (namespace_sem)
145quota_read: no (see below)
146quota_write: no (see below)
147bdev_try_to_free_page: no (see below)
148
149->statfs() has s_umount (shared) when called by ustat(2) (native or
150compat), but that's an accident of bad API; s_umount is used to pin
151the superblock down when we only have dev_t given us by userland to
152identify the superblock. Everything else (statfs(), fstatfs(), etc.)
153doesn't hold it when calling ->statfs() - superblock is pinned down
154by resolving the pathname passed to syscall.
155->quota_read() and ->quota_write() functions are both guaranteed to
156be the only ones operating on the quota file by the quota code (via
157dqio_sem) (unless an admin really wants to screw up something and
158writes to quota files with quotas on). For other details about locking
159see also dquot_operations section.
160->bdev_try_to_free_page is called from the ->releasepage handler of
161the block device inode. See there for more details.
162
163--------------------------- file_system_type ---------------------------
164prototypes:
165 struct dentry *(*mount) (struct file_system_type *, int,
166 const char *, void *);
167 void (*kill_sb) (struct super_block *);
168locking rules:
169 may block
170mount yes
171kill_sb yes
172
173->mount() returns ERR_PTR or the root dentry; its superblock should be locked
174on return.
175->kill_sb() takes a write-locked superblock, does all shutdown work on it,
176unlocks and drops the reference.
177
178--------------------------- address_space_operations --------------------------
179prototypes:
180 int (*writepage)(struct page *page, struct writeback_control *wbc);
181 int (*readpage)(struct file *, struct page *);
182 int (*sync_page)(struct page *);
183 int (*writepages)(struct address_space *, struct writeback_control *);
184 int (*set_page_dirty)(struct page *page);
185 int (*readpages)(struct file *filp, struct address_space *mapping,
186 struct list_head *pages, unsigned nr_pages);
187 int (*write_begin)(struct file *, struct address_space *mapping,
188 loff_t pos, unsigned len, unsigned flags,
189 struct page **pagep, void **fsdata);
190 int (*write_end)(struct file *, struct address_space *mapping,
191 loff_t pos, unsigned len, unsigned copied,
192 struct page *page, void *fsdata);
193 sector_t (*bmap)(struct address_space *, sector_t);
194 void (*invalidatepage) (struct page *, unsigned int, unsigned int);
195 int (*releasepage) (struct page *, int);
196 void (*freepage)(struct page *);
197 int (*direct_IO)(struct kiocb *, struct iov_iter *iter, loff_t offset);
198 int (*migratepage)(struct address_space *, struct page *, struct page *);
199 int (*launder_page)(struct page *);
200 int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long);
201 int (*error_remove_page)(struct address_space *, struct page *);
202 int (*swap_activate)(struct file *);
203 int (*swap_deactivate)(struct file *);
204
205locking rules:
206 All except set_page_dirty and freepage may block
207
208 PageLocked(page) i_mutex
209writepage: yes, unlocks (see below)
210readpage: yes, unlocks
211sync_page: maybe
212writepages:
213set_page_dirty no
214readpages:
215write_begin: locks the page yes
216write_end: yes, unlocks yes
217bmap:
218invalidatepage: yes
219releasepage: yes
220freepage: yes
221direct_IO:
222migratepage: yes (both)
223launder_page: yes
224is_partially_uptodate: yes
225error_remove_page: yes
226swap_activate: no
227swap_deactivate: no
228
229 ->write_begin(), ->write_end(), ->sync_page() and ->readpage()
230may be called from the request handler (/dev/loop).
231
232 ->readpage() unlocks the page, either synchronously or via I/O
233completion.
234
235 ->readpages() populates the pagecache with the passed pages and starts
236I/O against them. They come unlocked upon I/O completion.
237
238 ->writepage() is used for two purposes: for "memory cleansing" and for
239"sync". These are quite different operations and the behaviour may differ
240depending upon the mode.
241
242If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
243it *must* start I/O against the page, even if that would involve
244blocking on in-progress I/O.
245
246If writepage is called for memory cleansing (sync_mode ==
247WBC_SYNC_NONE) then its role is to get as much writeout underway as
248possible. So writepage should try to avoid blocking against
249currently-in-progress I/O.
250
251If the filesystem is not called for "sync" and it determines that it
252would need to block against in-progress I/O to be able to start new I/O
253against the page the filesystem should redirty the page with
254redirty_page_for_writepage(), then unlock the page and return zero.
255This may also be done to avoid internal deadlocks, but rarely.
256
257If the filesystem is called for sync then it must wait on any
258in-progress I/O and then start new I/O.
259
260The filesystem should unlock the page synchronously, before returning to the
261caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
262value. WRITEPAGE_ACTIVATE means that page cannot really be written out
263currently, and VM should stop calling ->writepage() on this page for some
264time. VM does this by moving page to the head of the active list, hence the
265name.
266
267Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
268and return zero, writepage *must* run set_page_writeback() against the page,
269followed by unlocking it. Once set_page_writeback() has been run against the
270page, write I/O can be submitted and the write I/O completion handler must run
271end_page_writeback() once the I/O is complete. If no I/O is submitted, the
272filesystem must run end_page_writeback() against the page before returning from
273writepage.
274
275That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
276if the filesystem needs the page to be locked during writeout, that is ok, too,
277the page is allowed to be unlocked at any point in time between the calls to
278set_page_writeback() and end_page_writeback().
279
280Note, failure to run either redirty_page_for_writepage() or the combination of
281set_page_writeback()/end_page_writeback() on a page submitted to writepage
282will leave the page itself marked clean but it will be tagged as dirty in the
283radix tree. This incoherency can lead to all sorts of hard-to-debug problems
284in the filesystem like having dirty inodes at umount and losing written data.
285
286 ->sync_page() locking rules are not well-defined - usually it is called
287with lock on page, but that is not guaranteed. Considering the currently
288existing instances of this method ->sync_page() itself doesn't look
289well-defined...
290
291 ->writepages() is used for periodic writeback and for syscall-initiated
292sync operations. The address_space should start I/O against at least
293*nr_to_write pages. *nr_to_write must be decremented for each page which is
294written. The address_space implementation may write more (or less) pages
295than *nr_to_write asks for, but it should try to be reasonably close. If
296nr_to_write is NULL, all dirty pages must be written.
297
298writepages should _only_ write pages which are present on
299mapping->io_pages.
300
301 ->set_page_dirty() is called from various places in the kernel
302when the target page is marked as needing writeback. It may be called
303under spinlock (it cannot block) and is sometimes called with the page
304not locked.
305
306 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
307filesystems and by the swapper. The latter will eventually go away. Please,
308keep it that way and don't breed new callers.
309
310 ->invalidatepage() is called when the filesystem must attempt to drop
311some or all of the buffers from the page when it is being truncated. It
312returns zero on success. If ->invalidatepage is zero, the kernel uses
313block_invalidatepage() instead.
314
315 ->releasepage() is called when the kernel is about to try to drop the
316buffers from the page in preparation for freeing it. It returns zero to
317indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
318the kernel assumes that the fs has no private interest in the buffers.
319
320 ->freepage() is called when the kernel is done dropping the page
321from the page cache.
322
323 ->launder_page() may be called prior to releasing a page if
324it is still found to be dirty. It returns zero if the page was successfully
325cleaned, or an error value if not. Note that in order to prevent the page
326getting mapped back in and redirtied, it needs to be kept locked
327across the entire operation.
328
329 ->swap_activate will be called with a non-zero argument on
330files backing (non block device backed) swapfiles. A return value
331of zero indicates success, in which case this file can be used for
332backing swapspace. The swapspace operations will be proxied to the
333address space operations.
334
335 ->swap_deactivate() will be called in the sys_swapoff()
336path after ->swap_activate() returned success.
337
338----------------------- file_lock_operations ------------------------------
339prototypes:
340 void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
341 void (*fl_release_private)(struct file_lock *);
342
343
344locking rules:
345 inode->i_lock may block
346fl_copy_lock: yes no
347fl_release_private: maybe maybe[1]
348
349[1]: ->fl_release_private for flock or POSIX locks is currently allowed
350to block. Leases however can still be freed while the i_lock is held and
351so fl_release_private called on a lease should not block.
352
353----------------------- lock_manager_operations ---------------------------
354prototypes:
355 int (*lm_compare_owner)(struct file_lock *, struct file_lock *);
356 unsigned long (*lm_owner_key)(struct file_lock *);
357 void (*lm_notify)(struct file_lock *); /* unblock callback */
358 int (*lm_grant)(struct file_lock *, struct file_lock *, int);
359 void (*lm_break)(struct file_lock *); /* break_lease callback */
360 int (*lm_change)(struct file_lock **, int);
361
362locking rules:
363
364 inode->i_lock blocked_lock_lock may block
365lm_compare_owner: yes[1] maybe no
366lm_owner_key yes[1] yes no
367lm_notify: yes yes no
368lm_grant: no no no
369lm_break: yes no no
370lm_change yes no no
371
372[1]: ->lm_compare_owner and ->lm_owner_key are generally called with
373*an* inode->i_lock held. It may not be the i_lock of the inode
374associated with either file_lock argument! This is the case with deadlock
375detection, since the code has to chase down the owners of locks that may
376be entirely unrelated to the one on which the lock is being acquired.
377For deadlock detection however, the blocked_lock_lock is also held. The
378fact that these locks are held ensures that the file_locks do not
379disappear out from under you while doing the comparison or generating an
380owner key.
381
382--------------------------- buffer_head -----------------------------------
383prototypes:
384 void (*b_end_io)(struct buffer_head *bh, int uptodate);
385
386locking rules:
387 called from interrupts. In other words, extreme care is needed here.
388bh is locked, but that's all warranties we have here. Currently only RAID1,
389highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
390call this method upon the IO completion.
391
392--------------------------- block_device_operations -----------------------
393prototypes:
394 int (*open) (struct block_device *, fmode_t);
395 int (*release) (struct gendisk *, fmode_t);
396 int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
397 int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
398 int (*direct_access) (struct block_device *, sector_t, void __pmem **,
399 unsigned long *);
400 int (*media_changed) (struct gendisk *);
401 void (*unlock_native_capacity) (struct gendisk *);
402 int (*revalidate_disk) (struct gendisk *);
403 int (*getgeo)(struct block_device *, struct hd_geometry *);
404 void (*swap_slot_free_notify) (struct block_device *, unsigned long);
405
406locking rules:
407 bd_mutex
408open: yes
409release: yes
410ioctl: no
411compat_ioctl: no
412direct_access: no
413media_changed: no
414unlock_native_capacity: no
415revalidate_disk: no
416getgeo: no
417swap_slot_free_notify: no (see below)
418
419media_changed, unlock_native_capacity and revalidate_disk are called only from
420check_disk_change().
421
422swap_slot_free_notify is called with swap_lock and sometimes the page lock
423held.
424
425
426--------------------------- file_operations -------------------------------
427prototypes:
428 loff_t (*llseek) (struct file *, loff_t, int);
429 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
430 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
431 ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
432 ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
433 int (*iterate) (struct file *, struct dir_context *);
434 unsigned int (*poll) (struct file *, struct poll_table_struct *);
435 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
436 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
437 int (*mmap) (struct file *, struct vm_area_struct *);
438 int (*open) (struct inode *, struct file *);
439 int (*flush) (struct file *);
440 int (*release) (struct inode *, struct file *);
441 int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
442 int (*aio_fsync) (struct kiocb *, int datasync);
443 int (*fasync) (int, struct file *, int);
444 int (*lock) (struct file *, int, struct file_lock *);
445 ssize_t (*readv) (struct file *, const struct iovec *, unsigned long,
446 loff_t *);
447 ssize_t (*writev) (struct file *, const struct iovec *, unsigned long,
448 loff_t *);
449 ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
450 void __user *);
451 ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
452 loff_t *, int);
453 unsigned long (*get_unmapped_area)(struct file *, unsigned long,
454 unsigned long, unsigned long, unsigned long);
455 int (*check_flags)(int);
456 int (*flock) (struct file *, int, struct file_lock *);
457 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
458 size_t, unsigned int);
459 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
460 size_t, unsigned int);
461 int (*setlease)(struct file *, long, struct file_lock **, void **);
462 long (*fallocate)(struct file *, int, loff_t, loff_t);
463};
464
465locking rules:
466 All may block.
467
468->llseek() locking has moved from llseek to the individual llseek
469implementations. If your fs is not using generic_file_llseek, you
470need to acquire and release the appropriate locks in your ->llseek().
471For many filesystems, it is probably safe to acquire the inode
472mutex or just to use i_size_read() instead.
473Note: this does not protect the file->f_pos against concurrent modifications
474since this is something the userspace has to take care about.
475
476->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
477Most instances call fasync_helper(), which does that maintenance, so it's
478not normally something one needs to worry about. Return values > 0 will be
479mapped to zero in the VFS layer.
480
481->readdir() and ->ioctl() on directories must be changed. Ideally we would
482move ->readdir() to inode_operations and use a separate method for directory
483->ioctl() or kill the latter completely. One of the problems is that for
484anything that resembles union-mount we won't have a struct file for all
485components. And there are other reasons why the current interface is a mess...
486
487->read on directories probably must go away - we should just enforce -EISDIR
488in sys_read() and friends.
489
490->setlease operations should call generic_setlease() before or after setting
491the lease within the individual filesystem to record the result of the
492operation
493
494--------------------------- dquot_operations -------------------------------
495prototypes:
496 int (*write_dquot) (struct dquot *);
497 int (*acquire_dquot) (struct dquot *);
498 int (*release_dquot) (struct dquot *);
499 int (*mark_dirty) (struct dquot *);
500 int (*write_info) (struct super_block *, int);
501
502These operations are intended to be more or less wrapping functions that ensure
503a proper locking wrt the filesystem and call the generic quota operations.
504
505What filesystem should expect from the generic quota functions:
506
507 FS recursion Held locks when called
508write_dquot: yes dqonoff_sem or dqptr_sem
509acquire_dquot: yes dqonoff_sem or dqptr_sem
510release_dquot: yes dqonoff_sem or dqptr_sem
511mark_dirty: no -
512write_info: yes dqonoff_sem
513
514FS recursion means calling ->quota_read() and ->quota_write() from superblock
515operations.
516
517More details about quota locking can be found in fs/dquot.c.
518
519--------------------------- vm_operations_struct -----------------------------
520prototypes:
521 void (*open)(struct vm_area_struct*);
522 void (*close)(struct vm_area_struct*);
523 int (*fault)(struct vm_area_struct*, struct vm_fault *);
524 int (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
525 int (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
526 int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
527
528locking rules:
529 mmap_sem PageLocked(page)
530open: yes
531close: yes
532fault: yes can return with page locked
533map_pages: yes
534page_mkwrite: yes can return with page locked
535pfn_mkwrite: yes
536access: yes
537
538 ->fault() is called when a previously not present pte is about
539to be faulted in. The filesystem must find and return the page associated
540with the passed in "pgoff" in the vm_fault structure. If it is possible that
541the page may be truncated and/or invalidated, then the filesystem must lock
542the page, then ensure it is not already truncated (the page lock will block
543subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
544locked. The VM will unlock the page.
545
546 ->map_pages() is called when VM asks to map easy accessible pages.
547Filesystem should find and map pages associated with offsets from "pgoff"
548till "max_pgoff". ->map_pages() is called with page table locked and must
549not block. If it's not possible to reach a page without blocking,
550filesystem should skip it. Filesystem should use do_set_pte() to setup
551page table entry. Pointer to entry associated with offset "pgoff" is
552passed in "pte" field in vm_fault structure. Pointers to entries for other
553offsets should be calculated relative to "pte".
554
555 ->page_mkwrite() is called when a previously read-only pte is
556about to become writeable. The filesystem again must ensure that there are
557no truncate/invalidate races, and then return with the page locked. If
558the page has been truncated, the filesystem should not look up a new page
559like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
560will cause the VM to retry the fault.
561
562 ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
563VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
564VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
565after this call is to make the pte read-write, unless pfn_mkwrite returns
566an error.
567
568 ->access() is called when get_user_pages() fails in
569access_process_vm(), typically used to debug a process through
570/proc/pid/mem or ptrace. This function is needed only for
571VM_IO | VM_PFNMAP VMAs.
572
573================================================================================
574 Dubious stuff
575
576(if you break something or notice that it is broken and do not fix it yourself
577- at least put it here)
1 The text below describes the locking rules for VFS-related methods.
2It is (believed to be) up-to-date. *Please*, if you change anything in
3prototypes or locking protocols - update this file. And update the relevant
4instances in the tree, don't leave that to maintainers of filesystems/devices/
5etc. At the very least, put the list of dubious cases in the end of this file.
6Don't turn it into log - maintainers of out-of-the-tree code are supposed to
7be able to use diff(1).
8 Thing currently missing here: socket operations. Alexey?
9
10--------------------------- dentry_operations --------------------------
11prototypes:
12 int (*d_revalidate)(struct dentry *, struct nameidata *);
13 int (*d_hash)(const struct dentry *, const struct inode *,
14 struct qstr *);
15 int (*d_compare)(const struct dentry *, const struct inode *,
16 const struct dentry *, const struct inode *,
17 unsigned int, const char *, const struct qstr *);
18 int (*d_delete)(struct dentry *);
19 void (*d_release)(struct dentry *);
20 void (*d_iput)(struct dentry *, struct inode *);
21 char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
22 struct vfsmount *(*d_automount)(struct path *path);
23 int (*d_manage)(struct dentry *, bool);
24
25locking rules:
26 rename_lock ->d_lock may block rcu-walk
27d_revalidate: no no yes (ref-walk) maybe
28d_hash no no no maybe
29d_compare: yes no no maybe
30d_delete: no yes no no
31d_release: no no yes no
32d_prune: no yes no no
33d_iput: no no yes no
34d_dname: no no no no
35d_automount: no no yes no
36d_manage: no no yes (ref-walk) maybe
37
38--------------------------- inode_operations ---------------------------
39prototypes:
40 int (*create) (struct inode *,struct dentry *,umode_t, struct nameidata *);
41 struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameid
42ata *);
43 int (*link) (struct dentry *,struct inode *,struct dentry *);
44 int (*unlink) (struct inode *,struct dentry *);
45 int (*symlink) (struct inode *,struct dentry *,const char *);
46 int (*mkdir) (struct inode *,struct dentry *,umode_t);
47 int (*rmdir) (struct inode *,struct dentry *);
48 int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
49 int (*rename) (struct inode *, struct dentry *,
50 struct inode *, struct dentry *);
51 int (*readlink) (struct dentry *, char __user *,int);
52 void * (*follow_link) (struct dentry *, struct nameidata *);
53 void (*put_link) (struct dentry *, struct nameidata *, void *);
54 void (*truncate) (struct inode *);
55 int (*permission) (struct inode *, int, unsigned int);
56 int (*get_acl)(struct inode *, int);
57 int (*setattr) (struct dentry *, struct iattr *);
58 int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *);
59 int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
60 ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
61 ssize_t (*listxattr) (struct dentry *, char *, size_t);
62 int (*removexattr) (struct dentry *, const char *);
63 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
64 void (*update_time)(struct inode *, struct timespec *, int);
65
66locking rules:
67 all may block
68 i_mutex(inode)
69lookup: yes
70create: yes
71link: yes (both)
72mknod: yes
73symlink: yes
74mkdir: yes
75unlink: yes (both)
76rmdir: yes (both) (see below)
77rename: yes (all) (see below)
78readlink: no
79follow_link: no
80put_link: no
81truncate: yes (see below)
82setattr: yes
83permission: no (may not block if called in rcu-walk mode)
84get_acl: no
85getattr: no
86setxattr: yes
87getxattr: no
88listxattr: no
89removexattr: yes
90fiemap: no
91update_time: no
92
93 Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on
94victim.
95 cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
96 ->truncate() is never called directly - it's a callback, not a
97method. It's called by vmtruncate() - deprecated library function used by
98->setattr(). Locking information above applies to that call (i.e. is
99inherited from ->setattr() - vmtruncate() is used when ATTR_SIZE had been
100passed).
101
102See Documentation/filesystems/directory-locking for more detailed discussion
103of the locking scheme for directory operations.
104
105--------------------------- super_operations ---------------------------
106prototypes:
107 struct inode *(*alloc_inode)(struct super_block *sb);
108 void (*destroy_inode)(struct inode *);
109 void (*dirty_inode) (struct inode *, int flags);
110 int (*write_inode) (struct inode *, struct writeback_control *wbc);
111 int (*drop_inode) (struct inode *);
112 void (*evict_inode) (struct inode *);
113 void (*put_super) (struct super_block *);
114 void (*write_super) (struct super_block *);
115 int (*sync_fs)(struct super_block *sb, int wait);
116 int (*freeze_fs) (struct super_block *);
117 int (*unfreeze_fs) (struct super_block *);
118 int (*statfs) (struct dentry *, struct kstatfs *);
119 int (*remount_fs) (struct super_block *, int *, char *);
120 void (*umount_begin) (struct super_block *);
121 int (*show_options)(struct seq_file *, struct dentry *);
122 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
123 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
124 int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t);
125
126locking rules:
127 All may block [not true, see below]
128 s_umount
129alloc_inode:
130destroy_inode:
131dirty_inode:
132write_inode:
133drop_inode: !!!inode->i_lock!!!
134evict_inode:
135put_super: write
136write_super: read
137sync_fs: read
138freeze_fs: read
139unfreeze_fs: read
140statfs: maybe(read) (see below)
141remount_fs: write
142umount_begin: no
143show_options: no (namespace_sem)
144quota_read: no (see below)
145quota_write: no (see below)
146bdev_try_to_free_page: no (see below)
147
148->statfs() has s_umount (shared) when called by ustat(2) (native or
149compat), but that's an accident of bad API; s_umount is used to pin
150the superblock down when we only have dev_t given us by userland to
151identify the superblock. Everything else (statfs(), fstatfs(), etc.)
152doesn't hold it when calling ->statfs() - superblock is pinned down
153by resolving the pathname passed to syscall.
154->quota_read() and ->quota_write() functions are both guaranteed to
155be the only ones operating on the quota file by the quota code (via
156dqio_sem) (unless an admin really wants to screw up something and
157writes to quota files with quotas on). For other details about locking
158see also dquot_operations section.
159->bdev_try_to_free_page is called from the ->releasepage handler of
160the block device inode. See there for more details.
161
162--------------------------- file_system_type ---------------------------
163prototypes:
164 int (*get_sb) (struct file_system_type *, int,
165 const char *, void *, struct vfsmount *);
166 struct dentry *(*mount) (struct file_system_type *, int,
167 const char *, void *);
168 void (*kill_sb) (struct super_block *);
169locking rules:
170 may block
171mount yes
172kill_sb yes
173
174->mount() returns ERR_PTR or the root dentry; its superblock should be locked
175on return.
176->kill_sb() takes a write-locked superblock, does all shutdown work on it,
177unlocks and drops the reference.
178
179--------------------------- address_space_operations --------------------------
180prototypes:
181 int (*writepage)(struct page *page, struct writeback_control *wbc);
182 int (*readpage)(struct file *, struct page *);
183 int (*sync_page)(struct page *);
184 int (*writepages)(struct address_space *, struct writeback_control *);
185 int (*set_page_dirty)(struct page *page);
186 int (*readpages)(struct file *filp, struct address_space *mapping,
187 struct list_head *pages, unsigned nr_pages);
188 int (*write_begin)(struct file *, struct address_space *mapping,
189 loff_t pos, unsigned len, unsigned flags,
190 struct page **pagep, void **fsdata);
191 int (*write_end)(struct file *, struct address_space *mapping,
192 loff_t pos, unsigned len, unsigned copied,
193 struct page *page, void *fsdata);
194 sector_t (*bmap)(struct address_space *, sector_t);
195 int (*invalidatepage) (struct page *, unsigned long);
196 int (*releasepage) (struct page *, int);
197 void (*freepage)(struct page *);
198 int (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
199 loff_t offset, unsigned long nr_segs);
200 int (*get_xip_mem)(struct address_space *, pgoff_t, int, void **,
201 unsigned long *);
202 int (*migratepage)(struct address_space *, struct page *, struct page *);
203 int (*launder_page)(struct page *);
204 int (*is_partially_uptodate)(struct page *, read_descriptor_t *, unsigned long);
205 int (*error_remove_page)(struct address_space *, struct page *);
206
207locking rules:
208 All except set_page_dirty and freepage may block
209
210 PageLocked(page) i_mutex
211writepage: yes, unlocks (see below)
212readpage: yes, unlocks
213sync_page: maybe
214writepages:
215set_page_dirty no
216readpages:
217write_begin: locks the page yes
218write_end: yes, unlocks yes
219bmap:
220invalidatepage: yes
221releasepage: yes
222freepage: yes
223direct_IO:
224get_xip_mem: maybe
225migratepage: yes (both)
226launder_page: yes
227is_partially_uptodate: yes
228error_remove_page: yes
229
230 ->write_begin(), ->write_end(), ->sync_page() and ->readpage()
231may be called from the request handler (/dev/loop).
232
233 ->readpage() unlocks the page, either synchronously or via I/O
234completion.
235
236 ->readpages() populates the pagecache with the passed pages and starts
237I/O against them. They come unlocked upon I/O completion.
238
239 ->writepage() is used for two purposes: for "memory cleansing" and for
240"sync". These are quite different operations and the behaviour may differ
241depending upon the mode.
242
243If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
244it *must* start I/O against the page, even if that would involve
245blocking on in-progress I/O.
246
247If writepage is called for memory cleansing (sync_mode ==
248WBC_SYNC_NONE) then its role is to get as much writeout underway as
249possible. So writepage should try to avoid blocking against
250currently-in-progress I/O.
251
252If the filesystem is not called for "sync" and it determines that it
253would need to block against in-progress I/O to be able to start new I/O
254against the page the filesystem should redirty the page with
255redirty_page_for_writepage(), then unlock the page and return zero.
256This may also be done to avoid internal deadlocks, but rarely.
257
258If the filesystem is called for sync then it must wait on any
259in-progress I/O and then start new I/O.
260
261The filesystem should unlock the page synchronously, before returning to the
262caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
263value. WRITEPAGE_ACTIVATE means that page cannot really be written out
264currently, and VM should stop calling ->writepage() on this page for some
265time. VM does this by moving page to the head of the active list, hence the
266name.
267
268Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
269and return zero, writepage *must* run set_page_writeback() against the page,
270followed by unlocking it. Once set_page_writeback() has been run against the
271page, write I/O can be submitted and the write I/O completion handler must run
272end_page_writeback() once the I/O is complete. If no I/O is submitted, the
273filesystem must run end_page_writeback() against the page before returning from
274writepage.
275
276That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
277if the filesystem needs the page to be locked during writeout, that is ok, too,
278the page is allowed to be unlocked at any point in time between the calls to
279set_page_writeback() and end_page_writeback().
280
281Note, failure to run either redirty_page_for_writepage() or the combination of
282set_page_writeback()/end_page_writeback() on a page submitted to writepage
283will leave the page itself marked clean but it will be tagged as dirty in the
284radix tree. This incoherency can lead to all sorts of hard-to-debug problems
285in the filesystem like having dirty inodes at umount and losing written data.
286
287 ->sync_page() locking rules are not well-defined - usually it is called
288with lock on page, but that is not guaranteed. Considering the currently
289existing instances of this method ->sync_page() itself doesn't look
290well-defined...
291
292 ->writepages() is used for periodic writeback and for syscall-initiated
293sync operations. The address_space should start I/O against at least
294*nr_to_write pages. *nr_to_write must be decremented for each page which is
295written. The address_space implementation may write more (or less) pages
296than *nr_to_write asks for, but it should try to be reasonably close. If
297nr_to_write is NULL, all dirty pages must be written.
298
299writepages should _only_ write pages which are present on
300mapping->io_pages.
301
302 ->set_page_dirty() is called from various places in the kernel
303when the target page is marked as needing writeback. It may be called
304under spinlock (it cannot block) and is sometimes called with the page
305not locked.
306
307 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
308filesystems and by the swapper. The latter will eventually go away. Please,
309keep it that way and don't breed new callers.
310
311 ->invalidatepage() is called when the filesystem must attempt to drop
312some or all of the buffers from the page when it is being truncated. It
313returns zero on success. If ->invalidatepage is zero, the kernel uses
314block_invalidatepage() instead.
315
316 ->releasepage() is called when the kernel is about to try to drop the
317buffers from the page in preparation for freeing it. It returns zero to
318indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
319the kernel assumes that the fs has no private interest in the buffers.
320
321 ->freepage() is called when the kernel is done dropping the page
322from the page cache.
323
324 ->launder_page() may be called prior to releasing a page if
325it is still found to be dirty. It returns zero if the page was successfully
326cleaned, or an error value if not. Note that in order to prevent the page
327getting mapped back in and redirtied, it needs to be kept locked
328across the entire operation.
329
330----------------------- file_lock_operations ------------------------------
331prototypes:
332 void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
333 void (*fl_release_private)(struct file_lock *);
334
335
336locking rules:
337 file_lock_lock may block
338fl_copy_lock: yes no
339fl_release_private: maybe no
340
341----------------------- lock_manager_operations ---------------------------
342prototypes:
343 int (*lm_compare_owner)(struct file_lock *, struct file_lock *);
344 void (*lm_notify)(struct file_lock *); /* unblock callback */
345 int (*lm_grant)(struct file_lock *, struct file_lock *, int);
346 void (*lm_release_private)(struct file_lock *);
347 void (*lm_break)(struct file_lock *); /* break_lease callback */
348 int (*lm_change)(struct file_lock **, int);
349
350locking rules:
351 file_lock_lock may block
352lm_compare_owner: yes no
353lm_notify: yes no
354lm_grant: no no
355lm_release_private: maybe no
356lm_break: yes no
357lm_change yes no
358
359--------------------------- buffer_head -----------------------------------
360prototypes:
361 void (*b_end_io)(struct buffer_head *bh, int uptodate);
362
363locking rules:
364 called from interrupts. In other words, extreme care is needed here.
365bh is locked, but that's all warranties we have here. Currently only RAID1,
366highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
367call this method upon the IO completion.
368
369--------------------------- block_device_operations -----------------------
370prototypes:
371 int (*open) (struct block_device *, fmode_t);
372 int (*release) (struct gendisk *, fmode_t);
373 int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
374 int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
375 int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *);
376 int (*media_changed) (struct gendisk *);
377 void (*unlock_native_capacity) (struct gendisk *);
378 int (*revalidate_disk) (struct gendisk *);
379 int (*getgeo)(struct block_device *, struct hd_geometry *);
380 void (*swap_slot_free_notify) (struct block_device *, unsigned long);
381
382locking rules:
383 bd_mutex
384open: yes
385release: yes
386ioctl: no
387compat_ioctl: no
388direct_access: no
389media_changed: no
390unlock_native_capacity: no
391revalidate_disk: no
392getgeo: no
393swap_slot_free_notify: no (see below)
394
395media_changed, unlock_native_capacity and revalidate_disk are called only from
396check_disk_change().
397
398swap_slot_free_notify is called with swap_lock and sometimes the page lock
399held.
400
401
402--------------------------- file_operations -------------------------------
403prototypes:
404 loff_t (*llseek) (struct file *, loff_t, int);
405 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
406 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
407 ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
408 ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
409 int (*readdir) (struct file *, void *, filldir_t);
410 unsigned int (*poll) (struct file *, struct poll_table_struct *);
411 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
412 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
413 int (*mmap) (struct file *, struct vm_area_struct *);
414 int (*open) (struct inode *, struct file *);
415 int (*flush) (struct file *);
416 int (*release) (struct inode *, struct file *);
417 int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
418 int (*aio_fsync) (struct kiocb *, int datasync);
419 int (*fasync) (int, struct file *, int);
420 int (*lock) (struct file *, int, struct file_lock *);
421 ssize_t (*readv) (struct file *, const struct iovec *, unsigned long,
422 loff_t *);
423 ssize_t (*writev) (struct file *, const struct iovec *, unsigned long,
424 loff_t *);
425 ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
426 void __user *);
427 ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
428 loff_t *, int);
429 unsigned long (*get_unmapped_area)(struct file *, unsigned long,
430 unsigned long, unsigned long, unsigned long);
431 int (*check_flags)(int);
432 int (*flock) (struct file *, int, struct file_lock *);
433 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
434 size_t, unsigned int);
435 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
436 size_t, unsigned int);
437 int (*setlease)(struct file *, long, struct file_lock **);
438 long (*fallocate)(struct file *, int, loff_t, loff_t);
439};
440
441locking rules:
442 All may block except for ->setlease.
443 No VFS locks held on entry except for ->setlease.
444
445->setlease has the file_list_lock held and must not sleep.
446
447->llseek() locking has moved from llseek to the individual llseek
448implementations. If your fs is not using generic_file_llseek, you
449need to acquire and release the appropriate locks in your ->llseek().
450For many filesystems, it is probably safe to acquire the inode
451mutex or just to use i_size_read() instead.
452Note: this does not protect the file->f_pos against concurrent modifications
453since this is something the userspace has to take care about.
454
455->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
456Most instances call fasync_helper(), which does that maintenance, so it's
457not normally something one needs to worry about. Return values > 0 will be
458mapped to zero in the VFS layer.
459
460->readdir() and ->ioctl() on directories must be changed. Ideally we would
461move ->readdir() to inode_operations and use a separate method for directory
462->ioctl() or kill the latter completely. One of the problems is that for
463anything that resembles union-mount we won't have a struct file for all
464components. And there are other reasons why the current interface is a mess...
465
466->read on directories probably must go away - we should just enforce -EISDIR
467in sys_read() and friends.
468
469--------------------------- dquot_operations -------------------------------
470prototypes:
471 int (*write_dquot) (struct dquot *);
472 int (*acquire_dquot) (struct dquot *);
473 int (*release_dquot) (struct dquot *);
474 int (*mark_dirty) (struct dquot *);
475 int (*write_info) (struct super_block *, int);
476
477These operations are intended to be more or less wrapping functions that ensure
478a proper locking wrt the filesystem and call the generic quota operations.
479
480What filesystem should expect from the generic quota functions:
481
482 FS recursion Held locks when called
483write_dquot: yes dqonoff_sem or dqptr_sem
484acquire_dquot: yes dqonoff_sem or dqptr_sem
485release_dquot: yes dqonoff_sem or dqptr_sem
486mark_dirty: no -
487write_info: yes dqonoff_sem
488
489FS recursion means calling ->quota_read() and ->quota_write() from superblock
490operations.
491
492More details about quota locking can be found in fs/dquot.c.
493
494--------------------------- vm_operations_struct -----------------------------
495prototypes:
496 void (*open)(struct vm_area_struct*);
497 void (*close)(struct vm_area_struct*);
498 int (*fault)(struct vm_area_struct*, struct vm_fault *);
499 int (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
500 int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
501
502locking rules:
503 mmap_sem PageLocked(page)
504open: yes
505close: yes
506fault: yes can return with page locked
507page_mkwrite: yes can return with page locked
508access: yes
509
510 ->fault() is called when a previously not present pte is about
511to be faulted in. The filesystem must find and return the page associated
512with the passed in "pgoff" in the vm_fault structure. If it is possible that
513the page may be truncated and/or invalidated, then the filesystem must lock
514the page, then ensure it is not already truncated (the page lock will block
515subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
516locked. The VM will unlock the page.
517
518 ->page_mkwrite() is called when a previously read-only pte is
519about to become writeable. The filesystem again must ensure that there are
520no truncate/invalidate races, and then return with the page locked. If
521the page has been truncated, the filesystem should not look up a new page
522like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
523will cause the VM to retry the fault.
524
525 ->access() is called when get_user_pages() fails in
526acces_process_vm(), typically used to debug a process through
527/proc/pid/mem or ptrace. This function is needed only for
528VM_IO | VM_PFNMAP VMAs.
529
530================================================================================
531 Dubious stuff
532
533(if you break something or notice that it is broken and do not fix it yourself
534- at least put it here)