Documentation/filesystems/adding-new-filesystems.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/adding-new-filesystems.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/adding-new-filesystems.rst
Extension
.rst
Size
8862 bytes
Lines
196
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

.. _adding_new_filesystems:

Adding New Filesystems
======================

This document describes what is involved in adding a new filesystem to the
Linux kernel.

Every filesystem merged into the kernel becomes the collective responsibility
of the VFS maintainers and the wider filesystem development community.
Experience has shown that filesystems which become unmaintained impose a
significant and ongoing burden: they are hard or impossible to test, they
block infrastructure changes because someone must update or preserve old APIs
for code that nobody is actively looking after, and they accumulate unfixed
bugs.  The requirements and expectations described here are informed by this
experience and are intended to ensure that new filesystems enter the kernel
on a sustainable footing.


Do You Need a New In-Kernel Filesystem?
---------------------------------------

Before proposing a new in-kernel filesystem, consider whether one of the
alternatives might be more appropriate.

 - If an existing in-kernel filesystem covers the same use case, improving it
   is generally preferred over adding a new implementation.  The kernel
   community favors incremental improvement over parallel implementations.

 - If the filesystem serves a niche audience or has a small user base, a FUSE
   (Filesystem in Userspace) implementation may be a better fit.  FUSE
   filesystems avoid the long-term kernel maintenance commitment and can be
   developed and released on their own schedule.

 - If kernel-level performance, reliability, or integration is genuinely
   required, make the case explicitly.  Explain who the users are, what the
   use case is, and why a FUSE implementation would not be sufficient.


Technical Requirements
----------------------

New filesystems must use current kernel interfaces and practices.
Submitting a filesystem built on outdated APIs creates an unacceptable
maintenance debt and is likely to face pushback during review.

Use modern VFS interfaces
  Do not use interfaces listed in
  :ref:`Documentation/process/deprecated.rst <deprecated>`.

  Use folios rather than raw page operations for page cache management and
  iomap rather than buffer heads for block mapping and I/O.  See
  ``Documentation/filesystems/iomap/index.rst`` for iomap documentation.

  Block-based filesystems that need functionality not currently provided by
  iomap should be prepared to explain why adding that functionality to iomap
  is infeasible, rather than reimplementing their own block mapping layer.

  Network filesystems should consider using the netfs library
  (``Documentation/filesystems/netfs_library.rst``), or be prepared to explain
  why it is not a good fit.

Provide userspace utilities
  A ``mkfs`` tool is expected so that the filesystem can be created and used
  by testers and users.  A ``fsck`` tool is strongly recommended; while not
  strictly required for every filesystem type, the ability to verify
  consistency and repair corruption is an important part of a mature
  filesystem.

Annotation

Implementation Notes