Received-SPF: pass (google.com: domain of linux-kernel+bounces-98349-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
Date: Sun, 10 Mar 2024 22:14:04 +0000
From: Lorenzo Stoakes <lstoakes@gmail.com>
To: Richard Weinberger <richard@nod.at>
Cc: linux-mm@kvack.org, linux-fsdevel@vger.kernel.org,
	linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
	upstream+pagemap@sigma-star.at, adobriyan@gmail.com,
	wangkefeng.wang@huawei.com, ryan.roberts@arm.com, hughd@google.com,
	peterx@redhat.com, david@redhat.com, avagin@google.com,
	vbabka@suse.cz, akpm@linux-foundation.org,
	usama.anjum@collabora.com, corbet@lwn.net
Subject: Re: [PATCH 2/2] [RFC] pagemap.rst: Document write bit
Message-ID: <Ze4wrHL6DEQJl_Oo@devil>
References: <20240306232339.29659-1-richard@nod.at>
 <20240306232339.29659-2-richard@nod.at>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20240306232339.29659-2-richard@nod.at>

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
>