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".) > +.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? > +.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.