[PATCH v2 12/12] mm: change the contract for free_pgtables(), update docs

[Lorenzo Stoakes (ARM)]

On Wed, Sep 09, 2026 at 10:24:21AM +0100, Kiryl Shutsemau wrote:
> On Tue, Sep 08, 2026 at 01:32:21PM +0100, Lorenzo Stoakes (ARM) wrote:
> > Now that page tables are freed after an RCU grace period, it is safe for
> > read-only page table walkers to walk page table ranges that are being
> > concurrently torn down, provided the mm is kept alive via mmgrab().
> >
> > It is however unsafe for writers to do so, as they must obtain an
> > appropriate lock to do so safely.
> >
> > Update the pte_offset_map_lock()'s comment block to reflect this.
> >
> > Similarly update the process addresses documentation.
> >
> > Signed-off-by: Lorenzo Stoakes (ARM) <ljs at kernel.org>
> > ---
> >  Documentation/mm/process_addrs.rst |  6 ++++++
> >  mm/pgtable-generic.c               | 15 +++++++++++----
> >  2 files changed, 17 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst
> > index a7296f251799..1e65b139f355 100644
> > --- a/Documentation/mm/process_addrs.rst
> > +++ b/Documentation/mm/process_addrs.rst
> > @@ -537,6 +537,12 @@ We establish basic locking rules when interacting with page tables:
> >  * When changing a page table entry the page table lock for that page table
> >    **must** be held, except if you can safely assume nobody can access the page
> >    tables concurrently (such as on invocation of :c:func:`!free_pgtables`).
> > +* Page tables may be *walked* under RCU alone, as page tables are freed only
> > +  after an RCU grace period has elapsed. However, any entry found must be
> > +  revalidated after the page table lock is taken (such as the
> > +  :c:func:`!pmd_same` recheck performed by :c:func:`!pte_offset_map_lock`)
> > +  before it is acted upon. Changing an entry always requires the page table
> > +  lock.
>
> This says the PTL plus a recheck is enough to act on the entry. It is
> not: free_pte_range() clears the PMD without the PTL, so pmd_same() can
> pass and the table is torn down right after. That is the case we settled
> on for the pte_offset_map_lock() comment, and the two now disagree.
>
> Something like "Changing an entry requires the page table lock and one
> of the locks that excludes teardown (mmap or VMA lock)" would match the
> comment.

Ack will change!

--
Cheers, Lorenzo