1.. SPDX-License-Identifier: GPL-2.0 2 3.. _adding_new_filesystems: 4 5Adding New Filesystems 6====================== 7 8This document describes what is involved in adding a new filesystem to the 9Linux kernel. 10 11Every filesystem merged into the kernel becomes the collective responsibility 12of the VFS maintainers and the wider filesystem development community. 13Experience has shown that filesystems which become unmaintained impose a 14significant and ongoing burden: they are hard or impossible to test, they 15block infrastructure changes because someone must update or preserve old APIs 16for code that nobody is actively looking after, and they accumulate unfixed 17bugs. The requirements and expectations described here are informed by this 18experience and are intended to ensure that new filesystems enter the kernel 19on a sustainable footing. 20 21 22Do You Need a New In-Kernel Filesystem? 23--------------------------------------- 24 25Before proposing a new in-kernel filesystem, consider whether one of the 26alternatives 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 42Technical Requirements 43---------------------- 44 45New filesystems must use current kernel interfaces and practices. 46Submitting a filesystem built on outdated APIs creates an unacceptable 47maintenance debt and is likely to face pushback during review. 48 49Use 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 65Provide 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 72Be 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 81Provide 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 87Community and Maintainership Expectations 88----------------------------------------- 89 90Merging a filesystem is a long-term commitment. The kernel community 91needs confidence that the filesystem will be actively maintained after it 92is merged. 93 94Identified 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 101Demonstrated 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 107Sustained 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 112Responsiveness 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 119User 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 124Building 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 134Submission Process 135------------------ 136 137This section covers what is specific to filesystem submissions, over and 138above 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 (``linux-fsdevel@vger.kernel.org``). 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 169Ongoing Obligations 170------------------- 171 172Merging is not the finish line. Maintaining a filesystem in the kernel is an 173ongoing 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. 196