[patch] mmap.2: document the munmap exception for underlying page size

[patch] mmap.2: document the munmap exception for underlying page size

[David Rientjes]

munmap(2) will fail with an errno of EINVAL for hugetlb memory if the 
length is not a multiple of the underlying page size.

Documentation/vm/hugetlbpage.txt was updated to specify this behavior 
since Linux 4.1 in commit 80d6b94bd69a ("mm, doc: cleanup and clarify 
munmap behavior for hugetlb memory").

Signed-off-by: David Rientjes <rientjes@google.com>
---
 man2/mmap.2 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man2/mmap.2 b/man2/mmap.2
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -383,6 +383,10 @@ All pages containing a part
 of the indicated range are unmapped, and subsequent references
 to these pages will generate
 .BR SIGSEGV .
+An exception is when the underlying memory is not of the native page
+size, such as hugetlb page sizes, whereas
+.I length
+must be a multiple of the underlying page size.
 It is not an error if the
 indicated range does not contain any mapped pages.
 .SS Timestamps changes for file-backed mappings

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[Michael Kerrisk (man-pages)]

Hi David,

On 07/22/2015 02:41 AM, David Rientjes wrote:
> munmap(2) will fail with an errno of EINVAL for hugetlb memory if the 
> length is not a multiple of the underlying page size.
> 
> Documentation/vm/hugetlbpage.txt was updated to specify this behavior 
> since Linux 4.1 in commit 80d6b94bd69a ("mm, doc: cleanup and clarify 
> munmap behavior for hugetlb memory").
> 
> Signed-off-by: David Rientjes <rientjes@google.com>
> ---
>  man2/mmap.2 | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/man2/mmap.2 b/man2/mmap.2
> --- a/man2/mmap.2
> +++ b/man2/mmap.2
> @@ -383,6 +383,10 @@ All pages containing a part
>  of the indicated range are unmapped, and subsequent references
>  to these pages will generate
>  .BR SIGSEGV .
> +An exception is when the underlying memory is not of the native page
> +size, such as hugetlb page sizes, whereas
> +.I length
> +must be a multiple of the underlying page size.
>  It is not an error if the
>  indicated range does not contain any mapped pages.
>  .SS Timestamps changes for file-backed mappings

I'm struggling a bit to understand your text. Is the point this:

    If we have a hugetlb area, then the munmap() length
    must be a multiple of the page size.

?

Are there any requirements about 'addr'? Must it also me huge-page-aligned?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[David Rientjes]

On Wed, 22 Jul 2015, Michael Kerrisk (man-pages) wrote:

> > diff --git a/man2/mmap.2 b/man2/mmap.2
> > --- a/man2/mmap.2
> > +++ b/man2/mmap.2
> > @@ -383,6 +383,10 @@ All pages containing a part
> >  of the indicated range are unmapped, and subsequent references
> >  to these pages will generate
> >  .BR SIGSEGV .
> > +An exception is when the underlying memory is not of the native page
> > +size, such as hugetlb page sizes, whereas
> > +.I length
> > +must be a multiple of the underlying page size.
> >  It is not an error if the
> >  indicated range does not contain any mapped pages.
> >  .SS Timestamps changes for file-backed mappings
> 
> I'm struggling a bit to understand your text. Is the point this:
> 
>     If we have a hugetlb area, then the munmap() length
>     must be a multiple of the page size.
> 
> ?
> 

Of the hugetlb page size, yes, which was meant by the "underlying page 
size" since we have configurable hugetlb sizes.  This is different from 
the native page size, whereas the length is rounded up to be page aligned 
per POSIX.

> Are there any requirements about 'addr'? Must it also me huge-page-aligned?
> 

Yes, so it looks like we need to fix up the reference to "address addr 
must be a multiple of the page size" to something like "address addr must 
be a multiple of the underlying page size" but I think the distinction 
isn't explicit enough as I'd like it.  I think it's better to explicitly 
show the exception for hugetlb page sizes and compare the underlying page 
size to the native page size to define how the behavior differs.

Would something like

	An exception is when the underlying memory, such as hugetlb 
	memory, is not of the native page size: the address addr and
	the length must be a multiple of the underlying page size.

suffice?

Also, is it typical to reference the commit of the documentation change 
in the kernel source that defines this?  I see this done with .\" blocks 
for MAP_STACK in the same man page.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[Mike Kravetz]

On 07/21/2015 05:41 PM, David Rientjes wrote:
> munmap(2) will fail with an errno of EINVAL for hugetlb memory if the
> length is not a multiple of the underlying page size.
>
> Documentation/vm/hugetlbpage.txt was updated to specify this behavior
> since Linux 4.1 in commit 80d6b94bd69a ("mm, doc: cleanup and clarify
> munmap behavior for hugetlb memory").
>
> Signed-off-by: David Rientjes <rientjes@google.com>
> ---
>   man2/mmap.2 | 4 ++++
>   1 file changed, 4 insertions(+)
>
> diff --git a/man2/mmap.2 b/man2/mmap.2
> --- a/man2/mmap.2
> +++ b/man2/mmap.2
> @@ -383,6 +383,10 @@ All pages containing a part
>   of the indicated range are unmapped, and subsequent references
>   to these pages will generate
>   .BR SIGSEGV .
> +An exception is when the underlying memory is not of the native page
> +size, such as hugetlb page sizes, whereas
> +.I length
> +must be a multiple of the underlying page size.
>   It is not an error if the
>   indicated range does not contain any mapped pages.
>   .SS Timestamps changes for file-backed mappings
>
> --

Should we also add a similar comment for the mmap offset?  Currently
the man page says:

"offset must be a multiple of the page size as returned by
  sysconf(_SC_PAGE_SIZE)."

For hugetlbfs, I beieve the offset must be a multiple of the
hugetlb page size.  A similar comment/exception about using
the "underlying page size" would apply here as well.

-- 
Mike Kravetz

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[David Rientjes]

On Wed, 22 Jul 2015, Mike Kravetz wrote:

> On 07/21/2015 05:41 PM, David Rientjes wrote:
> > munmap(2) will fail with an errno of EINVAL for hugetlb memory if the
> > length is not a multiple of the underlying page size.
> > 
> > Documentation/vm/hugetlbpage.txt was updated to specify this behavior
> > since Linux 4.1 in commit 80d6b94bd69a ("mm, doc: cleanup and clarify
> > munmap behavior for hugetlb memory").
> > 
> > Signed-off-by: David Rientjes <rientjes@google.com>
> > ---
> >   man2/mmap.2 | 4 ++++
> >   1 file changed, 4 insertions(+)
> > 
> > diff --git a/man2/mmap.2 b/man2/mmap.2
> > --- a/man2/mmap.2
> > +++ b/man2/mmap.2
> > @@ -383,6 +383,10 @@ All pages containing a part
> >   of the indicated range are unmapped, and subsequent references
> >   to these pages will generate
> >   .BR SIGSEGV .
> > +An exception is when the underlying memory is not of the native page
> > +size, such as hugetlb page sizes, whereas
> > +.I length
> > +must be a multiple of the underlying page size.
> >   It is not an error if the
> >   indicated range does not contain any mapped pages.
> >   .SS Timestamps changes for file-backed mappings
> > 
> > --
> 
> Should we also add a similar comment for the mmap offset?  Currently
> the man page says:
> 
> "offset must be a multiple of the page size as returned by
>  sysconf(_SC_PAGE_SIZE)."
> 
> For hugetlbfs, I beieve the offset must be a multiple of the
> hugetlb page size.  A similar comment/exception about using
> the "underlying page size" would apply here as well.
> 

Yes, that makes sense, thanks.  We should also explicitly say that mmap(2) 
automatically aligns length to be hugepage aligned if backed by hugetlbfs.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[Michael Kerrisk (man-pages)]

On 07/23/2015 12:03 AM, David Rientjes wrote:
> On Wed, 22 Jul 2015, Michael Kerrisk (man-pages) wrote:
> 
>>> diff --git a/man2/mmap.2 b/man2/mmap.2
>>> --- a/man2/mmap.2
>>> +++ b/man2/mmap.2
>>> @@ -383,6 +383,10 @@ All pages containing a part
>>>  of the indicated range are unmapped, and subsequent references
>>>  to these pages will generate
>>>  .BR SIGSEGV .
>>> +An exception is when the underlying memory is not of the native page
>>> +size, such as hugetlb page sizes, whereas
>>> +.I length
>>> +must be a multiple of the underlying page size.
>>>  It is not an error if the
>>>  indicated range does not contain any mapped pages.
>>>  .SS Timestamps changes for file-backed mappings
>>
>> I'm struggling a bit to understand your text. Is the point this:
>>
>>     If we have a hugetlb area, then the munmap() length
>>     must be a multiple of the page size.
>>
>> ?
>>
> 
> Of the hugetlb page size, yes, which was meant by the "underlying page 
> size" since we have configurable hugetlb sizes.  This is different from 
> the native page size, whereas the length is rounded up to be page aligned 
> per POSIX.
> 
>> Are there any requirements about 'addr'? Must it also me huge-page-aligned?
>>
> 
> Yes, so it looks like we need to fix up the reference to "address addr 
> must be a multiple of the page size" to something like "address addr must 
> be a multiple of the underlying page size" but I think the distinction 
> isn't explicit enough as I'd like it.  I think it's better to explicitly 
> show the exception for hugetlb page sizes and compare the underlying page 
> size to the native page size to define how the behavior differs.
> 
> Would something like
> 
> 	An exception is when the underlying memory, such as hugetlb 
> 	memory, is not of the native page size: the address addr and
> 	the length must be a multiple of the underlying page size.

See my suggestion in another mail (in a few minutes).

> suffice?
> 
> Also, is it typical to reference the commit of the documentation change 
> in the kernel source that defines this?  I see this done with .\" blocks 
> for MAP_STACK in the same man page.

I find it handy to add such references, for later references.
By the way, are you saying that some piece of behavior has
changed in recent times for munmap() on HugeTLB?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[Michael Kerrisk (man-pages)]

On 07/23/2015 01:49 AM, David Rientjes wrote:
> On Wed, 22 Jul 2015, Mike Kravetz wrote:
> 
>> On 07/21/2015 05:41 PM, David Rientjes wrote:
>>> munmap(2) will fail with an errno of EINVAL for hugetlb memory if the
>>> length is not a multiple of the underlying page size.
>>>
>>> Documentation/vm/hugetlbpage.txt was updated to specify this behavior
>>> since Linux 4.1 in commit 80d6b94bd69a ("mm, doc: cleanup and clarify
>>> munmap behavior for hugetlb memory").
>>>
>>> Signed-off-by: David Rientjes <rientjes@google.com>
>>> ---
>>>   man2/mmap.2 | 4 ++++
>>>   1 file changed, 4 insertions(+)
>>>
>>> diff --git a/man2/mmap.2 b/man2/mmap.2
>>> --- a/man2/mmap.2
>>> +++ b/man2/mmap.2
>>> @@ -383,6 +383,10 @@ All pages containing a part
>>>   of the indicated range are unmapped, and subsequent references
>>>   to these pages will generate
>>>   .BR SIGSEGV .
>>> +An exception is when the underlying memory is not of the native page
>>> +size, such as hugetlb page sizes, whereas
>>> +.I length
>>> +must be a multiple of the underlying page size.
>>>   It is not an error if the
>>>   indicated range does not contain any mapped pages.
>>>   .SS Timestamps changes for file-backed mappings
>>>
>>> --
>>
>> Should we also add a similar comment for the mmap offset?  Currently
>> the man page says:
>>
>> "offset must be a multiple of the page size as returned by
>>  sysconf(_SC_PAGE_SIZE)."
>>
>> For hugetlbfs, I beieve the offset must be a multiple of the
>> hugetlb page size.  A similar comment/exception about using
>> the "underlying page size" would apply here as well.
>>
> 
> Yes, that makes sense, thanks.  We should also explicitly say that mmap(2) 
> automatically aligns length to be hugepage aligned if backed by hugetlbfs.

And, surely, it also does something similar for mmap()'s 'addr'
argument? 

I suggest we add a subsection to describe the HugeTLB differences. How 
about something like:

   Huge page (Huge TLB) mappings
       For  mappings  that  employ  huge pages, the requirements for the
       arguments  of  mmap()  and  munmap()  differ  somewhat  from  the
       requirements for mappings that use the native system page size.

       For mmap(), offset must be a multiple of the underlying huge page
       size.  The system automatically aligns length to be a multiple of
       the underlying huge page size.

       For  munmap(),  addr  and  length  must both be a multiple of the
       underlying huge page size.
?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[David Rientjes]

On Thu, 23 Jul 2015, Michael Kerrisk (man-pages) wrote:

> >> Should we also add a similar comment for the mmap offset?  Currently
> >> the man page says:
> >>
> >> "offset must be a multiple of the page size as returned by
> >>  sysconf(_SC_PAGE_SIZE)."
> >>
> >> For hugetlbfs, I beieve the offset must be a multiple of the
> >> hugetlb page size.  A similar comment/exception about using
> >> the "underlying page size" would apply here as well.
> >>
> > 
> > Yes, that makes sense, thanks.  We should also explicitly say that mmap(2) 
> > automatically aligns length to be hugepage aligned if backed by hugetlbfs.
> 
> And, surely, it also does something similar for mmap()'s 'addr'
> argument? 
> 
> I suggest we add a subsection to describe the HugeTLB differences. How 
> about something like:
> 
>    Huge page (Huge TLB) mappings
>        For  mappings  that  employ  huge pages, the requirements for the
>        arguments  of  mmap()  and  munmap()  differ  somewhat  from  the
>        requirements for mappings that use the native system page size.
> 
>        For mmap(), offset must be a multiple of the underlying huge page
>        size.  The system automatically aligns length to be a multiple of
>        the underlying huge page size.
> 
>        For  munmap(),  addr  and  length  must both be a multiple of the
>        underlying huge page size.
> ?
> 

Looks good, please add my acked-by.  The commit that expanded on the 
documentation of this behavior was 
80d6b94bd69a7a49b52bf503ef6a841f43cf5bbb.

Answering from your other email, no, this behavior in the kernel has not 
changed recently but we found it wasn't properly documented so we wanted 
to fix that both in the kernel tree and in the man-pages to make it 
explicit.

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

Re: [patch] mmap.2: document the munmap exception for underlying page size

[Michael Kerrisk (man-pages)]

Hello David,

On 23 July 2015 at 22:52, David Rientjes <rientjes@google.com> wrote:
> On Thu, 23 Jul 2015, Michael Kerrisk (man-pages) wrote:
>
>> >> Should we also add a similar comment for the mmap offset?  Currently
>> >> the man page says:
>> >>
>> >> "offset must be a multiple of the page size as returned by
>> >>  sysconf(_SC_PAGE_SIZE)."
>> >>
>> >> For hugetlbfs, I beieve the offset must be a multiple of the
>> >> hugetlb page size.  A similar comment/exception about using
>> >> the "underlying page size" would apply here as well.
>> >>
>> >
>> > Yes, that makes sense, thanks.  We should also explicitly say that mmap(2)
>> > automatically aligns length to be hugepage aligned if backed by hugetlbfs.
>>
>> And, surely, it also does something similar for mmap()'s 'addr'
>> argument?
>>
>> I suggest we add a subsection to describe the HugeTLB differences. How
>> about something like:
>>
>>    Huge page (Huge TLB) mappings
>>        For  mappings  that  employ  huge pages, the requirements for the
>>        arguments  of  mmap()  and  munmap()  differ  somewhat  from  the
>>        requirements for mappings that use the native system page size.
>>
>>        For mmap(), offset must be a multiple of the underlying huge page
>>        size.  The system automatically aligns length to be a multiple of
>>        the underlying huge page size.
>>
>>        For  munmap(),  addr  and  length  must both be a multiple of the
>>        underlying huge page size.
>> ?
>>
>
> Looks good, please add my acked-by.

Done. Thanks for checking the text.

> The commit that expanded on the
> documentation of this behavior was
> 80d6b94bd69a7a49b52bf503ef6a841f43cf5bbb.
>
> Answering from your other email, no, this behavior in the kernel has not
> changed recently but we found it wasn't properly documented so we wanted
> to fix that both in the kernel tree and in the man-pages to make it
> explicit.

Okay -- thanks for the clarification.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>