This patch adds manual pages for the path-related functions
hugetlbfs_test_path(), hugetlbfs_find_path() and hugetlbfs_unlinked_fd()
and their size-equivalents where they exist. The functions dealing with
the default hugepage size have existed since libhugetlbfs 1.0 but were not
documented.
Of these functions, the most interesting one is hugetlbfs_unlinked_fd().
It can be trivially used to create multiple memory regions that grow/shrink
with mmap() or are placed in a specific location in memory. This may be
important for custom allocators that need more control over the created
memory region than provided by the easier-to-use function get_huge_pages().
Signed-off-by: Mel Gorman <[EMAIL PROTECTED]>
---
Makefile | 8 +++-
man/gethugepagesizes.3 | 8 ++-
man/hugetlbfs_find_path.3 | 50 +++++++++++++++++
man/hugetlbfs_test_path.3 | 39 +++++++++++++
man/hugetlbfs_unlinked_fd.3 | 127 +++++++++++++++++++++++++++++++++++++++++++
5 files changed, 229 insertions(+), 3 deletions(-)
create mode 100644 man/hugetlbfs_find_path.3
create mode 100644 man/hugetlbfs_test_path.3
create mode 100644 man/hugetlbfs_unlinked_fd.3
diff --git a/Makefile b/Makefile
index 4554154..9894351 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,9 @@ BIN_OBJ_DIR=obj
INSTALL_BIN = hugectl hugeedit hugeadm pagesize
INSTALL_HEADERS = hugetlbfs.h
INSTALL_MAN1 = pagesize.1
-INSTALL_MAN3 = get_huge_pages.3 gethugepagesizes.3 getpagesizes.3
+INSTALL_MAN3 = get_huge_pages.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
LDSCRIPT_TYPES = B BDT
@@ -379,7 +381,11 @@ install-man:
gzip -f $(DESTDIR)$(MANDIR3)/$$x; \
done
rm -f $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
ln -s get_huge_pages.3.gz $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
+ ln -s hugetlbfs_find_path.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
+ ln -s hugetlbfs_unlinked_fd.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_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/gethugepagesizes.3 b/man/gethugepagesizes.3
index 02442a9..64fb6c6 100644
--- a/man/gethugepagesizes.3
+++ b/man/gethugepagesizes.3
@@ -59,8 +59,12 @@ by \fBlibhugetlbfs\fP, hugetlbfs_find_path_for_size() can be
called on a
specific size to see if a mount point is configured.
.SH SEE ALSO
-.I oprofile(1),
-.I opendir(3),
+.I oprofile(1)
+,
+.I opendir(3)
+,
+.I hugetlbfs_find_path_for_size(3)
+,
.I libhugetlbfs(7)
.SH AUTHORS
diff --git a/man/hugetlbfs_find_path.3 b/man/hugetlbfs_find_path.3
new file mode 100644
index 0000000..e4cd809
--- /dev/null
+++ b/man/hugetlbfs_find_path.3
@@ -0,0 +1,50 @@
+.\" 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 HUGETLBFS_FIND_PATH_FOR_SIZE 3 "November 6, 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
+hugetlbfs_find_path_for_size \- Locate a mount point for hugetlbfs supporting
a given pagesize
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+.B const char *hugetlbfs_find_path(void);
+.br
+.B const char *hugetlbfs_find_path_for_size(long page_size);
+.SH DESCRIPTION
+
+\fBhugetlbfs_find_path\fB and its page-size-aware companion
+\fBhugetlb_find_path_for_size() locate a hugetlbfs mount point for the
+default hugepage size and a given \fBpage_size\fB respectively. Multiple
+hugetlbfs mounts may exist as a single mount point cannot mix huge page
+sizes at time of writing.
+
+If there are multiple mount points for a pagesize, this function returns the
+first one found. This is a limitation of hugetlbfs where it only tracks one
+mount per pagesize. This may be a problem on systems that have per-application
+mount points.
+
+.SH RETURN VALUE
+
+A path to a mount point if one is found and NULL otherwise.
+
+.SH SEE ALSO
+.I libhugetlbfs(7)
+,
+.I mount(8)
+.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..9a9236e
--- /dev/null
+++ b/man/hugetlbfs_test_path.3
@@ -0,0 +1,39 @@
+.\" 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 HUGETLBFS_TEST_PATH 3 "November 2006, 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
+hugetlbfs_test_path - Detect if a path is within a hugetlbfs mount
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+.B int hugetlbfs_test_path(const char *path)
+.SH DESCRIPTION
+
+\fBhugetlbfs_test_path()\fB detects if a given \fBpath\fB is within a
+hugetlbfs filesystem or not.
+
+.SH RETURN VALUE
+
+A non-zero value is returned if the path is on a hugetlbfs filesystem and
+0 otherwise.
+
+.SH SEE ALSO
+.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..4d2f176
--- /dev/null
+++ b/man/hugetlbfs_unlinked_fd.3
@@ -0,0 +1,127 @@
+.\" 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 HUGETLBFS_UNLINKED_FD 3 "November 6, 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
+hugetlbfs_unlinked_fd, hugetlbfs_unlinked_fd_for_size \- Open an unlinked file
on a hugetlbfs filesystem
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+
+.br
+.B int hugetlbfs_unlinked_fd(void);
+.br
+.B hugetlbfs_unlinked_fd_for_size(long page_size);
+.SH DESCRIPTION
+
+\fBhugetlbfs_unlinked_fd()\fP and its page-size-aware companion
+\fBhugetlbfs_unlinked_fd_for_size()\fP discover a suitable hugetlbfs mount
+point, open a file, unlink it and return the descriptor. These functions
+are used internally by hugetlbfs to create memory regions with mmap()
+that are backed by hugepages of different sizes.
+
+An external usage might be to manage a heap by allocating and unlinked
+file descriptor and using mmap() and munmap() to grow and shrink the heap
+respectively. When mapped with MAP_PRIVATE, unmapping from the end will
+automatically free the hugepages but MAP_SHARED will require ftruncate()
+to be called as well.
+
+This example program assumes a pool is already configured of at least 10
+pages. It is linked with hugetlbfs and illustrates how a heap that could
+be shared with children is created, grown and shrunk.
+
+.nf
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <hugetlbfs.h>
+ #include <sys/mman.h>
+ #include <string.h>
+
+ #define HEAPSTART (void *)0xA0000000
+
+ int main() {
+ int fd;
+ int i;
+ char *buf, *extent;
+ size_t len = gethugepagesize();
+
+ system("grep HugePages_Free: /proc/meminfo");
+
+ /* Create fd for hugetlbfs-backed heap */
+ fd = hugetlbfs_unlinked_fd();
+ if (fd < 0) {
+ printf("Failed to create unlinked fd on hugetlbfs\n");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Creating initial mapping\n");
+ buf = mmap(HEAPSTART, len, PROT_READ|PROT_WRITE,
+ MAP_SHARED, fd, 0);
+ if (buf == MAP_FAILED) {
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Growing heap\n");
+ for (i = 1; i < 10; i++) {
+ fflush(NULL);
+ extent = mmap(buf + gethugepagesize()*i,
+ gethugepagesize(),
+ PROT_READ|PROT_WRITE,
+ MAP_SHARED|MAP_FIXED,
+ fd, gethugepagesize()*i);
+ if (extent == MAP_FAILED) {
+ perror("extent map\n");
+ exit(EXIT_FAILURE);
+ }
+
+
+ memset(buf, 0, gethugepagesize()*i);
+ system("grep HugePages_Free: /proc/meminfo");
+ }
+
+ printf("Shrinking heap\n");
+ for (i = 9; i >= 0; i--) {
+ munmap(buf + gethugepagesize()*i, gethugepagesize());
+ ftruncate(fd, gethugepagesize()*i);
+ system("grep HugePages_Free: /proc/meminfo");
+ }
+
+ printf("Finished\n");
+ system("grep HugePages_Free: /proc/meminfo");
+ close(fd);
+ }
+.fi
+
+.SH RETURN VALUE
+
+Both functions return a valid file descriptor on success and -1 on failure.
+errno is not necessarily set to anything useful when an error occurs.
+
+.SH NOTES
+
+In the current version of libhugetlbfs, it is difficult to programatically
+determine why an unlinked file could not be created. It will depend on the
+user reading messages writting to console to diagnose and correct the error.
+
+.SH SEE ALSO
+.I oprofile(1)
+,
+.I libhugetlbfs(7)
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
+
--
1.5.6.5
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Libhugetlbfs-devel mailing list
Libhugetlbfs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/libhugetlbfs-devel
