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.
254    The filesystem should supply an ``->iomap_end`` function if it needs
279  * ``private`` is a pointer to `filesystem-private information
285  * ``validity_cookie`` is a magic freshness value set by the filesystem
288    because page faults can occur, which implies that filesystem locks
297 Every iomap function requires the filesystem to pass an operations
340    instead of waiting for the specific unavailable filesystem resource
352    If there is any doubt in the filesystem developer's mind as to
366 device or address range on a device, the filesystem should return that
394 It does not handle obtaining filesystem freeze protection, updating of
404  * The **upper** level primitive is provided by the filesystem to
406    The exact primitive is specific to the filesystem and operation,
408    For example, a filesystem might take ``i_rwsem`` before calling
414    * The **lower** level primitive is taken by the filesystem in the
436 The exact locking requirements are specific to the filesystem; for
439 Each filesystem author must figure out the locking for themself.