0001 =======
0002 Locking
0003 =======
0004
0005 The text below describes the locking rules for VFS-related methods.
0006 It is (believed to be) up-to-date. *Please*, if you change anything in
0007 prototypes or locking protocols - update this file. And update the relevant
0008 instances in the tree, don't leave that to maintainers of filesystems/devices/
0009 etc. At the very least, put the list of dubious cases in the end of this file.
0010 Don't turn it into log - maintainers of out-of-the-tree code are supposed to
0011 be able to use diff(1).
0012
0013 Thing currently missing here: socket operations. Alexey?
0014
0015 dentry_operations
0016 =================
0017
0018 prototypes::
0019
0020 int (*d_revalidate)(struct dentry *, unsigned int);
0021 int (*d_weak_revalidate)(struct dentry *, unsigned int);
0022 int (*d_hash)(const struct dentry *, struct qstr *);
0023 int (*d_compare)(const struct dentry *,
0024 unsigned int, const char *, const struct qstr *);
0025 int (*d_delete)(struct dentry *);
0026 int (*d_init)(struct dentry *);
0027 void (*d_release)(struct dentry *);
0028 void (*d_iput)(struct dentry *, struct inode *);
0029 char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
0030 struct vfsmount *(*d_automount)(struct path *path);
0031 int (*d_manage)(const struct path *, bool);
0032 struct dentry *(*d_real)(struct dentry *, const struct inode *);
0033
0034 locking rules:
0035
0036 ================== =========== ======== ============== ========
0037 ops rename_lock ->d_lock may block rcu-walk
0038 ================== =========== ======== ============== ========
0039 d_revalidate: no no yes (ref-walk) maybe
0040 d_weak_revalidate: no no yes no
0041 d_hash no no no maybe
0042 d_compare: yes no no maybe
0043 d_delete: no yes no no
0044 d_init: no no yes no
0045 d_release: no no yes no
0046 d_prune: no yes no no
0047 d_iput: no no yes no
0048 d_dname: no no no no
0049 d_automount: no no yes no
0050 d_manage: no no yes (ref-walk) maybe
0051 d_real no no yes no
0052 ================== =========== ======== ============== ========
0053
0054 inode_operations
0055 ================
0056
0057 prototypes::
0058
0059 int (*create) (struct inode *,struct dentry *,umode_t, bool);
0060 struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
0061 int (*link) (struct dentry *,struct inode *,struct dentry *);
0062 int (*unlink) (struct inode *,struct dentry *);
0063 int (*symlink) (struct inode *,struct dentry *,const char *);
0064 int (*mkdir) (struct inode *,struct dentry *,umode_t);
0065 int (*rmdir) (struct inode *,struct dentry *);
0066 int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
0067 int (*rename) (struct inode *, struct dentry *,
0068 struct inode *, struct dentry *, unsigned int);
0069 int (*readlink) (struct dentry *, char __user *,int);
0070 const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
0071 void (*truncate) (struct inode *);
0072 int (*permission) (struct inode *, int, unsigned int);
0073 struct posix_acl * (*get_acl)(struct inode *, int, bool);
0074 int (*setattr) (struct dentry *, struct iattr *);
0075 int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
0076 ssize_t (*listxattr) (struct dentry *, char *, size_t);
0077 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
0078 void (*update_time)(struct inode *, struct timespec *, int);
0079 int (*atomic_open)(struct inode *, struct dentry *,
0080 struct file *, unsigned open_flag,
0081 umode_t create_mode);
0082 int (*tmpfile) (struct inode *, struct dentry *, umode_t);
0083 int (*fileattr_set)(struct user_namespace *mnt_userns,
0084 struct dentry *dentry, struct fileattr *fa);
0085 int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa);
0086
0087 locking rules:
0088 all may block
0089
0090 ============= =============================================
0091 ops i_rwsem(inode)
0092 ============= =============================================
0093 lookup: shared
0094 create: exclusive
0095 link: exclusive (both)
0096 mknod: exclusive
0097 symlink: exclusive
0098 mkdir: exclusive
0099 unlink: exclusive (both)
0100 rmdir: exclusive (both)(see below)
0101 rename: exclusive (all) (see below)
0102 readlink: no
0103 get_link: no
0104 setattr: exclusive
0105 permission: no (may not block if called in rcu-walk mode)
0106 get_acl: no
0107 getattr: no
0108 listxattr: no
0109 fiemap: no
0110 update_time: no
0111 atomic_open: shared (exclusive if O_CREAT is set in open flags)
0112 tmpfile: no
0113 fileattr_get: no or exclusive
0114 fileattr_set: exclusive
0115 ============= =============================================
0116
0117
0118 Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
0119 exclusive on victim.
0120 cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
0121
0122 See Documentation/filesystems/directory-locking.rst for more detailed discussion
0123 of the locking scheme for directory operations.
0124
0125 xattr_handler operations
0126 ========================
0127
0128 prototypes::
0129
0130 bool (*list)(struct dentry *dentry);
0131 int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
0132 struct inode *inode, const char *name, void *buffer,
0133 size_t size);
0134 int (*set)(const struct xattr_handler *handler,
0135 struct user_namespace *mnt_userns,
0136 struct dentry *dentry, struct inode *inode, const char *name,
0137 const void *buffer, size_t size, int flags);
0138
0139 locking rules:
0140 all may block
0141
0142 ===== ==============
0143 ops i_rwsem(inode)
0144 ===== ==============
0145 list: no
0146 get: no
0147 set: exclusive
0148 ===== ==============
0149
0150 super_operations
0151 ================
0152
0153 prototypes::
0154
0155 struct inode *(*alloc_inode)(struct super_block *sb);
0156 void (*free_inode)(struct inode *);
0157 void (*destroy_inode)(struct inode *);
0158 void (*dirty_inode) (struct inode *, int flags);
0159 int (*write_inode) (struct inode *, struct writeback_control *wbc);
0160 int (*drop_inode) (struct inode *);
0161 void (*evict_inode) (struct inode *);
0162 void (*put_super) (struct super_block *);
0163 int (*sync_fs)(struct super_block *sb, int wait);
0164 int (*freeze_fs) (struct super_block *);
0165 int (*unfreeze_fs) (struct super_block *);
0166 int (*statfs) (struct dentry *, struct kstatfs *);
0167 int (*remount_fs) (struct super_block *, int *, char *);
0168 void (*umount_begin) (struct super_block *);
0169 int (*show_options)(struct seq_file *, struct dentry *);
0170 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
0171 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
0172
0173 locking rules:
0174 All may block [not true, see below]
0175
0176 ====================== ============ ========================
0177 ops s_umount note
0178 ====================== ============ ========================
0179 alloc_inode:
0180 free_inode: called from RCU callback
0181 destroy_inode:
0182 dirty_inode:
0183 write_inode:
0184 drop_inode: !!!inode->i_lock!!!
0185 evict_inode:
0186 put_super: write
0187 sync_fs: read
0188 freeze_fs: write
0189 unfreeze_fs: write
0190 statfs: maybe(read) (see below)
0191 remount_fs: write
0192 umount_begin: no
0193 show_options: no (namespace_sem)
0194 quota_read: no (see below)
0195 quota_write: no (see below)
0196 ====================== ============ ========================
0197
0198 ->statfs() has s_umount (shared) when called by ustat(2) (native or
0199 compat), but that's an accident of bad API; s_umount is used to pin
0200 the superblock down when we only have dev_t given us by userland to
0201 identify the superblock. Everything else (statfs(), fstatfs(), etc.)
0202 doesn't hold it when calling ->statfs() - superblock is pinned down
0203 by resolving the pathname passed to syscall.
0204
0205 ->quota_read() and ->quota_write() functions are both guaranteed to
0206 be the only ones operating on the quota file by the quota code (via
0207 dqio_sem) (unless an admin really wants to screw up something and
0208 writes to quota files with quotas on). For other details about locking
0209 see also dquot_operations section.
0210
0211 file_system_type
0212 ================
0213
0214 prototypes::
0215
0216 struct dentry *(*mount) (struct file_system_type *, int,
0217 const char *, void *);
0218 void (*kill_sb) (struct super_block *);
0219
0220 locking rules:
0221
0222 ======= =========
0223 ops may block
0224 ======= =========
0225 mount yes
0226 kill_sb yes
0227 ======= =========
0228
0229 ->mount() returns ERR_PTR or the root dentry; its superblock should be locked
0230 on return.
0231
0232 ->kill_sb() takes a write-locked superblock, does all shutdown work on it,
0233 unlocks and drops the reference.
0234
0235 address_space_operations
0236 ========================
0237 prototypes::
0238
0239 int (*writepage)(struct page *page, struct writeback_control *wbc);
0240 int (*read_folio)(struct file *, struct folio *);
0241 int (*writepages)(struct address_space *, struct writeback_control *);
0242 bool (*dirty_folio)(struct address_space *, struct folio *folio);
0243 void (*readahead)(struct readahead_control *);
0244 int (*write_begin)(struct file *, struct address_space *mapping,
0245 loff_t pos, unsigned len,
0246 struct page **pagep, void **fsdata);
0247 int (*write_end)(struct file *, struct address_space *mapping,
0248 loff_t pos, unsigned len, unsigned copied,
0249 struct page *page, void *fsdata);
0250 sector_t (*bmap)(struct address_space *, sector_t);
0251 void (*invalidate_folio) (struct folio *, size_t start, size_t len);
0252 bool (*release_folio)(struct folio *, gfp_t);
0253 void (*free_folio)(struct folio *);
0254 int (*direct_IO)(struct kiocb *, struct iov_iter *iter);
0255 int (*migrate_folio)(struct address_space *, struct folio *dst,
0256 struct folio *src, enum migrate_mode);
0257 int (*launder_folio)(struct folio *);
0258 bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count);
0259 int (*error_remove_page)(struct address_space *, struct page *);
0260 int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span)
0261 int (*swap_deactivate)(struct file *);
0262 int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter);
0263
0264 locking rules:
0265 All except dirty_folio and free_folio may block
0266
0267 ====================== ======================== ========= ===============
0268 ops folio locked i_rwsem invalidate_lock
0269 ====================== ======================== ========= ===============
0270 writepage: yes, unlocks (see below)
0271 read_folio: yes, unlocks shared
0272 writepages:
0273 dirty_folio: maybe
0274 readahead: yes, unlocks shared
0275 write_begin: locks the page exclusive
0276 write_end: yes, unlocks exclusive
0277 bmap:
0278 invalidate_folio: yes exclusive
0279 release_folio: yes
0280 free_folio: yes
0281 direct_IO:
0282 migrate_folio: yes (both)
0283 launder_folio: yes
0284 is_partially_uptodate: yes
0285 error_remove_page: yes
0286 swap_activate: no
0287 swap_deactivate: no
0288 swap_rw: yes, unlocks
0289 ====================== ======================== ========= ===============
0290
0291 ->write_begin(), ->write_end() and ->read_folio() may be called from
0292 the request handler (/dev/loop).
0293
0294 ->read_folio() unlocks the folio, either synchronously or via I/O
0295 completion.
0296
0297 ->readahead() unlocks the folios that I/O is attempted on like ->read_folio().
0298
0299 ->writepage() is used for two purposes: for "memory cleansing" and for
0300 "sync". These are quite different operations and the behaviour may differ
0301 depending upon the mode.
0302
0303 If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
0304 it *must* start I/O against the page, even if that would involve
0305 blocking on in-progress I/O.
0306
0307 If writepage is called for memory cleansing (sync_mode ==
0308 WBC_SYNC_NONE) then its role is to get as much writeout underway as
0309 possible. So writepage should try to avoid blocking against
0310 currently-in-progress I/O.
0311
0312 If the filesystem is not called for "sync" and it determines that it
0313 would need to block against in-progress I/O to be able to start new I/O
0314 against the page the filesystem should redirty the page with
0315 redirty_page_for_writepage(), then unlock the page and return zero.
0316 This may also be done to avoid internal deadlocks, but rarely.
0317
0318 If the filesystem is called for sync then it must wait on any
0319 in-progress I/O and then start new I/O.
0320
0321 The filesystem should unlock the page synchronously, before returning to the
0322 caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
0323 value. WRITEPAGE_ACTIVATE means that page cannot really be written out
0324 currently, and VM should stop calling ->writepage() on this page for some
0325 time. VM does this by moving page to the head of the active list, hence the
0326 name.
0327
0328 Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
0329 and return zero, writepage *must* run set_page_writeback() against the page,
0330 followed by unlocking it. Once set_page_writeback() has been run against the
0331 page, write I/O can be submitted and the write I/O completion handler must run
0332 end_page_writeback() once the I/O is complete. If no I/O is submitted, the
0333 filesystem must run end_page_writeback() against the page before returning from
0334 writepage.
0335
0336 That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
0337 if the filesystem needs the page to be locked during writeout, that is ok, too,
0338 the page is allowed to be unlocked at any point in time between the calls to
0339 set_page_writeback() and end_page_writeback().
0340
0341 Note, failure to run either redirty_page_for_writepage() or the combination of
0342 set_page_writeback()/end_page_writeback() on a page submitted to writepage
0343 will leave the page itself marked clean but it will be tagged as dirty in the
0344 radix tree. This incoherency can lead to all sorts of hard-to-debug problems
0345 in the filesystem like having dirty inodes at umount and losing written data.
0346
0347 ->writepages() is used for periodic writeback and for syscall-initiated
0348 sync operations. The address_space should start I/O against at least
0349 ``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
0350 which is written. The address_space implementation may write more (or less)
0351 pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
0352 If nr_to_write is NULL, all dirty pages must be written.
0353
0354 writepages should _only_ write pages which are present on
0355 mapping->io_pages.
0356
0357 ->dirty_folio() is called from various places in the kernel when
0358 the target folio is marked as needing writeback. The folio cannot be
0359 truncated because either the caller holds the folio lock, or the caller
0360 has found the folio while holding the page table lock which will block
0361 truncation.
0362
0363 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
0364 filesystems and by the swapper. The latter will eventually go away. Please,
0365 keep it that way and don't breed new callers.
0366
0367 ->invalidate_folio() is called when the filesystem must attempt to drop
0368 some or all of the buffers from the page when it is being truncated. It
0369 returns zero on success. The filesystem must exclusively acquire
0370 invalidate_lock before invalidating page cache in truncate / hole punch
0371 path (and thus calling into ->invalidate_folio) to block races between page
0372 cache invalidation and page cache filling functions (fault, read, ...).
0373
0374 ->release_folio() is called when the kernel is about to try to drop the
0375 buffers from the folio in preparation for freeing it. It returns false to
0376 indicate that the buffers are (or may be) freeable. If ->release_folio is
0377 NULL, the kernel assumes that the fs has no private interest in the buffers.
0378
0379 ->free_folio() is called when the kernel has dropped the folio
0380 from the page cache.
0381
0382 ->launder_folio() may be called prior to releasing a folio if
0383 it is still found to be dirty. It returns zero if the folio was successfully
0384 cleaned, or an error value if not. Note that in order to prevent the folio
0385 getting mapped back in and redirtied, it needs to be kept locked
0386 across the entire operation.
0387
0388 ->swap_activate() will be called to prepare the given file for swap. It
0389 should perform any validation and preparation necessary to ensure that
0390 writes can be performed with minimal memory allocation. It should call
0391 add_swap_extent(), or the helper iomap_swapfile_activate(), and return
0392 the number of extents added. If IO should be submitted through
0393 ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will be submitted
0394 directly to the block device ``sis->bdev``.
0395
0396 ->swap_deactivate() will be called in the sys_swapoff()
0397 path after ->swap_activate() returned success.
0398
0399 ->swap_rw will be called for swap IO if SWP_FS_OPS was set by ->swap_activate().
0400
0401 file_lock_operations
0402 ====================
0403
0404 prototypes::
0405
0406 void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
0407 void (*fl_release_private)(struct file_lock *);
0408
0409
0410 locking rules:
0411
0412 =================== ============= =========
0413 ops inode->i_lock may block
0414 =================== ============= =========
0415 fl_copy_lock: yes no
0416 fl_release_private: maybe maybe[1]_
0417 =================== ============= =========
0418
0419 .. [1]:
0420 ->fl_release_private for flock or POSIX locks is currently allowed
0421 to block. Leases however can still be freed while the i_lock is held and
0422 so fl_release_private called on a lease should not block.
0423
0424 lock_manager_operations
0425 =======================
0426
0427 prototypes::
0428
0429 void (*lm_notify)(struct file_lock *); /* unblock callback */
0430 int (*lm_grant)(struct file_lock *, struct file_lock *, int);
0431 void (*lm_break)(struct file_lock *); /* break_lease callback */
0432 int (*lm_change)(struct file_lock **, int);
0433 bool (*lm_breaker_owns_lease)(struct file_lock *);
0434 bool (*lm_lock_expirable)(struct file_lock *);
0435 void (*lm_expire_lock)(void);
0436
0437 locking rules:
0438
0439 ====================== ============= ================= =========
0440 ops flc_lock blocked_lock_lock may block
0441 ====================== ============= ================= =========
0442 lm_notify: no yes no
0443 lm_grant: no no no
0444 lm_break: yes no no
0445 lm_change yes no no
0446 lm_breaker_owns_lease: yes no no
0447 lm_lock_expirable yes no no
0448 lm_expire_lock no no yes
0449 ====================== ============= ================= =========
0450
0451 buffer_head
0452 ===========
0453
0454 prototypes::
0455
0456 void (*b_end_io)(struct buffer_head *bh, int uptodate);
0457
0458 locking rules:
0459
0460 called from interrupts. In other words, extreme care is needed here.
0461 bh is locked, but that's all warranties we have here. Currently only RAID1,
0462 highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
0463 call this method upon the IO completion.
0464
0465 block_device_operations
0466 =======================
0467 prototypes::
0468
0469 int (*open) (struct block_device *, fmode_t);
0470 int (*release) (struct gendisk *, fmode_t);
0471 int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
0472 int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
0473 int (*direct_access) (struct block_device *, sector_t, void **,
0474 unsigned long *);
0475 void (*unlock_native_capacity) (struct gendisk *);
0476 int (*getgeo)(struct block_device *, struct hd_geometry *);
0477 void (*swap_slot_free_notify) (struct block_device *, unsigned long);
0478
0479 locking rules:
0480
0481 ======================= ===================
0482 ops open_mutex
0483 ======================= ===================
0484 open: yes
0485 release: yes
0486 ioctl: no
0487 compat_ioctl: no
0488 direct_access: no
0489 unlock_native_capacity: no
0490 getgeo: no
0491 swap_slot_free_notify: no (see below)
0492 ======================= ===================
0493
0494 swap_slot_free_notify is called with swap_lock and sometimes the page lock
0495 held.
0496
0497
0498 file_operations
0499 ===============
0500
0501 prototypes::
0502
0503 loff_t (*llseek) (struct file *, loff_t, int);
0504 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
0505 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
0506 ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
0507 ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
0508 int (*iopoll) (struct kiocb *kiocb, bool spin);
0509 int (*iterate) (struct file *, struct dir_context *);
0510 int (*iterate_shared) (struct file *, struct dir_context *);
0511 __poll_t (*poll) (struct file *, struct poll_table_struct *);
0512 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
0513 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
0514 int (*mmap) (struct file *, struct vm_area_struct *);
0515 int (*open) (struct inode *, struct file *);
0516 int (*flush) (struct file *);
0517 int (*release) (struct inode *, struct file *);
0518 int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
0519 int (*fasync) (int, struct file *, int);
0520 int (*lock) (struct file *, int, struct file_lock *);
0521 ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
0522 loff_t *, int);
0523 unsigned long (*get_unmapped_area)(struct file *, unsigned long,
0524 unsigned long, unsigned long, unsigned long);
0525 int (*check_flags)(int);
0526 int (*flock) (struct file *, int, struct file_lock *);
0527 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
0528 size_t, unsigned int);
0529 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
0530 size_t, unsigned int);
0531 int (*setlease)(struct file *, long, struct file_lock **, void **);
0532 long (*fallocate)(struct file *, int, loff_t, loff_t);
0533 void (*show_fdinfo)(struct seq_file *m, struct file *f);
0534 unsigned (*mmap_capabilities)(struct file *);
0535 ssize_t (*copy_file_range)(struct file *, loff_t, struct file *,
0536 loff_t, size_t, unsigned int);
0537 loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,
0538 struct file *file_out, loff_t pos_out,
0539 loff_t len, unsigned int remap_flags);
0540 int (*fadvise)(struct file *, loff_t, loff_t, int);
0541
0542 locking rules:
0543 All may block.
0544
0545 ->llseek() locking has moved from llseek to the individual llseek
0546 implementations. If your fs is not using generic_file_llseek, you
0547 need to acquire and release the appropriate locks in your ->llseek().
0548 For many filesystems, it is probably safe to acquire the inode
0549 mutex or just to use i_size_read() instead.
0550 Note: this does not protect the file->f_pos against concurrent modifications
0551 since this is something the userspace has to take care about.
0552
0553 ->iterate() is called with i_rwsem exclusive.
0554
0555 ->iterate_shared() is called with i_rwsem at least shared.
0556
0557 ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
0558 Most instances call fasync_helper(), which does that maintenance, so it's
0559 not normally something one needs to worry about. Return values > 0 will be
0560 mapped to zero in the VFS layer.
0561
0562 ->readdir() and ->ioctl() on directories must be changed. Ideally we would
0563 move ->readdir() to inode_operations and use a separate method for directory
0564 ->ioctl() or kill the latter completely. One of the problems is that for
0565 anything that resembles union-mount we won't have a struct file for all
0566 components. And there are other reasons why the current interface is a mess...
0567
0568 ->read on directories probably must go away - we should just enforce -EISDIR
0569 in sys_read() and friends.
0570
0571 ->setlease operations should call generic_setlease() before or after setting
0572 the lease within the individual filesystem to record the result of the
0573 operation
0574
0575 ->fallocate implementation must be really careful to maintain page cache
0576 consistency when punching holes or performing other operations that invalidate
0577 page cache contents. Usually the filesystem needs to call
0578 truncate_inode_pages_range() to invalidate relevant range of the page cache.
0579 However the filesystem usually also needs to update its internal (and on disk)
0580 view of file offset -> disk block mapping. Until this update is finished, the
0581 filesystem needs to block page faults and reads from reloading now-stale page
0582 cache contents from the disk. Since VFS acquires mapping->invalidate_lock in
0583 shared mode when loading pages from disk (filemap_fault(), filemap_read(),
0584 readahead paths), the fallocate implementation must take the invalidate_lock to
0585 prevent reloading.
0586
0587 ->copy_file_range and ->remap_file_range implementations need to serialize
0588 against modifications of file data while the operation is running. For
0589 blocking changes through write(2) and similar operations inode->i_rwsem can be
0590 used. To block changes to file contents via a memory mapping during the
0591 operation, the filesystem must take mapping->invalidate_lock to coordinate
0592 with ->page_mkwrite.
0593
0594 dquot_operations
0595 ================
0596
0597 prototypes::
0598
0599 int (*write_dquot) (struct dquot *);
0600 int (*acquire_dquot) (struct dquot *);
0601 int (*release_dquot) (struct dquot *);
0602 int (*mark_dirty) (struct dquot *);
0603 int (*write_info) (struct super_block *, int);
0604
0605 These operations are intended to be more or less wrapping functions that ensure
0606 a proper locking wrt the filesystem and call the generic quota operations.
0607
0608 What filesystem should expect from the generic quota functions:
0609
0610 ============== ============ =========================
0611 ops FS recursion Held locks when called
0612 ============== ============ =========================
0613 write_dquot: yes dqonoff_sem or dqptr_sem
0614 acquire_dquot: yes dqonoff_sem or dqptr_sem
0615 release_dquot: yes dqonoff_sem or dqptr_sem
0616 mark_dirty: no -
0617 write_info: yes dqonoff_sem
0618 ============== ============ =========================
0619
0620 FS recursion means calling ->quota_read() and ->quota_write() from superblock
0621 operations.
0622
0623 More details about quota locking can be found in fs/dquot.c.
0624
0625 vm_operations_struct
0626 ====================
0627
0628 prototypes::
0629
0630 void (*open)(struct vm_area_struct*);
0631 void (*close)(struct vm_area_struct*);
0632 vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
0633 vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
0634 vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
0635 int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
0636
0637 locking rules:
0638
0639 ============= ========= ===========================
0640 ops mmap_lock PageLocked(page)
0641 ============= ========= ===========================
0642 open: yes
0643 close: yes
0644 fault: yes can return with page locked
0645 map_pages: yes
0646 page_mkwrite: yes can return with page locked
0647 pfn_mkwrite: yes
0648 access: yes
0649 ============= ========= ===========================
0650
0651 ->fault() is called when a previously not present pte is about to be faulted
0652 in. The filesystem must find and return the page associated with the passed in
0653 "pgoff" in the vm_fault structure. If it is possible that the page may be
0654 truncated and/or invalidated, then the filesystem must lock invalidate_lock,
0655 then ensure the page is not already truncated (invalidate_lock will block
0656 subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
0657 locked. The VM will unlock the page.
0658
0659 ->map_pages() is called when VM asks to map easy accessible pages.
0660 Filesystem should find and map pages associated with offsets from "start_pgoff"
0661 till "end_pgoff". ->map_pages() is called with page table locked and must
0662 not block. If it's not possible to reach a page without blocking,
0663 filesystem should skip it. Filesystem should use do_set_pte() to setup
0664 page table entry. Pointer to entry associated with the page is passed in
0665 "pte" field in vm_fault structure. Pointers to entries for other offsets
0666 should be calculated relative to "pte".
0667
0668 ->page_mkwrite() is called when a previously read-only pte is about to become
0669 writeable. The filesystem again must ensure that there are no
0670 truncate/invalidate races or races with operations such as ->remap_file_range
0671 or ->copy_file_range, and then return with the page locked. Usually
0672 mapping->invalidate_lock is suitable for proper serialization. If the page has
0673 been truncated, the filesystem should not look up a new page like the ->fault()
0674 handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to
0675 retry the fault.
0676
0677 ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
0678 VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
0679 VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
0680 after this call is to make the pte read-write, unless pfn_mkwrite returns
0681 an error.
0682
0683 ->access() is called when get_user_pages() fails in
0684 access_process_vm(), typically used to debug a process through
0685 /proc/pid/mem or ptrace. This function is needed only for
0686 VM_IO | VM_PFNMAP VMAs.
0687
0688 --------------------------------------------------------------------------------
0689
0690 Dubious stuff
0691
0692 (if you break something or notice that it is broken and do not fix it yourself
0693 - at least put it here)
