Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 1 | ======= |
| 2 | Locking |
| 3 | ======= |
| 4 | |
| 5 | The text below describes the locking rules for VFS-related methods. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 12 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 13 | Thing currently missing here: socket operations. Alexey? |
| 14 | |
| 15 | dentry_operations |
| 16 | ================= |
| 17 | |
| 18 | prototypes:: |
| 19 | |
Al Viro | 0b728e1 | 2012-06-10 16:03:43 -0400 | [diff] [blame] | 20 | int (*d_revalidate)(struct dentry *, unsigned int); |
Jeff Layton | ecf3d1f | 2013-02-20 11:19:05 -0500 | [diff] [blame] | 21 | int (*d_weak_revalidate)(struct dentry *, unsigned int); |
Linus Torvalds | da53be1 | 2013-05-21 15:22:44 -0700 | [diff] [blame] | 22 | int (*d_hash)(const struct dentry *, struct qstr *); |
Al Viro | 6fa67e7 | 2016-07-31 16:37:25 -0400 | [diff] [blame] | 23 | int (*d_compare)(const struct dentry *, |
Nick Piggin | 621e155 | 2011-01-07 17:49:27 +1100 | [diff] [blame] | 24 | unsigned int, const char *, const struct qstr *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 25 | int (*d_delete)(struct dentry *); |
Miklos Szeredi | 285b102 | 2016-06-28 11:47:32 +0200 | [diff] [blame] | 26 | int (*d_init)(struct dentry *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 27 | void (*d_release)(struct dentry *); |
| 28 | void (*d_iput)(struct dentry *, struct inode *); |
Eric Dumazet | c23fbb6 | 2007-05-08 00:26:18 -0700 | [diff] [blame] | 29 | char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); |
David Howells | 9875cf8 | 2011-01-14 18:45:21 +0000 | [diff] [blame] | 30 | struct vfsmount *(*d_automount)(struct path *path); |
Ian Kent | fb5f51c | 2016-11-24 08:03:41 +1100 | [diff] [blame] | 31 | int (*d_manage)(const struct path *, bool); |
Miklos Szeredi | fb16043 | 2018-07-18 15:44:44 +0200 | [diff] [blame] | 32 | struct dentry *(*d_real)(struct dentry *, const struct inode *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 33 | |
| 34 | locking rules: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 35 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 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 | |
Christian Brauner | 6c960e6 | 2023-01-13 12:49:13 +0100 | [diff] [blame] | 59 | int (*create) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t, bool); |
Al Viro | 00cd8dd | 2012-06-10 17:13:09 -0400 | [diff] [blame] | 60 | struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 61 | int (*link) (struct dentry *,struct inode *,struct dentry *); |
| 62 | int (*unlink) (struct inode *,struct dentry *); |
Christian Brauner | 7a77db9 | 2023-01-13 12:49:14 +0100 | [diff] [blame] | 63 | int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *); |
Christian Brauner | c54bd91 | 2023-01-13 12:49:15 +0100 | [diff] [blame] | 64 | int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 65 | int (*rmdir) (struct inode *,struct dentry *); |
Christian Brauner | 5ebb29b | 2023-01-13 12:49:16 +0100 | [diff] [blame] | 66 | int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t); |
Christian Brauner | e18275a | 2023-01-13 12:49:17 +0100 | [diff] [blame] | 67 | int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *, |
Miklos Szeredi | 520c8b1 | 2014-04-01 17:08:42 +0200 | [diff] [blame] | 68 | struct inode *, struct dentry *, unsigned int); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 69 | int (*readlink) (struct dentry *, char __user *,int); |
Eric Biggers | 1a6a316 | 2019-04-11 16:16:29 -0700 | [diff] [blame] | 70 | const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 71 | void (*truncate) (struct inode *); |
Christian Brauner | 4609e1f | 2023-01-13 12:49:22 +0100 | [diff] [blame] | 72 | int (*permission) (struct mnt_idmap *, struct inode *, int, unsigned int); |
Christian Brauner | cac2f8b | 2022-09-22 17:17:00 +0200 | [diff] [blame] | 73 | struct posix_acl * (*get_inode_acl)(struct inode *, int, bool); |
Christian Brauner | c1632a0 | 2023-01-13 12:49:11 +0100 | [diff] [blame] | 74 | int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *); |
Christian Brauner | b74d24f | 2023-01-13 12:49:12 +0100 | [diff] [blame] | 75 | int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 76 | ssize_t (*listxattr) (struct dentry *, char *, size_t); |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 77 | int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); |
Josef Bacik | c3b2da3 | 2012-03-26 09:59:21 -0400 | [diff] [blame] | 78 | void (*update_time)(struct inode *, struct timespec *, int); |
Al Viro | d958527 | 2012-06-22 12:39:14 +0400 | [diff] [blame] | 79 | int (*atomic_open)(struct inode *, struct dentry *, |
Al Viro | 30d90494 | 2012-06-22 12:40:19 +0400 | [diff] [blame] | 80 | struct file *, unsigned open_flag, |
Al Viro | 6c9b1de | 2018-07-09 19:20:08 -0400 | [diff] [blame] | 81 | umode_t create_mode); |
Christian Brauner | 011e2b7 | 2023-01-13 12:49:18 +0100 | [diff] [blame] | 82 | int (*tmpfile) (struct mnt_idmap *, struct inode *, |
Miklos Szeredi | 863f144 | 2022-09-24 07:00:00 +0200 | [diff] [blame] | 83 | struct file *, umode_t); |
Christian Brauner | 8782a9a | 2023-01-13 12:49:21 +0100 | [diff] [blame] | 84 | int (*fileattr_set)(struct mnt_idmap *idmap, |
Miklos Szeredi | 4c5b479 | 2021-04-07 14:36:42 +0200 | [diff] [blame] | 85 | struct dentry *dentry, struct fileattr *fa); |
| 86 | int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); |
Christian Brauner | 7743532 | 2023-01-13 12:49:19 +0100 | [diff] [blame] | 87 | struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); |
Chuck Lever | 6faddda69 | 2023-06-30 13:48:49 -0400 | [diff] [blame] | 88 | struct offset_ctx *(*get_offset_ctx)(struct inode *inode); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 89 | |
| 90 | locking rules: |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 91 | all may block |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 92 | |
Chuck Lever | 6faddda69 | 2023-06-30 13:48:49 -0400 | [diff] [blame] | 93 | ============== ================================================== |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 94 | ops i_rwsem(inode) |
Chuck Lever | 6faddda69 | 2023-06-30 13:48:49 -0400 | [diff] [blame] | 95 | ============== ================================================== |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 96 | lookup: shared |
| 97 | create: exclusive |
| 98 | link: exclusive (both) |
| 99 | mknod: exclusive |
| 100 | symlink: exclusive |
| 101 | mkdir: exclusive |
| 102 | unlink: exclusive (both) |
| 103 | rmdir: exclusive (both)(see below) |
| 104 | rename: exclusive (all) (see below) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 105 | readlink: no |
Al Viro | 6b25539 | 2015-11-17 10:20:54 -0500 | [diff] [blame] | 106 | get_link: no |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 107 | setattr: exclusive |
Nick Piggin | b74c79e | 2011-01-07 17:49:58 +1100 | [diff] [blame] | 108 | permission: no (may not block if called in rcu-walk mode) |
Christian Brauner | cac2f8b | 2022-09-22 17:17:00 +0200 | [diff] [blame] | 109 | get_inode_acl: no |
Christian Brauner | 7420332 | 2022-09-22 17:17:01 +0200 | [diff] [blame] | 110 | get_acl: no |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 111 | getattr: no |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 112 | listxattr: no |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 113 | fiemap: no |
Josef Bacik | c3b2da3 | 2012-03-26 09:59:21 -0400 | [diff] [blame] | 114 | update_time: no |
Jeff Layton | ff46734 | 2019-10-30 06:46:54 -0400 | [diff] [blame] | 115 | atomic_open: shared (exclusive if O_CREAT is set in open flags) |
Al Viro | 48bde8d | 2013-07-03 16:19:23 +0400 | [diff] [blame] | 116 | tmpfile: no |
Miklos Szeredi | 4c5b479 | 2021-04-07 14:36:42 +0200 | [diff] [blame] | 117 | fileattr_get: no or exclusive |
| 118 | fileattr_set: exclusive |
Chuck Lever | 6faddda69 | 2023-06-30 13:48:49 -0400 | [diff] [blame] | 119 | get_offset_ctx no |
| 120 | ============== ================================================== |
Josef Bacik | c3b2da3 | 2012-03-26 09:59:21 -0400 | [diff] [blame] | 121 | |
Andreas Gruenbacher | 6c6ef9f | 2016-09-29 17:48:44 +0200 | [diff] [blame] | 122 | |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 123 | Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem |
| 124 | exclusive on victim. |
Miklos Szeredi | 2773bf0 | 2016-09-27 11:03:58 +0200 | [diff] [blame] | 125 | cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 126 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 127 | See Documentation/filesystems/directory-locking.rst for more detailed discussion |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 128 | of the locking scheme for directory operations. |
| 129 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 130 | xattr_handler operations |
| 131 | ======================== |
| 132 | |
| 133 | prototypes:: |
| 134 | |
Andreas Gruenbacher | 6c6ef9f | 2016-09-29 17:48:44 +0200 | [diff] [blame] | 135 | bool (*list)(struct dentry *dentry); |
| 136 | int (*get)(const struct xattr_handler *handler, struct dentry *dentry, |
| 137 | struct inode *inode, const char *name, void *buffer, |
| 138 | size_t size); |
Christian Brauner | e65ce2a | 2021-01-21 14:19:27 +0100 | [diff] [blame] | 139 | int (*set)(const struct xattr_handler *handler, |
Christian Brauner | 39f60c1 | 2023-01-13 12:49:23 +0100 | [diff] [blame] | 140 | struct mnt_idmap *idmap, |
Christian Brauner | e65ce2a | 2021-01-21 14:19:27 +0100 | [diff] [blame] | 141 | struct dentry *dentry, struct inode *inode, const char *name, |
| 142 | const void *buffer, size_t size, int flags); |
Andreas Gruenbacher | 6c6ef9f | 2016-09-29 17:48:44 +0200 | [diff] [blame] | 143 | |
| 144 | locking rules: |
| 145 | all may block |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 146 | |
| 147 | ===== ============== |
| 148 | ops i_rwsem(inode) |
| 149 | ===== ============== |
Andreas Gruenbacher | 6c6ef9f | 2016-09-29 17:48:44 +0200 | [diff] [blame] | 150 | list: no |
| 151 | get: no |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 152 | set: exclusive |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 153 | ===== ============== |
Andreas Gruenbacher | 6c6ef9f | 2016-09-29 17:48:44 +0200 | [diff] [blame] | 154 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 155 | super_operations |
| 156 | ================ |
| 157 | |
| 158 | prototypes:: |
| 159 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 160 | struct inode *(*alloc_inode)(struct super_block *sb); |
Al Viro | fdb0da8 | 2019-04-10 14:43:44 -0400 | [diff] [blame] | 161 | void (*free_inode)(struct inode *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 162 | void (*destroy_inode)(struct inode *); |
Christoph Hellwig | aa38572 | 2011-05-27 06:53:02 -0400 | [diff] [blame] | 163 | void (*dirty_inode) (struct inode *, int flags); |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 164 | int (*write_inode) (struct inode *, struct writeback_control *wbc); |
Al Viro | 336fb3b | 2010-06-08 00:37:12 -0400 | [diff] [blame] | 165 | int (*drop_inode) (struct inode *); |
| 166 | void (*evict_inode) (struct inode *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 167 | void (*put_super) (struct super_block *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 168 | int (*sync_fs)(struct super_block *sb, int wait); |
Takashi Sato | c4be0c1 | 2009-01-09 16:40:58 -0800 | [diff] [blame] | 169 | int (*freeze_fs) (struct super_block *); |
| 170 | int (*unfreeze_fs) (struct super_block *); |
David Howells | 726c334 | 2006-06-23 02:02:58 -0700 | [diff] [blame] | 171 | int (*statfs) (struct dentry *, struct kstatfs *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 172 | int (*remount_fs) (struct super_block *, int *, char *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 173 | void (*umount_begin) (struct super_block *); |
Al Viro | 34c80b1 | 2011-12-08 21:32:45 -0500 | [diff] [blame] | 174 | int (*show_options)(struct seq_file *, struct dentry *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 175 | ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); |
| 176 | ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); |
| 177 | |
| 178 | locking rules: |
Al Viro | 336fb3b | 2010-06-08 00:37:12 -0400 | [diff] [blame] | 179 | All may block [not true, see below] |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 180 | |
| 181 | ====================== ============ ======================== |
| 182 | ops s_umount note |
| 183 | ====================== ============ ======================== |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 184 | alloc_inode: |
Al Viro | fdb0da8 | 2019-04-10 14:43:44 -0400 | [diff] [blame] | 185 | free_inode: called from RCU callback |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 186 | destroy_inode: |
Christoph Hellwig | aa38572 | 2011-05-27 06:53:02 -0400 | [diff] [blame] | 187 | dirty_inode: |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 188 | write_inode: |
Dave Chinner | f283c86 | 2011-03-22 22:23:39 +1100 | [diff] [blame] | 189 | drop_inode: !!!inode->i_lock!!! |
Al Viro | 336fb3b | 2010-06-08 00:37:12 -0400 | [diff] [blame] | 190 | evict_inode: |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 191 | put_super: write |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 192 | sync_fs: read |
Valerie Aurora | 06fd516 | 2012-06-12 16:20:48 +0200 | [diff] [blame] | 193 | freeze_fs: write |
| 194 | unfreeze_fs: write |
Al Viro | 336fb3b | 2010-06-08 00:37:12 -0400 | [diff] [blame] | 195 | statfs: maybe(read) (see below) |
| 196 | remount_fs: write |
Christoph Hellwig | 7e325d3 | 2009-06-19 20:22:37 +0200 | [diff] [blame] | 197 | umount_begin: no |
| 198 | show_options: no (namespace_sem) |
| 199 | quota_read: no (see below) |
| 200 | quota_write: no (see below) |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 201 | ====================== ============ ======================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 202 | |
Al Viro | 336fb3b | 2010-06-08 00:37:12 -0400 | [diff] [blame] | 203 | ->statfs() has s_umount (shared) when called by ustat(2) (native or |
| 204 | compat), but that's an accident of bad API; s_umount is used to pin |
| 205 | the superblock down when we only have dev_t given us by userland to |
| 206 | identify the superblock. Everything else (statfs(), fstatfs(), etc.) |
| 207 | doesn't hold it when calling ->statfs() - superblock is pinned down |
| 208 | by resolving the pathname passed to syscall. |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 209 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 210 | ->quota_read() and ->quota_write() functions are both guaranteed to |
| 211 | be the only ones operating on the quota file by the quota code (via |
| 212 | dqio_sem) (unless an admin really wants to screw up something and |
| 213 | writes to quota files with quotas on). For other details about locking |
| 214 | see also dquot_operations section. |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 215 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 216 | file_system_type |
| 217 | ================ |
| 218 | |
| 219 | prototypes:: |
| 220 | |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 221 | struct dentry *(*mount) (struct file_system_type *, int, |
| 222 | const char *, void *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 223 | void (*kill_sb) (struct super_block *); |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 224 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 225 | locking rules: |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 226 | |
| 227 | ======= ========= |
| 228 | ops may block |
| 229 | ======= ========= |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 230 | mount yes |
| 231 | kill_sb yes |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 232 | ======= ========= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 233 | |
Al Viro | 1a102ff | 2011-03-16 09:07:58 -0400 | [diff] [blame] | 234 | ->mount() returns ERR_PTR or the root dentry; its superblock should be locked |
| 235 | on return. |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 236 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 237 | ->kill_sb() takes a write-locked superblock, does all shutdown work on it, |
| 238 | unlocks and drops the reference. |
| 239 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 240 | address_space_operations |
| 241 | ======================== |
| 242 | prototypes:: |
| 243 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 244 | int (*writepage)(struct page *page, struct writeback_control *wbc); |
Matthew Wilcox (Oracle) | 08830c8 | 2022-04-29 08:45:43 -0400 | [diff] [blame] | 245 | int (*read_folio)(struct file *, struct folio *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 246 | int (*writepages)(struct address_space *, struct writeback_control *); |
Matthew Wilcox (Oracle) | 6f31a5a | 2022-02-09 20:22:00 +0000 | [diff] [blame] | 247 | bool (*dirty_folio)(struct address_space *, struct folio *folio); |
Matthew Wilcox (Oracle) | 8151b4c | 2020-06-01 21:46:44 -0700 | [diff] [blame] | 248 | void (*readahead)(struct readahead_control *); |
Nick Piggin | 4e02ed4 | 2008-10-29 14:00:55 -0700 | [diff] [blame] | 249 | int (*write_begin)(struct file *, struct address_space *mapping, |
Matthew Wilcox (Oracle) | 9d6b0cd | 2022-02-22 14:31:43 -0500 | [diff] [blame] | 250 | loff_t pos, unsigned len, |
Nick Piggin | 4e02ed4 | 2008-10-29 14:00:55 -0700 | [diff] [blame] | 251 | struct page **pagep, void **fsdata); |
| 252 | int (*write_end)(struct file *, struct address_space *mapping, |
| 253 | loff_t pos, unsigned len, unsigned copied, |
| 254 | struct page *page, void *fsdata); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 255 | sector_t (*bmap)(struct address_space *, sector_t); |
Matthew Wilcox (Oracle) | 128d1f8 | 2022-02-09 20:21:32 +0000 | [diff] [blame] | 256 | void (*invalidate_folio) (struct folio *, size_t start, size_t len); |
Matthew Wilcox (Oracle) | fa29000 | 2022-04-29 17:00:05 -0400 | [diff] [blame] | 257 | bool (*release_folio)(struct folio *, gfp_t); |
Matthew Wilcox (Oracle) | d2329aa | 2022-05-01 07:35:31 -0400 | [diff] [blame] | 258 | void (*free_folio)(struct folio *); |
Christoph Hellwig | c8b8e32 | 2016-04-07 08:51:58 -0700 | [diff] [blame] | 259 | int (*direct_IO)(struct kiocb *, struct iov_iter *iter); |
Matthew Wilcox (Oracle) | 5490da4 | 2022-06-06 09:00:16 -0400 | [diff] [blame] | 260 | int (*migrate_folio)(struct address_space *, struct folio *dst, |
| 261 | struct folio *src, enum migrate_mode); |
Matthew Wilcox (Oracle) | affa80e | 2022-02-09 20:21:52 +0000 | [diff] [blame] | 262 | int (*launder_folio)(struct folio *); |
Matthew Wilcox (Oracle) | 2e7e80f | 2022-02-09 20:21:27 +0000 | [diff] [blame] | 263 | bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count); |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 264 | int (*error_remove_page)(struct address_space *, struct page *); |
NeilBrown | cba738f | 2022-05-09 18:20:48 -0700 | [diff] [blame] | 265 | int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span) |
Mel Gorman | 62c230b | 2012-07-31 16:44:55 -0700 | [diff] [blame] | 266 | int (*swap_deactivate)(struct file *); |
NeilBrown | cba738f | 2022-05-09 18:20:48 -0700 | [diff] [blame] | 267 | int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 268 | |
| 269 | locking rules: |
Matthew Wilcox (Oracle) | d2329aa | 2022-05-01 07:35:31 -0400 | [diff] [blame] | 270 | All except dirty_folio and free_folio may block |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 271 | |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 272 | ====================== ======================== ========= =============== |
Matthew Wilcox (Oracle) | d2329aa | 2022-05-01 07:35:31 -0400 | [diff] [blame] | 273 | ops folio locked i_rwsem invalidate_lock |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 274 | ====================== ======================== ========= =============== |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 275 | writepage: yes, unlocks (see below) |
Matthew Wilcox (Oracle) | 08830c8 | 2022-04-29 08:45:43 -0400 | [diff] [blame] | 276 | read_folio: yes, unlocks shared |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 277 | writepages: |
Matthew Wilcox (Oracle) | fa29000 | 2022-04-29 17:00:05 -0400 | [diff] [blame] | 278 | dirty_folio: maybe |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 279 | readahead: yes, unlocks shared |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 280 | write_begin: locks the page exclusive |
| 281 | write_end: yes, unlocks exclusive |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 282 | bmap: |
Matthew Wilcox (Oracle) | 128d1f8 | 2022-02-09 20:21:32 +0000 | [diff] [blame] | 283 | invalidate_folio: yes exclusive |
Matthew Wilcox (Oracle) | fa29000 | 2022-04-29 17:00:05 -0400 | [diff] [blame] | 284 | release_folio: yes |
Matthew Wilcox (Oracle) | d2329aa | 2022-05-01 07:35:31 -0400 | [diff] [blame] | 285 | free_folio: yes |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 286 | direct_IO: |
Matthew Wilcox (Oracle) | 5490da4 | 2022-06-06 09:00:16 -0400 | [diff] [blame] | 287 | migrate_folio: yes (both) |
Matthew Wilcox (Oracle) | affa80e | 2022-02-09 20:21:52 +0000 | [diff] [blame] | 288 | launder_folio: yes |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 289 | is_partially_uptodate: yes |
| 290 | error_remove_page: yes |
Mel Gorman | 62c230b | 2012-07-31 16:44:55 -0700 | [diff] [blame] | 291 | swap_activate: no |
| 292 | swap_deactivate: no |
NeilBrown | cba738f | 2022-05-09 18:20:48 -0700 | [diff] [blame] | 293 | swap_rw: yes, unlocks |
Randy Dunlap | 7882c55 | 2021-07-27 16:22:12 -0700 | [diff] [blame] | 294 | ====================== ======================== ========= =============== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 295 | |
Matthew Wilcox (Oracle) | 08830c8 | 2022-04-29 08:45:43 -0400 | [diff] [blame] | 296 | ->write_begin(), ->write_end() and ->read_folio() may be called from |
Matthew Wilcox | f4e6d84 | 2016-03-06 23:27:26 -0500 | [diff] [blame] | 297 | the request handler (/dev/loop). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 298 | |
Matthew Wilcox (Oracle) | 08830c8 | 2022-04-29 08:45:43 -0400 | [diff] [blame] | 299 | ->read_folio() unlocks the folio, either synchronously or via I/O |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 300 | completion. |
| 301 | |
Matthew Wilcox (Oracle) | 08830c8 | 2022-04-29 08:45:43 -0400 | [diff] [blame] | 302 | ->readahead() unlocks the folios that I/O is attempted on like ->read_folio(). |
Matthew Wilcox (Oracle) | 8151b4c | 2020-06-01 21:46:44 -0700 | [diff] [blame] | 303 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 304 | ->writepage() is used for two purposes: for "memory cleansing" and for |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 305 | "sync". These are quite different operations and the behaviour may differ |
| 306 | depending upon the mode. |
| 307 | |
| 308 | If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then |
| 309 | it *must* start I/O against the page, even if that would involve |
| 310 | blocking on in-progress I/O. |
| 311 | |
| 312 | If writepage is called for memory cleansing (sync_mode == |
| 313 | WBC_SYNC_NONE) then its role is to get as much writeout underway as |
| 314 | possible. So writepage should try to avoid blocking against |
| 315 | currently-in-progress I/O. |
| 316 | |
| 317 | If the filesystem is not called for "sync" and it determines that it |
| 318 | would need to block against in-progress I/O to be able to start new I/O |
| 319 | against the page the filesystem should redirty the page with |
| 320 | redirty_page_for_writepage(), then unlock the page and return zero. |
| 321 | This may also be done to avoid internal deadlocks, but rarely. |
| 322 | |
Robert P. J. Day | 3a4fa0a | 2007-10-19 23:10:43 +0200 | [diff] [blame] | 323 | 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] | 324 | in-progress I/O and then start new I/O. |
| 325 | |
Nikita Danilov | 2054606 | 2005-05-01 08:58:37 -0700 | [diff] [blame] | 326 | The filesystem should unlock the page synchronously, before returning to the |
| 327 | caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE |
| 328 | value. WRITEPAGE_ACTIVATE means that page cannot really be written out |
| 329 | currently, and VM should stop calling ->writepage() on this page for some |
| 330 | time. VM does this by moving page to the head of the active list, hence the |
| 331 | name. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 332 | |
| 333 | Unless the filesystem is going to redirty_page_for_writepage(), unlock the page |
| 334 | and return zero, writepage *must* run set_page_writeback() against the page, |
| 335 | followed by unlocking it. Once set_page_writeback() has been run against the |
| 336 | page, write I/O can be submitted and the write I/O completion handler must run |
| 337 | end_page_writeback() once the I/O is complete. If no I/O is submitted, the |
| 338 | filesystem must run end_page_writeback() against the page before returning from |
| 339 | writepage. |
| 340 | |
| 341 | That is: after 2.5.12, pages which are under writeout are *not* locked. Note, |
| 342 | if the filesystem needs the page to be locked during writeout, that is ok, too, |
| 343 | the page is allowed to be unlocked at any point in time between the calls to |
| 344 | set_page_writeback() and end_page_writeback(). |
| 345 | |
| 346 | Note, failure to run either redirty_page_for_writepage() or the combination of |
| 347 | set_page_writeback()/end_page_writeback() on a page submitted to writepage |
| 348 | will leave the page itself marked clean but it will be tagged as dirty in the |
| 349 | radix tree. This incoherency can lead to all sorts of hard-to-debug problems |
| 350 | in the filesystem like having dirty inodes at umount and losing written data. |
| 351 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 352 | ->writepages() is used for periodic writeback and for syscall-initiated |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 353 | sync operations. The address_space should start I/O against at least |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 354 | ``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page |
| 355 | which is written. The address_space implementation may write more (or less) |
| 356 | pages than ``*nr_to_write`` asks for, but it should try to be reasonably close. |
| 357 | If nr_to_write is NULL, all dirty pages must be written. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 358 | |
| 359 | writepages should _only_ write pages which are present on |
| 360 | mapping->io_pages. |
| 361 | |
Matthew Wilcox (Oracle) | 6f31a5a | 2022-02-09 20:22:00 +0000 | [diff] [blame] | 362 | ->dirty_folio() is called from various places in the kernel when |
| 363 | the target folio is marked as needing writeback. The folio cannot be |
| 364 | truncated because either the caller holds the folio lock, or the caller |
| 365 | has found the folio while holding the page table lock which will block |
| 366 | truncation. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 367 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 368 | ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 369 | filesystems and by the swapper. The latter will eventually go away. Please, |
| 370 | keep it that way and don't breed new callers. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 371 | |
Matthew Wilcox (Oracle) | 128d1f8 | 2022-02-09 20:21:32 +0000 | [diff] [blame] | 372 | ->invalidate_folio() is called when the filesystem must attempt to drop |
Lukas Czerner | d47992f | 2013-05-21 23:17:23 -0400 | [diff] [blame] | 373 | some or all of the buffers from the page when it is being truncated. It |
Matthew Wilcox (Oracle) | 128d1f8 | 2022-02-09 20:21:32 +0000 | [diff] [blame] | 374 | returns zero on success. The filesystem must exclusively acquire |
| 375 | invalidate_lock before invalidating page cache in truncate / hole punch |
| 376 | path (and thus calling into ->invalidate_folio) to block races between page |
| 377 | cache invalidation and page cache filling functions (fault, read, ...). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 378 | |
Matthew Wilcox (Oracle) | 32b29cc | 2023-06-02 16:33:20 -0400 | [diff] [blame] | 379 | ->release_folio() is called when the MM wants to make a change to the |
| 380 | folio that would invalidate the filesystem's private data. For example, |
| 381 | it may be about to be removed from the address_space or split. The folio |
| 382 | is locked and not under writeback. It may be dirty. The gfp parameter |
| 383 | is not usually used for allocation, but rather to indicate what the |
| 384 | filesystem may do to attempt to free the private data. The filesystem may |
| 385 | return false to indicate that the folio's private data cannot be freed. |
| 386 | If it returns true, it should have already removed the private data from |
| 387 | the folio. If a filesystem does not provide a ->release_folio method, |
| 388 | the pagecache will assume that private data is buffer_heads and call |
| 389 | try_to_free_buffers(). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 390 | |
Matthew Wilcox (Oracle) | d2329aa | 2022-05-01 07:35:31 -0400 | [diff] [blame] | 391 | ->free_folio() is called when the kernel has dropped the folio |
Linus Torvalds | 6072d13 | 2010-12-01 13:35:19 -0500 | [diff] [blame] | 392 | from the page cache. |
| 393 | |
Matthew Wilcox (Oracle) | affa80e | 2022-02-09 20:21:52 +0000 | [diff] [blame] | 394 | ->launder_folio() may be called prior to releasing a folio if |
| 395 | it is still found to be dirty. It returns zero if the folio was successfully |
| 396 | cleaned, or an error value if not. Note that in order to prevent the folio |
Trond Myklebust | e3db769 | 2007-01-10 23:15:39 -0800 | [diff] [blame] | 397 | getting mapped back in and redirtied, it needs to be kept locked |
| 398 | across the entire operation. |
| 399 | |
NeilBrown | cba738f | 2022-05-09 18:20:48 -0700 | [diff] [blame] | 400 | ->swap_activate() will be called to prepare the given file for swap. It |
| 401 | should perform any validation and preparation necessary to ensure that |
| 402 | writes can be performed with minimal memory allocation. It should call |
| 403 | add_swap_extent(), or the helper iomap_swapfile_activate(), and return |
| 404 | the number of extents added. If IO should be submitted through |
| 405 | ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will be submitted |
| 406 | directly to the block device ``sis->bdev``. |
Mel Gorman | 62c230b | 2012-07-31 16:44:55 -0700 | [diff] [blame] | 407 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 408 | ->swap_deactivate() will be called in the sys_swapoff() |
Mel Gorman | 62c230b | 2012-07-31 16:44:55 -0700 | [diff] [blame] | 409 | path after ->swap_activate() returned success. |
| 410 | |
NeilBrown | cba738f | 2022-05-09 18:20:48 -0700 | [diff] [blame] | 411 | ->swap_rw will be called for swap IO if SWP_FS_OPS was set by ->swap_activate(). |
| 412 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 413 | file_lock_operations |
| 414 | ==================== |
| 415 | |
| 416 | prototypes:: |
| 417 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 418 | void (*fl_copy_lock)(struct file_lock *, struct file_lock *); |
| 419 | void (*fl_release_private)(struct file_lock *); |
| 420 | |
| 421 | |
| 422 | locking rules: |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 423 | |
| 424 | =================== ============= ========= |
| 425 | ops inode->i_lock may block |
| 426 | =================== ============= ========= |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 427 | fl_copy_lock: yes no |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 428 | fl_release_private: maybe maybe[1]_ |
| 429 | =================== ============= ========= |
Jeff Layton | 2ece173 | 2014-08-12 10:38:07 -0400 | [diff] [blame] | 430 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 431 | .. [1]: |
| 432 | ->fl_release_private for flock or POSIX locks is currently allowed |
| 433 | to block. Leases however can still be freed while the i_lock is held and |
| 434 | so fl_release_private called on a lease should not block. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 435 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 436 | lock_manager_operations |
| 437 | ======================= |
| 438 | |
| 439 | prototypes:: |
| 440 | |
J. Bruce Fields | 8fb47a4 | 2011-07-20 20:21:59 -0400 | [diff] [blame] | 441 | void (*lm_notify)(struct file_lock *); /* unblock callback */ |
| 442 | int (*lm_grant)(struct file_lock *, struct file_lock *, int); |
J. Bruce Fields | 8fb47a4 | 2011-07-20 20:21:59 -0400 | [diff] [blame] | 443 | void (*lm_break)(struct file_lock *); /* break_lease callback */ |
| 444 | int (*lm_change)(struct file_lock **, int); |
J. Bruce Fields | 28df3d1 | 2017-07-28 16:35:15 -0400 | [diff] [blame] | 445 | bool (*lm_breaker_owns_lease)(struct file_lock *); |
Dai Ngo | 2443da2 | 2022-05-02 14:19:25 -0700 | [diff] [blame] | 446 | bool (*lm_lock_expirable)(struct file_lock *); |
| 447 | void (*lm_expire_lock)(void); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 448 | |
| 449 | locking rules: |
Jeff Layton | 1c8c601 | 2013-06-21 08:58:15 -0400 | [diff] [blame] | 450 | |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 451 | ====================== ============= ================= ========= |
Dai Ngo | 9d66477 | 2022-02-12 10:12:52 -0800 | [diff] [blame] | 452 | ops flc_lock blocked_lock_lock may block |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 453 | ====================== ============= ================= ========= |
Dai Ngo | 9d66477 | 2022-02-12 10:12:52 -0800 | [diff] [blame] | 454 | lm_notify: no yes no |
Jeff Layton | 7b2296a | 2013-06-21 08:58:20 -0400 | [diff] [blame] | 455 | lm_grant: no no no |
| 456 | lm_break: yes no no |
| 457 | lm_change yes no no |
Dai Ngo | 9d66477 | 2022-02-12 10:12:52 -0800 | [diff] [blame] | 458 | lm_breaker_owns_lease: yes no no |
Dai Ngo | 2443da2 | 2022-05-02 14:19:25 -0700 | [diff] [blame] | 459 | lm_lock_expirable yes no no |
| 460 | lm_expire_lock no no yes |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 461 | ====================== ============= ================= ========= |
Jeff Layton | 1c8c601 | 2013-06-21 08:58:15 -0400 | [diff] [blame] | 462 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 463 | buffer_head |
| 464 | =========== |
| 465 | |
| 466 | prototypes:: |
| 467 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 468 | void (*b_end_io)(struct buffer_head *bh, int uptodate); |
| 469 | |
| 470 | locking rules: |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 471 | |
| 472 | called from interrupts. In other words, extreme care is needed here. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 473 | bh is locked, but that's all warranties we have here. Currently only RAID1, |
| 474 | highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices |
| 475 | call this method upon the IO completion. |
| 476 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 477 | block_device_operations |
| 478 | ======================= |
| 479 | prototypes:: |
| 480 | |
Christoph Hellwig | e1455d1 | 2010-10-06 10:46:53 +0200 | [diff] [blame] | 481 | int (*open) (struct block_device *, fmode_t); |
| 482 | int (*release) (struct gendisk *, fmode_t); |
| 483 | int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); |
| 484 | int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); |
Dan Williams | 7a9eb20 | 2016-06-03 18:06:47 -0700 | [diff] [blame] | 485 | int (*direct_access) (struct block_device *, sector_t, void **, |
Ross Zwisler | e2e0539 | 2015-08-18 13:55:41 -0600 | [diff] [blame] | 486 | unsigned long *); |
Christoph Hellwig | e1455d1 | 2010-10-06 10:46:53 +0200 | [diff] [blame] | 487 | void (*unlock_native_capacity) (struct gendisk *); |
Christoph Hellwig | e1455d1 | 2010-10-06 10:46:53 +0200 | [diff] [blame] | 488 | int (*getgeo)(struct block_device *, struct hd_geometry *); |
| 489 | void (*swap_slot_free_notify) (struct block_device *, unsigned long); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 490 | |
| 491 | locking rules: |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 492 | |
| 493 | ======================= =================== |
Christoph Hellwig | a869870 | 2021-05-25 08:12:56 +0200 | [diff] [blame] | 494 | ops open_mutex |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 495 | ======================= =================== |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 496 | open: yes |
| 497 | release: yes |
| 498 | ioctl: no |
| 499 | compat_ioctl: no |
| 500 | direct_access: no |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 501 | unlock_native_capacity: no |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 502 | getgeo: no |
| 503 | swap_slot_free_notify: no (see below) |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 504 | ======================= =================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 505 | |
Christoph Hellwig | e1455d1 | 2010-10-06 10:46:53 +0200 | [diff] [blame] | 506 | swap_slot_free_notify is called with swap_lock and sometimes the page lock |
| 507 | held. |
| 508 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 509 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 510 | file_operations |
| 511 | =============== |
| 512 | |
| 513 | prototypes:: |
| 514 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 515 | loff_t (*llseek) (struct file *, loff_t, int); |
| 516 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 517 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); |
Al Viro | 293bc98 | 2014-02-11 18:37:41 -0500 | [diff] [blame] | 518 | ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); |
| 519 | ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); |
Jan Kara | c625b4c | 2021-05-10 19:13:53 +0200 | [diff] [blame] | 520 | int (*iopoll) (struct kiocb *kiocb, bool spin); |
Al Viro | 2233f31 | 2013-05-22 21:44:23 -0400 | [diff] [blame] | 521 | int (*iterate) (struct file *, struct dir_context *); |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 522 | int (*iterate_shared) (struct file *, struct dir_context *); |
Christoph Hellwig | 6e8b704 | 2018-01-02 22:50:45 +0100 | [diff] [blame] | 523 | __poll_t (*poll) (struct file *, struct poll_table_struct *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 524 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); |
| 525 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); |
| 526 | int (*mmap) (struct file *, struct vm_area_struct *); |
| 527 | int (*open) (struct inode *, struct file *); |
| 528 | int (*flush) (struct file *); |
| 529 | int (*release) (struct inode *, struct file *); |
Josef Bacik | 02c24a8 | 2011-07-16 20:44:56 -0400 | [diff] [blame] | 530 | int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 531 | int (*fasync) (int, struct file *, int); |
| 532 | int (*lock) (struct file *, int, struct file_lock *); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 533 | unsigned long (*get_unmapped_area)(struct file *, unsigned long, |
| 534 | unsigned long, unsigned long, unsigned long); |
| 535 | int (*check_flags)(int); |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 536 | int (*flock) (struct file *, int, struct file_lock *); |
| 537 | ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, |
| 538 | size_t, unsigned int); |
| 539 | ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, |
| 540 | size_t, unsigned int); |
Jeff Layton | e6f5c78 | 2014-08-22 10:40:25 -0400 | [diff] [blame] | 541 | int (*setlease)(struct file *, long, struct file_lock **, void **); |
Christoph Hellwig | 2fe17c1 | 2011-01-14 13:07:43 +0100 | [diff] [blame] | 542 | long (*fallocate)(struct file *, int, loff_t, loff_t); |
Jan Kara | c625b4c | 2021-05-10 19:13:53 +0200 | [diff] [blame] | 543 | void (*show_fdinfo)(struct seq_file *m, struct file *f); |
| 544 | unsigned (*mmap_capabilities)(struct file *); |
| 545 | ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, |
| 546 | loff_t, size_t, unsigned int); |
| 547 | loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in, |
| 548 | struct file *file_out, loff_t pos_out, |
| 549 | loff_t len, unsigned int remap_flags); |
| 550 | int (*fadvise)(struct file *, loff_t, loff_t, int); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 551 | |
| 552 | locking rules: |
Linus Torvalds | a11e1d4 | 2018-06-28 09:43:44 -0700 | [diff] [blame] | 553 | All may block. |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 554 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 555 | ->llseek() locking has moved from llseek to the individual llseek |
| 556 | implementations. If your fs is not using generic_file_llseek, you |
| 557 | need to acquire and release the appropriate locks in your ->llseek(). |
| 558 | For many filesystems, it is probably safe to acquire the inode |
Jan Blunck | 866707f | 2010-05-26 14:44:54 -0700 | [diff] [blame] | 559 | mutex or just to use i_size_read() instead. |
| 560 | Note: this does not protect the file->f_pos against concurrent modifications |
| 561 | since this is something the userspace has to take care about. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 562 | |
Linus Torvalds | 3e32715 | 2023-08-05 12:25:01 -0700 | [diff] [blame] | 563 | ->iterate_shared() is called with i_rwsem held for reading, and with the |
| 564 | file f_pos_lock held exclusively |
Sean Anderson | 965de0e | 2018-05-23 22:29:10 -0400 | [diff] [blame] | 565 | |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 566 | ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. |
| 567 | Most instances call fasync_helper(), which does that maintenance, so it's |
| 568 | not normally something one needs to worry about. Return values > 0 will be |
| 569 | mapped to zero in the VFS layer. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 570 | |
| 571 | ->readdir() and ->ioctl() on directories must be changed. Ideally we would |
| 572 | move ->readdir() to inode_operations and use a separate method for directory |
| 573 | ->ioctl() or kill the latter completely. One of the problems is that for |
| 574 | anything that resembles union-mount we won't have a struct file for all |
| 575 | components. And there are other reasons why the current interface is a mess... |
| 576 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 577 | ->read on directories probably must go away - we should just enforce -EISDIR |
| 578 | in sys_read() and friends. |
| 579 | |
Jeff Layton | f82b4b6 | 2014-08-22 18:50:48 -0400 | [diff] [blame] | 580 | ->setlease operations should call generic_setlease() before or after setting |
| 581 | the lease within the individual filesystem to record the result of the |
| 582 | operation |
| 583 | |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 584 | ->fallocate implementation must be really careful to maintain page cache |
| 585 | consistency when punching holes or performing other operations that invalidate |
| 586 | page cache contents. Usually the filesystem needs to call |
| 587 | truncate_inode_pages_range() to invalidate relevant range of the page cache. |
| 588 | However the filesystem usually also needs to update its internal (and on disk) |
| 589 | view of file offset -> disk block mapping. Until this update is finished, the |
| 590 | filesystem needs to block page faults and reads from reloading now-stale page |
| 591 | cache contents from the disk. Since VFS acquires mapping->invalidate_lock in |
| 592 | shared mode when loading pages from disk (filemap_fault(), filemap_read(), |
| 593 | readahead paths), the fallocate implementation must take the invalidate_lock to |
| 594 | prevent reloading. |
| 595 | |
| 596 | ->copy_file_range and ->remap_file_range implementations need to serialize |
| 597 | against modifications of file data while the operation is running. For |
| 598 | blocking changes through write(2) and similar operations inode->i_rwsem can be |
| 599 | used. To block changes to file contents via a memory mapping during the |
| 600 | operation, the filesystem must take mapping->invalidate_lock to coordinate |
| 601 | with ->page_mkwrite. |
| 602 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 603 | dquot_operations |
| 604 | ================ |
| 605 | |
| 606 | prototypes:: |
| 607 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 608 | int (*write_dquot) (struct dquot *); |
| 609 | int (*acquire_dquot) (struct dquot *); |
| 610 | int (*release_dquot) (struct dquot *); |
| 611 | int (*mark_dirty) (struct dquot *); |
| 612 | int (*write_info) (struct super_block *, int); |
| 613 | |
| 614 | These operations are intended to be more or less wrapping functions that ensure |
| 615 | a proper locking wrt the filesystem and call the generic quota operations. |
| 616 | |
| 617 | What filesystem should expect from the generic quota functions: |
| 618 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 619 | ============== ============ ========================= |
| 620 | ops FS recursion Held locks when called |
| 621 | ============== ============ ========================= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 622 | write_dquot: yes dqonoff_sem or dqptr_sem |
| 623 | acquire_dquot: yes dqonoff_sem or dqptr_sem |
| 624 | release_dquot: yes dqonoff_sem or dqptr_sem |
| 625 | mark_dirty: no - |
| 626 | write_info: yes dqonoff_sem |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 627 | ============== ============ ========================= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 628 | |
| 629 | FS recursion means calling ->quota_read() and ->quota_write() from superblock |
| 630 | operations. |
| 631 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 632 | More details about quota locking can be found in fs/dquot.c. |
| 633 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 634 | vm_operations_struct |
| 635 | ==================== |
| 636 | |
| 637 | prototypes:: |
| 638 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 639 | void (*open)(struct vm_area_struct*); |
| 640 | void (*close)(struct vm_area_struct*); |
Souptick Joarder | fe3136f | 2018-07-22 18:31:34 +0530 | [diff] [blame] | 641 | vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); |
| 642 | vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *); |
| 643 | vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *); |
Rik van Riel | 28b2ee2 | 2008-07-23 21:27:05 -0700 | [diff] [blame] | 644 | int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 645 | |
| 646 | locking rules: |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 647 | |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 648 | ============= ========= =========================== |
Michel Lespinasse | c1e8d7c | 2020-06-08 21:33:54 -0700 | [diff] [blame] | 649 | ops mmap_lock PageLocked(page) |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 650 | ============= ========= =========================== |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 651 | open: yes |
| 652 | close: yes |
| 653 | fault: yes can return with page locked |
Matthew Wilcox (Oracle) | 58ef47e | 2023-03-27 18:45:15 +0100 | [diff] [blame] | 654 | map_pages: read |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 655 | page_mkwrite: yes can return with page locked |
Boaz Harrosh | dd90618 | 2015-04-15 16:15:11 -0700 | [diff] [blame] | 656 | pfn_mkwrite: yes |
Christoph Hellwig | b83be6f | 2010-12-16 12:04:54 +0100 | [diff] [blame] | 657 | access: yes |
Randy Dunlap | 6cbef2a | 2020-06-14 20:22:19 -0700 | [diff] [blame] | 658 | ============= ========= =========================== |
Mark Fasheh | ed2f2f9 | 2007-07-19 01:47:01 -0700 | [diff] [blame] | 659 | |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 660 | ->fault() is called when a previously not present pte is about to be faulted |
| 661 | in. The filesystem must find and return the page associated with the passed in |
| 662 | "pgoff" in the vm_fault structure. If it is possible that the page may be |
| 663 | truncated and/or invalidated, then the filesystem must lock invalidate_lock, |
| 664 | then ensure the page is not already truncated (invalidate_lock will block |
Nick Piggin | b827e49 | 2009-04-30 15:08:16 -0700 | [diff] [blame] | 665 | subsequent truncate), and then return with VM_FAULT_LOCKED, and the page |
| 666 | locked. The VM will unlock the page. |
| 667 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 668 | ->map_pages() is called when VM asks to map easy accessible pages. |
Kirill A. Shutemov | bae473a | 2016-07-26 15:25:20 -0700 | [diff] [blame] | 669 | Filesystem should find and map pages associated with offsets from "start_pgoff" |
Matthew Wilcox (Oracle) | 58ef47e | 2023-03-27 18:45:15 +0100 | [diff] [blame] | 670 | till "end_pgoff". ->map_pages() is called with the RCU lock held and must |
Kirill A. Shutemov | 8c6e50b | 2014-04-07 15:37:18 -0700 | [diff] [blame] | 671 | not block. If it's not possible to reach a page without blocking, |
| 672 | filesystem should skip it. Filesystem should use do_set_pte() to setup |
Kirill A. Shutemov | bae473a | 2016-07-26 15:25:20 -0700 | [diff] [blame] | 673 | page table entry. Pointer to entry associated with the page is passed in |
Jan Kara | 82b0f8c | 2016-12-14 15:06:58 -0800 | [diff] [blame] | 674 | "pte" field in vm_fault structure. Pointers to entries for other offsets |
Kirill A. Shutemov | bae473a | 2016-07-26 15:25:20 -0700 | [diff] [blame] | 675 | should be calculated relative to "pte". |
Kirill A. Shutemov | 8c6e50b | 2014-04-07 15:37:18 -0700 | [diff] [blame] | 676 | |
Jan Kara | 730633f | 2021-01-28 19:19:45 +0100 | [diff] [blame] | 677 | ->page_mkwrite() is called when a previously read-only pte is about to become |
| 678 | writeable. The filesystem again must ensure that there are no |
| 679 | truncate/invalidate races or races with operations such as ->remap_file_range |
| 680 | or ->copy_file_range, and then return with the page locked. Usually |
| 681 | mapping->invalidate_lock is suitable for proper serialization. If the page has |
| 682 | been truncated, the filesystem should not look up a new page like the ->fault() |
| 683 | handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to |
| 684 | retry the fault. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 685 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 686 | ->pfn_mkwrite() is the same as page_mkwrite but when the pte is |
Boaz Harrosh | dd90618 | 2015-04-15 16:15:11 -0700 | [diff] [blame] | 687 | VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is |
| 688 | VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior |
| 689 | after this call is to make the pte read-write, unless pfn_mkwrite returns |
| 690 | an error. |
| 691 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 692 | ->access() is called when get_user_pages() fails in |
Stefan Weil | 507da6a | 2013-12-05 20:34:05 +0100 | [diff] [blame] | 693 | access_process_vm(), typically used to debug a process through |
Rik van Riel | 28b2ee2 | 2008-07-23 21:27:05 -0700 | [diff] [blame] | 694 | /proc/pid/mem or ptrace. This function is needed only for |
| 695 | VM_IO | VM_PFNMAP VMAs. |
| 696 | |
Mauro Carvalho Chehab | ec23eb5 | 2019-07-26 09:51:27 -0300 | [diff] [blame] | 697 | -------------------------------------------------------------------------------- |
| 698 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 699 | Dubious stuff |
| 700 | |
| 701 | (if you break something or notice that it is broken and do not fix it yourself |
| 702 | - at least put it here) |