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