Filesystem Mount API

다단계 mount 절차 개요

이 GPL-2.0 문서는 Filesystem Mount API를 여덟 부분으로 설명합니다. Overview, filesystem context, context operation, security, VFS context API, superblock helper, parameter description, parameter helper function 순서입니다.

새 mount 생성은 다단계 과정입니다. 먼저 filesystem context를 만들고, userspace에서 보통 개별적으로 전달되는 parameter를 parse해 context에 붙입니다. Legacy binary parameter도 처리할 수 있습니다. 그다음 context 전체를 검증·전처리하고, superblock과 mount 가능한 root를 얻거나 생성한 뒤 실제 mount를 수행합니다.

오류가 있으면 context에 연결된 error message를 반환하고 마지막에 context를 파괴합니다. 이 모델은 option parsing, 보안 검증, superblock 선택, mount object 생성을 서로 다른 단계로 분리합니다.

이를 지원하려고 `struct file_system_type`에는 `init_fs_context(struct fs_context *fc)`와 `parameters`가 추가됩니다. 첫 필드는 추가 공간을 포함한 filesystem-specific context 부분을 설정하고, 둘째는 등록 시 검증 및 향후 system call의 조회에 쓸 parameter description을 가리킵니다.

Security 초기화는 filesystem callback 뒤에 수행됩니다. Filesystem이 먼저 namespace를 조정할 수 있어야 하기 때문입니다.

.. SPDX-License-Identifier: GPL-2.0

====================
Filesystem Mount API
====================

.. CONTENTS

 (1) Overview.

 (2) The filesystem context.

 (3) The filesystem context operations.

 (4) Filesystem context security.

 (5) VFS filesystem context API.

 (6) Superblock creation helpers.

 (7) Parameter description.

 (8) Parameter helper functions.


Overview
========

The creation of new mounts is now to be done in a multistep process:

 (1) Create a filesystem context.

 (2) Parse the parameters and attach them to the context.  Parameters are
     expected to be passed individually from userspace, though legacy binary
     parameters can also be handled.

 (3) Validate and pre-process the context.

 (4) Get or create a superblock and mountable root.

 (5) Perform the mount.

 (6) Return an error message attached to the context.

 (7) Destroy the context.

To support this, the file_system_type struct gains two new fields::

        int (*init_fs_context)(struct fs_context *fc);
        const struct fs_parameter_description *parameters;

The first is invoked to set up the filesystem-specific parts of a filesystem
context, including the additional space, and the second points to the
parameter description for validation at registration time and querying by a
future system call.

Note that security initialisation is done *after* the filesystem is called so
that the namespaces may be adjusted first.


The Filesystem context

fs_context 핵심 포인터와 namespace

Superblock 생성과 reconfiguration은 `struct fs_context`가 관장합니다. `ops`는 context에서 수행할 operation table이며 `file_system_type::init_fs_context()`가 반드시 설정해야 합니다. `fs_type`은 생성 또는 재구성 중인 filesystem의 `file_system_type`을 가리키고 type owner reference를 유지합니다.

`fs_private`는 파일시스템 전용 데이터 포인터로, 파일시스템이 parse한 option을 저장하는 곳입니다. `root`는 mount 가능한 tree의 root와 간접적으로 그 superblock을 가리키며 `->get_tree()`가 채웁니다. `root`가 설정되면 `root->d_sb`의 active reference도 보유해야 합니다.

`user_ns`와 `net_ns`는 호출 process가 사용하는 namespace의 일부이며 각각 reference를 유지합니다. Automount에서 parent mount의 superblock을 따르는 경우처럼 다른 source를 반영하기 위해 filesystem이 구독 namespace를 교체할 수 있습니다.

`cred`는 mounter의 credential이며 reference가 유지됩니다. 이 구간의 구조체 원문에는 이후 설명할 `source`, `subtype`, `security`, `s_fs_info`, flag, `purpose` 필드도 함께 선언되어 있습니다.

======================

The creation and reconfiguration of a superblock is governed by a filesystem
context.  This is represented by the fs_context structure::

        struct fs_context {
                const struct fs_context_operations *ops;
                struct file_system_type *fs_type;
                void                        *fs_private;
                struct dentry                *root;
                struct user_namespace        *user_ns;
                struct net                *net_ns;
                const struct cred        *cred;
                char                        *source;
                char                        *subtype;
                void                        *security;
                void                        *s_fs_info;
                unsigned int                sb_flags;
                unsigned int                sb_flags_mask;
                unsigned int                s_iflags;
                enum fs_context_purpose        purpose:8;
                ...
        };

The fs_context fields are as follows:

   * ::

       const struct fs_context_operations *ops

     These are operations that can be done on a filesystem context (see
     below).  This must be set by the ->init_fs_context() file_system_type
     operation.

   * ::

       struct file_system_type *fs_type

     A pointer to the file_system_type of the filesystem that is being
     constructed or reconfigured.  This retains a reference on the type owner.

   * ::

       void *fs_private

     A pointer to the file system's private data.  This is where the filesystem
     will need to store any options it parses.

   * ::

       struct dentry *root

     A pointer to the root of the mountable tree (and indirectly, the
     superblock thereof).  This is filled in by the ->get_tree() op.  If this
     is set, an active reference on root->d_sb must also be held.

   * ::

       struct user_namespace *user_ns
       struct net *net_ns

     There are a subset of the namespaces in use by the invoking process.  They
     retain references on each namespace.  The subscribed namespaces may be
     replaced by the filesystem to reflect other sources, such as the parent
     mount superblock on an automount.

