hugetlb: clean up and update huge pages documentation

HugePages_Total is the size of the pool of huge pages.

HugePages_Free  is the number of huge pages in the pool that are not yet

                allocated.

HugePages_Rsvd is short for "reserved," and is the number of hugepages

for which a commitment to allocate from the pool has been made, but no

allocation has yet been made. It's vaguely analogous to overcommit.

HugePages_Rsvd  is short for "reserved," and is the number of huge pages for

                which a commitment to allocate from the pool has been made,

                but no allocation has yet been made.  Reserved huge pages

                guarantee that an application will be able to allocate a

                huge page from the pool of huge pages at fault time.

HugePages_Surp  is short for "surplus," and is the number of huge pages in

the pool above the value in /proc/sys/vm/nr_hugepages. The maximum

number of surplus hugepages is controlled by

                the pool above the value in /proc/sys/vm/nr_hugepages. The

                maximum number of surplus huge pages is controlled by

                /proc/sys/vm/nr_overcommit_hugepages.

/proc/filesystems should also show a filesystem of type "hugetlbfs" configured

the huge pages.  It is required that the system administrator preallocate

enough memory for huge page purposes.

Use the following command to dynamically allocate/deallocate hugepages:

The administrator can preallocate huge pages on the kernel boot command line by

specifying the "hugepages=N" parameter, where 'N' = the number of huge pages

requested.  This is the most reliable method for preallocating huge pages as

memory has not yet become fragmented.

Some platforms support multiple huge page sizes.  To preallocate huge pages

of a specific size, one must preceed the huge pages boot command parameters

with a huge page size selection parameter "hugepagesz=<size>".  <size> must

be specified in bytes with optional scale suffix [kKmMgG].  The default huge

page size may be selected with the "default_hugepagesz=<size>" boot parameter.

/proc/sys/vm/nr_hugepages indicates the current number of configured [default

size] hugetlb pages in the kernel.  Super user can dynamically request more

(or free some pre-configured) huge pages.

Use the following command to dynamically allocate/deallocate default sized

huge pages:

	echo 20 > /proc/sys/vm/nr_hugepages

This command will try to configure 20 hugepages in the system.  The success

or failure of allocation depends on the amount of physically contiguous

memory that is preset in system at this time.  System administrators may want

to put this command in one of the local rc init files.  This will enable the

kernel to request huge pages early in the boot process (when the possibility

of getting physical contiguous pages is still very high). In either

case, administrators will want to verify the number of hugepages actually

allocated by checking the sysctl or meminfo.

This command will try to configure 20 default sized huge pages in the system.

On a NUMA platform, the kernel will attempt to distribute the huge page pool

over the all on-line nodes.  These huge pages, allocated when nr_hugepages

is increased, are called "persistent huge pages".

The success or failure of huge page allocation depends on the amount of

physically contiguous memory that is preset in system at the time of the

allocation attempt.  If the kernel is unable to allocate huge pages from

some nodes in a NUMA system, it will attempt to make up the difference by

allocating extra pages on other nodes with sufficient available contiguous

memory, if any.

/proc/sys/vm/nr_overcommit_hugepages indicates how large the pool of

System administrators may want to put this command in one of the local rc init

files.  This will enable the kernel to request huge pages early in the boot

process when the possibility of getting physical contiguous pages is still

very high.  Administrators can verify the number of huge pages actually

allocated by checking the sysctl or meminfo.  To check the per node

distribution of huge pages in a NUMA system, use:

	cat /sys/devices/system/node/node*/meminfo | fgrep Huge

/proc/sys/vm/nr_overcommit_hugepages specifies how large the pool of

huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are

requested by applications. echo'ing any non-zero value into this file

indicates that the hugetlb subsystem is allowed to try to obtain

hugepages from the buddy allocator, if the normal pool is exhausted. As

requested by applications.  Writing any non-zero value into this file

indicates that the hugetlb subsystem is allowed to try to obtain "surplus"

huge pages from the buddy allocator, when the normal pool is exhausted. As

these surplus huge pages go out of use, they are freed back to the buddy

allocator.

When increasing the huge page pool size via nr_hugepages, any surplus

pages will first be promoted to persistent huge pages.  Then, additional

huge pages will be allocated, if necessary and if possible, to fulfill

the new huge page pool size.

The administrator may shrink the pool of preallocated huge pages for

the default huge page size by setting the nr_hugepages sysctl to a

smaller value.  The kernel will attempt to balance the freeing of huge pages

across all on-line nodes.  Any free huge pages on the selected nodes will

be freed back to the buddy allocator.

Caveat: Shrinking the pool via nr_hugepages such that it becomes less

than the number of huge pages in use will convert the balance to surplus

huge pages even if it would exceed the overcommit value.  As long as

With support for multiple huge page pools at run-time available, much of

the huge page userspace interface has been duplicated in sysfs. The above

information applies to the default hugepage size (which will be

controlled by the proc interfaces for backwards compatibility). The root

hugepage control directory is

information applies to the default huge page size which will be

controlled by the /proc interfaces for backwards compatibility. The root

huge page control directory in sysfs is:

	/sys/kernel/mm/hugepages