Lines Matching +full:no +full:- +full:unaligned +full:- +full:direct +full:- +full:access
1 .. SPDX-License-Identifier: GPL-2.0
35 linked lists of buffer heads instead of the per-folio bitmaps that iomap
42 -----------------------------------
61 --------------------------
63 .. code-block:: c
77 - ``get_folio``: Called to allocate and return an active reference to
81 This could be used to `set up per-folio filesystem state
82 <https://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/>`_
85 - ``put_folio``: Called to unlock and put a folio after a pagecache
89 This could be used to `commit per-folio filesystem state
90 <https://lore.kernel.org/all/20180619164137.13720-6-hch@lst.de/>`_
91 that was set up by ``->get_folio``.
93 - ``iomap_valid``: The filesystem may not hold locks between
94 ``->iomap_begin`` and ``->iomap_end`` because pagecache operations
96 for memory reclamation, or engage in other time-consuming actions.
100 <https://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/>`_
109 fsdax does not need this revalidation because there's no writeback
110 and no support for unwritten extents.
113 ``->iomap_valid`` function to decide if the mapping is still valid.
117 ``->iomap_begin`` function may set ``struct iomap::validity_cookie``
122 iomap::validity_cookie`` during ``->iomap_begin``.
125 ``->iomap_valid``, then the iomap should considered stale and the
128 - ``read_folio_range``: Called to synchronously read in the range that will
139 --------------------------
141 .. code-block:: c
151 - ``read_folio_range``: Called to read in the range. This must be provided
156 - ``submit_read``: Submit any pending read requests. This function is
159 Internal per-Folio State
160 ------------------------
169 tracks the per-fsblock uptodate and dirty state itself.
171 <https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_
182 * ``dirty``: iomap will set the per-block dirty state when programs
190 because there is only one per folio, and the per-fsblock overhead is two
197 ----------------------------
202 The ``flags`` argument to ``->iomap_begin`` will be set to zero.
209 .. code-block:: c
219 * ``ops->read_folio_range()`` and ``rac``
222 * ``ops->read_folio_range()`` and ``cur_folio``
224 ``ops->submit_read()`` and ``read_ctx`` are optional. ``read_ctx`` is used to
229 ---------------
234 the ``flags`` argument to ``->iomap_begin``.
244 to ``->iomap_begin``.
254 <https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_
256 <https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_
259 ``->iomap_end`` function to find all the clean areas of the folios
274 pagecache for non-truncation file operations that are not aligned to
277 ``->iomap_begin``.
288 to ``->iomap_begin``.
293 ----------
301 ``->iomap_begin``.
306 -------------------
319 ``->writeback_range`` machinery described below even if the writeback fails.
321 ``-EIO`` is recorded for userspace to collect via ``fsync``.
328 .. code-block:: c
338 - ``writeback_range``: Sets ``wpc->iomap`` to the space mapping of the file
342 <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_
344 Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end``
350 This revalidation must be open-coded by the filesystem; it is
356 The folio will be marked clean and an ``-EIO`` recorded in the
359 <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_
367 - ``writeback_submit``: Submit the previous built writeback context.
371 This might include pre-write space accounting updates, or installing
372 a custom ``->bi_end_io`` function for internal purposes, such as
391 submitted by ``->submit_writeback``
397 <https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_
398 for post-writeback updates by batching them.
420 Direct I/O
423 In Linux, direct I/O is defined as file I/O that is issued directly to
425 The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and
428 .. code-block:: c
456 or fail with ``-EAGAIN``.
457 This can be used by filesystems with complex unaligned I/O
458 write paths to provide an optimised fast path for unaligned writes.
461 no risk of stale data exposure or data loss.
463 perform the serialisation steps needed to provide exclusive access
464 to the unaligned I/O range so that it can perform allocation and
465 sub-block zeroing safely.
468 <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_
470 <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.
479 These ``struct kiocb`` flags are significant for direct I/O with iomap:
493 Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and
494 ``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open``
496 They should not set ``->direct_IO``, which is deprecated.
498 If a filesystem wishes to perform its own work before direct I/O
505 -------------
509 * A non-negative number of bytes transferred.
511 * ``-ENOTBLK``: Fall back to buffered I/O.
514 The ``->iomap_begin`` or ``->iomap_end`` functions may also return
517 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
522 Direct Reads
523 ------------
525 A direct I/O read initiates a read I/O from the storage device to the
529 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with
537 Direct Writes
538 -------------
540 A direct I/O write initiates a write I/O to the storage device from the
545 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT |
556 the unaligned regions without exposing stale contents.
558 * ``IOMAP_ATOMIC``: This write is being issued with torn-write
560 Torn-write protection may be provided based on HW-offload or by a
563 For HW-offload based support, only a single bio can be created for the
570 conversion or copy-on-write), all updates for the entire file range
572 Untorn-writes may be longer than a single file block. In all cases,
576 untorn-write based on HW-offload.
578 For untorn-writes based on a software mechanism provided by the
580 which apply for HW-offload based untorn-writes do not apply.
582 HW-offload based untorn-writes may not be issued, e.g. the range of the
592 -------------------------
593 .. code-block:: c
605 - ``submit_io``: iomap calls this function when it has constructed a
608 If no function is provided, ``submit_bio`` will be called directly.
612 - ``end_io``: This is called after the ``struct bio`` completes.
613 This function should perform post-write conversions of unwritten
623 - ``bio_set``: This allows the filesystem to provide a custom bio_set
624 for allocating direct I/O bios.
625 This enables filesystems to `stash additional per-bio information
626 <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_
631 should set a custom ``->bi_end_io`` function via ``->submit_io``.
633 ``iomap_dio_bio_end_io`` to finish the direct I/O.
639 These devices support a new access mode known as "fsdax" that allows
643 -----------
647 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any
656 ------------
660 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |
672 mapping operation with ``-EAGAIN``.
683 ``flags`` argument to ``->iomap_begin``.
685 passed as the ``flags`` argument to ``->iomap_begin``.
691 ------------------------------------------
695 The ``flags`` argument to ``->iomap_begin`` are the same as the
706 -------------------
718 ---------
723 ``->iomap_begin``.
733 ---------
738 ``->iomap_begin``.
741 Regions of the pagecache with no folio mapped, or a !uptodate fsblock
750 The ``iomap_swapfile_activate`` function finds all the base-page aligned
754 ``->iomap_begin``.
766 -------------
771 ``->iomap_begin``.
776 -------------------