From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-alma10-1.taild15c8.ts.net [100.103.45.18]) (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 2DC1854B1D3; Tue, 13 Oct 2026 15:26:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=100.103.45.18 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791905171; cv=none; b=iRHt1CKhnb0LsRoEo8dBJwHwpo4ddRD8H9g/B2OGC8L8fsB5W8CXSF1PXAIto8aDG08xrw4P8yuIfBxd+VZx+wo4HqURdJZxq2Y+N35vgY2eU49x59ndO+aOao12xMTclchA+3PQvdoCA+ZlYz3htp8XNHzbsYuPKoRdlBt4kU0= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791905171; c=relaxed/simple; bh=DDiahBEFUVzHSQO+kCct3A2pNxLPszDSq8A2g5WOsqQ=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=oCIwkQ0ztRSdg8oLEfgPhKe9ft+3S1JlLpVdtTjq/Z0xYDPioSM1+42DN3OeqQXqiguwETiPith3c+ZcjkGhnav/vMw19FvBYMva0V2u5SDkOaC9hNgHmbElX/A0Arqaw3h7L6VOCUyoqNnEpxNtywtViMhWGJ/6Kmkldiupy9Y= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PZOBya++; arc=none smtp.client-ip=100.103.45.18 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="PZOBya++" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4E7B71F000FF; Tue, 13 Oct 2026 15:25:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kernel.org; s=k20260515; t=1791905169; bh=G4u/5yOQJ9DvGgmtwMCTNwSFdn4Bt/KH0TLY0ESMg1E=; h=Date:Subject:To:Cc:References:From:In-Reply-To; b=PZOBya++ukTznkcFehO8mUZ/500E6EjoUbkakGO4LAJjse/uybNRq4JgfI4l2XPde biJU+3ftzSrE3lxabC/wUtQvplsNRf41l4nhCKCiqJxyYCs+QmRYLW863oL1ZzgQqn CSKVQbdsvxSgBfe6D7sX2fmPuzgFEDU3PdZH/DNL9YfqfH0zQU6c56R0WQDWxNytCQ D8S0OkiBTXs73chJpVcL5i3f3S9sWdgaNGbx02F95N2VeA85vk52wKbv4gp6Kq/1rk jC2u7PVOECqeXedpj70EJihHLltFuDkTB1mjGIKBoiNHQxk5OTt0dsrY2Cjxo7vyok 0JLbZ4KqAQ75w== Message-ID: <69ce0f48-aec7-448a-adcf-8cac08a2696c@kernel.org> Date: Tue, 13 Oct 2026 17:25:35 +0200 Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v6 09/39] docs: filesystems: update mmap_prepare docs for discontig kernel pgs To: "Lorenzo Stoakes (ARM)" , Andrew Morton , "Liam R. Howlett" , Vlastimil Babka , Jann Horn , Pedro Falcato , Mike Rapoport , Suren Baghdasaryan , Michal Hocko , Jonathan Corbet , Greg Kroah-Hartman , Dennis Dalessandro , Jason Gunthorpe , Leon Romanovsky , Paul Moore , Stephen Smalley , Jaroslav Kysela , Takashi Iwai , Alexei Starovoitov , Daniel Borkmann , Andrii Nakryiko , Eduard Zingerman , Kumar Kartikeya Dwivedi , Zi Yan , Baolin Wang , Nico Pache , Ryan Roberts , Dev Jain , Barry Song , Lance Yang , Usama Arif , Kiryl Shutsemau , Doug Gilbert , "James E.J. Bottomley" , "Martin K. Petersen" , Simona Vetter , Helge Deller , Sebastian Reichel , John Hubbard , Peter Xu , Masami Hiramatsu , Oleg Nesterov , Peter Zijlstra , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , x86@kernel.org, Arnaldo Carvalho de Melo , Namhyung Kim , Mark Rutland , Rik van Riel , Harry Yoo , Juri Lelli , Vincent Guittot , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , David Airlie , Will Deacon , "Aneesh Kumar K.V" , Nick Piggin , Arnd Bergmann , Muchun Song , Oscar Salvador , "Matthew Wilcox (Oracle)" , Jan Kara , Marc Zyngier , Oliver Upton , Catalin Marinas , Madhavan Srinivasan , Anup Patel , Paul Walmsley , Palmer Dabbelt , Albert Ou , Christian Borntraeger , Janosch Frank , Claudio Imbrenda , Alexander Gordeev , Gerald Schaefer , Heiko Carstens , Vasily Gorbik , "David S. Miller" , Andreas Larsson , Alexander Viro , Christian Brauner , Matthew Brost , Joshua Hahn , Rakie Kim , Byungchul Park , Gregory Price , Ying Huang , Alistair Popple , Chris Li , Kairui Song , Kemeng Shi , Nhat Pham , Baoquan He , Youngjun Park , Johannes Weiner , Qi Zheng , Shakeel Butt , Axel Rasmussen , Yuanchu Xie , Wei Xu , Chengming Zhou , Michal Hocko , Miklos Szeredi , Xu Xin Cc: linux-mm@kvack.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, linux-usb@vger.kernel.org, linux-rdma@vger.kernel.org, selinux@vger.kernel.org, linux-sound@vger.kernel.org, bpf@vger.kernel.org, linux-scsi@vger.kernel.org, linux-fbdev@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-trace-kernel@vger.kernel.org, linux-perf-users@vger.kernel.org, linux-arch@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, kvmarm@lists.linux.dev, linuxppc-dev@lists.ozlabs.org, kvm@vger.kernel.org, kvm-riscv@lists.infradead.org, linux-riscv@lists.infradead.org, linux-s390@vger.kernel.org, sparclinux@vger.kernel.org, fuse-devel@lists.linux.dev, Ihor Solodrai , Bert Karwatzki References: <20261013-b4-mmap-prepare-vma-flag-sanify-v6-0-1aa3c9b139f9@kernel.org> <20261013-b4-mmap-prepare-vma-flag-sanify-v6-9-1aa3c9b139f9@kernel.org> From: "David Hildenbrand (Arm)" Content-Language: en-US Autocrypt: addr=david@kernel.org; keydata= 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 qIws/H2t In-Reply-To: <20261013-b4-mmap-prepare-vma-flag-sanify-v6-9-1aa3c9b139f9@kernel.org> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit On 10/13/26 17:04, Lorenzo Stoakes (ARM) wrote: > Describe the newly introduced discontiguous kernel page mapping mechanism, > detailing how to use it sensibly and how the API looks. > > Explicitly detail the various discontiguous actions available and how to > use them. > > Reviewed-by: Suren Baghdasaryan > Signed-off-by: Lorenzo Stoakes (ARM) > --- > Documentation/filesystems/mmap_prepare.rst | 81 ++++++++++++++++++++++++++++++ > 1 file changed, 81 insertions(+) > > diff --git a/Documentation/filesystems/mmap_prepare.rst b/Documentation/filesystems/mmap_prepare.rst > index 82c99c95ad85..b5afbb33e5c8 100644 > --- a/Documentation/filesystems/mmap_prepare.rst > +++ b/Documentation/filesystems/mmap_prepare.rst > @@ -164,5 +164,86 @@ pointer. These are: > sufficient entries in the page array to cover the entire range of the > described VMA. > > +* mmap_action_map_discontig_kernel_pages() - Maps a discontiguous range of > + `struct page` pointers over the VMA. They must span from the start of the VMA, > + but may terminate prior to the end (leaving the remainder unmapped). > + > **NOTE:** The ``action`` field should never normally be manipulated directly, > rather you ought to use one of these helpers. > + > +Discontiguous Actions > +===================== > + > +Some actions can be performed across discontiguous ranges. > + > +Map kernel pages > +---------------- > + > +To map kernel pages discontiguously, you must provide hooks using ``struct > +discontig_kernel_page_ops``: > + > +.. code-block:: C > + > + struct discontig_kernel_page_ops { > + int (*init)(void *vm_private_data, void **private); > + int (*get)(struct discontig_kernel_page_state *state); > + }; > + > +The ``init`` hook is optional and allows state to be established before the > +operation starts, for instance taking a reference count. Nothing is invoked > +after the operation, so ``init`` must not leave locks held, and state that must > +be released once the mapping goes away should be released in > +``vm_ops->close``. > + > +The ``init`` hook, if provided, is invoked prior to the operation starting. It > +may update what is pointed to by ``vm_private_data`` and/or ``private``. If an > +error is returned, then the operation is aborted. The ``private`` field can be > +reassigned. > + > +**NOTE:** The operation may sleep between invocations of ``get``, so locks > +needed to stabilise state must be taken and released within each hook. > + > +The ``get`` handler is the key means through which the operation is > +executed. The current state of the operation is provided through ``struct > +discontig_kernel_page_state``: > + > +.. code-block:: C > + > + struct discontig_kernel_page_state { > + /* Map state. */ > + unsigned long start; /* Start address of VMA. */ > + unsigned long end; /* End address of VMA. */ > + unsigned long addr; /* The current address to be mapped. */ > + pgoff_t pgoff; /* The current pgoff to be mapped. */ > + unsigned long nr_pages_mapped; /* The number of pages mapped. */ > + unsigned long nr_pages_remain; /* The number of pages remaining. */ > + > + /* User-defined state. */ > + void *vm_private_data; /* VMA private data. */ > + void *private; /* Mapping private data. */ > + > + /* Users should not touch these, use discontig_kernel_map_*() helpers. */ > + ... internal fields ... > + }; > + > +With ``private`` being an additional user-controllable state variable, > +initialised via ``mmap_action_map_discontig_kernel_pages()``, and > +``vm_private_data`` being equal to the ``desc->private_data`` field set in > +the ``mmap_prepare()`` hook. > + > +In the ``get`` hook, the user must choose how to map kernel pages: > + > +* ``discontig_kernel_map_abort()`` - Call this to abort the operation, whatever > + has been mapped so far will be retained, the rest of the mapping will SIGBUS > + if accessed. > +* ``discontig_kernel_map_page()`` - Maps a single page, correctly handling "single page" can be misleading with compound pages. "Map an entire (compound) page" or sth like that would be clearer. Acked-by: David Hildenbrand (Arm) -- Cheers, David