filesystems/iomap/design.rst

1 .. SPDX-License-Identifier: GPL-2.0
70 of mapping function calls into the filesystem across a larger amount of
71 data.
78    1. Obtain a space mapping via ``->iomap_begin``
80    2. For each sub-unit of work...
82       1. Revalidate the mapping and go back to (1) above, if necessary.
89    4. Release the mapping via ``->iomap_end``, if necessary
105 -----------
127    device pre-shutdown hook from returning before other threads have
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.
152 ----------------
154 The filesystem communicates to the iomap iterator the mapping of
158 .. code-block:: c
177    bytes, covered by this mapping.
180  * ``type`` describes the type of the space mapping:
185      the mapping.
193      ``->iomap_end`` function must delete the reservation.
205      Reads from this type of mapping will return zeroes to the caller.
207      mapping to MAPPED.
212      For write operation, the ``->iomap_end`` function presumably
213      handles persisting the data.
216  * ``flags`` describe the status of the space mapping.
217    These flags should be set by the filesystem in ``->iomap_begin``:
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
225      to access any data written.
231    * **IOMAP_F_SHARED**: The space under the mapping is shared.
232      Copy on write is necessary to avoid corrupting other file data.
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
243      regular file data.
254    The filesystem should supply an ``->iomap_end`` function if it needs
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.
279  * ``private`` is a pointer to `filesystem-private information
280    <https://lore.kernel.org/all/20180619164137.13720-7-hch@lst.de/>`_.
281    This value will be passed unchanged to ``->iomap_end``.
289    should not be held between ``->iomap_begin`` and ``->iomap_end``.
295 --------------------
298 structure to obtain a mapping and (optionally) to release the mapping:
300 .. code-block:: c
312 ``->iomap_begin``
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
325 operation-specific sections below.
333    memory-like storage.
338    This is similar in intent to ``O_NONBLOCK`` for network APIs - it is
345    single iomap mapping.
354    then they should return ``-EAGAIN`` as early as possible rather than
365 <https://lore.kernel.org/all/20191008071527.29304-9-hch@lst.de/>`_
368 Only pagecache and fsdax operations support reading from one mapping and
371 ``->iomap_end``
374 After the operation completes, the ``->iomap_end`` function, if present,
375 is called to signal that iomap is finished with a mapping.
377 context that were set up in ``->iomap_begin``.
382 ``flags`` will contain the same value passed to ``->iomap_begin``.
391 iomap only handles mapping and I/O.
415      ``->iomap_begin`` and ``->iomap_end`` functions to coordinate
416      access to the file space mapping information.
423      Filesystems with immutable mapping information may not require
427      coordinate access to its own internal data structures.
432      For example, pagecache write operations will obtain a file mapping,
448  * Does iomap *actually* work for non-regular file data?