tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/mm: add descriptions for arch page table helpers
This adds a specific description file for all arch page table helpers which
is in sync with the semantics being tested via CONFIG_DEBUG_VM_PGTABLE. All
future changes either to these descriptions here or the debug test should
always remain in sync.
[anshuman.khandual@arm.com: fold in Mike's patch for the rst document, fix typos in the rst document]
Link: http://lkml.kernel.org/r/1594610587-4172-5-git-send-email-anshuman.khandual@arm.com
Suggested-by: Mike Rapoport <rppt@kernel.org>
Signed-off-by: Anshuman Khandual <anshuman.khandual@arm.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Acked-by: Mike Rapoport <rppt@linux.ibm.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mike Rapoport <rppt@linux.ibm.com>
Cc: Vineet Gupta <vgupta@synopsys.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Paul Mackerras <paulus@samba.org>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Heiko Carstens <heiko.carstens@de.ibm.com>
Cc: Vasily Gorbik <gor@linux.ibm.com>
Cc: Christian Borntraeger <borntraeger@de.ibm.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Borislav Petkov <bp@alien8.de>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Kirill A. Shutemov <kirill@shutemov.name>
Cc: Paul Walmsley <paul.walmsley@sifive.com>
Cc: Palmer Dabbelt <palmer@dabbelt.com>
Cc: Zi Yan <ziy@nvidia.com>
Link: http://lkml.kernel.org/r/1593996516-7186-5-git-send-email-anshuman.khandual@arm.com
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
authored by
Anshuman Khandual
and committed by
Linus Torvalds
b1d00007
6315df41
+264
+258
Documentation/vm/arch_pgtable_helpers.rst
+258
Documentation/vm/arch_pgtable_helpers.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. _arch_page_table_helpers:
4
+
5
+
===============================
6
+
Architecture Page Table Helpers
7
+
===============================
8
+
9
+
Generic MM expects architectures (with MMU) to provide helpers to create, access
10
+
and modify page table entries at various level for different memory functions.
11
+
These page table helpers need to conform to a common semantics across platforms.
12
+
Following tables describe the expected semantics which can also be tested during
13
+
boot via CONFIG_DEBUG_VM_PGTABLE option. All future changes in here or the debug
14
+
test need to be in sync.
15
+
16
+
======================
17
+
PTE Page Table Helpers
18
+
======================
19
+
20
+
+---------------------------+--------------------------------------------------+
21
+
| pte_same | Tests whether both PTE entries are the same |
22
+
+---------------------------+--------------------------------------------------+
23
+
| pte_bad | Tests a non-table mapped PTE |
24
+
+---------------------------+--------------------------------------------------+
25
+
| pte_present | Tests a valid mapped PTE |
26
+
+---------------------------+--------------------------------------------------+
27
+
| pte_young | Tests a young PTE |
28
+
+---------------------------+--------------------------------------------------+
29
+
| pte_dirty | Tests a dirty PTE |
30
+
+---------------------------+--------------------------------------------------+
31
+
| pte_write | Tests a writable PTE |
32
+
+---------------------------+--------------------------------------------------+
33
+
| pte_special | Tests a special PTE |
34
+
+---------------------------+--------------------------------------------------+
35
+
| pte_protnone | Tests a PROT_NONE PTE |
36
+
+---------------------------+--------------------------------------------------+
37
+
| pte_devmap | Tests a ZONE_DEVICE mapped PTE |
38
+
+---------------------------+--------------------------------------------------+
39
+
| pte_soft_dirty | Tests a soft dirty PTE |
40
+
+---------------------------+--------------------------------------------------+
41
+
| pte_swp_soft_dirty | Tests a soft dirty swapped PTE |
42
+
+---------------------------+--------------------------------------------------+
43
+
| pte_mkyoung | Creates a young PTE |
44
+
+---------------------------+--------------------------------------------------+
45
+
| pte_mkold | Creates an old PTE |
46
+
+---------------------------+--------------------------------------------------+
47
+
| pte_mkdirty | Creates a dirty PTE |
48
+
+---------------------------+--------------------------------------------------+
49
+
| pte_mkclean | Creates a clean PTE |
50
+
+---------------------------+--------------------------------------------------+
51
+
| pte_mkwrite | Creates a writable PTE |
52
+
+---------------------------+--------------------------------------------------+
53
+
| pte_mkwrprotect | Creates a write protected PTE |
54
+
+---------------------------+--------------------------------------------------+
55
+
| pte_mkspecial | Creates a special PTE |
56
+
+---------------------------+--------------------------------------------------+
57
+
| pte_mkdevmap | Creates a ZONE_DEVICE mapped PTE |
58
+
+---------------------------+--------------------------------------------------+
59
+
| pte_mksoft_dirty | Creates a soft dirty PTE |
60
+
+---------------------------+--------------------------------------------------+
61
+
| pte_clear_soft_dirty | Clears a soft dirty PTE |
62
+
+---------------------------+--------------------------------------------------+
63
+
| pte_swp_mksoft_dirty | Creates a soft dirty swapped PTE |
64
+
+---------------------------+--------------------------------------------------+
65
+
| pte_swp_clear_soft_dirty | Clears a soft dirty swapped PTE |
66
+
+---------------------------+--------------------------------------------------+
67
+
| pte_mknotpresent | Invalidates a mapped PTE |
68
+
+---------------------------+--------------------------------------------------+
69
+
| ptep_get_and_clear | Clears a PTE |
70
+
+---------------------------+--------------------------------------------------+
71
+
| ptep_get_and_clear_full | Clears a PTE |
72
+
+---------------------------+--------------------------------------------------+
73
+
| ptep_test_and_clear_young | Clears young from a PTE |
74
+
+---------------------------+--------------------------------------------------+
75
+
| ptep_set_wrprotect | Converts into a write protected PTE |
76
+
+---------------------------+--------------------------------------------------+
77
+
| ptep_set_access_flags | Converts into a more permissive PTE |
78
+
+---------------------------+--------------------------------------------------+
79
+
80
+
======================
81
+
PMD Page Table Helpers
82
+
======================
83
+
84
+
+---------------------------+--------------------------------------------------+
85
+
| pmd_same | Tests whether both PMD entries are the same |
86
+
+---------------------------+--------------------------------------------------+
87
+
| pmd_bad | Tests a non-table mapped PMD |
88
+
+---------------------------+--------------------------------------------------+
89
+
| pmd_leaf | Tests a leaf mapped PMD |
90
+
+---------------------------+--------------------------------------------------+
91
+
| pmd_huge | Tests a HugeTLB mapped PMD |
92
+
+---------------------------+--------------------------------------------------+
93
+
| pmd_trans_huge | Tests a Transparent Huge Page (THP) at PMD |
94
+
+---------------------------+--------------------------------------------------+
95
+
| pmd_present | Tests a valid mapped PMD |
96
+
+---------------------------+--------------------------------------------------+
97
+
| pmd_young | Tests a young PMD |
98
+
+---------------------------+--------------------------------------------------+
99
+
| pmd_dirty | Tests a dirty PMD |
100
+
+---------------------------+--------------------------------------------------+
101
+
| pmd_write | Tests a writable PMD |
102
+
+---------------------------+--------------------------------------------------+
103
+
| pmd_special | Tests a special PMD |
104
+
+---------------------------+--------------------------------------------------+
105
+
| pmd_protnone | Tests a PROT_NONE PMD |
106
+
+---------------------------+--------------------------------------------------+
107
+
| pmd_devmap | Tests a ZONE_DEVICE mapped PMD |
108
+
+---------------------------+--------------------------------------------------+
109
+
| pmd_soft_dirty | Tests a soft dirty PMD |
110
+
+---------------------------+--------------------------------------------------+
111
+
| pmd_swp_soft_dirty | Tests a soft dirty swapped PMD |
112
+
+---------------------------+--------------------------------------------------+
113
+
| pmd_mkyoung | Creates a young PMD |
114
+
+---------------------------+--------------------------------------------------+
115
+
| pmd_mkold | Creates an old PMD |
116
+
+---------------------------+--------------------------------------------------+
117
+
| pmd_mkdirty | Creates a dirty PMD |
118
+
+---------------------------+--------------------------------------------------+
119
+
| pmd_mkclean | Creates a clean PMD |
120
+
+---------------------------+--------------------------------------------------+
121
+
| pmd_mkwrite | Creates a writable PMD |
122
+
+---------------------------+--------------------------------------------------+
123
+
| pmd_mkwrprotect | Creates a write protected PMD |
124
+
+---------------------------+--------------------------------------------------+
125
+
| pmd_mkspecial | Creates a special PMD |
126
+
+---------------------------+--------------------------------------------------+
127
+
| pmd_mkdevmap | Creates a ZONE_DEVICE mapped PMD |
128
+
+---------------------------+--------------------------------------------------+
129
+
| pmd_mksoft_dirty | Creates a soft dirty PMD |
130
+
+---------------------------+--------------------------------------------------+
131
+
| pmd_clear_soft_dirty | Clears a soft dirty PMD |
132
+
+---------------------------+--------------------------------------------------+
133
+
| pmd_swp_mksoft_dirty | Creates a soft dirty swapped PMD |
134
+
+---------------------------+--------------------------------------------------+
135
+
| pmd_swp_clear_soft_dirty | Clears a soft dirty swapped PMD |
136
+
+---------------------------+--------------------------------------------------+
137
+
| pmd_mkinvalid | Invalidates a mapped PMD [1] |
138
+
+---------------------------+--------------------------------------------------+
139
+
| pmd_set_huge | Creates a PMD huge mapping |
140
+
+---------------------------+--------------------------------------------------+
141
+
| pmd_clear_huge | Clears a PMD huge mapping |
142
+
+---------------------------+--------------------------------------------------+
143
+
| pmdp_get_and_clear | Clears a PMD |
144
+
+---------------------------+--------------------------------------------------+
145
+
| pmdp_get_and_clear_full | Clears a PMD |
146
+
+---------------------------+--------------------------------------------------+
147
+
| pmdp_test_and_clear_young | Clears young from a PMD |
148
+
+---------------------------+--------------------------------------------------+
149
+
| pmdp_set_wrprotect | Converts into a write protected PMD |
150
+
+---------------------------+--------------------------------------------------+
151
+
| pmdp_set_access_flags | Converts into a more permissive PMD |
152
+
+---------------------------+--------------------------------------------------+
153
+
154
+
======================
155
+
PUD Page Table Helpers
156
+
======================
157
+
158
+
+---------------------------+--------------------------------------------------+
159
+
| pud_same | Tests whether both PUD entries are the same |
160
+
+---------------------------+--------------------------------------------------+
161
+
| pud_bad | Tests a non-table mapped PUD |
162
+
+---------------------------+--------------------------------------------------+
163
+
| pud_leaf | Tests a leaf mapped PUD |
164
+
+---------------------------+--------------------------------------------------+
165
+
| pud_huge | Tests a HugeTLB mapped PUD |
166
+
+---------------------------+--------------------------------------------------+
167
+
| pud_trans_huge | Tests a Transparent Huge Page (THP) at PUD |
168
+
+---------------------------+--------------------------------------------------+
169
+
| pud_present | Tests a valid mapped PUD |
170
+
+---------------------------+--------------------------------------------------+
171
+
| pud_young | Tests a young PUD |
172
+
+---------------------------+--------------------------------------------------+
173
+
| pud_dirty | Tests a dirty PUD |
174
+
+---------------------------+--------------------------------------------------+
175
+
| pud_write | Tests a writable PUD |
176
+
+---------------------------+--------------------------------------------------+
177
+
| pud_devmap | Tests a ZONE_DEVICE mapped PUD |
178
+
+---------------------------+--------------------------------------------------+
179
+
| pud_mkyoung | Creates a young PUD |
180
+
+---------------------------+--------------------------------------------------+
181
+
| pud_mkold | Creates an old PUD |
182
+
+---------------------------+--------------------------------------------------+
183
+
| pud_mkdirty | Creates a dirty PUD |
184
+
+---------------------------+--------------------------------------------------+
185
+
| pud_mkclean | Creates a clean PUD |
186
+
+---------------------------+--------------------------------------------------+
187
+
| pud_mkwrite | Creates a writable PUD |
188
+
+---------------------------+--------------------------------------------------+
189
+
| pud_mkwrprotect | Creates a write protected PUD |
190
+
+---------------------------+--------------------------------------------------+
191
+
| pud_mkdevmap | Creates a ZONE_DEVICE mapped PUD |
192
+
+---------------------------+--------------------------------------------------+
193
+
| pud_mkinvalid | Invalidates a mapped PUD [1] |
194
+
+---------------------------+--------------------------------------------------+
195
+
| pud_set_huge | Creates a PUD huge mapping |
196
+
+---------------------------+--------------------------------------------------+
197
+
| pud_clear_huge | Clears a PUD huge mapping |
198
+
+---------------------------+--------------------------------------------------+
199
+
| pudp_get_and_clear | Clears a PUD |
200
+
+---------------------------+--------------------------------------------------+
201
+
| pudp_get_and_clear_full | Clears a PUD |
202
+
+---------------------------+--------------------------------------------------+
203
+
| pudp_test_and_clear_young | Clears young from a PUD |
204
+
+---------------------------+--------------------------------------------------+
205
+
| pudp_set_wrprotect | Converts into a write protected PUD |
206
+
+---------------------------+--------------------------------------------------+
207
+
| pudp_set_access_flags | Converts into a more permissive PUD |
208
+
+---------------------------+--------------------------------------------------+
209
+
210
+
==========================
211
+
HugeTLB Page Table Helpers
212
+
==========================
213
+
214
+
+---------------------------+--------------------------------------------------+
215
+
| pte_huge | Tests a HugeTLB |
216
+
+---------------------------+--------------------------------------------------+
217
+
| pte_mkhuge | Creates a HugeTLB |
218
+
+---------------------------+--------------------------------------------------+
219
+
| huge_pte_dirty | Tests a dirty HugeTLB |
220
+
+---------------------------+--------------------------------------------------+
221
+
| huge_pte_write | Tests a writable HugeTLB |
222
+
+---------------------------+--------------------------------------------------+
223
+
| huge_pte_mkdirty | Creates a dirty HugeTLB |
224
+
+---------------------------+--------------------------------------------------+
225
+
| huge_pte_mkwrite | Creates a writable HugeTLB |
226
+
+---------------------------+--------------------------------------------------+
227
+
| huge_pte_mkwrprotect | Creates a write protected HugeTLB |
228
+
+---------------------------+--------------------------------------------------+
229
+
| huge_ptep_get_and_clear | Clears a HugeTLB |
230
+
+---------------------------+--------------------------------------------------+
231
+
| huge_ptep_set_wrprotect | Converts into a write protected HugeTLB |
232
+
+---------------------------+--------------------------------------------------+
233
+
| huge_ptep_set_access_flags | Converts into a more permissive HugeTLB |
234
+
+---------------------------+--------------------------------------------------+
235
+
236
+
========================
237
+
SWAP Page Table Helpers
238
+
========================
239
+
240
+
+---------------------------+--------------------------------------------------+
241
+
| __pte_to_swp_entry | Creates a swapped entry (arch) from a mapped PTE |
242
+
+---------------------------+--------------------------------------------------+
243
+
| __swp_to_pte_entry | Creates a mapped PTE from a swapped entry (arch) |
244
+
+---------------------------+--------------------------------------------------+
245
+
| __pmd_to_swp_entry | Creates a swapped entry (arch) from a mapped PMD |
246
+
+---------------------------+--------------------------------------------------+
247
+
| __swp_to_pmd_entry | Creates a mapped PMD from a swapped entry (arch) |
248
+
+---------------------------+--------------------------------------------------+
249
+
| is_migration_entry | Tests a migration (read or write) swapped entry |
250
+
+---------------------------+--------------------------------------------------+
251
+
| is_write_migration_entry | Tests a write migration swapped entry |
252
+
+---------------------------+--------------------------------------------------+
253
+
| make_migration_entry_read | Converts into read migration swapped entry |
254
+
+---------------------------+--------------------------------------------------+
255
+
| make_migration_entry | Creates a migration swapped entry (read or write)|
256
+
+---------------------------+--------------------------------------------------+
257
+
258
+
[1] https://lore.kernel.org/linux-mm/20181017020930.GN30832@redhat.com/
+6
mm/debug_vm_pgtable.c
+6
mm/debug_vm_pgtable.c
···
31
31
#include <asm/pgalloc.h>
32
32
#include <asm/tlbflush.h>
33
33
34
+
/*
35
+
* Please refer Documentation/vm/arch_pgtable_helpers.rst for the semantics
36
+
* expectations that are being validated here. All future changes in here
37
+
* or the documentation need to be in sync.
38
+
*/
39
+
34
40
#define VMFLAGS (VM_READ|VM_WRITE|VM_EXEC)
35
41
36
42
/*