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