blob: 00ff0cfccfa71cdce0d02ddd8608cf962ee99308 [file] [log] [blame]
David Howells5fe18902018-11-01 23:07:26 +00001 ====================
2 FILESYSTEM MOUNT API
3 ====================
4
5CONTENTS
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 Howells7d6ab822019-03-27 22:53:31 +000015 (5) VFS filesystem context API.
David Howells5fe18902018-11-01 23:07:26 +000016
David Howells7d6ab822019-03-27 22:53:31 +000017 (6) Superblock creation helpers.
David Howells5fe18902018-11-01 23:07:26 +000018
David Howells7d6ab822019-03-27 22:53:31 +000019 (7) Parameter description.
20
21 (8) Parameter helper functions.
David Howells5fe18902018-11-01 23:07:26 +000022
23
24========
25OVERVIEW
26========
27
28The 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 Howells7d6ab822019-03-27 22:53:31 +000046To support this, the file_system_type struct gains two new fields:
David Howells5fe18902018-11-01 23:07:26 +000047
48 int (*init_fs_context)(struct fs_context *fc);
David Howells7d6ab822019-03-27 22:53:31 +000049 const struct fs_parameter_description *parameters;
David Howells5fe18902018-11-01 23:07:26 +000050
David Howells7d6ab822019-03-27 22:53:31 +000051The first is invoked to set up the filesystem-specific parts of a filesystem
52context, including the additional space, and the second points to the
53parameter description for validation at registration time and querying by a
54future system call.
David Howells5fe18902018-11-01 23:07:26 +000055
56Note that security initialisation is done *after* the filesystem is called so
57that the namespaces may be adjusted first.
58
59
60======================
61THE FILESYSTEM CONTEXT
62======================
63
64The creation and reconfiguration of a superblock is governed by a filesystem
65context. 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 Howells7d6ab822019-03-27 22:53:31 +000081 unsigned int s_iflags;
82 unsigned int lsm_flags;
David Howells5fe18902018-11-01 23:07:26 +000083 enum fs_context_purpose purpose:8;
David Howells5fe18902018-11-01 23:07:26 +000084 ...
85 };
86
87The 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 Howells7d6ab822019-03-27 22:53:31 +0000149 (*) unsigned int s_iflags
150
151 These will be bitwise-OR'd with s->s_iflags when a superblock is created.
152
David Howells5fe18902018-11-01 23:07:26 +0000153 (*) 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 Howells5fe18902018-11-01 23:07:26 +0000162The mount context is created by calling vfs_new_fs_context() or
163vfs_dup_fs_context() and is destroyed with put_fs_context(). Note that the
164structure is not refcounted.
165
166VFS, security and filesystem mount options are set individually with
167vfs_parse_mount_option(). Options provided by the old mount(2) system call as
168a page of data can be parsed with generic_parse_monolithic().
169
170When mounting, the filesystem is allowed to take data from any of the pointers
171and attach it to the superblock (or whatever), provided it clears the pointer
172in the mount context.
173
174The filesystem is also allowed to allocate resources and pin them with the
175mount context. For instance, NFS might pin the appropriate protocol version
176module.
177
178
179=================================
180THE FILESYSTEM CONTEXT OPERATIONS
181=================================
182
183The 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
195These operations are invoked by the various stages of the mount procedure to
196manage 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===========================
266FILESYSTEM CONTEXT SECURITY
267===========================
268
269The filesystem context contains a security pointer that the LSMs can use for
270building up a security context for the superblock to be mounted. There are a
271number 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 Howells7d6ab822019-03-27 22:53:31 +0000343==========================
344VFS FILESYSTEM CONTEXT API
345==========================
David Howells5fe18902018-11-01 23:07:26 +0000346
David Howells7d6ab822019-03-27 22:53:31 +0000347There are four operations for creating a filesystem context and one for
348destroying a context:
David Howells5fe18902018-11-01 23:07:26 +0000349
David Howells7d6ab822019-03-27 22:53:31 +0000350 (*) struct fs_context *fs_context_for_mount(
351 struct file_system_type *fs_type,
352 unsigned int sb_flags);
David Howells5fe18902018-11-01 23:07:26 +0000353
David Howells7d6ab822019-03-27 22:53:31 +0000354 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 Howells5fe18902018-11-01 23:07:26 +0000358
David Howells7d6ab822019-03-27 22:53:31 +0000359 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 Howells5fe18902018-11-01 23:07:26 +0000384
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
404In all the above operations, apart from the put op, the return is a mount
405context pointer or a negative error code.
406
407For the remaining operations, if an error occurs, a negative error code will be
408returned.
409
David Howells5fe18902018-11-01 23:07:26 +0000410 (*) 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 Howells7d6ab822019-03-27 22:53:31 +0000438 (*) int vfs_parse_fs_string(struct fs_context *fc, const char *key,
David Howells5fe18902018-11-01 23:07:26 +0000439 const char *value, size_t v_size);
440
David Howells7d6ab822019-03-27 22:53:31 +0000441 A wrapper around vfs_parse_fs_param() that copies the value string it is
442 passed.
David Howells5fe18902018-11-01 23:07:26 +0000443
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 Howells7d6ab822019-03-27 22:53:31 +0000449 ->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===========================
464SUPERBLOCK CREATION HELPERS
465===========================
466
467A number of VFS helpers are available for use by filesystems for the creation
468or 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
484The 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 Howells5fe18902018-11-01 23:07:26 +0000512
513
514=====================
515PARAMETER DESCRIPTION
516=====================
517
518Parameters are described using structures defined in linux/fs_parser.h.
519There's a core description struct that links everything together:
520
521 struct fs_parameter_description {
522 const char name[16];
David Howells5fe18902018-11-01 23:07:26 +0000523 const struct fs_parameter_spec *specs;
524 const struct fs_parameter_enum *enums;
525 };
526
527For example:
528
David Howells7d6ab822019-03-27 22:53:31 +0000529 enum {
David Howells5fe18902018-11-01 23:07:26 +0000530 Opt_autocell,
531 Opt_bar,
532 Opt_dyn,
533 Opt_foo,
534 Opt_source,
David Howells5fe18902018-11-01 23:07:26 +0000535 };
536
537 static const struct fs_parameter_description afs_fs_parameters = {
538 .name = "kAFS",
David Howells5fe18902018-11-01 23:07:26 +0000539 .specs = afs_param_specs,
540 .enums = afs_param_enums,
541 };
542
543The 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 Howells7d6ab822019-03-27 22:53:31 +0000550 (2) const struct fs_parameter_specification *specs;
David Howells5fe18902018-11-01 23:07:26 +0000551
David Howells7d6ab822019-03-27 22:53:31 +0000552 Table of parameter specifications, terminated with a null entry, where the
553 entries are of type:
David Howells5fe18902018-11-01 23:07:26 +0000554
David Howells7d6ab822019-03-27 22:53:31 +0000555 struct fs_parameter_spec {
556 const char *name;
557 u8 opt;
558 enum fs_parameter_type type:8;
559 unsigned short flags;
David Howells5fe18902018-11-01 23:07:26 +0000560 };
561
David Howells7d6ab822019-03-27 22:53:31 +0000562 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 Howells5fe18902018-11-01 23:07:26 +0000568
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 Howells7d6ab822019-03-27 22:53:31 +0000577 fs_param_is_u64 64-bit unsigned int result->uint_64
David Howells5fe18902018-11-01 23:07:26 +0000578 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 Howells7d6ab822019-03-27 22:53:31 +0000583 fs_param_is_fd File descriptor result->int_32
David Howells5fe18902018-11-01 23:07:26 +0000584
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 Howells7d6ab822019-03-27 22:53:31 +0000588 Each parameter can also be qualified with 'flags':
David Howells5fe18902018-11-01 23:07:26 +0000589
David Howells7d6ab822019-03-27 22:53:31 +0000590 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 Howells5fe18902018-11-01 23:07:26 +0000594
David Howells7d6ab822019-03-27 22:53:31 +0000595 These are wrapped with a number of convenience wrappers:
David Howells5fe18902018-11-01 23:07:26 +0000596
David Howells7d6ab822019-03-27 22:53:31 +0000597 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 Howells5fe18902018-11-01 23:07:26 +0000623 };
624
David Howells7d6ab822019-03-27 22:53:31 +0000625 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 Howells5fe18902018-11-01 23:07:26 +0000628
629 (6) const struct fs_parameter_enum *enums;
David Howells5fe18902018-11-01 23:07:26 +0000630
David Howells7d6ab822019-03-27 22:53:31 +0000631 Table of enum value names to integer mappings, terminated with a null
632 entry. This is of type:
David Howells5fe18902018-11-01 23:07:26 +0000633
634 struct fs_parameter_enum {
David Howells7d6ab822019-03-27 22:53:31 +0000635 u8 opt;
David Howells5fe18902018-11-01 23:07:26 +0000636 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 Howells5fe18902018-11-01 23:07:26 +0000653The parser should be pointed to by the parser pointer in the file_system_type
654struct as this will provide validation on registration (if
655CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
656userspace using the fsinfo() syscall.
657
658
659==========================
660PARAMETER HELPER FUNCTIONS
661==========================
662
663A number of helper functions are provided to help a filesystem or an LSM
664process 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 Howells7d6ab822019-03-27 22:53:31 +0000677 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 Howells5fe18902018-11-01 23:07:26 +0000679
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 Howells7d6ab822019-03-27 22:53:31 +0000691 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 Howells5fe18902018-11-01 23:07:26 +0000698
699 (*) int fs_parse(struct fs_context *fc,
David Howells7d6ab822019-03-27 22:53:31 +0000700 const struct fs_parameter_description *desc,
David Howells5fe18902018-11-01 23:07:26 +0000701 struct fs_parameter *param,
David Howells7d6ab822019-03-27 22:53:31 +0000702 struct fs_parse_result *result);
David Howells5fe18902018-11-01 23:07:26 +0000703
704 This is the main interpreter of parameters. It uses the parameter
David Howells7d6ab822019-03-27 22:53:31 +0000705 description to look up a parameter by key name and to convert that to an
706 option number (which it returns).
David Howells5fe18902018-11-01 23:07:26 +0000707
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 Howells7d6ab822019-03-27 22:53:31 +0000710 the result stored in result->{boolean,int_32,uint_32,uint_64}.
David Howells5fe18902018-11-01 23:07:26 +0000711
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 Howells7d6ab822019-03-27 22:53:31 +0000715 fs_param_neg_with_no set, then a match will be made and result->negated
716 will be set to true.
David Howells5fe18902018-11-01 23:07:26 +0000717
David Howells7d6ab822019-03-27 22:53:31 +0000718 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 Howells5fe18902018-11-01 23:07:26 +0000721
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.