Commit | Line | Data |
---|---|---|
ec23eb54 MCC |
1 | ======= |
2 | Locking | |
3 | ======= | |
4 | ||
5 | The text below describes the locking rules for VFS-related methods. | |
1da177e4 LT |
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). | |
1da177e4 | 12 | |
ec23eb54 MCC |
13 | Thing currently missing here: socket operations. Alexey? |
14 | ||
15 | dentry_operations | |
16 | ================= | |
17 | ||
18 | prototypes:: | |
19 | ||
0b728e19 | 20 | int (*d_revalidate)(struct dentry *, unsigned int); |
ecf3d1f1 | 21 | int (*d_weak_revalidate)(struct dentry *, unsigned int); |
da53be12 | 22 | int (*d_hash)(const struct dentry *, struct qstr *); |
6fa67e70 | 23 | int (*d_compare)(const struct dentry *, |
621e155a | 24 | unsigned int, const char *, const struct qstr *); |
1da177e4 | 25 | int (*d_delete)(struct dentry *); |
285b102d | 26 | int (*d_init)(struct dentry *); |
1da177e4 LT |
27 | void (*d_release)(struct dentry *); |
28 | void (*d_iput)(struct dentry *, struct inode *); | |
c23fbb6b | 29 | char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); |
9875cf80 | 30 | struct vfsmount *(*d_automount)(struct path *path); |
fb5f51c7 | 31 | int (*d_manage)(const struct path *, bool); |
fb16043b | 32 | struct dentry *(*d_real)(struct dentry *, const struct inode *); |
1da177e4 LT |
33 | |
34 | locking rules: | |
ec23eb54 MCC |
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 | ||
ebfc3b49 | 59 | int (*create) (struct inode *,struct dentry *,umode_t, bool); |
00cd8dd3 | 60 | struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); |
1da177e4 LT |
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 *); | |
18bb1db3 | 64 | int (*mkdir) (struct inode *,struct dentry *,umode_t); |
1da177e4 | 65 | int (*rmdir) (struct inode *,struct dentry *); |
1a67aafb | 66 | int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); |
1da177e4 | 67 | int (*rename) (struct inode *, struct dentry *, |
520c8b16 | 68 | struct inode *, struct dentry *, unsigned int); |
1da177e4 | 69 | int (*readlink) (struct dentry *, char __user *,int); |
1a6a3165 | 70 | const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); |
1da177e4 | 71 | void (*truncate) (struct inode *); |
b74c79e9 | 72 | int (*permission) (struct inode *, int, unsigned int); |
4e34e719 | 73 | int (*get_acl)(struct inode *, int); |
1da177e4 | 74 | int (*setattr) (struct dentry *, struct iattr *); |
75dd7e4b | 75 | int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); |
1da177e4 | 76 | ssize_t (*listxattr) (struct dentry *, char *, size_t); |
b83be6f2 | 77 | int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); |
c3b2da31 | 78 | void (*update_time)(struct inode *, struct timespec *, int); |
d9585277 | 79 | int (*atomic_open)(struct inode *, struct dentry *, |
30d90494 | 80 | struct file *, unsigned open_flag, |
6c9b1de1 | 81 | umode_t create_mode); |
48bde8d3 | 82 | int (*tmpfile) (struct inode *, struct dentry *, umode_t); |
1da177e4 LT |
83 | |
84 | locking rules: | |
b83be6f2 | 85 | all may block |
ec23eb54 MCC |
86 | |
87 | ============ ============================================= | |
88 | ops i_rwsem(inode) | |
89 | ============ ============================================= | |
965de0ec SA |
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) | |
1da177e4 | 99 | readlink: no |
6b255391 | 100 | get_link: no |
965de0ec | 101 | setattr: exclusive |
b74c79e9 | 102 | permission: no (may not block if called in rcu-walk mode) |
4e34e719 | 103 | get_acl: no |
1da177e4 | 104 | getattr: no |
1da177e4 | 105 | listxattr: no |
b83be6f2 | 106 | fiemap: no |
c3b2da31 | 107 | update_time: no |
ff467342 | 108 | atomic_open: shared (exclusive if O_CREAT is set in open flags) |
48bde8d3 | 109 | tmpfile: no |
ec23eb54 | 110 | ============ ============================================= |
c3b2da31 | 111 | |
6c6ef9f2 | 112 | |
965de0ec SA |
113 | Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem |
114 | exclusive on victim. | |
2773bf00 | 115 | cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. |
1da177e4 | 116 | |
ec23eb54 | 117 | See Documentation/filesystems/directory-locking.rst for more detailed discussion |
1da177e4 LT |
118 | of the locking scheme for directory operations. |
119 | ||
ec23eb54 MCC |
120 | xattr_handler operations |
121 | ======================== | |
122 | ||
123 | prototypes:: | |
124 | ||
6c6ef9f2 AG |
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); | |
e65ce2a5 CB |
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); | |
6c6ef9f2 AG |
133 | |
134 | locking rules: | |
135 | all may block | |
ec23eb54 MCC |
136 | |
137 | ===== ============== | |
138 | ops i_rwsem(inode) | |
139 | ===== ============== | |
6c6ef9f2 AG |
140 | list: no |
141 | get: no | |
965de0ec | 142 | set: exclusive |
ec23eb54 MCC |
143 | ===== ============== |
144 | ||
145 | super_operations | |
146 | ================ | |
147 | ||
148 | prototypes:: | |
6c6ef9f2 | 149 | |
1da177e4 | 150 | struct inode *(*alloc_inode)(struct super_block *sb); |
fdb0da89 | 151 | void (*free_inode)(struct inode *); |
1da177e4 | 152 | void (*destroy_inode)(struct inode *); |
aa385729 | 153 | void (*dirty_inode) (struct inode *, int flags); |
b83be6f2 | 154 | int (*write_inode) (struct inode *, struct writeback_control *wbc); |
336fb3b9 AV |
155 | int (*drop_inode) (struct inode *); |
156 | void (*evict_inode) (struct inode *); | |
1da177e4 | 157 | void (*put_super) (struct super_block *); |
1da177e4 | 158 | int (*sync_fs)(struct super_block *sb, int wait); |
c4be0c1d TS |
159 | int (*freeze_fs) (struct super_block *); |
160 | int (*unfreeze_fs) (struct super_block *); | |
726c3342 | 161 | int (*statfs) (struct dentry *, struct kstatfs *); |
1da177e4 | 162 | int (*remount_fs) (struct super_block *, int *, char *); |
1da177e4 | 163 | void (*umount_begin) (struct super_block *); |
34c80b1d | 164 | int (*show_options)(struct seq_file *, struct dentry *); |
1da177e4 LT |
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); | |
b83be6f2 | 167 | int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); |
1da177e4 LT |
168 | |
169 | locking rules: | |
336fb3b9 | 170 | All may block [not true, see below] |
ec23eb54 MCC |
171 | |
172 | ====================== ============ ======================== | |
173 | ops s_umount note | |
174 | ====================== ============ ======================== | |
7e325d3a | 175 | alloc_inode: |
fdb0da89 | 176 | free_inode: called from RCU callback |
7e325d3a | 177 | destroy_inode: |
aa385729 | 178 | dirty_inode: |
7e325d3a | 179 | write_inode: |
f283c86a | 180 | drop_inode: !!!inode->i_lock!!! |
336fb3b9 | 181 | evict_inode: |
7e325d3a | 182 | put_super: write |
7e325d3a | 183 | sync_fs: read |
06fd516c VA |
184 | freeze_fs: write |
185 | unfreeze_fs: write | |
336fb3b9 AV |
186 | statfs: maybe(read) (see below) |
187 | remount_fs: write | |
7e325d3a CH |
188 | umount_begin: no |
189 | show_options: no (namespace_sem) | |
190 | quota_read: no (see below) | |
191 | quota_write: no (see below) | |
b83be6f2 | 192 | bdev_try_to_free_page: no (see below) |
ec23eb54 | 193 | ====================== ============ ======================== |
1da177e4 | 194 | |
336fb3b9 AV |
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. | |
ec23eb54 | 201 | |
1da177e4 LT |
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. | |
ec23eb54 | 207 | |
b83be6f2 CH |
208 | ->bdev_try_to_free_page is called from the ->releasepage handler of |
209 | the block device inode. See there for more details. | |
1da177e4 | 210 | |
ec23eb54 MCC |
211 | file_system_type |
212 | ================ | |
213 | ||
214 | prototypes:: | |
215 | ||
b83be6f2 CH |
216 | struct dentry *(*mount) (struct file_system_type *, int, |
217 | const char *, void *); | |
1da177e4 | 218 | void (*kill_sb) (struct super_block *); |
ec23eb54 | 219 | |
1da177e4 | 220 | locking rules: |
ec23eb54 MCC |
221 | |
222 | ======= ========= | |
223 | ops may block | |
224 | ======= ========= | |
b83be6f2 CH |
225 | mount yes |
226 | kill_sb yes | |
ec23eb54 | 227 | ======= ========= |
1da177e4 | 228 | |
1a102ff9 AV |
229 | ->mount() returns ERR_PTR or the root dentry; its superblock should be locked |
230 | on return. | |
ec23eb54 | 231 | |
1da177e4 LT |
232 | ->kill_sb() takes a write-locked superblock, does all shutdown work on it, |
233 | unlocks and drops the reference. | |
234 | ||
ec23eb54 MCC |
235 | address_space_operations |
236 | ======================== | |
237 | prototypes:: | |
238 | ||
1da177e4 LT |
239 | int (*writepage)(struct page *page, struct writeback_control *wbc); |
240 | int (*readpage)(struct file *, struct page *); | |
1da177e4 LT |
241 | int (*writepages)(struct address_space *, struct writeback_control *); |
242 | int (*set_page_dirty)(struct page *page); | |
8151b4c8 | 243 | void (*readahead)(struct readahead_control *); |
1da177e4 LT |
244 | int (*readpages)(struct file *filp, struct address_space *mapping, |
245 | struct list_head *pages, unsigned nr_pages); | |
4e02ed4b NP |
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); | |
1da177e4 | 252 | sector_t (*bmap)(struct address_space *, sector_t); |
d47992f8 | 253 | void (*invalidatepage) (struct page *, unsigned int, unsigned int); |
1da177e4 | 254 | int (*releasepage) (struct page *, int); |
6072d13c | 255 | void (*freepage)(struct page *); |
c8b8e32d | 256 | int (*direct_IO)(struct kiocb *, struct iov_iter *iter); |
bda807d4 | 257 | bool (*isolate_page) (struct page *, isolate_mode_t); |
b83be6f2 | 258 | int (*migratepage)(struct address_space *, struct page *, struct page *); |
bda807d4 | 259 | void (*putback_page) (struct page *); |
b83be6f2 | 260 | int (*launder_page)(struct page *); |
c186afb4 | 261 | int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); |
b83be6f2 | 262 | int (*error_remove_page)(struct address_space *, struct page *); |
62c230bc MG |
263 | int (*swap_activate)(struct file *); |
264 | int (*swap_deactivate)(struct file *); | |
1da177e4 LT |
265 | |
266 | locking rules: | |
6072d13c | 267 | All except set_page_dirty and freepage may block |
1da177e4 | 268 | |
ec23eb54 MCC |
269 | ====================== ======================== ========= |
270 | ops PageLocked(page) i_rwsem | |
271 | ====================== ======================== ========= | |
b83be6f2 CH |
272 | writepage: yes, unlocks (see below) |
273 | readpage: yes, unlocks | |
b83be6f2 CH |
274 | writepages: |
275 | set_page_dirty no | |
8151b4c8 MWO |
276 | readahead: yes, unlocks |
277 | readpages: no | |
ec23eb54 MCC |
278 | write_begin: locks the page exclusive |
279 | write_end: yes, unlocks exclusive | |
b83be6f2 CH |
280 | bmap: |
281 | invalidatepage: yes | |
282 | releasepage: yes | |
283 | freepage: yes | |
284 | direct_IO: | |
bda807d4 | 285 | isolate_page: yes |
b83be6f2 | 286 | migratepage: yes (both) |
bda807d4 | 287 | putback_page: yes |
b83be6f2 CH |
288 | launder_page: yes |
289 | is_partially_uptodate: yes | |
290 | error_remove_page: yes | |
62c230bc MG |
291 | swap_activate: no |
292 | swap_deactivate: no | |
ec23eb54 | 293 | ====================== ======================== ========= |
1da177e4 | 294 | |
ec23eb54 | 295 | ->write_begin(), ->write_end() and ->readpage() may be called from |
f4e6d844 | 296 | the request handler (/dev/loop). |
1da177e4 | 297 | |
ec23eb54 | 298 | ->readpage() unlocks the page, either synchronously or via I/O |
1da177e4 LT |
299 | completion. |
300 | ||
8151b4c8 MWO |
301 | ->readahead() unlocks the pages that I/O is attempted on like ->readpage(). |
302 | ||
ec23eb54 | 303 | ->readpages() populates the pagecache with the passed pages and starts |
1da177e4 LT |
304 | I/O against them. They come unlocked upon I/O completion. |
305 | ||
ec23eb54 | 306 | ->writepage() is used for two purposes: for "memory cleansing" and for |
1da177e4 LT |
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 | ||
3a4fa0a2 | 325 | If the filesystem is called for sync then it must wait on any |
1da177e4 LT |
326 | in-progress I/O and then start new I/O. |
327 | ||
2054606a ND |
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. | |
1da177e4 LT |
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 | ||
ec23eb54 | 354 | ->writepages() is used for periodic writeback and for syscall-initiated |
1da177e4 | 355 | sync operations. The address_space should start I/O against at least |
ec23eb54 MCC |
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. | |
1da177e4 LT |
360 | |
361 | writepages should _only_ write pages which are present on | |
362 | mapping->io_pages. | |
363 | ||
ec23eb54 | 364 | ->set_page_dirty() is called from various places in the kernel |
1da177e4 LT |
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 | ||
ec23eb54 | 369 | ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some |
b83be6f2 CH |
370 | filesystems and by the swapper. The latter will eventually go away. Please, |
371 | keep it that way and don't breed new callers. | |
1da177e4 | 372 | |
ec23eb54 | 373 | ->invalidatepage() is called when the filesystem must attempt to drop |
d47992f8 LC |
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 | |
1da177e4 LT |
376 | block_invalidatepage() instead. |
377 | ||
ec23eb54 | 378 | ->releasepage() is called when the kernel is about to try to drop the |
1da177e4 LT |
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 | ||
ec23eb54 | 383 | ->freepage() is called when the kernel is done dropping the page |
6072d13c LT |
384 | from the page cache. |
385 | ||
ec23eb54 | 386 | ->launder_page() may be called prior to releasing a page if |
e3db7691 TM |
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 | ||
ec23eb54 | 392 | ->swap_activate will be called with a non-zero argument on |
62c230bc MG |
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 | ||
ec23eb54 | 398 | ->swap_deactivate() will be called in the sys_swapoff() |
62c230bc MG |
399 | path after ->swap_activate() returned success. |
400 | ||
ec23eb54 MCC |
401 | file_lock_operations |
402 | ==================== | |
403 | ||
404 | prototypes:: | |
405 | ||
1da177e4 LT |
406 | void (*fl_copy_lock)(struct file_lock *, struct file_lock *); |
407 | void (*fl_release_private)(struct file_lock *); | |
408 | ||
409 | ||
410 | locking rules: | |
ec23eb54 MCC |
411 | |
412 | =================== ============= ========= | |
413 | ops inode->i_lock may block | |
414 | =================== ============= ========= | |
b83be6f2 | 415 | fl_copy_lock: yes no |
ec23eb54 MCC |
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. | |
2ece173e | 423 | |
ec23eb54 MCC |
424 | lock_manager_operations |
425 | ======================= | |
426 | ||
427 | prototypes:: | |
1da177e4 | 428 | |
8fb47a4f BF |
429 | void (*lm_notify)(struct file_lock *); /* unblock callback */ |
430 | int (*lm_grant)(struct file_lock *, struct file_lock *, int); | |
8fb47a4f BF |
431 | void (*lm_break)(struct file_lock *); /* break_lease callback */ |
432 | int (*lm_change)(struct file_lock **, int); | |
28df3d15 | 433 | bool (*lm_breaker_owns_lease)(struct file_lock *); |
1da177e4 LT |
434 | |
435 | locking rules: | |
1c8c601a | 436 | |
6cbef2ad | 437 | ====================== ============= ================= ========= |
ec23eb54 | 438 | ops inode->i_lock blocked_lock_lock may block |
6cbef2ad | 439 | ====================== ============= ================= ========= |
7b2296af JL |
440 | lm_notify: yes yes no |
441 | lm_grant: no no no | |
442 | lm_break: yes no no | |
443 | lm_change yes no no | |
28df3d15 | 444 | lm_breaker_owns_lease: no no no |
6cbef2ad | 445 | ====================== ============= ================= ========= |
ec23eb54 MCC |
446 | |
447 | buffer_head | |
448 | =========== | |
449 | ||
450 | prototypes:: | |
1c8c601a | 451 | |
1da177e4 LT |
452 | void (*b_end_io)(struct buffer_head *bh, int uptodate); |
453 | ||
454 | locking rules: | |
ec23eb54 MCC |
455 | |
456 | called from interrupts. In other words, extreme care is needed here. | |
1da177e4 LT |
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 | ||
ec23eb54 MCC |
461 | block_device_operations |
462 | ======================= | |
463 | prototypes:: | |
464 | ||
e1455d1b CH |
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); | |
7a9eb206 | 469 | int (*direct_access) (struct block_device *, sector_t, void **, |
e2e05394 | 470 | unsigned long *); |
e1455d1b | 471 | void (*unlock_native_capacity) (struct gendisk *); |
1da177e4 | 472 | int (*revalidate_disk) (struct gendisk *); |
e1455d1b CH |
473 | int (*getgeo)(struct block_device *, struct hd_geometry *); |
474 | void (*swap_slot_free_notify) (struct block_device *, unsigned long); | |
1da177e4 LT |
475 | |
476 | locking rules: | |
ec23eb54 MCC |
477 | |
478 | ======================= =================== | |
479 | ops bd_mutex | |
480 | ======================= =================== | |
b83be6f2 CH |
481 | open: yes |
482 | release: yes | |
483 | ioctl: no | |
484 | compat_ioctl: no | |
485 | direct_access: no | |
b83be6f2 CH |
486 | unlock_native_capacity: no |
487 | revalidate_disk: no | |
488 | getgeo: no | |
489 | swap_slot_free_notify: no (see below) | |
ec23eb54 | 490 | ======================= =================== |
e1455d1b | 491 | |
e1455d1b CH |
492 | swap_slot_free_notify is called with swap_lock and sometimes the page lock |
493 | held. | |
1da177e4 | 494 | |
1da177e4 | 495 | |
ec23eb54 MCC |
496 | file_operations |
497 | =============== | |
498 | ||
499 | prototypes:: | |
500 | ||
1da177e4 LT |
501 | loff_t (*llseek) (struct file *, loff_t, int); |
502 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); | |
1da177e4 | 503 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); |
293bc982 AV |
504 | ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); |
505 | ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); | |
2233f31a | 506 | int (*iterate) (struct file *, struct dir_context *); |
965de0ec | 507 | int (*iterate_shared) (struct file *, struct dir_context *); |
6e8b704d | 508 | __poll_t (*poll) (struct file *, struct poll_table_struct *); |
1da177e4 LT |
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 *); | |
02c24a82 | 515 | int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); |
1da177e4 LT |
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); | |
b83be6f2 CH |
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); | |
e6f5c789 | 534 | int (*setlease)(struct file *, long, struct file_lock **, void **); |
2fe17c10 | 535 | long (*fallocate)(struct file *, int, loff_t, loff_t); |
1da177e4 LT |
536 | |
537 | locking rules: | |
a11e1d43 | 538 | All may block. |
b83be6f2 | 539 | |
1da177e4 LT |
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 | |
866707fc JB |
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. | |
1da177e4 | 547 | |
965de0ec SA |
548 | ->iterate() is called with i_rwsem exclusive. |
549 | ||
550 | ->iterate_shared() is called with i_rwsem at least shared. | |
551 | ||
b83be6f2 CH |
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. | |
1da177e4 LT |
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 | ||
1da177e4 LT |
563 | ->read on directories probably must go away - we should just enforce -EISDIR |
564 | in sys_read() and friends. | |
565 | ||
f82b4b67 JL |
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 | ||
ec23eb54 MCC |
570 | dquot_operations |
571 | ================ | |
572 | ||
573 | prototypes:: | |
574 | ||
1da177e4 LT |
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 | ||
ec23eb54 MCC |
586 | ============== ============ ========================= |
587 | ops FS recursion Held locks when called | |
588 | ============== ============ ========================= | |
1da177e4 LT |
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 | |
ec23eb54 | 594 | ============== ============ ========================= |
1da177e4 LT |
595 | |
596 | FS recursion means calling ->quota_read() and ->quota_write() from superblock | |
597 | operations. | |
598 | ||
1da177e4 LT |
599 | More details about quota locking can be found in fs/dquot.c. |
600 | ||
ec23eb54 MCC |
601 | vm_operations_struct |
602 | ==================== | |
603 | ||
604 | prototypes:: | |
605 | ||
1da177e4 LT |
606 | void (*open)(struct vm_area_struct*); |
607 | void (*close)(struct vm_area_struct*); | |
fe3136f4 SJ |
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 *); | |
28b2ee20 | 611 | int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); |
1da177e4 LT |
612 | |
613 | locking rules: | |
ec23eb54 | 614 | |
6cbef2ad | 615 | ============= ========= =========================== |
c1e8d7c6 | 616 | ops mmap_lock PageLocked(page) |
6cbef2ad | 617 | ============= ========= =========================== |
b83be6f2 CH |
618 | open: yes |
619 | close: yes | |
620 | fault: yes can return with page locked | |
8c6e50b0 | 621 | map_pages: yes |
b83be6f2 | 622 | page_mkwrite: yes can return with page locked |
dd906184 | 623 | pfn_mkwrite: yes |
b83be6f2 | 624 | access: yes |
6cbef2ad | 625 | ============= ========= =========================== |
ed2f2f9b | 626 | |
ec23eb54 | 627 | ->fault() is called when a previously not present pte is about |
b827e496 NP |
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 | ||
ec23eb54 | 635 | ->map_pages() is called when VM asks to map easy accessible pages. |
bae473a4 KS |
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 | |
8c6e50b0 KS |
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 | |
bae473a4 | 640 | page table entry. Pointer to entry associated with the page is passed in |
82b0f8c3 | 641 | "pte" field in vm_fault structure. Pointers to entries for other offsets |
bae473a4 | 642 | should be calculated relative to "pte". |
8c6e50b0 | 643 | |
ec23eb54 | 644 | ->page_mkwrite() is called when a previously read-only pte is |
b827e496 NP |
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. | |
1da177e4 | 650 | |
ec23eb54 | 651 | ->pfn_mkwrite() is the same as page_mkwrite but when the pte is |
dd906184 BH |
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 | ||
ec23eb54 | 657 | ->access() is called when get_user_pages() fails in |
507da6a1 | 658 | access_process_vm(), typically used to debug a process through |
28b2ee20 RR |
659 | /proc/pid/mem or ptrace. This function is needed only for |
660 | VM_IO | VM_PFNMAP VMAs. | |
661 | ||
ec23eb54 MCC |
662 | -------------------------------------------------------------------------------- |
663 | ||
1da177e4 LT |
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) |