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: <ea8c2be9-0af0-445b-b7fe-fd9e80bd6a65@lucifer.local>
Date: Tue, 3 Jun 2025 15:24:23 +0100
From: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
To: Jonathan Corbet <corbet@....net>
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

On Tue, Jun 03, 2025 at 08:08:22AM -0600, Jonathan Corbet wrote:
> 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.

I can go change that.

But to repeat - 'given C's weirdness with typing I really prefer to be
explicit in referencing a struct vs. e.g. a typedef.'

I'm not doing this with an intent of Sphix misuse, it's with intent of
being as clear as possible.

>
> 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?

Because it apparently requires me to document every function I reference?
Unless I'm missing something?

I may be misunderstanding you.

If not then fine, I can delay this patch, go off and do a 'cleanup' patch
first, that will drop the '!'s and come back to this.

But if I need to document every referenced function that just isn't
feasible for me with my current workload.

Please clarify!

>
> Thanks,
>
> jon