sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget0/translations/zh_CN/filesystems/iomap/operationsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/zh_TW/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/it_IT/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ja_JP/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ko_KR/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/pt_BR/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/sp_SP/filesystems/iomap/operationsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhJ/var/lib/git/docbuild/linux/Documentation/filesystems/iomap/operations.rsthKubhtarget)}(h.. _iomap_operations:h]h}(h]iomap-operationsah ]h"]iomap_operationsah$]h&]uh1hhKhhhhhhubh)}(hDumb style notes to maintain the author's sanity: Please try to start sentences on separate lines so that sentence changes don't bleed colors in diff. Heading decorations are documented in sphinx.rst.h]hDumb style notes to maintain the author's sanity: Please try to start sentences on separate lines so that sentence changes don't bleed colors in diff. Heading decorations are documented in sphinx.rst.}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhK ubhsection)}(hhh](htitle)}(hSupported File Operationsh]hSupported File Operations}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubhtopic)}(hTable of Contents h](h)}(hTable of Contentsh]hTable of Contents}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh bullet_list)}(hhh](h list_item)}(hhh](h paragraph)}(hhh]h reference)}(hhh]h Buffered I/O}(hjhhhNhNubah}(h]id1ah ]h"]h$]h&]refid buffered-i-ouh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]hliteral)}(h#``struct address_space_operations``h]hstruct address_space_operations}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hNhNhj=ubah}(h]id2ah ]h"]h$]h&]refidstruct-address-space-operationsuh1jhj:ubah}(h]h ]h"]h$]h&]uh1jhj7ubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]jA)}(h``struct iomap_write_ops``h]hstruct iomap_write_ops}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hNhNhjkubah}(h]id3ah ]h"]h$]h&]refidstruct-iomap-write-opsuh1jhjhubah}(h]h ]h"]h$]h&]uh1jhjeubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]jA)}(h``struct iomap_read_ops``h]hstruct iomap_read_ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hNhNhjubah}(h]id4ah ]h"]h$]h&]refidstruct-iomap-read-opsuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]hInternal per-Folio State}(hjhhhNhNubah}(h]id5ah ]h"]h$]h&]refidinternal-per-folio-stateuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]hBuffered Readahead and Reads}(hjhhhNhNubah}(h]id6ah ]h"]h$]h&]refidbuffered-readahead-and-readsuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh](j)}(hhh]j)}(hhh]hBuffered Writes}(hjhhhNhNubah}(h]id7ah ]h"]h$]h&]refidbuffered-writesuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]hmmap Write Faults}(hj&hhhNhNubah}(h]id8ah ]h"]h$]h&]refidmmap-write-faultsuh1jhj#ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hBuffered Write Failures}(hjHhhhNhNubah}(h]id9ah ]h"]h$]h&]refidbuffered-write-failuresuh1jhjEubah}(h]h ]h"]h$]h&]uh1jhjBubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hZeroing for File Operations}(hjjhhhNhNubah}(h]id10ah ]h"]h$]h&]refidzeroing-for-file-operationsuh1jhjgubah}(h]h ]h"]h$]h&]uh1jhjdubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hUnsharing Reflinked File Data}(hjhhhNhNubah}(h]id11ah ]h"]h$]h&]refidunsharing-reflinked-file-datauh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]h Truncation}(hjhhhNhNubah}(h]id12ah ]h"]h$]h&]refid truncationuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh](j)}(hhh]j)}(hhh]hPagecache Writeback}(hjhhhNhNubah}(h]id13ah ]h"]h$]h&]refidpagecache-writebackuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]jA)}(h``struct iomap_writeback_ops``h]hstruct iomap_writeback_ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hNhNhjubah}(h]id14ah ]h"]h$]h&]refidstruct-iomap-writeback-opsuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hPagecache Writeback Completion}(hj'hhhNhNubah}(h]id15ah ]h"]h$]h&]refidpagecache-writeback-completionuh1jhj$ubah}(h]h ]h"]h$]h&]uh1jhj!ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhj4ubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]h Direct I/O}(hjahhhNhNubah}(h]id16ah ]h"]h$]h&]refid direct-i-ouh1jhj^ubah}(h]h ]h"]h$]h&]uh1jhj[ubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]h Return Values}(hjhhhNhNubah}(h]id17ah ]h"]h$]h&]refid return-valuesuh1jhj}ubah}(h]h ]h"]h$]h&]uh1jhjzubah}(h]h ]h"]h$]h&]uh1jhjwubj)}(hhh]j)}(hhh]j)}(hhh]h Direct Reads}(hjhhhNhNubah}(h]id18ah ]h"]h$]h&]refid direct-readsuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjwubj)}(hhh]j)}(hhh]j)}(hhh]h Direct Writes}(hjhhhNhNubah}(h]id19ah ]h"]h$]h&]refid direct-writesuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjwubj)}(hhh]j)}(hhh]j)}(hhh]jA)}(h``struct iomap_dio_ops:``h]hstruct iomap_dio_ops:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hNhNhjubah}(h]id20ah ]h"]h$]h&]refidstruct-iomap-dio-opsuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjwubeh}(h]h ]h"]h$]h&]uh1j hj[ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]hDAX I/O}(hjhhhNhNubah}(h]id21ah ]h"]h$]h&]refiddax-i-ouh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]h fsdax Reads}(hj=hhhNhNubah}(h]id22ah ]h"]h$]h&]refid fsdax-readsuh1jhj:ubah}(h]h ]h"]h$]h&]uh1jhj7ubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh](j)}(hhh]j)}(hhh]h fsdax Writes}(hj_hhhNhNubah}(h]id23ah ]h"]h$]h&]refid fsdax-writesuh1jhj\ubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]j)}(hhh]j)}(hhh]j)}(hhh]hfsdax mmap Faults}(hj~hhhNhNubah}(h]id24ah ]h"]h$]h&]refidfsdax-mmap-faultsuh1jhj{ubah}(h]h ]h"]h$]h&]uh1jhjxubah}(h]h ]h"]h$]h&]uh1jhjuubah}(h]h ]h"]h$]h&]uh1j hjYubeh}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]h*fsdax Truncation, fallocate, and Unsharing}(hjhhhNhNubah}(h]id25ah ]h"]h$]h&]refid(fsdax-truncation-fallocate-and-unsharinguh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubj)}(hhh]j)}(hhh]j)}(hhh]hfsdax Deduplication}(hjhhhNhNubah}(h]id26ah ]h"]h$]h&]refidfsdax-deduplicationuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj4ubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]h Seeking Files}(hjhhhNhNubah}(h]id27ah ]h"]h$]h&]refid seeking-filesuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]h SEEK_DATA}(hjhhhNhNubah}(h]id28ah ]h"]h$]h&]refid seek-datauh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]h SEEK_HOLE}(hj=hhhNhNubah}(h]id29ah ]h"]h$]h&]refid seek-holeuh1jhj:ubah}(h]h ]h"]h$]h&]uh1jhj7ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hSwap File Activation}(hjkhhhNhNubah}(h]id30ah ]h"]h$]h&]refidswap-file-activationuh1jhjhubah}(h]h ]h"]h$]h&]uh1jhjeubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]hFile Space Mapping Reporting}(hjhhhNhNubah}(h]id31ah ]h"]h$]h&]refidfile-space-mapping-reportinguh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]j)}(hhh]j)}(hhh]h FS_IOC_FIEMAP}(hjhhhNhNubah}(h]id32ah ]h"]h$]h&]refid fs-ioc-fiemapuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]j)}(hhh]j)}(hhh]hFIBMAP (deprecated)}(hjhhhNhNubah}(h]id33ah ]h"]h$]h&]refidfibmap-deprecateduh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hhhhhNhNubeh}(h]table-of-contentsah ](contentslocaleh"]table of contentsah$]h&]uh1hhhhKhhhhubj)}(hOBelow are a discussion of the high level file operations that iomap implements.h]hOBelow are a discussion of the high level file operations that iomap implements.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhhhhubh)}(hhh](h)}(h Buffered I/Oh]h Buffered I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]refidj'uh1hhjhhhhhKubj)}(hBuffered I/O is the default file I/O path in Linux. File contents are cached in memory ("pagecache") to satisfy reads and writes. Dirty cache will be written back to disk at some point that can be forced via ``fsync`` and variants.h](hBuffered I/O is the default file I/O path in Linux. File contents are cached in memory (“pagecache”) to satisfy reads and writes. Dirty cache will be written back to disk at some point that can be forced via }(hj&hhhNhNubjA)}(h ``fsync``h]hfsync}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj&ubh and variants.}(hj&hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hX\iomap implements nearly all the folio and pagecache management that filesystems have to implement themselves under the legacy I/O model. This means that the filesystem need not know the details of allocating, mapping, managing uptodate and dirty state, or writeback of pagecache folios. Under the legacy I/O model, this was managed very inefficiently with linked lists of buffer heads instead of the per-folio bitmaps that iomap uses. Unless the filesystem explicitly opts in to buffer heads, they will not be used, which makes buffered I/O much more efficient, and the pagecache maintainer much happier.h]hX\iomap implements nearly all the folio and pagecache management that filesystems have to implement themselves under the legacy I/O model. This means that the filesystem need not know the details of allocating, mapping, managing uptodate and dirty state, or writeback of pagecache folios. Under the legacy I/O model, this was managed very inefficiently with linked lists of buffer heads instead of the per-folio bitmaps that iomap uses. Unless the filesystem explicitly opts in to buffer heads, they will not be used, which makes buffered I/O much more efficient, and the pagecache maintainer much happier.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(hhh](h)}(hjDh]jA)}(hjDh]hstruct address_space_operations}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjWubah}(h]h ]h"]h$]h&]j%jRuh1hhjThhhhhK*ubj)}(heThe following iomap functions can be referenced directly from the address space operations structure:h]heThe following iomap functions can be referenced directly from the address space operations structure:}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK,hjThhubh block_quote)}(hq* ``iomap_dirty_folio`` * ``iomap_release_folio`` * ``iomap_invalidate_folio`` * ``iomap_is_partially_uptodate`` h]j)}(hhh](j)}(h``iomap_dirty_folio``h]j)}(hjh]jA)}(hjh]hiomap_dirty_folio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK/hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``iomap_release_folio``h]j)}(hjh]jA)}(hjh]hiomap_release_folio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK0hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``iomap_invalidate_folio``h]j)}(hjh]jA)}(hjh]hiomap_invalidate_folio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK1hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h ``iomap_is_partially_uptodate`` h]j)}(h``iomap_is_partially_uptodate``h]jA)}(hjh]hiomap_is_partially_uptodate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK2hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet*uh1j hhhK/hj}ubah}(h]h ]h"]h$]h&]uh1j{hhhK/hjThhubj)}(h=The following address space operations can be wrapped easily:h]h=The following address space operations can be wrapped easily:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK4hjThhubj|)}(hQ* ``read_folio`` * ``readahead`` * ``writepages`` * ``bmap`` * ``swap_activate`` h]j)}(hhh](j)}(h``read_folio``h]j)}(hj*h]jA)}(hj*h]h read_folio}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj,ubah}(h]h ]h"]h$]h&]uh1jhhhK6hj(ubah}(h]h ]h"]h$]h&]uh1jhj%ubj)}(h ``readahead``h]j)}(hjJh]jA)}(hjJh]h readahead}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjLubah}(h]h ]h"]h$]h&]uh1jhhhK7hjHubah}(h]h ]h"]h$]h&]uh1jhj%ubj)}(h``writepages``h]j)}(hjjh]jA)}(hjjh]h writepages}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjlubah}(h]h ]h"]h$]h&]uh1jhhhK8hjhubah}(h]h ]h"]h$]h&]uh1jhj%ubj)}(h``bmap``h]j)}(hjh]jA)}(hjh]hbmap}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK9hjubah}(h]h ]h"]h$]h&]uh1jhj%ubj)}(h``swap_activate`` h]j)}(h``swap_activate``h]jA)}(hjh]h swap_activate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]uh1jhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhj%ubeh}(h]h ]h"]h$]h&]j j uh1j hhhK6hj!ubah}(h]h ]h"]h$]h&]uh1j{hhhK6hjThhubeh}(h]jXah ]h"]struct address_space_operationsah$]h&]uh1hhjhhhhhK*ubh)}(hhh](h)}(hjph]jA)}(hjph]hstruct iomap_write_ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]j%j~uh1hhjhhhhhK=ubh literal_block)}(hXstruct iomap_write_ops { struct folio *(*get_folio)(struct iomap_iter *iter, loff_t pos, unsigned len); void (*put_folio)(struct inode *inode, loff_t pos, unsigned copied, struct folio *folio); bool (*iomap_valid)(struct inode *inode, const struct iomap *iomap); int (*read_folio_range)(const struct iomap_iter *iter, struct folio *folio, loff_t pos, size_t len); };h]hXstruct iomap_write_ops { struct folio *(*get_folio)(struct iomap_iter *iter, loff_t pos, unsigned len); void (*put_folio)(struct inode *inode, loff_t pos, unsigned copied, struct folio *folio); bool (*iomap_valid)(struct inode *inode, const struct iomap *iomap); int (*read_folio_range)(const struct iomap_iter *iter, struct folio *folio, loff_t pos, size_t len); };}hjsbah}(h]h ]h"]h$]h&]hhƌforcelanguagechighlight_args}uh1jhhhK?hjhhubj)}(hiomap calls these functions:h]hiomap calls these functions:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKKhjhhubj|)}(hX - ``get_folio``: Called to allocate and return an active reference to a locked folio prior to starting a write. If this function is not provided, iomap will call ``iomap_get_folio``. This could be used to `set up per-folio filesystem state `_ for a write. - ``put_folio``: Called to unlock and put a folio after a pagecache operation completes. If this function is not provided, iomap will ``folio_unlock`` and ``folio_put`` on its own. This could be used to `commit per-folio filesystem state `_ that was set up by ``->get_folio``. - ``iomap_valid``: The filesystem may not hold locks between ``->iomap_begin`` and ``->iomap_end`` because pagecache operations can take folio locks, fault on userspace pages, initiate writeback for memory reclamation, or engage in other time-consuming actions. If a file's space mapping data are mutable, it is possible that the mapping for a particular pagecache folio can `change in the time it takes `_ to allocate, install, and lock that folio. For the pagecache, races can happen if writeback doesn't take ``i_rwsem`` or ``invalidate_lock`` and updates mapping information. Races can also happen if the filesystem allows concurrent writes. For such files, the mapping *must* be revalidated after the folio lock has been taken so that iomap can manage the folio correctly. fsdax does not need this revalidation because there's no writeback and no support for unwritten extents. Filesystems subject to this kind of race must provide a ``->iomap_valid`` function to decide if the mapping is still valid. If the mapping is not valid, the mapping will be sampled again. To support making the validity decision, the filesystem's ``->iomap_begin`` function may set ``struct iomap::validity_cookie`` at the same time that it populates the other iomap fields. A simple validation cookie implementation is a sequence counter. If the filesystem bumps the sequence counter every time it modifies the inode's extent map, it can be placed in the ``struct iomap::validity_cookie`` during ``->iomap_begin``. If the value in the cookie is found to be different to the value the filesystem holds when the mapping is passed back to ``->iomap_valid``, then the iomap should considered stale and the validation failed. - ``read_folio_range``: Called to synchronously read in the range that will be written to. If this function is not provided, iomap will default to submitting a bio read request. h]j)}(hhh](j)}(hXG``get_folio``: Called to allocate and return an active reference to a locked folio prior to starting a write. If this function is not provided, iomap will call ``iomap_get_folio``. This could be used to `set up per-folio filesystem state `_ for a write. h]j)}(hXF``get_folio``: Called to allocate and return an active reference to a locked folio prior to starting a write. If this function is not provided, iomap will call ``iomap_get_folio``. This could be used to `set up per-folio filesystem state `_ for a write.h](jA)}(h ``get_folio``h]h get_folio}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh: Called to allocate and return an active reference to a locked folio prior to starting a write. If this function is not provided, iomap will call }(hj#hhhNhNubjA)}(h``iomap_get_folio``h]hiomap_get_folio}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh. This could be used to }(hj#hhhNhNubj)}(hn`set up per-folio filesystem state `_h]h!set up per-folio filesystem state}(hjKhhhNhNubah}(h]h ]h"]h$]h&]name!set up per-folio filesystem staterefuriGhttps://lore.kernel.org/all/20190429220934.10415-5-agruenba@redhat.com/uh1jhj#ubh)}(hJ h]h}(h]!set-up-per-folio-filesystem-stateah ]h"]!set up per-folio filesystem stateah$]h&]refurij\uh1hȌ referencedKhj#ubh for a write.}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXS``put_folio``: Called to unlock and put a folio after a pagecache operation completes. If this function is not provided, iomap will ``folio_unlock`` and ``folio_put`` on its own. This could be used to `commit per-folio filesystem state `_ that was set up by ``->get_folio``. h]j)}(hXR``put_folio``: Called to unlock and put a folio after a pagecache operation completes. If this function is not provided, iomap will ``folio_unlock`` and ``folio_put`` on its own. This could be used to `commit per-folio filesystem state `_ that was set up by ``->get_folio``.h](jA)}(h ``put_folio``h]h put_folio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhw: Called to unlock and put a folio after a pagecache operation completes. If this function is not provided, iomap will }(hjhhhNhNubjA)}(h``folio_unlock``h]h folio_unlock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h ``folio_put``h]h folio_put}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh# on its own. This could be used to }(hjhhhNhNubj)}(he`commit per-folio filesystem state `_h]h!commit per-folio filesystem state}(hjhhhNhNubah}(h]h ]h"]h$]h&]name!commit per-folio filesystem statej[>https://lore.kernel.org/all/20180619164137.13720-6-hch@lst.de/uh1jhjubh)}(hA h]h}(h]!commit-per-folio-filesystem-stateah ]h"]!commit per-folio filesystem stateah$]h&]refurijuh1hjjKhjubh that was set up by }(hjhhhNhNubjA)}(h``->get_folio``h]h ->get_folio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKUhj{ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``iomap_valid``: The filesystem may not hold locks between ``->iomap_begin`` and ``->iomap_end`` because pagecache operations can take folio locks, fault on userspace pages, initiate writeback for memory reclamation, or engage in other time-consuming actions. If a file's space mapping data are mutable, it is possible that the mapping for a particular pagecache folio can `change in the time it takes `_ to allocate, install, and lock that folio. For the pagecache, races can happen if writeback doesn't take ``i_rwsem`` or ``invalidate_lock`` and updates mapping information. Races can also happen if the filesystem allows concurrent writes. For such files, the mapping *must* be revalidated after the folio lock has been taken so that iomap can manage the folio correctly. fsdax does not need this revalidation because there's no writeback and no support for unwritten extents. Filesystems subject to this kind of race must provide a ``->iomap_valid`` function to decide if the mapping is still valid. If the mapping is not valid, the mapping will be sampled again. To support making the validity decision, the filesystem's ``->iomap_begin`` function may set ``struct iomap::validity_cookie`` at the same time that it populates the other iomap fields. A simple validation cookie implementation is a sequence counter. If the filesystem bumps the sequence counter every time it modifies the inode's extent map, it can be placed in the ``struct iomap::validity_cookie`` during ``->iomap_begin``. If the value in the cookie is found to be different to the value the filesystem holds when the mapping is passed back to ``->iomap_valid``, then the iomap should considered stale and the validation failed. h](j)}(hX ``iomap_valid``: The filesystem may not hold locks between ``->iomap_begin`` and ``->iomap_end`` because pagecache operations can take folio locks, fault on userspace pages, initiate writeback for memory reclamation, or engage in other time-consuming actions. If a file's space mapping data are mutable, it is possible that the mapping for a particular pagecache folio can `change in the time it takes `_ to allocate, install, and lock that folio.h](jA)}(h``iomap_valid``h]h iomap_valid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh,: The filesystem may not hold locks between }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h``->iomap_end``h]h ->iomap_end}(hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhX because pagecache operations can take folio locks, fault on userspace pages, initiate writeback for memory reclamation, or engage in other time-consuming actions. If a file’s space mapping data are mutable, it is possible that the mapping for a particular pagecache folio can }(hjhhhNhNubj)}(hi`change in the time it takes `_h]hchange in the time it takes}(hj7 hhhNhNubah}(h]h ]h"]h$]h&]namechange in the time it takesj[Hhttps://lore.kernel.org/all/20221123055812.747923-8-david@fromorbit.com/uh1jhjubh)}(hK h]h}(h]change-in-the-time-it-takesah ]h"]change in the time it takesah$]h&]refurijG uh1hjjKhjubh+ to allocate, install, and lock that folio.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhK]hjubj)}(hXGFor the pagecache, races can happen if writeback doesn't take ``i_rwsem`` or ``invalidate_lock`` and updates mapping information. Races can also happen if the filesystem allows concurrent writes. For such files, the mapping *must* be revalidated after the folio lock has been taken so that iomap can manage the folio correctly.h](h@For the pagecache, races can happen if writeback doesn’t take }(hj_ hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj_ ubh or }(hj_ hhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj_ ubh and updates mapping information. Races can also happen if the filesystem allows concurrent writes. For such files, the mapping }(hj_ hhhNhNubhemphasis)}(h*must*h]hmust}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj_ ubha be revalidated after the folio lock has been taken so that iomap can manage the folio correctly.}(hj_ hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKghjubj)}(hhfsdax does not need this revalidation because there's no writeback and no support for unwritten extents.h]hjfsdax does not need this revalidation because there’s no writeback and no support for unwritten extents.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKmhjubj)}(hFilesystems subject to this kind of race must provide a ``->iomap_valid`` function to decide if the mapping is still valid. If the mapping is not valid, the mapping will be sampled again.h](h8Filesystems subject to this kind of race must provide a }(hj hhhNhNubjA)}(h``->iomap_valid``h]h ->iomap_valid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubhr function to decide if the mapping is still valid. If the mapping is not valid, the mapping will be sampled again.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKphjubj)}(hXxTo support making the validity decision, the filesystem's ``->iomap_begin`` function may set ``struct iomap::validity_cookie`` at the same time that it populates the other iomap fields. A simple validation cookie implementation is a sequence counter. If the filesystem bumps the sequence counter every time it modifies the inode's extent map, it can be placed in the ``struct iomap::validity_cookie`` during ``->iomap_begin``. If the value in the cookie is found to be different to the value the filesystem holds when the mapping is passed back to ``->iomap_valid``, then the iomap should considered stale and the validation failed.h](hiomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh function may set }(hj hhhNhNubjA)}(h!``struct iomap::validity_cookie``h]hstruct iomap::validity_cookie}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh at the same time that it populates the other iomap fields. A simple validation cookie implementation is a sequence counter. If the filesystem bumps the sequence counter every time it modifies the inode’s extent map, it can be placed in the }(hj hhhNhNubjA)}(h!``struct iomap::validity_cookie``h]hstruct iomap::validity_cookie}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh during }(hj hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh{. If the value in the cookie is found to be different to the value the filesystem holds when the mapping is passed back to }(hj hhhNhNubjA)}(h``->iomap_valid``h]h ->iomap_valid}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubhC, then the iomap should considered stale and the validation failed.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKthjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(h``read_folio_range``: Called to synchronously read in the range that will be written to. If this function is not provided, iomap will default to submitting a bio read request. h]j)}(h``read_folio_range``: Called to synchronously read in the range that will be written to. If this function is not provided, iomap will default to submitting a bio read request.h](jA)}(h``read_folio_range``h]hread_folio_range}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjE ubh: Called to synchronously read in the range that will be written to. If this function is not provided, iomap will default to submitting a bio read request.}(hjE hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjA ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j -uh1j hhhKMhjubah}(h]h ]h"]h$]h&]uh1j{hhhKMhjhhubj)}(hIThese ``struct kiocb`` flags are significant for buffered I/O with iomap:h](hThese }(hjt hhhNhNubjA)}(h``struct kiocb``h]h struct kiocb}(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt ubh3 flags are significant for buffered I/O with iomap:}(hjt hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj|)}(hc* ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. * ``IOCB_DONTCACHE``: Turns on ``IOMAP_DONTCACHE``. h]j)}(hhh](j)}(h,``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. h]j)}(h+``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.h](jA)}(h``IOCB_NOWAIT``h]h IOCB_NOWAIT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh : Turns on }(hj hhhNhNubjA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h2``IOCB_DONTCACHE``: Turns on ``IOMAP_DONTCACHE``. h]j)}(h1``IOCB_DONTCACHE``: Turns on ``IOMAP_DONTCACHE``.h](jA)}(h``IOCB_DONTCACHE``h]hIOCB_DONTCACHE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh : Turns on }(hj hhhNhNubjA)}(h``IOMAP_DONTCACHE``h]hIOMAP_DONTCACHE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKhj ubah}(h]h ]h"]h$]h&]uh1j{hhhKhjhhubeh}(h]jah ]h"]struct iomap_write_opsah$]h&]uh1hhjhhhhhK=ubh)}(hhh](h)}(hjh]jA)}(hjh]hstruct iomap_read_ops}(hj$ hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj! ubah}(h]h ]h"]h$]h&]j%juh1hhj hhhhhKubj)}(hstruct iomap_read_ops { int (*read_folio_range)(const struct iomap_iter *iter, struct iomap_read_folio_ctx *ctx, size_t len); void (*submit_read)(struct iomap_read_folio_ctx *ctx); };h]hstruct iomap_read_ops { int (*read_folio_range)(const struct iomap_iter *iter, struct iomap_read_folio_ctx *ctx, size_t len); void (*submit_read)(struct iomap_read_folio_ctx *ctx); };}hj7 sbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKhj hhubj)}(hiomap calls these functions:h]hiomap calls these functions:}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj|)}(hX>- ``read_folio_range``: Called to read in the range. This must be provided by the caller. If this succeeds, iomap_finish_folio_read() must be called after the range is read in, regardless of whether the read succeeded or failed. - ``submit_read``: Submit any pending read requests. This function is optional. h]j)}(hhh](j)}(h``read_folio_range``: Called to read in the range. This must be provided by the caller. If this succeeds, iomap_finish_folio_read() must be called after the range is read in, regardless of whether the read succeeded or failed. h]j)}(h``read_folio_range``: Called to read in the range. This must be provided by the caller. If this succeeds, iomap_finish_folio_read() must be called after the range is read in, regardless of whether the read succeeded or failed.h](jA)}(h``read_folio_range``h]hread_folio_range}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj_ ubh: Called to read in the range. This must be provided by the caller. If this succeeds, iomap_finish_folio_read() must be called after the range is read in, regardless of whether the read succeeded or failed.}(hj_ hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj[ ubah}(h]h ]h"]h$]h&]uh1jhjX ubj)}(hN``submit_read``: Submit any pending read requests. This function is optional. h]j)}(hM``submit_read``: Submit any pending read requests. This function is optional.h](jA)}(h``submit_read``h]h submit_read}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh>: Submit any pending read requests. This function is optional.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjX ubeh}(h]h ]h"]h$]h&]j jm uh1j hhhKhjT ubah}(h]h ]h"]h$]h&]uh1j{hhhKhj hhubeh}(h]jah ]h"]struct iomap_read_opsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hInternal per-Folio Stateh]hInternal per-Folio State}(hj hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj hhhhhKubj)}(hX?If the fsblock size matches the size of a pagecache folio, it is assumed that all disk I/O operations will operate on the entire folio. The uptodate (memory contents are at least as new as what's on disk) and dirty (memory contents are newer than what's on disk) status of the folio are all that's needed for this case.h]hXEIf the fsblock size matches the size of a pagecache folio, it is assumed that all disk I/O operations will operate on the entire folio. The uptodate (memory contents are at least as new as what’s on disk) and dirty (memory contents are newer than what’s on disk) status of the folio are all that’s needed for this case.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hX(If the fsblock size is less than the size of a pagecache folio, iomap tracks the per-fsblock uptodate and dirty state itself. This enables iomap to handle both "bs < ps" `filesystems `_ and large folios in the pagecache.h](hIf the fsblock size is less than the size of a pagecache folio, iomap tracks the per-fsblock uptodate and dirty state itself. This enables iomap to handle both “bs < ps” }(hj hhhNhNubj)}(h[`filesystems `_h]h filesystems}(hj hhhNhNubah}(h]h ]h"]h$]h&]name filesystemsj[Jhttps://lore.kernel.org/all/20230725122932.144426-1-ritesh.list@gmail.com/uh1jhj ubh)}(hM h]h}(h] filesystemsah ]h"] filesystemsah$]h&]refurij uh1hjjKhj ubh# and large folios in the pagecache.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(h3iomap internally tracks two state bits per fsblock:h]h3iomap internally tracks two state bits per fsblock:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj|)}(hX* ``uptodate``: iomap will try to keep folios fully up to date. If there are read(ahead) errors, those fsblocks will not be marked uptodate. The folio itself will be marked uptodate when all fsblocks within the folio are uptodate. * ``dirty``: iomap will set the per-block dirty state when programs write to the file. The folio itself will be marked dirty when any fsblock within the folio is dirty. h]j)}(hhh](j)}(h``uptodate``: iomap will try to keep folios fully up to date. If there are read(ahead) errors, those fsblocks will not be marked uptodate. The folio itself will be marked uptodate when all fsblocks within the folio are uptodate. h]j)}(h``uptodate``: iomap will try to keep folios fully up to date. If there are read(ahead) errors, those fsblocks will not be marked uptodate. The folio itself will be marked uptodate when all fsblocks within the folio are uptodate.h](jA)}(h ``uptodate``h]huptodate}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj" ubh: iomap will try to keep folios fully up to date. If there are read(ahead) errors, those fsblocks will not be marked uptodate. The folio itself will be marked uptodate when all fsblocks within the folio are uptodate.}(hj" hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h``dirty``: iomap will set the per-block dirty state when programs write to the file. The folio itself will be marked dirty when any fsblock within the folio is dirty. h]j)}(h``dirty``: iomap will set the per-block dirty state when programs write to the file. The folio itself will be marked dirty when any fsblock within the folio is dirty.h](jA)}(h ``dirty``h]hdirty}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjH ubh: iomap will set the per-block dirty state when programs write to the file. The folio itself will be marked dirty when any fsblock within the folio is dirty.}(hjH hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjD ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKhj ubah}(h]h ]h"]h$]h&]uh1j{hhhKhj hhubj)}(hiomap also tracks the amount of read and write disk IOs that are in flight. This structure is much lighter weight than ``struct buffer_head`` because there is only one per folio, and the per-fsblock overhead is two bits vs. 104 bytes.h](hwiomap also tracks the amount of read and write disk IOs that are in flight. This structure is much lighter weight than }(hjv hhhNhNubjA)}(h``struct buffer_head``h]hstruct buffer_head}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjv ubh] because there is only one per folio, and the per-fsblock overhead is two bits vs. 104 bytes.}(hjv hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hFilesystems wishing to turn on large folios in the pagecache should call ``mapping_set_large_folios`` when initializing the incore inode.h](hIFilesystems wishing to turn on large folios in the pagecache should call }(hj hhhNhNubjA)}(h``mapping_set_large_folios``h]hmapping_set_large_folios}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh$ when initializing the incore inode.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubeh}(h]jah ]h"]internal per-folio stateah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hBuffered Readahead and Readsh]hBuffered Readahead and Reads}(hj hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj hhhhhKubj)}(hX(The ``iomap_readahead`` function initiates readahead to the pagecache. The ``iomap_read_folio`` function reads one folio's worth of data into the pagecache. The ``flags`` argument to ``->iomap_begin`` will be set to zero. The pagecache takes whatever locks it needs before calling the filesystem.h](hThe }(hj hhhNhNubjA)}(h``iomap_readahead``h]hiomap_readahead}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh4 function initiates readahead to the pagecache. The }(hj hhhNhNubjA)}(h``iomap_read_folio``h]hiomap_read_folio}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubhD function reads one folio’s worth of data into the pagecache. The }(hj hhhNhNubjA)}(h ``flags``h]hflags}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh argument to }(hj hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh` will be set to zero. The pagecache takes whatever locks it needs before calling the filesystem.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(h\Both ``iomap_readahead`` and ``iomap_read_folio`` pass in a ``struct iomap_read_folio_ctx``:h](hBoth }(hj$ hhhNhNubjA)}(h``iomap_readahead``h]hiomap_readahead}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj$ ubh and }(hj$ hhhNhNubjA)}(h``iomap_read_folio``h]hiomap_read_folio}(hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj$ ubh pass in a }(hj$ hhhNhNubjA)}(h``struct iomap_read_folio_ctx``h]hstruct iomap_read_folio_ctx}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj$ ubh:}(hj$ hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubj)}(hstruct iomap_read_folio_ctx { const struct iomap_read_ops *ops; struct folio *cur_folio; struct readahead_control *rac; void *read_ctx; };h]hstruct iomap_read_folio_ctx { const struct iomap_read_ops *ops; struct folio *cur_folio; struct readahead_control *rac; void *read_ctx; };}hjh sbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKhj hhubhdefinition_list)}(hhh](hdefinition_list_item)}(hH``iomap_readahead`` must set: * ``ops->read_folio_range()`` and ``rac`` h](hterm)}(h``iomap_readahead`` must set:h](jA)}(h``iomap_readahead``h]hiomap_readahead}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh must set:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1j hhhKhj~ ubh definition)}(hhh]j)}(hhh]j)}(h(``ops->read_folio_range()`` and ``rac`` h]j)}(h'``ops->read_folio_range()`` and ``rac``h](jA)}(h``ops->read_folio_range()``h]hops->read_folio_range()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh and }(hj hhhNhNubjA)}(h``rac``h]hrac}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubeh}(h]h ]h"]h$]h&]uh1jhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]j j uh1j hhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj~ ubeh}(h]h ]h"]h$]h&]uh1j| hhhKhjy ubj} )}(hO``iomap_read_folio`` must set: * ``ops->read_folio_range()`` and ``cur_folio`` h](j )}(h``iomap_read_folio`` must set:h](jA)}(h``iomap_read_folio``h]hiomap_read_folio}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj ubh must set:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1j hhhKhj ubj )}(hhh]j)}(hhh]j)}(h.``ops->read_folio_range()`` and ``cur_folio`` h]j)}(h-``ops->read_folio_range()`` and ``cur_folio``h](jA)}(h``ops->read_folio_range()``h]hops->read_folio_range()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h ``cur_folio``h]h cur_folio}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]j j uh1j hhhKhjubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j| hhhKhjy hhubeh}(h]h ]h"]h$]h&]uh1jw hj hhhNhNubj)}(h``ops->submit_read()`` and ``read_ctx`` are optional. ``read_ctx`` is used to pass in any custom data the caller needs accessible in the ops callbacks for fulfilling reads.h](jA)}(h``ops->submit_read()``h]hops->submit_read()}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj`ubh and }(hj`hhhNhNubjA)}(h ``read_ctx``h]hread_ctx}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj`ubh are optional. }(hj`hhhNhNubjA)}(h ``read_ctx``h]hread_ctx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj`ubhj is used to pass in any custom data the caller needs accessible in the ops callbacks for fulfilling reads.}(hj`hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhj hhubeh}(h]jah ]h"]buffered readahead and readsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hBuffered Writesh]hBuffered Writes}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhKubj)}(hX'The ``iomap_file_buffered_write`` function writes an ``iocb`` to the pagecache. ``IOMAP_WRITE`` or ``IOMAP_WRITE`` | ``IOMAP_NOWAIT`` will be passed as the ``flags`` argument to ``->iomap_begin``. Callers commonly take ``i_rwsem`` in either shared or exclusive mode before calling this function.h](hThe }(hjhhhNhNubjA)}(h``iomap_file_buffered_write``h]hiomap_file_buffered_write}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh function writes an }(hjhhhNhNubjA)}(h``iocb``h]hiocb}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh to the pagecache. }(hjhhhNhNubjA)}(h``IOMAP_WRITE``h]h IOMAP_WRITE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh or }(hjhhhNhNubjA)}(h``IOMAP_WRITE``h]h IOMAP_WRITE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh | }(hjhhhNhNubjA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be passed as the }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh argument to }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh. Callers commonly take }(hjhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhA in either shared or exclusive mode before calling this function.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(hhh](h)}(hmmap Write Faultsh]hmmap Write Faults}(hjYhhhNhNubah}(h]h ]h"]h$]h&]j%j/uh1hhjVhhhhhKubj)}(hX The ``iomap_page_mkwrite`` function handles a write fault to a folio in the pagecache. ``IOMAP_WRITE | IOMAP_FAULT`` will be passed as the ``flags`` argument to ``->iomap_begin``. Callers commonly take the mmap ``invalidate_lock`` in shared or exclusive mode before calling this function.h](hThe }(hjghhhNhNubjA)}(h``iomap_page_mkwrite``h]hiomap_page_mkwrite}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjgubh= function handles a write fault to a folio in the pagecache. }(hjghhhNhNubjA)}(h``IOMAP_WRITE | IOMAP_FAULT``h]hIOMAP_WRITE | IOMAP_FAULT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjgubh will be passed as the }(hjghhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjgubh argument to }(hjghhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjgubh!. Callers commonly take the mmap }(hjghhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjgubh: in shared or exclusive mode before calling this function.}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjVhhubeh}(h]j5ah ]h"]mmap write faultsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hBuffered Write Failuresh]hBuffered Write Failures}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%jQuh1hhjhhhhhKubj)}(hX;After a short write to the pagecache, the areas not written will not become marked dirty. The filesystem must arrange to `cancel `_ such `reservations `_ because writeback will not consume the reservation. The ``iomap_write_delalloc_release`` can be called from a ``->iomap_end`` function to find all the clean areas of the folios caching a fresh (``IOMAP_F_NEW``) delalloc mapping. It takes the ``invalidate_lock``.h](hyAfter a short write to the pagecache, the areas not written will not become marked dirty. The filesystem must arrange to }(hjhhhNhNubj)}(hT`cancel `_h]hcancel}(hjhhhNhNubah}(h]h ]h"]h$]h&]namecancelj[Hhttps://lore.kernel.org/all/20221123055812.747923-6-david@fromorbit.com/uh1jhjubh)}(hK h]h}(h]cancelah ]h"]cancelah$]h&]refurijuh1hjjKhjubh such }(hjhhhNhNubj)}(ha`reservations `_h]h reservations}(hjhhhNhNubah}(h]h ]h"]h$]h&]name reservationsj[Ohttps://lore.kernel.org/linux-xfs/20220817093627.GZ3600936@dread.disaster.area/uh1jhjubh)}(hR h]h}(h] reservationsah ]h"] reservationsah$]h&]refurij!uh1hjjKhjubh9 because writeback will not consume the reservation. The }(hjhhhNhNubjA)}(h ``iomap_write_delalloc_release``h]hiomap_write_delalloc_release}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh can be called from a }(hjhhhNhNubjA)}(h``->iomap_end``h]h ->iomap_end}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhE function to find all the clean areas of the folios caching a fresh (}(hjhhhNhNubjA)}(h``IOMAP_F_NEW``h]h IOMAP_F_NEW}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh!) delalloc mapping. It takes the }(hjhhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hX:The filesystem must supply a function ``punch`` to be called for each file range in this state. This function must *only* remove delayed allocation reservations, in case another thread racing with the current thread writes successfully to the same region and triggers writeback to flush the dirty data out to disk.h](h&The filesystem must supply a function }(hjhhhNhNubjA)}(h ``punch``h]hpunch}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhD to be called for each file range in this state. This function must }(hjhhhNhNubj )}(h*only*h]honly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh remove delayed allocation reservations, in case another thread racing with the current thread writes successfully to the same region and triggers writeback to flush the dirty data out to disk.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]jWah ]h"]buffered write failuresah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hZeroing for File Operationsh]hZeroing for File Operations}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%jsuh1hhjhhhhhMubj)}(hXSFilesystems can call ``iomap_zero_range`` to perform zeroing of the pagecache for non-truncation file operations that are not aligned to the fsblock size. ``IOMAP_ZERO`` will be passed as the ``flags`` argument to ``->iomap_begin``. Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive mode before calling this function.h](hFilesystems can call }(hjhhhNhNubjA)}(h``iomap_zero_range``h]hiomap_zero_range}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhr to perform zeroing of the pagecache for non-truncation file operations that are not aligned to the fsblock size. }(hjhhhNhNubjA)}(h``IOMAP_ZERO``h]h IOMAP_ZERO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be passed as the }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh argument to }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh. Callers typically hold }(hjhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh0 in exclusive mode before calling this function.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]jyah ]h"]zeroing for file operationsah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hUnsharing Reflinked File Datah]hUnsharing Reflinked File Data}(hjOhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjLhhhhhMubj)}(hXgFilesystems can call ``iomap_file_unshare`` to force a file sharing storage with another file to preemptively copy the shared data to newly allocate storage. ``IOMAP_WRITE | IOMAP_UNSHARE`` will be passed as the ``flags`` argument to ``->iomap_begin``. Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive mode before calling this function.h](hFilesystems can call }(hj]hhhNhNubjA)}(h``iomap_file_unshare``h]hiomap_file_unshare}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubhs to force a file sharing storage with another file to preemptively copy the shared data to newly allocate storage. }(hj]hhhNhNubjA)}(h``IOMAP_WRITE | IOMAP_UNSHARE``h]hIOMAP_WRITE | IOMAP_UNSHARE}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubh will be passed as the }(hj]hhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubh argument to }(hj]hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubh. Callers typically hold }(hj]hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubh and }(hj]hhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj]ubh0 in exclusive mode before calling this function.}(hj]hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjLhhubeh}(h]jah ]h"]unsharing reflinked file dataah$]h&]uh1hhjhhhhhMubeh}(h]jah ]h"]buffered writesah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Truncationh]h Truncation}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhM%ubj)}(hXFilesystems can call ``iomap_truncate_page`` to zero the bytes in the pagecache from EOF to the end of the fsblock during a file truncation operation. ``truncate_setsize`` or ``truncate_pagecache`` will take care of everything after the EOF block. ``IOMAP_ZERO`` will be passed as the ``flags`` argument to ``->iomap_begin``. Callers typically hold ``i_rwsem`` and ``invalidate_lock`` in exclusive mode before calling this function.h](hFilesystems can call }(hjhhhNhNubjA)}(h``iomap_truncate_page``h]hiomap_truncate_page}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhk to zero the bytes in the pagecache from EOF to the end of the fsblock during a file truncation operation. r}(hjhhhNhNubjA)}(h``truncate_setsize``h]htruncate_setsize}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh or }(hjhhhNhNubjA)}(h``truncate_pagecache``h]htruncate_pagecache}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh3 will take care of everything after the EOF block. }(hjhhhNhNubjA)}(h``IOMAP_ZERO``h]h IOMAP_ZERO}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be passed as the }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh argument to }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh. Callers typically hold }(hjhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh0 in exclusive mode before calling this function.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM'hjhhubeh}(h]jah ]h"] truncationah$]h&]uh1hhjhhhhhM%ubh)}(hhh](h)}(hPagecache Writebackh]hPagecache Writeback}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhM2ubj)}(hXFilesystems can call ``iomap_writepages`` to respond to a request to write dirty pagecache folios to disk. The ``mapping`` and ``wbc`` parameters should be passed unchanged. The ``wpc`` pointer should be allocated by the filesystem and must be initialized to zero.h](hFilesystems can call }(hjhhhNhNubjA)}(h``iomap_writepages``h]hiomap_writepages}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhF to respond to a request to write dirty pagecache folios to disk. The }(hjhhhNhNubjA)}(h ``mapping``h]hmapping}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h``wbc``h]hwbc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh, parameters should be passed unchanged. The }(hjhhhNhNubjA)}(h``wpc``h]hwpc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhO pointer should be allocated by the filesystem and must be initialized to zero.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM4hjhhubj)}(hThe pagecache will lock each folio before trying to schedule it for writeback. It does not lock ``i_rwsem`` or ``invalidate_lock``.h](h`The pagecache will lock each folio before trying to schedule it for writeback. It does not lock }(hjhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh or }(hjhhhNhNubjA)}(h``invalidate_lock``h]hinvalidate_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM:hjhhubj)}(hX The dirty bit will be cleared for all folios run through the ``->writeback_range`` machinery described below even if the writeback fails. This is to prevent dirty folio clots when storage devices fail; an ``-EIO`` is recorded for userspace to collect via ``fsync``.h](h=The dirty bit will be cleared for all folios run through the }(hj4hhhNhNubjA)}(h``->writeback_range``h]h->writeback_range}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj4ubh{ machinery described below even if the writeback fails. This is to prevent dirty folio clots when storage devices fail; an }(hj4hhhNhNubjA)}(h``-EIO``h]h-EIO}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj4ubh* is recorded for userspace to collect via }(hj4hhhNhNubjA)}(h ``fsync``h]hfsync}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj4ubh.}(hj4hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM>hjhhubj)}(h:The ``ops`` structure must be specified and is as follows:h](hThe }(hjxhhhNhNubjA)}(h``ops``h]hops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjxubh/ structure must be specified and is as follows:}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMChjhhubh)}(hhh](h)}(hjh]jA)}(hjh]hstruct iomap_writeback_ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhMFubj)}(hstruct iomap_writeback_ops { int (*writeback_range)(struct iomap_writepage_ctx *wpc, struct folio *folio, u64 pos, unsigned int len, u64 end_pos); int (*writeback_submit)(struct iomap_writepage_ctx *wpc, int error); };h]hstruct iomap_writeback_ops { int (*writeback_range)(struct iomap_writepage_ctx *wpc, struct folio *folio, u64 pos, unsigned int len, u64 end_pos); int (*writeback_submit)(struct iomap_writepage_ctx *wpc, int error); };}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMHhjhhubj)}(hThe fields are as follows:h]hThe fields are as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMPhjhhubj|)}(hX - ``writeback_range``: Sets ``wpc->iomap`` to the space mapping of the file range (in bytes) given by ``offset`` and ``len``. iomap calls this function for each dirty fs block in each dirty folio, though it will `reuse mappings `_ for runs of contiguous dirty fsblocks within a folio. Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end`` function must deal with persisting written data. Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently requires mapping to allocated space. Filesystems can skip a potentially expensive mapping lookup if the mappings have not changed. This revalidation must be open-coded by the filesystem; it is unclear if ``iomap::validity_cookie`` can be reused for this purpose. If this methods fails to schedule I/O for any part of a dirty folio, it should throw away any reservations that may have been made for the write. The folio will be marked clean and an ``-EIO`` recorded in the pagecache. Filesystems can use this callback to `remove `_ delalloc reservations to avoid having delalloc reservations for clean pagecache. This function must be supplied by the filesystem. If this succeeds, iomap_finish_folio_write() must be called once writeback completes for the range, regardless of whether the writeback succeeded or failed. - ``writeback_submit``: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom ``->bi_end_io`` function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update transactions from process context before submitting the bio. This function must be supplied by the filesystem. h]j)}(hhh](j)}(hX``writeback_range``: Sets ``wpc->iomap`` to the space mapping of the file range (in bytes) given by ``offset`` and ``len``. iomap calls this function for each dirty fs block in each dirty folio, though it will `reuse mappings `_ for runs of contiguous dirty fsblocks within a folio. Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end`` function must deal with persisting written data. Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently requires mapping to allocated space. Filesystems can skip a potentially expensive mapping lookup if the mappings have not changed. This revalidation must be open-coded by the filesystem; it is unclear if ``iomap::validity_cookie`` can be reused for this purpose. If this methods fails to schedule I/O for any part of a dirty folio, it should throw away any reservations that may have been made for the write. The folio will be marked clean and an ``-EIO`` recorded in the pagecache. Filesystems can use this callback to `remove `_ delalloc reservations to avoid having delalloc reservations for clean pagecache. This function must be supplied by the filesystem. If this succeeds, iomap_finish_folio_write() must be called once writeback completes for the range, regardless of whether the writeback succeeded or failed. h](j)}(hX``writeback_range``: Sets ``wpc->iomap`` to the space mapping of the file range (in bytes) given by ``offset`` and ``len``. iomap calls this function for each dirty fs block in each dirty folio, though it will `reuse mappings `_ for runs of contiguous dirty fsblocks within a folio. Do not return ``IOMAP_INLINE`` mappings here; the ``->iomap_end`` function must deal with persisting written data. Do not return ``IOMAP_DELALLOC`` mappings here; iomap currently requires mapping to allocated space. Filesystems can skip a potentially expensive mapping lookup if the mappings have not changed. This revalidation must be open-coded by the filesystem; it is unclear if ``iomap::validity_cookie`` can be reused for this purpose.h](jA)}(h``writeback_range``h]hwriteback_range}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh: Sets }(hjhhhNhNubjA)}(h``wpc->iomap``h]h wpc->iomap}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh< to the space mapping of the file range (in bytes) given by }(hjhhhNhNubjA)}(h ``offset``h]hoffset}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh and }(hjhhhNhNubjA)}(h``len``h]hlen}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhX. iomap calls this function for each dirty fs block in each dirty folio, though it will }(hjhhhNhNubj)}(hT`reuse mappings `_h]hreuse mappings}(hj%hhhNhNubah}(h]h ]h"]h$]h&]namereuse mappingsj[@https://lore.kernel.org/all/20231207072710.176093-15-hch@lst.de/uh1jhjubh)}(hC h]h}(h]reuse-mappingsah ]h"]reuse mappingsah$]h&]refurij5uh1hjjKhjubhE for runs of contiguous dirty fsblocks within a folio. Do not return }(hjhhhNhNubjA)}(h``IOMAP_INLINE``h]h IOMAP_INLINE}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh mappings here; the }(hjhhhNhNubjA)}(h``->iomap_end``h]h ->iomap_end}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh@ function must deal with persisting written data. Do not return }(hjhhhNhNubjA)}(h``IOMAP_DELALLOC``h]hIOMAP_DELALLOC}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh mappings here; iomap currently requires mapping to allocated space. Filesystems can skip a potentially expensive mapping lookup if the mappings have not changed. This revalidation must be open-coded by the filesystem; it is unclear if }(hjhhhNhNubjA)}(h``iomap::validity_cookie``h]hiomap::validity_cookie}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh can be reused for this purpose.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMRhjubj)}(hXuIf this methods fails to schedule I/O for any part of a dirty folio, it should throw away any reservations that may have been made for the write. The folio will be marked clean and an ``-EIO`` recorded in the pagecache. Filesystems can use this callback to `remove `_ delalloc reservations to avoid having delalloc reservations for clean pagecache. This function must be supplied by the filesystem. If this succeeds, iomap_finish_folio_write() must be called once writeback completes for the range, regardless of whether the writeback succeeded or failed.h](hIf this methods fails to schedule I/O for any part of a dirty folio, it should throw away any reservations that may have been made for the write. The folio will be marked clean and an }(hjhhhNhNubjA)}(h``-EIO``h]h-EIO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhA recorded in the pagecache. Filesystems can use this callback to }(hjhhhNhNubj)}(hT`remove `_h]hremove}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameremovej[Hhttps://lore.kernel.org/all/20201029163313.1766967-1-bfoster@redhat.com/uh1jhjubh)}(hK h]h}(h]removeah ]h"]removeah$]h&]refurijuh1hjjKhjubhX  delalloc reservations to avoid having delalloc reservations for clean pagecache. This function must be supplied by the filesystem. If this succeeds, iomap_finish_folio_write() must be called once writeback completes for the range, regardless of whether the writeback succeeded or failed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMbhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hX5``writeback_submit``: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom ``->bi_end_io`` function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update transactions from process context before submitting the bio. This function must be supplied by the filesystem. h]j)}(hX4``writeback_submit``: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom ``->bi_end_io`` function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update transactions from process context before submitting the bio. This function must be supplied by the filesystem.h](jA)}(h``writeback_submit``h]hwriteback_submit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhX5: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom }(hjhhhNhNubjA)}(h``->bi_end_io``h]h ->bi_end_io}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update transactions from process context before submitting the bio. This function must be supplied by the filesystem.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMohjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j jm uh1j hhhMRhjubah}(h]h ]h"]h$]h&]uh1j{hhhMRhjhhubeh}(h]jah ]h"]struct iomap_writeback_opsah$]h&]uh1hhjhhhhhMFubh)}(hhh](h)}(hPagecache Writeback Completionh]hPagecache Writeback Completion}(hj+hhhNhNubah}(h]h ]h"]h$]h&]j%j0uh1hhj(hhhhhMzubj)}(hXTo handle the bookkeeping that must happen after disk I/O for writeback completes, iomap creates chains of ``struct iomap_ioend`` objects that wrap the ``bio`` that is used to write pagecache data to disk. By default, iomap finishes writeback ioends by clearing the writeback bit on the folios attached to the ``ioend``. If the write failed, it will also set the error bits on the folios and the address space. This can happen in interrupt or process context, depending on the storage device. Filesystems that need to update internal bookkeeping (e.g. unwritten extent conversions) should set their own bi_end_io on the bios submitted by ``->submit_writeback`` This function should call ``iomap_finish_ioends`` after finishing its own work (e.g. unwritten extent conversion).h](hkTo handle the bookkeeping that must happen after disk I/O for writeback completes, iomap creates chains of }(hj9hhhNhNubjA)}(h``struct iomap_ioend``h]hstruct iomap_ioend}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh objects that wrap the }(hj9hhhNhNubjA)}(h``bio``h]hbio}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh that is used to write pagecache data to disk. By default, iomap finishes writeback ioends by clearing the writeback bit on the folios attached to the }(hj9hhhNhNubjA)}(h ``ioend``h]hioend}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubhX?. If the write failed, it will also set the error bits on the folios and the address space. This can happen in interrupt or process context, depending on the storage device. Filesystems that need to update internal bookkeeping (e.g. unwritten extent conversions) should set their own bi_end_io on the bios submitted by }(hj9hhhNhNubjA)}(h``->submit_writeback``h]h->submit_writeback}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh This function should call }(hj9hhhNhNubjA)}(h``iomap_finish_ioends``h]hiomap_finish_ioends}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubhA after finishing its own work (e.g. unwritten extent conversion).}(hj9hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM|hj(hhubj)}(hXqSome filesystems may wish to `amortize the cost of running metadata transactions `_ for post-writeback updates by batching them. They may also require transactions to run from process context, which implies punting batches to a workqueue. iomap ioends contain a ``list_head`` to enable batching.h](hSome filesystems may wish to }(hjhhhNhNubj)}(h`amortize the cost of running metadata transactions `_h]h2amortize the cost of running metadata transactions}(hjhhhNhNubah}(h]h ]h"]h$]h&]name2amortize the cost of running metadata transactionsj[Hhttps://lore.kernel.org/all/20220120034733.221737-1-david@fromorbit.com/uh1jhjubh)}(hK h]h}(h]2amortize-the-cost-of-running-metadata-transactionsah ]h"]2amortize the cost of running metadata transactionsah$]h&]refurijuh1hjjKhjubh for post-writeback updates by batching them. They may also require transactions to run from process context, which implies punting batches to a workqueue. iomap ioends contain a }(hjhhhNhNubjA)}(h ``list_head``h]h list_head}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh to enable batching.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj(hhubj)}(hMGiven a batch of ioends, iomap has a few helpers to assist with amortization:h]hMGiven a batch of ioends, iomap has a few helpers to assist with amortization:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj(hhubj|)}(hX9* ``iomap_sort_ioends``: Sort all the ioends in the list by file offset. * ``iomap_ioend_try_merge``: Given an ioend that is not in any list and a separate list of sorted ioends, merge as many of the ioends from the head of the list into the given ioend. ioends can only be merged if the file range and storage addresses are contiguous; the unwritten and shared status are the same; and the write I/O outcome is the same. The merged ioends become their own list. * ``iomap_finish_ioends``: Finish an ioend that possibly has other ioends linked to it. h]j)}(hhh](j)}(hG``iomap_sort_ioends``: Sort all the ioends in the list by file offset. h]j)}(hF``iomap_sort_ioends``: Sort all the ioends in the list by file offset.h](jA)}(h``iomap_sort_ioends``h]hiomap_sort_ioends}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh1: Sort all the ioends in the list by file offset.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``iomap_ioend_try_merge``: Given an ioend that is not in any list and a separate list of sorted ioends, merge as many of the ioends from the head of the list into the given ioend. ioends can only be merged if the file range and storage addresses are contiguous; the unwritten and shared status are the same; and the write I/O outcome is the same. The merged ioends become their own list. h]j)}(hX``iomap_ioend_try_merge``: Given an ioend that is not in any list and a separate list of sorted ioends, merge as many of the ioends from the head of the list into the given ioend. ioends can only be merged if the file range and storage addresses are contiguous; the unwritten and shared status are the same; and the write I/O outcome is the same. The merged ioends become their own list.h](jA)}(h``iomap_ioend_try_merge``h]hiomap_ioend_try_merge}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj"ubhXj: Given an ioend that is not in any list and a separate list of sorted ioends, merge as many of the ioends from the head of the list into the given ioend. ioends can only be merged if the file range and storage addresses are contiguous; the unwritten and shared status are the same; and the write I/O outcome is the same. The merged ioends become their own list.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hV``iomap_finish_ioends``: Finish an ioend that possibly has other ioends linked to it. h]j)}(hU``iomap_finish_ioends``: Finish an ioend that possibly has other ioends linked to it.h](jA)}(h``iomap_finish_ioends``h]hiomap_finish_ioends}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjHubh>: Finish an ioend that possibly has other ioends linked to it.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjDubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhj(hhubeh}(h]j6ah ]h"]pagecache writeback completionah$]h&]uh1hhjhhhhhMzubeh}(h]jah ]h"]pagecache writebackah$]h&]uh1hhjhhhhhM2ubeh}(h]j-ah ]h"] buffered i/oah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Direct I/Oh]h Direct I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%jjuh1hhjhhhhhMubj)}(hIn Linux, direct I/O is defined as file I/O that is issued directly to storage, bypassing the pagecache. The ``iomap_dio_rw`` function implements O_DIRECT (direct I/O) reads and writes for files.h](hmIn Linux, direct I/O is defined as file I/O that is issued directly to storage, bypassing the pagecache. The }(hjhhhNhNubjA)}(h``iomap_dio_rw``h]h iomap_dio_rw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhF function implements O_DIRECT (direct I/O) reads and writes for files.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hXssize_t iomap_dio_rw(struct kiocb *iocb, struct iov_iter *iter, const struct iomap_ops *ops, const struct iomap_dio_ops *dops, unsigned int dio_flags, void *private, size_t done_before);h]hXssize_t iomap_dio_rw(struct kiocb *iocb, struct iov_iter *iter, const struct iomap_ops *ops, const struct iomap_dio_ops *dops, unsigned int dio_flags, void *private, size_t done_before);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMhjhhubj)}(hXThe filesystem can provide the ``dops`` parameter if it needs to perform extra work before or after the I/O is issued to storage. The ``done_before`` parameter tells the how much of the request has already been transferred. It is used to continue a request asynchronously when `part of the request `_ has already been completed synchronously.h](hThe filesystem can provide the }(hjhhhNhNubjA)}(h``dops``h]hdops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh_ parameter if it needs to perform extra work before or after the I/O is issued to storage. The }(hjhhhNhNubjA)}(h``done_before``h]h done_before}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh parameter tells the how much of the request has already been transferred. It is used to continue a request asynchronously when }(hjhhhNhNubj)}(h`part of the request `_h]hpart of the request}(hjhhhNhNubah}(h]h ]h"]h$]h&]namepart of the requestj[vhttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c03098d4b9ad76bca2966a8769dcfe59f7f85103uh1jhjubh)}(hy h]h}(h]part-of-the-requestah ]h"]part of the requestah$]h&]refurijuh1hjjKhjubh* has already been completed synchronously.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hThe ``done_before`` parameter should be set if writes for the ``iocb`` have been initiated prior to the call. The direction of the I/O is determined from the ``iocb`` passed in.h](hThe }(hjhhhNhNubjA)}(h``done_before``h]h done_before}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh+ parameter should be set if writes for the }(hjhhhNhNubjA)}(h``iocb``h]hiocb}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhX have been initiated prior to the call. The direction of the I/O is determined from the }(hjhhhNhNubjA)}(h``iocb``h]hiocb}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh passed in.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hQThe ``dio_flags`` argument can be set to any combination of the following values:h](hThe }(hjchhhNhNubjA)}(h ``dio_flags``h]h dio_flags}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjcubh@ argument can be set to any combination of the following values:}(hjchhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj|)}(hXo* ``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the kiocb is not synchronous. * ``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range or fail with ``-EAGAIN``. This can be used by filesystems with complex unaligned I/O write paths to provide an optimised fast path for unaligned writes. If a pure overwrite can be performed, then serialisation against other I/Os to the same filesystem block(s) is unnecessary as there is no risk of stale data exposure or data loss. If a pure overwrite cannot be performed, then the filesystem can perform the serialisation steps needed to provide exclusive access to the unaligned I/O range so that it can perform allocation and sub-block zeroing safely. Filesystems can use this flag to try to reduce locking contention, but a lot of `detailed checking `_ is required to do it `correctly `_. * ``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever progress has already been made. The caller may deal with the page fault and retry the operation. If the caller decides to retry the operation, it should pass the accumulated return values of all previous calls as the ``done_before`` parameter to the next call. h]j)}(hhh](j)}(h]``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the kiocb is not synchronous. h]j)}(h\``IOMAP_DIO_FORCE_WAIT``: Wait for the I/O to complete even if the kiocb is not synchronous.h](jA)}(h``IOMAP_DIO_FORCE_WAIT``h]hIOMAP_DIO_FORCE_WAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhD: Wait for the I/O to complete even if the kiocb is not synchronous.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range or fail with ``-EAGAIN``. This can be used by filesystems with complex unaligned I/O write paths to provide an optimised fast path for unaligned writes. If a pure overwrite can be performed, then serialisation against other I/Os to the same filesystem block(s) is unnecessary as there is no risk of stale data exposure or data loss. If a pure overwrite cannot be performed, then the filesystem can perform the serialisation steps needed to provide exclusive access to the unaligned I/O range so that it can perform allocation and sub-block zeroing safely. Filesystems can use this flag to try to reduce locking contention, but a lot of `detailed checking `_ is required to do it `correctly `_. h]j)}(hX``IOMAP_DIO_OVERWRITE_ONLY``: Perform a pure overwrite for this range or fail with ``-EAGAIN``. This can be used by filesystems with complex unaligned I/O write paths to provide an optimised fast path for unaligned writes. If a pure overwrite can be performed, then serialisation against other I/Os to the same filesystem block(s) is unnecessary as there is no risk of stale data exposure or data loss. If a pure overwrite cannot be performed, then the filesystem can perform the serialisation steps needed to provide exclusive access to the unaligned I/O range so that it can perform allocation and sub-block zeroing safely. Filesystems can use this flag to try to reduce locking contention, but a lot of `detailed checking `_ is required to do it `correctly `_.h](jA)}(h``IOMAP_DIO_OVERWRITE_ONLY``h]hIOMAP_DIO_OVERWRITE_ONLY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh7: Perform a pure overwrite for this range or fail with }(hjhhhNhNubjA)}(h ``-EAGAIN``h]h-EAGAIN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhXd. This can be used by filesystems with complex unaligned I/O write paths to provide an optimised fast path for unaligned writes. If a pure overwrite can be performed, then serialisation against other I/Os to the same filesystem block(s) is unnecessary as there is no risk of stale data exposure or data loss. If a pure overwrite cannot be performed, then the filesystem can perform the serialisation steps needed to provide exclusive access to the unaligned I/O range so that it can perform allocation and sub-block zeroing safely. Filesystems can use this flag to try to reduce locking contention, but a lot of }(hjhhhNhNubj)}(he`detailed checking `_h]hdetailed checking}(hjhhhNhNubah}(h]h ]h"]h$]h&]namedetailed checkingj[Nhttps://lore.kernel.org/linux-ext4/20230314130759.642710-1-bfoster@redhat.com/uh1jhjubh)}(hQ h]h}(h]detailed-checkingah ]h"]detailed checkingah$]h&]refurijuh1hjjKhjubh is required to do it }(hjhhhNhNubj)}(h]`correctly `_h]h correctly}(hjhhhNhNubah}(h]h ]h"]h$]h&]name correctlyj[Nhttps://lore.kernel.org/linux-ext4/20230810165559.946222-1-bfoster@redhat.com/uh1jhjubh)}(hQ h]h}(h] correctlyah ]h"] correctlyah$]h&]refurijuh1hjjKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXD``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever progress has already been made. The caller may deal with the page fault and retry the operation. If the caller decides to retry the operation, it should pass the accumulated return values of all previous calls as the ``done_before`` parameter to the next call. h]j)}(hXC``IOMAP_DIO_PARTIAL``: If a page fault occurs, return whatever progress has already been made. The caller may deal with the page fault and retry the operation. If the caller decides to retry the operation, it should pass the accumulated return values of all previous calls as the ``done_before`` parameter to the next call.h](jA)}(h``IOMAP_DIO_PARTIAL``h]hIOMAP_DIO_PARTIAL}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj0ubhX: If a page fault occurs, return whatever progress has already been made. The caller may deal with the page fault and retry the operation. If the caller decides to retry the operation, it should pass the accumulated return values of all previous calls as the }(hj0hhhNhNubjA)}(h``done_before``h]h done_before}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj0ubh parameter to the next call.}(hj0hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj,ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhjhhubj)}(hGThese ``struct kiocb`` flags are significant for direct I/O with iomap:h](hThese }(hjphhhNhNubjA)}(h``struct kiocb``h]h struct kiocb}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjpubh1 flags are significant for direct I/O with iomap:}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj|)}(hX* ``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. * ``IOCB_SYNC``: Ensure that the device has persisted data to disk before completing the call. In the case of pure overwrites, the I/O may be issued with FUA enabled. * ``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an interrupt. Only meaningful for asynchronous I/O, and only if the entire I/O can be issued as a single ``struct bio``. h]j)}(hhh](j)}(h,``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``. h]j)}(h+``IOCB_NOWAIT``: Turns on ``IOMAP_NOWAIT``.h](jA)}(h``IOCB_NOWAIT``h]h IOCB_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh : Turns on }(hjhhhNhNubjA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``IOCB_SYNC``: Ensure that the device has persisted data to disk before completing the call. In the case of pure overwrites, the I/O may be issued with FUA enabled. h]j)}(h``IOCB_SYNC``: Ensure that the device has persisted data to disk before completing the call. In the case of pure overwrites, the I/O may be issued with FUA enabled.h](jA)}(h ``IOCB_SYNC``h]h IOCB_SYNC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh: Ensure that the device has persisted data to disk before completing the call. In the case of pure overwrites, the I/O may be issued with FUA enabled.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an interrupt. Only meaningful for asynchronous I/O, and only if the entire I/O can be issued as a single ``struct bio``. h]j)}(h``IOCB_HIPRI``: Poll for I/O completion instead of waiting for an interrupt. Only meaningful for asynchronous I/O, and only if the entire I/O can be issued as a single ``struct bio``.h](jA)}(h``IOCB_HIPRI``h]h IOCB_HIPRI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh: Poll for I/O completion instead of waiting for an interrupt. Only meaningful for asynchronous I/O, and only if the entire I/O can be issued as a single }(hjhhhNhNubjA)}(h``struct bio``h]h struct bio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhjhhubj)}(hFilesystems should call ``iomap_dio_rw`` from ``->read_iter`` and ``->write_iter``, and set ``FMODE_CAN_ODIRECT`` in the ``->open`` function for the file. They should not set ``->direct_IO``, which is deprecated.h](hFilesystems should call }(hj9hhhNhNubjA)}(h``iomap_dio_rw``h]h iomap_dio_rw}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh from }(hj9hhhNhNubjA)}(h``->read_iter``h]h ->read_iter}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh and }(hj9hhhNhNubjA)}(h``->write_iter``h]h ->write_iter}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh , and set }(hj9hhhNhNubjA)}(h``FMODE_CAN_ODIRECT``h]hFMODE_CAN_ODIRECT}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh in the }(hj9hhhNhNubjA)}(h ``->open``h]h->open}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh, function for the file. They should not set }(hj9hhhNhNubjA)}(h``->direct_IO``h]h ->direct_IO}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj9ubh, which is deprecated.}(hj9hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hXIf a filesystem wishes to perform its own work before direct I/O completion, it should call ``__iomap_dio_rw``. If its return value is not an error pointer or a NULL pointer, the filesystem should pass the return value to ``iomap_dio_complete`` after finishing its internal work.h](h\If a filesystem wishes to perform its own work before direct I/O completion, it should call }(hjhhhNhNubjA)}(h``__iomap_dio_rw``h]h__iomap_dio_rw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhp. If its return value is not an error pointer or a NULL pointer, the filesystem should pass the return value to }(hjhhhNhNubjA)}(h``iomap_dio_complete``h]hiomap_dio_complete}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh# after finishing its internal work.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubh)}(hhh](h)}(h Return Valuesh]h Return Values}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhMubj)}(h1``iomap_dio_rw`` can return one of the following:h](jA)}(h``iomap_dio_rw``h]h iomap_dio_rw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh! can return one of the following:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj|)}(hX* A non-negative number of bytes transferred. * ``-ENOTBLK``: Fall back to buffered I/O. iomap itself will return this value if it cannot invalidate the page cache before issuing the I/O to storage. The ``->iomap_begin`` or ``->iomap_end`` functions may also return this value. * ``-EIOCBQUEUED``: The asynchronous direct I/O request has been queued and will be completed separately. * Any of the other negative error codes. h]j)}(hhh](j)}(h,A non-negative number of bytes transferred. h]j)}(h+A non-negative number of bytes transferred.h]h+A non-negative number of bytes transferred.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h``-ENOTBLK``: Fall back to buffered I/O. iomap itself will return this value if it cannot invalidate the page cache before issuing the I/O to storage. The ``->iomap_begin`` or ``->iomap_end`` functions may also return this value. h]j)}(h``-ENOTBLK``: Fall back to buffered I/O. iomap itself will return this value if it cannot invalidate the page cache before issuing the I/O to storage. The ``->iomap_begin`` or ``->iomap_end`` functions may also return this value.h](jA)}(h ``-ENOTBLK``h]h-ENOTBLK}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj5ubh: Fall back to buffered I/O. iomap itself will return this value if it cannot invalidate the page cache before issuing the I/O to storage. The }(hj5hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj5ubh or }(hj5hhhNhNubjA)}(h``->iomap_end``h]h ->iomap_end}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj5ubh& functions may also return this value.}(hj5hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj1ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hh``-EIOCBQUEUED``: The asynchronous direct I/O request has been queued and will be completed separately. h]j)}(hg``-EIOCBQUEUED``: The asynchronous direct I/O request has been queued and will be completed separately.h](jA)}(h``-EIOCBQUEUED``h]h -EIOCBQUEUED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhW: The asynchronous direct I/O request has been queued and will be completed separately.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj{ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h'Any of the other negative error codes. h]j)}(h&Any of the other negative error codes.h]h&Any of the other negative error codes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhjhhubeh}(h]jah ]h"] return valuesah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h Direct Readsh]h Direct Reads}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhM ubj)}(hX A direct I/O read initiates a read I/O from the storage device to the caller's buffer. Dirty parts of the pagecache are flushed to storage before initiating the read io. The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT`` with any combination of the following enhancements:h](hA direct I/O read initiates a read I/O from the storage device to the caller’s buffer. Dirty parts of the pagecache are flushed to storage before initiating the read io. The }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh value for }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be }(hjhhhNhNubjA)}(h``IOMAP_DIRECT``h]h IOMAP_DIRECT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh4 with any combination of the following enhancements:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM hjhhubj|)}(h+* ``IOMAP_NOWAIT``, as defined previously. h]j)}(hhh]j)}(h)``IOMAP_NOWAIT``, as defined previously. h]j)}(h(``IOMAP_NOWAIT``, as defined previously.h](jA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj,ubh, as defined previously.}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj(ubah}(h]h ]h"]h$]h&]uh1jhj%ubah}(h]h ]h"]h$]h&]j j uh1j hhhMhj!ubah}(h]h ]h"]h$]h&]uh1j{hhhMhjhhubj)}(hNCallers commonly hold ``i_rwsem`` in shared mode before calling this function.h](hCallers commonly hold }(hjZhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjZubh- in shared mode before calling this function.}(hjZhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]jah ]h"] direct readsah$]h&]uh1hhjhhhhhM ubh)}(hhh](h)}(h Direct Writesh]h Direct Writes}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhMubj)}(hXrA direct I/O write initiates a write I/O to the storage device from the caller's buffer. Dirty parts of the pagecache are flushed to storage before initiating the write io. The pagecache is invalidated both before and after the write io. The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DIRECT | IOMAP_WRITE`` with any combination of the following enhancements:h](hA direct I/O write initiates a write I/O to the storage device from the caller’s buffer. Dirty parts of the pagecache are flushed to storage before initiating the write io. The pagecache is invalidated both before and after the write io. The }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh value for }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be }(hjhhhNhNubjA)}(h``IOMAP_DIRECT | IOMAP_WRITE``h]hIOMAP_DIRECT | IOMAP_WRITE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh4 with any combination of the following enhancements:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj|)}(hX|* ``IOMAP_NOWAIT``, as defined previously. * ``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial blocks is not allowed. The entire file range must map to a single written or unwritten extent. The file I/O range must be aligned to the filesystem block size if the mapping is unwritten and the filesystem cannot handle zeroing the unaligned regions without exposing stale contents. * ``IOMAP_ATOMIC``: This write is being issued with torn-write protection. Torn-write protection may be provided based on HW-offload or by a software mechanism provided by the filesystem. For HW-offload based support, only a single bio can be created for the write, and the write must not be split into multiple I/O requests, i.e. flag REQ_ATOMIC must be set. The file range to write must be aligned to satisfy the requirements of both the filesystem and the underlying block device's atomic commit capabilities. If filesystem metadata updates are required (e.g. unwritten extent conversion or copy-on-write), all updates for the entire file range must be committed atomically as well. Untorn-writes may be longer than a single file block. In all cases, the mapping start disk block must have at least the same alignment as the write offset. The filesystems must set IOMAP_F_ATOMIC_BIO to inform iomap core of an untorn-write based on HW-offload. For untorn-writes based on a software mechanism provided by the filesystem, all the disk block alignment and single bio restrictions which apply for HW-offload based untorn-writes do not apply. The mechanism would typically be used as a fallback for when HW-offload based untorn-writes may not be issued, e.g. the range of the write covers multiple extents, meaning that it is not possible to issue a single bio. All filesystem metadata updates for the entire file range must be committed atomically as well. h]j)}(hhh](j)}(h)``IOMAP_NOWAIT``, as defined previously. h]j)}(h(``IOMAP_NOWAIT``, as defined previously.h](jA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh, as defined previously.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM$hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX[``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial blocks is not allowed. The entire file range must map to a single written or unwritten extent. The file I/O range must be aligned to the filesystem block size if the mapping is unwritten and the filesystem cannot handle zeroing the unaligned regions without exposing stale contents. h]j)}(hXZ``IOMAP_OVERWRITE_ONLY``: Allocating blocks and zeroing partial blocks is not allowed. The entire file range must map to a single written or unwritten extent. The file I/O range must be aligned to the filesystem block size if the mapping is unwritten and the filesystem cannot handle zeroing the unaligned regions without exposing stale contents.h](jA)}(h``IOMAP_OVERWRITE_ONLY``h]hIOMAP_OVERWRITE_ONLY}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhXB: Allocating blocks and zeroing partial blocks is not allowed. The entire file range must map to a single written or unwritten extent. The file I/O range must be aligned to the filesystem block size if the mapping is unwritten and the filesystem cannot handle zeroing the unaligned regions without exposing stale contents.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM&hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``IOMAP_ATOMIC``: This write is being issued with torn-write protection. Torn-write protection may be provided based on HW-offload or by a software mechanism provided by the filesystem. For HW-offload based support, only a single bio can be created for the write, and the write must not be split into multiple I/O requests, i.e. flag REQ_ATOMIC must be set. The file range to write must be aligned to satisfy the requirements of both the filesystem and the underlying block device's atomic commit capabilities. If filesystem metadata updates are required (e.g. unwritten extent conversion or copy-on-write), all updates for the entire file range must be committed atomically as well. Untorn-writes may be longer than a single file block. In all cases, the mapping start disk block must have at least the same alignment as the write offset. The filesystems must set IOMAP_F_ATOMIC_BIO to inform iomap core of an untorn-write based on HW-offload. For untorn-writes based on a software mechanism provided by the filesystem, all the disk block alignment and single bio restrictions which apply for HW-offload based untorn-writes do not apply. The mechanism would typically be used as a fallback for when HW-offload based untorn-writes may not be issued, e.g. the range of the write covers multiple extents, meaning that it is not possible to issue a single bio. All filesystem metadata updates for the entire file range must be committed atomically as well. h](j)}(h``IOMAP_ATOMIC``: This write is being issued with torn-write protection. Torn-write protection may be provided based on HW-offload or by a software mechanism provided by the filesystem.h](jA)}(h``IOMAP_ATOMIC``h]h IOMAP_ATOMIC}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj-ubh: This write is being issued with torn-write protection. Torn-write protection may be provided based on HW-offload or by a software mechanism provided by the filesystem.}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM.hj)ubj)}(hXFor HW-offload based support, only a single bio can be created for the write, and the write must not be split into multiple I/O requests, i.e. flag REQ_ATOMIC must be set. The file range to write must be aligned to satisfy the requirements of both the filesystem and the underlying block device's atomic commit capabilities. If filesystem metadata updates are required (e.g. unwritten extent conversion or copy-on-write), all updates for the entire file range must be committed atomically as well. Untorn-writes may be longer than a single file block. In all cases, the mapping start disk block must have at least the same alignment as the write offset. The filesystems must set IOMAP_F_ATOMIC_BIO to inform iomap core of an untorn-write based on HW-offload.h]hXFor HW-offload based support, only a single bio can be created for the write, and the write must not be split into multiple I/O requests, i.e. flag REQ_ATOMIC must be set. The file range to write must be aligned to satisfy the requirements of both the filesystem and the underlying block device’s atomic commit capabilities. If filesystem metadata updates are required (e.g. unwritten extent conversion or copy-on-write), all updates for the entire file range must be committed atomically as well. Untorn-writes may be longer than a single file block. In all cases, the mapping start disk block must have at least the same alignment as the write offset. The filesystems must set IOMAP_F_ATOMIC_BIO to inform iomap core of an untorn-write based on HW-offload.}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM3hj)ubj)}(hXFor untorn-writes based on a software mechanism provided by the filesystem, all the disk block alignment and single bio restrictions which apply for HW-offload based untorn-writes do not apply. The mechanism would typically be used as a fallback for when HW-offload based untorn-writes may not be issued, e.g. the range of the write covers multiple extents, meaning that it is not possible to issue a single bio. All filesystem metadata updates for the entire file range must be committed atomically as well.h]hXFor untorn-writes based on a software mechanism provided by the filesystem, all the disk block alignment and single bio restrictions which apply for HW-offload based untorn-writes do not apply. The mechanism would typically be used as a fallback for when HW-offload based untorn-writes may not be issued, e.g. the range of the write covers multiple extents, meaning that it is not possible to issue a single bio. All filesystem metadata updates for the entire file range must be committed atomically as well.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMBhj)ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhM$hjubah}(h]h ]h"]h$]h&]uh1j{hhhM$hjhhubj)}(h[Callers commonly hold ``i_rwsem`` in shared or exclusive mode before calling this function.h](hCallers commonly hold }(hjwhhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjwubh: in shared or exclusive mode before calling this function.}(hjwhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMLhjhhubeh}(h]jah ]h"] direct writesah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hjh]jA)}(hjh]hstruct iomap_dio_ops:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubah}(h]h ]h"]h$]h&]j%juh1hhjhhhhhMPubj)}(hX struct iomap_dio_ops { void (*submit_io)(const struct iomap_iter *iter, struct bio *bio, loff_t file_offset); int (*end_io)(struct kiocb *iocb, ssize_t size, int error, unsigned flags); struct bio_set *bio_set; };h]hX struct iomap_dio_ops { void (*submit_io)(const struct iomap_iter *iter, struct bio *bio, loff_t file_offset); int (*end_io)(struct kiocb *iocb, ssize_t size, int error, unsigned flags); struct bio_set *bio_set; };}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMQhjhhubj)}(h,The fields of this structure are as follows:h]h,The fields of this structure are as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM[hjhhubj|)}(hX- ``submit_io``: iomap calls this function when it has constructed a ``struct bio`` object for the I/O requested, and wishes to submit it to the block device. If no function is provided, ``submit_bio`` will be called directly. Filesystems that would like to perform additional work before (e.g. data replication for btrfs) should implement this function. - ``end_io``: This is called after the ``struct bio`` completes. This function should perform post-write conversions of unwritten extent mappings, handle write failures, etc. The ``flags`` argument may be set to a combination of the following: * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend should mark the extent as written. * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a copy on write operation, so the ioend should switch mappings. - ``bio_set``: This allows the filesystem to provide a custom bio_set for allocating direct I/O bios. This enables filesystems to `stash additional per-bio information `_ for private use. If this field is NULL, generic ``struct bio`` objects will be used. h]j)}(hhh](j)}(hXa``submit_io``: iomap calls this function when it has constructed a ``struct bio`` object for the I/O requested, and wishes to submit it to the block device. If no function is provided, ``submit_bio`` will be called directly. Filesystems that would like to perform additional work before (e.g. data replication for btrfs) should implement this function. h]j)}(hX```submit_io``: iomap calls this function when it has constructed a ``struct bio`` object for the I/O requested, and wishes to submit it to the block device. If no function is provided, ``submit_bio`` will be called directly. Filesystems that would like to perform additional work before (e.g. data replication for btrfs) should implement this function.h](jA)}(h ``submit_io``h]h submit_io}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh6: iomap calls this function when it has constructed a }(hjhhhNhNubjA)}(h``struct bio``h]h struct bio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhh object for the I/O requested, and wishes to submit it to the block device. If no function is provided, }(hjhhhNhNubjA)}(h``submit_bio``h]h submit_bio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be called directly. Filesystems that would like to perform additional work before (e.g. data replication for btrfs) should implement this function.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM]hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``end_io``: This is called after the ``struct bio`` completes. This function should perform post-write conversions of unwritten extent mappings, handle write failures, etc. The ``flags`` argument may be set to a combination of the following: * ``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend should mark the extent as written. * ``IOMAP_DIO_COW``: Writing to the space in the mapping required a copy on write operation, so the ioend should switch mappings. h](j)}(h``end_io``: This is called after the ``struct bio`` completes. This function should perform post-write conversions of unwritten extent mappings, handle write failures, etc. The ``flags`` argument may be set to a combination of the following:h](jA)}(h ``end_io``h]hend_io}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj)ubh: This is called after the }(hj)hhhNhNubjA)}(h``struct bio``h]h struct bio}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj)ubh~ completes. This function should perform post-write conversions of unwritten extent mappings, handle write failures, etc. The }(hj)hhhNhNubjA)}(h ``flags``h]hflags}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj)ubh7 argument may be set to a combination of the following:}(hj)hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMdhj%ubj)}(hhh](j)}(hd``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend should mark the extent as written. h]j)}(hc``IOMAP_DIO_UNWRITTEN``: The mapping was unwritten, so the ioend should mark the extent as written.h](jA)}(h``IOMAP_DIO_UNWRITTEN``h]hIOMAP_DIO_UNWRITTEN}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjpubhL: The mapping was unwritten, so the ioend should mark the extent as written.}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMihjlubah}(h]h ]h"]h$]h&]uh1jhjiubj)}(h``IOMAP_DIO_COW``: Writing to the space in the mapping required a copy on write operation, so the ioend should switch mappings. h]j)}(h``IOMAP_DIO_COW``: Writing to the space in the mapping required a copy on write operation, so the ioend should switch mappings.h](jA)}(h``IOMAP_DIO_COW``h]h IOMAP_DIO_COW}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhn: Writing to the space in the mapping required a copy on write operation, so the ioend should switch mappings.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMlhjubah}(h]h ]h"]h$]h&]uh1jhjiubeh}(h]h ]h"]h$]h&]j j uh1j hhhMihj%ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hX?``bio_set``: This allows the filesystem to provide a custom bio_set for allocating direct I/O bios. This enables filesystems to `stash additional per-bio information `_ for private use. If this field is NULL, generic ``struct bio`` objects will be used. vh]j)}(hX>``bio_set``: This allows the filesystem to provide a custom bio_set for allocating direct I/O bios. This enables filesystems to `stash additional per-bio information `_ for private use. If this field is NULL, generic ``struct bio`` objects will be used.h](jA)}(h ``bio_set``h]hbio_set}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubhu: This allows the filesystem to provide a custom bio_set for allocating direct I/O bios. This enables filesystems to }(hjhhhNhNubj)}(hi`stash additional per-bio information `_h]h$stash additional per-bio information}(hjhhhNhNubah}(h]h ]h"]h$]h&]name$stash additional per-bio informationj[?https://lore.kernel.org/all/20220505201115.937837-3-hch@lst.de/uh1jhjubh)}(hB h]h}(h]$stash-additional-per-bio-informationah ]h"]$stash additional per-bio informationah$]h&]refurijuh1hjjKhjubh1 for private use. If this field is NULL, generic }(hjhhhNhNubjA)}(h``struct bio``h]h struct bio}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh objects will be used.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMohjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j jm uh1j hhhM]hjubah}(h]h ]h"]h$]h&]uh1j{hhhM]hjhhubj)}(hFilesystems that want to perform extra work after an I/O completion should set a custom ``->bi_end_io`` function via ``->submit_io``. Afterwards, the custom endio function must call ``iomap_dio_bio_end_io`` to finish the direct I/O.h](hXFilesystems that want to perform extra work after an I/O completion should set a custom }(hj*hhhNhNubjA)}(h``->bi_end_io``h]h ->bi_end_io}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj*ubh function via }(hj*hhhNhNubjA)}(h``->submit_io``h]h ->submit_io}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj*ubh2. Afterwards, the custom endio function must call }(hj*hhhNhNubjA)}(h``iomap_dio_bio_end_io``h]hiomap_dio_bio_end_io}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj*ubh to finish the direct I/O.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMvhjhhubeh}(h]jah ]h"]struct iomap_dio_ops:ah$]h&]uh1hhjhhhhhMPubeh}(h]jpah ]h"] direct i/oah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hDAX I/Oh]hDAX I/O}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%j'uh1hhj|hhhhhM|ubj)}(hSome storage devices can be directly mapped as memory. These devices support a new access mode known as "fsdax" that allows loads and stores through the CPU and memory controller.h]hSome storage devices can be directly mapped as memory. These devices support a new access mode known as “fsdax” that allows loads and stores through the CPU and memory controller.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM~hj|hhubh)}(hhh](h)}(h fsdax Readsh]h fsdax Reads}(hjhhhNhNubah}(h]h ]h"]h$]h&]j%jFuh1hhjhhhhhMubj)}(hA fsdax read performs a memcpy from storage device to the caller's buffer. The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX`` with any combination of the following enhancements:h](hQA fsdax read performs a memcpy from storage device to the caller’s buffer. The }(hjhhhNhNubjA)}(h ``flags``h]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh value for }(hjhhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh will be }(hjhhhNhNubjA)}(h ``IOMAP_DAX``h]h IOMAP_DAX}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh4 with any combination of the following enhancements:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj|)}(h+* ``IOMAP_NOWAIT``, as defined previously. h]j)}(hhh]j)}(h)``IOMAP_NOWAIT``, as defined previously. h]j)}(h(``IOMAP_NOWAIT``, as defined previously.h](jA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh, as defined previously.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhjhhubj)}(hNCallers commonly hold ``i_rwsem`` in shared mode before calling this function.h](hCallers commonly hold }(hj)hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj)ubh- in shared mode before calling this function.}(hj)hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubeh}(h]jLah ]h"] fsdax readsah$]h&]uh1hhj|hhhhhMubh)}(hhh](h)}(h fsdax Writesh]h fsdax Writes}(hjShhhNhNubah}(h]h ]h"]h$]h&]j%jhuh1hhjPhhhhhMubj)}(hA fsdax write initiates a memcpy to the storage device from the caller's buffer. The ``flags`` value for ``->iomap_begin`` will be ``IOMAP_DAX | IOMAP_WRITE`` with any combination of the following enhancements:h](hWA fsdax write initiates a memcpy to the storage device from the caller’s buffer. The }(hjahhhNhNubjA)}(h ``flags``h]hflags}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjaubh value for }(hjahhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjaubh will be }(hjahhhNhNubjA)}(h``IOMAP_DAX | IOMAP_WRITE``h]hIOMAP_DAX | IOMAP_WRITE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjaubh4 with any combination of the following enhancements:}(hjahhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjPhhubj|)}(hX* ``IOMAP_NOWAIT``, as defined previously. * ``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be performed from this mapping. This requires the filesystem extent mapping to already exist as an ``IOMAP_MAPPED`` type and span the entire range of the write I/O request. If the filesystem cannot map this request in a way that allows the iomap infrastructure to perform a pure overwrite, it must fail the mapping operation with ``-EAGAIN``. h]j)}(hhh](j)}(h)``IOMAP_NOWAIT``, as defined previously. h]j)}(h(``IOMAP_NOWAIT``, as defined previously.h](jA)}(h``IOMAP_NOWAIT``h]h IOMAP_NOWAIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh, as defined previously.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be performed from this mapping. This requires the filesystem extent mapping to already exist as an ``IOMAP_MAPPED`` type and span the entire range of the write I/O request. If the filesystem cannot map this request in a way that allows the iomap infrastructure to perform a pure overwrite, it must fail the mapping operation with ``-EAGAIN``. h]j)}(hX``IOMAP_OVERWRITE_ONLY``: The caller requires a pure overwrite to be performed from this mapping. This requires the filesystem extent mapping to already exist as an ``IOMAP_MAPPED`` type and span the entire range of the write I/O request. If the filesystem cannot map this request in a way that allows the iomap infrastructure to perform a pure overwrite, it must fail the mapping operation with ``-EAGAIN``.h](jA)}(h``IOMAP_OVERWRITE_ONLY``h]hIOMAP_OVERWRITE_ONLY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh: The caller requires a pure overwrite to be performed from this mapping. This requires the filesystem extent mapping to already exist as an }(hjhhhNhNubjA)}(h``IOMAP_MAPPED``h]h IOMAP_MAPPED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh type and span the entire range of the write I/O request. If the filesystem cannot map this request in a way that allows the iomap infrastructure to perform a pure overwrite, it must fail the mapping operation with }(hjhhhNhNubjA)}(h ``-EAGAIN``h]h-EAGAIN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjubah}(h]h ]h"]h$]h&]uh1j{hhhMhjPhhubj)}(hQCallers commonly hold ``i_rwsem`` in exclusive mode before calling this function.h](hCallers commonly hold }(hj( hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj( ubh0 in exclusive mode before calling this function.}(hj( hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjPhhubh)}(hhh](h)}(hfsdax mmap Faultsh]hfsdax mmap Faults}(hjK hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjH hhhhhMubj)}(hX9The ``dax_iomap_fault`` function handles read and write faults to fsdax storage. For a read fault, ``IOMAP_DAX | IOMAP_FAULT`` will be passed as the ``flags`` argument to ``->iomap_begin``. For a write fault, ``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE`` will be passed as the ``flags`` argument to ``->iomap_begin``.h](hThe }(hjY hhhNhNubjA)}(h``dax_iomap_fault``h]hdax_iomap_fault}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubhL function handles read and write faults to fsdax storage. For a read fault, }(hjY hhhNhNubjA)}(h``IOMAP_DAX | IOMAP_FAULT``h]hIOMAP_DAX | IOMAP_FAULT}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh will be passed as the }(hjY hhhNhNubjA)}(h ``flags``h]hflags}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh argument to }(hjY hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh. For a write fault, }(hjY hhhNhNubjA)}(h)``IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE``h]h%IOMAP_DAX | IOMAP_FAULT | IOMAP_WRITE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh will be passed as the }(hjY hhhNhNubjA)}(h ``flags``h]hflags}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh argument to }hjY sbjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjY ubh.}(hjY hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjH hhubj)}(h[Callers commonly hold the same locks as they do to call their iomap pagecache counterparts.h]h[Callers commonly hold the same locks as they do to call their iomap pagecache counterparts.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjH hhubeh}(h]jah ]h"]fsdax mmap faultsah$]h&]uh1hhjPhhhhhMubeh}(h]jnah ]h"] fsdax writesah$]h&]uh1hhj|hhhhhMubh)}(hhh](h)}(h*fsdax Truncation, fallocate, and Unsharingh]h*fsdax Truncation, fallocate, and Unsharing}(hj!hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj!hhhhhMubj)}(hFor fsdax files, the following functions are provided to replace their iomap pagecache I/O counterparts. The ``flags`` argument to ``->iomap_begin`` are the same as the pagecache counterparts, with ``IOMAP_DAX`` added.h](hmFor fsdax files, the following functions are provided to replace their iomap pagecache I/O counterparts. The }(hj!hhhNhNubjA)}(h ``flags``h]hflags}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubh argument to }(hj!hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj,!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubh2 are the same as the pagecache counterparts, with }(hj!hhhNhNubjA)}(h ``IOMAP_DAX``h]h IOMAP_DAX}(hj>!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubh added.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj!hhubj|)}(hD* ``dax_file_unshare`` * ``dax_zero_range`` * ``dax_truncate_page`` h]j)}(hhh](j)}(h``dax_file_unshare``h]j)}(hj_!h]jA)}(hj_!h]hdax_file_unshare}(hjd!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hja!ubah}(h]h ]h"]h$]h&]uh1jhhhMhj]!ubah}(h]h ]h"]h$]h&]uh1jhjZ!ubj)}(h``dax_zero_range``h]j)}(hj!h]jA)}(hj!h]hdax_zero_range}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubah}(h]h ]h"]h$]h&]uh1jhhhMhj}!ubah}(h]h ]h"]h$]h&]uh1jhjZ!ubj)}(h``dax_truncate_page`` h]j)}(h``dax_truncate_page``h]jA)}(hj!h]hdax_truncate_page}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubah}(h]h ]h"]h$]h&]uh1jhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jhjZ!ubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhjV!ubah}(h]h ]h"]h$]h&]uh1j{hhhMhj!hhubj)}(h[Callers commonly hold the same locks as they do to call their iomap pagecache counterparts.h]h[Callers commonly hold the same locks as they do to call their iomap pagecache counterparts.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj!hhubeh}(h]jah ]h"]*fsdax truncation, fallocate, and unsharingah$]h&]uh1hhj|hhhhhMubh)}(hhh](h)}(hfsdax Deduplicationh]hfsdax Deduplication}(hj!hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj!hhhhhMubj)}(hFilesystems implementing the ``FIDEDUPERANGE`` ioctl must call the ``dax_remap_file_range_prep`` function with their own iomap read ops.h](hFilesystems implementing the }(hj!hhhNhNubjA)}(h``FIDEDUPERANGE``h]h FIDEDUPERANGE}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubh ioctl must call the }(hj!hhhNhNubjA)}(h``dax_remap_file_range_prep``h]hdax_remap_file_range_prep}(hj "hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj!ubh( function with their own iomap read ops.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj!hhubeh}(h]jah ]h"]fsdax deduplicationah$]h&]uh1hhj|hhhhhMubeh}(h]j-ah ]h"]dax i/oah$]h&]uh1hhhhhhhhM|ubh)}(hhh](h)}(h Seeking Filesh]h Seeking Files}(hj3"hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj0"hhhhhMubj)}(hNiomap implements the two iterating whence modes of the ``llseek`` system call.h](h7iomap implements the two iterating whence modes of the }(hjA"hhhNhNubjA)}(h ``llseek``h]hllseek}(hjI"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjA"ubh system call.}(hjA"hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj0"hhubh)}(hhh](h)}(h SEEK_DATAh]h SEEK_DATA}(hjd"hhhNhNubah}(h]h ]h"]h$]h&]j%j$uh1hhja"hhhhhMubj)}(hThe ``iomap_seek_data`` function implements the SEEK_DATA "whence" value for llseek. ``IOMAP_REPORT`` will be passed as the ``flags`` argument to ``->iomap_begin``.h](hThe }(hjr"hhhNhNubjA)}(h``iomap_seek_data``h]hiomap_seek_data}(hjz"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjr"ubhB function implements the SEEK_DATA “whence” value for llseek. }(hjr"hhhNhNubjA)}(h``IOMAP_REPORT``h]h IOMAP_REPORT}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjr"ubh will be passed as the }(hjr"hhhNhNubjA)}(h ``flags``h]hflags}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjr"ubh argument to }(hjr"hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjr"ubh.}(hjr"hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhja"hhubj)}(hFor unwritten mappings, the pagecache will be searched. Regions of the pagecache with a folio mapped and uptodate fsblocks within those folios will be reported as data areas.h]hFor unwritten mappings, the pagecache will be searched. Regions of the pagecache with a folio mapped and uptodate fsblocks within those folios will be reported as data areas.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhja"hhubj)}(hNCallers commonly hold ``i_rwsem`` in shared mode before calling this function.h](hCallers commonly hold }(hj"hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj"ubh- in shared mode before calling this function.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhja"hhubeh}(h]j*ah ]h"] seek_dataah$]h&]uh1hhj0"hhhhhMubh)}(hhh](h)}(h SEEK_HOLEh]h SEEK_HOLE}(hj#hhhNhNubah}(h]h ]h"]h$]h&]j%jFuh1hhj"hhhhhMubj)}(hThe ``iomap_seek_hole`` function implements the SEEK_HOLE "whence" value for llseek. ``IOMAP_REPORT`` will be passed as the ``flags`` argument to ``->iomap_begin``.h](hThe }(hj#hhhNhNubjA)}(h``iomap_seek_hole``h]hiomap_seek_hole}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubhB function implements the SEEK_HOLE “whence” value for llseek. }(hj#hhhNhNubjA)}(h``IOMAP_REPORT``h]h IOMAP_REPORT}(hj(#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh will be passed as the }(hj#hhhNhNubjA)}(h ``flags``h]hflags}(hj:#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh argument to }(hj#hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hjL#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh.}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj"hhubj)}(hFor unwritten mappings, the pagecache will be searched. Regions of the pagecache with no folio mapped, or a !uptodate fsblock within a folio will be reported as sparse hole areas.h]hFor unwritten mappings, the pagecache will be searched. Regions of the pagecache with no folio mapped, or a !uptodate fsblock within a folio will be reported as sparse hole areas.}(hjd#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhj"hhubj)}(hNCallers commonly hold ``i_rwsem`` in shared mode before calling this function.h](hCallers commonly hold }(hjr#hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hjz#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjr#ubh- in shared mode before calling this function.}(hjr#hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj"hhubeh}(h]jLah ]h"] seek_holeah$]h&]uh1hhj0"hhhhhMubeh}(h]j ah ]h"] seeking filesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hSwap File Activationh]hSwap File Activation}(hj#hhhNhNubah}(h]h ]h"]h$]h&]j%jtuh1hhj#hhhhhMubj)}(hXThe ``iomap_swapfile_activate`` function finds all the base-page aligned regions in a file and sets them up as swap space. The file will be ``fsync()``'d before activation. ``IOMAP_REPORT`` will be passed as the ``flags`` argument to ``->iomap_begin``. All mappings must be mapped or unwritten; cannot be dirty or shared, and cannot span multiple block devices. Callers must hold ``i_rwsem`` in exclusive mode; this is already provided by ``swapon``.h](hThe }(hj#hhhNhNubjA)}(h``iomap_swapfile_activate``h]hiomap_swapfile_activate}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubhm function finds all the base-page aligned regions in a file and sets them up as swap space. The file will be }(hj#hhhNhNubjA)}(h ``fsync()``h]hfsync()}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh’d before activation. }(hj#hhhNhNubjA)}(h``IOMAP_REPORT``h]h IOMAP_REPORT}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh will be passed as the }(hj#hhhNhNubjA)}(h ``flags``h]hflags}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh argument to }(hj#hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh. All mappings must be mapped or unwritten; cannot be dirty or shared, and cannot span multiple block devices. Callers must hold }(hj#hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh0 in exclusive mode; this is already provided by }(hj#hhhNhNubjA)}(h ``swapon``h]hswapon}(hj%$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj#ubh.}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhj#hhubeh}(h]jzah ]h"]swap file activationah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hFile Space Mapping Reportingh]hFile Space Mapping Reporting}(hjG$hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhjD$hhhhhMubj)}(hiomap_begin``. Callers commonly hold ``i_rwsem`` in shared mode before calling this function.h](hThe }(hjt$hhhNhNubjA)}(h``iomap_fiemap``h]h iomap_fiemap}(hj|$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubhS function exports file extent mappings to userspace in the format specified by the }(hjt$hhhNhNubjA)}(h``FS_IOC_FIEMAP``h]h FS_IOC_FIEMAP}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubh ioctl. }(hjt$hhhNhNubjA)}(h``IOMAP_REPORT``h]h IOMAP_REPORT}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubh will be passed as the }(hjt$hhhNhNubjA)}(h ``flags``h]hflags}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubh argument to }(hjt$hhhNhNubjA)}(h``->iomap_begin``h]h ->iomap_begin}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubh. Callers commonly hold }(hjt$hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hjt$ubh- in shared mode before calling this function.}(hjt$hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhMhjc$hhubeh}(h]jah ]h"] fs_ioc_fiemapah$]h&]uh1hhjD$hhhhhMubh)}(hhh](h)}(hFIBMAP (deprecated)h]hFIBMAP (deprecated)}(hj$hhhNhNubah}(h]h ]h"]h$]h&]j%juh1hhj$hhhhhMubj)}(hX``iomap_bmap`` implements FIBMAP. The calling conventions are the same as for FIEMAP. This function is only provided to maintain compatibility for filesystems that implemented FIBMAP prior to conversion. This ioctl is deprecated; do **not** add a FIBMAP implementation to filesystems that do not have it. Callers should probably hold ``i_rwsem`` in shared mode before calling this function, but this is unclear.h](jA)}(h``iomap_bmap``h]h iomap_bmap}(hj %hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj%ubh implements FIBMAP. The calling conventions are the same as for FIEMAP. This function is only provided to maintain compatibility for filesystems that implemented FIBMAP prior to conversion. This ioctl is deprecated; do }(hj%hhhNhNubhstrong)}(h**not**h]hnot}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1j%hj%ubh^ add a FIBMAP implementation to filesystems that do not have it. Callers should probably hold }(hj%hhhNhNubjA)}(h ``i_rwsem``h]hi_rwsem}(hj0%hhhNhNubah}(h]h ]h"]h$]h&]uh1j@hj%ubhB in shared mode before calling this function, but this is unclear.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1jhhhM hj$hhubeh}(h]jah ]h"]fibmap (deprecated)ah$]h&]uh1hhjD$hhhhhMubeh}(h]jah ]h"]file space mapping reportingah$]h&]uh1hhhhhhhhMubeh}(h]supported-file-operationsah ]h"]supported file operationsah$]h&]uh1hhhhhhhhK ubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj%error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(hhj[%jX%jjjj-jjXj jjfjcjjjQ jN j jj jj j jjjjjj5jjWj jj+j(jIjyjjjjjjj%jj?j<jjjzj6jjjyjpjjjjjjjjj~jjjjrjjjj-"j-jMjLj jnj jj!jj&"jj#j j"j*j#jLjA$jzjS%jj$jjL%ju nametypes}(hӈj[%jjjj jfjjQ j j j jjjjj j+jIjjjj%j?jjzjjyjjjjj~jjrjj-"jMj j j!j&"j#j"j#jA$jS%j$jL%uh}(hhjX%hjhj-jjXjTjjjcj]jjjN jH jj jj j j jj jjj5jVjWjjjj(j"jyjjjLjjjjjjj<j6jjj6j(jjjpjjjjjjjjjjjjjjjjjj-j|jLjjnjPjjH jj!jj!j j0"j*ja"jLj"jzj#jjD$jjc$jj$j'jjRj=j~jkjjjjjjjjj/j&jQjHjsjjjjjjjjjjj0j'jjjajjjjjjjjj'jjFj=jhj_jj~jjjjjjj$jjFj=jtjkjjjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j%K!sRparse_messages]transform_messages]hsystem_message)}(hhh]j)}(hhh]h6Hyperlink target "iomap_operations" is not referenced.}hj%sbah}(h]h ]h"]h$]h&]uh1jhj%ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehnjlineKuh1j%uba transformerN include_log] decorationNhhub.