From nobody Tue Apr 7 16:13:24 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D8D8E37C0E7; Thu, 12 Mar 2026 20:27:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773347273; cv=none; b=sYWvBfMlxHbhvu9+L3r8bkQeqtfvAHA6200fktWlBpaPH9e4WeXBgmBbpG2/fOF4Wenus7E9QQuzK5YJSbmPF8UPdswf+RX8YRTTPmSvOYIc/k4A9SPZNogoc57bNeltKV/v6+JDSz0ukhB4c2XYj1/7epPvPnrdXkcHVzNahqg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773347273; c=relaxed/simple; bh=Vhnl6dyI6DciWh1R2wyZ1qlkDiUoqFRvSKLSiU1V8ls=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QWF4uGOlCClOW3Fu9tepBHjkZQ2lilYq6MtMWEBo0qJyCm/71ivrKliLHfqvnFWqDj09gQmYL7SCz8DuymYKK4XjrtQ44GSofCDtQNuPOd7Ksi+AURIwlcFbh8L3+bMdeT7q+waI+anO/yb4PsB2+SU8i1a0nx8eB0+6PFAMeh0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZK1Wltim; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZK1Wltim" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 22B7DC19425; Thu, 12 Mar 2026 20:27:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1773347273; bh=Vhnl6dyI6DciWh1R2wyZ1qlkDiUoqFRvSKLSiU1V8ls=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZK1WltimUAZc0jYB/huW7CthVu5Pu5VFPFyTyvlS4T7HMAkTnJpb74i68i41ylW7Q 7fyRQuCh/gLCub/cymRHsmhpsfS8DFpbAqZr1SS92G3+vQpwXbZfJnBMCChrImWhS6 V+8bnKKwhWmdij/nWi43ezCIkdrjaJHlgcQy5rFniS8jR/7Rlk/YDXp43NqjK9oYzc FeI0J/rG34AJ6d6heDnhG73A8JiyAlXMohvdqoF701Bc7TYx5fMtntCofNtc6fMrPg EWAXKwA/Mf9O9WCfz+8946sw4KO8eURIrObVsTiW6QjgNpFc+hr+6SFctAmLsbLljH BJiGxYp2Ms+uA== From: "Lorenzo Stoakes (Oracle)" To: Andrew Morton Cc: Jonathan Corbet , Clemens Ladisch , Arnd Bergmann , Greg Kroah-Hartman , "K . Y . Srinivasan" , Haiyang Zhang , Wei Liu , Dexuan Cui , Long Li , Alexander Shishkin , Maxime Coquelin , Alexandre Torgue , Miquel Raynal , Richard Weinberger , Vignesh Raghavendra , Bodo Stroesser , "Martin K . Petersen" , David Howells , Marc Dionne , Alexander Viro , Christian Brauner , Jan Kara , David Hildenbrand , "Liam R . Howlett" , Vlastimil Babka , Mike Rapoport , Suren Baghdasaryan , Michal Hocko , Jann Horn , Pedro Falcato , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, linux-hyperv@vger.kernel.org, linux-stm32@st-md-mailman.stormreply.com, linux-arm-kernel@lists.infradead.org, linux-mtd@lists.infradead.org, linux-staging@lists.linux.dev, linux-scsi@vger.kernel.org, target-devel@vger.kernel.org, linux-afs@lists.infradead.org, linux-fsdevel@vger.kernel.org, linux-mm@kvack.org, Ryan Roberts Subject: [PATCH 02/15] mm: add documentation for the mmap_prepare file operation callback Date: Thu, 12 Mar 2026 20:27:17 +0000 Message-ID: X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" This documentation makes it easier for a driver/file system implementer to correctly use this callback. It covers the fundamentals, whilst intentionally leaving the less lovely possible actions one might take undocumented (for instance - the success_hook, error_hook fields in mmap_action). The document also covers the new VMA flags implementation which is the only one which will work correctly with mmap_prepare. Signed-off-by: Lorenzo Stoakes (Oracle) --- Documentation/filesystems/mmap_prepare.rst | 131 +++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 Documentation/filesystems/mmap_prepare.rst diff --git a/Documentation/filesystems/mmap_prepare.rst b/Documentation/fil= esystems/mmap_prepare.rst new file mode 100644 index 000000000000..76908200f3a1 --- /dev/null +++ b/Documentation/filesystems/mmap_prepare.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D +mmap_prepare callback HOWTO +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +Introduction +############ + +The `struct file->f_op->mmap()` callback has been deprecated as it is both= a +stability and security risk, and doesn't always permit the merging of adja= cent +mappings resulting in unnecessary memory fragmentation. + +It has been replaced with the `file->f_op->mmap_prepare()` callback which = solves +these problems. + +## How To Use + +In your driver's `struct file_operations` struct, specify an `mmap_prepare` +callback rather than an `mmap` one, e.g. for ext4: + + +.. code-block:: C + + const struct file_operations ext4_file_operations =3D { + ... + .mmap_prepare =3D ext4_file_mmap_prepare, + }; + +This has a signature of `int (*mmap_prepare)(struct vm_area_desc *)`. + +Examining the `struct vm_area_desc` type: + +.. code-block:: C + + struct vm_area_desc { + /* Immutable state. */ + const struct mm_struct *const mm; + struct file *const file; /* May vary from vm_file in stacked calle= rs. */ + unsigned long start; + unsigned long end; + + /* Mutable fields. Populated with initial state. */ + pgoff_t pgoff; + struct file *vm_file; + vma_flags_t vma_flags; + pgprot_t page_prot; + + /* Write-only fields. */ + const struct vm_operations_struct *vm_ops; + void *private_data; + + /* Take further action? */ + struct mmap_action action; + }; + +This is straightforward - you have all the fields you need to set up the +mapping, and you can update the mutable and writable fields, for instance: + +.. code-block:: Cw + + static int ext4_file_mmap_prepare(struct vm_area_desc *desc) + { + int ret; + struct file *file =3D desc->file; + struct inode *inode =3D file->f_mapping->host; + + ... + + file_accessed(file); + if (IS_DAX(file_inode(file))) { + desc->vm_ops =3D &ext4_dax_vm_ops; + vma_desc_set_flags(desc, VMA_HUGEPAGE_BIT); + } else { + desc->vm_ops =3D &ext4_file_vm_ops; + } + return 0; + } + +Importantly, you no longer have to dance around with reference counts or l= ocks +when updating these fields - __you can simply go ahead and change them__. + +Everything is taken care of by the mapping code. + +VMA Flags +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Along with `mmap_prepare`, VMA flags have undergone an overhaul. Where bef= ore +you would invoke one of `vm_flags_init()`, `vm_flags_reset()`, `vm_flags_s= et()`, +`vm_flags_clear()`, and `vm_flags_mod()` to modify flags (and to have the +locking done correctly for you, this is no longer necessary. + +Also, the legacy approach of specifying VMA flags via `VM_READ`, `VM_WRITE= `, +etc. - i.e. using a `VM_xxx` macro has changed too. + +When implementing `mmap_prepare()`, reference flags by their bit number, d= efined +as a `VMA_xxx_BIT` macro, e.g. `VMA_READ_BIT`, `VMA_WRITE_BIT` etc., and u= se one +of (where `desc` is a pointer to `struct vma_area_desc`): + +* `vma_desc_test_flags(desc, ...)` - Specify a comma-separated list of fla= gs you + wish to test for (whether _any_ are set), e.g. - `vma_desc_test_flags(de= sc, + VMA_WRITE_BIT, VMA_MAYWRITE_BIT)` - returns `true` if either are set, + otherwise `false`. +* `vma_desc_set_flags(desc, ...)` - Update the VMA descriptor flags to set + additional flags specified by a comma-separated list, + e.g. - `vma_desc_set_flags(desc, VMA_PFNMAP_BIT, VMA_IO_BIT)`. +* `vma_desc_clear_flags(desc, ...)` - Update the VMA descriptor flags to c= lear + flags specified by a comma-separated list, e.g. - `vma_desc_clear_flags(= desc, + VMA_WRITE_BIT, VMA_MAYWRITE_BIT)`. + +Actions +=3D=3D=3D=3D=3D=3D=3D + +You can now very easily have actions be performed upon a mapping once set = up by +utilising simple helper functions invoked upon the `struct vm_area_desc` +pointer. These are: + +* `mmap_action_remap()` - Remaps a range consisting only of PFNs for a spe= cific + range starting a virtual address and PFN number of a set size. + +* `mmap_action_remap_full()` - Same as `mmap_action_remap()`, only remaps = the + entire mapping from `start_pfn` onward. + +* `mmap_action_ioremap()` - Same as `mmap_action_remap()`, only performs a= n I/O + remap. + +* `mmap_action_ioremap_full()` - Same as `mmap_action_ioremap()`, only rem= aps + the entire mapping from `start_pfn` onward. + +**NOTE:** The 'action' field should never normally be manipulated directly, +rather you ought to use one of these helpers. --=20 2.53.0