Documentation/filesystems/iomap/design.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/iomap/design.rst
Extension
.rst
Size
18490 bytes
Lines
460
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 {
     u64                 addr;
     loff_t              offset;
     u64                 length;
     u16                 type;
     u16                 flags;
     struct block_device *bdev;
     struct dax_device   *dax_dev;
     void                *inline_data;
     void                *private;
     u64                 validity_cookie;
 };

The fields are as follows:

 * ``offset`` and ``length`` describe the range of file offsets, in
   bytes, covered by this mapping.
   These fields must always be set by the filesystem.

 * ``type`` describes the type of the space mapping:

   * **IOMAP_HOLE**: No storage has been allocated.
     This type must never be returned in response to an ``IOMAP_WRITE``
     operation because writes must allocate and map space, and return
     the mapping.
     The ``addr`` field must be set to ``IOMAP_NULL_ADDR``.
     iomap does not support writing (whether via pagecache or direct
     I/O) to a hole.

   * **IOMAP_DELALLOC**: A promise to allocate space at a later time
     ("delayed allocation").
     If the filesystem returns IOMAP_F_NEW here and the write fails, the
     ``->iomap_end`` function must delete the reservation.
     The ``addr`` field must be set to ``IOMAP_NULL_ADDR``.

   * **IOMAP_MAPPED**: The file range maps to specific space on the
     storage device.
     The device is returned in ``bdev`` or ``dax_dev``.
     The device address, in bytes, is returned via ``addr``.

   * **IOMAP_UNWRITTEN**: The file range maps to specific space on the
     storage device, but the space has not yet been initialized.
     The device is returned in ``bdev`` or ``dax_dev``.
     The device address, in bytes, is returned via ``addr``.
     Reads from this type of mapping will return zeroes to the caller.
     For a write or writeback operation, the ioend should update the
     mapping to MAPPED.
     Refer to the sections about ioends for more details.

   * **IOMAP_INLINE**: The file range maps to the memory buffer
     specified by ``inline_data``.
     For write operation, the ``->iomap_end`` function presumably
     handles persisting the data.
     The ``addr`` field must be set to ``IOMAP_NULL_ADDR``.

 * ``flags`` describe the status of the space mapping.
   These flags should be set by the filesystem in ``->iomap_begin``:

   * **IOMAP_F_NEW**: The space under the mapping is newly allocated.
     Areas that will not be written to must be zeroed.
     If a write fails and the mapping is a space reservation, the
     reservation must be deleted.

   * **IOMAP_F_DIRTY**: The inode will have uncommitted metadata needed
     to access any data written.
     fdatasync is required to commit these changes to persistent
     storage.
     This needs to take into account metadata changes that *may* be made
     at I/O completion, such as file size updates from direct I/O.

Annotation

Implementation Notes