1 .. SPDX-License-Identifier: GPL-2.0
2 .. _iomap_porting:
3
4 ..
5 Dumb style notes to maintain the autho
6 Please try to start sentences on separ
7 sentence changes don't bleed colors in
8 Heading decorations are documented in
9
10 =======================
11 Porting Your Filesystem
12 =======================
13
14 .. contents:: Table of Contents
15 :local:
16
17 Why Convert?
18 ============
19
20 There are several reasons to convert a filesys
21
22 1. The classic Linux I/O path is not terribly
23 Pagecache operations lock a single base pa
24 into the filesystem to return a mapping fo
25 Direct I/O operations build I/O requests a
26 time.
27 This worked well enough for direct/indirec
28 as ext2, but is very inefficient for exten
29 as XFS.
30
31 2. Large folios are only supported via iomap;
32 convert the old buffer_head path to use th
33
34 3. Direct access to storage on memory-like de
35 supported via iomap.
36
37 4. Lower maintenance overhead for individual
38 iomap handles common pagecache related ope
39 allocating, instantiating, locking, and un
40 No ->write_begin(), ->write_end() or direc
41 address_space_operations are required to b
42 filesystem using iomap.
43
44 How Do I Convert a Filesystem?
45 ==============================
46
47 First, add ``#include <linux/iomap.h>`` from y
48 ``select FS_IOMAP`` to your filesystem's Kconf
49 Build the kernel, run fstests with the ``-g al
50 variety of your filesystem's supported configu
51 baseline of which tests pass and which ones fa
52
53 The recommended approach is first to implement
54 ``->iomap_end`` if necessary) to allow iomap t
55 mapping of a file range.
56 In most cases, this is a relatively trivial co
57 ``get_block()`` function for read-only mapping
58 ``FS_IOC_FIEMAP`` is a good first target becau
59 implement support for it and then to determine
60 iteration is correct from userspace.
61 If FIEMAP is returning the correct information
62 other read-only mapping operations will do the
63
64 Next, modify the filesystem's ``get_block(crea
65 implementation to use the new ``->iomap_begin`
66 file space for selected read operations.
67 Hide behind a debugging knob the ability to sw
68 functions for selected call paths.
69 It is necessary to write some code to fill out
70 mapping information from the ``iomap`` structu
71 can be tested without needing to implement any
72
73 Once the read-only functions are working like
74 level file operation one by one to use iomap n
75 going through ``get_block()``.
76 Done one at a time, regressions should be self
77 You *do* have a regression test baseline for f
78 It is suggested to convert swap file activatio
79 ``SEEK_HOLE`` before tackling the I/O paths.
80 A likely complexity at this point will be conv
81 I/O path because of bufferheads.
82 The buffered read I/O paths doesn't need to be
83 direct I/O read path should be converted in th
84
85 At this point, you should look over your ``->i
86 If it switches between large blocks of code ba
87 ``flags`` argument, you should consider breaki
88 per-operation iomap ops with smaller, more coh
89 XFS is a good example of this.
90
91 The next thing to do is implement ``get_blocks
92 functionality in the ``->iomap_begin``/``->iom
93 It is strongly recommended to create separate
94 iomap ops for write operations.
95 Then convert the direct I/O write path to ioma
96 w/ DIO enabled in earnest on filesystem.
97 This will flush out lots of data integrity cor
98 write mapping implementation introduces.
99
100 Now, convert any remaining file operations to
101 This will get the entire filesystem using the
102 they should largely be debugged and working co
103
104 Most likely at this point, the buffered read a
105 need to be converted.
106 The mapping functions should all work correctl
107 done is rewriting all the code that interfaces
108 interface with iomap and folios.
109 It is much easier first to get regular file I/
110 features like fscrypt, fsverity, compression,
111 converted to use iomap.
112 Some of those fancy features (fscrypt and comp
113 implemented yet in iomap.
114 For unjournalled filesystems that use the page
115 and directories, you might also try converting
116
117 The rest is left as an exercise for the reader
118 for every filesystem.
119 If you encounter problems, email the people an
120 ``get_maintainers.pl`` for help.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.