On Mon, Jul 28, 2025 at 10:34:07PM +0200, Jann Horn wrote: > On Mon, Jul 28, 2025 at 4:05 PM Lorenzo Stoakes > <lorenzo.stoakes@xxxxxxxxxx> wrote: > > Document the new behaviour introduced in Linux 6.17 whereby it is now > > possible to move multiple mappings in a single operation, as long as the > > operation is purely a move, that is old_size is equal to new_size and > > MREMAP_FIXED is specified. > > > > To make things clearer, also describe this 'pure move' operation, before > > expanding upon it to describe the newly introduced behaviour. > > > > This change also explains the limitations of of this method and the > > possibility of partial failure. > > > > Finally, we pluralise language where it makes sense to so the documentation > > does not contradict either this new capability nor the pre-existing edge > > case. > > > > Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> > > --- > > man/man2/mremap.2 | 78 ++++++++++++++++++++++++++++++++++++++++------- > > 1 file changed, 67 insertions(+), 11 deletions(-) > > > > diff --git a/man/man2/mremap.2 b/man/man2/mremap.2 > > index 2168ca728..cb3412591 100644 > > --- a/man/man2/mremap.2 > > +++ b/man/man2/mremap.2 > > @@ -25,18 +25,41 @@ moving it at the same time (controlled by the > > argument and > > the available virtual address space). > > .P > > +Mappings can simply be moved by specifying equal > > (Bikeshedding: This "simply" sounds weird to me. If you're trying to > define a "simple move" with this, the rest of this block is not very > specific about what exactly that is supposed to be. In my opinion, > "pure" would also be a nicer word than "simple" if you're looking for > an expression that means "a move that doesn't do other things".) Will rephrase, the intent is that I'm saying we can 'simply' perform the 'only move'. > > > +.I old_size > > +and > > +.I new_size > > +and specifying > > +.IR new_address , > > +see the description of > > +.B MREMAP_FIXED > > +below. > > +Since Linux 6.17, > > +while > > +.I old_address > > +must reside within a mapping, > > +.I old_size > > +may span multiple mappings > > +which do not have to be > > +adjacent to one another. > > +.P > > +If the operation is not a simple move > > +then > > +.I old_size > > +must span only a single mapping. > > I'm reading between the lines that "simple move" is supposed to mean > "the size is not changing and MREMAP_DONTUNMAP is not set", which then > implies that in order to actually make anything happen, MREMAP_FIXED > must be specified? No, MREMAP_DONTUNMAP can be set, but MREMAP_FIXED must always be set for this to happen. Let me rephrase for clarity. > > > +.P > > .I old_address > > -is the old address of the virtual memory block that you > > -want to expand (or shrink). > > +is the old address of the first virtual memory block that you > > +want to expand, shrink, and/or move. > > Note that > > .I old_address > > has to be page aligned. > > .I old_size > > -is the old size of the > > -virtual memory block. > > +is the size of the range containing > > +virtual memory blocks to be manipulated. > > .I new_size > > is the requested size of the > > -virtual memory block after the resize. > > +virtual memory blocks after the resize. > > An optional fifth argument, > > .IR new_address , > > may be provided; see the description of > > @@ -105,13 +128,43 @@ If > > is specified, then > > .B MREMAP_MAYMOVE > > must also be specified. > > +.IP > > +Since Linux 6.17, > > +if > > +.I old_size > > +is equal to > > +.I new_size > > +and > > +.B MREMAP_FIXED > > +is specified, then > > +.I old_size > > +may span beyond the mapping in which > > +.I old_address > > +resides. > > +In this case, > > +gaps between mappings in the original range > > +are maintained in the new range. > > +The whole operation is performed atomically > > +unless an error arises, > > +in which case the operation may be partially > > +completed, > > +that is, > > +some mappings may be moved and others not. > > This is much clearer to me. Thanks
