iomap Supported File Operations

지원하는 상위 수준 파일 연산

이 문서는 GPL-2.0이며 Sphinx anchor는 `iomap_operations`입니다. 숨김 style note는 diff 가독성을 위해 문장마다 줄을 나누고 heading 장식은 `sphinx.rst`를 따르라고 요청합니다.

local table of contents 아래에서 iomap이 구현하는 상위 수준 file operation을 설명합니다. 이후 각 절은 buffered I/O, direct I/O, fsdax, seek, swapfile, 공간 mapping 보고가 요구하는 callback과 flag, locking을 구체적으로 정의합니다.

.. SPDX-License-Identifier: GPL-2.0
.. _iomap_operations:

..
        Dumb style notes to maintain the author's sanity:
        Please try to start sentences on separate lines so that
        sentence changes don't bleed colors in diff.
        Heading decorations are documented in sphinx.rst.

=========================
Supported File Operations
=========================

.. contents:: Table of Contents
   :local:

Below are a discussion of the high level file operations that iomap
implements.

Buffered I/O와 address space operation

Buffered I/O는 Linux의 기본 file I/O 경로입니다. file content를 memory의 pagecache에 보관해 read와 write를 처리하고, dirty cache는 나중에 disk로 writeback됩니다. `fsync`와 그 변형으로 writeback을 강제할 수 있습니다.

iomap은 legacy I/O model에서 파일시스템이 직접 구현해야 했던 folio와 pagecache 관리의 거의 전부를 구현합니다. 따라서 파일시스템은 pagecache folio의 allocation, mapping, uptodate·dirty 상태 관리, writeback 세부사항을 알 필요가 없습니다.

legacy model은 folio별 bitmap 대신 buffer head linked list로 이를 비효율적으로 관리했습니다. 파일시스템이 buffer head 사용을 명시적으로 선택하지 않는 한 iomap은 사용하지 않으므로 buffered I/O가 훨씬 효율적입니다.

`struct address_space_operations`에서 `iomap_dirty_folio`, `iomap_release_folio`, `iomap_invalidate_folio`, `iomap_is_partially_uptodate`를 직접 참조할 수 있습니다. `read_folio`, `readahead`, `writepages`, `bmap`, `swap_activate` operation은 iomap helper를 간단히 감싸 구현할 수 있습니다.

Buffered I/O
============

Buffered I/O is the default file I/O path in Linux.
File contents are cached in memory ("pagecache") to satisfy reads and
writes.
Dirty cache will be written back to disk at some point that can be
forced via ``fsync`` and variants.

iomap implements nearly all the folio and pagecache management that
filesystems have to implement themselves under the legacy I/O model.
This means that the filesystem need not know the details of allocating,
mapping, managing uptodate and dirty state, or writeback of pagecache
folios.
Under the legacy I/O model, this was managed very inefficiently with
linked lists of buffer heads instead of the per-folio bitmaps that iomap
uses.
Unless the filesystem explicitly opts in to buffer heads, they will not
be used, which makes buffered I/O much more efficient, and the pagecache
maintainer much happier.

``struct address_space_operations``
-----------------------------------

The following iomap functions can be referenced directly from the
address space operations structure:

 * ``iomap_dirty_folio``
 * ``iomap_release_folio``
 * ``iomap_invalidate_folio``
 * ``iomap_is_partially_uptodate``

The following address space operations can be wrapped easily:

 * ``read_folio``
 * ``readahead``
 * ``writepages``
 * ``bmap``
 * ``swap_activate``

`struct iomap_write_ops`와 mapping 재검증

`struct iomap_write_ops`는 `get_folio`, `put_folio`, `iomap_valid`, `read_folio_range` callback을 제공합니다.

`get_folio`는 write 시작 전에 locked folio를 할당하고 active reference를 반환합니다. 제공하지 않으면 iomap이 `iomap_get_folio`를 호출합니다. 파일시스템은 이를 이용해 write용 per-folio private state를 준비할 수 있습니다.

`put_folio`는 pagecache 연산 완료 후 folio를 unlock하고 reference를 내려놓습니다. 제공하지 않으면 iomap이 `folio_unlock`과 `folio_put`을 호출합니다. `->get_folio`에서 준비한 per-folio filesystem state를 commit하는 데 사용할 수 있습니다.

pagecache 연산은 folio lock 획득, 사용자 공간 page fault, memory reclaim을 위한 writeback, 그 밖의 오래 걸리는 작업을 수행할 수 있으므로 파일시스템은 `->iomap_begin`과 `->iomap_end` 사이에 lock을 유지할 수 없습니다. file space mapping data가 mutable이면 folio를 할당·설치·lock하는 사이 특정 folio의 mapping이 바뀔 수 있습니다.

writeback이 `i_rwsem` 또는 `invalidate_lock`을 잡지 않고 mapping 정보를 갱신하거나 파일시스템이 concurrent write를 허용하면 pagecache race가 발생할 수 있습니다. 이런 파일은 folio lock을 잡은 뒤 mapping을 반드시 재검증해야 iomap이 folio를 올바르게 관리할 수 있습니다. fsdax에는 writeback도 unwritten extent 지원도 없으므로 이 재검증이 필요 없습니다.

이 race에 노출되는 파일시스템은 mapping이 여전히 유효한지 판단하는 `->iomap_valid`를 제공해야 합니다. 유효하지 않으면 mapping을 다시 sampling합니다.

검증을 돕기 위해 `->iomap_begin`은 다른 field와 함께 `struct iomap::validity_cookie`를 설정할 수 있습니다. 단순 구현은 inode extent map을 바꿀 때마다 증가시키는 sequence counter입니다. begin에서 cookie에 counter를 넣고, `->iomap_valid`로 돌아왔을 때 파일시스템 값과 다르면 iomap은 stale이며 검증은 실패합니다.

`read_folio_range`는 write할 범위를 동기적으로 먼저 읽습니다. 제공하지 않으면 iomap이 bio read request를 제출합니다. Buffered I/O에서 `struct kiocb`의 `IOCB_NOWAIT`는 `IOMAP_NOWAIT`, `IOCB_DONTCACHE`는 `IOMAP_DONTCACHE`를 켭니다.

``struct iomap_write_ops``
--------------------------

