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