Loading...
Note: File does not exist in v3.15.
1.. SPDX-License-Identifier: GPL-2.0
2.. _iomap_operations:
3
4..
5 Dumb style notes to maintain the author's sanity:
6 Please try to start sentences on separate lines so that
7 sentence changes don't bleed colors in diff.
8 Heading decorations are documented in sphinx.rst.
9
10=========================
11Supported File Operations
12=========================
13
14.. contents:: Table of Contents
15 :local:
16
17Below are a discussion of the high level file operations that iomap
18implements.
19
20Buffered I/O
21============
22
23Buffered I/O is the default file I/O path in Linux.
24File contents are cached in memory ("pagecache") to satisfy reads and
25writes.
26Dirty cache will be written back to disk at some point that can be
27forced via ``fsync`` and variants.
28
29iomap implements nearly all the folio and pagecache management that
30filesystems have to implement themselves under the legacy I/O model.
31This means that the filesystem need not know the details of allocating,
32mapping, managing uptodate and dirty state, or writeback of pagecache
33folios.
34Under the legacy I/O model, this was managed very inefficiently with
35linked lists of buffer heads instead of the per-folio bitmaps that iomap
36uses.
37Unless the filesystem explicitly opts in to buffer heads, they will not
38be used, which makes buffered I/O much more efficient, and the pagecache
39maintainer much happier.
40
41``struct address_space_operations``
42-----------------------------------
43
44The following iomap functions can be referenced directly from the
45address space operations structure:
46
47 * ``iomap_dirty_folio``
48 * ``iomap_release_folio``
49 * ``iomap_invalidate_folio``
50 * ``iomap_is_partially_uptodate``
51
52The following address space operations can be wrapped easily:
53
54 * ``read_folio``
55 * ``readahead``
56 * ``writepages``
57 * ``bmap``
58 * ``swap_activate``
59
60``struct iomap_folio_ops``
61--------------------------
62
63The ``->iomap_begin`` function for pagecache operations may set the
64``struct iomap::folio_ops`` field to an ops structure to override
65default behaviors of iomap:
66
67.. code-block:: c
68
69 struct iomap_folio_ops {
70 struct folio *(*get_folio)(struct iomap_iter *iter, loff_t pos,
71 unsigned len);
72 void (*put_folio)(struct inode *inode, loff_t pos, unsigned copied,
73 struct folio *folio);
74 bool (*iomap_valid)(struct inode *inode, const struct iomap *iomap);
75 };
76
77iomap calls these functions:
78
79 - ``get_folio``: Called to allocate and return an active reference to
80 a locked folio prior to starting a write.
81 If this function is not provided, iomap will call
82 ``iomap_get_folio``.
83 This could be used to `set up per-folio filesystem state
84 <https://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/>`_
85 for a write.
86
87 - ``put_folio``: Called to unlock and put a folio after a pagecache
88 operation completes.
89 If this function is not provided, iomap will ``folio_unlock`` and
90 ``folio_put`` on its own.
91 This could be used to `commit per-folio filesystem state
92 <https://lore.kernel.org/all/20180619164137.13720-6-hch@lst.de/>`_
93 that was set up by ``->get_folio``.
94
95 - ``iomap_valid``: The filesystem may not hold locks between
96 ``->iomap_begin`` and ``->iomap_end`` because pagecache operations
97 can take folio locks, fault on userspace pages, initiate writeback
98 for memory reclamation, or engage in other time-consuming actions.
99 If a file's space mapping data are mutable, it is possible that the
100 mapping for a particular pagecache folio can `change in the time it
101 takes
102 <https://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/>`_
103 to allocate, install, and lock that folio.
104
105 For the pagecache, races can happen if writeback doesn't take
106 ``i_rwsem`` or ``invalidate_lock`` and updates mapping information.
107 Races can also happen if the filesytem allows concurrent writes.
108 For such files, the mapping *must* be revalidated after the folio
109 lock has been taken so that iomap can manage the folio correctly.
110
111 fsdax does not need this revalidation because there's no writeback
112 and no support for unwritten extents.
113
114 Filesystems subject to this kind of race must provide a
115 ``->iomap_valid`` function to decide if the mapping is still valid.
116 If the mapping is not valid, the mapping will be sampled again.
117
118 To support making the validity decision, the filesystem's
119 ``->iomap_begin`` function may set ``struct iomap::validity_cookie``
120 at the same time that it populates the other iomap fields.
121 A simple validation cookie implementation is a sequence counter.
122 If the filesystem bumps the sequence counter every time it modifies
123 the inode's extent map, it can be placed in the ``struct
124 iomap::validity_cookie`` during ``->iomap_begin``.
125 If the value in the cookie is found to be different to the value
126 the filesystem holds when the mapping is passed back to
127 ``->iomap_valid``, then the iomap should considered stale and the
128 validation failed.
129
130These ``struct kiocb`` flags are significant for buffered I/O with iomap:
131
132 * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.
133
134Internal per-Folio State
135------------------------
136
137If the fsblock size matches the size of a pagecache folio, it is assumed
138that all disk I/O operations will operate on the entire folio.
139The uptodate (memory contents are at least as new as what's on disk) and
140dirty (memory contents are newer than what's on disk) status of the
141folio are all that's needed for this case.
142
143If the fsblock size is less than the size of a pagecache folio, iomap
144tracks the per-fsblock uptodate and dirty state itself.
145This enables iomap to handle both "bs < ps" `filesystems
146<https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_
147and large folios in the pagecache.
148
149iomap internally tracks two state bits per fsblock:
150
151 * ``uptodate``: iomap will try to keep folios fully up to date.
152 If there are read(ahead) errors, those fsblocks will not be marked
153 uptodate.
154 The folio itself will be marked uptodate when all fsblocks within the
155 folio are uptodate.
156
157 * ``dirty``: iomap will set the per-block dirty state when programs
158 write to the file.
159 The folio itself will be marked dirty when any fsblock within the
160 folio is dirty.
161
162iomap also tracks the amount of read and write disk IOs that are in
163flight.
164This structure is much lighter weight than ``struct buffer_head``
165because there is only one per folio, and the per-fsblock overhead is two
166bits vs. 104 bytes.
167
168Filesystems wishing to turn on large folios in the pagecache should call
169``mapping_set_large_folios`` when initializing the incore inode.
170
171Buffered Readahead and Reads
172----------------------------
173
174The ``iomap_readahead`` function initiates readahead to the pagecache.
175The ``iomap_read_folio`` function reads one folio's worth of data into
176the pagecache.
177The ``flags`` argument to ``->iomap_begin`` will be set to zero.
178The pagecache takes whatever locks it needs before calling the
179filesystem.
180
181Buffered Writes
182---------------
183
184The ``iomap_file_buffered_write`` function writes an ``iocb`` to the
185pagecache.
186``IOMAP_WRITE`` or ``IOMAP_WRITE`` | ``IOMAP_NOWAIT`` will be passed as
187the ``flags`` argument to ``->iomap_begin``.
188Callers commonly take ``i_rwsem`` in either shared or exclusive mode
189before calling this function.
190
191mmap Write Faults
192~~~~~~~~~~~~~~~~~
193
194The ``iomap_page_mkwrite`` function handles a write fault to a folio in
195the pagecache.
196``IOMAP_WRITE | IOMAP_FAULT`` will be passed as the ``flags`` argument
197to ``->iomap_begin``.
198Callers commonly take the mmap ``invalidate_lock`` in shared or
199exclusive mode before calling this function.
200
201Buffered Write Failures
202~~~~~~~~~~~~~~~~~~~~~~~
203
204After a short write to the pagecache, the areas not written will not
205become marked dirty.
206The filesystem must arrange to `cancel
207<https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_
208such `reservations
209<https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_
210because writeback will not consume the reservation.
211The ``iomap_write_delalloc_release`` can be called from a
212``->iomap_end`` function to find all the clean areas of the folios
213caching a fresh (``IOMAP_F_NEW``) delalloc mapping.
214It takes the ``invalidate_lock``.
215
216The filesystem must supply a function ``punch`` to be called for
217each file range in this state.
218This function must *only* remove delayed allocation reservations, in
219case another thread racing with the current thread writes successfully
220to the same region and triggers writeback to flush the dirty data out to
221disk.
222
223Zeroing for File Operations
224~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
226Filesystems can call ``iomap_zero_range`` to perform zeroing of the
227pagecache for non-truncation file operations that are not aligned to
228the fsblock size.
229``IOMAP_ZERO`` will be passed as the ``flags`` argument to
230``->iomap_begin``.
231Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
232mode before calling this function.
233
234Unsharing Reflinked File Data
235~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236
237Filesystems can call ``iomap_file_unshare`` to force a file sharing
238storage with another file to preemptively copy the shared data to newly
239allocate storage.
240``IOMAP_WRITE | IOMAP_UNSHARE`` will be passed as the ``flags`` argument
241to ``->iomap_begin``.
242Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
243mode before calling this function.
244
245Truncation
246----------
247
248Filesystems can call ``iomap_truncate_page`` to zero the bytes in the
249pagecache from EOF to the end of the fsblock during a file truncation
250operation.
251``truncate_setsize`` or ``truncate_pagecache`` will take care of
252everything after the EOF block.
253``IOMAP_ZERO`` will be passed as the ``flags`` argument to
254``->iomap_begin``.
255Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
256mode before calling this function.
257
258Pagecache Writeback
259-------------------
260
261Filesystems can call ``iomap_writepages`` to respond to a request to
262write dirty pagecache folios to disk.
263The ``mapping`` and ``wbc`` parameters should be passed unchanged.
264The ``wpc`` pointer should be allocated by the filesystem and must
265be initialized to zero.
266
267The pagecache will lock each folio before trying to schedule it for
268writeback.
269It does not lock ``i_rwsem`` or ``invalidate_lock``.
270
271The dirty bit will be cleared for all folios run through the
272``->map_blocks`` machinery described below even if the writeback fails.
273This is to prevent dirty folio clots when storage devices fail; an
274``-EIO`` is recorded for userspace to collect via ``fsync``.
275
276The ``ops`` structure must be specified and is as follows:
277
278``struct iomap_writeback_ops``
279~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280
281.. code-block:: c
282
283 struct iomap_writeback_ops {
284 int (*map_blocks)(struct iomap_writepage_ctx *wpc, struct inode *inode,
285 loff_t offset, unsigned len);
286 int (*prepare_ioend)(struct iomap_ioend *ioend, int status);
287 void (*discard_folio)(struct folio *folio, loff_t pos);
288 };
289
290The fields are as follows:
291
292 - ``map_blocks``: Sets ``wpc->iomap`` to the space mapping of the file
293 range (in bytes) given by ``offset`` and ``len``.
294 iomap calls this function for each dirty fs block in each dirty folio,
295 though it will `reuse mappings
296 <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_
297 for runs of contiguous dirty fsblocks within a folio.
298 Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end``
299 function must deal with persisting written data.
300 Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently
301 requires mapping to allocated space.
302 Filesystems can skip a potentially expensive mapping lookup if the
303 mappings have not changed.
304 This revalidation must be open-coded by the filesystem; it is
305 unclear if ``iomap::validity_cookie`` can be reused for this
306 purpose.
307 This function must be supplied by the filesystem.
308
309 - ``prepare_ioend``: Enables filesystems to transform the writeback
310 ioend or perform any other preparatory work before the writeback I/O
311 is submitted.
312 This might include pre-write space accounting updates, or installing
313 a custom ``->bi_end_io`` function for internal purposes, such as
314 deferring the ioend completion to a workqueue to run metadata update
315 transactions from process context.
316 This function is optional.
317
318 - ``discard_folio``: iomap calls this function after ``->map_blocks``
319 fails to schedule I/O for any part of a dirty folio.
320 The function should throw away any reservations that may have been
321 made for the write.
322 The folio will be marked clean and an ``-EIO`` recorded in the
323 pagecache.
324 Filesystems can use this callback to `remove
325 <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_
326 delalloc reservations to avoid having delalloc reservations for
327 clean pagecache.
328 This function is optional.
329
330Pagecache Writeback Completion
331~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
332
333To handle the bookkeeping that must happen after disk I/O for writeback
334completes, iomap creates chains of ``struct iomap_ioend`` objects that
335wrap the ``bio`` that is used to write pagecache data to disk.
336By default, iomap finishes writeback ioends by clearing the writeback
337bit on the folios attached to the ``ioend``.
338If the write failed, it will also set the error bits on the folios and
339the address space.
340This can happen in interrupt or process context, depending on the
341storage device.
342
343Filesystems that need to update internal bookkeeping (e.g. unwritten
344extent conversions) should provide a ``->prepare_ioend`` function to
345set ``struct iomap_end::bio::bi_end_io`` to its own function.
346This function should call ``iomap_finish_ioends`` after finishing its
347own work (e.g. unwritten extent conversion).
348
349Some filesystems may wish to `amortize the cost of running metadata
350transactions
351<https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_
352for post-writeback updates by batching them.
353They may also require transactions to run from process context, which
354implies punting batches to a workqueue.
355iomap ioends contain a ``list_head`` to enable batching.
356
357Given a batch of ioends, iomap has a few helpers to assist with
358amortization:
359
360 * ``iomap_sort_ioends``: Sort all the ioends in the list by file
361 offset.
362
363 * ``iomap_ioend_try_merge``: Given an ioend that is not in any list and
364 a separate list of sorted ioends, merge as many of the ioends from
365 the head of the list into the given ioend.
366 ioends can only be merged if the file range and storage addresses are
367 contiguous; the unwritten and shared status are the same; and the
368 write I/O outcome is the same.
369 The merged ioends become their own list.
370
371 * ``iomap_finish_ioends``: Finish an ioend that possibly has other
372 ioends linked to it.
373
374Direct I/O
375==========
376
377In Linux, direct I/O is defined as file I/O that is issued directly to
378storage, bypassing the pagecache.
379The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and
380writes for files.
381
382.. code-block:: c
383
384 ssize_t iomap_dio_rw(struct kiocb *iocb, struct iov_iter *iter,
385 const struct iomap_ops *ops,
386 const struct iomap_dio_ops *dops,
387 unsigned int dio_flags, void *private,
388 size_t done_before);
389
390The filesystem can provide the ``dops`` parameter if it needs to perform
391extra work before or after the I/O is issued to storage.
392The ``done_before`` parameter tells the how much of the request has
393already been transferred.
394It is used to continue a request asynchronously when `part of the
395request
396<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c03098d4b9ad76bca2966a8769dcfe59f7f85103>`_
397has already been completed synchronously.
398
399The ``done_before`` parameter should be set if writes for the ``iocb``
400have been initiated prior to the call.
401The direction of the I/O is determined from the ``iocb`` passed in.
402
403The ``dio_flags`` argument can be set to any combination of the
404following values:
405
406 * ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the
407 kiocb is not synchronous.
408
409 * ``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range
410 or fail with ``-EAGAIN``.
411 This can be used by filesystems with complex unaligned I/O
412 write paths to provide an optimised fast path for unaligned writes.
413 If a pure overwrite can be performed, then serialisation against
414 other I/Os to the same filesystem block(s) is unnecessary as there is
415 no risk of stale data exposure or data loss.
416 If a pure overwrite cannot be performed, then the filesystem can
417 perform the serialisation steps needed to provide exclusive access
418 to the unaligned I/O range so that it can perform allocation and
419 sub-block zeroing safely.
420 Filesystems can use this flag to try to reduce locking contention,
421 but a lot of `detailed checking
422 <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_
423 is required to do it `correctly
424 <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.
425
426 * ``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever
427 progress has already been made.
428 The caller may deal with the page fault and retry the operation.
429 If the caller decides to retry the operation, it should pass the
430 accumulated return values of all previous calls as the
431 ``done_before`` parameter to the next call.
432
433These ``struct kiocb`` flags are significant for direct I/O with iomap:
434
435 * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.
436
437 * ``IOCB_SYNC``: Ensure that the device has persisted data to disk
438 before completing the call.
439 In the case of pure overwrites, the I/O may be issued with FUA
440 enabled.
441
442 * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an
443 interrupt.
444 Only meaningful for asynchronous I/O, and only if the entire I/O can
445 be issued as a single ``struct bio``.
446
447 * ``IOCB_DIO_CALLER_COMP``: Try to run I/O completion from the caller's
448 process context.
449 See ``linux/fs.h`` for more details.
450
451Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and
452``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open``
453function for the file.
454They should not set ``->direct_IO``, which is deprecated.
455
456If a filesystem wishes to perform its own work before direct I/O
457completion, it should call ``__iomap_dio_rw``.
458If its return value is not an error pointer or a NULL pointer, the
459filesystem should pass the return value to ``iomap_dio_complete`` after
460finishing its internal work.
461
462Return Values
463-------------
464
465``iomap_dio_rw`` can return one of the following:
466
467 * A non-negative number of bytes transferred.
468
469 * ``-ENOTBLK``: Fall back to buffered I/O.
470 iomap itself will return this value if it cannot invalidate the page
471 cache before issuing the I/O to storage.
472 The ``->iomap_begin`` or ``->iomap_end`` functions may also return
473 this value.
474
475 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
476 queued and will be completed separately.
477
478 * Any of the other negative error codes.
479
480Direct Reads
481------------
482
483A direct I/O read initiates a read I/O from the storage device to the
484caller's buffer.
485Dirty parts of the pagecache are flushed to storage before initiating
486the read io.
487The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with
488any combination of the following enhancements:
489
490 * ``IOMAP_NOWAIT``, as defined previously.
491
492Callers commonly hold ``i_rwsem`` in shared mode before calling this
493function.
494
495Direct Writes
496-------------
497
498A direct I/O write initiates a write I/O to the storage device from the
499caller's buffer.
500Dirty parts of the pagecache are flushed to storage before initiating
501the write io.
502The pagecache is invalidated both before and after the write io.
503The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT |
504IOMAP_WRITE`` with any combination of the following enhancements:
505
506 * ``IOMAP_NOWAIT``, as defined previously.
507
508 * ``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial
509 blocks is not allowed.
510 The entire file range must map to a single written or unwritten
511 extent.
512 The file I/O range must be aligned to the filesystem block size
513 if the mapping is unwritten and the filesystem cannot handle zeroing
514 the unaligned regions without exposing stale contents.
515
516 * ``IOMAP_ATOMIC``: This write is being issued with torn-write
517 protection.
518 Only a single bio can be created for the write, and the write must
519 not be split into multiple I/O requests, i.e. flag REQ_ATOMIC must be
520 set.
521 The file range to write must be aligned to satisfy the requirements
522 of both the filesystem and the underlying block device's atomic
523 commit capabilities.
524 If filesystem metadata updates are required (e.g. unwritten extent
525 conversion or copy on write), all updates for the entire file range
526 must be committed atomically as well.
527 Only one space mapping is allowed per untorn write.
528 Untorn writes must be aligned to, and must not be longer than, a
529 single file block.
530
531Callers commonly hold ``i_rwsem`` in shared or exclusive mode before
532calling this function.
533
534``struct iomap_dio_ops:``
535-------------------------
536.. code-block:: c
537
538 struct iomap_dio_ops {
539 void (*submit_io)(const struct iomap_iter *iter, struct bio *bio,
540 loff_t file_offset);
541 int (*end_io)(struct kiocb *iocb, ssize_t size, int error,
542 unsigned flags);
543 struct bio_set *bio_set;
544 };
545
546The fields of this structure are as follows:
547
548 - ``submit_io``: iomap calls this function when it has constructed a
549 ``struct bio`` object for the I/O requested, and wishes to submit it
550 to the block device.
551 If no function is provided, ``submit_bio`` will be called directly.
552 Filesystems that would like to perform additional work before (e.g.
553 data replication for btrfs) should implement this function.
554
555 - ``end_io``: This is called after the ``struct bio`` completes.
556 This function should perform post-write conversions of unwritten
557 extent mappings, handle write failures, etc.
558 The ``flags`` argument may be set to a combination of the following:
559
560 * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend
561 should mark the extent as written.
562
563 * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a
564 copy on write operation, so the ioend should switch mappings.
565
566 - ``bio_set``: This allows the filesystem to provide a custom bio_set
567 for allocating direct I/O bios.
568 This enables filesystems to `stash additional per-bio information
569 <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_
570 for private use.
571 If this field is NULL, generic ``struct bio`` objects will be used.
572
573Filesystems that want to perform extra work after an I/O completion
574should set a custom ``->bi_end_io`` function via ``->submit_io``.
575Afterwards, the custom endio function must call
576``iomap_dio_bio_end_io`` to finish the direct I/O.
577
578DAX I/O
579=======
580
581Some storage devices can be directly mapped as memory.
582These devices support a new access mode known as "fsdax" that allows
583loads and stores through the CPU and memory controller.
584
585fsdax Reads
586-----------
587
588A fsdax read performs a memcpy from storage device to the caller's
589buffer.
590The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any
591combination of the following enhancements:
592
593 * ``IOMAP_NOWAIT``, as defined previously.
594
595Callers commonly hold ``i_rwsem`` in shared mode before calling this
596function.
597
598fsdax Writes
599------------
600
601A fsdax write initiates a memcpy to the storage device from the caller's
602buffer.
603The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |
604IOMAP_WRITE`` with any combination of the following enhancements:
605
606 * ``IOMAP_NOWAIT``, as defined previously.
607
608 * ``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be
609 performed from this mapping.
610 This requires the filesystem extent mapping to already exist as an
611 ``IOMAP_MAPPED`` type and span the entire range of the write I/O
612 request.
613 If the filesystem cannot map this request in a way that allows the
614 iomap infrastructure to perform a pure overwrite, it must fail the
615 mapping operation with ``-EAGAIN``.
616
617Callers commonly hold ``i_rwsem`` in exclusive mode before calling this
618function.
619
620fsdax mmap Faults
621~~~~~~~~~~~~~~~~~
622
623The ``dax_iomap_fault`` function handles read and write faults to fsdax
624storage.
625For a read fault, ``IOMAP_DAX | IOMAP_FAULT`` will be passed as the
626``flags`` argument to ``->iomap_begin``.
627For a write fault, ``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE`` will be
628passed as the ``flags`` argument to ``->iomap_begin``.
629
630Callers commonly hold the same locks as they do to call their iomap
631pagecache counterparts.
632
633fsdax Truncation, fallocate, and Unsharing
634------------------------------------------
635
636For fsdax files, the following functions are provided to replace their
637iomap pagecache I/O counterparts.
638The ``flags`` argument to ``->iomap_begin`` are the same as the
639pagecache counterparts, with ``IOMAP_DAX`` added.
640
641 * ``dax_file_unshare``
642 * ``dax_zero_range``
643 * ``dax_truncate_page``
644
645Callers commonly hold the same locks as they do to call their iomap
646pagecache counterparts.
647
648fsdax Deduplication
649-------------------
650
651Filesystems implementing the ``FIDEDUPERANGE`` ioctl must call the
652``dax_remap_file_range_prep`` function with their own iomap read ops.
653
654Seeking Files
655=============
656
657iomap implements the two iterating whence modes of the ``llseek`` system
658call.
659
660SEEK_DATA
661---------
662
663The ``iomap_seek_data`` function implements the SEEK_DATA "whence" value
664for llseek.
665``IOMAP_REPORT`` will be passed as the ``flags`` argument to
666``->iomap_begin``.
667
668For unwritten mappings, the pagecache will be searched.
669Regions of the pagecache with a folio mapped and uptodate fsblocks
670within those folios will be reported as data areas.
671
672Callers commonly hold ``i_rwsem`` in shared mode before calling this
673function.
674
675SEEK_HOLE
676---------
677
678The ``iomap_seek_hole`` function implements the SEEK_HOLE "whence" value
679for llseek.
680``IOMAP_REPORT`` will be passed as the ``flags`` argument to
681``->iomap_begin``.
682
683For unwritten mappings, the pagecache will be searched.
684Regions of the pagecache with no folio mapped, or a !uptodate fsblock
685within a folio will be reported as sparse hole areas.
686
687Callers commonly hold ``i_rwsem`` in shared mode before calling this
688function.
689
690Swap File Activation
691====================
692
693The ``iomap_swapfile_activate`` function finds all the base-page aligned
694regions in a file and sets them up as swap space.
695The file will be ``fsync()``'d before activation.
696``IOMAP_REPORT`` will be passed as the ``flags`` argument to
697``->iomap_begin``.
698All mappings must be mapped or unwritten; cannot be dirty or shared, and
699cannot span multiple block devices.
700Callers must hold ``i_rwsem`` in exclusive mode; this is already
701provided by ``swapon``.
702
703File Space Mapping Reporting
704============================
705
706iomap implements two of the file space mapping system calls.
707
708FS_IOC_FIEMAP
709-------------
710
711The ``iomap_fiemap`` function exports file extent mappings to userspace
712in the format specified by the ``FS_IOC_FIEMAP`` ioctl.
713``IOMAP_REPORT`` will be passed as the ``flags`` argument to
714``->iomap_begin``.
715Callers commonly hold ``i_rwsem`` in shared mode before calling this
716function.
717
718FIBMAP (deprecated)
719-------------------
720
721``iomap_bmap`` implements FIBMAP.
722The calling conventions are the same as for FIEMAP.
723This function is only provided to maintain compatibility for filesystems
724that implemented FIBMAP prior to conversion.
725This ioctl is deprecated; do **not** add a FIBMAP implementation to
726filesystems that do not have it.
727Callers should probably hold ``i_rwsem`` in shared mode before calling
728this function, but this is unclear.