linux-kernel - Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing, non-vma traversal

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: <8734cg9auh.fsf@trenco.lwn.net>
Date: Tue, 03 Jun 2025 08:08:22 -0600
From: Jonathan Corbet <corbet@....net>
To: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
Cc: Andrew Morton <akpm@...ux-foundation.org>, Suren Baghdasaryan
 <surenb@...gle.com>, "Liam R . Howlett" <Liam.Howlett@...cle.com>,
 Vlastimil Babka <vbabka@...e.cz>, Shakeel Butt <shakeel.butt@...ux.dev>,
 Jann Horn <jannh@...gle.com>, Qi Zheng <zhengqi.arch@...edance.com>,
 linux-mm@...ck.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing,
 non-vma traversal

Lorenzo Stoakes <lorenzo.stoakes@...cle.com> writes:

> On Mon, Jun 02, 2025 at 03:38:55PM -0600, Jonathan Corbet wrote:
>> Lorenzo Stoakes <lorenzo.stoakes@...cle.com> writes:
>>
>> > --- a/Documentation/mm/process_addrs.rst
>> > +++ b/Documentation/mm/process_addrs.rst
>> > @@ -303,7 +303,9 @@ 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
>> >     establishes this suffices for traversal (there are also lockless variants
>> > -   which eliminate even this requirement, such as :c:func:`!gup_fast`).
>> > +   which eliminate even this requirement, such as :c:func:`!gup_fast`). There is
>> > +   also a special case of page table traversal for non-VMA regions which we
>>
>> The "!gup_fast" caught my attention - I was unaware that Sphinx had such
>> a thing.  Its purpose would be to appear to suppress the generation of the
>> link that turns the cross reference into a cross reference.
>>
>> The MM docs are full of these, do we know why?
>
> Removing it from the struct vm_area_struct struct immediately give:
>
> /home/lorenzo/kerndev/kernels/mm/Documentation/mm/process_addrs.rst:11: WARNING: Unparseable C cross-reference: 'struct vm_area_struct'
> Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
>   struct vm_area_struct
>
> And given C's weirdness with typing I really prefer to be explicit in
> referencing a struct vs. e.g. a typedef.

That's because the :c:struct: markup doesn't want the word "struct" in
there.  In this case, the "!" is being used, essentially, to hide the
fact that the Sphinx markup is being entirely misused here.  You would
be far better off just saying:

  **struct vm_area_struct**

and avoiding the uglier markup in this case.

Once again, taking out the markup entirely will cause the automarkup
code to do the right thing, with the proviso that undocumented
structures (which, tragically, includes struct vm_area_struct) won't be
marked up in the current implementation.  By far the best solution here
is to remove all of the markup and add a kerneldoc comment for this
rather important structure.

> At any rate I'm not sure it's all that useful to cross-reference these?

Why would you *not* want to cross-reference something and make life easier
for your reader?

Thanks,

jon