121 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. _iomap_porting:3 4..5 Dumb style notes to maintain the author's sanity:6 Please try to start sentences on separate lines so that7 sentence changes don't bleed colors in diff.8 Heading decorations are documented in sphinx.rst.9 10=======================11Porting Your Filesystem12=======================13 14.. contents:: Table of Contents15 :local:16 17Why Convert?18============19 20There are several reasons to convert a filesystem to iomap:21 22 1. The classic Linux I/O path is not terribly efficient.23 Pagecache operations lock a single base page at a time and then call24 into the filesystem to return a mapping for only that page.25 Direct I/O operations build I/O requests a single file block at a26 time.27 This worked well enough for direct/indirect-mapped filesystems such28 as ext2, but is very inefficient for extent-based filesystems such29 as XFS.30 31 2. Large folios are only supported via iomap; there are no plans to32 convert the old buffer_head path to use them.33 34 3. Direct access to storage on memory-like devices (fsdax) is only35 supported via iomap.36 37 4. Lower maintenance overhead for individual filesystem maintainers.38 iomap handles common pagecache related operations itself, such as39 allocating, instantiating, locking, and unlocking of folios.40 No ->write_begin(), ->write_end() or direct_IO41 address_space_operations are required to be implemented by42 filesystem using iomap.43 44How Do I Convert a Filesystem?45==============================46 47First, add ``#include <linux/iomap.h>`` from your source code and add48``select FS_IOMAP`` to your filesystem's Kconfig option.49Build the kernel, run fstests with the ``-g all`` option across a wide50variety of your filesystem's supported configurations to build a51baseline of which tests pass and which ones fail.52 53The recommended approach is first to implement ``->iomap_begin`` (and54``->iomap_end`` if necessary) to allow iomap to obtain a read-only55mapping of a file range.56In most cases, this is a relatively trivial conversion of the existing57``get_block()`` function for read-only mappings.58``FS_IOC_FIEMAP`` is a good first target because it is trivial to59implement support for it and then to determine that the extent map60iteration is correct from userspace.61If FIEMAP is returning the correct information, it's a good sign that62other read-only mapping operations will do the right thing.63 64Next, modify the filesystem's ``get_block(create = false)``65implementation to use the new ``->iomap_begin`` implementation to map66file space for selected read operations.67Hide behind a debugging knob the ability to switch on the iomap mapping68functions for selected call paths.69It is necessary to write some code to fill out the bufferhead-based70mapping information from the ``iomap`` structure, but the new functions71can be tested without needing to implement any iomap APIs.72 73Once the read-only functions are working like this, convert each high74level file operation one by one to use iomap native APIs instead of75going through ``get_block()``.76Done one at a time, regressions should be self evident.77You *do* have a regression test baseline for fstests, right?78It is suggested to convert swap file activation, ``SEEK_DATA``, and79``SEEK_HOLE`` before tackling the I/O paths.80A likely complexity at this point will be converting the buffered read81I/O path because of bufferheads.82The buffered read I/O paths doesn't need to be converted yet, though the83direct I/O read path should be converted in this phase.84 85At this point, you should look over your ``->iomap_begin`` function.86If it switches between large blocks of code based on dispatching of the87``flags`` argument, you should consider breaking it up into88per-operation iomap ops with smaller, more cohesive functions.89XFS is a good example of this.90 91The next thing to do is implement ``get_blocks(create == true)``92functionality in the ``->iomap_begin``/``->iomap_end`` methods.93It is strongly recommended to create separate mapping functions and94iomap ops for write operations.95Then convert the direct I/O write path to iomap, and start running fsx96w/ DIO enabled in earnest on filesystem.97This will flush out lots of data integrity corner case bugs that the new98write mapping implementation introduces.99 100Now, convert any remaining file operations to call the iomap functions.101This will get the entire filesystem using the new mapping functions, and102they should largely be debugged and working correctly after this step.103 104Most likely at this point, the buffered read and write paths will still105need to be converted.106The mapping functions should all work correctly, so all that needs to be107done is rewriting all the code that interfaces with bufferheads to108interface with iomap and folios.109It is much easier first to get regular file I/O (without any fancy110features like fscrypt, fsverity, compression, or data=journaling)111converted to use iomap.112Some of those fancy features (fscrypt and compression) aren't113implemented yet in iomap.114For unjournalled filesystems that use the pagecache for symbolic links115and directories, you might also try converting their handling to iomap.116 117The rest is left as an exercise for the reader, as it will be different118for every filesystem.119If you encounter problems, email the people and lists in120``get_maintainers.pl`` for help.121