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

[Lorenzo Stoakes <lorenzo.stoakes@oracle.com>]

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