Re: [PATCH man-pages v5] madvise.2: add MADV_GUARD_INSTALL, MADV_GUARD_REMOVE description

[Alejandro Colomar <alx@kernel.org>]

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

Hi Lorenzo,

On Fri, Dec 06, 2024 at 11:34:18AM GMT, Lorenzo Stoakes wrote:
> Lightweight guard region support has been added to Linux 6.13, which adds
> MADV_GUARD_INSTALL and MADV_GUARD_REMOVE flags to the madvise() system
> call. Therefore, update the manpage for madvise() and describe these
> operations.
> 
> Reviewed-by: Jann Horn <jannh@google.com>
> Reviewed-by: Vlastimil Babka <vbabka@suse.cz>
> Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>

Thanks for the updated patch.  I had already applied v4:
<https://lore.kernel.org/all/20241205104125.67518-1-lorenzo.stoakes@oracle.com/T/#m7a891296e1ade7025569e3c3595b4f288135a7a9>

> ---
> v5:
> * Prefer 'replaced' to 'cleared' when discussing existing mappings that have
>   MADV_GUARD_INSTALL applied to them, as suggested by Vlastimil.
> * Included small changes Alejandro applied to patch.

So I have now rebased v5 on top of the current tip of the branch, which
results in a small patch containing just the wording fix:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=28c42e01fc175e50e38d>

Have a lovely night!
Alex

> 
> v4:
> * Reference function chapters as per Alejandro.
> * Minor rewording as per Alejandro.
> https://lore.kernel.org/all/20241205104125.67518-1-lorenzo.stoakes@oracle.com
> 
> v3:
> * Don't describe SIGSEGV as a fatal signal as per Jann.
> https://lore.kernel.org/all/20241202165829.72121-1-lorenzo.stoakes@oracle.com
> 
> v2:
> * Updated to use semantic newlines as suggested by Alejandro.
> * Avoided emboldening parens as suggested by Alejandro.
> * One very minor grammatical fix.
> https://lore.kernel.org/all/20241129155943.85215-1-lorenzo.stoakes@oracle.com
> 
> v1:
> https://lore.kernel.org/all/20241129093205.8664-1-lorenzo.stoakes@oracle.com
> 
>  man/man2/madvise.2 | 103 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 103 insertions(+)
> 
> diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
> index 0dd481d21..c9b4722db 100644
> --- a/man/man2/madvise.2
> +++ b/man/man2/madvise.2
> @@ -676,6 +676,101 @@ or secret memory regions created using
>  Note that with
>  .BR MADV_POPULATE_WRITE ,
>  the process can be killed at any moment when the system runs out of memory.
> +.TP
> +.BR MADV_GUARD_INSTALL " (since Linux 6.13)"
> +Install a lightweight guard region
> +into the range specified by
> +.I addr
> +and
> +.IR size ,
> +causing any read or write in the range to result in a
> +.B SIGSEGV
> +signal being raised.
> +.IP
> +If the region maps memory pages
> +those mappings will be replaced
> +as part of the operation,
> +though if
> +.B MADV_GUARD_INSTALL
> +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.
> +An
> +.B EINVAL
> +error is returned if it is attempted on any other kind of mapping.
> +.IP
> +This operation is more efficient than mapping a new region of memory
> +.BR PROT_NONE ,
> +as it does not require the establishment of new mappings.
> +Instead,
> +regions of an existing mapping
> +simply have their page tables
> +manipulated to establish the desired behavior.
> +No additional memory is used.
> +.IP
> +Lightweight guard regions remain on fork
> +(except for any parts which have had
> +.B MADV_WIPEONFORK
> +applied to them),
> +and are not removed by
> +.BR MADV_DONTNEED ,
> +.BR MADV_FREE ,
> +.BR MADV_PAGEOUT ,
> +or
> +.BR MADV_COLD .
> +.IP
> +Attempting to
> +.BR mlock (2)
> +lightweight guard regions will fail,
> +as will
> +.B MADV_POPULATE_READ
> +or
> +.BR MADV_POPULATE_WRITE .
> +.IP
> +If the mapping has its attributes changed,
> +or is split or partially unmapped,
> +any existing guard regions remain in place
> +(except if they are unmapped).
> +.IP
> +If a mapping is moved using
> +.BR mremap (2),
> +lightweight guard regions are moved with it.
> +.IP
> +Lightweight guard regions are removed when unmapped,
> +on process teardown,
> +or when the
> +.B MADV_GUARD_REMOVE
> +operation is applied to them.
> +.TP
> +.BR MADV_GUARD_REMOVE " (since Linux 6.13)"
> +Remove any lightweight guard regions
> +which exist in the range specified by
> +.I addr
> +and
> +.IR size .
> +.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,
> +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.
> +.IP
> +If any transparent huge pages are encountered in the operation,
> +they are left in place.
>  .SH RETURN VALUE
>  On success,
>  .BR madvise ()
> @@ -794,6 +889,14 @@ or
>  or secret memory regions created using
>  .BR memfd_secret(2) .
>  .TP
> +.B EINVAL
> +.I advice
> +is
> +.B MADV_GUARD_INSTALL
> +or
> +.BR MADV_GUARD_REMOVE ,
> +but the specified address range contains an unsupported mapping.
> +.TP
>  .B EIO
>  (for
>  .BR MADV_WILLNEED )
> --
> 2.47.1

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

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