Re: [PATCH man-pages v3 1/4] madvise.2: update THP file/shmem documentation for +5.4

["Zach O'Keefe" <zokeefe@google.com>]

On Sun, Oct 30, 2022 at 4:42 AM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi Zach!
>
> On 10/22/22 00:32, Zach OKeefe wrote:
> > From: Zach O'Keefe <zokeefe@google.com>
> >
> > Since Linux 5.4, Transparent Huge Pages now support both file-backed
> > memory and shmem memory. Update MADV_HUGEPAGE advice description to
> > reflect this.
> >
> > Additionally, expand the description of requirements for memory to be
> > considered eligible for THP: alignment / mapping requirements, VMA
> > flags, prctl(2) settings, inode status, etc.
> >
> > Signed-off-by: Zach O'Keefe <zokeefe@google.com>
>
> Patch applied!  Thanks.
> Since you were interested, I amended it with the following diff:
>
>
> diff --git a/man2/madvise.2 b/man2/madvise.2
> index 64f788ace..48bda703c 100644
> --- a/man2/madvise.2
> +++ b/man2/madvise.2
> @@ -361,9 +361,10 @@ .SS Linux-specific advice values
>   and file-backed pages.
>   For all memory types,
>   memory may only be replaced by huge pages on hugepage-aligned boundaries.
> -For file-mapped memory \(em including tmpfs (see
> -.BR tmpfs (2))
> -\(em the mapping must also be naturally hugepage-aligned within the file.
> +For file-mapped memory
> +\(emincluding tmpfs (see
> +.BR tmpfs (2))\(em
> +the mapping must also be naturally hugepage-aligned within the file.
>   Additionally,
>   for file-backed,
>   non-tmpfs memory,
> @@ -382,7 +383,7 @@ .SS Linux-specific advice values
>   The process must also not have
>   .B PR_SET_THP_DISABLE
>   set (see
> -.BR prctl (2) ).
> +.BR prctl (2)).
>   .IP
>   The
>   .B MADV_HUGEPAGE
>
>
> - The em dashes you used were correct with spaces in both sides; there are those
> who use them with spaces in both sides and those who use them with no spaces at
> all.  And then there are those who put spaces as if they were parentheses
> (admittedly this is much less common).  I prefer this latter case, since it
> makes technical texts more parseable.
>
> - I used a semantic newline break for the em dashes, since they are similar to a
> coma.
>
> - Removed a spurious space in BR that would have made the formatting weird.
>
> Cheers,
>

Thanks for taking the patch, and thanks for taking the time with the
explanation! Glad I wasn't *too* far off :)

Changes look good to me - thank you!

Best,
Zach

> Alex
>
>
> > ---
> >   man2/madvise.2 | 38 +++++++++++++++++++++++++++++++++++---
> >   1 file changed, 35 insertions(+), 3 deletions(-)
> >
> > diff --git a/man2/madvise.2 b/man2/madvise.2
> > index 81cce56af..64f788ace 100644
> > --- a/man2/madvise.2
> > +++ b/man2/madvise.2
> > @@ -320,8 +320,6 @@ Enable Transparent Huge Pages (THP) for pages in the range specified by
> >   .I addr
> >   and
> >   .IR length .
> > -Currently, Transparent Huge Pages work only with private anonymous pages (see
> > -.BR mmap (2)).
> >   The kernel will regularly scan the areas marked as huge page candidates
> >   to replace them with huge pages.
> >   The kernel will also allocate huge pages directly when the region is
> > @@ -354,12 +352,46 @@ an access pattern that the developer knows in advance won't risk
> >   to increase the memory footprint of the application when transparent
> >   hugepages are enabled.
> >   .IP
> > +.\" commit 99cb0dbd47a15d395bf3faa78dc122bc5efe3fc0
> > +Since Linux 5.4,
> > +automatic scan of eligible areas and replacement by huge pages works with
> > +private anonymous pages (see
> > +.BR mmap (2)),
> > +shmem pages,
> > +and file-backed pages.
> > +For all memory types,
> > +memory may only be replaced by huge pages on hugepage-aligned boundaries.
> > +For file-mapped memory \(em including tmpfs (see
> > +.BR tmpfs (2))
> > +\(em the mapping must also be naturally hugepage-aligned within the file.
> > +Additionally,
> > +for file-backed,
> > +non-tmpfs memory,
> > +the file must not be open for write and the mapping must be executable.
> > +.IP
> > +The VMA must not be marked
> > +.BR VM_NOHUGEPAGE ,
> > +.BR VM_HUGETLB ,
> > +.BR VM_IO ,
> > +.BR VM_DONTEXPAND ,
> > +.BR VM_MIXEDMAP ,
> > +or
> > +.BR VM_PFNMAP ,
> > +nor can it be stack memory or backed by a DAX-enabled device
> > +(unless the DAX device is hot-plugged as System RAM).
> > +The process must also not have
> > +.B PR_SET_THP_DISABLE
> > +set (see
> > +.BR prctl (2) ).
> > +.IP
> >   The
> >   .B MADV_HUGEPAGE
> >   and
> >   .B MADV_NOHUGEPAGE
> >   operations are available only if the kernel was configured with
> > -.BR CONFIG_TRANSPARENT_HUGEPAGE .
> > +.B CONFIG_TRANSPARENT_HUGEPAGE
> > +and file/shmem memory is only supported if the kernel was configured with
> > +.BR CONFIG_READ_ONLY_THP_FOR_FS .
> >   .TP
> >   .BR MADV_NOHUGEPAGE " (since Linux 2.6.38)"
> >   Ensures that memory in the address range specified by
>
> --
> <http://www.alejandro-colomar.es/>