Hi Lorenzo, Jann, On Tue, Jul 29, 2025 at 02:47:35PM +0100, Lorenzo Stoakes 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 simply an MREMAP_FIXED move - that is old_size is equal to > new_size and MREMAP_FIXED is specified. > > To make things clearer, also describe this kind of 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 do so such that the > documentation does not contradict either this new capability nor the > pre-existing edge case. > > Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> I see some very minor formatting or punctuation issues, but I'll fix them while applying. Jann, do you plan to review this? Have a lovely day! Alex > --- > man/man2/mremap.2 | 84 ++++++++++++++++++++++++++++++++++++++++------- > 1 file changed, 73 insertions(+), 11 deletions(-) > > diff --git a/man/man2/mremap.2 b/man/man2/mremap.2 > index 2168ca728..6ba51310c 100644 > --- a/man/man2/mremap.2 > +++ b/man/man2/mremap.2 > @@ -25,18 +25,47 @@ moving it at the same time (controlled by the > argument and > the available virtual address space). > .P > +Mappings can also simply be moved > +(without any resizing) > +by specifying equal > +.I old_size > +and > +.I new_size > +and using the > +.B MREMAP_FIXED > +flag > +(see 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 when > +performing a move like this. > +The > +.B MREMAP_DONTUNMAP > +flag may be specified. > +.P > +If the operation is not > +simply moving mappings, > +then > +.I old_size > +must span only a single mapping. > +.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 +134,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. > +.IP > + > +Moving multiple mappings is not permitted if > +any of those mappings have either > +been registered with > +.BR userfaultfd (2) , > +or map drivers that > +specify their own custom address mapping logic. > .TP > .BR MREMAP_DONTUNMAP " (since Linux 5.7)" > .\" commit e346b3813067d4b17383f975f197a9aa28a3b077 > This flag, which must be used in conjunction with > .BR MREMAP_MAYMOVE , > -remaps a mapping to a new address but does not unmap the mapping at > -.IR old_address . > +remaps mappings to a new address but does not unmap them > +from their original address. > .IP > The > .B MREMAP_DONTUNMAP > @@ -149,13 +208,13 @@ mapped. > See NOTES for some possible applications of > .BR MREMAP_DONTUNMAP . > .P > -If the memory segment specified by > +If the memory segments specified by > .I old_address > and > .I old_size > -is locked (using > +are locked (using > .BR mlock (2) > -or similar), then this lock is maintained when the segment is > +or similar), then this lock is maintained when the segments are > resized and/or relocated. > As a consequence, the amount of memory locked by the process may change. > .SH RETURN VALUE > @@ -188,7 +247,10 @@ virtual memory address for this process. > You can also get > .B EFAULT > even if there exist mappings that cover the > -whole address space requested, but those mappings are of different types. > +whole address space requested, but those mappings are of different types, > +and the > +.BR mremap () > +operation being performed does not support this. > .TP > .B EINVAL > An invalid argument was given. > -- > 2.50.1 -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
