Re: [PATCH v2] docs/mm: add VMA locks documentation

[Lorenzo Stoakes <lorenzo.stoakes@oracle.com>]

On Fri, Nov 08, 2024 at 01:57:06PM +0000, Lorenzo Stoakes wrote:
> Locking around VMAs is complicated and confusing. While we have a number of
> disparate comments scattered around the place, we seem to be reaching a
> level of complexity that justifies a serious effort at clearly documenting
> how locks are expected to be used when it comes to interacting with
> mm_struct and vm_area_struct objects.
>
> This is especially pertinent as regards the efforts to find sensible
> abstractions for these fundamental objects in kernel rust code whose
> compiler strictly requires some means of expressing these rules (and
> through this expression, self-document these requirements as well as
> enforce them).
>
> The document limits scope to mmap and VMA locks and those that are
> immediately adjacent and relevant to them - so additionally covers page
> table locking as this is so very closely tied to VMA operations (and relies
> upon us handling these correctly).
>
> The document tries to cover some of the nastier and more confusing edge
> cases and concerns especially around lock ordering and page table teardown.
>
> The document is split between generally useful information for users of mm
> interfaces, and separately a section intended for mm kernel developers
> providing a discussion around internal implementation details.
>
> Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>

Hi Andrew,

As Murphy's law so often dictates, I noticed a few small mistakes moments
after sending the patch... :)

I enclose a fix-patch to correct these, basically a typo and some small
prose fixes.

I have also updated https://ljs.io/v2/mm/process_addrs to reflect this.

Thanks, Lorenzo

----8<----
From 11d47b63e5b3a631741c663257f0f9051585f3b3 Mon Sep 17 00:00:00 2001
From: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Date: Sat, 9 Nov 2024 15:52:55 +0000
Subject: [PATCH] docs/mm: minor corrections

Rename a section to avoid confusion with the address_space type, fix a typo, and
reword a mangled sentence.

Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
---
 Documentation/mm/process_addrs.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/mm/process_addrs.rst b/Documentation/mm/process_addrs.rst
index 5aef4fd0e0e9..ed74685ffbf2 100644
--- a/Documentation/mm/process_addrs.rst
+++ b/Documentation/mm/process_addrs.rst
@@ -68,8 +68,8 @@ described below).

 Stabilising a VMA also keeps the address space described by it around.

-Using address space locks
--------------------------
+Lock usage
+----------

 If you want to **read** VMA metadata fields or just keep the VMA stable, you
 must do one of the following:
@@ -291,7 +291,7 @@ typically refer to the leaf level as the PTE level regardless.
 	  compiler might, in practice, eliminate any code relating to missing
 	  ones.

-There are free key operations typically performed on page tables:
+There are four key operations typically performed on page tables:

 1. **Traversing** page tables - Simply reading page tables in order to traverse
    them. This only requires that the VMA is kept stable, so a lock which
@@ -513,11 +513,11 @@ When performing a page table traversal and keeping the VMA stable, whether a
 read must be performed once and only once or not depends on the architecture
 (for instance x86-64 does not require any special precautions).

-It is on the write side, or if a read informs whether a write takes place (on an
-installation of a page table entry say, for instance in
-:c:func:`!__pud_install`), where special care must always be taken. In these
-cases we can never assume that page table locks give us entirely exclusive
-access, and must retrieve page table entries once and only once.
+If a write is being performed, or if a read informs whether a write takes place
+(on an installation of a page table entry say, for instance in
+:c:func:`!__pud_install`), special care must always be taken. In these cases we
+can never assume that page table locks give us entirely exclusive access, and
+must retrieve page table entries once and only once.

 If we are reading page table entries, then we need only ensure that the compiler
 does not rearrange our loads. This is achieved via :c:func:`!pXXp_get`
--
2.47.0