Documentation/mm/arch_pgtable_helpers.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============================
   4 Architecture Page Table Helpers
   5 ===============================
   6
   7 Generic MM expects architectures (with MMU) to provide helpers to create, access
   8 and modify page table entries at various level for different memory functions.
   9 These page table helpers need to conform to a common semantics across platforms.
  10 Following tables describe the expected semantics which can also be tested during
  11 boot via CONFIG_DEBUG_VM_PGTABLE option. All future changes in here or the debug
  12 test need to be in sync.
  13
  14
  15 PTE Page Table Helpers
  16 ======================
  17
  18 +---------------------------+--------------------------------------------------+
  19 | pte_same                  | Tests whether both PTE entries are the same      |
  20 +---------------------------+--------------------------------------------------+
  21 | pte_present               | Tests a valid mapped PTE                         |
  22 +---------------------------+--------------------------------------------------+
  23 | pte_young                 | Tests a young PTE                                |
  24 +---------------------------+--------------------------------------------------+
  25 | pte_dirty                 | Tests a dirty PTE                                |
  26 +---------------------------+--------------------------------------------------+
  27 | pte_write                 | Tests a writable PTE                             |
  28 +---------------------------+--------------------------------------------------+
  29 | pte_special               | Tests a special PTE                              |
  30 +---------------------------+--------------------------------------------------+
  31 | pte_protnone              | Tests a PROT_NONE PTE                            |
  32 +---------------------------+--------------------------------------------------+
  33 | pte_devmap                | Tests a ZONE_DEVICE mapped PTE                   |
  34 +---------------------------+--------------------------------------------------+
  35 | pte_soft_dirty            | Tests a soft dirty PTE                           |
  36 +---------------------------+--------------------------------------------------+
  37 | pte_swp_soft_dirty        | Tests a soft dirty swapped PTE                   |
  38 +---------------------------+--------------------------------------------------+
  39 | pte_mkyoung               | Creates a young PTE                              |
  40 +---------------------------+--------------------------------------------------+
  41 | pte_mkold                 | Creates an old PTE                               |
  42 +---------------------------+--------------------------------------------------+
  43 | pte_mkdirty               | Creates a dirty PTE                              |
  44 +---------------------------+--------------------------------------------------+
  45 | pte_mkclean               | Creates a clean PTE                              |
  46 +---------------------------+--------------------------------------------------+
  47 | pte_mkwrite               | Creates a writable PTE of the type specified by  |
  48 |                           | the VMA.                                         |
  49 +---------------------------+--------------------------------------------------+
  50 | pte_mkwrite_novma         | Creates a writable PTE, of the conventional type |
  51 |                           | of writable.                                     |
  52 +---------------------------+--------------------------------------------------+
  53 | pte_wrprotect             | 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_clear                | Clears a PTE                                     |
  70 +---------------------------+--------------------------------------------------+
  71 | ptep_get_and_clear        | Clears and returns PTE                           |
  72 +---------------------------+--------------------------------------------------+
  73 | ptep_get_and_clear_full   | Clears and returns PTE (batched PTE unmap)       |
  74 +---------------------------+--------------------------------------------------+
  75 | ptep_test_and_clear_young | Clears young from a PTE                          |
  76 +---------------------------+--------------------------------------------------+
  77 | ptep_set_wrprotect        | Converts into a write protected PTE              |
  78 +---------------------------+--------------------------------------------------+
  79 | ptep_set_access_flags     | Converts into a more permissive PTE              |
  80 +---------------------------+--------------------------------------------------+
  81
  82
  83 PMD Page Table Helpers
  84 ======================
  85
  86 +---------------------------+--------------------------------------------------+
  87 | pmd_same                  | Tests whether both PMD entries are the same      |
  88 +---------------------------+--------------------------------------------------+
  89 | pmd_bad                   | Tests a non-table mapped PMD                     |
  90 +---------------------------+--------------------------------------------------+
  91 | pmd_leaf                  | Tests a leaf mapped PMD                          |
  92 +---------------------------+--------------------------------------------------+
  93 | pmd_trans_huge            | Tests a Transparent Huge Page (THP) at PMD       |
  94 +---------------------------+--------------------------------------------------+
  95 | pmd_present               | Tests whether pmd_page() points to valid memory  |
  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 of the type specified by  |
 122 |                           | the VMA.                                         |
 123 +---------------------------+--------------------------------------------------+
 124 | pmd_mkwrite_novma         | Creates a writable PMD, of the conventional type |
 125 |                           | of writable.                                     |
 126 +---------------------------+--------------------------------------------------+
 127 | pmd_wrprotect             | Creates a write protected PMD                    |
 128 +---------------------------+--------------------------------------------------+
 129 | pmd_mkspecial             | Creates a special PMD                            |
 130 +---------------------------+--------------------------------------------------+
 131 | pmd_mkdevmap              | Creates a ZONE_DEVICE mapped PMD                 |
 132 +---------------------------+--------------------------------------------------+
 133 | pmd_mksoft_dirty          | Creates a soft dirty PMD                         |
 134 +---------------------------+--------------------------------------------------+
 135 | pmd_clear_soft_dirty      | Clears a soft dirty PMD                          |
 136 +---------------------------+--------------------------------------------------+
 137 | pmd_swp_mksoft_dirty      | Creates a soft dirty swapped PMD                 |
 138 +---------------------------+--------------------------------------------------+
 139 | pmd_swp_clear_soft_dirty  | Clears a soft dirty swapped PMD                  |
 140 +---------------------------+--------------------------------------------------+
 141 | pmd_mkinvalid             | Invalidates a present PMD; do not call for       |
 142 |                           | non-present PMD [1]                              |
 143 +---------------------------+--------------------------------------------------+
 144 | pmd_set_huge              | Creates a PMD huge mapping                       |
 145 +---------------------------+--------------------------------------------------+
 146 | pmd_clear_huge            | Clears a PMD huge mapping                        |
 147 +---------------------------+--------------------------------------------------+
 148 | pmdp_get_and_clear        | Clears a PMD                                     |
 149 +---------------------------+--------------------------------------------------+
 150 | pmdp_get_and_clear_full   | Clears a PMD                                     |
 151 +---------------------------+--------------------------------------------------+
 152 | pmdp_test_and_clear_young | Clears young from a PMD                          |
 153 +---------------------------+--------------------------------------------------+
 154 | pmdp_set_wrprotect        | Converts into a write protected PMD              |
 155 +---------------------------+--------------------------------------------------+
 156 | pmdp_set_access_flags     | Converts into a more permissive PMD              |
 157 +---------------------------+--------------------------------------------------+
 158
 159
 160 PUD Page Table Helpers
 161 ======================
 162
 163 +---------------------------+--------------------------------------------------+
 164 | pud_same                  | Tests whether both PUD entries are the same      |
 165 +---------------------------+--------------------------------------------------+
 166 | pud_bad                   | Tests a non-table mapped PUD                     |
 167 +---------------------------+--------------------------------------------------+
 168 | pud_leaf                  | Tests a leaf mapped PUD                          |
 169 +---------------------------+--------------------------------------------------+
 170 | pud_trans_huge            | Tests a Transparent Huge Page (THP) at PUD       |
 171 +---------------------------+--------------------------------------------------+
 172 | pud_present               | Tests a valid mapped PUD                         |
 173 +---------------------------+--------------------------------------------------+
 174 | pud_young                 | Tests a young PUD                                |
 175 +---------------------------+--------------------------------------------------+
 176 | pud_dirty                 | Tests a dirty PUD                                |
 177 +---------------------------+--------------------------------------------------+
 178 | pud_write                 | Tests a writable PUD                             |
 179 +---------------------------+--------------------------------------------------+
 180 | pud_devmap                | Tests a ZONE_DEVICE mapped PUD                   |
 181 +---------------------------+--------------------------------------------------+
 182 | pud_mkyoung               | Creates a young PUD                              |
 183 +---------------------------+--------------------------------------------------+
 184 | pud_mkold                 | Creates an old PUD                               |
 185 +---------------------------+--------------------------------------------------+
 186 | pud_mkdirty               | Creates a dirty PUD                              |
 187 +---------------------------+--------------------------------------------------+
 188 | pud_mkclean               | Creates a clean PUD                              |
 189 +---------------------------+--------------------------------------------------+
 190 | pud_mkwrite               | Creates a writable PUD                           |
 191 +---------------------------+--------------------------------------------------+
 192 | pud_wrprotect             | Creates a write protected PUD                    |
 193 +---------------------------+--------------------------------------------------+
 194 | pud_mkdevmap              | Creates a ZONE_DEVICE mapped PUD                 |
 195 +---------------------------+--------------------------------------------------+
 196 | pud_mkinvalid             | Invalidates a present PUD; do not call for       |
 197 |                           | non-present PUD [1]                              |
 198 +---------------------------+--------------------------------------------------+
 199 | pud_set_huge              | Creates a PUD huge mapping                       |
 200 +---------------------------+--------------------------------------------------+
 201 | pud_clear_huge            | Clears a PUD huge mapping                        |
 202 +---------------------------+--------------------------------------------------+
 203 | pudp_get_and_clear        | Clears a PUD                                     |
 204 +---------------------------+--------------------------------------------------+
 205 | pudp_get_and_clear_full   | Clears a PUD                                     |
 206 +---------------------------+--------------------------------------------------+
 207 | pudp_test_and_clear_young | Clears young from a PUD                          |
 208 +---------------------------+--------------------------------------------------+
 209 | pudp_set_wrprotect        | Converts into a write protected PUD              |
 210 +---------------------------+--------------------------------------------------+
 211 | pudp_set_access_flags     | Converts into a more permissive PUD              |
 212 +---------------------------+--------------------------------------------------+
 213
 214
 215 HugeTLB Page Table Helpers
 216 ==========================
 217
 218 +---------------------------+--------------------------------------------------+
 219 | pte_huge                  | Tests a HugeTLB                                  |
 220 +---------------------------+--------------------------------------------------+
 221 | arch_make_huge_pte        | Creates a HugeTLB                                |
 222 +---------------------------+--------------------------------------------------+
 223 | huge_pte_dirty            | Tests a dirty HugeTLB                            |
 224 +---------------------------+--------------------------------------------------+
 225 | huge_pte_write            | Tests a writable HugeTLB                         |
 226 +---------------------------+--------------------------------------------------+
 227 | huge_pte_mkdirty          | Creates a dirty HugeTLB                          |
 228 +---------------------------+--------------------------------------------------+
 229 | huge_pte_mkwrite          | Creates a writable HugeTLB                       |
 230 +---------------------------+--------------------------------------------------+
 231 | huge_pte_wrprotect        | Creates a write protected HugeTLB                |
 232 +---------------------------+--------------------------------------------------+
 233 | huge_ptep_get_and_clear   | Clears a HugeTLB                                 |
 234 +---------------------------+--------------------------------------------------+
 235 | huge_ptep_set_wrprotect   | Converts into a write protected HugeTLB          |
 236 +---------------------------+--------------------------------------------------+
 237 | huge_ptep_set_access_flags  | Converts into a more permissive HugeTLB        |
 238 +---------------------------+--------------------------------------------------+
 239
 240
 241 SWAP Page Table Helpers
 242 ========================
 243
 244 +---------------------------+--------------------------------------------------+
 245 | __pte_to_swp_entry        | Creates a swapped entry (arch) from a mapped PTE |
 246 +---------------------------+--------------------------------------------------+
 247 | __swp_to_pte_entry        | Creates a mapped PTE from a swapped entry (arch) |
 248 +---------------------------+--------------------------------------------------+
 249 | __pmd_to_swp_entry        | Creates a swapped entry (arch) from a mapped PMD |
 250 +---------------------------+--------------------------------------------------+
 251 | __swp_to_pmd_entry        | Creates a mapped PMD from a swapped entry (arch) |
 252 +---------------------------+--------------------------------------------------+
 253 | is_migration_entry        | Tests a migration (read or write) swapped entry  |
 254 +-------------------------------+----------------------------------------------+
 255 | is_writable_migration_entry   | Tests a write migration swapped entry        |
 256 +-------------------------------+----------------------------------------------+
 257 | make_readable_migration_entry | Creates a read migration swapped entry       |
 258 +-------------------------------+----------------------------------------------+
 259 | make_writable_migration_entry | Creates a write migration swapped entry      |
 260 +-------------------------------+----------------------------------------------+
 261
 262 [1] https://lore.kernel.org/linux-mm/20181017020930.GN30832@redhat.com/