filesystems/iomap/design.rst

70 of mapping function calls into the filesystem across a larger amount of
78    1. Obtain a space mapping via ``->iomap_begin``
82       1. Revalidate the mapping and go back to (1) above, if necessary.
89    4. Release the mapping via ``->iomap_end``, if necessary
130  * **filesystem mapping lock**: This synchronization primitive is
131    internal to the filesystem and must protect the file mapping data
132    from updates while a mapping is being sampled.
138    mapping.
154 The filesystem communicates to the iomap iterator the mapping of
177    bytes, covered by this mapping.
180  * ``type`` describes the type of the space mapping:
185      the mapping.
205      Reads from this type of mapping will return zeroes to the caller.
207      mapping to MAPPED.
216  * ``flags`` describe the status of the space mapping.
219    * **IOMAP_F_NEW**: The space under the mapping is newly allocated.
221      If a write fails and the mapping is a space reservation, the
231    * **IOMAP_F_SHARED**: The space under the mapping is shared.
234    * **IOMAP_F_BUFFER_HEAD**: This mapping requires the use of buffer
239      coalesced into this single mapping.
242    * **IOMAP_F_XATTR**: The mapping is for extended attribute data, not
258      using this mapping.
260    * **IOMAP_F_STALE**: The mapping was found to be stale.
261      iomap will call ``->iomap_end`` on this mapping and then
262      ``->iomap_begin`` to obtain a new mapping.
268  * ``bdev`` describes the block device for this mapping.
271  * ``dax_dev`` describes the DAX device for this mapping.
277    This value is ignored for all other mapping types.
298 structure to obtain a mapping and (optionally) to release the mapping:
315 iomap operations call ``->iomap_begin`` to obtain one file mapping for
318 This mapping should be returned through the ``iomap`` pointer.
319 The mapping must cover at least the first byte of the supplied file
345    single iomap mapping.
368 Only pagecache and fsdax operations support reading from one mapping and
375 is called to signal that iomap is finished with a mapping.
391 iomap only handles mapping and I/O.
416      access to the file space mapping information.
423      Filesystems with immutable mapping information may not require
432      For example, pagecache write operations will obtain a file mapping,