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

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

On Fri, Nov 29, 2024 at 01:35:01PM +0100, Alejandro Colomar wrote:
> Hi Lorenzo,
>
> On Fri, Nov 29, 2024 at 09:32:05AM +0000, 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.
> >
> > Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
>
> Thanks for the patch.  Please see some comments below.

Ack will fix up and respin!

>
> Have a lovely day!

You too! Thanks for taking the time to look :)

> Alex
>
> > ---
> >  man/man2/madvise.2 | 81 ++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 81 insertions(+)
> >
> > diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
> > index 4f2210ee2..e539fefe4 100644
> > --- a/man/man2/madvise.2
> > +++ b/man/man2/madvise.2
> > @@ -676,6 +676,79 @@ 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 fatal
> > +.B SIGSEGV
> > +signal being raised.
> > +.IP
> > +If the region maps memory pages they will be cleared 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.
>
> Please use semantic newlines.  See man-pages(7):
>
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p';
>    Use semantic newlines
>        In the source of a manual page, new sentences should be started
>        on new lines, long sentences should  be  split  into  lines  at
>        clause breaks (commas, semicolons, colons, and so on), and long
>        clauses should be split at phrase boundaries.  This convention,
>        sometimes  known as "semantic newlines", makes it easier to see
>        the effect of patches, which often operate at the level of  in‐
>        dividual sentences, clauses, or phrases.
>
>
> > +.IP
> > +This operation is only supported 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
> > +.B mlock()
> > +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 any are unmapped).
> > +.IP
> > +If a mapping is moved using
> > +.BR mremap() ,
>
> The "()" should not be bold.  They should go with the ','.
>
> > +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, only valid 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 ()
> > @@ -787,6 +860,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/>