Re: [PATCH 2/2] [RFC] pagemap.rst: Document write bit

[Lorenzo Stoakes <lstoakes@gmail.com>]

On Thu, Mar 07, 2024 at 12:23:39AM +0100, Richard Weinberger wrote:
> Bit 58 denotes that a PTE is writable.
> The main use case is detecting CoW mappings.
>
> Signed-off-by: Richard Weinberger <richard@nod.at>
> ---
>  Documentation/admin-guide/mm/pagemap.rst | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst
> index f5f065c67615..81ffe3601b96 100644
> --- a/Documentation/admin-guide/mm/pagemap.rst
> +++ b/Documentation/admin-guide/mm/pagemap.rst
> @@ -21,7 +21,8 @@ There are four components to pagemap:
>      * 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)
> -    * Bits 58-60 zero
> +    * Bit  58    pte is writable (since 6.10)

I really think we need to be careful about talking about 'writable' again
because people are easily confused about the difference between a writable
_mapping_ and a writable _page table entry_.

Of course you mention PTE here, but I think it might be better to say
something like:

    * Bit  58    raw pte r/w flag (since 6.10)

> +    * Bits 59-60 zero
>      * Bit  61    page is file-page or shared-anon (since 3.5)
>      * Bit  62    page swapped
>      * Bit  63    page present
> @@ -37,6 +38,11 @@ There are four components to pagemap:
>     precisely which pages are mapped (or in swap) and comparing mapped
>     pages between processes.
>
> +   Bit 58 is useful to detect CoW mappings; however, it does not indicate
> +   whether the page mapping is writable or not. If an anonymous mapping is
> +   writable but the write bit is not set, it means that the next write access
> +   will cause a page fault, and copy-on-write will happen.
> +

David has addressed the copy vs. anon exclusive remap issue, but I also
feel this needs some balking out.

I would simply rephrase this in terms of whether a write fault occurs or
not e.g.:

   Bit 58 indicates whether the PTE has the write flag set. If this flag is
   unset, then write accesses for this mapping will cause a fault for this
   page. If the mapping is private (whether anonymous or file-backed), this
   can result in a Copy-on-Write (though if anonymous-excusive the flag
   will simply be set). If file-backed, this being cleared may simply
   indicate that this file page is clean.

>     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.
> --
> 2.35.3
>