How the Linux kernel's iomap layer works

An LWN.net feature demystifies the Linux kernel's iomap layer, a component frequently mentioned in filesystem discussions but rarely explained in detail. Introduced by Christoph Hellwig in the 4.8 kernel, building on earlier work by Dave Chinner in XFS, iomap has grown into a dozen files under fs/iomap organized as two layers: a low-level mapping between files and their backing store, and higher-level code that implements common filesystem operations on top of it, removing a lot of duplicated boilerplate from individual filesystems.

The piece explains why the older buffer-head model struggles with large files and extent-based filesystems, since a single contiguous extent might need hundreds of buffer heads that must be reassembled into efficient I/O. Iomap instead represents such mappings with a single struct iomap, using types like IOMAP_MAPPED, IOMAP_HOLE, IOMAP_DELALLOC, and IOMAP_UNWRITTEN to describe normal mappings, unallocated holes, delayed allocations, and unwritten blocks. Filesystems populate these mappings through iomap_begin() and iomap_end() callbacks tied to specific I/O operations.

The author notes that while iomap provides many useful I/O helper functions, they are largely undocumented, forcing developers to read source code to understand their use — possibly one reason the migration of filesystems to iomap has taken time. The topic matters to kernel and filesystem engineers because it clarifies a core abstraction underpinning modern storage I/O performance and code maintainability.