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
254      using this mapping.
256    * **IOMAP_F_STALE**: The mapping was found to be stale.
257      iomap will call ``->iomap_end`` on this mapping and then
258      ``->iomap_begin`` to obtain a new mapping.
264  * ``bdev`` describes the block device for this mapping.
267  * ``dax_dev`` describes the DAX device for this mapping.
273    This value is ignored for all other mapping types.
294 structure to obtain a mapping and (optionally) to release the mapping:
311 iomap operations call ``->iomap_begin`` to obtain one file mapping for
314 This mapping should be returned through the ``iomap`` pointer.
315 The mapping must cover at least the first byte of the supplied file
341    single iomap mapping.
359 Only pagecache and fsdax operations support reading from one mapping and
366 is called to signal that iomap is finished with a mapping.
382 iomap only handles mapping and I/O.
407      access to the file space mapping information.
414      Filesystems with immutable mapping information may not require
423      For example, pagecache write operations will obtain a file mapping,