Documentation/filesystems/iomap/operations.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/iomap/operations.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/iomap/operations.rst
Extension
.rst
Size
30237 bytes
Lines
786
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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``.

Annotation

Implementation Notes