source·security·flag·purpose와 context 수명주기

`source`는 mount source를 지정합니다. `/dev/sda1` 같은 block device일 수도 있고 NFS가 사용하는 `host:/path` 같은 값일 수도 있습니다. `subtype`은 `/proc/mounts`에 표시되는 type을 한정하기 위해 덧붙이는 문자열이며 FUSE가 사용합니다.

`security`는 LSM이 mount할 superblock의 security data를 쌓는 위치입니다. `s_fs_info`는 새 superblock에 제안할 `s_fs_info`이고 `sget_fc()`가 superblock으로 옮깁니다. Superblock을 서로 구별하는 key로 사용할 수 있습니다.

`sb_flags`와 `sb_flags_mask`는 `super_block::s_flags`에서 설정하거나 지울 `SB_*` bit를 나타냅니다. `s_iflags`는 superblock 생성 시 `s->s_iflags`에 bitwise OR 됩니다.

`purpose`는 context 목적을 표시합니다. `FS_CONTEXT_FOR_MOUNT`는 명시적 mount용 새 superblock, `FS_CONTEXT_FOR_SUBMOUNT`는 기존 mount의 새 automatic submount, `FS_CONTEXT_FOR_RECONFIGURE`는 기존 mount 변경입니다.

Mount context는 `vfs_new_fs_context()` 또는 `vfs_dup_fs_context()`로 만들고 `put_fs_context()`로 파괴합니다. 구조체 자체는 refcounted가 아닙니다. VFS·security·filesystem option은 `vfs_parse_mount_option()`으로 하나씩 설정하며 old `mount(2)`의 data page는 `generic_parse_monolithic()`으로 parse할 수 있습니다.

Mount 중 파일시스템은 context의 pointer가 가리키는 데이터를 superblock 등으로 가져갈 수 있지만 반드시 context의 해당 pointer를 clear해야 합니다. Context에 resource를 할당하고 pin할 수도 있습니다. 예를 들어 NFS는 적절한 protocol version module을 pin할 수 있습니다.

   * ::

       const struct cred *cred

     The mounter's credentials.  This retains a reference on the credentials.

   * ::

       char *source

     This specifies the source.  It may be a block device (e.g. /dev/sda1) or
     something more exotic, such as the "host:/path" that NFS desires.

   * ::

       char *subtype

     This is a string to be added to the type displayed in /proc/mounts to
     qualify it (used by FUSE).  This is available for the filesystem to set if
     desired.

   * ::

       void *security

     A place for the LSMs to hang their security data for the superblock.  The
     relevant security operations are described below.

   * ::

       void *s_fs_info

     The proposed s_fs_info for a new superblock, set in the superblock by
     sget_fc().  This can be used to distinguish superblocks.

   * ::

       unsigned int sb_flags
       unsigned int sb_flags_mask

     Which bits SB_* flags are to be set/cleared in super_block::s_flags.

   * ::

       unsigned int s_iflags

     These will be bitwise-OR'd with s->s_iflags when a superblock is created.

   * ::

       enum fs_context_purpose

     This indicates the purpose for which the context is intended.  The
     available values are:

        ==========================        ======================================
        FS_CONTEXT_FOR_MOUNT,                New superblock for explicit mount
        FS_CONTEXT_FOR_SUBMOUNT                New automatic submount of extant mount
        FS_CONTEXT_FOR_RECONFIGURE        Change an existing mount
        ==========================        ======================================

The mount context is created by calling vfs_new_fs_context() or
vfs_dup_fs_context() and is destroyed with put_fs_context().  Note that the
structure is not refcounted.

VFS, security and filesystem mount options are set individually with
vfs_parse_mount_option().  Options provided by the old mount(2) system call as
a page of data can be parsed with generic_parse_monolithic().

When mounting, the filesystem is allowed to take data from any of the pointers
and attach it to the superblock (or whatever), provided it clears the pointer
in the mount context.

The filesystem is also allowed to allocate resources and pin them with the
mount context.  For instance, NFS might pin the appropriate protocol version
module.


The Filesystem Context Operations

fs_context_operations의 free·dup·parse_param

`struct fs_context_operations`는 `free`, `dup`, `parse_param`, `parse_monolithic`, `get_tree`, `reconfigure` callback을 제공합니다. Mount procedure의 각 단계가 이 table을 호출하여 filesystem context를 관리합니다.

`free(fc)`는 context 파괴 시 filesystem-specific 부분을 정리합니다. `->get_tree()`가 일부 데이터를 떼어내고 pointer를 NULL로 만들었을 수 있으므로 부분적으로 비어 있는 context를 안전하게 처리해야 합니다.

`dup(fc, src_fc)`는 context 복제 시 filesystem-private data를 복제하며 실패하면 error를 반환할 수 있습니다. 실패 직후에도 `put_fs_context()`가 호출되므로 `->dup()`은 실패 경로에서도 새 context의 private data가 `->free()`에 안전한 상태가 되도록 만들어야 합니다.

`parse_param(fc, param)`은 parameter 하나를 context에 추가할 때 호출됩니다. `param`은 key name과 선택적 value object를 가리킵니다. VFS option과 security option은 미리 걸러져 각각 `fc->sb_flags`, `fc->security`가 갱신된 상태입니다.

Parameter는 `fs_parse()`와 `fs_lookup_param()`으로 parse할 수 있습니다. Source도 이름이 `source`인 parameter로 전달됩니다. 성공 시 0, 실패 시 negative error code를 반환합니다.

