We have introduced the mmap_complete() and mmap_abort() callbacks, which work in conjunction with mmap_prepare(), so describe what they used for. We update both the VFS documentation and the porting guide. Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> --- Documentation/filesystems/porting.rst | 9 +++++++ Documentation/filesystems/vfs.rst | 35 +++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 85f590254f07..abc1b8c95d24 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -1285,3 +1285,12 @@ rather than a VMA, as the VMA at this stage is not yet valid. The vm_area_desc provides the minimum required information for a filesystem to initialise state upon memory mapping of a file-backed region, and output parameters for the file system to set this state. + +In nearly all cases, this is all that is required for a filesystem. However, +should there be a need to operate on the newly inserted VMA, the mmap_complete() +can be specified to do so. + +Additionally, if mmap_prepare() and mmap_complete() are specified, mmap_abort() +may also be provided which is invoked if the mapping fails between mmap_prepare +and mmap_complete(). It is only valid to specify mmap_abort() if both other +hooks are provided. diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 486a91633474..172d36a13e13 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -1114,6 +1114,10 @@ This describes how the VFS can manipulate an open file. As of kernel int (*uring_cmd_iopoll)(struct io_uring_cmd *, struct io_comp_batch *, unsigned int poll_flags); int (*mmap_prepare)(struct vm_area_desc *); + int (*mmap_complete)(struct file *, struct vm_area_struct *, + const void *context); + void (*mmap_abort)(const struct file *, const void *vm_private_data, + const void *context); }; Again, all methods are called without any locks being held, unless @@ -1236,6 +1240,37 @@ otherwise noted. file-backed memory mapping, most notably establishing relevant private state and VMA callbacks. +``mmap_complete`` + If mmap_prepare is provided, will be invoked after the mapping is fully + established, with the mmap and VMA write locks held. + + It is useful for prepopulating VMAs before they may be accessed by + users. + + The hook MUST NOT release either the VMA or mmap write locks. This is + asserted by the mmap logic. + + If an error is returned by the hook, the VMA is unmapped and the + mmap() operation fails with that error. + + It is not valid to specify this hook if mmap_prepare is not also + specified, doing so will result in an error upon mapping. + +``mmap_abort`` + If mmap_prepare() and mmap_complete() are provided, then mmap_abort + may also be provided, which will be invoked if the mapping operation + fails between the two calls. + + This is important, because mmap_prepare may succeed, but some other part + of the mapping operation may fail before mmap_complete can be called. + + This allows a caller to acquire locks in mmap_prepare with certainty + that the locks will be released by either mmap_abort or mmap_complete no + matter what happens. + + It is not valid to specify this unless mmap_prepare and mmap_complete + are both specified, doing so will result in an error upon mapping. + Note that the file operations are implemented by the specific filesystem in which the inode resides. When opening a device node (character or block special) most filesystems will call special -- 2.51.0
