aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile11
-rw-r--r--man/gethugepagesize.354
-rw-r--r--man/gethugepagesizes.37
-rw-r--r--man/getpagesizes.32
-rw-r--r--man/hugetlbfs_find_path.352
-rw-r--r--man/hugetlbfs_test_path.353
-rw-r--r--man/hugetlbfs_unlinked_fd.355
-rw-r--r--man/ld.hugetlbfs.172
-rw-r--r--man/libhugetlbfs.724
9 files changed, 318 insertions, 12 deletions
diff --git a/Makefile b/Makefile
index 7f03eb4..03966b2 100644
--- a/Makefile
+++ b/Makefile
@@ -11,9 +11,10 @@ INSTALL_SCRIPT = cpupcstat oprofile_map_events.pl oprofile_start.sh
INSTALL_HELPER = huge_page_setup_helper.py
INSTALL_PERLMOD = DataCollect.pm OpCollect.pm PerfCollect.pm Report.pm
INSTALL_HEADERS = hugetlbfs.h
-INSTALL_MAN1 = pagesize.1
-INSTALL_MAN3 = get_huge_pages.3 get_hugepage_region.3 \
- gethugepagesizes.3 getpagesizes.3
+INSTALL_MAN1 = ld.hugetlbfs.1 pagesize.1
+INSTALL_MAN3 = get_huge_pages.3 get_hugepage_region.3 gethugepagesize.3 \
+ gethugepagesizes.3 getpagesizes.3 hugetlbfs_find_path.3 \
+ hugetlbfs_test_path.3 hugetlbfs_unlinked_fd.3
INSTALL_MAN7 = libhugetlbfs.7
INSTALL_MAN8 = hugectl.8 hugeedit.8 hugeadm.8 cpupcstat.8
LDSCRIPT_TYPES = B BDT
@@ -392,8 +393,12 @@ install-man:
done
rm -f $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
rm -f $(DESTDIR)$(MANDIR3)/free_hugepage_region.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
ln -s get_huge_pages.3.gz $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
ln -s get_hugepage_region.3.gz $(DESTDIR)$(MANDIR3)/free_hugepage_region.3.gz
+ ln -s hugetlbfs_unlinked_fd.3.gz $(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
+ ln -s hugetlbfs_find_path.3.gz $(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
for x in $(INSTALL_MAN7); do \
$(INSTALL) -m 444 man/$$x $(DESTDIR)$(MANDIR7); \
gzip -f $(DESTDIR)$(MANDIR7)/$$x; \
diff --git a/man/gethugepagesize.3 b/man/gethugepagesize.3
new file mode 100644
index 0000000..9c46ccf
--- /dev/null
+++ b/man/gethugepagesize.3
@@ -0,0 +1,54 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" 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 GETHUGEPAGESIZE 3 "March 7, 2012"
+.\" 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
+gethugepagesize - Get the default huge page size
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+
+.B long gethugepagesize(void)
+
+.SH DESCRIPTION
+
+The gethugepagesize() function returns the default huge page size used by
+libhugetlbfs. This will be either the system default, or a valid value set
+by the environment variable \fBHUGETLB_DEFAULT_PAGE_SIZE\fP.
+
+If the system does not support any huge page sizes an error is returned.
+
+.SH RETURN VALUE
+
+On success, the default huge page size is returned. On failure,
+-1 is returned and errno is set appropriately.
+
+.SH ERRORS
+
+.TP
+.B ENOSYS
+The system does not support huge pages.
+
+.SH SEE ALSO
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff --git a/man/gethugepagesizes.3 b/man/gethugepagesizes.3
index 02442a9..a782094 100644
--- a/man/gethugepagesizes.3
+++ b/man/gethugepagesizes.3
@@ -19,7 +19,6 @@
gethugepagesizes - Get the system supported huge page sizes
.SH SYNOPSIS
.B #include <hugetlbfs.h>
-.br
.br
int gethugepagesizes(long pagesizes[], int n_elem);
@@ -41,12 +40,10 @@ the number of huge page sizes stored in pagesizes is returned. On failure,
.SH ERRORS
.TP
-.B ERRNO
+.B EINVAL
\fBn_elem\fP is less than zero or \fBn_elem\fP is greater than zero and
\fBpagesizes\fP is NULL.
-
.PP
-
Also see opendir(3) for other possible values for errno. This error occurs
when the sysfs directory exists but cannot be opened.
@@ -61,9 +58,9 @@ specific size to see if a mount point is configured.
.SH SEE ALSO
.I oprofile(1),
.I opendir(3),
+.I hugetlbfs_find_path_for_size(3),
.I libhugetlbfs(7)
.SH AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel
mailing list.
-
diff --git a/man/getpagesizes.3 b/man/getpagesizes.3
index fb3a387..cbd534a 100644
--- a/man/getpagesizes.3
+++ b/man/getpagesizes.3
@@ -41,7 +41,7 @@ number of page sizes stored in \fBpagesizes\fP is returned. On failure,
.SH ERRORS
.TP
-.B ERRNO
+.B EINVAL
\fBn_elem\fP is less than zero or \fBn_elem\fP is greater than zero and
\fBpagesizes\fP is NULL.
diff --git a/man/hugetlbfs_find_path.3 b/man/hugetlbfs_find_path.3
new file mode 100644
index 0000000..b2d1171
--- /dev/null
+++ b/man/hugetlbfs_find_path.3
@@ -0,0 +1,52 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" 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 HUGETLBFS_FIND_PATH 3 "March 7, 2012"
+.\" 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
+hugetlbfs_find_path, hugetlbfs_find_path_for_size - Locate an appropriate hugetlbfs mount point
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+const char *hugetlbfs_find_path(void);
+.br
+const char *hugetlbfs_find_path_for_size(long page_size);
+
+.SH DESCRIPTION
+
+These functions return a pathname for a mounted hugetlbfs filesystem for
+the appropriate huge page size. For hugetlbfs_find_path, the default
+huge page size is used (see gethugepagesize(3)). For
+hugetlbfs_find_path_for_size, a valid huge page size must be specified
+(see gethugepagesizes(3)).
+
+.SH RETURN VALUE
+
+On success, a non-NULL value is returned.
+On failure, NULL is returned.
+
+.SH SEE ALSO
+.I libhugetlbfs(7),
+.I gethugepagesize(3),
+.I gethugepagesizes(3)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff --git a/man/hugetlbfs_test_path.3 b/man/hugetlbfs_test_path.3
new file mode 100644
index 0000000..67295ea
--- /dev/null
+++ b/man/hugetlbfs_test_path.3
@@ -0,0 +1,53 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" 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 HUGETLBFS_TEST_PATH 3 "March 7, 2012"
+.\" 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
+hugetlbfs_test_path - Determine whether a mount point is hugetlbfs
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+int hugetlbfs_test_path(const char *mount);
+
+.SH DESCRIPTION
+
+The hugetlbfs_test_path() function determines whether a given pathname
+is in a hugetlbfs filesystem.
+
+.SH RETURN VALUE
+
+On success, 1 is returned for a hugetlbfs filesystem, or 0 for a
+non-hugetlbfs filesystem. On failure, -1 is returned and errno is set
+appropriately.
+
+.SH ERRORS
+
+.PP
+Please see statfs(3) for possible values for errno.
+
+
+.SH SEE ALSO
+.I statfs(3),
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff --git a/man/hugetlbfs_unlinked_fd.3 b/man/hugetlbfs_unlinked_fd.3
new file mode 100644
index 0000000..ffeb716
--- /dev/null
+++ b/man/hugetlbfs_unlinked_fd.3
@@ -0,0 +1,55 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" 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 HUGETLBFS_UNLINKED_FD 3 "March 7, 2012"
+.\" 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
+hugetlbfs_unlinked_fd, hugetlbfs_unlinked_fd_for_size - Obtain a file descriptor for a new unlinked file in hugetlbfs
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+.B int hugetlbfs_unlinked_fd(void);
+.br
+.B int hugetlbfs_unlinked_fd_for_size(long page_size);
+
+.SH DESCRIPTION
+
+These functions return an open file descriptor for a unique, newly-created
+file in a hugetlbfs filesystem. To avoid leaking hugepages, the file
+is unlinked automatically before the function returns.
+
+For hugetlbfs_unlinked_fd, the default huge page size is used (see
+gethugepagesize(3)). For hugetlbfs_unlinked_fd_for_size, a valid huge
+page size must be specified (see gethugepagesizes(3)).
+
+.SH RETURN VALUE
+
+On success, a valid open file descriptor is returned. On failure,
+-1 is returned and errno may be set appropriately.
+
+.SH SEE ALSO
+.I gethugepagesize(3),
+.I gethugepagesizes(3),
+.I mkstemp(3),
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff --git a/man/ld.hugetlbfs.1 b/man/ld.hugetlbfs.1
new file mode 100644
index 0000000..60487e2
--- /dev/null
+++ b/man/ld.hugetlbfs.1
@@ -0,0 +1,72 @@
+\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" 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 LD.HUGETLBFS 1 "March 12, 2012"
+.\" 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
+ld.hugetlbfs \- link a program for huge pages
+.SH SYNOPSIS
+.B ld.hugetlbfs [options]
+.SH DESCRIPTION
+
+\fBld.hugetlbfs\fP replaces the normal \fBld\fP command for linking programs
+to use hugepages. Under gcc, you should use the option
+\fB-B /usr/share/libhugetlbfs\fP which tells gcc to look in a non-standard
+location for the linker. This could be set in the \fBCFLAGS\fP environment
+variable.
+
+.TP
+.B -Wl,--hugetlbfs-align
+
+This method of linking an application permits greater flexibility at runtime.
+Using HUGETLB_ELFMAP, it is possible to control which program segments are
+placed in hugepages. The following four settings will cause the indicated
+segments to be placed in hugepages:
+
+ HUGETLB_ELFMAP=R Read-only segments (text)
+ HUGETLB_ELFMAP=W Writable segments (data/BSS)
+ HUGETLB_ELFMAP=RW All segments (text/data/BSS)
+ HUGETLB_ELFMAP=no No segments
+
+It is possible to select specific huge page sizes for read-only and writable
+segments by using the following advanced syntax:
+
+ HUGETLB_ELFMAP=[R[=<pagesize>]:[W[=<pagesize>]]
+
+.B -Wl,--hugetlbfs-link=B
+
+Under binutils 2.16 or older, this option will link the application to store
+BSS data (only) into hugepages.
+
+.B -Wl,--hugetlbfs-link=BDT
+
+Under binutils 2.16 or older, this option will link the application to store
+text, initialized data and BSS data into hugepages.
+
+.SH FILES
+[DESTDIR|/usr/share]/doc/libhugetlbfs/HOWTO
+
+.SH SEE ALSO
+.I libhugetlbfs(7),
+.I hugectl(8),
+.I hugeedit(8)
+.br
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff --git a/man/libhugetlbfs.7 b/man/libhugetlbfs.7
index 14bcf04..7131ca9 100644
--- a/man/libhugetlbfs.7
+++ b/man/libhugetlbfs.7
@@ -39,8 +39,8 @@ they are large enough.
For the effective backing of text and data with huge pages, the application
must be linked to the library and the ELF segments correctly aligned using
the ld helpers. Once linked, malloc or shared memory can still be backed
-but no pre-loading is required. See /usr/share/docs/libhugetlbfs/HOWTO for
-detailed instructions on relinking applications.
+but no pre-loading is required. See /usr/share/doc/libhugetlbfs/HOWTO and
+ld.hugetlbfs(1) for detailed instructions on relinking applications.
For applications that are hugepage-aware and linked to the library
\fBget_huge_pages()\fP can be used for the direct allocation of
@@ -64,6 +64,11 @@ all cases, the environment being unset implies the feature should remain
disabled.
.TP
+.B HUGETLB_DEFAULT_PAGE_SIZE=<pagesize>
+This sets the default hugepage size to be used by libhugetlbfs. If not
+set, libhugetlbfs will use the kernel's default hugepage size.
+
+.TP
.B HUGETLB_MORECORE=[yes|<pagesize>]
This enables the hugepage malloc() feature, instructing libhugetlbfs to
override glibc's normal morecore() function with a hugepage version and use
@@ -199,14 +204,27 @@ The default value for this is 1 and the range of the value is from 0 to
Once set, this will give very detailed output on what is happening in the
library and run extra diagnostics.
+.SH FILES
+[DESTDIR|/usr/share]/doc/libhugetlbfs/HOWTO
+
.SH SEE ALSO
.I oprofile(1),
+.I ld.hugetlbfs(1),
.I hugectl(8),
.I hugeedit(8),
+.I gethugepagesize(3),
+.I gethugepagesizes(3),
+.I getpagesizes(3),
+.I hugetlbfs_test_path(3),
+.I hugetlbfs_find_path(3),
+.I hugetlbfs_find_path_for_size(3),
+.I hugetlbfs_test_path(3),
+.I hugetlbfs_test_path_for_size(3),
+.I hugetlbfs_unlinked_fd(3),
+.I hugetlbfs_unlinked_fd_for_size(3),
.I get_huge_pages(3),
.I free_huge_pages(3)
.br
.SH AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel
mailing list.
-