[Deepin-Kernel-SIG][linux-6.6-y][Upstream] docs/mm: add VMA locks documentation#1605
Merged
opsiff merged 1 commit intodeepin-community:linux-6.6.yfrom Apr 8, 2026
Merged
Conversation
mainline inclusion from mainline-v6.13-rc4 category: docs Locking around VMAs is complicated and confusing. While we have a number of disparate comments scattered around the place, we seem to be reaching a level of complexity that justifies a serious effort at clearly documenting how locks are expected to be used when it comes to interacting with mm_struct and vm_area_struct objects. This is especially pertinent as regards the efforts to find sensible abstractions for these fundamental objects in kernel rust code whose compiler strictly requires some means of expressing these rules (and through this expression, self-document these requirements as well as enforce them). The document limits scope to mmap and VMA locks and those that are immediately adjacent and relevant to them - so additionally covers page table locking as this is so very closely tied to VMA operations (and relies upon us handling these correctly). The document tries to cover some of the nastier and more confusing edge cases and concerns especially around lock ordering and page table teardown. The document is split between generally useful information for users of mm interfaces, and separately a section intended for mm kernel developers providing a discussion around internal implementation details. [lorenzo.stoakes@oracle.com: v3] Link: https://lkml.kernel.org/r/20241114205402.859737-1-lorenzo.stoakes@oracle.com [lorenzo.stoakes@oracle.com: docs/mm: minor corrections] Link: https://lkml.kernel.org/r/d3de735a-25ae-4eb2-866c-a9624fe6f795@lucifer.local [jannh@google.com: docs/mm: add more warnings around page table access] Link: https://lkml.kernel.org/r/20241118-vma-docs-addition1-onv3-v2-1-c9d5395b72ee@google.com Link: https://lkml.kernel.org/r/20241108135708.48567-1-lorenzo.stoakes@oracle.com Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com> Acked-by: Qi Zheng <zhengqi.arch@bytedance.com> Acked-by: Mike Rapoport (Microsoft) <rppt@kernel.org> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Jann Horn <jannh@google.com> Cc: Alice Ryhl <aliceryhl@google.com> Cc: Boqun Feng <boqun.feng@gmail.com> Cc: Hillf Danton <hdanton@sina.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Liam R. Howlett <Liam.Howlett@Oracle.com> Cc: Matthew Wilcox <willy@infradead.org> Cc: SeongJae Park <sj@kernel.org> Cc: Suren Baghdasaryan <surenb@google.com> Cc: Vlastimil Babka <vbabka@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> (cherry picked from commit dbf8be8) Signed-off-by: Wentao Guan <guanwentao@uniontech.com>
Reviewer's guide (collapsed on small PRs)Reviewer's GuideBackports upstream documentation changes to extend Documentation/mm/process_addrs.rst with a detailed description of mmap/VMA locking rules, page table locking interactions, and guidance for both mm interface users and mm core developers. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 3 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="Documentation/mm/process_addrs.rst" line_range="170" />
<code_context>
+ :c:macro:`!CONFIG_ARCH_HAS_PTE_SPECIAL`.
+ ===================== ======================================== ===========
+
+These fields describes the size, start and end of the VMA, and as such cannot be
+modified without first being hidden from the reverse mapping since these fields
+are used to locate VMAs within the reverse mapping interval trees.
</code_context>
<issue_to_address>
**issue (typo):** Use plural verb form with the plural subject "fields".
This should be "These fields describe the size, start and end of the VMA..." to match the plural subject.
```suggestion
These fields describe the size, start and end of the VMA, and as such cannot be
```
</issue_to_address>
### Comment 2
<location path="Documentation/mm/process_addrs.rst" line_range="471-474" />
<code_context>
+ and PUD each make use of the process address space granularity
+ :c:member:`!mm->page_table_lock` lock when modified.
+
+* **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks
+ either kept within the folios describing the page tables or allocated
+ separated and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is
+ set. The PMD spin lock is obtained via :c:func:`!pmd_lock`, however PTEs are
+ mapped into higher memory (if a 32-bit system) and carefully locked via
</code_context>
<issue_to_address>
**suggestion (typo):** Replace "allocated separated" with "allocated separately" for correct wording.
Here, "allocated separately and pointed at by the folios" (or "pointed to by the folios") would be more grammatical and clear.
```suggestion
* **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks
either kept within the folios describing the page tables or allocated
separately and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is
set. The PMD spin lock is obtained via :c:func:`!pmd_lock`, however PTEs are
```
</issue_to_address>
### Comment 3
<location path="Documentation/mm/process_addrs.rst" line_range="568-570" />
<code_context>
+the page table entry only once.
+
+However, if we wish to manipulate an existing page table entry and care about
+the previously stored data, we must go further and use an hardware atomic
+operation as, for example, in :c:func:`!ptep_get_and_clear`.
+
</code_context>
<issue_to_address>
**issue (typo):** Change "an hardware" to "a hardware" for correct article usage.
Since "hardware" starts with a consonant sound, the article should be "a" rather than "an".
```suggestion
However, if we wish to manipulate an existing page table entry and care about
the previously stored data, we must go further and use a hardware atomic
operation as, for example, in :c:func:`!ptep_get_and_clear`.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| :c:macro:`!CONFIG_ARCH_HAS_PTE_SPECIAL`. | ||
| ===================== ======================================== =========== | ||
|
|
||
| These fields describes the size, start and end of the VMA, and as such cannot be |
There was a problem hiding this comment.
issue (typo): Use plural verb form with the plural subject "fields".
This should be "These fields describe the size, start and end of the VMA..." to match the plural subject.
Suggested change
| These fields describes the size, start and end of the VMA, and as such cannot be | |
| These fields describe the size, start and end of the VMA, and as such cannot be |
Comment on lines
+471
to
+474
| * **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks | ||
| either kept within the folios describing the page tables or allocated | ||
| separated and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is | ||
| set. The PMD spin lock is obtained via :c:func:`!pmd_lock`, however PTEs are |
There was a problem hiding this comment.
suggestion (typo): Replace "allocated separated" with "allocated separately" for correct wording.
Here, "allocated separately and pointed at by the folios" (or "pointed to by the folios") would be more grammatical and clear.
Suggested change
| * **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks | |
| either kept within the folios describing the page tables or allocated | |
| separated and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is | |
| set. The PMD spin lock is obtained via :c:func:`!pmd_lock`, however PTEs are | |
| * **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks | |
| either kept within the folios describing the page tables or allocated | |
| separately and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is | |
| set. The PMD spin lock is obtained via :c:func:`!pmd_lock`, however PTEs are |
Comment on lines
+568
to
+570
| However, if we wish to manipulate an existing page table entry and care about | ||
| the previously stored data, we must go further and use an hardware atomic | ||
| operation as, for example, in :c:func:`!ptep_get_and_clear`. |
There was a problem hiding this comment.
issue (typo): Change "an hardware" to "a hardware" for correct article usage.
Since "hardware" starts with a consonant sound, the article should be "a" rather than "an".
Suggested change
| However, if we wish to manipulate an existing page table entry and care about | |
| the previously stored data, we must go further and use an hardware atomic | |
| operation as, for example, in :c:func:`!ptep_get_and_clear`. | |
| However, if we wish to manipulate an existing page table entry and care about | |
| the previously stored data, we must go further and use a hardware atomic | |
| operation as, for example, in :c:func:`!ptep_get_and_clear`. |
Member
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Avenger-285714 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
There was a problem hiding this comment.
Pull request overview
This PR substantially expands Documentation/mm/process_addrs.rst to document VMA/mmap/rmap locking and closely related page table locking semantics, targeting both general mm interface users and mm developers.
Changes:
- Adds a comprehensive overview of VMAs,
mm_struct, and the different lock types (mmap/VMA/rmap) and their permitted combinations. - Documents page table operations (traversal/install/zap/free), locking requirements, ordering concerns, and PTE-level special cases.
- Adds internal implementation notes on per-VMA locking and mmap write-lock downgrading behavior.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+7
to
+10
| .. toctree:: | ||
| :maxdepth: 3 | ||
|
|
||
|
|
There was a problem hiding this comment.
The file adds a .. toctree:: directive but no entries, which typically triggers a Sphinx warning (empty toctree) and doesn’t provide navigation. Either remove this toctree block or add the intended child documents under it.
Suggested change
| .. toctree:: | |
| :maxdepth: 3 |
Comment on lines
+216
to
+225
| underlying object is reference counted | ||
| and can be shared across multiple VMAs | ||
| for scalability. | ||
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | ||
| to perform readahead. This field is swap-specific | ||
| accessed atomically. lock. | ||
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | ||
| describes the NUMA behaviour of the VMA write. | ||
| VMA. The underlying object is reference | ||
| counted. |
There was a problem hiding this comment.
This table row continuation uses tab characters for indentation. Tabs can break RST table alignment/rendering; replace tabs with spaces and align the wrapped description text with the other cells.
Suggested change
| underlying object is reference counted | |
| and can be shared across multiple VMAs | |
| for scalability. | |
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | |
| to perform readahead. This field is swap-specific | |
| accessed atomically. lock. | |
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | |
| describes the NUMA behaviour of the VMA write. | |
| VMA. The underlying object is reference | |
| counted. | |
| underlying object is reference counted | |
| and can be shared across multiple VMAs | |
| for scalability. | |
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | |
| to perform readahead. This field is swap-specific | |
| accessed atomically. lock. | |
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | |
| describes the NUMA behaviour of the VMA write. | |
| VMA. The underlying object is reference | |
| counted. |
Comment on lines
+216
to
+225
| underlying object is reference counted | ||
| and can be shared across multiple VMAs | ||
| for scalability. | ||
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | ||
| to perform readahead. This field is swap-specific | ||
| accessed atomically. lock. | ||
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | ||
| describes the NUMA behaviour of the VMA write. | ||
| VMA. The underlying object is reference | ||
| counted. |
There was a problem hiding this comment.
There’s a stray tab-indented continuation line inside the table ("counted."). Tabs can break RST table formatting; use spaces and align the wrapped text with the other cell contents.
Suggested change
| underlying object is reference counted | |
| and can be shared across multiple VMAs | |
| for scalability. | |
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | |
| to perform readahead. This field is swap-specific | |
| accessed atomically. lock. | |
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | |
| describes the NUMA behaviour of the VMA write. | |
| VMA. The underlying object is reference | |
| counted. | |
| underlying object is reference counted | |
| and can be shared across multiple VMAs | |
| for scalability. | |
| :c:member:`!swap_readahead_info` CONFIG_SWAP Metadata used by the swap mechanism mmap read, | |
| to perform readahead. This field is swap-specific | |
| accessed atomically. lock. | |
| :c:member:`!vm_policy` CONFIG_NUMA :c:type:`!mempolicy` object which mmap write, | |
| describes the NUMA behaviour of the VMA write. | |
| VMA. The underlying object is reference | |
| counted. |
Comment on lines
+295
to
+299
| five the kernel cleverly 'folds' page table levels, that is stubbing | ||
| out functions related to the skipped levels. This allows us to | ||
| conceptually act as if there were always five levels, even if the | ||
| compiler might, in practice, eliminate any code relating to missing | ||
| ones. |
There was a problem hiding this comment.
This .. note:: block uses tab indentation for its content. RST expects consistent space indentation; tabs can render incorrectly or fail doc builds. Replace the tabs with spaces and keep indentation consistent with other notes in the file.
Suggested change
| five the kernel cleverly 'folds' page table levels, that is stubbing | |
| out functions related to the skipped levels. This allows us to | |
| conceptually act as if there were always five levels, even if the | |
| compiler might, in practice, eliminate any code relating to missing | |
| ones. | |
| five the kernel cleverly 'folds' page table levels, that is stubbing | |
| out functions related to the skipped levels. This allows us to | |
| conceptually act as if there were always five levels, even if the | |
| compiler might, in practice, eliminate any code relating to missing | |
| ones. |
Comment on lines
+378
to
+386
| .. code-block:: | ||
|
|
||
| inode->i_rwsem (while writing or truncating, not reading or faulting) | ||
| mm->mmap_lock | ||
| mapping->invalidate_lock (in filemap_fault) | ||
| folio_lock | ||
| hugetlbfs_i_mmap_rwsem_key (in huge_pmd_share, see hugetlbfs below) | ||
| vma_start_write | ||
| mapping->i_mmap_rwsem |
There was a problem hiding this comment.
.. code-block:: normally requires an explicit language (e.g. text or none). As written, this may be rejected by Sphinx or rendered inconsistently. Specify an appropriate language for this lock-ordering snippet.
|
|
||
| * **Fine-grained page table locks** - PMDs and PTEs each have fine-grained locks | ||
| either kept within the folios describing the page tables or allocated | ||
| separated and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is |
There was a problem hiding this comment.
Wording issue: “allocated separated” should be “allocated separately”.
Suggested change
| separated and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is | |
| separately and pointed at by the folios if :c:macro:`!ALLOC_SPLIT_PTLOCKS` is |
Comment on lines
+565
to
+569
| Each of these uses :c:func:`!READ_ONCE` to guarantee that the compiler reads | ||
| the page table entry only once. | ||
|
|
||
| However, if we wish to manipulate an existing page table entry and care about | ||
| the previously stored data, we must go further and use an hardware atomic |
There was a problem hiding this comment.
READ_ONCE is a macro, but it’s referenced as :c:func:!READ_ONCE here; consider using `:c:macro:`!READ_ONCE for correct markup. Also, “an hardware atomic operation” should be “a hardware atomic operation”.
Suggested change
| Each of these uses :c:func:`!READ_ONCE` to guarantee that the compiler reads | |
| the page table entry only once. | |
| However, if we wish to manipulate an existing page table entry and care about | |
| the previously stored data, we must go further and use an hardware atomic | |
| Each of these uses :c:macro:`!READ_ONCE` to guarantee that the compiler reads | |
| the page table entry only once. | |
| However, if we wish to manipulate an existing page table entry and care about | |
| the previously stored data, we must go further and use a hardware atomic |
| Terminology | ||
| ----------- | ||
|
|
||
| * **mmap locks** - Each MM has a read/write semaphore :c:member:`!mmap_lock` |
There was a problem hiding this comment.
This sentence uses :c:member:!mmap_lock without indicating which type it belongs to. To avoid ambiguity, consider referencing it as `:c:member:`mm_struct.mmap_lock or otherwise making it explicit that this is mm_struct->mmap_lock.
Suggested change
| * **mmap locks** - Each MM has a read/write semaphore :c:member:`!mmap_lock` | |
| * **mmap locks** - Each MM has a read/write semaphore :c:member:`mm_struct.mmap_lock` |
Comment on lines
+380
to
+386
| inode->i_rwsem (while writing or truncating, not reading or faulting) | ||
| mm->mmap_lock | ||
| mapping->invalidate_lock (in filemap_fault) | ||
| folio_lock | ||
| hugetlbfs_i_mmap_rwsem_key (in huge_pmd_share, see hugetlbfs below) | ||
| vma_start_write | ||
| mapping->i_mmap_rwsem |
There was a problem hiding this comment.
This lock-ordering snippet is introduced as the opening comment from mm/rmap.c, but it doesn’t match the actual comment in this branch (e.g., mm/rmap.c has page->flags PG_locked (lock_page) and additional locks, while this shows folio_lock). Consider quoting the current mm/rmap.c comment verbatim (or explicitly mark this as an adapted example).
Comment on lines
+437
to
+446
| ->page_table_lock or pte_lock | ||
| ->swap_lock (try_to_unmap_one) | ||
| ->private_lock (try_to_unmap_one) | ||
| ->i_pages lock (try_to_unmap_one) | ||
| ->lruvec->lru_lock (follow_page_mask->mark_page_accessed) | ||
| ->lruvec->lru_lock (check_pte_range->folio_isolate_lru) | ||
| ->private_lock (folio_remove_rmap_pte->set_page_dirty) | ||
| ->i_pages lock (folio_remove_rmap_pte->set_page_dirty) | ||
| bdi.wb->list_lock (folio_remove_rmap_pte->set_page_dirty) | ||
| ->inode->i_lock (folio_remove_rmap_pte->set_page_dirty) |
There was a problem hiding this comment.
Similarly, this is presented as the lock-ordering comment from mm/filemap.c, but several entries differ from the actual comment in this branch (e.g. follow_page_mask vs follow_page, folio_remove_rmap_pte vs page_remove_rmap). To avoid confusion, consider syncing this snippet with the current mm/filemap.c comment or clearly labeling it as a non-verbatim/forward-looking version.
Member
|
It looks like there's no process_addrs.rst under Documentation/translations/zh_CN/mm (upstream). We could add it when getting chance. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
mainline inclusion
from mainline-v6.13-rc4
category: docs
Locking around VMAs is complicated and confusing. While we have a number of disparate comments scattered around the place, we seem to be reaching a level of complexity that justifies a serious effort at clearly documenting how locks are expected to be used when it comes to interacting with mm_struct and vm_area_struct objects.
This is especially pertinent as regards the efforts to find sensible abstractions for these fundamental objects in kernel rust code whose compiler strictly requires some means of expressing these rules (and through this expression, self-document these requirements as well as enforce them).
The document limits scope to mmap and VMA locks and those that are immediately adjacent and relevant to them - so additionally covers page table locking as this is so very closely tied to VMA operations (and relies upon us handling these correctly).
The document tries to cover some of the nastier and more confusing edge cases and concerns especially around lock ordering and page table teardown.
The document is split between generally useful information for users of mm interfaces, and separately a section intended for mm kernel developers providing a discussion around internal implementation details.
[lorenzo.stoakes@oracle.com: v3]
Link: https://lkml.kernel.org/r/20241114205402.859737-1-lorenzo.stoakes@oracle.com
[lorenzo.stoakes@oracle.com: docs/mm: minor corrections]
Link: https://lkml.kernel.org/r/d3de735a-25ae-4eb2-866c-a9624fe6f795@lucifer.local
[jannh@google.com: docs/mm: add more warnings around page table access]
Link: https://lkml.kernel.org/r/20241118-vma-docs-addition1-onv3-v2-1-c9d5395b72ee@google.com
Link: https://lkml.kernel.org/r/20241108135708.48567-1-lorenzo.stoakes@oracle.com
Acked-by: Qi Zheng zhengqi.arch@bytedance.com
Acked-by: Mike Rapoport (Microsoft) rppt@kernel.org
Reviewed-by: Bagas Sanjaya bagasdotme@gmail.com
Reviewed-by: Jann Horn jannh@google.com
Cc: Alice Ryhl aliceryhl@google.com
Cc: Boqun Feng boqun.feng@gmail.com
Cc: Hillf Danton hdanton@sina.com
Cc: Jonathan Corbet corbet@lwn.net
Cc: Liam R. Howlett Liam.Howlett@Oracle.com
Cc: Matthew Wilcox willy@infradead.org
Cc: SeongJae Park sj@kernel.org
Cc: Suren Baghdasaryan surenb@google.com
Cc: Vlastimil Babka vbabka@suse.cz
(cherry picked from commit dbf8be8)
Summary by Sourcery
Documentation: