David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 1 | ==================== |
| 2 | FILESYSTEM MOUNT API |
| 3 | ==================== |
| 4 | |
| 5 | CONTENTS |
| 6 | |
| 7 | (1) Overview. |
| 8 | |
| 9 | (2) The filesystem context. |
| 10 | |
| 11 | (3) The filesystem context operations. |
| 12 | |
| 13 | (4) Filesystem context security. |
| 14 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 15 | (5) VFS filesystem context API. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 16 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 17 | (6) Superblock creation helpers. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 18 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 19 | (7) Parameter description. |
| 20 | |
| 21 | (8) Parameter helper functions. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 22 | |
| 23 | |
| 24 | ======== |
| 25 | OVERVIEW |
| 26 | ======== |
| 27 | |
| 28 | The creation of new mounts is now to be done in a multistep process: |
| 29 | |
| 30 | (1) Create a filesystem context. |
| 31 | |
| 32 | (2) Parse the parameters and attach them to the context. Parameters are |
| 33 | expected to be passed individually from userspace, though legacy binary |
| 34 | parameters can also be handled. |
| 35 | |
| 36 | (3) Validate and pre-process the context. |
| 37 | |
| 38 | (4) Get or create a superblock and mountable root. |
| 39 | |
| 40 | (5) Perform the mount. |
| 41 | |
| 42 | (6) Return an error message attached to the context. |
| 43 | |
| 44 | (7) Destroy the context. |
| 45 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 46 | To support this, the file_system_type struct gains two new fields: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 47 | |
| 48 | int (*init_fs_context)(struct fs_context *fc); |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 49 | const struct fs_parameter_description *parameters; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 50 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 51 | The first is invoked to set up the filesystem-specific parts of a filesystem |
| 52 | context, including the additional space, and the second points to the |
| 53 | parameter description for validation at registration time and querying by a |
| 54 | future system call. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 55 | |
| 56 | Note that security initialisation is done *after* the filesystem is called so |
| 57 | that the namespaces may be adjusted first. |
| 58 | |
| 59 | |
| 60 | ====================== |
| 61 | THE FILESYSTEM CONTEXT |
| 62 | ====================== |
| 63 | |
| 64 | The creation and reconfiguration of a superblock is governed by a filesystem |
| 65 | context. This is represented by the fs_context structure: |
| 66 | |
| 67 | struct fs_context { |
| 68 | const struct fs_context_operations *ops; |
| 69 | struct file_system_type *fs_type; |
| 70 | void *fs_private; |
| 71 | struct dentry *root; |
| 72 | struct user_namespace *user_ns; |
| 73 | struct net *net_ns; |
| 74 | const struct cred *cred; |
| 75 | char *source; |
| 76 | char *subtype; |
| 77 | void *security; |
| 78 | void *s_fs_info; |
| 79 | unsigned int sb_flags; |
| 80 | unsigned int sb_flags_mask; |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 81 | unsigned int s_iflags; |
| 82 | unsigned int lsm_flags; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 83 | enum fs_context_purpose purpose:8; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 84 | ... |
| 85 | }; |
| 86 | |
| 87 | The fs_context fields are as follows: |
| 88 | |
| 89 | (*) const struct fs_context_operations *ops |
| 90 | |
| 91 | These are operations that can be done on a filesystem context (see |
| 92 | below). This must be set by the ->init_fs_context() file_system_type |
| 93 | operation. |
| 94 | |
| 95 | (*) struct file_system_type *fs_type |
| 96 | |
| 97 | A pointer to the file_system_type of the filesystem that is being |
| 98 | constructed or reconfigured. This retains a reference on the type owner. |
| 99 | |
| 100 | (*) void *fs_private |
| 101 | |
| 102 | A pointer to the file system's private data. This is where the filesystem |
| 103 | will need to store any options it parses. |
| 104 | |
| 105 | (*) struct dentry *root |
| 106 | |
| 107 | A pointer to the root of the mountable tree (and indirectly, the |
| 108 | superblock thereof). This is filled in by the ->get_tree() op. If this |
| 109 | is set, an active reference on root->d_sb must also be held. |
| 110 | |
| 111 | (*) struct user_namespace *user_ns |
| 112 | (*) struct net *net_ns |
| 113 | |
| 114 | There are a subset of the namespaces in use by the invoking process. They |
| 115 | retain references on each namespace. The subscribed namespaces may be |
| 116 | replaced by the filesystem to reflect other sources, such as the parent |
| 117 | mount superblock on an automount. |
| 118 | |
| 119 | (*) const struct cred *cred |
| 120 | |
| 121 | The mounter's credentials. This retains a reference on the credentials. |
| 122 | |
| 123 | (*) char *source |
| 124 | |
| 125 | This specifies the source. It may be a block device (e.g. /dev/sda1) or |
| 126 | something more exotic, such as the "host:/path" that NFS desires. |
| 127 | |
| 128 | (*) char *subtype |
| 129 | |
| 130 | This is a string to be added to the type displayed in /proc/mounts to |
| 131 | qualify it (used by FUSE). This is available for the filesystem to set if |
| 132 | desired. |
| 133 | |
| 134 | (*) void *security |
| 135 | |
| 136 | A place for the LSMs to hang their security data for the superblock. The |
| 137 | relevant security operations are described below. |
| 138 | |
| 139 | (*) void *s_fs_info |
| 140 | |
| 141 | The proposed s_fs_info for a new superblock, set in the superblock by |
| 142 | sget_fc(). This can be used to distinguish superblocks. |
| 143 | |
| 144 | (*) unsigned int sb_flags |
| 145 | (*) unsigned int sb_flags_mask |
| 146 | |
| 147 | Which bits SB_* flags are to be set/cleared in super_block::s_flags. |
| 148 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 149 | (*) unsigned int s_iflags |
| 150 | |
| 151 | These will be bitwise-OR'd with s->s_iflags when a superblock is created. |
| 152 | |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 153 | (*) enum fs_context_purpose |
| 154 | |
| 155 | This indicates the purpose for which the context is intended. The |
| 156 | available values are: |
| 157 | |
| 158 | FS_CONTEXT_FOR_MOUNT, -- New superblock for explicit mount |
| 159 | FS_CONTEXT_FOR_SUBMOUNT -- New automatic submount of extant mount |
| 160 | FS_CONTEXT_FOR_RECONFIGURE -- Change an existing mount |
| 161 | |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 162 | The mount context is created by calling vfs_new_fs_context() or |
| 163 | vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the |
| 164 | structure is not refcounted. |
| 165 | |
| 166 | VFS, security and filesystem mount options are set individually with |
| 167 | vfs_parse_mount_option(). Options provided by the old mount(2) system call as |
| 168 | a page of data can be parsed with generic_parse_monolithic(). |
| 169 | |
| 170 | When mounting, the filesystem is allowed to take data from any of the pointers |
| 171 | and attach it to the superblock (or whatever), provided it clears the pointer |
| 172 | in the mount context. |
| 173 | |
| 174 | The filesystem is also allowed to allocate resources and pin them with the |
| 175 | mount context. For instance, NFS might pin the appropriate protocol version |
| 176 | module. |
| 177 | |
| 178 | |
| 179 | ================================= |
| 180 | THE FILESYSTEM CONTEXT OPERATIONS |
| 181 | ================================= |
| 182 | |
| 183 | The filesystem context points to a table of operations: |
| 184 | |
| 185 | struct fs_context_operations { |
| 186 | void (*free)(struct fs_context *fc); |
| 187 | int (*dup)(struct fs_context *fc, struct fs_context *src_fc); |
| 188 | int (*parse_param)(struct fs_context *fc, |
| 189 | struct struct fs_parameter *param); |
| 190 | int (*parse_monolithic)(struct fs_context *fc, void *data); |
| 191 | int (*get_tree)(struct fs_context *fc); |
| 192 | int (*reconfigure)(struct fs_context *fc); |
| 193 | }; |
| 194 | |
| 195 | These operations are invoked by the various stages of the mount procedure to |
| 196 | manage the filesystem context. They are as follows: |
| 197 | |
| 198 | (*) void (*free)(struct fs_context *fc); |
| 199 | |
| 200 | Called to clean up the filesystem-specific part of the filesystem context |
| 201 | when the context is destroyed. It should be aware that parts of the |
| 202 | context may have been removed and NULL'd out by ->get_tree(). |
| 203 | |
| 204 | (*) int (*dup)(struct fs_context *fc, struct fs_context *src_fc); |
| 205 | |
| 206 | Called when a filesystem context has been duplicated to duplicate the |
| 207 | filesystem-private data. An error may be returned to indicate failure to |
| 208 | do this. |
| 209 | |
| 210 | [!] Note that even if this fails, put_fs_context() will be called |
| 211 | immediately thereafter, so ->dup() *must* make the |
| 212 | filesystem-private data safe for ->free(). |
| 213 | |
| 214 | (*) int (*parse_param)(struct fs_context *fc, |
| 215 | struct struct fs_parameter *param); |
| 216 | |
| 217 | Called when a parameter is being added to the filesystem context. param |
| 218 | points to the key name and maybe a value object. VFS-specific options |
| 219 | will have been weeded out and fc->sb_flags updated in the context. |
| 220 | Security options will also have been weeded out and fc->security updated. |
| 221 | |
| 222 | The parameter can be parsed with fs_parse() and fs_lookup_param(). Note |
| 223 | that the source(s) are presented as parameters named "source". |
| 224 | |
| 225 | If successful, 0 should be returned or a negative error code otherwise. |
| 226 | |
| 227 | (*) int (*parse_monolithic)(struct fs_context *fc, void *data); |
| 228 | |
| 229 | Called when the mount(2) system call is invoked to pass the entire data |
| 230 | page in one go. If this is expected to be just a list of "key[=val]" |
| 231 | items separated by commas, then this may be set to NULL. |
| 232 | |
| 233 | The return value is as for ->parse_param(). |
| 234 | |
| 235 | If the filesystem (e.g. NFS) needs to examine the data first and then |
| 236 | finds it's the standard key-val list then it may pass it off to |
| 237 | generic_parse_monolithic(). |
| 238 | |
| 239 | (*) int (*get_tree)(struct fs_context *fc); |
| 240 | |
| 241 | Called to get or create the mountable root and superblock, using the |
| 242 | information stored in the filesystem context (reconfiguration goes via a |
| 243 | different vector). It may detach any resources it desires from the |
| 244 | filesystem context and transfer them to the superblock it creates. |
| 245 | |
| 246 | On success it should set fc->root to the mountable root and return 0. In |
| 247 | the case of an error, it should return a negative error code. |
| 248 | |
| 249 | The phase on a userspace-driven context will be set to only allow this to |
| 250 | be called once on any particular context. |
| 251 | |
| 252 | (*) int (*reconfigure)(struct fs_context *fc); |
| 253 | |
| 254 | Called to effect reconfiguration of a superblock using information stored |
| 255 | in the filesystem context. It may detach any resources it desires from |
| 256 | the filesystem context and transfer them to the superblock. The |
| 257 | superblock can be found from fc->root->d_sb. |
| 258 | |
| 259 | On success it should return 0. In the case of an error, it should return |
| 260 | a negative error code. |
| 261 | |
| 262 | [NOTE] reconfigure is intended as a replacement for remount_fs. |
| 263 | |
| 264 | |
| 265 | =========================== |
| 266 | FILESYSTEM CONTEXT SECURITY |
| 267 | =========================== |
| 268 | |
| 269 | The filesystem context contains a security pointer that the LSMs can use for |
| 270 | building up a security context for the superblock to be mounted. There are a |
| 271 | number of operations used by the new mount code for this purpose: |
| 272 | |
| 273 | (*) int security_fs_context_alloc(struct fs_context *fc, |
| 274 | struct dentry *reference); |
| 275 | |
| 276 | Called to initialise fc->security (which is preset to NULL) and allocate |
| 277 | any resources needed. It should return 0 on success or a negative error |
| 278 | code on failure. |
| 279 | |
| 280 | reference will be non-NULL if the context is being created for superblock |
| 281 | reconfiguration (FS_CONTEXT_FOR_RECONFIGURE) in which case it indicates |
| 282 | the root dentry of the superblock to be reconfigured. It will also be |
| 283 | non-NULL in the case of a submount (FS_CONTEXT_FOR_SUBMOUNT) in which case |
| 284 | it indicates the automount point. |
| 285 | |
| 286 | (*) int security_fs_context_dup(struct fs_context *fc, |
| 287 | struct fs_context *src_fc); |
| 288 | |
| 289 | Called to initialise fc->security (which is preset to NULL) and allocate |
| 290 | any resources needed. The original filesystem context is pointed to by |
| 291 | src_fc and may be used for reference. It should return 0 on success or a |
| 292 | negative error code on failure. |
| 293 | |
| 294 | (*) void security_fs_context_free(struct fs_context *fc); |
| 295 | |
| 296 | Called to clean up anything attached to fc->security. Note that the |
| 297 | contents may have been transferred to a superblock and the pointer cleared |
| 298 | during get_tree. |
| 299 | |
| 300 | (*) int security_fs_context_parse_param(struct fs_context *fc, |
| 301 | struct fs_parameter *param); |
| 302 | |
| 303 | Called for each mount parameter, including the source. The arguments are |
| 304 | as for the ->parse_param() method. It should return 0 to indicate that |
| 305 | the parameter should be passed on to the filesystem, 1 to indicate that |
| 306 | the parameter should be discarded or an error to indicate that the |
| 307 | parameter should be rejected. |
| 308 | |
| 309 | The value pointed to by param may be modified (if a string) or stolen |
| 310 | (provided the value pointer is NULL'd out). If it is stolen, 1 must be |
| 311 | returned to prevent it being passed to the filesystem. |
| 312 | |
| 313 | (*) int security_fs_context_validate(struct fs_context *fc); |
| 314 | |
| 315 | Called after all the options have been parsed to validate the collection |
| 316 | as a whole and to do any necessary allocation so that |
| 317 | security_sb_get_tree() and security_sb_reconfigure() are less likely to |
| 318 | fail. It should return 0 or a negative error code. |
| 319 | |
| 320 | In the case of reconfiguration, the target superblock will be accessible |
| 321 | via fc->root. |
| 322 | |
| 323 | (*) int security_sb_get_tree(struct fs_context *fc); |
| 324 | |
| 325 | Called during the mount procedure to verify that the specified superblock |
| 326 | is allowed to be mounted and to transfer the security data there. It |
| 327 | should return 0 or a negative error code. |
| 328 | |
| 329 | (*) void security_sb_reconfigure(struct fs_context *fc); |
| 330 | |
| 331 | Called to apply any reconfiguration to an LSM's context. It must not |
| 332 | fail. Error checking and resource allocation must be done in advance by |
| 333 | the parameter parsing and validation hooks. |
| 334 | |
| 335 | (*) int security_sb_mountpoint(struct fs_context *fc, struct path *mountpoint, |
| 336 | unsigned int mnt_flags); |
| 337 | |
| 338 | Called during the mount procedure to verify that the root dentry attached |
| 339 | to the context is permitted to be attached to the specified mountpoint. |
| 340 | It should return 0 on success or a negative error code on failure. |
| 341 | |
| 342 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 343 | ========================== |
| 344 | VFS FILESYSTEM CONTEXT API |
| 345 | ========================== |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 346 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 347 | There are four operations for creating a filesystem context and one for |
| 348 | destroying a context: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 349 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 350 | (*) struct fs_context *fs_context_for_mount( |
| 351 | struct file_system_type *fs_type, |
| 352 | unsigned int sb_flags); |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 353 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 354 | Allocate a filesystem context for the purpose of setting up a new mount, |
| 355 | whether that be with a new superblock or sharing an existing one. This |
| 356 | sets the superblock flags, initialises the security and calls |
| 357 | fs_type->init_fs_context() to initialise the filesystem private data. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 358 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 359 | fs_type specifies the filesystem type that will manage the context and |
| 360 | sb_flags presets the superblock flags stored therein. |
| 361 | |
| 362 | (*) struct fs_context *fs_context_for_reconfigure( |
| 363 | struct dentry *dentry, |
| 364 | unsigned int sb_flags, |
| 365 | unsigned int sb_flags_mask); |
| 366 | |
| 367 | Allocate a filesystem context for the purpose of reconfiguring an |
| 368 | existing superblock. dentry provides a reference to the superblock to be |
| 369 | configured. sb_flags and sb_flags_mask indicate which superblock flags |
| 370 | need changing and to what. |
| 371 | |
| 372 | (*) struct fs_context *fs_context_for_submount( |
| 373 | struct file_system_type *fs_type, |
| 374 | struct dentry *reference); |
| 375 | |
| 376 | Allocate a filesystem context for the purpose of creating a new mount for |
| 377 | an automount point or other derived superblock. fs_type specifies the |
| 378 | filesystem type that will manage the context and the reference dentry |
| 379 | supplies the parameters. Namespaces are propagated from the reference |
| 380 | dentry's superblock also. |
| 381 | |
| 382 | Note that it's not a requirement that the reference dentry be of the same |
| 383 | filesystem type as fs_type. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 384 | |
| 385 | (*) struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc); |
| 386 | |
| 387 | Duplicate a filesystem context, copying any options noted and duplicating |
| 388 | or additionally referencing any resources held therein. This is available |
| 389 | for use where a filesystem has to get a mount within a mount, such as NFS4 |
| 390 | does by internally mounting the root of the target server and then doing a |
| 391 | private pathwalk to the target directory. |
| 392 | |
| 393 | The purpose in the new context is inherited from the old one. |
| 394 | |
| 395 | (*) void put_fs_context(struct fs_context *fc); |
| 396 | |
| 397 | Destroy a filesystem context, releasing any resources it holds. This |
| 398 | calls the ->free() operation. This is intended to be called by anyone who |
| 399 | created a filesystem context. |
| 400 | |
| 401 | [!] filesystem contexts are not refcounted, so this causes unconditional |
| 402 | destruction. |
| 403 | |
| 404 | In all the above operations, apart from the put op, the return is a mount |
| 405 | context pointer or a negative error code. |
| 406 | |
| 407 | For the remaining operations, if an error occurs, a negative error code will be |
| 408 | returned. |
| 409 | |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 410 | (*) int vfs_parse_fs_param(struct fs_context *fc, |
| 411 | struct fs_parameter *param); |
| 412 | |
| 413 | Supply a single mount parameter to the filesystem context. This include |
| 414 | the specification of the source/device which is specified as the "source" |
| 415 | parameter (which may be specified multiple times if the filesystem |
| 416 | supports that). |
| 417 | |
| 418 | param specifies the parameter key name and the value. The parameter is |
| 419 | first checked to see if it corresponds to a standard mount flag (in which |
| 420 | case it is used to set an SB_xxx flag and consumed) or a security option |
| 421 | (in which case the LSM consumes it) before it is passed on to the |
| 422 | filesystem. |
| 423 | |
| 424 | The parameter value is typed and can be one of: |
| 425 | |
| 426 | fs_value_is_flag, Parameter not given a value. |
| 427 | fs_value_is_string, Value is a string |
| 428 | fs_value_is_blob, Value is a binary blob |
| 429 | fs_value_is_filename, Value is a filename* + dirfd |
| 430 | fs_value_is_filename_empty, Value is a filename* + dirfd + AT_EMPTY_PATH |
| 431 | fs_value_is_file, Value is an open file (file*) |
| 432 | |
| 433 | If there is a value, that value is stored in a union in the struct in one |
| 434 | of param->{string,blob,name,file}. Note that the function may steal and |
| 435 | clear the pointer, but then becomes responsible for disposing of the |
| 436 | object. |
| 437 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 438 | (*) int vfs_parse_fs_string(struct fs_context *fc, const char *key, |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 439 | const char *value, size_t v_size); |
| 440 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 441 | A wrapper around vfs_parse_fs_param() that copies the value string it is |
| 442 | passed. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 443 | |
| 444 | (*) int generic_parse_monolithic(struct fs_context *fc, void *data); |
| 445 | |
| 446 | Parse a sys_mount() data page, assuming the form to be a text list |
| 447 | consisting of key[=val] options separated by commas. Each item in the |
| 448 | list is passed to vfs_mount_option(). This is the default when the |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 449 | ->parse_monolithic() method is NULL. |
| 450 | |
| 451 | (*) int vfs_get_tree(struct fs_context *fc); |
| 452 | |
| 453 | Get or create the mountable root and superblock, using the parameters in |
| 454 | the filesystem context to select/configure the superblock. This invokes |
| 455 | the ->get_tree() method. |
| 456 | |
| 457 | (*) struct vfsmount *vfs_create_mount(struct fs_context *fc); |
| 458 | |
| 459 | Create a mount given the parameters in the specified filesystem context. |
| 460 | Note that this does not attach the mount to anything. |
| 461 | |
| 462 | |
| 463 | =========================== |
| 464 | SUPERBLOCK CREATION HELPERS |
| 465 | =========================== |
| 466 | |
| 467 | A number of VFS helpers are available for use by filesystems for the creation |
| 468 | or looking up of superblocks. |
| 469 | |
| 470 | (*) struct super_block * |
| 471 | sget_fc(struct fs_context *fc, |
| 472 | int (*test)(struct super_block *sb, struct fs_context *fc), |
| 473 | int (*set)(struct super_block *sb, struct fs_context *fc)); |
| 474 | |
| 475 | This is the core routine. If test is non-NULL, it searches for an |
| 476 | existing superblock matching the criteria held in the fs_context, using |
| 477 | the test function to match them. If no match is found, a new superblock |
| 478 | is created and the set function is called to set it up. |
| 479 | |
| 480 | Prior to the set function being called, fc->s_fs_info will be transferred |
| 481 | to sb->s_fs_info - and fc->s_fs_info will be cleared if set returns |
| 482 | success (ie. 0). |
| 483 | |
| 484 | The following helpers all wrap sget_fc(): |
| 485 | |
| 486 | (*) int vfs_get_super(struct fs_context *fc, |
| 487 | enum vfs_get_super_keying keying, |
| 488 | int (*fill_super)(struct super_block *sb, |
| 489 | struct fs_context *fc)) |
| 490 | |
| 491 | This creates/looks up a deviceless superblock. The keying indicates how |
| 492 | many superblocks of this type may exist and in what manner they may be |
| 493 | shared: |
| 494 | |
| 495 | (1) vfs_get_single_super |
| 496 | |
| 497 | Only one such superblock may exist in the system. Any further |
| 498 | attempt to get a new superblock gets this one (and any parameter |
| 499 | differences are ignored). |
| 500 | |
| 501 | (2) vfs_get_keyed_super |
| 502 | |
| 503 | Multiple superblocks of this type may exist and they're keyed on |
| 504 | their s_fs_info pointer (for example this may refer to a |
| 505 | namespace). |
| 506 | |
| 507 | (3) vfs_get_independent_super |
| 508 | |
| 509 | Multiple independent superblocks of this type may exist. This |
| 510 | function never matches an existing one and always creates a new |
| 511 | one. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 512 | |
| 513 | |
| 514 | ===================== |
| 515 | PARAMETER DESCRIPTION |
| 516 | ===================== |
| 517 | |
| 518 | Parameters are described using structures defined in linux/fs_parser.h. |
| 519 | There's a core description struct that links everything together: |
| 520 | |
| 521 | struct fs_parameter_description { |
| 522 | const char name[16]; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 523 | const struct fs_parameter_spec *specs; |
| 524 | const struct fs_parameter_enum *enums; |
| 525 | }; |
| 526 | |
| 527 | For example: |
| 528 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 529 | enum { |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 530 | Opt_autocell, |
| 531 | Opt_bar, |
| 532 | Opt_dyn, |
| 533 | Opt_foo, |
| 534 | Opt_source, |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 535 | }; |
| 536 | |
| 537 | static const struct fs_parameter_description afs_fs_parameters = { |
| 538 | .name = "kAFS", |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 539 | .specs = afs_param_specs, |
| 540 | .enums = afs_param_enums, |
| 541 | }; |
| 542 | |
| 543 | The members are as follows: |
| 544 | |
| 545 | (1) const char name[16]; |
| 546 | |
| 547 | The name to be used in error messages generated by the parse helper |
| 548 | functions. |
| 549 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 550 | (2) const struct fs_parameter_specification *specs; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 551 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 552 | Table of parameter specifications, terminated with a null entry, where the |
| 553 | entries are of type: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 554 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 555 | struct fs_parameter_spec { |
| 556 | const char *name; |
| 557 | u8 opt; |
| 558 | enum fs_parameter_type type:8; |
| 559 | unsigned short flags; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 560 | }; |
| 561 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 562 | The 'name' field is a string to match exactly to the parameter key (no |
| 563 | wildcards, patterns and no case-independence) and 'opt' is the value that |
| 564 | will be returned by the fs_parser() function in the case of a successful |
| 565 | match. |
| 566 | |
| 567 | The 'type' field indicates the desired value type and must be one of: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 568 | |
| 569 | TYPE NAME EXPECTED VALUE RESULT IN |
| 570 | ======================= ======================= ===================== |
| 571 | fs_param_is_flag No value n/a |
| 572 | fs_param_is_bool Boolean value result->boolean |
| 573 | fs_param_is_u32 32-bit unsigned int result->uint_32 |
| 574 | fs_param_is_u32_octal 32-bit octal int result->uint_32 |
| 575 | fs_param_is_u32_hex 32-bit hex int result->uint_32 |
| 576 | fs_param_is_s32 32-bit signed int result->int_32 |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 577 | fs_param_is_u64 64-bit unsigned int result->uint_64 |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 578 | fs_param_is_enum Enum value name result->uint_32 |
| 579 | fs_param_is_string Arbitrary string param->string |
| 580 | fs_param_is_blob Binary blob param->blob |
| 581 | fs_param_is_blockdev Blockdev path * Needs lookup |
| 582 | fs_param_is_path Path * Needs lookup |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 583 | fs_param_is_fd File descriptor result->int_32 |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 584 | |
| 585 | Note that if the value is of fs_param_is_bool type, fs_parse() will try |
| 586 | to match any string value against "0", "1", "no", "yes", "false", "true". |
| 587 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 588 | Each parameter can also be qualified with 'flags': |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 589 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 590 | fs_param_v_optional The value is optional |
| 591 | fs_param_neg_with_no result->negated set if key is prefixed with "no" |
| 592 | fs_param_neg_with_empty result->negated set if value is "" |
| 593 | fs_param_deprecated The parameter is deprecated. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 594 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 595 | These are wrapped with a number of convenience wrappers: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 596 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 597 | MACRO SPECIFIES |
| 598 | ======================= =============================================== |
| 599 | fsparam_flag() fs_param_is_flag |
| 600 | fsparam_flag_no() fs_param_is_flag, fs_param_neg_with_no |
| 601 | fsparam_bool() fs_param_is_bool |
| 602 | fsparam_u32() fs_param_is_u32 |
| 603 | fsparam_u32oct() fs_param_is_u32_octal |
| 604 | fsparam_u32hex() fs_param_is_u32_hex |
| 605 | fsparam_s32() fs_param_is_s32 |
| 606 | fsparam_u64() fs_param_is_u64 |
| 607 | fsparam_enum() fs_param_is_enum |
| 608 | fsparam_string() fs_param_is_string |
| 609 | fsparam_blob() fs_param_is_blob |
| 610 | fsparam_bdev() fs_param_is_blockdev |
| 611 | fsparam_path() fs_param_is_path |
| 612 | fsparam_fd() fs_param_is_fd |
| 613 | |
| 614 | all of which take two arguments, name string and option number - for |
| 615 | example: |
| 616 | |
| 617 | static const struct fs_parameter_spec afs_param_specs[] = { |
| 618 | fsparam_flag ("autocell", Opt_autocell), |
| 619 | fsparam_flag ("dyn", Opt_dyn), |
| 620 | fsparam_string ("source", Opt_source), |
| 621 | fsparam_flag_no ("foo", Opt_foo), |
| 622 | {} |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 623 | }; |
| 624 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 625 | An addition macro, __fsparam() is provided that takes an additional pair |
| 626 | of arguments to specify the type and the flags for anything that doesn't |
| 627 | match one of the above macros. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 628 | |
| 629 | (6) const struct fs_parameter_enum *enums; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 630 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 631 | Table of enum value names to integer mappings, terminated with a null |
| 632 | entry. This is of type: |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 633 | |
| 634 | struct fs_parameter_enum { |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 635 | u8 opt; |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 636 | char name[14]; |
| 637 | u8 value; |
| 638 | }; |
| 639 | |
| 640 | Where the array is an unsorted list of { parameter ID, name }-keyed |
| 641 | elements that indicate the value to map to, e.g.: |
| 642 | |
| 643 | static const struct fs_parameter_enum afs_param_enums[] = { |
| 644 | { Opt_bar, "x", 1}, |
| 645 | { Opt_bar, "y", 23}, |
| 646 | { Opt_bar, "z", 42}, |
| 647 | }; |
| 648 | |
| 649 | If a parameter of type fs_param_is_enum is encountered, fs_parse() will |
| 650 | try to look the value up in the enum table and the result will be stored |
| 651 | in the parse result. |
| 652 | |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 653 | The parser should be pointed to by the parser pointer in the file_system_type |
| 654 | struct as this will provide validation on registration (if |
| 655 | CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from |
| 656 | userspace using the fsinfo() syscall. |
| 657 | |
| 658 | |
| 659 | ========================== |
| 660 | PARAMETER HELPER FUNCTIONS |
| 661 | ========================== |
| 662 | |
| 663 | A number of helper functions are provided to help a filesystem or an LSM |
| 664 | process the parameters it is given. |
| 665 | |
| 666 | (*) int lookup_constant(const struct constant_table tbl[], |
| 667 | const char *name, int not_found); |
| 668 | |
| 669 | Look up a constant by name in a table of name -> integer mappings. The |
| 670 | table is an array of elements of the following type: |
| 671 | |
| 672 | struct constant_table { |
| 673 | const char *name; |
| 674 | int value; |
| 675 | }; |
| 676 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 677 | If a match is found, the corresponding value is returned. If a match |
| 678 | isn't found, the not_found value is returned instead. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 679 | |
| 680 | (*) bool validate_constant_table(const struct constant_table *tbl, |
| 681 | size_t tbl_size, |
| 682 | int low, int high, int special); |
| 683 | |
| 684 | Validate a constant table. Checks that all the elements are appropriately |
| 685 | ordered, that there are no duplicates and that the values are between low |
| 686 | and high inclusive, though provision is made for one allowable special |
| 687 | value outside of that range. If no special value is required, special |
| 688 | should just be set to lie inside the low-to-high range. |
| 689 | |
| 690 | If all is good, true is returned. If the table is invalid, errors are |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 691 | logged to dmesg and false is returned. |
| 692 | |
| 693 | (*) bool fs_validate_description(const struct fs_parameter_description *desc); |
| 694 | |
| 695 | This performs some validation checks on a parameter description. It |
| 696 | returns true if the description is good and false if it is not. It will |
| 697 | log errors to dmesg if validation fails. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 698 | |
| 699 | (*) int fs_parse(struct fs_context *fc, |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 700 | const struct fs_parameter_description *desc, |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 701 | struct fs_parameter *param, |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 702 | struct fs_parse_result *result); |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 703 | |
| 704 | This is the main interpreter of parameters. It uses the parameter |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 705 | description to look up a parameter by key name and to convert that to an |
| 706 | option number (which it returns). |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 707 | |
| 708 | If successful, and if the parameter type indicates the result is a |
| 709 | boolean, integer or enum type, the value is converted by this function and |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 710 | the result stored in result->{boolean,int_32,uint_32,uint_64}. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 711 | |
| 712 | If a match isn't initially made, the key is prefixed with "no" and no |
| 713 | value is present then an attempt will be made to look up the key with the |
| 714 | prefix removed. If this matches a parameter for which the type has flag |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 715 | fs_param_neg_with_no set, then a match will be made and result->negated |
| 716 | will be set to true. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 717 | |
David Howells | 7d6ab82 | 2019-03-27 22:53:31 +0000 | [diff] [blame] | 718 | If the parameter isn't matched, -ENOPARAM will be returned; if the |
| 719 | parameter is matched, but the value is erroneous, -EINVAL will be |
| 720 | returned; otherwise the parameter's option number will be returned. |
David Howells | 5fe1890 | 2018-11-01 23:07:26 +0000 | [diff] [blame] | 721 | |
| 722 | (*) int fs_lookup_param(struct fs_context *fc, |
| 723 | struct fs_parameter *value, |
| 724 | bool want_bdev, |
| 725 | struct path *_path); |
| 726 | |
| 727 | This takes a parameter that carries a string or filename type and attempts |
| 728 | to do a path lookup on it. If the parameter expects a blockdev, a check |
| 729 | is made that the inode actually represents one. |
| 730 | |
| 731 | Returns 0 if successful and *_path will be set; returns a negative error |
| 732 | code if not. |