Lines Matching +full:i +full:- +full:cache +full:- +full:block +full:- +full:size
1 .. SPDX-License-Identifier: GPL-2.0
20 Buffered I/O
23 Buffered I/O is the default file I/O path in Linux.
26 Dirty cache will be written back to disk at some point that can be
30 filesystems have to implement themselves under the legacy I/O model.
34 Under the legacy I/O model, this was managed very inefficiently with
35 linked lists of buffer heads instead of the per-folio bitmaps that iomap
38 be used, which makes buffered I/O much more efficient, and the pagecache
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/>`_
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
130 These ``struct kiocb`` flags are significant for buffered I/O with iomap:
134 Internal per-Folio State
135 ------------------------
137 If the fsblock size matches the size of a pagecache folio, it is assumed
138 that all disk I/O operations will operate on the entire folio.
143 If the fsblock size is less than the size of a pagecache folio, iomap
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
228 the fsblock size.
230 ``->iomap_begin``.
241 to ``->iomap_begin``.
246 ----------
252 everything after the EOF block.
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
294 iomap calls this function for each dirty fs block in each dirty folio,
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
310 ioend or perform any other preparatory work before the writeback I/O
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``
319 fails to schedule I/O for any part of a dirty folio.
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/>`_
333 To handle the bookkeeping that must happen after disk I/O for writeback
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.
368 write I/O outcome is the same.
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
391 extra work before or after the I/O is issued to storage.
401 The direction of the I/O is determined from the ``iocb`` passed in.
406 * ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the
410 or fail with ``-EAGAIN``.
411 This can be used by filesystems with complex unaligned I/O
414 other I/Os to the same filesystem block(s) is unnecessary as there is
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:
439 In the case of pure overwrites, the I/O may be issued with FUA
442 * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an
444 Only meaningful for asynchronous I/O, and only if the entire I/O can
447 * ``IOCB_DIO_CALLER_COMP``: Try to run I/O completion from the caller's
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.
471 cache before issuing the I/O to storage.
472 The ``->iomap_begin`` or ``->iomap_end`` functions may also return
475 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
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
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 |
512 The file I/O range must be aligned to the filesystem block size
520 -------------------------
521 .. code-block:: c
526 int (*end_io)(struct kiocb *iocb, ssize_t size, int error,
533 - ``submit_io``: iomap calls this function when it has constructed a
534 ``struct bio`` object for the I/O requested, and wishes to submit it
535 to the block device.
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/>`_
558 Filesystems that want to perform extra work after an I/O completion
559 should set a custom ``->bi_end_io`` function via ``->submit_io``.
561 ``iomap_dio_bio_end_io`` to finish the direct I/O.
563 DAX I/O
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 |
596 ``IOMAP_MAPPED`` type and span the entire range of the write I/O
600 mapping operation with ``-EAGAIN``.
611 ``flags`` argument to ``->iomap_begin``.
613 passed as the ``flags`` argument to ``->iomap_begin``.
619 ------------------------------------------
622 iomap pagecache I/O counterparts.
623 The ``flags`` argument to ``->iomap_begin`` are the same as the
634 -------------------
646 ---------
651 ``->iomap_begin``.
661 ---------
666 ``->iomap_begin``.
678 The ``iomap_swapfile_activate`` function finds all the base-page aligned
682 ``->iomap_begin``.
684 cannot span multiple block devices.
694 -------------
699 ``->iomap_begin``.
704 -------------------