.. code-block:: c

 struct iomap_write_ops {
     struct folio *(*get_folio)(struct iomap_iter *iter, loff_t pos,
                                unsigned len);
     void (*put_folio)(struct inode *inode, loff_t pos, unsigned copied,
                       struct folio *folio);
     bool (*iomap_valid)(struct inode *inode, const struct iomap *iomap);
     int (*read_folio_range)(const struct iomap_iter *iter,
                             struct folio *folio, loff_t pos, size_t len);
 };

iomap calls these functions:

  - ``get_folio``: Called to allocate and return an active reference to
    a locked folio prior to starting a write.
    If this function is not provided, iomap will call
    ``iomap_get_folio``.
    This could be used to `set up per-folio filesystem state
    <https://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/>`_
    for a write.

  - ``put_folio``: Called to unlock and put a folio after a pagecache
    operation completes.
    If this function is not provided, iomap will ``folio_unlock`` and
    ``folio_put`` on its own.
    This could be used to `commit per-folio filesystem state
    <https://lore.kernel.org/all/20180619164137.13720-6-hch@lst.de/>`_
    that was set up by ``->get_folio``.

  - ``iomap_valid``: The filesystem may not hold locks between
    ``->iomap_begin`` and ``->iomap_end`` because pagecache operations
    can take folio locks, fault on userspace pages, initiate writeback
    for memory reclamation, or engage in other time-consuming actions.
    If a file's space mapping data are mutable, it is possible that the
    mapping for a particular pagecache folio can `change in the time it
    takes
    <https://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/>`_
    to allocate, install, and lock that folio.

    For the pagecache, races can happen if writeback doesn't take
    ``i_rwsem`` or ``invalidate_lock`` and updates mapping information.
    Races can also happen if the filesystem allows concurrent writes.
    For such files, the mapping *must* be revalidated after the folio
    lock has been taken so that iomap can manage the folio correctly.

    fsdax does not need this revalidation because there's no writeback
    and no support for unwritten extents.

    Filesystems subject to this kind of race must provide a
    ``->iomap_valid`` function to decide if the mapping is still valid.
    If the mapping is not valid, the mapping will be sampled again.

    To support making the validity decision, the filesystem's
    ``->iomap_begin`` function may set ``struct iomap::validity_cookie``
    at the same time that it populates the other iomap fields.
    A simple validation cookie implementation is a sequence counter.
    If the filesystem bumps the sequence counter every time it modifies
    the inode's extent map, it can be placed in the ``struct
    iomap::validity_cookie`` during ``->iomap_begin``.
    If the value in the cookie is found to be different to the value
    the filesystem holds when the mapping is passed back to
    ``->iomap_valid``, then the iomap should considered stale and the
    validation failed.

  - ``read_folio_range``: Called to synchronously read in the range that will
    be written to. If this function is not provided, iomap will default to
    submitting a bio read request.

These ``struct kiocb`` flags are significant for buffered I/O with iomap:

 * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.

 * ``IOCB_DONTCACHE``: Turns on ``IOMAP_DONTCACHE``.

내부 per-folio 상태

fsblock 크기와 pagecache folio 크기가 같으면 모든 disk I/O가 folio 전체에 작용한다고 가정합니다. 이 경우 memory content가 disk만큼 최신인지 나타내는 `uptodate`와 memory가 disk보다 최신인지 나타내는 `dirty` folio 상태만 있으면 됩니다.

fsblock이 folio보다 작으면 iomap이 fsblock별 uptodate와 dirty 상태를 직접 추적합니다. 이로써 block size가 page size보다 작은 `bs < ps` 파일시스템과 pagecache의 large folio를 모두 처리합니다.

iomap은 fsblock마다 두 bit를 추적합니다. read 또는 readahead 오류가 난 fsblock은 `uptodate`로 표시하지 않고, folio 안 모든 fsblock이 uptodate일 때 folio도 uptodate로 표시합니다. program이 파일에 쓰면 해당 block의 `dirty`를 설정하고, 하나라도 dirty이면 folio도 dirty로 표시합니다.

진행 중인 read·write disk I/O 개수도 추적합니다. folio마다 구조체 하나만 있고 fsblock별 비용이 104 byte인 `struct buffer_head`와 달리 두 bit뿐이므로 훨씬 가볍습니다. pagecache에서 large folio를 쓰려는 파일시스템은 incore inode 초기화 때 `mapping_set_large_folios`를 호출해야 합니다.

Internal per-Folio State
------------------------

