Documentation/filesystems/iomap/porting.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/iomap/porting.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/iomap/porting.rst
Extension
.rst
Size
5371 bytes
Lines
121
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
.. _iomap_porting:

..
        Dumb style notes to maintain the author's sanity:
        Please try to start sentences on separate lines so that
        sentence changes don't bleed colors in diff.
        Heading decorations are documented in sphinx.rst.

=======================
Porting Your Filesystem
=======================

.. contents:: Table of Contents
   :local:

Why Convert?
============

There are several reasons to convert a filesystem to iomap:

 1. The classic Linux I/O path is not terribly efficient.
    Pagecache operations lock a single base page at a time and then call
    into the filesystem to return a mapping for only that page.
    Direct I/O operations build I/O requests a single file block at a
    time.
    This worked well enough for direct/indirect-mapped filesystems such
    as ext2, but is very inefficient for extent-based filesystems such
    as XFS.

 2. Large folios are only supported via iomap; there are no plans to
    convert the old buffer_head path to use them.

 3. Direct access to storage on memory-like devices (fsdax) is only
    supported via iomap.

 4. Lower maintenance overhead for individual filesystem maintainers.
    iomap handles common pagecache related operations itself, such as
    allocating, instantiating, locking, and unlocking of folios.
    No ->write_begin(), ->write_end() or direct_IO
    address_space_operations are required to be implemented by
    filesystem using iomap.

How Do I Convert a Filesystem?
==============================

First, add ``#include <linux/iomap.h>`` from your source code and add
``select FS_IOMAP`` to your filesystem's Kconfig option.
Build the kernel, run fstests with the ``-g all`` option across a wide
variety of your filesystem's supported configurations to build a
baseline of which tests pass and which ones fail.

The recommended approach is first to implement ``->iomap_begin`` (and
``->iomap_end`` if necessary) to allow iomap to obtain a read-only
mapping of a file range.
In most cases, this is a relatively trivial conversion of the existing
``get_block()`` function for read-only mappings.
``FS_IOC_FIEMAP`` is a good first target because it is trivial to
implement support for it and then to determine that the extent map
iteration is correct from userspace.
If FIEMAP is returning the correct information, it's a good sign that
other read-only mapping operations will do the right thing.

Next, modify the filesystem's ``get_block(create = false)``
implementation to use the new ``->iomap_begin`` implementation to map
file space for selected read operations.
Hide behind a debugging knob the ability to switch on the iomap mapping
functions for selected call paths.
It is necessary to write some code to fill out the bufferhead-based
mapping information from the ``iomap`` structure, but the new functions

Annotation

Implementation Notes