.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH GET_HUGEPAGE_REGION 3 "November 7, 2008"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
get_hugepage_region, free_hugepage_region \- Allocate and free regions of memory that use hugepages where possible
.SH SYNOPSIS
.B #include <hugetlbfs.h>
.br

.br
.B void *get_hugepage_region(size_t len, ghr_t flags);
.br
.B void free_hugepage_region(void *ptr);
.SH DESCRIPTION

\fBget_hugepage_region()\fP allocates a memory region \fBlen\fP bytes in size
backed by hugepages. Hugepages may be of benefit to applications that use
large amounts of address space and suffer a performance hit due to TLB
misses. Wall-clock time or oprofile can be used to determine if there is
a performance benefit from using hugepages or not.

Unlike \fBget_huge_pages()\fP, \fBlen\fP does not have to be hugepage-aligned
although memory may be wasted due to alignment. The caller may also specify
that base pages be used in the event there are no hugepages available.

The \fBflags\fP argument changes the behaviour of the function. Flags may
be or'd together.

.TP
.B GHR_FALLBACK
Use base pages if there are an insufficient number of huge pages.

.TP
.B GHR_STRICT
Use hugepages or return NULL.

.TP
.B GHR_COLOR
When specified, bytes that would be wasted due to alignment are used to
color the buffer by offsetting it by a random cacheline within the hugepage.
This avoids a performance problem whereby multiple buffers use the same
cache lines at the same offsets. If it is not important that the start of the
buffer be page-aligned, specify this flag.

.TP
.B GHR_DEFAULT
The library chooses a sensible combination of flags for allocating a region of
memory. The current default is:
	GHR_FALLBACK | GHR_COLOR

.PP

\fBfree_hugepage_region()\fP frees a region of memory allocated by
\fBget_hugepage_region()\fP. The behaviour of the function if another
pointer is used, valid or otherwise, is undefined.

.SH RETURN VALUE

On success, a pointer is returned for to the allocated memory. On
error, NULL is returned. errno will be set based on what the failure of
mmap() was due to.

.SH SEE ALSO
.I oprofile(1)
,
.I gethugepagesize(3)
,
.I get_huge_pages(3)
,
.I libhugetlbfs(7)
.SH AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel
mailing list.