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