| 1 | |
| 2 |
|
| 3 | .. _adding_new_filesystems:
|
| 4 |
|
| 5 | Adding New Filesystems
|
| 6 | ======================
|
| 7 |
|
| 8 | This document describes what is involved in adding a new filesystem to the
|
| 9 | Linux kernel.
|
| 10 |
|
| 11 | Every filesystem merged into the kernel becomes the collective responsibility
|
| 12 | of the VFS maintainers and the wider filesystem development community.
|
| 13 | Experience has shown that filesystems which become unmaintained impose a
|
| 14 | significant and ongoing burden: they are hard or impossible to test, they
|
| 15 | block infrastructure changes because someone must update or preserve old APIs
|
| 16 | for code that nobody is actively looking after, and they accumulate unfixed
|
| 17 | bugs. The requirements and expectations described here are informed by this
|
| 18 | experience and are intended to ensure that new filesystems enter the kernel
|
| 19 | on a sustainable footing.
|
| 20 |
|
| 21 |
|
| 22 | Do You Need a New In-Kernel Filesystem?
|
| 23 | ---------------------------------------
|
| 24 |
|
| 25 | Before proposing a new in-kernel filesystem, consider whether one of the
|
| 26 | alternatives might be more appropriate.
|
| 27 |
|
| 28 | - If an existing in-kernel filesystem covers the same use case, improving it
|
| 29 | is generally preferred over adding a new implementation. The kernel
|
| 30 | community favors incremental improvement over parallel implementations.
|
| 31 |
|
| 32 | - If the filesystem serves a niche audience or has a small user base, a FUSE
|
| 33 | (Filesystem in Userspace) implementation may be a better fit. FUSE
|
| 34 | filesystems avoid the long-term kernel maintenance commitment and can be
|
| 35 | developed and released on their own schedule.
|
| 36 |
|
| 37 | - If kernel-level performance, reliability, or integration is genuinely
|
| 38 | required, make the case explicitly. Explain who the users are, what the
|
| 39 | use case is, and why a FUSE implementation would not be sufficient.
|
| 40 |
|
| 41 |
|
| 42 | Technical Requirements
|
| 43 | ----------------------
|
| 44 |
|
| 45 | New filesystems must use current kernel interfaces and practices.
|
| 46 | Submitting a filesystem built on outdated APIs creates an unacceptable
|
| 47 | maintenance debt and is likely to face pushback during review.
|
| 48 |
|
| 49 | Use modern VFS interfaces
|
| 50 | Do not use interfaces listed in
|
| 51 | :ref:`Documentation/process/deprecated.rst <deprecated>`.
|
| 52 |
|
| 53 | Use folios rather than raw page operations for page cache management and
|
| 54 | iomap rather than buffer heads for block mapping and I/O. See
|
| 55 | ``Documentation/filesystems/iomap/index.rst`` for iomap documentation.
|
| 56 |
|
| 57 | Block-based filesystems that need functionality not currently provided by
|
| 58 | iomap should be prepared to explain why adding that functionality to iomap
|
| 59 | is infeasible, rather than reimplementing their own block mapping layer.
|
| 60 |
|
| 61 | Network filesystems should consider using the netfs library
|
| 62 | (``Documentation/filesystems/netfs_library.rst``), or be prepared to explain
|
| 63 | why it is not a good fit.
|
| 64 |
|
| 65 | Provide userspace utilities
|
| 66 | A ``mkfs`` tool is expected so that the filesystem can be created and used
|
| 67 | by testers and users. A ``fsck`` tool is strongly recommended; while not
|
| 68 | strictly required for every filesystem type, the ability to verify
|
| 69 | consistency and repair corruption is an important part of a mature
|
| 70 | filesystem.
|
| 71 |
|
| 72 | Be testable
|
| 73 | The filesystem must be testable in a meaningful way. The
|
| 74 | `fstests <https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git>`_
|
| 75 | framework (also known as xfstests) is the standard testing infrastructure
|
| 76 | for Linux filesystems and its use is highly recommended. At a minimum,
|
| 77 | there must be a credible and documented way to test the filesystem and
|
| 78 | detect regressions. When submitting, include a summary of test results
|
| 79 | indicating which tests pass, fail, or are not applicable.
|
| 80 |
|
| 81 | Provide documentation
|
| 82 | A documentation file under ``Documentation/filesystems/`` describing the
|
| 83 | filesystem, its on-disk format, mount options, and any notable design
|
| 84 | decisions is recommended.
|
| 85 |
|
| 86 |
|
| 87 | Community and Maintainership Expectations
|
| 88 | -----------------------------------------
|
| 89 |
|
| 90 | Merging a filesystem is a long-term commitment. The kernel community
|
| 91 | needs confidence that the filesystem will be actively maintained after it
|
| 92 | is merged.
|
| 93 |
|
| 94 | Identified maintainers
|
| 95 | The submission must include a ``MAINTAINERS`` entry with at least one
|
| 96 | maintainer (``M:``), a mailing list (``L:``), and a git tree (``T:``).
|
| 97 | Having two or more maintainers is strongly preferred so that coverage
|
| 98 | does not depend on a single person. The maintainers are expected to be
|
| 99 | the primary points of contact for the filesystem going forward.
|
| 100 |
|
| 101 | Demonstrated commitment
|
| 102 | A track record of maintaining kernel code -- for example, in other
|
| 103 | subsystems -- significantly strengthens the case for a new filesystem.
|
| 104 | Maintainers who are already known and trusted within the community face
|
| 105 | less friction during review.
|
| 106 |
|
| 107 | Sustained backing
|
| 108 | Major filesystems in Linux have organizational or corporate support behind
|
| 109 | their development. Filesystems that depend entirely on volunteer effort
|
| 110 | face higher scrutiny about their long-term viability.
|
| 111 |
|
| 112 | Responsiveness
|
| 113 | The maintainer is expected to respond to bug reports, address review
|
| 114 | feedback, and adapt the filesystem to VFS infrastructure changes such as
|
| 115 | folio conversions, iomap migration, and mount API updates. Unresponsive
|
| 116 | maintainership is one of the primary reasons filesystems end up on the
|
| 117 | path to deprecation.
|
| 118 |
|
| 119 | User base
|
| 120 | Clearly describe who the users of this filesystem are and the scale of the
|
| 121 | user base. Filesystems with a very small or unclear user base face a
|
| 122 | harder path to acceptance and a higher risk of future deprecation.
|
| 123 |
|
| 124 | Building your track record
|
| 125 | A practical way to demonstrate many of the qualities above is to maintain
|
| 126 | the filesystem out-of-tree for a period before requesting a merge. This
|
| 127 | shows sustained commitment, builds a visible user base, and gives reviewers
|
| 128 | confidence that the code and its maintainer will persist after merging.
|
| 129 | That said, it is recognized that for some filesystems the user base grows
|
| 130 | significantly only after upstreaming, so a compelling case for expected
|
| 131 | adoption can substitute for a large existing user base.
|
| 132 |
|
| 133 |
|
| 134 | Submission Process
|
| 135 | ------------------
|
| 136 |
|
| 137 | This section covers what is specific to filesystem submissions, over and
|
| 138 | above the normal submission advice in
|
| 139 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and
|
| 140 | :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
|
| 141 |
|
| 142 | - Send patches to the linux-fsdevel mailing list
|
| 143 | (``[email protected]``). CC the relevant VFS maintainers as
|
| 144 | listed in the ``MAINTAINERS`` file under
|
| 145 | ``FILESYSTEMS (VFS and infrastructure)``.
|
| 146 |
|
| 147 | - Structure the submission logically. It is neither acceptable to send one
|
| 148 | large patch containing the entire filesystem, nor is a replay of the full
|
| 149 | development history helpful to reviewers. Instead, split the series by
|
| 150 | topic -- for example: superblock and mount handling, inode operations,
|
| 151 | directory operations, address space operations, and so on -- so that each
|
| 152 | patch is reviewable in isolation.
|
| 153 |
|
| 154 | - Separate any filesystem-specific ioctls into their own patches with
|
| 155 | dedicated justification. Interfaces beyond those already common across
|
| 156 | other filesystems will receive additional scrutiny because they are hard
|
| 157 | to maintain and may conflict with future generic interfaces.
|
| 158 |
|
| 159 | - Expect thorough review. Filesystem code interacts deeply with the VFS,
|
| 160 | memory management, and block layers, so reviewers will examine the code
|
| 161 | carefully. Address all review feedback and be prepared for multiple
|
| 162 | revision cycles.
|
| 163 |
|
| 164 | - It may be appropriate to mark the filesystem as experimental in its Kconfig
|
| 165 | help text for the first few releases to set expectations while the code
|
| 166 | stabilizes in-tree.
|
| 167 |
|
| 168 |
|
| 169 | Ongoing Obligations
|
| 170 | -------------------
|
| 171 |
|
| 172 | Merging is not the finish line. Maintaining a filesystem in the kernel is an
|
| 173 | ongoing commitment.
|
| 174 |
|
| 175 | - Adapt to VFS infrastructure changes. The VFS layer evolves continuously;
|
| 176 | maintainers are expected to keep up with conversions such as folio
|
| 177 | migration, iomap adoption, and mount API updates.
|
| 178 |
|
| 179 | - Maintain test coverage. As test suites evolve, the filesystem's test
|
| 180 | results should be kept current.
|
| 181 |
|
| 182 | - Handle security issues and regression promptly. Both those reported
|
| 183 | by ordinary users and those reported by test bots and fuzzing tools.
|
| 184 | The filesystem must handle corrupted input gracefully without corrupting
|
| 185 | memory, hanging, or crashing the kernel.
|
| 186 |
|
| 187 | - Engage with the wider filesystem community. Participate on linux-fsdevel,
|
| 188 | share approaches to common problems, and look for opportunities to reuse
|
| 189 | shared infrastructure. It is inappropriate to develop in isolation on a
|
| 190 | private list and surface patches only at merge time.
|
| 191 |
|
| 192 | - Filesystems that become unmaintained -- where the maintainer stops
|
| 193 | responding, infrastructure changes go unadapted, and testing becomes
|
| 194 | impossible -- are candidates for deprecation and eventual removal from
|
| 195 | the kernel.
|