locking.rst 25 KB

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