iomap

iomap grew out of need to provide modern block mapping abstraction for filesystems to read/write for three different IO access methods:

• Direct IO
• Buffered IO
• DAX

Block mapping provides a mapping between data cached in memory, in the page cache, and the location on persistent storage where that data lives. LWN has an incredible review of the old buffer-heads block-mapping and why they are inefficient, since the the inception of Linux. Since buffer-heads work on a 512-byte block based paradigm, it creates an overhead for modern storage media which no longer necessarily works only on 512-blocks. This document strives to provide a template for LSFMM for what will hopefully eventually become upstream Linux kernel documentation for iomap and guidance for developers on converting a filesystem over from buffer-heads to iomap.

A modern block abstraction

Instead of assuming a granularity of storage media 512-blocks at time, iomap allows filesystems to query storage media for data using block ranges. Since block mapping are provided for a block ranges for cache data in memory, in the page cache, naturally this implies operations on block ranges will also deal with multipage operations in the page cache. Folios are used to help provide multipage operations in memory.

struct iomap_ops

A filesystem is encouraged to provide struct iomap_ops for beginning an IO operation and ending an IO operation on a block range, and so the struct iomap_ops data structure has iomap_begin() and iomap_end() callbacks.

Experience in adopting iomap on XFS has has shown that the filesystem implementation of these operations can be simplified considerably if one struct iomap_ops is provided per major filesystem IO operation:

• read
• direct writes
• DAX writes
• buffered writes
• xattr - FIEMAP_FLAG_XATTR
• seek

In terms of simplicity, you may convert a filesystem in this order instead:

For example:

• struct iomap_ops xfs_read_iomap_ops` iomap: lift the xfs writeback code to iomap

• struct iomap_ops xfs_direct_write_iomap_ops

• struct iomap_ops xfs_dax_write_iomap_ops

• struct iomap_ops xfs_buffered_write_iomap_ops - xfs: split out a new set of read-only iomap ops

• struct iomap_ops xfs_xattr_iomap_ops - xfs: fix SEEK_DATA for speculative COW fork preallocation

• struct iomap_ops xfs_seek_iomap_ops - iomap: move the iomap_dio_rw ->end_io callback into a structure

struct iomap_dio_ops

Used for Direct-IO. These will call iomap_dio_write().

• struct iomap_dio_ops xfs_dio_write_ops->end_io() - iomap: add a filesystem hook for direct I/O bio submission

• struct iomap_dio_ops xfs_dio_write_ops->submit_io() - xfs: split the iomap ops for buffered vs direct writes

struct iomap_writeback_ops

• struct iomap_writeback_ops xfs_writeback_ops - xfs: support CoW in fsdax mode

Converting filesystems from buffer-head to iomap guide

One op at at time

You may try to convert a filesystem IO operation at time, for instance this order reflects the order in which XFS started converting over to iomap:

• xattr
• seek
• direct writes
• buffered writes
• read
• DAX writes

Defining a simple filesystem

The easiest