=================================

The filesystem context points to a table of operations::

        struct fs_context_operations {
                void (*free)(struct fs_context *fc);
                int (*dup)(struct fs_context *fc, struct fs_context *src_fc);
                int (*parse_param)(struct fs_context *fc,
                                   struct fs_parameter *param);
                int (*parse_monolithic)(struct fs_context *fc, void *data);
                int (*get_tree)(struct fs_context *fc);
                int (*reconfigure)(struct fs_context *fc);
        };

These operations are invoked by the various stages of the mount procedure to
manage the filesystem context.  They are as follows:

   * ::

        void (*free)(struct fs_context *fc);

     Called to clean up the filesystem-specific part of the filesystem context
     when the context is destroyed.  It should be aware that parts of the
     context may have been removed and NULL'd out by ->get_tree().

   * ::

        int (*dup)(struct fs_context *fc, struct fs_context *src_fc);

     Called when a filesystem context has been duplicated to duplicate the
     filesystem-private data.  An error may be returned to indicate failure to
     do this.

     .. Warning::

         Note that even if this fails, put_fs_context() will be called
         immediately thereafter, so ->dup() *must* make the
         filesystem-private data safe for ->free().

   * ::

        int (*parse_param)(struct fs_context *fc,
                           struct fs_parameter *param);

     Called when a parameter is being added to the filesystem context.  param
     points to the key name and maybe a value object.  VFS-specific options
     will have been weeded out and fc->sb_flags updated in the context.
     Security options will also have been weeded out and fc->security updated.

     The parameter can be parsed with fs_parse() and fs_lookup_param().  Note
     that the source(s) are presented as parameters named "source".

     If successful, 0 should be returned or a negative error code otherwise.

monolithic parsing, get_tree, reconfigure

`parse_monolithic(fc, data)`는 `mount(2)`가 data page 전체를 한 번에 전달할 때 호출됩니다. 내용이 comma로 구분된 `key[=val]` 목록이라면 callback을 NULL로 둘 수 있습니다. 반환 규칙은 `->parse_param()`과 같습니다.

NFS처럼 먼저 data를 검사해야 하는 파일시스템도 결과가 표준 key-value 목록이면 `generic_parse_monolithic()`으로 넘길 수 있습니다.

`get_tree(fc)`는 context 정보를 사용해 mount 가능한 root와 superblock을 얻거나 생성합니다. 원하는 resource를 context에서 분리해 생성한 superblock으로 이전할 수 있습니다. 성공 시 `fc->root`를 mountable root로 설정하고 0을 반환하며 실패 시 negative error를 반환합니다. Userspace-driven context의 phase는 특정 context에서 한 번만 호출되도록 제한됩니다.

`reconfigure(fc)`는 context에 저장된 정보로 기존 superblock 설정을 변경합니다. Resource를 context에서 superblock으로 이전할 수 있고 대상 superblock은 `fc->root->d_sb`에서 찾습니다. 성공 시 0, 실패 시 negative error를 반환합니다. 이 callback은 `remount_fs`를 대체하기 위한 것입니다.

   * ::

        int (*parse_monolithic)(struct fs_context *fc, void *data);

     Called when the mount(2) system call is invoked to pass the entire data
     page in one go.  If this is expected to be just a list of "key[=val]"
     items separated by commas, then this may be set to NULL.

     The return value is as for ->parse_param().

     If the filesystem (e.g. NFS) needs to examine the data first and then
     finds it's the standard key-val list then it may pass it off to
     generic_parse_monolithic().

   * ::

        int (*get_tree)(struct fs_context *fc);

     Called to get or create the mountable root and superblock, using the
     information stored in the filesystem context (reconfiguration goes via a
     different vector).  It may detach any resources it desires from the
     filesystem context and transfer them to the superblock it creates.

     On success it should set fc->root to the mountable root and return 0.  In
     the case of an error, it should return a negative error code.

     The phase on a userspace-driven context will be set to only allow this to
     be called once on any particular context.

   * ::

        int (*reconfigure)(struct fs_context *fc);

     Called to effect reconfiguration of a superblock using information stored
     in the filesystem context.  It may detach any resources it desires from
     the filesystem context and transfer them to the superblock.  The
     superblock can be found from fc->root->d_sb.

     On success it should return 0.  In the case of an error, it should return
     a negative error code.

     .. Note:: reconfigure is intended as a replacement for remount_fs.

LSM context 생성·복제·parameter 처리

Filesystem context의 `security` pointer는 LSM이 mount할 superblock의 security context를 구성하는 데 사용합니다.

`security_fs_context_alloc(fc, reference)`는 NULL로 미리 설정된 `fc->security`를 초기화하고 필요한 resource를 할당합니다. 성공 시 0, 실패 시 negative error를 반환합니다. Reconfigure이면 `reference`는 대상 superblock의 root dentry이고, submount이면 automount point이므로 둘 다 non-NULL입니다.

`security_fs_context_dup(fc, src_fc)`도 새 context의 NULL security field를 초기화하고 resource를 할당하되 원본 `src_fc`를 참고할 수 있습니다. 성공 시 0, 실패 시 negative error입니다.

`security_fs_context_free(fc)`는 `fc->security`에 연결된 것을 정리합니다. `get_tree` 중 내용이 superblock으로 이전되고 pointer가 clear되었을 수 있음을 고려해야 합니다.

`security_fs_context_parse_param(fc, param)`은 source를 포함한 각 mount parameter마다 호출됩니다. 0은 parameter를 filesystem에 넘기라는 뜻이고, 1은 버리라는 뜻이며, error는 거부를 뜻합니다.

