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

[Jonathan Corbet <corbet@lwn.net>]

Lorenzo Stoakes <lorenzo.stoakes@oracle.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?

I would recommend removing them unless there's some reason I don't see
for doing this.  Also get rid of the :c:func: noise entirely - just
saying gup_fast() will do the right thing.

> +.. note:: Since v6.14 and commit 6375e95f381e ("mm: pgtable: reclaim empty
> PTE + page in madvise (MADV_DONTNEED)"), we now also free empty PTE tables
> + on zap. This does not change zapping locking requirements.

As a general rule, the docs should represent the current state of
affairs; people wanting documentation for older kernels are best advised
to look at those kernels.  Or so it seems to me, anyway.  So I'm not
sure we need the "since..." stuff.

Thanks,

jon