diff mbox series

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

Message ID 20221021223300.3675201-2-zokeefe@google.com (mailing list archive)
State New
Headers show
Series Add MADV_COLLAPSE documentation | expand

Commit Message

Zach O'Keefe Oct. 21, 2022, 10:32 p.m. UTC 
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>
---
 man2/madvise.2 | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

Comments

Alejandro Colomar Oct. 30, 2022, 11:41 a.m. UTC | #1 
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,

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
Zach O'Keefe Oct. 31, 2022, 4:33 p.m. UTC | #2 
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/>
Alejandro Colomar Oct. 31, 2022, 8:11 p.m. UTC | #3 
Hi Zach!

On 10/31/22 17:33, Zach O'Keefe wrote:
> 
> Thanks for taking the patch, and thanks for taking the time with the
> explanation! Glad I wasn't *too* far off :)

:)

BTW, I just documented the linters that are available in the build system.
It would have caught an issue an patch 2/4 that I didn't (although it requires a 
yet-unreleased groff version; so it won't be available to general public until 
it is released in a few months).
You may want to run it in future patches ;)

I'll tell more about it in the thread for 2/4

> 
> Changes look good to me - thank you!

Cheers,
Alex
diff mbox series

Patch

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