filesystems/iomap/operations.rst

1 .. SPDX-License-Identifier: GPL-2.0
35 linked lists of buffer heads instead of the per-folio bitmaps that iomap
42 -----------------------------------
61 --------------------------
63 The ``->iomap_begin`` function for pagecache operations may set the
67 .. code-block:: c
79   - ``get_folio``: Called to allocate and return an active reference to
83     This could be used to `set up per-folio filesystem state
84     <https://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/>`_
87   - ``put_folio``: Called to unlock and put a folio after a pagecache
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``.
95   - ``iomap_valid``: The filesystem may not hold locks between
96     ``->iomap_begin`` and ``->iomap_end`` because pagecache operations
98     for memory reclamation, or engage in other time-consuming actions.
102     <https://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/>`_
111     fsdax does not need this revalidation because there's no writeback
112     and no support for unwritten extents.
115     ``->iomap_valid`` function to decide if the mapping is still valid.
119     ``->iomap_begin`` function may set ``struct iomap::validity_cookie``
124     iomap::validity_cookie`` during ``->iomap_begin``.
127     ``->iomap_valid``, then the iomap should considered stale and the
136 Internal per-Folio State
137 ------------------------
146 tracks the per-fsblock uptodate and dirty state itself.
148 <https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_
159  * ``dirty``: iomap will set the per-block dirty state when programs
167 because there is only one per folio, and the per-fsblock overhead is two
174 ----------------------------
179 The ``flags`` argument to ``->iomap_begin`` will be set to zero.
184 ---------------
189 the ``flags`` argument to ``->iomap_begin``.
199 to ``->iomap_begin``.
209 <https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_
211 <https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_
214 ``->iomap_end`` function to find all the clean areas of the folios
229 pagecache for non-truncation file operations that are not aligned to
232 ``->iomap_begin``.
243 to ``->iomap_begin``.
248 ----------
256 ``->iomap_begin``.
261 -------------------
274 ``->map_blocks`` machinery described below even if the writeback fails.
276 ``-EIO`` is recorded for userspace to collect via ``fsync``.
283 .. code-block:: c
294   - ``map_blocks``: Sets ``wpc->iomap`` to the space mapping of the file
298     <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_
300     Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end``
306     This revalidation must be open-coded by the filesystem; it is
311   - ``submit_ioend``: Allows the file systems to hook into writeback bio
313     This might include pre-write space accounting updates, or installing
314     a custom ``->bi_end_io`` function for internal purposes, such as
319   - ``discard_folio``: iomap calls this function after ``->map_blocks``
323     The folio will be marked clean and an ``-EIO`` recorded in the
326     <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_
345 extent conversions) should provide a ``->submit_ioend`` function to
352 <https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_
353 for post-writeback updates by batching them.
375 Direct I/O
378 In Linux, direct I/O is defined as file I/O that is issued directly to
380 The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and
383 .. code-block:: c
411    or fail with ``-EAGAIN``.
412    This can be used by filesystems with complex unaligned I/O
413    write paths to provide an optimised fast path for unaligned writes.
416    no risk of stale data exposure or data loss.
418    perform the serialisation steps needed to provide exclusive access
419    to the unaligned I/O range so that it can perform allocation and
420    sub-block zeroing safely.
423    <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_
425    <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.
434 These ``struct kiocb`` flags are significant for direct I/O with iomap:
452 Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and
453 ``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open``
455 They should not set ``->direct_IO``, which is deprecated.
457 If a filesystem wishes to perform its own work before direct I/O
464 -------------
468  * A non-negative number of bytes transferred.
470  * ``-ENOTBLK``: Fall back to buffered I/O.
473    The ``->iomap_begin`` or ``->iomap_end`` functions may also return
476  * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
481 Direct Reads
482 ------------
484 A direct I/O read initiates a read I/O from the storage device to the
488 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with
496 Direct Writes
497 -------------
499 A direct I/O write initiates a write I/O to the storage device from the
504 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT |
515    the unaligned regions without exposing stale contents.
517  * ``IOMAP_ATOMIC``: This write is being issued with torn-write
519    Torn-write protection may be provided based on HW-offload or by a
522    For HW-offload based support, only a single bio can be created for the
529    conversion or copy-on-write), all updates for the entire file range
531    Untorn-writes may be longer than a single file block. In all cases,
535    untorn-write based on HW-offload.
537    For untorn-writes based on a software mechanism provided by the
539    which apply for HW-offload based untorn-writes do not apply.
541    HW-offload based untorn-writes may not be issued, e.g. the range of the
551 -------------------------
552 .. code-block:: c
564   - ``submit_io``: iomap calls this function when it has constructed a
567     If no function is provided, ``submit_bio`` will be called directly.
571   - ``end_io``: This is called after the ``struct bio`` completes.
572     This function should perform post-write conversions of unwritten
582   - ``bio_set``: This allows the filesystem to provide a custom bio_set
583     for allocating direct I/O bios.
584     This enables filesystems to `stash additional per-bio information
585     <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_
590 should set a custom ``->bi_end_io`` function via ``->submit_io``.
592 ``iomap_dio_bio_end_io`` to finish the direct I/O.
598 These devices support a new access mode known as "fsdax" that allows
602 -----------
606 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any
615 ------------
619 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |
631    mapping operation with ``-EAGAIN``.
642 ``flags`` argument to ``->iomap_begin``.
644 passed as the ``flags`` argument to ``->iomap_begin``.
650 ------------------------------------------
654 The ``flags`` argument to ``->iomap_begin`` are the same as the
665 -------------------
677 ---------
682 ``->iomap_begin``.
692 ---------
697 ``->iomap_begin``.
700 Regions of the pagecache with no folio mapped, or a !uptodate fsblock
709 The ``iomap_swapfile_activate`` function finds all the base-page aligned
713 ``->iomap_begin``.
725 -------------
730 ``->iomap_begin``.
735 -------------------