11ad1335dSMike Rapoport.. _pagemap: 21ad1335dSMike Rapoport 31ad1335dSMike Rapoport============================= 41ad1335dSMike RapoportExamining Process Page Tables 51ad1335dSMike Rapoport============================= 61ad1335dSMike Rapoport 71ad1335dSMike Rapoportpagemap is a new (as of 2.6.25) set of interfaces in the kernel that allow 81ad1335dSMike Rapoportuserspace programs to examine the page tables and related information by 91ad1335dSMike Rapoportreading files in ``/proc``. 101ad1335dSMike Rapoport 111ad1335dSMike RapoportThere are four components to pagemap: 121ad1335dSMike Rapoport 131ad1335dSMike Rapoport * ``/proc/pid/pagemap``. This file lets a userspace process find out which 141ad1335dSMike Rapoport physical frame each virtual page is mapped to. It contains one 64-bit 151ad1335dSMike Rapoport value for each virtual page, containing the following data (from 161ad1335dSMike Rapoport ``fs/proc/task_mmu.c``, above pagemap_read): 171ad1335dSMike Rapoport 181ad1335dSMike Rapoport * Bits 0-54 page frame number (PFN) if present 191ad1335dSMike Rapoport * Bits 0-4 swap type if swapped 201ad1335dSMike Rapoport * Bits 5-54 swap offset if swapped 21e27a20f1SMike Rapoport * Bit 55 pte is soft-dirty (see 22e27a20f1SMike Rapoport :ref:`Documentation/admin-guide/mm/soft-dirty.rst <soft_dirty>`) 231ad1335dSMike Rapoport * Bit 56 page exclusively mapped (since 4.2) 24fb8e37f3SPeter Xu * Bit 57 pte is uffd-wp write-protected (since 5.13) (see 25fb8e37f3SPeter Xu :ref:`Documentation/admin-guide/mm/userfaultfd.rst <userfaultfd>`) 261ad1335dSMike Rapoport * Bits 57-60 zero 271ad1335dSMike Rapoport * Bit 61 page is file-page or shared-anon (since 3.5) 281ad1335dSMike Rapoport * Bit 62 page swapped 291ad1335dSMike Rapoport * Bit 63 page present 301ad1335dSMike Rapoport 311ad1335dSMike Rapoport Since Linux 4.0 only users with the CAP_SYS_ADMIN capability can get PFNs. 321ad1335dSMike Rapoport In 4.0 and 4.1 opens by unprivileged fail with -EPERM. Starting from 331ad1335dSMike Rapoport 4.2 the PFN field is zeroed if the user does not have CAP_SYS_ADMIN. 341ad1335dSMike Rapoport Reason: information about PFNs helps in exploiting Rowhammer vulnerability. 351ad1335dSMike Rapoport 361ad1335dSMike Rapoport If the page is not present but in swap, then the PFN contains an 371ad1335dSMike Rapoport encoding of the swap file number and the page's offset into the 381ad1335dSMike Rapoport swap. Unmapped pages return a null PFN. This allows determining 391ad1335dSMike Rapoport precisely which pages are mapped (or in swap) and comparing mapped 401ad1335dSMike Rapoport pages between processes. 411ad1335dSMike Rapoport 421ad1335dSMike Rapoport Efficient users of this interface will use ``/proc/pid/maps`` to 431ad1335dSMike Rapoport determine which areas of memory are actually mapped and llseek to 441ad1335dSMike Rapoport skip over unmapped regions. 451ad1335dSMike Rapoport 461ad1335dSMike Rapoport * ``/proc/kpagecount``. This file contains a 64-bit count of the number of 471ad1335dSMike Rapoport times each page is mapped, indexed by PFN. 481ad1335dSMike Rapoport 497f1d23e6SChristian HansenThe page-types tool in the tools/vm directory can be used to query the 507f1d23e6SChristian Hansennumber of times a page is mapped. 517f1d23e6SChristian Hansen 521ad1335dSMike Rapoport * ``/proc/kpageflags``. This file contains a 64-bit set of flags for each 531ad1335dSMike Rapoport page, indexed by PFN. 541ad1335dSMike Rapoport 551ad1335dSMike Rapoport The flags are (from ``fs/proc/page.c``, above kpageflags_read): 561ad1335dSMike Rapoport 571ad1335dSMike Rapoport 0. LOCKED 581ad1335dSMike Rapoport 1. ERROR 591ad1335dSMike Rapoport 2. REFERENCED 601ad1335dSMike Rapoport 3. UPTODATE 611ad1335dSMike Rapoport 4. DIRTY 621ad1335dSMike Rapoport 5. LRU 631ad1335dSMike Rapoport 6. ACTIVE 641ad1335dSMike Rapoport 7. SLAB 651ad1335dSMike Rapoport 8. WRITEBACK 661ad1335dSMike Rapoport 9. RECLAIM 671ad1335dSMike Rapoport 10. BUDDY 681ad1335dSMike Rapoport 11. MMAP 691ad1335dSMike Rapoport 12. ANON 701ad1335dSMike Rapoport 13. SWAPCACHE 711ad1335dSMike Rapoport 14. SWAPBACKED 721ad1335dSMike Rapoport 15. COMPOUND_HEAD 731ad1335dSMike Rapoport 16. COMPOUND_TAIL 741ad1335dSMike Rapoport 17. HUGE 751ad1335dSMike Rapoport 18. UNEVICTABLE 761ad1335dSMike Rapoport 19. HWPOISON 771ad1335dSMike Rapoport 20. NOPAGE 781ad1335dSMike Rapoport 21. KSM 791ad1335dSMike Rapoport 22. THP 80ca215086SDavid Hildenbrand 23. OFFLINE 811ad1335dSMike Rapoport 24. ZERO_PAGE 821ad1335dSMike Rapoport 25. IDLE 83ca215086SDavid Hildenbrand 26. PGTABLE 841ad1335dSMike Rapoport 851ad1335dSMike Rapoport * ``/proc/kpagecgroup``. This file contains a 64-bit inode number of the 861ad1335dSMike Rapoport memory cgroup each page is charged to, indexed by PFN. Only available when 871ad1335dSMike Rapoport CONFIG_MEMCG is set. 881ad1335dSMike Rapoport 891ad1335dSMike RapoportShort descriptions to the page flags 901ad1335dSMike Rapoport==================================== 911ad1335dSMike Rapoport 921ad1335dSMike Rapoport0 - LOCKED 931ad1335dSMike Rapoport page is being locked for exclusive access, e.g. by undergoing read/write IO 941ad1335dSMike Rapoport7 - SLAB 951ad1335dSMike Rapoport page is managed by the SLAB/SLOB/SLUB/SLQB kernel memory allocator 961ad1335dSMike Rapoport When compound page is used, SLUB/SLQB will only set this flag on the head 971ad1335dSMike Rapoport page; SLOB will not flag it at all. 981ad1335dSMike Rapoport10 - BUDDY 991ad1335dSMike Rapoport a free memory block managed by the buddy system allocator 1001ad1335dSMike Rapoport The buddy system organizes free memory in blocks of various orders. 1011ad1335dSMike Rapoport An order N block has 2^N physically contiguous pages, with the BUDDY flag 1021ad1335dSMike Rapoport set for and _only_ for the first page. 1031ad1335dSMike Rapoport15 - COMPOUND_HEAD 1041ad1335dSMike Rapoport A compound page with order N consists of 2^N physically contiguous pages. 1051ad1335dSMike Rapoport A compound page with order 2 takes the form of "HTTT", where H donates its 1061ad1335dSMike Rapoport head page and T donates its tail page(s). The major consumers of compound 107e27a20f1SMike Rapoport pages are hugeTLB pages 108e27a20f1SMike Rapoport (:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`), 109e27a20f1SMike Rapoport the SLUB etc. memory allocators and various device drivers. 110e27a20f1SMike Rapoport However in this interface, only huge/giga pages are made visible 111e27a20f1SMike Rapoport to end users. 1121ad1335dSMike Rapoport16 - COMPOUND_TAIL 1131ad1335dSMike Rapoport A compound page tail (see description above). 1141ad1335dSMike Rapoport17 - HUGE 1151ad1335dSMike Rapoport this is an integral part of a HugeTLB page 1161ad1335dSMike Rapoport19 - HWPOISON 1171ad1335dSMike Rapoport hardware detected memory corruption on this page: don't touch the data! 1181ad1335dSMike Rapoport20 - NOPAGE 1191ad1335dSMike Rapoport no page frame exists at the requested address 1201ad1335dSMike Rapoport21 - KSM 1211ad1335dSMike Rapoport identical memory pages dynamically shared between one or more processes 1221ad1335dSMike Rapoport22 - THP 1231ad1335dSMike Rapoport contiguous pages which construct transparent hugepages 124ca215086SDavid Hildenbrand23 - OFFLINE 125ca215086SDavid Hildenbrand page is logically offline 1261ad1335dSMike Rapoport24 - ZERO_PAGE 1271ad1335dSMike Rapoport zero page for pfn_zero or huge_zero page 1281ad1335dSMike Rapoport25 - IDLE 1291ad1335dSMike Rapoport page has not been accessed since it was marked idle (see 130e27a20f1SMike Rapoport :ref:`Documentation/admin-guide/mm/idle_page_tracking.rst <idle_page_tracking>`). 131e27a20f1SMike Rapoport Note that this flag may be stale in case the page was accessed via 132e27a20f1SMike Rapoport a PTE. To make sure the flag is up-to-date one has to read 133e27a20f1SMike Rapoport ``/sys/kernel/mm/page_idle/bitmap`` first. 134ca215086SDavid Hildenbrand26 - PGTABLE 135ca215086SDavid Hildenbrand page is in use as a page table 1361ad1335dSMike Rapoport 1371ad1335dSMike RapoportIO related page flags 1381ad1335dSMike Rapoport--------------------- 1391ad1335dSMike Rapoport 1401ad1335dSMike Rapoport1 - ERROR 1411ad1335dSMike Rapoport IO error occurred 1421ad1335dSMike Rapoport3 - UPTODATE 1431ad1335dSMike Rapoport page has up-to-date data 1441ad1335dSMike Rapoport ie. for file backed page: (in-memory data revision >= on-disk one) 1451ad1335dSMike Rapoport4 - DIRTY 1461ad1335dSMike Rapoport page has been written to, hence contains new data 1471ad1335dSMike Rapoport i.e. for file backed page: (in-memory data revision > on-disk one) 1481ad1335dSMike Rapoport8 - WRITEBACK 1491ad1335dSMike Rapoport page is being synced to disk 1501ad1335dSMike Rapoport 1511ad1335dSMike RapoportLRU related page flags 1521ad1335dSMike Rapoport---------------------- 1531ad1335dSMike Rapoport 1541ad1335dSMike Rapoport5 - LRU 1551ad1335dSMike Rapoport page is in one of the LRU lists 1561ad1335dSMike Rapoport6 - ACTIVE 1571ad1335dSMike Rapoport page is in the active LRU list 1581ad1335dSMike Rapoport18 - UNEVICTABLE 1591ad1335dSMike Rapoport page is in the unevictable (non-)LRU list It is somehow pinned and 1601ad1335dSMike Rapoport not a candidate for LRU page reclaims, e.g. ramfs pages, 1611ad1335dSMike Rapoport shmctl(SHM_LOCK) and mlock() memory segments 1621ad1335dSMike Rapoport2 - REFERENCED 1631ad1335dSMike Rapoport page has been referenced since last LRU list enqueue/requeue 1641ad1335dSMike Rapoport9 - RECLAIM 1651ad1335dSMike Rapoport page will be reclaimed soon after its pageout IO completed 1661ad1335dSMike Rapoport11 - MMAP 1671ad1335dSMike Rapoport a memory mapped page 1681ad1335dSMike Rapoport12 - ANON 1691ad1335dSMike Rapoport a memory mapped page that is not part of a file 1701ad1335dSMike Rapoport13 - SWAPCACHE 1711ad1335dSMike Rapoport page is mapped to swap space, i.e. has an associated swap entry 1721ad1335dSMike Rapoport14 - SWAPBACKED 1731ad1335dSMike Rapoport page is backed by swap/RAM 1741ad1335dSMike Rapoport 1751ad1335dSMike RapoportThe page-types tool in the tools/vm directory can be used to query the 1761ad1335dSMike Rapoportabove flags. 1771ad1335dSMike Rapoport 1781ad1335dSMike RapoportUsing pagemap to do something useful 1791ad1335dSMike Rapoport==================================== 1801ad1335dSMike Rapoport 1811ad1335dSMike RapoportThe general procedure for using pagemap to find out about a process' memory 1821ad1335dSMike Rapoportusage goes like this: 1831ad1335dSMike Rapoport 1841ad1335dSMike Rapoport 1. Read ``/proc/pid/maps`` to determine which parts of the memory space are 1851ad1335dSMike Rapoport mapped to what. 1861ad1335dSMike Rapoport 2. Select the maps you are interested in -- all of them, or a particular 1871ad1335dSMike Rapoport library, or the stack or the heap, etc. 1881ad1335dSMike Rapoport 3. Open ``/proc/pid/pagemap`` and seek to the pages you would like to examine. 1891ad1335dSMike Rapoport 4. Read a u64 for each page from pagemap. 1901ad1335dSMike Rapoport 5. Open ``/proc/kpagecount`` and/or ``/proc/kpageflags``. For each PFN you 1911ad1335dSMike Rapoport just read, seek to that entry in the file, and read the data you want. 1921ad1335dSMike Rapoport 1931ad1335dSMike RapoportFor example, to find the "unique set size" (USS), which is the amount of 1941ad1335dSMike Rapoportmemory that a process is using that is not shared with any other process, 1951ad1335dSMike Rapoportyou can go through every map in the process, find the PFNs, look those up 1961ad1335dSMike Rapoportin kpagecount, and tally up the number of pages that are only referenced 1971ad1335dSMike Rapoportonce. 1981ad1335dSMike Rapoport 199*cbbb69d3STiberiu A GeorgescuExceptions for Shared Memory 200*cbbb69d3STiberiu A Georgescu============================ 201*cbbb69d3STiberiu A Georgescu 202*cbbb69d3STiberiu A GeorgescuPage table entries for shared pages are cleared when the pages are zapped or 203*cbbb69d3STiberiu A Georgescuswapped out. This makes swapped out pages indistinguishable from never-allocated 204*cbbb69d3STiberiu A Georgescuones. 205*cbbb69d3STiberiu A Georgescu 206*cbbb69d3STiberiu A GeorgescuIn kernel space, the swap location can still be retrieved from the page cache. 207*cbbb69d3STiberiu A GeorgescuHowever, values stored only on the normal PTE get lost irretrievably when the 208*cbbb69d3STiberiu A Georgescupage is swapped out (i.e. SOFT_DIRTY). 209*cbbb69d3STiberiu A Georgescu 210*cbbb69d3STiberiu A GeorgescuIn user space, whether the page is present, swapped or none can be deduced with 211*cbbb69d3STiberiu A Georgescuthe help of lseek and/or mincore system calls. 212*cbbb69d3STiberiu A Georgescu 213*cbbb69d3STiberiu A Georgesculseek() can differentiate between accessed pages (present or swapped out) and 214*cbbb69d3STiberiu A Georgescuholes (none/non-allocated) by specifying the SEEK_DATA flag on the file where 215*cbbb69d3STiberiu A Georgescuthe pages are backed. For anonymous shared pages, the file can be found in 216*cbbb69d3STiberiu A Georgescu``/proc/pid/map_files/``. 217*cbbb69d3STiberiu A Georgescu 218*cbbb69d3STiberiu A Georgescumincore() can differentiate between pages in memory (present, including swap 219*cbbb69d3STiberiu A Georgescucache) and out of memory (swapped out or none/non-allocated). 220*cbbb69d3STiberiu A Georgescu 2211ad1335dSMike RapoportOther notes 2221ad1335dSMike Rapoport=========== 2231ad1335dSMike Rapoport 2241ad1335dSMike RapoportReading from any of the files will return -EINVAL if you are not starting 2251ad1335dSMike Rapoportthe read on an 8-byte boundary (e.g., if you sought an odd number of bytes 2261ad1335dSMike Rapoportinto the file), or if the size of the read is not a multiple of 8 bytes. 2271ad1335dSMike Rapoport 2281ad1335dSMike RapoportBefore Linux 3.11 pagemap bits 55-60 were used for "page-shift" (which is 2291ad1335dSMike Rapoportalways 12 at most architectures). Since Linux 3.11 their meaning changes 2301ad1335dSMike Rapoportafter first clear of soft-dirty bits. Since Linux 4.2 they are used for 2311ad1335dSMike Rapoportflags unconditionally. 232