Documentation/filesystems/locking.rst

   1 =======
   2 Locking
   3 =======
   4
   5 The text below describes the locking rules for VFS-related methods.
   6 It is (believed to be) up-to-date. *Please*, if you change anything in
   7 prototypes or locking protocols - update this file. And update the relevant
   8 instances in the tree, don't leave that to maintainers of filesystems/devices/
   9 etc. At the very least, put the list of dubious cases in the end of this file.
  10 Don't turn it into log - maintainers of out-of-the-tree code are supposed to
  11 be able to use diff(1).
  12
  13 Thing currently missing here: socket operations. Alexey?
  14
  15 dentry_operations
  16 =================
  17
  18 prototypes::
  19
  20         int (*d_revalidate)(struct inode *, const struct qstr *,
  21                             struct dentry *, unsigned int);
  22         int (*d_weak_revalidate)(struct dentry *, unsigned int);
  23         int (*d_hash)(const struct dentry *, struct qstr *);
  24         int (*d_compare)(const struct dentry *,
  25                         unsigned int, const char *, const struct qstr *);
  26         int (*d_delete)(struct dentry *);
  27         int (*d_init)(struct dentry *);
  28         void (*d_release)(struct dentry *);
  29         void (*d_iput)(struct dentry *, struct inode *);
  30         char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
  31         struct vfsmount *(*d_automount)(struct path *path);
  32         int (*d_manage)(const struct path *, bool);
  33         struct dentry *(*d_real)(struct dentry *, enum d_real_type type);
  34         bool (*d_unalias_trylock)(const struct dentry *);
  35         void (*d_unalias_unlock)(const struct dentry *);
  36
  37 locking rules:
  38
  39 ================== ===========  ========        ==============  ========
  40 ops                rename_lock  ->d_lock        may block       rcu-walk
  41 ================== ===========  ========        ==============  ========
  42 d_revalidate:      no           no              yes (ref-walk)  maybe
  43 d_weak_revalidate: no           no              yes             no
  44 d_hash             no           no              no              maybe
  45 d_compare:         yes          no              no              maybe
  46 d_delete:          no           yes             no              no
  47 d_init:            no           no              yes             no
  48 d_release:         no           no              yes             no
  49 d_prune:           no           yes             no              no
  50 d_iput:            no           no              yes             no
  51 d_dname:           no           no              no              no
  52 d_automount:       no           no              yes             no
  53 d_manage:          no           no              yes (ref-walk)  maybe
  54 d_real             no           no              yes             no
  55 d_unalias_trylock  yes          no              no              no
  56 d_unalias_unlock   yes          no              no              no
  57 ================== ===========  ========        ==============  ========
  58
  59 inode_operations
  60 ================
  61
  62 prototypes::
  63
  64         int (*create) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t, bool);
  65         struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
  66         int (*link) (struct dentry *,struct inode *,struct dentry *);
  67         int (*unlink) (struct inode *,struct dentry *);
  68         int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *);
  69         int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t);
  70         int (*rmdir) (struct inode *,struct dentry *);
  71         int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t);
  72         int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *,
  73                         struct inode *, struct dentry *, unsigned int);
  74         int (*readlink) (struct dentry *, char __user *,int);
  75         const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
  76         void (*truncate) (struct inode *);
  77         int (*permission) (struct mnt_idmap *, struct inode *, int, unsigned int);
  78         struct posix_acl * (*get_inode_acl)(struct inode *, int, bool);
  79         int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *);
  80         int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int);
  81         ssize_t (*listxattr) (struct dentry *, char *, size_t);
  82         int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
  83         void (*update_time)(struct inode *, struct timespec *, int);
  84         int (*atomic_open)(struct inode *, struct dentry *,
  85                                 struct file *, unsigned open_flag,
  86                                 umode_t create_mode);
  87         int (*tmpfile) (struct mnt_idmap *, struct inode *,
  88                         struct file *, umode_t);
  89         int (*fileattr_set)(struct mnt_idmap *idmap,
  90                             struct dentry *dentry, struct fileattr *fa);
  91         int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa);
  92         struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int);
  93         struct offset_ctx *(*get_offset_ctx)(struct inode *inode);
  94
  95 locking rules:
  96         all may block
  97
  98 ==============  ==================================================
  99 ops             i_rwsem(inode)
 100 ==============  ==================================================
 101 lookup:         shared
 102 create:         exclusive
 103 link:           exclusive (both)
 104 mknod:          exclusive
 105 symlink:        exclusive
 106 mkdir:          exclusive
 107 unlink:         exclusive (both)
 108 rmdir:          exclusive (both)(see below)
 109 rename:         exclusive (both parents, some children) (see below)
 110 readlink:       no
 111 get_link:       no
 112 setattr:        exclusive
 113 permission:     no (may not block if called in rcu-walk mode)
 114 get_inode_acl:  no
 115 get_acl:        no
 116 getattr:        no
 117 listxattr:      no
 118 fiemap:         no
 119 update_time:    no
 120 atomic_open:    shared (exclusive if O_CREAT is set in open flags)
 121 tmpfile:        no
 122 fileattr_get:   no or exclusive
 123 fileattr_set:   exclusive
 124 get_offset_ctx  no
 125 ==============  ==================================================
 126
 127
 128         Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
 129         exclusive on victim.
 130         cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
 131         ->unlink() and ->rename() have ->i_rwsem exclusive on all non-directories
 132         involved.
 133         ->rename() has ->i_rwsem exclusive on any subdirectory that changes parent.
 134
 135 See Documentation/filesystems/directory-locking.rst for more detailed discussion
 136 of the locking scheme for directory operations.
 137
 138 xattr_handler operations
 139 ========================
 140
 141 prototypes::
 142
 143         bool (*list)(struct dentry *dentry);
 144         int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
 145                    struct inode *inode, const char *name, void *buffer,
 146                    size_t size);
 147         int (*set)(const struct xattr_handler *handler,
 148                    struct mnt_idmap *idmap,
 149                    struct dentry *dentry, struct inode *inode, const char *name,
 150                    const void *buffer, size_t size, int flags);
 151
 152 locking rules:
 153         all may block
 154
 155 =====           ==============
 156 ops             i_rwsem(inode)
 157 =====           ==============
 158 list:           no
 159 get:            no
 160 set:            exclusive
 161 =====           ==============
 162
 163 super_operations
 164 ================
 165
 166 prototypes::
 167
 168         struct inode *(*alloc_inode)(struct super_block *sb);
 169         void (*free_inode)(struct inode *);
 170         void (*destroy_inode)(struct inode *);
 171         void (*dirty_inode) (struct inode *, int flags);
 172         int (*write_inode) (struct inode *, struct writeback_control *wbc);
 173         int (*drop_inode) (struct inode *);
 174         void (*evict_inode) (struct inode *);
 175         void (*put_super) (struct super_block *);
 176         int (*sync_fs)(struct super_block *sb, int wait);
 177         int (*freeze_fs) (struct super_block *);
 178         int (*unfreeze_fs) (struct super_block *);
 179         int (*statfs) (struct dentry *, struct kstatfs *);
 180         int (*remount_fs) (struct super_block *, int *, char *);
 181         void (*umount_begin) (struct super_block *);
 182         int (*show_options)(struct seq_file *, struct dentry *);
 183         ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
 184         ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
 185
 186 locking rules:
 187         All may block [not true, see below]
 188
 189 ======================  ============    ========================
 190 ops                     s_umount        note
 191 ======================  ============    ========================
 192 alloc_inode:
 193 free_inode:                             called from RCU callback
 194 destroy_inode:
 195 dirty_inode:
 196 write_inode:
 197 drop_inode:                             !!!inode->i_lock!!!
 198 evict_inode:
 199 put_super:              write
 200 sync_fs:                read
 201 freeze_fs:              write
 202 unfreeze_fs:            write
 203 statfs:                 maybe(read)     (see below)
 204 remount_fs:             write
 205 umount_begin:           no
 206 show_options:           no              (namespace_sem)
 207 quota_read:             no              (see below)
 208 quota_write:            no              (see below)
 209 ======================  ============    ========================
 210
 211 ->statfs() has s_umount (shared) when called by ustat(2) (native or
 212 compat), but that's an accident of bad API; s_umount is used to pin
 213 the superblock down when we only have dev_t given us by userland to
 214 identify the superblock.  Everything else (statfs(), fstatfs(), etc.)
 215 doesn't hold it when calling ->statfs() - superblock is pinned down
 216 by resolving the pathname passed to syscall.
 217
 218 ->quota_read() and ->quota_write() functions are both guaranteed to
 219 be the only ones operating on the quota file by the quota code (via
 220 dqio_sem) (unless an admin really wants to screw up something and
 221 writes to quota files with quotas on). For other details about locking
 222 see also dquot_operations section.
 223
 224 file_system_type
 225 ================
 226
 227 prototypes::
 228
 229         struct dentry *(*mount) (struct file_system_type *, int,
 230                        const char *, void *);
 231         void (*kill_sb) (struct super_block *);
 232
 233 locking rules:
 234
 235 =======         =========
 236 ops             may block
 237 =======         =========
 238 mount           yes
 239 kill_sb         yes
 240 =======         =========
 241
 242 ->mount() returns ERR_PTR or the root dentry; its superblock should be locked
 243 on return.
 244
 245 ->kill_sb() takes a write-locked superblock, does all shutdown work on it,
 246 unlocks and drops the reference.
 247
 248 address_space_operations
 249 ========================
 250 prototypes::
 251
 252         int (*writepage)(struct page *page, struct writeback_control *wbc);
 253         int (*read_folio)(struct file *, struct folio *);
 254         int (*writepages)(struct address_space *, struct writeback_control *);
 255         bool (*dirty_folio)(struct address_space *, struct folio *folio);
 256         void (*readahead)(struct readahead_control *);
 257         int (*write_begin)(struct file *, struct address_space *mapping,
 258                                 loff_t pos, unsigned len,
 259                                 struct folio **foliop, void **fsdata);
 260         int (*write_end)(struct file *, struct address_space *mapping,
 261                                 loff_t pos, unsigned len, unsigned copied,
 262                                 struct folio *folio, void *fsdata);
 263         sector_t (*bmap)(struct address_space *, sector_t);
 264         void (*invalidate_folio) (struct folio *, size_t start, size_t len);
 265         bool (*release_folio)(struct folio *, gfp_t);
 266         void (*free_folio)(struct folio *);
 267         int (*direct_IO)(struct kiocb *, struct iov_iter *iter);
 268         int (*migrate_folio)(struct address_space *, struct folio *dst,
 269                         struct folio *src, enum migrate_mode);
 270         int (*launder_folio)(struct folio *);
 271         bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count);
 272         int (*error_remove_folio)(struct address_space *, struct folio *);
 273         int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span)
 274         int (*swap_deactivate)(struct file *);
 275         int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter);
 276
 277 locking rules:
 278         All except dirty_folio and free_folio may block
 279
 280 ======================  ======================== =========      ===============
 281 ops                     folio locked             i_rwsem        invalidate_lock
 282 ======================  ======================== =========      ===============
 283 writepage:              yes, unlocks (see below)
 284 read_folio:             yes, unlocks                            shared
 285 writepages:
 286 dirty_folio:            maybe
 287 readahead:              yes, unlocks                            shared
 288 write_begin:            locks the folio          exclusive
 289 write_end:              yes, unlocks             exclusive
 290 bmap:
 291 invalidate_folio:       yes                                     exclusive
 292 release_folio:          yes
 293 free_folio:             yes
 294 direct_IO:
 295 migrate_folio:          yes (both)
 296 launder_folio:          yes
 297 is_partially_uptodate:  yes
 298 error_remove_folio:     yes
 299 swap_activate:          no
 300 swap_deactivate:        no
 301 swap_rw:                yes, unlocks
 302 ======================  ======================== =========      ===============
 303
 304 ->write_begin(), ->write_end() and ->read_folio() may be called from
 305 the request handler (/dev/loop).
 306
 307 ->read_folio() unlocks the folio, either synchronously or via I/O
 308 completion.
 309
 310 ->readahead() unlocks the folios that I/O is attempted on like ->read_folio().
 311
 312 ->writepage() is used for two purposes: for "memory cleansing" and for
 313 "sync".  These are quite different operations and the behaviour may differ
 314 depending upon the mode.
 315
 316 If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
 317 it *must* start I/O against the page, even if that would involve
 318 blocking on in-progress I/O.
 319
 320 If writepage is called for memory cleansing (sync_mode ==
 321 WBC_SYNC_NONE) then its role is to get as much writeout underway as
 322 possible.  So writepage should try to avoid blocking against
 323 currently-in-progress I/O.
 324
 325 If the filesystem is not called for "sync" and it determines that it
 326 would need to block against in-progress I/O to be able to start new I/O
 327 against the page the filesystem should redirty the page with
 328 redirty_page_for_writepage(), then unlock the page and return zero.
 329 This may also be done to avoid internal deadlocks, but rarely.
 330
 331 If the filesystem is called for sync then it must wait on any
 332 in-progress I/O and then start new I/O.
 333
 334 The filesystem should unlock the page synchronously, before returning to the
 335 caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
 336 value. WRITEPAGE_ACTIVATE means that page cannot really be written out
 337 currently, and VM should stop calling ->writepage() on this page for some
 338 time. VM does this by moving page to the head of the active list, hence the
 339 name.
 340
 341 Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
 342 and return zero, writepage *must* run set_page_writeback() against the page,
 343 followed by unlocking it.  Once set_page_writeback() has been run against the
 344 page, write I/O can be submitted and the write I/O completion handler must run
 345 end_page_writeback() once the I/O is complete.  If no I/O is submitted, the
 346 filesystem must run end_page_writeback() against the page before returning from
 347 writepage.
 348
 349 That is: after 2.5.12, pages which are under writeout are *not* locked.  Note,
 350 if the filesystem needs the page to be locked during writeout, that is ok, too,
 351 the page is allowed to be unlocked at any point in time between the calls to
 352 set_page_writeback() and end_page_writeback().
 353
 354 Note, failure to run either redirty_page_for_writepage() or the combination of
 355 set_page_writeback()/end_page_writeback() on a page submitted to writepage
 356 will leave the page itself marked clean but it will be tagged as dirty in the
 357 radix tree.  This incoherency can lead to all sorts of hard-to-debug problems
 358 in the filesystem like having dirty inodes at umount and losing written data.
 359
 360 ->writepages() is used for periodic writeback and for syscall-initiated
 361 sync operations.  The address_space should start I/O against at least
 362 ``*nr_to_write`` pages.  ``*nr_to_write`` must be decremented for each page
 363 which is written.  The address_space implementation may write more (or less)
 364 pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
 365 If nr_to_write is NULL, all dirty pages must be written.
 366
 367 writepages should _only_ write pages which are present on
 368 mapping->io_pages.
 369
 370 ->dirty_folio() is called from various places in the kernel when
 371 the target folio is marked as needing writeback.  The folio cannot be
 372 truncated because either the caller holds the folio lock, or the caller
 373 has found the folio while holding the page table lock which will block
 374 truncation.
 375
 376 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
 377 filesystems and by the swapper. The latter will eventually go away.  Please,
 378 keep it that way and don't breed new callers.
 379
 380 ->invalidate_folio() is called when the filesystem must attempt to drop
 381 some or all of the buffers from the page when it is being truncated. It
 382 returns zero on success.  The filesystem must exclusively acquire
 383 invalidate_lock before invalidating page cache in truncate / hole punch
 384 path (and thus calling into ->invalidate_folio) to block races between page
 385 cache invalidation and page cache filling functions (fault, read, ...).
 386
 387 ->release_folio() is called when the MM wants to make a change to the
 388 folio that would invalidate the filesystem's private data.  For example,
 389 it may be about to be removed from the address_space or split.  The folio
 390 is locked and not under writeback.  It may be dirty.  The gfp parameter
 391 is not usually used for allocation, but rather to indicate what the
 392 filesystem may do to attempt to free the private data.  The filesystem may
 393 return false to indicate that the folio's private data cannot be freed.
 394 If it returns true, it should have already removed the private data from
 395 the folio.  If a filesystem does not provide a ->release_folio method,
 396 the pagecache will assume that private data is buffer_heads and call
 397 try_to_free_buffers().
 398
 399 ->free_folio() is called when the kernel has dropped the folio
 400 from the page cache.
 401
 402 ->launder_folio() may be called prior to releasing a folio if
 403 it is still found to be dirty. It returns zero if the folio was successfully
 404 cleaned, or an error value if not. Note that in order to prevent the folio
 405 getting mapped back in and redirtied, it needs to be kept locked
 406 across the entire operation.
 407
 408 ->swap_activate() will be called to prepare the given file for swap.  It
 409 should perform any validation and preparation necessary to ensure that
 410 writes can be performed with minimal memory allocation.  It should call
 411 add_swap_extent(), or the helper iomap_swapfile_activate(), and return
 412 the number of extents added.  If IO should be submitted through
 413 ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will be submitted
 414 directly to the block device ``sis->bdev``.
 415
 416 ->swap_deactivate() will be called in the sys_swapoff()
 417 path after ->swap_activate() returned success.
 418
 419 ->swap_rw will be called for swap IO if SWP_FS_OPS was set by ->swap_activate().
 420
 421 file_lock_operations
 422 ====================
 423
 424 prototypes::
 425
 426         void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
 427         void (*fl_release_private)(struct file_lock *);
 428
 429
 430 locking rules:
 431
 432 ===================     =============   =========
 433 ops                     inode->i_lock   may block
 434 ===================     =============   =========
 435 fl_copy_lock:           yes             no
 436 fl_release_private:     maybe           maybe[1]_
 437 ===================     =============   =========
 438
 439 .. [1]:
 440    ->fl_release_private for flock or POSIX locks is currently allowed
 441    to block. Leases however can still be freed while the i_lock is held and
 442    so fl_release_private called on a lease should not block.
 443
 444 lock_manager_operations
 445 =======================
 446
 447 prototypes::
 448
 449         void (*lm_notify)(struct file_lock *);  /* unblock callback */
 450         int (*lm_grant)(struct file_lock *, struct file_lock *, int);
 451         void (*lm_break)(struct file_lock *); /* break_lease callback */
 452         int (*lm_change)(struct file_lock **, int);
 453         bool (*lm_breaker_owns_lease)(struct file_lock *);
 454         bool (*lm_lock_expirable)(struct file_lock *);
 455         void (*lm_expire_lock)(void);
 456
 457 locking rules:
 458
 459 ======================  =============   =================       =========
 460 ops                        flc_lock     blocked_lock_lock       may block
 461 ======================  =============   =================       =========
 462 lm_notify:              no              yes                     no
 463 lm_grant:               no              no                      no
 464 lm_break:               yes             no                      no
 465 lm_change               yes             no                      no
 466 lm_breaker_owns_lease:  yes             no                      no
 467 lm_lock_expirable       yes             no                      no
 468 lm_expire_lock          no              no                      yes
 469 ======================  =============   =================       =========
 470
 471 buffer_head
 472 ===========
 473
 474 prototypes::
 475
 476         void (*b_end_io)(struct buffer_head *bh, int uptodate);
 477
 478 locking rules:
 479
 480 called from interrupts. In other words, extreme care is needed here.
 481 bh is locked, but that's all warranties we have here. Currently only RAID1,
 482 highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
 483 call this method upon the IO completion.
 484
 485 block_device_operations
 486 =======================
 487 prototypes::
 488
 489         int (*open) (struct block_device *, fmode_t);
 490         int (*release) (struct gendisk *, fmode_t);
 491         int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
 492         int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
 493         int (*direct_access) (struct block_device *, sector_t, void **,
 494                                 unsigned long *);
 495         void (*unlock_native_capacity) (struct gendisk *);
 496         int (*getgeo)(struct block_device *, struct hd_geometry *);
 497         void (*swap_slot_free_notify) (struct block_device *, unsigned long);
 498
 499 locking rules:
 500
 501 ======================= ===================
 502 ops                     open_mutex
 503 ======================= ===================
 504 open:                   yes
 505 release:                yes
 506 ioctl:                  no
 507 compat_ioctl:           no
 508 direct_access:          no
 509 unlock_native_capacity: no
 510 getgeo:                 no
 511 swap_slot_free_notify:  no      (see below)
 512 ======================= ===================
 513
 514 swap_slot_free_notify is called with swap_lock and sometimes the page lock
 515 held.
 516
 517
 518 file_operations
 519 ===============
 520
 521 prototypes::
 522
 523         loff_t (*llseek) (struct file *, loff_t, int);
 524         ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
 525         ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
 526         ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
 527         ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
 528         int (*iopoll) (struct kiocb *kiocb, bool spin);
 529         int (*iterate_shared) (struct file *, struct dir_context *);
 530         __poll_t (*poll) (struct file *, struct poll_table_struct *);
 531         long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
 532         long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
 533         int (*mmap) (struct file *, struct vm_area_struct *);
 534         int (*open) (struct inode *, struct file *);
 535         int (*flush) (struct file *);
 536         int (*release) (struct inode *, struct file *);
 537         int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
 538         int (*fasync) (int, struct file *, int);
 539         int (*lock) (struct file *, int, struct file_lock *);
 540         unsigned long (*get_unmapped_area)(struct file *, unsigned long,
 541                         unsigned long, unsigned long, unsigned long);
 542         int (*check_flags)(int);
 543         int (*flock) (struct file *, int, struct file_lock *);
 544         ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
 545                         size_t, unsigned int);
 546         ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
 547                         size_t, unsigned int);
 548         int (*setlease)(struct file *, long, struct file_lock **, void **);
 549         long (*fallocate)(struct file *, int, loff_t, loff_t);
 550         void (*show_fdinfo)(struct seq_file *m, struct file *f);
 551         unsigned (*mmap_capabilities)(struct file *);
 552         ssize_t (*copy_file_range)(struct file *, loff_t, struct file *,
 553                         loff_t, size_t, unsigned int);
 554         loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,
 555                         struct file *file_out, loff_t pos_out,
 556                         loff_t len, unsigned int remap_flags);
 557         int (*fadvise)(struct file *, loff_t, loff_t, int);
 558
 559 locking rules:
 560         All may block.
 561
 562 ->llseek() locking has moved from llseek to the individual llseek
 563 implementations.  If your fs is not using generic_file_llseek, you
 564 need to acquire and release the appropriate locks in your ->llseek().
 565 For many filesystems, it is probably safe to acquire the inode
 566 mutex or just to use i_size_read() instead.
 567 Note: this does not protect the file->f_pos against concurrent modifications
 568 since this is something the userspace has to take care about.
 569
 570 ->iterate_shared() is called with i_rwsem held for reading, and with the
 571 file f_pos_lock held exclusively
 572
 573 ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
 574 Most instances call fasync_helper(), which does that maintenance, so it's
 575 not normally something one needs to worry about.  Return values > 0 will be
 576 mapped to zero in the VFS layer.
 577
 578 ->readdir() and ->ioctl() on directories must be changed. Ideally we would
 579 move ->readdir() to inode_operations and use a separate method for directory
 580 ->ioctl() or kill the latter completely. One of the problems is that for
 581 anything that resembles union-mount we won't have a struct file for all
 582 components. And there are other reasons why the current interface is a mess...
 583
 584 ->read on directories probably must go away - we should just enforce -EISDIR
 585 in sys_read() and friends.
 586
 587 ->setlease operations should call generic_setlease() before or after setting
 588 the lease within the individual filesystem to record the result of the
 589 operation
 590
 591 ->fallocate implementation must be really careful to maintain page cache
 592 consistency when punching holes or performing other operations that invalidate
 593 page cache contents. Usually the filesystem needs to call
 594 truncate_inode_pages_range() to invalidate relevant range of the page cache.
 595 However the filesystem usually also needs to update its internal (and on disk)
 596 view of file offset -> disk block mapping. Until this update is finished, the
 597 filesystem needs to block page faults and reads from reloading now-stale page
 598 cache contents from the disk. Since VFS acquires mapping->invalidate_lock in
 599 shared mode when loading pages from disk (filemap_fault(), filemap_read(),
 600 readahead paths), the fallocate implementation must take the invalidate_lock to
 601 prevent reloading.
 602
 603 ->copy_file_range and ->remap_file_range implementations need to serialize
 604 against modifications of file data while the operation is running. For
 605 blocking changes through write(2) and similar operations inode->i_rwsem can be
 606 used. To block changes to file contents via a memory mapping during the
 607 operation, the filesystem must take mapping->invalidate_lock to coordinate
 608 with ->page_mkwrite.
 609
 610 dquot_operations
 611 ================
 612
 613 prototypes::
 614
 615         int (*write_dquot) (struct dquot *);
 616         int (*acquire_dquot) (struct dquot *);
 617         int (*release_dquot) (struct dquot *);
 618         int (*mark_dirty) (struct dquot *);
 619         int (*write_info) (struct super_block *, int);
 620
 621 These operations are intended to be more or less wrapping functions that ensure
 622 a proper locking wrt the filesystem and call the generic quota operations.
 623
 624 What filesystem should expect from the generic quota functions:
 625
 626 ==============  ============    =========================
 627 ops             FS recursion    Held locks when called
 628 ==============  ============    =========================
 629 write_dquot:    yes             dqonoff_sem or dqptr_sem
 630 acquire_dquot:  yes             dqonoff_sem or dqptr_sem
 631 release_dquot:  yes             dqonoff_sem or dqptr_sem
 632 mark_dirty:     no              -
 633 write_info:     yes             dqonoff_sem
 634 ==============  ============    =========================
 635
 636 FS recursion means calling ->quota_read() and ->quota_write() from superblock
 637 operations.
 638
 639 More details about quota locking can be found in fs/dquot.c.
 640
 641 vm_operations_struct
 642 ====================
 643
 644 prototypes::
 645
 646         void (*open)(struct vm_area_struct *);
 647         void (*close)(struct vm_area_struct *);
 648         vm_fault_t (*fault)(struct vm_fault *);
 649         vm_fault_t (*huge_fault)(struct vm_fault *, unsigned int order);
 650         vm_fault_t (*map_pages)(struct vm_fault *, pgoff_t start, pgoff_t end);
 651         vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
 652         vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
 653         int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
 654
 655 locking rules:
 656
 657 =============   ==========      ===========================
 658 ops             mmap_lock       PageLocked(page)
 659 =============   ==========      ===========================
 660 open:           write
 661 close:          read/write
 662 fault:          read            can return with page locked
 663 huge_fault:     maybe-read
 664 map_pages:      maybe-read
 665 page_mkwrite:   read            can return with page locked
 666 pfn_mkwrite:    read
 667 access:         read
 668 =============   ==========      ===========================
 669
 670 ->fault() is called when a previously not present pte is about to be faulted
 671 in. The filesystem must find and return the page associated with the passed in
 672 "pgoff" in the vm_fault structure. If it is possible that the page may be
 673 truncated and/or invalidated, then the filesystem must lock invalidate_lock,
 674 then ensure the page is not already truncated (invalidate_lock will block
 675 subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
 676 locked. The VM will unlock the page.
 677
 678 ->huge_fault() is called when there is no PUD or PMD entry present.  This
 679 gives the filesystem the opportunity to install a PUD or PMD sized page.
 680 Filesystems can also use the ->fault method to return a PMD sized page,
 681 so implementing this function may not be necessary.  In particular,
 682 filesystems should not call filemap_fault() from ->huge_fault().
 683 The mmap_lock may not be held when this method is called.
 684
 685 ->map_pages() is called when VM asks to map easy accessible pages.
 686 Filesystem should find and map pages associated with offsets from "start_pgoff"
 687 till "end_pgoff". ->map_pages() is called with the RCU lock held and must
 688 not block.  If it's not possible to reach a page without blocking,
 689 filesystem should skip it. Filesystem should use set_pte_range() to setup
 690 page table entry. Pointer to entry associated with the page is passed in
 691 "pte" field in vm_fault structure. Pointers to entries for other offsets
 692 should be calculated relative to "pte".
 693
 694 ->page_mkwrite() is called when a previously read-only pte is about to become
 695 writeable. The filesystem again must ensure that there are no
 696 truncate/invalidate races or races with operations such as ->remap_file_range
 697 or ->copy_file_range, and then return with the page locked. Usually
 698 mapping->invalidate_lock is suitable for proper serialization. If the page has
 699 been truncated, the filesystem should not look up a new page like the ->fault()
 700 handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to
 701 retry the fault.
 702
 703 ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
 704 VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
 705 VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
 706 after this call is to make the pte read-write, unless pfn_mkwrite returns
 707 an error.
 708
 709 ->access() is called when get_user_pages() fails in
 710 access_process_vm(), typically used to debug a process through
 711 /proc/pid/mem or ptrace.  This function is needed only for
 712 VM_IO | VM_PFNMAP VMAs.
 713
 714 --------------------------------------------------------------------------------
 715
 716                         Dubious stuff
 717
 718 (if you break something or notice that it is broken and do not fix it yourself
 719 - at least put it here)