[PATCH] manual: Document the MAP_HUGETLB, MADV_HUGEPAGE, MADV_NOHUGEPAGE flags

[Florian Weimer]

On 11/19/2017 03:29 AM, Rical Jasan wrote:
>> -These functions are declared in @file{sys/mman.h}.
>> +Note that @samp{sysconf (_SC_PAGESIZE)} only returns the default page
>> +size of the system.  On some systems, mappings can use larger page sizes
>> +for certain files, and applications can request larger page sizes for
>> +anonymous mappings as well (see the @code{MAP_HUGETLB} flag below).
> 
> I think the first sentence can be dropped since you already clarified
> it's the default page size above, and it would avoid having the function
> call in the sentence (which was also just shown).

Okay.

>> +The following functions are declared in @file{sys/mman.h}.
> 
> As a general rule, I end sentences containing "the following" with a
> colon, but +1 for adding that bit here.

Colon added.

>>   @deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
>>   @standards{POSIX, sys/mman.h}
>> @@ -1460,6 +1464,28 @@ On some systems using private anonymous mmaps is more efficient than using
>>   @code{malloc} for large blocks.  This is not an issue with @theglibc{},
>>   as the included @code{malloc} automatically uses @code{mmap} where appropriate.
>>   
>> +@item MAP_HUGETLB
> 
> @standards{Linux, sys/mman.h}
> 
>> +This requests that the system uses an alternative page size which is
>> +larger than the default page size for the mapping.  For some workloads,
>> +increasing the page size for large mappings improves performance because
>> +the system needs to handle far fewer pages.  For other workloads which
>> +require frequent transfer of pages between storage or different nodes,
>> +the increased page granularity may cause performance problems due to the
> 
> Shouldn't this be "decreased page granularity"?

Right, fixed.

>> +increased page size and larger transfers.
>> +
>> +In order to create the mapping, the system needs physically contiguous
>> +memory of the size of the increased page size.  As a result,
>> +@code{MAP_HUGETLB} mappings are affected by memory fragmentation, and
>> +their creation can fail even if plenty of memory is available in the
>> +system.
>> +
>> +Not all file systems support mappings with an increased page size.
>> +
>> +The @code{MAP_HUGETLB} flag is specific to Linux.
>> +
>> +@c There is a mechanism to select different hugepage sizes, see
> 
> "sizes; see"

Fixed.

>> +@c include/uapi/asm-generic/hugetlb_encode.h in the kernel sources.
>> +
>>   @c Linux has some other MAP_ options, which I have not discussed here.
>>   @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to
>>   @c user programs (and I don't understand the last two).  MAP_LOCKED does
>> @@ -1476,8 +1502,11 @@ Possible errors include:
>>   
>>   @item EINVAL
>>   
>> -Either @var{address} was unusable, or inconsistent @var{flags} were
>> -given.
>> +Either @var{address} was unusable (because it is not a multiple of the
>> +applicable page size), or inconsistent @var{flags} were given.
>> +
>> +If @code{MAP_HUGETLB} was specified: the file or system does not support
> 
> "specified,"

Okay.

>> +large page sizes.
>>   
>>   @item EACCES
>>   
>> @@ -1678,6 +1707,20 @@ The region is no longer needed.  The kernel may free these pages,
>>   causing any changes to the pages to be lost, as well as swapped
>>   out pages to be discarded.
>>   
>> +@item MADV_HUGEPAGE
> 
> @standards{Linux, sys/mman.h}
> 
>> +Indicate that it is beneficial to increase the page size for this
>> +mapping.  This can improve performance larger mappings because the
> 
> "performance for"

Fixed.

>> +system needs to handle far fewer pages.  However, if parts of the
>> +mapping are frequently transferred between storage or different nodes,
>> +performance may suffer because individual transfers can become
>> +substantially larger due to the increased page size.
>> +
>> +This flag is specific to Linux.
>> +
>> +@item MADV_NOHUGEPAGE
>> +Undo the effect of a previous @code{MADV_NOHUGEPAGE} advice.  This flag
> 
> Undoes MADV_HUGEPAGE, right?

Fixed as well.

Thanks for your review, updated patch attached.

Florian
-------------- next part --------------
A non-text attachment was scrubbed...
Name: hugetlb.patch
Type: text/x-patch
Size: 4142 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20171119/594c2068/attachment.bin>