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