[PATCH v2] madvise.2: update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[PATCH v2] madvise.2: update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Lorenzo Stoakes]

Lightweight guard region support has been extended in Linux 6.15,
permitting the use of these features for file-backed and read-only
mappings.

Update the description for these operations in the madvise manpage to
describe the changed behaviour.

Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
---
v2:
(all as per Alejandro :)
* Removed v prefixes on linux version numbers.
* Removed invalid blank line.
* Various style and layout fixups.

v1:
https://lore.kernel.org/all/20250317210653.273728-1-lorenzo.stoakes@oracle.com/

 man/man2/madvise.2 | 39 +++++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 10 deletions(-)

diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
index bd2b90b7a..be1ba17ae 100644
--- a/man/man2/madvise.2
+++ b/man/man2/madvise.2
@@ -697,9 +697,24 @@ is applied to regions
 containing pre-existing lightweight guard regions,
 they are left in place.
 .IP
-This operation is supported
-only for writable anonymous private mappings
-which have not been mlock'd.
+Prior to Linux 6.15,
+this operation was supported
+only for writable anonymous private mappings.
+Since Linux 6.15,
+both anonymous and file-backed mappings are supported,
+including read-only mappings.
+.IP
+The mapping must not be mlock'd,
+map hugetlb ranges,
+nor contain special mappings.
+For example,
+mappings marked with kernel-internal flags such as
+.B VM_PFNMAP
+or
+.BR VM_IO ,
+or secret memory regions created using
+.BR memfd_secret (2).
+.IP
 An
 .B EINVAL
 error is returned if it is attempted on any other kind of mapping.
@@ -756,19 +771,23 @@ and
 .IP
 All mappings in the range
 other than lightweight guard regions
-are left in place
-(including mlock'd mappings).
-The operation is,
-however,
-valid only for writable anonymous private mappings,
+are left in place.
+The operation is supported on those mappings
+permitted by
+.B MADV_GUARD_INSTALL
+in addition to mlock()'d mappings,
 returning an
 .B EINVAL
 error otherwise.
 .IP
 When lightweight guard regions are removed,
 they act as empty regions of the containing mapping.
-Since only writable anonymous private mappings are supported,
-they therefore become zero-fill-on-demand pages.
+Therefore,
+anonymous private mappings become
+zero-fill-on-demand pages,
+and file-backed mappings are repopulated with the
+memory contents from the up-to-date contents of the
+underlying mapped file.
 .IP
 If any transparent huge pages are encountered in the operation,
 they are left in place.
--
2.49.0

Re: [PATCH v2] madvise.2: update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Lorenzo Stoakes]

Hey Alejandro,

Just a gentle ping on this :) Let me know if you need me to do anything
else on this!

Cheers, Lorenzo

On Wed, Apr 23, 2025 at 07:31:05PM +0100, Lorenzo Stoakes wrote:
> Lightweight guard region support has been extended in Linux 6.15,
> permitting the use of these features for file-backed and read-only
> mappings.
>
> Update the description for these operations in the madvise manpage to
> describe the changed behaviour.
>
> Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> ---
> v2:
> (all as per Alejandro :)
> * Removed v prefixes on linux version numbers.
> * Removed invalid blank line.
> * Various style and layout fixups.
>
> v1:
> https://lore.kernel.org/all/20250317210653.273728-1-lorenzo.stoakes@oracle.com/
>
>  man/man2/madvise.2 | 39 +++++++++++++++++++++++++++++----------
>  1 file changed, 29 insertions(+), 10 deletions(-)
>
> diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
> index bd2b90b7a..be1ba17ae 100644
> --- a/man/man2/madvise.2
> +++ b/man/man2/madvise.2
> @@ -697,9 +697,24 @@ is applied to regions
>  containing pre-existing lightweight guard regions,
>  they are left in place.
>  .IP
> -This operation is supported
> -only for writable anonymous private mappings
> -which have not been mlock'd.
> +Prior to Linux 6.15,
> +this operation was supported
> +only for writable anonymous private mappings.
> +Since Linux 6.15,
> +both anonymous and file-backed mappings are supported,
> +including read-only mappings.
> +.IP
> +The mapping must not be mlock'd,
> +map hugetlb ranges,
> +nor contain special mappings.
> +For example,
> +mappings marked with kernel-internal flags such as
> +.B VM_PFNMAP
> +or
> +.BR VM_IO ,
> +or secret memory regions created using
> +.BR memfd_secret (2).
> +.IP
>  An
>  .B EINVAL
>  error is returned if it is attempted on any other kind of mapping.
> @@ -756,19 +771,23 @@ and
>  .IP
>  All mappings in the range
>  other than lightweight guard regions
> -are left in place
> -(including mlock'd mappings).
> -The operation is,
> -however,
> -valid only for writable anonymous private mappings,
> +are left in place.
> +The operation is supported on those mappings
> +permitted by
> +.B MADV_GUARD_INSTALL
> +in addition to mlock()'d mappings,
>  returning an
>  .B EINVAL
>  error otherwise.
>  .IP
>  When lightweight guard regions are removed,
>  they act as empty regions of the containing mapping.
> -Since only writable anonymous private mappings are supported,
> -they therefore become zero-fill-on-demand pages.
> +Therefore,
> +anonymous private mappings become
> +zero-fill-on-demand pages,
> +and file-backed mappings are repopulated with the
> +memory contents from the up-to-date contents of the
> +underlying mapped file.
>  .IP
>  If any transparent huge pages are encountered in the operation,
>  they are left in place.
> --
> 2.49.0

Re: [PATCH v2] madvise.2: update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 913 bytes --]

Hey Lorenzo!

On Thu, May 01, 2025 at 10:53:51AM +0100, Lorenzo Stoakes wrote:
> Hey Alejandro,
> 
> Just a gentle ping on this :) Let me know if you need me to do anything
> else on this!

Sorry for being slow; I was on a family trip.  :-)


I've applied your patch.  It was all good.  I've only slightly tweaked
the commit message subject line:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=9ee66d0b01dfc797c57b4735fd48c138f97a66d2>

	man/man2/madvise.2: Update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE for Linux 6.15

I added the info that it's about Linux 6.15, to see it without having to
read the entire message, and also used the full path of the page (I
changed that recently for all commits).  (Plus also start with uppercase
after the ':'.)

> Cheers, Lorenzo


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] madvise.2: update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Lorenzo Stoakes]

On Thu, May 01, 2025 at 01:14:59PM +0200, Alejandro Colomar wrote:
> Hey Lorenzo!
>
> On Thu, May 01, 2025 at 10:53:51AM +0100, Lorenzo Stoakes wrote:
> > Hey Alejandro,
> >
> > Just a gentle ping on this :) Let me know if you need me to do anything
> > else on this!
>
> Sorry for being slow; I was on a family trip.  :-)

Ah no worries at all obviously, hope you had a great time! :)

>
>
> I've applied your patch.  It was all good.  I've only slightly tweaked
> the commit message subject line:
>
> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=9ee66d0b01dfc797c57b4735fd48c138f97a66d2>
>
> 	man/man2/madvise.2: Update MADV_GUARD_INSTALL, MADV_GUARD_REMOVE for Linux 6.15
>
> I added the info that it's about Linux 6.15, to see it without having to
> read the entire message, and also used the full path of the page (I
> changed that recently for all commits).  (Plus also start with uppercase
> after the ':'.)

Perfect thanks so much! And those changes sound fine!

>
> > Cheers, Lorenzo
>
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>

Cheers, Lorenzo