If the fsblock size matches the size of a pagecache folio, it is assumed
that all disk I/O operations will operate on the entire folio.
The uptodate (memory contents are at least as new as what's on disk) and
dirty (memory contents are newer than what's on disk) status of the
folio are all that's needed for this case.

If the fsblock size is less than the size of a pagecache folio, iomap
tracks the per-fsblock uptodate and dirty state itself.
This enables iomap to handle both "bs < ps" `filesystems
<https://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/>`_
and large folios in the pagecache.

iomap internally tracks two state bits per fsblock:

 * ``uptodate``: iomap will try to keep folios fully up to date.
   If there are read(ahead) errors, those fsblocks will not be marked
   uptodate.
   The folio itself will be marked uptodate when all fsblocks within the
   folio are uptodate.

 * ``dirty``: iomap will set the per-block dirty state when programs
   write to the file.
   The folio itself will be marked dirty when any fsblock within the
   folio is dirty.

iomap also tracks the amount of read and write disk IOs that are in
flight.
This structure is much lighter weight than ``struct buffer_head``
because there is only one per folio, and the per-fsblock overhead is two
bits vs. 104 bytes.

Filesystems wishing to turn on large folios in the pagecache should call
``mapping_set_large_folios`` when initializing the incore inode.

Buffered readahead·read·write

`iomap_readahead`는 pagecache readahead를 시작하고 `iomap_read_folio`는 folio 하나 분량의 data를 pagecache로 읽습니다. 이때 `->iomap_begin`의 `flags`는 0이며, pagecache가 파일시스템을 호출하기 전에 필요한 lock을 잡습니다.

`iomap_file_buffered_write`는 `iocb`를 pagecache에 씁니다. `->iomap_begin`에는 `IOMAP_WRITE` 또는 `IOMAP_WRITE | IOMAP_NOWAIT`가 전달됩니다. 호출자는 보통 이 함수 전에 `i_rwsem`을 shared 또는 exclusive mode로 잡습니다.

Buffered Readahead and Reads
----------------------------

The ``iomap_readahead`` function initiates readahead to the pagecache.
The ``iomap_read_folio`` function reads one folio's worth of data into
the pagecache.
The ``flags`` argument to ``->iomap_begin`` will be set to zero.
The pagecache takes whatever locks it needs before calling the
filesystem.

Buffered Writes
---------------

The ``iomap_file_buffered_write`` function writes an ``iocb`` to the
pagecache.
``IOMAP_WRITE`` or ``IOMAP_WRITE`` | ``IOMAP_NOWAIT`` will be passed as
the ``flags`` argument to ``->iomap_begin``.
Callers commonly take ``i_rwsem`` in either shared or exclusive mode
before calling this function.

mmap write fault와 short write 실패 처리

`iomap_page_mkwrite`는 pagecache folio의 write fault를 처리합니다. `->iomap_begin`에는 `IOMAP_WRITE | IOMAP_FAULT`가 전달됩니다. 호출자는 보통 mmap `invalidate_lock`을 shared 또는 exclusive mode로 잡고 호출합니다.

pagecache short write 뒤에는 쓰지 않은 영역이 dirty로 표시되지 않습니다. writeback이 그 reservation을 소비하지 않으므로 파일시스템이 해당 delayed allocation reservation을 취소해야 합니다.

`->iomap_end`에서 `iomap_write_delalloc_release`를 호출하면 새 `IOMAP_F_NEW` delalloc mapping을 cache하는 folio 중 clean 영역을 모두 찾을 수 있습니다. 이 함수는 `invalidate_lock`을 잡습니다.

파일시스템은 이러한 각 file range에 호출할 `punch` 함수를 제공해야 합니다. 같은 영역에 racing thread가 성공적으로 write하고 writeback으로 dirty data를 disk에 내보낼 수 있으므로 `punch`는 delayed allocation reservation만 제거해야 하며 이미 기록된 data를 없애면 안 됩니다.

mmap Write Faults
~~~~~~~~~~~~~~~~~

The ``iomap_page_mkwrite`` function handles a write fault to a folio in
the pagecache.
``IOMAP_WRITE | IOMAP_FAULT`` will be passed as the ``flags`` argument
to ``->iomap_begin``.
Callers commonly take the mmap ``invalidate_lock`` in shared or
exclusive mode before calling this function.

Buffered Write Failures
~~~~~~~~~~~~~~~~~~~~~~~

After a short write to the pagecache, the areas not written will not
become marked dirty.
The filesystem must arrange to `cancel
<https://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/>`_
such `reservations
<https://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/>`_
because writeback will not consume the reservation.
The ``iomap_write_delalloc_release`` can be called from a
``->iomap_end`` function to find all the clean areas of the folios
caching a fresh (``IOMAP_F_NEW``) delalloc mapping.
It takes the ``invalidate_lock``.

The filesystem must supply a function ``punch`` to be called for
each file range in this state.
This function must *only* remove delayed allocation reservations, in
case another thread racing with the current thread writes successfully
to the same region and triggers writeback to flush the dirty data out to
disk.

Zeroing, reflink unshare, truncation

파일시스템은 truncation이 아닌 연산의 범위가 fsblock 크기에 정렬되지 않았을 때 `iomap_zero_range`로 pagecache를 zeroing할 수 있습니다. `->iomap_begin`에는 `IOMAP_ZERO`가 전달되며 호출자는 보통 `i_rwsem`과 `invalidate_lock`을 exclusive mode로 잡습니다.

`iomap_file_unshare`는 다른 파일과 storage를 공유하는 reflink file이 공유 data를 새로 할당한 공간에 미리 copy하도록 강제합니다. `->iomap_begin`에는 `IOMAP_WRITE | IOMAP_UNSHARE`가 전달되고 두 lock을 보통 exclusive mode로 잡습니다.

file truncation 중 `iomap_truncate_page`는 EOF부터 해당 fsblock 끝까지 pagecache byte를 zeroing합니다. EOF block 이후는 `truncate_setsize` 또는 `truncate_pagecache`가 처리합니다. begin flag는 `IOMAP_ZERO`이고 호출자는 보통 `i_rwsem`과 `invalidate_lock`을 exclusive mode로 잡습니다.

Zeroing for File Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Filesystems can call ``iomap_zero_range`` to perform zeroing of the
pagecache for non-truncation file operations that are not aligned to
the fsblock size.
``IOMAP_ZERO`` will be passed as the ``flags`` argument to
``->iomap_begin``.
Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
mode before calling this function.

Unsharing Reflinked File Data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Filesystems can call ``iomap_file_unshare`` to force a file sharing
storage with another file to preemptively copy the shared data to newly
allocate storage.
``IOMAP_WRITE | IOMAP_UNSHARE`` will be passed as the ``flags`` argument
to ``->iomap_begin``.
Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
mode before calling this function.

Truncation
----------

Filesystems can call ``iomap_truncate_page`` to zero the bytes in the
pagecache from EOF to the end of the fsblock during a file truncation
operation.
``truncate_setsize`` or ``truncate_pagecache`` will take care of
everything after the EOF block.
``IOMAP_ZERO`` will be passed as the ``flags`` argument to
``->iomap_begin``.
Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive
mode before calling this function.

Pagecache writeback과 `struct iomap_writeback_ops`

파일시스템은 dirty pagecache folio를 disk에 쓰라는 요청에 `iomap_writepages`로 응답할 수 있습니다. `mapping`과 `wbc` parameter는 변경 없이 전달하고, 파일시스템이 할당하는 `wpc`는 0으로 초기화해야 합니다.

pagecache는 writeback을 schedule하기 전에 각 folio를 lock하지만 `i_rwsem`이나 `invalidate_lock`은 잡지 않습니다. 아래 `->writeback_range` 경로를 거친 모든 folio는 writeback 실패 여부와 관계없이 dirty bit를 지웁니다. storage device 실패 때 dirty folio가 뭉쳐 남는 것을 막기 위한 동작이며, 사용자 공간이 `fsync`로 회수할 `-EIO`를 기록합니다.

필수 `struct iomap_writeback_ops`는 `writeback_range`와 `writeback_submit` callback을 가집니다.

`writeback_range`는 `offset`과 `len`이 지정한 byte 범위의 공간 mapping을 `wpc->iomap`에 설정합니다. iomap은 dirty folio의 dirty fsblock마다 호출하지만 folio 안에서 연속된 dirty fsblock run은 mapping을 재사용합니다.

이 callback에서는 `IOMAP_INLINE`을 반환하면 안 됩니다. written data 영속화는 `->iomap_end`가 처리해야 하기 때문입니다. `IOMAP_DELALLOC`도 반환할 수 없으며 현재 iomap은 할당된 공간으로의 mapping을 요구합니다.

mapping이 바뀌지 않았다면 비싼 lookup을 생략할 수 있지만 재검증은 파일시스템이 직접 구현해야 합니다. `iomap::validity_cookie`를 재사용할 수 있는지는 불분명합니다.

dirty folio 일부라도 I/O schedule에 실패하면 write를 위해 만든 reservation을 모두 버려야 합니다. folio는 clean으로 표시되고 pagecache에 `-EIO`가 기록됩니다. callback은 delalloc reservation을 제거해 clean pagecache에 reservation이 남지 않게 할 수 있으며 반드시 파일시스템이 제공해야 합니다.

`writeback_submit`은 직전에 만든 writeback context를 제출합니다. block 기반 파일시스템은 `iomap_ioend_writeback_submit` helper를 사용하고 다른 파일시스템은 자체 구현할 수 있습니다. pre-write 공간 회계 갱신이나 custom `->bi_end_io` 설치 등 bio 제출 직전 작업을 hook할 수 있습니다.

custom end I/O는 metadata update transaction을 process context에서 실행하려고 ioend completion을 workqueue로 미루는 데도 쓸 수 있습니다. 이 callback도 반드시 제공해야 합니다.

Pagecache Writeback
-------------------

Filesystems can call ``iomap_writepages`` to respond to a request to
write dirty pagecache folios to disk.
The ``mapping`` and ``wbc`` parameters should be passed unchanged.
The ``wpc`` pointer should be allocated by the filesystem and must
be initialized to zero.

The pagecache will lock each folio before trying to schedule it for
writeback.
It does not lock ``i_rwsem`` or ``invalidate_lock``.

The dirty bit will be cleared for all folios run through the
``->writeback_range`` machinery described below even if the writeback fails.
This is to prevent dirty folio clots when storage devices fail; an
``-EIO`` is recorded for userspace to collect via ``fsync``.

The ``ops`` structure must be specified and is as follows:

``struct iomap_writeback_ops``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: c

 struct iomap_writeback_ops {
    int (*writeback_range)(struct iomap_writepage_ctx *wpc,
        struct folio *folio, u64 pos, unsigned int len, u64 end_pos);
    int (*writeback_submit)(struct iomap_writepage_ctx *wpc, int error);
 };

The fields are as follows:

  - ``writeback_range``: Sets ``wpc->iomap`` to the space mapping of the file
    range (in bytes) given by ``offset`` and ``len``.
    iomap calls this function for each dirty fs block in each dirty folio,
    though it will `reuse mappings
    <https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/>`_
    for runs of contiguous dirty fsblocks within a folio.
    Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end``
    function must deal with persisting written data.
    Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently
    requires mapping to allocated space.
    Filesystems can skip a potentially expensive mapping lookup if the
    mappings have not changed.
    This revalidation must be open-coded by the filesystem; it is
    unclear if ``iomap::validity_cookie`` can be reused for this
    purpose.

    If this methods fails to schedule I/O for any part of a dirty folio, it
    should throw away any reservations that may have been made for the write.
    The folio will be marked clean and an ``-EIO`` recorded in the
    pagecache.
    Filesystems can use this callback to `remove
    <https://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/>`_
    delalloc reservations to avoid having delalloc reservations for
    clean pagecache.
    This function must be supplied by the filesystem.

  - ``writeback_submit``: Submit the previous built writeback context.
    Block based file systems should use the iomap_ioend_writeback_submit
    helper, other file system can implement their own.
    File systems can optionally hook into writeback bio submission.
    This might include pre-write space accounting updates, or installing
    a custom ``->bi_end_io`` function for internal purposes, such as
    deferring the ioend completion to a workqueue to run metadata update
    transactions from process context before submitting the bio.
    This function must be supplied by the filesystem.

Pagecache writeback completion과 ioend batching

writeback disk I/O 완료 후 회계를 처리하려고 iomap은 pagecache data를 disk에 쓰는 `bio`를 감싼 `struct iomap_ioend` chain을 만듭니다.

기본적으로 iomap은 ioend에 연결된 folio의 writeback bit를 지워 완료합니다. write가 실패하면 folio와 address space에 error bit도 설정합니다. storage device에 따라 interrupt 또는 process context에서 실행될 수 있습니다.

unwritten extent conversion처럼 내부 회계 갱신이 필요한 파일시스템은 `->submit_writeback`이 제출하는 bio에 자체 `bi_end_io`를 설정해야 합니다. 자체 작업을 마친 뒤 `iomap_finish_ioends`를 호출해야 합니다. 원문은 callback 구조체 이름 `writeback_submit`과 별도로 여기에서 `->submit_writeback` 표기를 사용하므로 그대로 보존합니다.

일부 파일시스템은 writeback 후 metadata transaction 비용을 줄이려고 여러 완료를 batch하거나, transaction을 process context에서 실행하려고 batch를 workqueue로 넘겨야 합니다. iomap ioend의 `list_head`가 batching을 지원합니다.

`iomap_sort_ioends`는 list의 ioend를 file offset 순으로 정렬합니다. `iomap_ioend_try_merge`는 어떤 list에도 속하지 않은 ioend와 정렬된 별도 list를 받아 head부터 가능한 ioend를 합칩니다. file range와 storage address가 연속이고 unwritten·shared 상태와 write I/O 결과가 같을 때만 합칠 수 있으며, 합쳐진 ioend는 자체 list가 됩니다.

`iomap_finish_ioends`는 다른 ioend가 연결됐을 수 있는 하나의 ioend를 최종 완료합니다.

Pagecache Writeback Completion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To handle the bookkeeping that must happen after disk I/O for writeback
completes, iomap creates chains of ``struct iomap_ioend`` objects that
wrap the ``bio`` that is used to write pagecache data to disk.
By default, iomap finishes writeback ioends by clearing the writeback
bit on the folios attached to the ``ioend``.
If the write failed, it will also set the error bits on the folios and
the address space.
This can happen in interrupt or process context, depending on the
storage device.
Filesystems that need to update internal bookkeeping (e.g. unwritten
extent conversions) should set their own bi_end_io on the bios
submitted by ``->submit_writeback``
This function should call ``iomap_finish_ioends`` after finishing its
own work (e.g. unwritten extent conversion).

Some filesystems may wish to `amortize the cost of running metadata
transactions
<https://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/>`_
for post-writeback updates by batching them.
They may also require transactions to run from process context, which
implies punting batches to a workqueue.
iomap ioends contain a ``list_head`` to enable batching.

Given a batch of ioends, iomap has a few helpers to assist with
amortization:

 * ``iomap_sort_ioends``: Sort all the ioends in the list by file
   offset.

 * ``iomap_ioend_try_merge``: Given an ioend that is not in any list and
   a separate list of sorted ioends, merge as many of the ioends from
   the head of the list into the given ioend.
   ioends can only be merged if the file range and storage addresses are
   contiguous; the unwritten and shared status are the same; and the
   write I/O outcome is the same.
   The merged ioends become their own list.

 * ``iomap_finish_ioends``: Finish an ioend that possibly has other
   ioends linked to it.

Direct I/O entry point와 실행 flag

Linux에서 direct I/O는 pagecache를 우회해 storage에 직접 발행하는 file I/O입니다. `iomap_dio_rw`는 file의 `O_DIRECT` read와 write를 구현하며 `iocb`, `iov_iter`, mapping `ops`, 선택적 direct I/O `dops`, `dio_flags`, private data, `done_before`를 받습니다.

파일시스템은 storage I/O 제출 전후에 추가 작업이 필요하면 `dops`를 제공합니다. `done_before`는 이미 전송된 요청 byte 수입니다. 요청 일부가 동기적으로 끝난 뒤 나머지를 비동기로 이어갈 때 사용하며, `iomap_dio_rw` 호출 전에 같은 `iocb`의 write를 시작했다면 설정해야 합니다. I/O 방향은 전달된 `iocb`에서 결정합니다.

`IOMAP_DIO_FORCE_WAIT`는 `kiocb`가 비동기여도 I/O 완료를 기다립니다.

`IOMAP_DIO_OVERWRITE_ONLY`는 해당 범위를 pure overwrite로 수행하거나 `-EAGAIN`으로 실패하게 합니다. 복잡한 unaligned I/O write 경로를 가진 파일시스템이 정렬되지 않은 write의 최적화 fast path로 사용할 수 있습니다.

pure overwrite가 가능하면 stale data 노출이나 data loss 위험이 없어 같은 fsblock에 대한 다른 I/O와 직렬화할 필요가 없습니다. 불가능하면 파일시스템은 해당 unaligned 범위의 exclusive access를 위한 직렬화를 수행해 allocation과 sub-block zeroing을 안전하게 처리할 수 있습니다. locking contention을 줄일 수 있지만 올바른 구현에는 상세한 검사가 많이 필요합니다.

`IOMAP_DIO_PARTIAL`은 page fault가 발생하면 지금까지의 진행량을 반환합니다. 호출자는 fault를 처리하고 재시도할 수 있으며, 재시도하면 이전 모든 호출의 누적 반환값을 다음 `done_before`로 넘겨야 합니다.

Direct I/O에서 `IOCB_NOWAIT`는 `IOMAP_NOWAIT`를 켭니다. `IOCB_SYNC`는 호출 완료 전에 device가 data를 disk에 영속화하도록 하며 pure overwrite는 FUA를 켜 발행할 수 있습니다. `IOCB_HIPRI`는 interrupt를 기다리지 않고 completion을 polling하며, 비동기 I/O이면서 전체 I/O를 단일 `struct bio`로 발행할 수 있을 때만 의미가 있습니다.

`IOCB_DIO_CALLER_COMP`는 호출자 process context에서 I/O completion을 실행하려고 시도하며 자세한 내용은 `linux/fs.h`에 있습니다.

파일시스템은 `->read_iter`와 `->write_iter`에서 `iomap_dio_rw`를 호출하고 file의 `->open`에서 `FMODE_CAN_ODIRECT`를 설정해야 합니다. deprecated된 `->direct_IO`는 설정하면 안 됩니다.

direct I/O completion 전에 자체 작업을 하려면 `__iomap_dio_rw`를 호출합니다. 반환값이 error pointer도 NULL도 아니면 내부 작업을 마친 뒤 그 값을 `iomap_dio_complete`에 전달해야 합니다.

Direct I/O
==========

In Linux, direct I/O is defined as file I/O that is issued directly to
storage, bypassing the pagecache.
The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and
writes for files.

.. code-block:: c

 ssize_t iomap_dio_rw(struct kiocb *iocb, struct iov_iter *iter,
                      const struct iomap_ops *ops,
                      const struct iomap_dio_ops *dops,
                      unsigned int dio_flags, void *private,
                      size_t done_before);

The filesystem can provide the ``dops`` parameter if it needs to perform
extra work before or after the I/O is issued to storage.
The ``done_before`` parameter tells the how much of the request has
already been transferred.
It is used to continue a request asynchronously when `part of the
request
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c03098d4b9ad76bca2966a8769dcfe59f7f85103>`_
has already been completed synchronously.

The ``done_before`` parameter should be set if writes for the ``iocb``
have been initiated prior to the call.
The direction of the I/O is determined from the ``iocb`` passed in.

The ``dio_flags`` argument can be set to any combination of the
following values:

 * ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the
   kiocb is not synchronous.

 * ``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range
   or fail with ``-EAGAIN``.
   This can be used by filesystems with complex unaligned I/O
   write paths to provide an optimised fast path for unaligned writes.
   If a pure overwrite can be performed, then serialisation against
   other I/Os to the same filesystem block(s) is unnecessary as there is
   no risk of stale data exposure or data loss.
   If a pure overwrite cannot be performed, then the filesystem can
   perform the serialisation steps needed to provide exclusive access
   to the unaligned I/O range so that it can perform allocation and
   sub-block zeroing safely.
   Filesystems can use this flag to try to reduce locking contention,
   but a lot of `detailed checking
   <https://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/>`_
   is required to do it `correctly
   <https://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/>`_.

 * ``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever
   progress has already been made.
   The caller may deal with the page fault and retry the operation.
   If the caller decides to retry the operation, it should pass the
   accumulated return values of all previous calls as the
   ``done_before`` parameter to the next call.

These ``struct kiocb`` flags are significant for direct I/O with iomap:

 * ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.

 * ``IOCB_SYNC``: Ensure that the device has persisted data to disk
   before completing the call.
   In the case of pure overwrites, the I/O may be issued with FUA
   enabled.

 * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an
   interrupt.
   Only meaningful for asynchronous I/O, and only if the entire I/O can
   be issued as a single ``struct bio``.

 * ``IOCB_DIO_CALLER_COMP``: Try to run I/O completion from the caller's
   process context.
   See ``linux/fs.h`` for more details.

Filesystems should call ``iomap_dio_rw`` from ``->read_iter`` and
``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open``
function for the file.
They should not set ``->direct_IO``, which is deprecated.

If a filesystem wishes to perform its own work before direct I/O
completion, it should call ``__iomap_dio_rw``.
If its return value is not an error pointer or a NULL pointer, the
filesystem should pass the return value to ``iomap_dio_complete`` after
finishing its internal work.

Direct I/O 반환값

`iomap_dio_rw`는 전송한 byte 수를 나타내는 0 이상의 값을 반환할 수 있습니다.

`-ENOTBLK`는 buffered I/O로 fallback하라는 뜻입니다. storage에 I/O를 내기 전 pagecache를 invalidate할 수 없으면 iomap 자체가 반환하며 `->iomap_begin`이나 `->iomap_end`도 반환할 수 있습니다.

`-EIOCBQUEUED`는 비동기 direct I/O 요청이 queue에 들어갔고 별도로 완료될 것임을 뜻합니다. 그 밖의 음수 error code도 반환할 수 있습니다.

Return Values
-------------

``iomap_dio_rw`` can return one of the following:

 * A non-negative number of bytes transferred.

 * ``-ENOTBLK``: Fall back to buffered I/O.
   iomap itself will return this value if it cannot invalidate the page
   cache before issuing the I/O to storage.
   The ``->iomap_begin`` or ``->iomap_end`` functions may also return
   this value.

 * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been
   queued and will be completed separately.

 * Any of the other negative error codes.

Direct read

Direct I/O read는 storage device에서 호출자 buffer로 read I/O를 시작합니다. 시작하기 전에 pagecache의 dirty 부분을 storage로 flush합니다.

`->iomap_begin`의 기본 flag는 `IOMAP_DIRECT`이고 앞서 정의한 `IOMAP_NOWAIT`를 조합할 수 있습니다. 호출자는 보통 이 함수 전에 `i_rwsem`을 shared mode로 잡습니다.

Direct Reads
------------

A direct I/O read initiates a read I/O from the storage device to the
caller's buffer.
Dirty parts of the pagecache are flushed to storage before initiating
the read io.
The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with
any combination of the following enhancements:

 * ``IOMAP_NOWAIT``, as defined previously.

Callers commonly hold ``i_rwsem`` in shared mode before calling this
function.

Direct write와 atomic write

Direct I/O write는 호출자 buffer에서 storage device로 write I/O를 시작합니다. 시작 전 pagecache의 dirty 부분을 storage로 flush하고, write 전후 모두 pagecache를 invalidate합니다. `->iomap_begin`의 기본 flag는 `IOMAP_DIRECT | IOMAP_WRITE`이며 `IOMAP_NOWAIT` 등을 조합할 수 있습니다.

`IOMAP_OVERWRITE_ONLY`에서는 block allocation과 partial block zeroing을 허용하지 않습니다. 전체 file range가 하나의 written 또는 unwritten extent에 mapping되어야 합니다. mapping이 unwritten이고 파일시스템이 stale content 노출 없이 비정렬 영역을 zeroing할 수 없다면 I/O 범위도 fsblock 크기에 정렬해야 합니다.

`IOMAP_ATOMIC`은 torn-write 보호를 적용한 write입니다. HW-offload 또는 파일시스템의 software mechanism으로 보호할 수 있습니다.

HW-offload에서는 write 전체를 단일 bio로 만들고 여러 I/O request로 나누면 안 되므로 `REQ_ATOMIC`을 설정해야 합니다. write range는 파일시스템과 underlying block device의 atomic commit alignment 요구를 모두 충족해야 합니다.

unwritten extent conversion이나 copy-on-write처럼 metadata update가 필요하면 전체 file range의 모든 update도 atomic하게 commit해야 합니다. untorn write는 fsblock 하나보다 길 수 있지만 언제나 mapping 시작 disk block의 alignment가 write offset 이상이어야 합니다. 파일시스템은 `IOMAP_F_ATOMIC_BIO`로 HW-offload 기반 untorn write임을 iomap core에 알려야 합니다.

Software mechanism 기반 untorn write에는 HW-offload의 disk block alignment와 single-bio 제한이 적용되지 않습니다. write range가 여러 extent를 덮어 single bio를 발행할 수 없는 등 HW-offload를 사용할 수 없을 때 보통 fallback으로 씁니다. 그래도 전체 range의 파일시스템 metadata update는 모두 atomic하게 commit해야 합니다.

호출자는 보통 direct write 전에 `i_rwsem`을 shared 또는 exclusive mode로 잡습니다.

Direct Writes
-------------

A direct I/O write initiates a write I/O to the storage device from the
caller's buffer.
Dirty parts of the pagecache are flushed to storage before initiating
the write io.
The pagecache is invalidated both before and after the write io.
The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT |
IOMAP_WRITE`` with any combination of the following enhancements:

 * ``IOMAP_NOWAIT``, as defined previously.

 * ``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial
   blocks is not allowed.
   The entire file range must map to a single written or unwritten
   extent.
   The file I/O range must be aligned to the filesystem block size
   if the mapping is unwritten and the filesystem cannot handle zeroing
   the unaligned regions without exposing stale contents.

 * ``IOMAP_ATOMIC``: This write is being issued with torn-write
   protection.
   Torn-write protection may be provided based on HW-offload or by a
   software mechanism provided by the filesystem.

   For HW-offload based support, only a single bio can be created for the
   write, and the write must not be split into multiple I/O requests, i.e.
   flag REQ_ATOMIC must be set.
   The file range to write must be aligned to satisfy the requirements
   of both the filesystem and the underlying block device's atomic
   commit capabilities.
   If filesystem metadata updates are required (e.g. unwritten extent
   conversion or copy-on-write), all updates for the entire file range
   must be committed atomically as well.
   Untorn-writes may be longer than a single file block. In all cases,
   the mapping start disk block must have at least the same alignment as
   the write offset.
   The filesystems must set IOMAP_F_ATOMIC_BIO to inform iomap core of an
   untorn-write based on HW-offload.

   For untorn-writes based on a software mechanism provided by the
   filesystem, all the disk block alignment and single bio restrictions
   which apply for HW-offload based untorn-writes do not apply.
   The mechanism would typically be used as a fallback for when
   HW-offload based untorn-writes may not be issued, e.g. the range of the
   write covers multiple extents, meaning that it is not possible to issue
   a single bio.
   All filesystem metadata updates for the entire file range must be
   committed atomically as well.

Callers commonly hold ``i_rwsem`` in shared or exclusive mode before
calling this function.

`struct iomap_dio_ops`와 bio completion

원문 heading은 backtick 안에 colon까지 포함한 `struct iomap_dio_ops:`로 되어 있습니다. 구조체는 `submit_io`, `end_io`, `bio_set` field를 가집니다.

`submit_io`는 iomap이 요청 I/O용 `struct bio`를 만들고 block device에 제출하려 할 때 호출합니다. 제공하지 않으면 `submit_bio`를 직접 호출합니다. btrfs data replication처럼 제출 전에 추가 작업이 필요한 파일시스템이 구현합니다.

`end_io`는 `struct bio` 완료 후 호출됩니다. unwritten extent mapping의 post-write conversion, write failure 처리 등을 수행해야 합니다.

`end_io`의 `flags`에는 `IOMAP_DIO_UNWRITTEN`과 `IOMAP_DIO_COW`를 조합할 수 있습니다. UNWRITTEN이면 ioend가 extent를 written으로 표시해야 하고, COW이면 mapping 공간에 대한 write에 copy-on-write가 필요했으므로 ioend가 mapping을 전환해야 합니다.

`bio_set`은 파일시스템이 direct I/O bio 할당용 custom bio_set을 제공해 private per-bio 정보를 저장할 수 있게 합니다. NULL이면 generic `struct bio`를 사용합니다.

I/O completion 뒤 추가 작업이 필요한 파일시스템은 `->submit_io`에서 custom `->bi_end_io`를 설정해야 합니다. custom endio 함수는 마지막에 `iomap_dio_bio_end_io`를 호출해 direct I/O를 완료해야 합니다.

``struct iomap_dio_ops:``
-------------------------
.. code-block:: c

 struct iomap_dio_ops {
     void (*submit_io)(const struct iomap_iter *iter, struct bio *bio,
                       loff_t file_offset);
     int (*end_io)(struct kiocb *iocb, ssize_t size, int error,
                   unsigned flags);
     struct bio_set *bio_set;
 };

The fields of this structure are as follows:

  - ``submit_io``: iomap calls this function when it has constructed a
    ``struct bio`` object for the I/O requested, and wishes to submit it
    to the block device.
    If no function is provided, ``submit_bio`` will be called directly.
    Filesystems that would like to perform additional work before (e.g.
    data replication for btrfs) should implement this function.

  - ``end_io``: This is called after the ``struct bio`` completes.
    This function should perform post-write conversions of unwritten
    extent mappings, handle write failures, etc.
    The ``flags`` argument may be set to a combination of the following:

    * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend
      should mark the extent as written.

    * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a
      copy on write operation, so the ioend should switch mappings.

  - ``bio_set``: This allows the filesystem to provide a custom bio_set
    for allocating direct I/O bios.
    This enables filesystems to `stash additional per-bio information
    <https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/>`_
    for private use.
    If this field is NULL, generic ``struct bio`` objects will be used.

Filesystems that want to perform extra work after an I/O completion
should set a custom ``->bi_end_io`` function via ``->submit_io``.
Afterwards, the custom endio function must call
``iomap_dio_bio_end_io`` to finish the direct I/O.

DAX I/O와 fsdax read

일부 storage device는 memory로 직접 mapping할 수 있습니다. 이 device는 CPU와 memory controller를 통한 load와 store를 허용하는 `fsdax` access mode를 지원합니다.

fsdax read는 storage device에서 호출자 buffer로 `memcpy`합니다. `->iomap_begin`에는 `IOMAP_DAX`와 선택적 `IOMAP_NOWAIT`가 전달됩니다. 호출자는 보통 `i_rwsem`을 shared mode로 잡습니다.

DAX I/O
=======

Some storage devices can be directly mapped as memory.
These devices support a new access mode known as "fsdax" that allows
loads and stores through the CPU and memory controller.

fsdax Reads
-----------

A fsdax read performs a memcpy from storage device to the caller's
buffer.
The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any
combination of the following enhancements:

 * ``IOMAP_NOWAIT``, as defined previously.

Callers commonly hold ``i_rwsem`` in shared mode before calling this
function.

fsdax write

fsdax write는 호출자 buffer에서 storage device로 `memcpy`합니다. `->iomap_begin`에는 `IOMAP_DAX | IOMAP_WRITE`와 선택적 `IOMAP_NOWAIT` 또는 `IOMAP_OVERWRITE_ONLY`가 전달됩니다.

`IOMAP_OVERWRITE_ONLY`는 해당 mapping에서 pure overwrite를 요구합니다. 파일시스템 extent mapping이 이미 `IOMAP_MAPPED`로 존재하고 write I/O 요청 전체 범위를 덮어야 합니다. iomap이 pure overwrite를 수행할 수 있는 mapping을 만들지 못하면 `-EAGAIN`으로 실패해야 합니다.

호출자는 보통 fsdax write 전에 `i_rwsem`을 exclusive mode로 잡습니다.

fsdax Writes
------------

A fsdax write initiates a memcpy to the storage device from the caller's
buffer.
The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX |
IOMAP_WRITE`` with any combination of the following enhancements:

 * ``IOMAP_NOWAIT``, as defined previously.

 * ``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be
   performed from this mapping.
   This requires the filesystem extent mapping to already exist as an
   ``IOMAP_MAPPED`` type and span the entire range of the write I/O
   request.
   If the filesystem cannot map this request in a way that allows the
   iomap infrastructure to perform a pure overwrite, it must fail the
   mapping operation with ``-EAGAIN``.

Callers commonly hold ``i_rwsem`` in exclusive mode before calling this
function.

fsdax fault·범위 연산·deduplication

`dax_iomap_fault`는 fsdax storage의 read와 write fault를 처리합니다. read fault의 begin flag는 `IOMAP_DAX | IOMAP_FAULT`, write fault는 여기에 `IOMAP_WRITE`를 더합니다. 호출자는 보통 대응하는 iomap pagecache 함수와 같은 lock을 잡습니다.

fsdax file에서는 pagecache I/O 대응 함수를 대신해 `dax_file_unshare`, `dax_zero_range`, `dax_truncate_page`를 제공합니다. begin flag는 pagecache 대응 함수와 같고 `IOMAP_DAX`를 추가합니다. lock도 대응 함수와 동일합니다.

`FIDEDUPERANGE` ioctl을 구현하는 파일시스템은 자체 iomap read ops와 함께 `dax_remap_file_range_prep`을 호출해야 합니다.

fsdax mmap Faults
~~~~~~~~~~~~~~~~~

The ``dax_iomap_fault`` function handles read and write faults to fsdax
storage.
For a read fault, ``IOMAP_DAX | IOMAP_FAULT`` will be passed as the
``flags`` argument to ``->iomap_begin``.
For a write fault, ``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE`` will be
passed as the ``flags`` argument to ``->iomap_begin``.

Callers commonly hold the same locks as they do to call their iomap
pagecache counterparts.

fsdax Truncation, fallocate, and Unsharing
------------------------------------------

For fsdax files, the following functions are provided to replace their
iomap pagecache I/O counterparts.
The ``flags`` argument to ``->iomap_begin`` are the same as the
pagecache counterparts, with ``IOMAP_DAX`` added.

 * ``dax_file_unshare``
 * ``dax_zero_range``
 * ``dax_truncate_page``

Callers commonly hold the same locks as they do to call their iomap
pagecache counterparts.

fsdax Deduplication
-------------------

Filesystems implementing the ``FIDEDUPERANGE`` ioctl must call the
``dax_remap_file_range_prep`` function with their own iomap read ops.

`SEEK_DATA`와 `SEEK_HOLE`

iomap은 `llseek` system call의 두 iterating whence mode를 구현합니다.

`iomap_seek_data`는 `SEEK_DATA`를 구현하며 `->iomap_begin`에 `IOMAP_REPORT`를 전달합니다. unwritten mapping에서는 pagecache를 검색하고, folio가 mapping되어 있으며 그 안의 fsblock이 uptodate인 pagecache 영역을 data로 보고합니다. 호출자는 보통 `i_rwsem`을 shared mode로 잡습니다.

`iomap_seek_hole`은 `SEEK_HOLE`을 구현하고 같은 `IOMAP_REPORT` flag를 사용합니다. unwritten mapping에서 folio가 mapping되지 않았거나 folio 안에 `!uptodate` fsblock이 있는 pagecache 영역을 sparse hole로 보고합니다. 호출자는 보통 `i_rwsem` shared mode를 잡습니다.

Seeking Files
=============

iomap implements the two iterating whence modes of the ``llseek`` system
call.

SEEK_DATA
---------

The ``iomap_seek_data`` function implements the SEEK_DATA "whence" value
for llseek.
``IOMAP_REPORT`` will be passed as the ``flags`` argument to
``->iomap_begin``.

For unwritten mappings, the pagecache will be searched.
Regions of the pagecache with a folio mapped and uptodate fsblocks
within those folios will be reported as data areas.

Callers commonly hold ``i_rwsem`` in shared mode before calling this
function.

SEEK_HOLE
---------

The ``iomap_seek_hole`` function implements the SEEK_HOLE "whence" value
for llseek.
``IOMAP_REPORT`` will be passed as the ``flags`` argument to
``->iomap_begin``.

For unwritten mappings, the pagecache will be searched.
Regions of the pagecache with no folio mapped, or a !uptodate fsblock
within a folio will be reported as sparse hole areas.

Callers commonly hold ``i_rwsem`` in shared mode before calling this
function.

Swap file 활성화

`iomap_swapfile_activate`는 파일에서 base-page에 정렬된 모든 영역을 찾아 swap space로 설정합니다. 활성화 전에 파일을 `fsync()`합니다.

`->iomap_begin`에는 `IOMAP_REPORT`가 전달됩니다. 모든 mapping은 mapped 또는 unwritten이어야 하고 dirty나 shared이면 안 되며 여러 block device에 걸칠 수 없습니다.

호출자는 `i_rwsem`을 exclusive mode로 잡아야 하며 `swapon`이 이미 이를 제공합니다.

Swap File Activation
====================

The ``iomap_swapfile_activate`` function finds all the base-page aligned
regions in a file and sets them up as swap space.
The file will be ``fsync()``'d before activation.
``IOMAP_REPORT`` will be passed as the ``flags`` argument to
``->iomap_begin``.
All mappings must be mapped or unwritten; cannot be dirty or shared, and
cannot span multiple block devices.
Callers must hold ``i_rwsem`` in exclusive mode; this is already
provided by ``swapon``.

FIEMAP과 deprecated FIBMAP

iomap은 file space mapping을 보고하는 system call 가운데 두 가지를 구현합니다.

`iomap_fiemap`은 `FS_IOC_FIEMAP` ioctl이 지정한 형식으로 file extent mapping을 사용자 공간에 내보냅니다. `->iomap_begin`에는 `IOMAP_REPORT`가 전달되고 호출자는 보통 `i_rwsem`을 shared mode로 잡습니다.

`iomap_bmap`은 FIBMAP을 구현하며 호출 규약은 FIEMAP과 같습니다. iomap 전환 전부터 FIBMAP을 구현했던 파일시스템의 호환성 유지를 위해서만 제공합니다.

FIBMAP ioctl은 deprecated되었으므로 기존에 없는 파일시스템에 새 구현을 추가하면 안 됩니다. 호출자가 `i_rwsem`을 shared mode로 잡아야 할 가능성이 높지만 원문은 이 부분이 불분명하다고 명시합니다.

File Space Mapping Reporting
============================

iomap implements two of the file space mapping system calls.

FS_IOC_FIEMAP
-------------

The ``iomap_fiemap`` function exports file extent mappings to userspace
in the format specified by the ``FS_IOC_FIEMAP`` ioctl.
``IOMAP_REPORT`` will be passed as the ``flags`` argument to
``->iomap_begin``.
Callers commonly hold ``i_rwsem`` in shared mode before calling this
function.

FIBMAP (deprecated)
-------------------

``iomap_bmap`` implements FIBMAP.
The calling conventions are the same as for FIEMAP.
This function is only provided to maintain compatibility for filesystems
that implemented FIBMAP prior to conversion.
This ioctl is deprecated; do **not** add a FIBMAP implementation to
filesystems that do not have it.
Callers should probably hold ``i_rwsem`` in shared mode before calling
this function, but this is unclear.