714 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. _iomap_operations:3 4..5 Dumb style notes to maintain the author's sanity:6 Please try to start sentences on separate lines so that7 sentence changes don't bleed colors in diff.8 Heading decorations are documented in sphinx.rst.9 10=========================11Supported File Operations12=========================13 14.. contents:: Table of Contents15 :local:16 17Below are a discussion of the high level file operations that iomap18implements.19 20Buffered I/O21============22 23Buffered I/O is the default file I/O path in Linux.24File contents are cached in memory ("pagecache") to satisfy reads and25writes.26Dirty cache will be written back to disk at some point that can be27forced via ``fsync`` and variants.28 29iomap implements nearly all the folio and pagecache management that30filesystems 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 pagecache33folios.34Under the legacy I/O model, this was managed very inefficiently with35linked lists of buffer heads instead of the per-folio bitmaps that iomap36uses.37Unless the filesystem explicitly opts in to buffer heads, they will not38be used, which makes buffered I/O much more efficient, and the pagecache39maintainer much happier.40 41``struct address_space_operations``42-----------------------------------43 44The following iomap functions can be referenced directly from the45address 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 the64``struct iomap::folio_ops`` field to an ops structure to override65default behaviors of iomap:66 67.. code-block:: c68 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 to80 a locked folio prior to starting a write.81 If this function is not provided, iomap will call82 ``iomap_get_folio``.83 This could be used to `set up per-folio filesystem state84 <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 pagecache88 operation completes.89 If this function is not provided, iomap will ``folio_unlock`` and90 ``folio_put`` on its own.91 This could be used to `commit per-folio filesystem state92 <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 between96 ``->iomap_begin`` and ``->iomap_end`` because pagecache operations97 can take folio locks, fault on userspace pages, initiate writeback98 for memory reclamation, or engage in other time-consuming actions.99 If a file's space mapping data are mutable, it is possible that the100 mapping for a particular pagecache folio can `change in the time it101 takes102 <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 take106 ``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 folio109 lock has been taken so that iomap can manage the folio correctly.110 111 fsdax does not need this revalidation because there's no writeback112 and no support for unwritten extents.113 114 Filesystems subject to this kind of race must provide a115 ``->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's119 ``->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 modifies123 the inode's extent map, it can be placed in the ``struct124 iomap::validity_cookie`` during ``->iomap_begin``.125 If the value in the cookie is found to be different to the value126 the filesystem holds when the mapping is passed back to127 ``->iomap_valid``, then the iomap should considered stale and the128 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 State135------------------------136 137If the fsblock size matches the size of a pagecache folio, it is assumed138that 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) and140dirty (memory contents are newer than what's on disk) status of the141folio are all that's needed for this case.142 143If the fsblock size is less than the size of a pagecache folio, iomap144tracks the per-fsblock uptodate and dirty state itself.145This enables iomap to handle both "bs < ps" `filesystems146<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 marked153 uptodate.154 The folio itself will be marked uptodate when all fsblocks within the155 folio are uptodate.156 157 * ``dirty``: iomap will set the per-block dirty state when programs158 write to the file.159 The folio itself will be marked dirty when any fsblock within the160 folio is dirty.161 162iomap also tracks the amount of read and write disk IOs that are in163flight.164This structure is much lighter weight than ``struct buffer_head``165because there is only one per folio, and the per-fsblock overhead is two166bits vs. 104 bytes.167 168Filesystems wishing to turn on large folios in the pagecache should call169``mapping_set_large_folios`` when initializing the incore inode.170 171Buffered Readahead and Reads172----------------------------173 174The ``iomap_readahead`` function initiates readahead to the pagecache.175The ``iomap_read_folio`` function reads one folio's worth of data into176the pagecache.177The ``flags`` argument to ``->iomap_begin`` will be set to zero.178The pagecache takes whatever locks it needs before calling the179filesystem.180 181Buffered Writes182---------------183 184The ``iomap_file_buffered_write`` function writes an ``iocb`` to the185pagecache.186``IOMAP_WRITE`` or ``IOMAP_WRITE`` | ``IOMAP_NOWAIT`` will be passed as187the ``flags`` argument to ``->iomap_begin``.188Callers commonly take ``i_rwsem`` in either shared or exclusive mode189before calling this function.190 191mmap Write Faults192~~~~~~~~~~~~~~~~~193 194The ``iomap_page_mkwrite`` function handles a write fault to a folio in195the pagecache.196``IOMAP_WRITE | IOMAP_FAULT`` will be passed as the ``flags`` argument197to ``->iomap_begin``.198Callers commonly take the mmap ``invalidate_lock`` in shared or199exclusive mode before calling this function.200 201Buffered Write Failures202~~~~~~~~~~~~~~~~~~~~~~~203 204After a short write to the pagecache, the areas not written will not205become marked dirty.206The filesystem must arrange to `cancel207<https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_208such `reservations209<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 a212``->iomap_end`` function to find all the clean areas of the folios213caching a fresh (``IOMAP_F_NEW``) delalloc mapping.214It takes the ``invalidate_lock``.215 216The filesystem must supply a function ``punch`` to be called for217each file range in this state.218This function must *only* remove delayed allocation reservations, in219case another thread racing with the current thread writes successfully220to the same region and triggers writeback to flush the dirty data out to221disk.222 223Zeroing for File Operations224~~~~~~~~~~~~~~~~~~~~~~~~~~~225 226Filesystems can call ``iomap_zero_range`` to perform zeroing of the227pagecache for non-truncation file operations that are not aligned to228the fsblock size.229``IOMAP_ZERO`` will be passed as the ``flags`` argument to230``->iomap_begin``.231Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive232mode before calling this function.233 234Unsharing Reflinked File Data235~~~~~~~~~~~~~~~~~~~~~~~~~~~~~236 237Filesystems can call ``iomap_file_unshare`` to force a file sharing238storage with another file to preemptively copy the shared data to newly239allocate storage.240``IOMAP_WRITE | IOMAP_UNSHARE`` will be passed as the ``flags`` argument241to ``->iomap_begin``.242Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive243mode before calling this function.244 245Truncation246----------247 248Filesystems can call ``iomap_truncate_page`` to zero the bytes in the249pagecache from EOF to the end of the fsblock during a file truncation250operation.251``truncate_setsize`` or ``truncate_pagecache`` will take care of252everything after the EOF block.253``IOMAP_ZERO`` will be passed as the ``flags`` argument to254``->iomap_begin``.255Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive256mode before calling this function.257 258Pagecache Writeback259-------------------260 261Filesystems can call ``iomap_writepages`` to respond to a request to262write dirty pagecache folios to disk.263The ``mapping`` and ``wbc`` parameters should be passed unchanged.264The ``wpc`` pointer should be allocated by the filesystem and must265be initialized to zero.266 267The pagecache will lock each folio before trying to schedule it for268writeback.269It does not lock ``i_rwsem`` or ``invalidate_lock``.270 271The dirty bit will be cleared for all folios run through the272``->map_blocks`` machinery described below even if the writeback fails.273This is to prevent dirty folio clots when storage devices fail; an274``-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:: c282 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 file293 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 mappings296 <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 currently301 requires mapping to allocated space.302 Filesystems can skip a potentially expensive mapping lookup if the303 mappings have not changed.304 This revalidation must be open-coded by the filesystem; it is305 unclear if ``iomap::validity_cookie`` can be reused for this306 purpose.307 This function must be supplied by the filesystem.308 309 - ``prepare_ioend``: Enables filesystems to transform the writeback310 ioend or perform any other preparatory work before the writeback I/O311 is submitted.312 This might include pre-write space accounting updates, or installing313 a custom ``->bi_end_io`` function for internal purposes, such as314 deferring the ioend completion to a workqueue to run metadata update315 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 been321 made for the write.322 The folio will be marked clean and an ``-EIO`` recorded in the323 pagecache.324 Filesystems can use this callback to `remove325 <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_326 delalloc reservations to avoid having delalloc reservations for327 clean pagecache.328 This function is optional.329 330Pagecache Writeback Completion331~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~332 333To handle the bookkeeping that must happen after disk I/O for writeback334completes, iomap creates chains of ``struct iomap_ioend`` objects that335wrap the ``bio`` that is used to write pagecache data to disk.336By default, iomap finishes writeback ioends by clearing the writeback337bit on the folios attached to the ``ioend``.338If the write failed, it will also set the error bits on the folios and339the address space.340This can happen in interrupt or process context, depending on the341storage device.342 343Filesystems that need to update internal bookkeeping (e.g. unwritten344extent conversions) should provide a ``->prepare_ioend`` function to345set ``struct iomap_end::bio::bi_end_io`` to its own function.346This function should call ``iomap_finish_ioends`` after finishing its347own work (e.g. unwritten extent conversion).348 349Some filesystems may wish to `amortize the cost of running metadata350transactions351<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, which354implies 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 with358amortization:359 360 * ``iomap_sort_ioends``: Sort all the ioends in the list by file361 offset.362 363 * ``iomap_ioend_try_merge``: Given an ioend that is not in any list and364 a separate list of sorted ioends, merge as many of the ioends from365 the head of the list into the given ioend.366 ioends can only be merged if the file range and storage addresses are367 contiguous; the unwritten and shared status are the same; and the368 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 other372 ioends linked to it.373 374Direct I/O375==========376 377In Linux, direct I/O is defined as file I/O that is issued directly to378storage, bypassing the pagecache.379The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and380writes for files.381 382.. code-block:: c383 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 perform391extra work before or after the I/O is issued to storage.392The ``done_before`` parameter tells the how much of the request has393already been transferred.394It is used to continue a request asynchronously when `part of the395request396<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 the404following values:405 406 * ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the407 kiocb is not synchronous.408 409 * ``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range410 or fail with ``-EAGAIN``.411 This can be used by filesystems with complex unaligned I/O412 write paths to provide an optimised fast path for unaligned writes.413 If a pure overwrite can be performed, then serialisation against414 other I/Os to the same filesystem block(s) is unnecessary as there is415 no risk of stale data exposure or data loss.416 If a pure overwrite cannot be performed, then the filesystem can417 perform the serialisation steps needed to provide exclusive access418 to the unaligned I/O range so that it can perform allocation and419 sub-block zeroing safely.420 Filesystems can use this flag to try to reduce locking contention,421 but a lot of `detailed checking422 <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_423 is required to do it `correctly424 <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.425 426 * ``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever427 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 the430 accumulated return values of all previous calls as the431 ``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 disk438 before completing the call.439 In the case of pure overwrites, the I/O may be issued with FUA440 enabled.441 442 * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an443 interrupt.444 Only meaningful for asynchronous I/O, and only if the entire I/O can445 be issued as a single ``struct bio``.446 447 * ``IOCB_DIO_CALLER_COMP``: Try to run I/O completion from the caller's448 process context.449 See ``linux/fs.h`` for more details.450 451Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and452``->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/O457completion, it should call ``__iomap_dio_rw``.458If its return value is not an error pointer or a NULL pointer, the459filesystem should pass the return value to ``iomap_dio_complete`` after460finishing its internal work.461 462Return Values463-------------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 page471 cache before issuing the I/O to storage.472 The ``->iomap_begin`` or ``->iomap_end`` functions may also return473 this value.474 475 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been476 queued and will be completed separately.477 478 * Any of the other negative error codes.479 480Direct Reads481------------482 483A direct I/O read initiates a read I/O from the storage device to the484caller's buffer.485Dirty parts of the pagecache are flushed to storage before initiating486the read io.487The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with488any combination of the following enhancements:489 490 * ``IOMAP_NOWAIT``, as defined previously.491 492Callers commonly hold ``i_rwsem`` in shared mode before calling this493function.494 495Direct Writes496-------------497 498A direct I/O write initiates a write I/O to the storage device from the499caller's buffer.500Dirty parts of the pagecache are flushed to storage before initiating501the 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 partial509 blocks is not allowed.510 The entire file range must map to a single written or unwritten511 extent.512 The file I/O range must be aligned to the filesystem block size513 if the mapping is unwritten and the filesystem cannot handle zeroing514 the unaligned regions without exposing stale contents.515 516Callers commonly hold ``i_rwsem`` in shared or exclusive mode before517calling this function.518 519``struct iomap_dio_ops:``520-------------------------521.. code-block:: c522 523 struct iomap_dio_ops {524 void (*submit_io)(const struct iomap_iter *iter, struct bio *bio,525 loff_t file_offset);526 int (*end_io)(struct kiocb *iocb, ssize_t size, int error,527 unsigned flags);528 struct bio_set *bio_set;529 };530 531The fields of this structure are as follows:532 533 - ``submit_io``: iomap calls this function when it has constructed a534 ``struct bio`` object for the I/O requested, and wishes to submit it535 to the block device.536 If no function is provided, ``submit_bio`` will be called directly.537 Filesystems that would like to perform additional work before (e.g.538 data replication for btrfs) should implement this function.539 540 - ``end_io``: This is called after the ``struct bio`` completes.541 This function should perform post-write conversions of unwritten542 extent mappings, handle write failures, etc.543 The ``flags`` argument may be set to a combination of the following:544 545 * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend546 should mark the extent as written.547 548 * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a549 copy on write operation, so the ioend should switch mappings.550 551 - ``bio_set``: This allows the filesystem to provide a custom bio_set552 for allocating direct I/O bios.553 This enables filesystems to `stash additional per-bio information554 <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_555 for private use.556 If this field is NULL, generic ``struct bio`` objects will be used.557 558Filesystems that want to perform extra work after an I/O completion559should set a custom ``->bi_end_io`` function via ``->submit_io``.560Afterwards, the custom endio function must call561``iomap_dio_bio_end_io`` to finish the direct I/O.562 563DAX I/O564=======565 566Some storage devices can be directly mapped as memory.567These devices support a new access mode known as "fsdax" that allows568loads and stores through the CPU and memory controller.569 570fsdax Reads571-----------572 573A fsdax read performs a memcpy from storage device to the caller's574buffer.575The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any576combination of the following enhancements:577 578 * ``IOMAP_NOWAIT``, as defined previously.579 580Callers commonly hold ``i_rwsem`` in shared mode before calling this581function.582 583fsdax Writes584------------585 586A fsdax write initiates a memcpy to the storage device from the caller's587buffer.588The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |589IOMAP_WRITE`` with any combination of the following enhancements:590 591 * ``IOMAP_NOWAIT``, as defined previously.592 593 * ``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be594 performed from this mapping.595 This requires the filesystem extent mapping to already exist as an596 ``IOMAP_MAPPED`` type and span the entire range of the write I/O597 request.598 If the filesystem cannot map this request in a way that allows the599 iomap infrastructure to perform a pure overwrite, it must fail the600 mapping operation with ``-EAGAIN``.601 602Callers commonly hold ``i_rwsem`` in exclusive mode before calling this603function.604 605fsdax mmap Faults606~~~~~~~~~~~~~~~~~607 608The ``dax_iomap_fault`` function handles read and write faults to fsdax609storage.610For a read fault, ``IOMAP_DAX | IOMAP_FAULT`` will be passed as the611``flags`` argument to ``->iomap_begin``.612For a write fault, ``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE`` will be613passed as the ``flags`` argument to ``->iomap_begin``.614 615Callers commonly hold the same locks as they do to call their iomap616pagecache counterparts.617 618fsdax Truncation, fallocate, and Unsharing619------------------------------------------620 621For fsdax files, the following functions are provided to replace their622iomap pagecache I/O counterparts.623The ``flags`` argument to ``->iomap_begin`` are the same as the624pagecache counterparts, with ``IOMAP_DAX`` added.625 626 * ``dax_file_unshare``627 * ``dax_zero_range``628 * ``dax_truncate_page``629 630Callers commonly hold the same locks as they do to call their iomap631pagecache counterparts.632 633fsdax Deduplication634-------------------635 636Filesystems implementing the ``FIDEDUPERANGE`` ioctl must call the637``dax_remap_file_range_prep`` function with their own iomap read ops.638 639Seeking Files640=============641 642iomap implements the two iterating whence modes of the ``llseek`` system643call.644 645SEEK_DATA646---------647 648The ``iomap_seek_data`` function implements the SEEK_DATA "whence" value649for llseek.650``IOMAP_REPORT`` will be passed as the ``flags`` argument to651``->iomap_begin``.652 653For unwritten mappings, the pagecache will be searched.654Regions of the pagecache with a folio mapped and uptodate fsblocks655within those folios will be reported as data areas.656 657Callers commonly hold ``i_rwsem`` in shared mode before calling this658function.659 660SEEK_HOLE661---------662 663The ``iomap_seek_hole`` function implements the SEEK_HOLE "whence" value664for llseek.665``IOMAP_REPORT`` will be passed as the ``flags`` argument to666``->iomap_begin``.667 668For unwritten mappings, the pagecache will be searched.669Regions of the pagecache with no folio mapped, or a !uptodate fsblock670within a folio will be reported as sparse hole areas.671 672Callers commonly hold ``i_rwsem`` in shared mode before calling this673function.674 675Swap File Activation676====================677 678The ``iomap_swapfile_activate`` function finds all the base-page aligned679regions in a file and sets them up as swap space.680The file will be ``fsync()``'d before activation.681``IOMAP_REPORT`` will be passed as the ``flags`` argument to682``->iomap_begin``.683All mappings must be mapped or unwritten; cannot be dirty or shared, and684cannot span multiple block devices.685Callers must hold ``i_rwsem`` in exclusive mode; this is already686provided by ``swapon``.687 688File Space Mapping Reporting689============================690 691iomap implements two of the file space mapping system calls.692 693FS_IOC_FIEMAP694-------------695 696The ``iomap_fiemap`` function exports file extent mappings to userspace697in the format specified by the ``FS_IOC_FIEMAP`` ioctl.698``IOMAP_REPORT`` will be passed as the ``flags`` argument to699``->iomap_begin``.700Callers commonly hold ``i_rwsem`` in shared mode before calling this701function.702 703FIBMAP (deprecated)704-------------------705 706``iomap_bmap`` implements FIBMAP.707The calling conventions are the same as for FIEMAP.708This function is only provided to maintain compatibility for filesystems709that implemented FIBMAP prior to conversion.710This ioctl is deprecated; do **not** add a FIBMAP implementation to711filesystems that do not have it.712Callers should probably hold ``i_rwsem`` in shared mode before calling713this function, but this is unclear.714