filesystems/iomap/design.rst

20 iomap is a filesystem library for handling common file operations.
25     from the filesystem, but the storage information is not necessarily
52 The target audience for this document are filesystem, storage, and
63 the basis of that unit, the iomap model asks the filesystem for the
66 This strategy improves the filesystem's visibility into the size of the
70 of mapping function calls into the filesystem across a larger amount of
130  * **filesystem mapping lock**: This synchronization primitive is
131    internal to the filesystem and must protect the file mapping data
133    The filesystem author must determine how this coordination should
145    This implies that the filesystem must have already allocated space
146    on disk as ``IOMAP_MAPPED`` and the filesystem must not place any
154 The filesystem communicates to the iomap iterator the mapping of
178    These fields must always be set by the filesystem.
192      If the filesystem returns IOMAP_F_NEW here and the write fails, the
217    These flags should be set by the filesystem in ``->iomap_begin``:
247      be set by the filesystem for its own purposes.
250    The filesystem should supply an ``->iomap_end`` function if it needs
275  * ``private`` is a pointer to `filesystem-private information
281  * ``validity_cookie`` is a magic freshness value set by the filesystem
284    because page faults can occur, which implies that filesystem locks
293 Every iomap function requires the filesystem to pass an operations
336    instead of waiting for the specific unavailable filesystem resource
348    If there is any doubt in the filesystem developer's mind as to
357 device or address range on a device, the filesystem should return that
385 It does not handle obtaining filesystem freeze protection, updating of
395  * The **upper** level primitive is provided by the filesystem to
397    The exact primitive is specific to the filesystem and operation,
399    For example, a filesystem might take ``i_rwsem`` before calling
405    * The **lower** level primitive is taken by the filesystem in the
427 The exact locking requirements are specific to the filesystem; for
430 Each filesystem author must figure out the locking for themself.