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 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
134 Internal per-Folio State
135 ------------------------
144 tracks the per-fsblock uptodate and dirty state itself.
146 <https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_
157 * ``dirty``: iomap will set the per-block dirty state when programs
165 because there is only one per folio, and the per-fsblock overhead is two
172 ----------------------------
177 The ``flags`` argument to ``->iomap_begin`` will be set to zero.
182 ---------------
187 the ``flags`` argument to ``->iomap_begin``.
197 to ``->iomap_begin``.
207 <https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_
209 <https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_
212 ``->iomap_end`` function to find all the clean areas of the folios
227 pagecache for non-truncation file operations that are not aligned to
230 ``->iomap_begin``.
241 to ``->iomap_begin``.
246 ----------
254 ``->iomap_begin``.
259 -------------------
272 ``->map_blocks`` machinery described below even if the writeback fails.
274 ``-EIO`` is recorded for userspace to collect via ``fsync``.
281 .. code-block:: c
292 - ``map_blocks``: Sets ``wpc->iomap`` to the space mapping of the file
296 <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_
298 Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end``
304 This revalidation must be open-coded by the filesystem; it is
309 - ``prepare_ioend``: Enables filesystems to transform the writeback
312 This might include pre-write space accounting updates, or installing
313 a custom ``->bi_end_io`` function for internal purposes, such as
318 - ``discard_folio``: iomap calls this function after ``->map_blocks``
322 The folio will be marked clean and an ``-EIO`` recorded in the
325 <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_
344 extent conversions) should provide a ``->prepare_ioend`` function to
351 <https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_
352 for post-writeback updates by batching them.
374 Direct I/O
377 In Linux, direct I/O is defined as file I/O that is issued directly to
379 The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and
382 .. code-block:: c
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.
415 no risk of stale data exposure or data loss.
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.
422 <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_
424 <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.
433 These ``struct kiocb`` flags are significant for direct I/O with iomap:
451 Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and
452 ``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open``
454 They should not set ``->direct_IO``, which is deprecated.
456 If a filesystem wishes to perform its own work before direct I/O
463 -------------
467 * A non-negative number of bytes transferred.
469 * ``-ENOTBLK``: Fall back to buffered I/O.
472 The ``->iomap_begin`` or ``->iomap_end`` functions may also return
475 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
480 Direct Reads
481 ------------
483 A direct I/O read initiates a read I/O from the storage device to the
487 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with
495 Direct Writes
496 -------------
498 A direct I/O write initiates a write I/O to the storage device from the
503 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT |
514 the unaligned regions without exposing stale contents.
520 -------------------------
521 .. code-block:: c
533 - ``submit_io``: iomap calls this function when it has constructed a
536 If no function is provided, ``submit_bio`` will be called directly.
540 - ``end_io``: This is called after the ``struct bio`` completes.
541 This function should perform post-write conversions of unwritten
551 - ``bio_set``: This allows the filesystem to provide a custom bio_set
552 for allocating direct I/O bios.
553 This enables filesystems to `stash additional per-bio information
554 <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_
559 should set a custom ``->bi_end_io`` function via ``->submit_io``.
561 ``iomap_dio_bio_end_io`` to finish the direct I/O.
567 These devices support a new access mode known as "fsdax" that allows
571 -----------
575 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any
584 ------------
588 The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |
600 mapping operation with ``-EAGAIN``.
611 ``flags`` argument to ``->iomap_begin``.
613 passed as the ``flags`` argument to ``->iomap_begin``.
619 ------------------------------------------
623 The ``flags`` argument to ``->iomap_begin`` are the same as the
634 -------------------
646 ---------
651 ``->iomap_begin``.
661 ---------
666 ``->iomap_begin``.
669 Regions of the pagecache with no folio mapped, or a !uptodate fsblock
678 The ``iomap_swapfile_activate`` function finds all the base-page aligned
682 ``->iomap_begin``.
694 -------------
699 ``->iomap_begin``.
704 -------------------