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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <d3de735a-25ae-4eb2-866c-a9624fe6f795@lucifer.local>
Date: Sat, 9 Nov 2024 16:01:46 +0000
From: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
To: Andrew Morton <akpm@...ux-foundation.org>,
        Jonathan Corbet <corbet@....net>
Cc: "Liam R . Howlett" <Liam.Howlett@...cle.com>,
        Vlastimil Babka <vbabka@...e.cz>, Jann Horn <jannh@...gle.com>,
        Alice Ryhl <aliceryhl@...gle.com>, Boqun Feng <boqun.feng@...il.com>,
        Matthew Wilcox <willy@...radead.org>, Mike Rapoport <rppt@...nel.org>,
        linux-mm@...ck.org, linux-kernel@...r.kernel.org,
        linux-doc@...r.kernel.org, Suren Baghdasaryan <surenb@...gle.com>,
        Hillf Danton <hdanton@...a.com>, Qi Zheng <zhengqi.arch@...edance.com>,
        SeongJae Park <sj@...nel.org>, Bagas Sanjaya <bagasdotme@...il.com>
Subject: Re: [PATCH v2] docs/mm: add VMA locks documentation

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@...cle.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@...cle.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@...cle.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