3.1.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 callinto the filesystem to return a mapping for only that page.Direct I/O operations build I/O requests a single file block at atime.This worked well enough for direct/indirect-mapped filesystems suchas ext2, but is very inefficient for extent-based filesystems suchas XFS.

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

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

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

3.2.How Do I Convert a Filesystem?¶

First, add#include<linux/iomap.h> from your source code and addselectFS_IOMAP to your filesystem’s Kconfig option.Build the kernel, run fstests with the-gall option across a widevariety of your filesystem’s supported configurations to build abaseline 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-onlymapping of a file range.In most cases, this is a relatively trivial conversion of the existingget_block() function for read-only mappings.FS_IOC_FIEMAP is a good first target because it is trivial toimplement support for it and then to determine that the extent mapiteration is correct from userspace.If FIEMAP is returning the correct information, it’s a good sign thatother read-only mapping operations will do the right thing.

Next, modify the filesystem’sget_block(create=false)implementation to use the new->iomap_begin implementation to mapfile space for selected read operations.Hide behind a debugging knob the ability to switch on the iomap mappingfunctions for selected call paths.It is necessary to write some code to fill out the bufferhead-basedmapping information from theiomap structure, but the new functionscan be tested without needing to implement any iomap APIs.

Once the read-only functions are working like this, convert each highlevel file operation one by one to use iomap native APIs instead ofgoing throughget_block().Done one at a time, regressions should be self evident.Youdo have a regression test baseline for fstests, right?It is suggested to convert swap file activation,SEEK_DATA, andSEEK_HOLE before tackling the I/O paths.A likely complexity at this point will be converting the buffered readI/O path because of bufferheads.The buffered read I/O paths doesn’t need to be converted yet, though thedirect I/O read path should be converted in this phase.

At this point, you should look over your->iomap_begin function.If it switches between large blocks of code based on dispatching of theflags argument, you should consider breaking it up intoper-operation iomap ops with smaller, more cohesive functions.XFS is a good example of this.

The next thing to do is implementget_blocks(create==true)functionality in the->iomap_begin/->iomap_end methods.It is strongly recommended to create separate mapping functions andiomap ops for write operations.Then convert the direct I/O write path to iomap, and start running fsxw/ DIO enabled in earnest on filesystem.This will flush out lots of data integrity corner case bugs that the newwrite mapping implementation introduces.

Now, convert any remaining file operations to call the iomap functions.This will get the entire filesystem using the new mapping functions, andthey should largely be debugged and working correctly after this step.

Most likely at this point, the buffered read and write paths will stillneed to be converted.The mapping functions should all work correctly, so all that needs to bedone is rewriting all the code that interfaces with bufferheads tointerface with iomap and folios.It is much easier first to get regular file I/O (without any fancyfeatures like fscrypt, fsverity, compression, or data=journaling)converted to use iomap.Some of those fancy features (fscrypt and compression) aren’timplemented yet in iomap.For unjournalled filesystems that use the pagecache for symbolic linksand directories, you might also try converting their handling to iomap.

The rest is left as an exercise for the reader, as it will be differentfor every filesystem.If you encounter problems, email the people and lists inget_maintainers.pl for help.