tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs/mm: expand vma doc to highlight pte freeing, non-vma traversal

The process addresses documentation already contains a great deal of
information about mmap/VMA locking and page table traversal and
manipulation.

However it waves it hands about non-VMA traversal. Add a section for this
and explain the caveats around this kind of traversal.

Additionally, commit 6375e95f381e ("mm: pgtable: reclaim empty PTE page in
madvise(MADV_DONTNEED)") caused zapping to also free empty PTE page
tables. Highlight this.

Link: https://lkml.kernel.org/r/20250604180308.137116-1-lorenzo.stoakes@oracle.com
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Jann Horn <jannh@google.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Liam Howlett <liam.howlett@oracle.com>
Cc: Qi Zheng <zhengqi.arch@bytedance.com>
Cc: Shakeel Butt <shakeel.butt@linux.dev>
Cc: Suren Baghdasaryan <surenb@google.com>
Cc: Vlastimil Babka <vbabka@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>

authored by

Lorenzo Stoakes and committed by
Andrew Morton 80d1a813 3091b615

+48 -6
+48 -6
Documentation/mm/process_addrs.rst
··· 303 303 1. **Traversing** page tables - Simply reading page tables in order to traverse 304 304 them. This only requires that the VMA is kept stable, so a lock which 305 305 establishes this suffices for traversal (there are also lockless variants 306 - which eliminate even this requirement, such as :c:func:`!gup_fast`). 306 + which eliminate even this requirement, such as :c:func:`!gup_fast`). There is 307 + also a special case of page table traversal for non-VMA regions which we 308 + consider separately below. 307 309 2. **Installing** page table mappings - Whether creating a new mapping or 308 310 modifying an existing one in such a way as to change its identity. This 309 311 requires that the VMA is kept stable via an mmap or VMA lock (explicitly not ··· 337 335 operations that perform writes also acquire internal page table locks to 338 336 serialise - see the page table implementation detail section for more details). 339 337 338 + .. note:: We free empty PTE tables on zap under the RCU lock - this does not 339 + change the aforementioned locking requirements around zapping. 340 + 340 341 When **installing** page table entries, the mmap or VMA lock must be held to 341 342 keep the VMA stable. We explore why this is in the page table locking details 342 343 section below. 343 - 344 - .. warning:: Page tables are normally only traversed in regions covered by VMAs. 345 - If you want to traverse page tables in areas that might not be 346 - covered by VMAs, heavier locking is required. 347 - See :c:func:`!walk_page_range_novma` for details. 348 344 349 345 **Freeing** page tables is an entirely internal memory management operation and 350 346 has special requirements (see the page freeing section below for more details). ··· 354 354 The :c:func:`!free_pgtables` function removes the relevant VMAs 355 355 from the reverse mappings, but no other VMAs can be permitted to be 356 356 accessible and span the specified range. 357 + 358 + Traversing non-VMA page tables 359 + ------------------------------ 360 + 361 + We've focused above on traversal of page tables belonging to VMAs. It is also 362 + possible to traverse page tables which are not represented by VMAs. 363 + 364 + Kernel page table mappings themselves are generally managed but whatever part of 365 + the kernel established them and the aforementioned locking rules do not apply - 366 + for instance vmalloc has its own set of locks which are utilised for 367 + establishing and tearing down page its page tables. 368 + 369 + However, for convenience we provide the :c:func:`!walk_kernel_page_table_range` 370 + function which is synchronised via the mmap lock on the :c:macro:`!init_mm` 371 + kernel instantiation of the :c:struct:`!struct mm_struct` metadata object. 372 + 373 + If an operation requires exclusive access, a write lock is used, but if not, a 374 + read lock suffices - we assert only that at least a read lock has been acquired. 375 + 376 + Since, aside from vmalloc and memory hot plug, kernel page tables are not torn 377 + down all that often - this usually suffices, however any caller of this 378 + functionality must ensure that any additionally required locks are acquired in 379 + advance. 380 + 381 + We also permit a truly unusual case is the traversal of non-VMA ranges in 382 + **userland** ranges, as provided for by :c:func:`!walk_page_range_debug`. 383 + 384 + This has only one user - the general page table dumping logic (implemented in 385 + :c:macro:`!mm/ptdump.c`) - which seeks to expose all mappings for debug purposes 386 + even if they are highly unusual (possibly architecture-specific) and are not 387 + backed by a VMA. 388 + 389 + We must take great care in this case, as the :c:func:`!munmap` implementation 390 + detaches VMAs under an mmap write lock before tearing down page tables under a 391 + downgraded mmap read lock. 392 + 393 + This means such an operation could race with this, and thus an mmap **write** 394 + lock is required. 357 395 358 396 Lock ordering 359 397 ------------- ··· 498 460 499 461 Page table locking details 500 462 -------------------------- 463 + 464 + .. note:: This section explores page table locking requirements for page tables 465 + encompassed by a VMA. See the above section on non-VMA page table 466 + traversal for details on how we handle that case. 501 467 502 468 In addition to the locks described in the terminology section above, we have 503 469 additional locks dedicated to page tables: