Documentation/admin-guide/mm/pagemap.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/mm/pagemap.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/mm/pagemap.rst
Extension
.rst
Size
13014 bytes
Lines
318
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=============================
Examining Process Page Tables
=============================

pagemap is a new (as of 2.6.25) set of interfaces in the kernel that allow
userspace programs to examine the page tables and related information by
reading files in ``/proc``.

There are four components to pagemap:

 * ``/proc/pid/pagemap``.  This file lets a userspace process find out which
   physical frame each virtual page is mapped to.  It contains one 64-bit
   value for each virtual page, containing the following data (from
   ``fs/proc/task_mmu.c``, above pagemap_read):

    * Bits 0-54  page frame number (PFN) if present
    * Bits 0-4   swap type if swapped
    * Bits 5-54  swap offset if swapped
    * Bit  55    pte is soft-dirty (see
      Documentation/admin-guide/mm/soft-dirty.rst)
    * Bit  56    page exclusively mapped (since 4.2)
    * Bit  57    pte is uffd-wp write-protected (since 5.13) (see
      Documentation/admin-guide/mm/userfaultfd.rst)
    * Bit  58    pte is a guard region (since 6.15) (see madvise (2) man page)
    * Bits 59-60 zero
    * Bit  61    page is file-page or shared-anon (since 3.5)
    * Bit  62    page swapped
    * Bit  63    page present

   Since Linux 4.0 only users with the CAP_SYS_ADMIN capability can get PFNs.
   In 4.0 and 4.1 opens by unprivileged fail with -EPERM.  Starting from
   4.2 the PFN field is zeroed if the user does not have CAP_SYS_ADMIN.
   Reason: information about PFNs helps in exploiting Rowhammer vulnerability.

   If the page is not present but in swap, then the PFN contains an
   encoding of the swap file number and the page's offset into the
   swap. Unmapped pages return a null PFN. This allows determining
   precisely which pages are mapped (or in swap) and comparing mapped
   pages between processes.

   Traditionally, bit 56 indicates that a page is mapped exactly once and bit
   56 is clear when a page is mapped multiple times, even when mapped in the
   same process multiple times. In some kernel configurations, the semantics
   for pages part of a larger allocation (e.g., THP) can differ: bit 56 is set
   if all pages part of the corresponding large allocation are *certainly*
   mapped in the same process, even if the page is mapped multiple times in that
   process. Bit 56 is clear when any page page of the larger allocation
   is *maybe* mapped in a different process. In some cases, a large allocation
   might be treated as "maybe mapped by multiple processes" even though this
   is no longer the case.

   Efficient users of this interface will use ``/proc/pid/maps`` to
   determine which areas of memory are actually mapped and llseek to
   skip over unmapped regions.

 * ``/proc/kpagecount``.  This file contains a 64-bit count of the number of
   times each page is mapped, indexed by PFN. Some kernel configurations do
   not track the precise number of times a page part of a larger allocation
   (e.g., THP) is mapped. In these configurations, the average number of
   mappings per page in this larger allocation is returned instead. However,
   if any page of the large allocation is mapped, the returned value will
   be at least 1.

The page-types tool in the tools/mm directory can be used to query the
number of times a page is mapped.

 * ``/proc/kpageflags``.  This file contains a 64-bit set of flags for each
   page, indexed by PFN.

   The flags are (from ``fs/proc/page.c``, above kpageflags_read):

Annotation

Implementation Notes