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_huge                  | Tests a HugeTLB mapped PMD                       |
  94 +---------------------------+--------------------------------------------------+
  95 | pmd_trans_huge            | Tests a Transparent Huge Page (THP) at PMD       |
  96 +---------------------------+--------------------------------------------------+
  97 | pmd_present               | Tests whether pmd_page() points to valid memory  |
  98 +---------------------------+--------------------------------------------------+
  99 | pmd_young                 | Tests a young PMD                                |
 100 +---------------------------+--------------------------------------------------+
 101 | pmd_dirty                 | Tests a dirty PMD                                |
 102 +---------------------------+--------------------------------------------------+
 103 | pmd_write                 | Tests a writable PMD                             |
 104 +---------------------------+--------------------------------------------------+
 105 | pmd_special               | Tests a special PMD                              |
 106 +---------------------------+--------------------------------------------------+
 107 | pmd_protnone              | Tests a PROT_NONE PMD                            |
 108 +---------------------------+--------------------------------------------------+
 109 | pmd_devmap                | Tests a ZONE_DEVICE mapped PMD                   |
 110 +---------------------------+--------------------------------------------------+
 111 | pmd_soft_dirty            | Tests a soft dirty PMD                           |
 112 +---------------------------+--------------------------------------------------+
 113 | pmd_swp_soft_dirty        | Tests a soft dirty swapped PMD                   |
 114 +---------------------------+--------------------------------------------------+
 115 | pmd_mkyoung               | Creates a young PMD                              |
 116 +---------------------------+--------------------------------------------------+
 117 | pmd_mkold                 | Creates an old PMD                               |
 118 +---------------------------+--------------------------------------------------+
 119 | pmd_mkdirty               | Creates a dirty PMD                              |
 120 +---------------------------+--------------------------------------------------+
 121 | pmd_mkclean               | Creates a clean PMD                              |
 122 +---------------------------+--------------------------------------------------+
 123 | pmd_mkwrite               | Creates a writable PMD of the type specified by  |
 124 |                           | the VMA.                                         |
 125 +---------------------------+--------------------------------------------------+
 126 | pmd_mkwrite_novma         | Creates a writable PMD, of the conventional type |
 127 |                           | of writable.                                     |
 128 +---------------------------+--------------------------------------------------+
 129 | pmd_wrprotect             | Creates a write protected PMD                    |
 130 +---------------------------+--------------------------------------------------+
 131 | pmd_mkspecial             | Creates a special PMD                            |
 132 +---------------------------+--------------------------------------------------+
 133 | pmd_mkdevmap              | Creates a ZONE_DEVICE mapped PMD                 |
 134 +---------------------------+--------------------------------------------------+
 135 | pmd_mksoft_dirty          | Creates a soft dirty PMD                         |
 136 +---------------------------+--------------------------------------------------+
 137 | pmd_clear_soft_dirty      | Clears a soft dirty PMD                          |
 138 +---------------------------+--------------------------------------------------+
 139 | pmd_swp_mksoft_dirty      | Creates a soft dirty swapped PMD                 |
 140 +---------------------------+--------------------------------------------------+
 141 | pmd_swp_clear_soft_dirty  | Clears a soft dirty swapped PMD                  |
 142 +---------------------------+--------------------------------------------------+
 143 | pmd_mkinvalid             | Invalidates a mapped PMD [1]                     |
 144 +---------------------------+--------------------------------------------------+
 145 | pmd_set_huge              | Creates a PMD huge mapping                       |
 146 +---------------------------+--------------------------------------------------+
 147 | pmd_clear_huge            | Clears a PMD huge mapping                        |
 148 +---------------------------+--------------------------------------------------+
 149 | pmdp_get_and_clear        | Clears a PMD                                     |
 150 +---------------------------+--------------------------------------------------+
 151 | pmdp_get_and_clear_full   | Clears a PMD                                     |
 152 +---------------------------+--------------------------------------------------+
 153 | pmdp_test_and_clear_young | Clears young from a PMD                          |
 154 +---------------------------+--------------------------------------------------+
 155 | pmdp_set_wrprotect        | Converts into a write protected PMD              |
 156 +---------------------------+--------------------------------------------------+
 157 | pmdp_set_access_flags     | Converts into a more permissive PMD              |
 158 +---------------------------+--------------------------------------------------+
 159
 160
 161 PUD Page Table Helpers
 162 ======================
 163
 164 +---------------------------+--------------------------------------------------+
 165 | pud_same                  | Tests whether both PUD entries are the same      |
 166 +---------------------------+--------------------------------------------------+
 167 | pud_bad                   | Tests a non-table mapped PUD                     |
 168 +---------------------------+--------------------------------------------------+
 169 | pud_leaf                  | Tests a leaf mapped PUD                          |
 170 +---------------------------+--------------------------------------------------+
 171 | pud_huge                  | Tests a HugeTLB mapped PUD                       |
 172 +---------------------------+--------------------------------------------------+
 173 | pud_trans_huge            | Tests a Transparent Huge Page (THP) at PUD       |
 174 +---------------------------+--------------------------------------------------+
 175 | pud_present               | Tests a valid mapped PUD                         |
 176 +---------------------------+--------------------------------------------------+
 177 | pud_young                 | Tests a young PUD                                |
 178 +---------------------------+--------------------------------------------------+
 179 | pud_dirty                 | Tests a dirty PUD                                |
 180 +---------------------------+--------------------------------------------------+
 181 | pud_write                 | Tests a writable PUD                             |
 182 +---------------------------+--------------------------------------------------+
 183 | pud_devmap                | Tests a ZONE_DEVICE mapped PUD                   |
 184 +---------------------------+--------------------------------------------------+
 185 | pud_mkyoung               | Creates a young PUD                              |
 186 +---------------------------+--------------------------------------------------+
 187 | pud_mkold                 | Creates an old PUD                               |
 188 +---------------------------+--------------------------------------------------+
 189 | pud_mkdirty               | Creates a dirty PUD                              |
 190 +---------------------------+--------------------------------------------------+
 191 | pud_mkclean               | Creates a clean PUD                              |
 192 +---------------------------+--------------------------------------------------+
 193 | pud_mkwrite               | Creates a writable PUD                           |
 194 +---------------------------+--------------------------------------------------+
 195 | pud_wrprotect             | Creates a write protected PUD                    |
 196 +---------------------------+--------------------------------------------------+
 197 | pud_mkdevmap              | Creates a ZONE_DEVICE mapped PUD                 |
 198 +---------------------------+--------------------------------------------------+
 199 | pud_mkinvalid             | Invalidates a mapped PUD [1]                     |
 200 +---------------------------+--------------------------------------------------+
 201 | pud_set_huge              | Creates a PUD huge mapping                       |
 202 +---------------------------+--------------------------------------------------+
 203 | pud_clear_huge            | Clears a PUD huge mapping                        |
 204 +---------------------------+--------------------------------------------------+
 205 | pudp_get_and_clear        | Clears a PUD                                     |
 206 +---------------------------+--------------------------------------------------+
 207 | pudp_get_and_clear_full   | Clears a PUD                                     |
 208 +---------------------------+--------------------------------------------------+
 209 | pudp_test_and_clear_young | Clears young from a PUD                          |
 210 +---------------------------+--------------------------------------------------+
 211 | pudp_set_wrprotect        | Converts into a write protected PUD              |
 212 +---------------------------+--------------------------------------------------+
 213 | pudp_set_access_flags     | Converts into a more permissive PUD              |
 214 +---------------------------+--------------------------------------------------+
 215
 216
 217 HugeTLB Page Table Helpers
 218 ==========================
 219
 220 +---------------------------+--------------------------------------------------+
 221 | pte_huge                  | Tests a HugeTLB                                  |
 222 +---------------------------+--------------------------------------------------+
 223 | arch_make_huge_pte        | Creates a HugeTLB                                |
 224 +---------------------------+--------------------------------------------------+
 225 | huge_pte_dirty            | Tests a dirty HugeTLB                            |
 226 +---------------------------+--------------------------------------------------+
 227 | huge_pte_write            | Tests a writable HugeTLB                         |
 228 +---------------------------+--------------------------------------------------+
 229 | huge_pte_mkdirty          | Creates a dirty HugeTLB                          |
 230 +---------------------------+--------------------------------------------------+
 231 | huge_pte_mkwrite          | Creates a writable HugeTLB                       |
 232 +---------------------------+--------------------------------------------------+
 233 | huge_pte_wrprotect        | Creates a write protected HugeTLB                |
 234 +---------------------------+--------------------------------------------------+
 235 | huge_ptep_get_and_clear   | Clears a HugeTLB                                 |
 236 +---------------------------+--------------------------------------------------+
 237 | huge_ptep_set_wrprotect   | Converts into a write protected HugeTLB          |
 238 +---------------------------+--------------------------------------------------+
 239 | huge_ptep_set_access_flags  | Converts into a more permissive HugeTLB        |
 240 +---------------------------+--------------------------------------------------+
 241
 242
 243 SWAP Page Table Helpers
 244 ========================
 245
 246 +---------------------------+--------------------------------------------------+
 247 | __pte_to_swp_entry        | Creates a swapped entry (arch) from a mapped PTE |
 248 +---------------------------+--------------------------------------------------+
 249 | __swp_to_pte_entry        | Creates a mapped PTE from a swapped entry (arch) |
 250 +---------------------------+--------------------------------------------------+
 251 | __pmd_to_swp_entry        | Creates a swapped entry (arch) from a mapped PMD |
 252 +---------------------------+--------------------------------------------------+
 253 | __swp_to_pmd_entry        | Creates a mapped PMD from a swapped entry (arch) |
 254 +---------------------------+--------------------------------------------------+
 255 | is_migration_entry        | Tests a migration (read or write) swapped entry  |
 256 +-------------------------------+----------------------------------------------+
 257 | is_writable_migration_entry   | Tests a write migration swapped entry        |
 258 +-------------------------------+----------------------------------------------+
 259 | make_readable_migration_entry | Creates a read migration swapped entry       |
 260 +-------------------------------+----------------------------------------------+
 261 | make_writable_migration_entry | Creates a write migration swapped entry      |
 262 +-------------------------------+----------------------------------------------+
 263
 264 [1] https://lore.kernel.org/linux-mm/20181017020930.GN30832@redhat.com/