문자열 value는 수정할 수 있고 value pointer를 NULL로 만들면 훔쳐갈 수 있습니다. 훔쳤다면 filesystem에 전달되지 않도록 반드시 1을 반환해야 합니다.

Filesystem context Security
===========================

The filesystem context contains a security pointer that the LSMs can use for
building up a security context for the superblock to be mounted.  There are a
number of operations used by the new mount code for this purpose:

   * ::

        int security_fs_context_alloc(struct fs_context *fc,
                                      struct dentry *reference);

     Called to initialise fc->security (which is preset to NULL) and allocate
     any resources needed.  It should return 0 on success or a negative error
     code on failure.

     reference will be non-NULL if the context is being created for superblock
     reconfiguration (FS_CONTEXT_FOR_RECONFIGURE) in which case it indicates
     the root dentry of the superblock to be reconfigured.  It will also be
     non-NULL in the case of a submount (FS_CONTEXT_FOR_SUBMOUNT) in which case
     it indicates the automount point.

   * ::

        int security_fs_context_dup(struct fs_context *fc,
                                    struct fs_context *src_fc);

     Called to initialise fc->security (which is preset to NULL) and allocate
     any resources needed.  The original filesystem context is pointed to by
     src_fc and may be used for reference.  It should return 0 on success or a
     negative error code on failure.

   * ::

        void security_fs_context_free(struct fs_context *fc);

     Called to clean up anything attached to fc->security.  Note that the
     contents may have been transferred to a superblock and the pointer cleared
     during get_tree.

   * ::

        int security_fs_context_parse_param(struct fs_context *fc,
                                            struct fs_parameter *param);

     Called for each mount parameter, including the source.  The arguments are
     as for the ->parse_param() method.  It should return 0 to indicate that
     the parameter should be passed on to the filesystem, 1 to indicate that
     the parameter should be discarded or an error to indicate that the
     parameter should be rejected.

     The value pointed to by param may be modified (if a string) or stolen
     (provided the value pointer is NULL'd out).  If it is stolen, 1 must be
     returned to prevent it being passed to the filesystem.

Security validation과 superblock hook

`security_fs_context_validate(fc)`는 모든 option을 parse한 뒤 collection 전체를 검증하고 필요한 resource를 미리 할당합니다. 그러면 `security_sb_get_tree()`와 `security_sb_reconfigure()`가 실패할 가능성을 줄일 수 있습니다. 성공 시 0, 실패 시 negative error를 반환합니다. Reconfigure 대상은 `fc->root`로 접근할 수 있습니다.

`security_sb_get_tree(fc)`는 mount procedure에서 지정 superblock의 mount가 허용되는지 확인하고 security data를 그곳으로 이전합니다. 성공 시 0 또는 negative error를 반환합니다.

`security_sb_reconfigure(fc)`는 LSM context에 reconfiguration을 적용하며 실패해서는 안 됩니다. Error checking과 resource allocation은 parameter parsing·validation hook에서 미리 끝내야 합니다.

`security_sb_mountpoint(fc, mountpoint, mnt_flags)`는 context의 root dentry를 지정 mountpoint에 붙여도 되는지 검증합니다. 성공 시 0, 실패 시 negative error를 반환합니다.

   * ::

        int security_fs_context_validate(struct fs_context *fc);

     Called after all the options have been parsed to validate the collection
     as a whole and to do any necessary allocation so that
     security_sb_get_tree() and security_sb_reconfigure() are less likely to
     fail.  It should return 0 or a negative error code.

     In the case of reconfiguration, the target superblock will be accessible
     via fc->root.

   * ::

        int security_sb_get_tree(struct fs_context *fc);

     Called during the mount procedure to verify that the specified superblock
     is allowed to be mounted and to transfer the security data there.  It
     should return 0 or a negative error code.

   * ::

        void security_sb_reconfigure(struct fs_context *fc);

     Called to apply any reconfiguration to an LSM's context.  It must not
     fail.  Error checking and resource allocation must be done in advance by
     the parameter parsing and validation hooks.

   * ::

        int security_sb_mountpoint(struct fs_context *fc,
                                   struct path *mountpoint,
                                   unsigned int mnt_flags);

     Called during the mount procedure to verify that the root dentry attached
     to the context is permitted to be attached to the specified mountpoint.
     It should return 0 on success or a negative error code on failure.

VFS context 생성·복제·파괴 API

VFS는 filesystem context 생성 operation 네 개와 파괴 operation 하나를 제공합니다.

`fs_context_for_mount(fs_type, sb_flags)`는 새 superblock을 만들거나 기존 것을 공유하는 새 mount context를 할당합니다. Superblock flag를 설정하고 security를 초기화하며 `fs_type->init_fs_context()`로 filesystem private data를 초기화합니다.

`fs_context_for_reconfigure(dentry, sb_flags, sb_flags_mask)`는 기존 superblock 재설정 context를 할당합니다. `dentry`가 대상 superblock reference이고 두 flag 인수가 어떤 superblock flag를 어떤 값으로 바꿀지 나타냅니다.

`fs_context_for_submount(fs_type, reference)`는 automount point 또는 다른 파생 superblock의 새 mount context를 할당합니다. Reference dentry가 parameter를 제공하고 그 superblock에서 namespace도 전달됩니다. Reference dentry의 filesystem type이 `fs_type`과 같을 필요는 없습니다.

`vfs_dup_fs_context(src_fc)`는 기록된 option을 복사하고 보유 resource를 복제하거나 reference를 추가합니다. NFS4가 target server root를 내부 mount한 뒤 target directory로 private pathwalk하는 것처럼 mount 안에서 mount가 필요한 경우에 사용합니다. 새 context의 purpose는 원본에서 상속됩니다.

`put_fs_context(fc)`는 resource를 해제하고 `->free()`를 호출하여 context를 파괴합니다. Context를 만든 모든 호출자가 사용해야 합니다. Filesystem context는 refcounted가 아니므로 이 호출은 조건 없이 파괴합니다.

`put`을 제외한 생성 API는 context pointer 또는 negative error code를 반환합니다. 이후 나오는 나머지 operation은 오류 시 negative error code를 반환합니다.

VFS Filesystem context API
==========================

There are four operations for creating a filesystem context and one for
destroying a context:

   * ::

       struct fs_context *fs_context_for_mount(struct file_system_type *fs_type,
                                               unsigned int sb_flags);

     Allocate a filesystem context for the purpose of setting up a new mount,
     whether that be with a new superblock or sharing an existing one.  This
     sets the superblock flags, initialises the security and calls
     fs_type->init_fs_context() to initialise the filesystem private data.

     fs_type specifies the filesystem type that will manage the context and
     sb_flags presets the superblock flags stored therein.

   * ::

       struct fs_context *fs_context_for_reconfigure(
                struct dentry *dentry,
                unsigned int sb_flags,
                unsigned int sb_flags_mask);

     Allocate a filesystem context for the purpose of reconfiguring an
     existing superblock.  dentry provides a reference to the superblock to be
     configured.  sb_flags and sb_flags_mask indicate which superblock flags
     need changing and to what.

   * ::

       struct fs_context *fs_context_for_submount(
                struct file_system_type *fs_type,
                struct dentry *reference);

     Allocate a filesystem context for the purpose of creating a new mount for
     an automount point or other derived superblock.  fs_type specifies the
     filesystem type that will manage the context and the reference dentry
     supplies the parameters.  Namespaces are propagated from the reference
     dentry's superblock also.

     Note that it's not a requirement that the reference dentry be of the same
     filesystem type as fs_type.

   * ::

        struct fs_context *vfs_dup_fs_context(struct fs_context *src_fc);

     Duplicate a filesystem context, copying any options noted and duplicating
     or additionally referencing any resources held therein.  This is available
     for use where a filesystem has to get a mount within a mount, such as NFS4
     does by internally mounting the root of the target server and then doing a
     private pathwalk to the target directory.

     The purpose in the new context is inherited from the old one.

   * ::

       void put_fs_context(struct fs_context *fc);

     Destroy a filesystem context, releasing any resources it holds.  This
     calls the ->free() operation.  This is intended to be called by anyone who
     created a filesystem context.

     .. Warning::

        filesystem contexts are not refcounted, so this causes unconditional
        destruction.

In all the above operations, apart from the put op, the return is a mount
context pointer or a negative error code.

For the remaining operations, if an error occurs, a negative error code will be
returned.

VFS parameter 전달과 mount object 생성

`vfs_parse_fs_param(fc, param)`은 mount parameter 하나를 context에 제공합니다. Device/source도 이름이 `source`인 parameter이며 파일시스템이 지원하면 여러 번 지정할 수 있습니다.

Parameter는 먼저 표준 mount flag인지 검사되어 해당하면 `SB_xxx` flag를 설정하고 소비됩니다. 다음으로 security option이면 LSM이 소비합니다. 두 경우가 아니면 filesystem으로 전달됩니다.

Value type은 값 없는 `fs_value_is_flag`, string, binary blob, filename과 dirfd, open `file *`로 구분됩니다. Value가 있으면 `param->{string,blob,name,file}` union에 저장됩니다. 함수가 pointer를 가져가고 clear할 수 있지만 그때부터 object 처분 책임도 넘겨받습니다.

`vfs_parse_fs_qstr()`과 `vfs_parse_fs_string()`은 전달받은 value string을 복사한 뒤 `vfs_parse_fs_param()`을 호출하는 wrapper입니다.

`generic_parse_monolithic(fc, data)`은 `sys_mount()` data page를 comma로 구분된 `key[=val]` text list로 가정해 parse하고 각 항목을 `vfs_mount_option()`에 넘깁니다. `->parse_monolithic()`이 NULL일 때 기본 동작입니다. 원문의 함수명 표기는 그대로 보존합니다.

`vfs_get_tree(fc)`는 context parameter로 superblock을 선택·설정하고 mountable root와 superblock을 얻거나 생성하며 `->get_tree()`를 호출합니다. `vfs_create_mount(fc)`는 context parameter로 mount를 만들지만 어디에도 attach하지는 않습니다.

   * ::

        int vfs_parse_fs_param(struct fs_context *fc,
                               struct fs_parameter *param);

     Supply a single mount parameter to the filesystem context.  This includes
     the specification of the source/device which is specified as the "source"
     parameter (which may be specified multiple times if the filesystem
     supports that).

     param specifies the parameter key name and the value.  The parameter is
     first checked to see if it corresponds to a standard mount flag (in which
     case it is used to set an SB_xxx flag and consumed) or a security option
     (in which case the LSM consumes it) before it is passed on to the
     filesystem.

     The parameter value is typed and can be one of:

        ====================                =============================
        fs_value_is_flag                Parameter not given a value
        fs_value_is_string                Value is a string
        fs_value_is_blob                Value is a binary blob
        fs_value_is_filename                Value is a filename* + dirfd
        fs_value_is_file                Value is an open file (file*)
        ====================                =============================

     If there is a value, that value is stored in a union in the struct in one
     of param->{string,blob,name,file}.  Note that the function may steal and
     clear the pointer, but then becomes responsible for disposing of the
     object.

   * ::

       int vfs_parse_fs_qstr(struct fs_context *fc, const char *key,
                               const struct qstr *value);

     A wrapper around vfs_parse_fs_param() that copies the value string it is
     passed.

   * ::

       int vfs_parse_fs_string(struct fs_context *fc, const char *key,
                               const char *value);

     A wrapper around vfs_parse_fs_param() that copies the value string it is
     passed.

   * ::

       int generic_parse_monolithic(struct fs_context *fc, void *data);

     Parse a sys_mount() data page, assuming the form to be a text list
     consisting of key[=val] options separated by commas.  Each item in the
     list is passed to vfs_mount_option().  This is the default when the
     ->parse_monolithic() method is NULL.

   * ::

       int vfs_get_tree(struct fs_context *fc);

     Get or create the mountable root and superblock, using the parameters in
     the filesystem context to select/configure the superblock.  This invokes
     the ->get_tree() method.

   * ::

       struct vfsmount *vfs_create_mount(struct fs_context *fc);

     Create a mount given the parameters in the specified filesystem context.
     Note that this does not attach the mount to anything.

sget_fc와 superblock 선택 helper

VFS는 파일시스템이 superblock을 생성하거나 검색할 때 쓸 helper를 제공합니다. Core routine인 `sget_fc(fc, test, set)`는 `test`가 non-NULL이면 context 조건과 맞는 기존 superblock을 `test` callback으로 검색합니다. Match가 없으면 새 superblock을 만들고 `set` callback으로 설정합니다.

`set` 호출 전에 `fc->s_fs_info`가 `sb->s_fs_info`로 이전됩니다. `set`이 성공, 즉 0을 반환하면 `fc->s_fs_info`가 clear됩니다.

`vfs_get_single_super`는 시스템에 해당 superblock이 하나만 존재하도록 하며 이후 요청은 parameter 차이를 무시하고 기존 것을 받습니다.

`vfs_get_keyed_super`는 같은 type의 superblock을 여러 개 허용하고 `s_fs_info` pointer를 key로 사용합니다. 예를 들어 namespace를 가리킬 수 있습니다. `vfs_get_independent_super`도 여러 개를 허용하지만 기존 항목과 절대 match하지 않고 항상 새 superblock을 만듭니다.

Superblock Creation Helpers
===========================

A number of VFS helpers are available for use by filesystems for the creation
or looking up of superblocks.

   * ::

       struct super_block *
       sget_fc(struct fs_context *fc,
               int (*test)(struct super_block *sb, struct fs_context *fc),
               int (*set)(struct super_block *sb, struct fs_context *fc));

     This is the core routine.  If test is non-NULL, it searches for an
     existing superblock matching the criteria held in the fs_context, using
     the test function to match them.  If no match is found, a new superblock
     is created and the set function is called to set it up.

     Prior to the set function being called, fc->s_fs_info will be transferred
     to sb->s_fs_info - and fc->s_fs_info will be cleared if set returns
     success (ie. 0).

The following helpers all wrap sget_fc():

        (1) vfs_get_single_super

            Only one such superblock may exist in the system.  Any further
            attempt to get a new superblock gets this one (and any parameter
            differences are ignored).

        (2) vfs_get_keyed_super

            Multiple superblocks of this type may exist and they're keyed on
            their s_fs_info pointer (for example this may refer to a
            namespace).

        (3) vfs_get_independent_super

            Multiple independent superblocks of this type may exist.  This
            function never matches an existing one and always creates a new
            one.

fs_parameter_description과 specification

Parameter는 `linux/fs_parser.h`에 정의된 구조체로 설명합니다. Core `struct fs_parameter_description`은 parameter specification table `specs`와 enum mapping table `enums`를 연결합니다. 원문은 AFS의 `Opt_autocell`, `Opt_bar`, `Opt_dyn`, `Opt_foo`, `Opt_source` 예를 보여줍니다.

NULL entry로 끝나는 `specs` table의 각 `struct fs_parameter_spec`에는 `name`, `opt`, `type`, `flags`가 있습니다.

`name`은 parameter key와 정확히 비교하는 문자열입니다. Wildcard·pattern·case-insensitive matching은 없습니다. `opt`는 match 성공 시 `fs_parser()`가 반환할 값입니다. `type`은 요구하는 value type을 나타내며 다음 구간 표의 상수 중 하나여야 합니다.

Parameter Description
=====================

Parameters are described using structures defined in linux/fs_parser.h.
There's a core description struct that links everything together::

        struct fs_parameter_description {
                const struct fs_parameter_spec *specs;
                const struct fs_parameter_enum *enums;
        };

For example::

        enum {
                Opt_autocell,
                Opt_bar,
                Opt_dyn,
                Opt_foo,
                Opt_source,
        };

        static const struct fs_parameter_description afs_fs_parameters = {
                .specs                = afs_param_specs,
                .enums                = afs_param_enums,
        };

The members are as follows:

 (1) ::

       const struct fs_parameter_specification *specs;

     Table of parameter specifications, terminated with a null entry, where the
     entries are of type::

        struct fs_parameter_spec {
                const char                *name;
                u8                        opt;
                enum fs_parameter_type        type:8;
                unsigned short                flags;
        };

     The 'name' field is a string to match exactly to the parameter key (no
     wildcards, patterns and no case-independence) and 'opt' is the value that
     will be returned by the fs_parser() function in the case of a successful
     match.

     The 'type' field indicates the desired value type and must be one of:

Parameter type·flag·wrapper macro

`fs_param_is_flag`는 값이 없고 별도 결과도 없습니다. Boolean은 `result->boolean`, unsigned 32-bit·octal·hex는 `result->uint_32`, signed 32-bit는 `result->int_32`, unsigned 64-bit는 `result->uint_64`에 저장됩니다.

`fs_param_is_enum`은 enum 이름을 `result->uint_32`로 바꿉니다. Arbitrary string과 binary blob은 각각 `param->string`, `param->blob`에 남습니다. Block device path와 일반 path는 lookup이 필요합니다. File descriptor는 `result->int_32`, user ID와 group ID는 각각 `result->uid`, `result->gid`에 저장됩니다.

Boolean type이면 `fs_parse()`가 string value를 `0`, `1`, `no`, `yes`, `false`, `true`와 비교합니다.

Parameter flag로 `fs_param_v_optional`은 value가 선택 사항임을 나타냅니다. `fs_param_neg_with_no`는 key 앞에 `no`가 붙으면 `result->negated`를 설정하고, `fs_param_neg_with_empty`는 value가 빈 문자열이면 설정합니다. `fs_param_deprecated`는 폐기 예정 parameter입니다.

Convenience macro는 type과 flag 조합을 만듭니다. `fsparam_flag`, `fsparam_flag_no`, `fsparam_bool`, `fsparam_u32`, `fsparam_u32oct`, `fsparam_s32`, `fsparam_u64`, `fsparam_enum`, `fsparam_string`, `fsparam_blob`, `fsparam_bdev`, `fsparam_path`, `fsparam_fd`, `fsparam_uid`, `fsparam_gid`가 있습니다.

각 macro는 name string과 option number 두 인수를 받습니다. AFS 예에서는 `autocell`, `dyn`, `source`, negation을 허용하는 `foo`를 등록하고 빈 entry로 table을 끝냅니다. 표준 macro에 맞지 않는 경우 type과 flag 인수 한 쌍을 추가로 받는 `__fsparam()`을 사용합니다.

        =======================        =======================        =====================
        TYPE NAME                EXPECTED VALUE                RESULT IN
        =======================        =======================        =====================
        fs_param_is_flag        No value                n/a
        fs_param_is_bool        Boolean value                result->boolean
        fs_param_is_u32                32-bit unsigned int        result->uint_32
        fs_param_is_u32_octal        32-bit octal int        result->uint_32
        fs_param_is_u32_hex        32-bit hex int                result->uint_32
        fs_param_is_s32                32-bit signed int        result->int_32
        fs_param_is_u64                64-bit unsigned int        result->uint_64
        fs_param_is_enum        Enum value name         result->uint_32
        fs_param_is_string        Arbitrary string        param->string
        fs_param_is_blob        Binary blob                param->blob
        fs_param_is_blockdev        Blockdev path                * Needs lookup
        fs_param_is_path        Path                        * Needs lookup
        fs_param_is_fd                File descriptor                result->int_32
        fs_param_is_uid                User ID (u32)           result->uid
        fs_param_is_gid                Group ID (u32)          result->gid
        =======================        =======================        =====================

     Note that if the value is of fs_param_is_bool type, fs_parse() will try
     to match any string value against "0", "1", "no", "yes", "false", "true".

     Each parameter can also be qualified with 'flags':

        =======================        ================================================
        fs_param_v_optional        The value is optional
        fs_param_neg_with_no        result->negated set if key is prefixed with "no"
        fs_param_neg_with_empty        result->negated set if value is ""
        fs_param_deprecated        The parameter is deprecated.
        =======================        ================================================

     These are wrapped with a number of convenience wrappers:

        =======================        ===============================================
        MACRO                        SPECIFIES
        =======================        ===============================================
        fsparam_flag()                fs_param_is_flag
        fsparam_flag_no()        fs_param_is_flag, fs_param_neg_with_no
        fsparam_bool()                fs_param_is_bool
        fsparam_u32()                fs_param_is_u32
        fsparam_u32oct()        fs_param_is_u32_octal
        fsparam_s32()                fs_param_is_s32
        fsparam_u64()                fs_param_is_u64
        fsparam_enum()                fs_param_is_enum
        fsparam_string()        fs_param_is_string
        fsparam_blob()                fs_param_is_blob
        fsparam_bdev()                fs_param_is_blockdev
        fsparam_path()                fs_param_is_path
        fsparam_fd()                fs_param_is_fd
        fsparam_uid()                fs_param_is_uid
        fsparam_gid()                fs_param_is_gid
        =======================        ===============================================

     all of which take two arguments, name string and option number - for
     example::

        static const struct fs_parameter_spec afs_param_specs[] = {
                fsparam_flag        ("autocell",        Opt_autocell),
                fsparam_flag        ("dyn",                Opt_dyn),
                fsparam_string        ("source",        Opt_source),
                fsparam_flag_no        ("foo",                Opt_foo),
                {}
        };

     An addition macro, __fsparam() is provided that takes an additional pair
     of arguments to specify the type and the flags for anything that doesn't
     match one of the above macros.

Enum mapping과 parser 등록 검증

`enums`는 enum value name을 integer로 mapping하며 NULL entry로 끝납니다. `struct fs_parameter_enum`은 option ID `opt`, 최대 길이가 구조체에 반영된 `name[14]`, mapping 결과 `value`를 가집니다.

Array는 `{ parameter ID, name }`을 key로 하는 정렬되지 않은 element 목록입니다. 원문 예는 `Opt_bar`의 `x`, `y`, `z`를 각각 1, 23, 42로 mapping합니다.

`fs_param_is_enum` parameter를 만나면 `fs_parse()`가 enum table에서 value를 찾고 parse result에 저장합니다.

Parameter description은 `file_system_type` 구조체의 parser pointer가 가리켜야 합니다. 그러면 `CONFIG_VALIDATE_FS_PARSER=y`일 때 등록 시 검증할 수 있고, userspace가 `fsinfo()` syscall로 description을 조회할 수 있습니다.

 (2) ::

       const struct fs_parameter_enum *enums;

     Table of enum value names to integer mappings, terminated with a null
     entry.  This is of type::

        struct fs_parameter_enum {
                u8                opt;
                char                name[14];
                u8                value;
        };

     Where the array is an unsorted list of { parameter ID, name }-keyed
     elements that indicate the value to map to, e.g.::

        static const struct fs_parameter_enum afs_param_enums[] = {
                { Opt_bar,   "x",      1},
                { Opt_bar,   "y",      23},
                { Opt_bar,   "z",      42},
        };

     If a parameter of type fs_param_is_enum is encountered, fs_parse() will
     try to look the value up in the enum table and the result will be stored
     in the parse result.

The parser should be pointed to by the parser pointer in the file_system_type
struct as this will provide validation on registration (if
CONFIG_VALIDATE_FS_PARSER=y) and will allow the description to be queried from
userspace using the fsinfo() syscall.

Parameter lookup·검증·parse helper

Filesystem 또는 LSM이 전달받은 parameter를 처리하도록 여러 helper가 제공됩니다.

`lookup_constant(tbl, name, not_found)`는 name-to-integer mapping인 `struct constant_table` array에서 이름을 찾습니다. Match되면 해당 value, 아니면 `not_found` 값을 반환합니다.

`fs_validate_description(name, desc)`는 parameter description을 검증합니다. 유효하면 true, 아니면 false를 반환하고 실패 오류를 kernel log buffer에 기록합니다.

`fs_parse(fc, desc, param, result)`는 주 parameter interpreter입니다. Description에서 key name으로 parameter를 찾아 option number로 변환해 반환합니다. Type이 boolean, integer, enum, uid, gid이면 value도 변환하여 `result->{boolean,int_32,uint_32,uint_64,uid,gid}`에 저장합니다.

처음 match되지 않았고 key가 `no`로 시작하며 value가 없으면 prefix를 제거해 다시 찾습니다. Match한 parameter에 `fs_param_neg_with_no`가 설정되어 있으면 성공으로 처리하고 `result->negated`를 true로 만듭니다.

Parameter가 match되지 않으면 `-ENOPARAM`, match했지만 value가 잘못되면 `-EINVAL`, 그 밖에는 parameter option number를 반환합니다.

`fs_lookup_param(fc, value, want_bdev, flags, _path)`는 string 또는 filename parameter에 path lookup을 시도합니다. Block device를 요구하면 inode가 실제 blockdev인지 확인합니다. 성공하면 0과 설정된 `*_path`, 실패하면 negative error code를 반환합니다.

Parameter Helper Functions
==========================

A number of helper functions are provided to help a filesystem or an LSM
process the parameters it is given.

   * ::

       int lookup_constant(const struct constant_table tbl[],
                           const char *name, int not_found);

     Look up a constant by name in a table of name -> integer mappings.  The
     table is an array of elements of the following type::

        struct constant_table {
                const char        *name;
                int                value;
        };

     If a match is found, the corresponding value is returned.  If a match
     isn't found, the not_found value is returned instead.

   * ::

       bool fs_validate_description(const char *name,
                                    const struct fs_parameter_description *desc);

     This performs some validation checks on a parameter description.  It
     returns true if the description is good and false if it is not.  It will
     log errors to the kernel log buffer if validation fails.

   * ::

        int fs_parse(struct fs_context *fc,
                     const struct fs_parameter_description *desc,
                     struct fs_parameter *param,
                     struct fs_parse_result *result);

     This is the main interpreter of parameters.  It uses the parameter
     description to look up a parameter by key name and to convert that to an
     option number (which it returns).

     If successful, and if the parameter type indicates the result is a
     boolean, integer, enum, uid, or gid type, the value is converted by this
     function and the result stored in
     result->{boolean,int_32,uint_32,uint_64,uid,gid}.

     If a match isn't initially made, the key is prefixed with "no" and no
     value is present then an attempt will be made to look up the key with the
     prefix removed.  If this matches a parameter for which the type has flag
     fs_param_neg_with_no set, then a match will be made and result->negated
     will be set to true.

     If the parameter isn't matched, -ENOPARAM will be returned; if the
     parameter is matched, but the value is erroneous, -EINVAL will be
     returned; otherwise the parameter's option number will be returned.

   * ::

       int fs_lookup_param(struct fs_context *fc,
                           struct fs_parameter *value,
                           bool want_bdev,
                           unsigned int flags,
                           struct path *_path);

     This takes a parameter that carries a string or filename type and attempts
     to do a path lookup on it.  If the parameter expects a blockdev, a check
     is made that the inode actually represents one.

     Returns 0 if successful and ``*_path`` will be set; returns a negative
     error code if not.