'''Overview'''

The hugetlb pool exists to manage the allocation of fixed objects (huge pages).  As special requirements have evolved, the complexity of the hugetlb pool management code has increased.  This documentation exists to demystify the code and make it easier for others to work with the hugetlb pool and avoid mistakes.

'''Venn Diagram'''

This diagram shows how the counters relate to one another with respect to the huge pages and their various states.  The three main counters are: nr_huge_pages, free_huge_pages, and resv_huge_pages.  Pages can exist in each of the three domains (as described in the diagram).  Each of the three counters is equal to the number of pages within its respective domain plus all pages in sub-domains.  For example: Page "C" is a reserved huge page and its presence there is noted in all three counters; while page "B" is noted only in free_huge_pages and nr_huge_pages.

This logic shows that:
 * nr_huge_pages represents the total number of huge pages IN ANY STATE.
 * free_huge_pages counts the number of pages not currently in use (eg. pages are not mapped).
 * resv_huge_pages represents a special kind of free_huge_page that set aside for a shared mapping but is not yet mapped.

attachment:hugetlb%2Dpool%2DVenn.png

attachment:hugetlb%2Dpool%2Dstates.png