116 lines
4.1 KiB
Groff
116 lines
4.1 KiB
Groff
|
.\"
|
||
|
|
.\" Copyright (C) 2014 - 2018 Intel Corporation.
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright notice(s),
|
||
|
|
.\" this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright notice(s),
|
||
|
|
.\" this list of conditions and the following disclaimer in the documentation
|
||
|
|
.\" and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS
|
||
|
|
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
|
||
|
|
.\" EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
||
|
|
.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
||
|
|
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
||
|
|
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
||
|
|
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.TH "MEMKIND_PMEM" 3 "2015-04-21" "Intel Corporation" "MEMKIND_PMEM" \" -*- nroff -*-
|
||
|
|
.SH "NAME"
|
||
|
|
memkind_pmem.h \- file-backed memory memkind operations.
|
||
|
|
.br
|
||
|
|
Note: This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed.
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.nf
|
||
|
|
.B #include <memkind/internal/memkind_pmem.h>
|
||
|
|
.sp
|
||
|
|
.B Link with -lmemkind
|
||
|
|
.sp
|
||
|
|
.BI "int memkind_pmem_create(struct memkind " "*kind" ", struct memkind_ops " "*ops" ", const char " "*name" );
|
||
|
|
.br
|
||
|
|
.BI "int memkind_pmem_destroy(struct memkind " "*kind" );
|
||
|
|
.br
|
||
|
|
.BI "void *memkind_pmem_mmap(struct memkind " "*kind" ", void " "*addr" ", size_t " "size" );
|
||
|
|
.br
|
||
|
|
.BI "int memkind_pmem_get_mmap_flags(struct memkind " "*kind" ", int " "*flags" );
|
||
|
|
.br
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
The pmem memory memkind operations enable memory kinds built on memory-mapped
|
||
|
|
files. These support traditional
|
||
|
|
.B volatile
|
||
|
|
memory allocation in a fashion similar to
|
||
|
|
.BR libvmem (3)
|
||
|
|
library. It uses the
|
||
|
|
.BR mmap (2)
|
||
|
|
system call to create a pool of volatile memory. Such memory may have different
|
||
|
|
attributes, depending on the file system containing the memory-mapped files.
|
||
|
|
(See also
|
||
|
|
.IR http://pmem.io/pmdk/libvmem ).
|
||
|
|
.PP
|
||
|
|
The pmem memkinds are most useful when used with
|
||
|
|
.I Direct Access
|
||
|
|
storage (DAX), which is memory-addressable persistent storage
|
||
|
|
that supports load/store access without being paged via the system page cache.
|
||
|
|
A Persistent Memory-aware file system is typically used to provide this
|
||
|
|
type of access.
|
||
|
|
.PP
|
||
|
|
The most convenient way to create pmem memkinds is to use
|
||
|
|
.BR memkind_create_pmem ()
|
||
|
|
(see
|
||
|
|
.BR memkind (3)).
|
||
|
|
.PP
|
||
|
|
.BR memkind_pmem_create ()
|
||
|
|
is an implementation of the memkind "create" operation for file-backed memory
|
||
|
|
kinds. This allocates a space for some pmem-specific metadata, then calls
|
||
|
|
.BR memkind_arena_create ()
|
||
|
|
(see
|
||
|
|
.BR memkind_arena (3))
|
||
|
|
.PP
|
||
|
|
.BR memkind_pmem_destroy ()
|
||
|
|
is an implementation of the memkind "destroy" operation for file-backed memory
|
||
|
|
kinds. This releases all of the resources
|
||
|
|
allocated by
|
||
|
|
.BR memkind_pmem_create ()
|
||
|
|
and allows the file system space to be reclaimed.
|
||
|
|
.PP
|
||
|
|
.BR memkind_pmem_mmap ()
|
||
|
|
allocates the file system space for a block of
|
||
|
|
.I size
|
||
|
|
bytes in the memory-mapped file associated with given kind.
|
||
|
|
The
|
||
|
|
.I addr
|
||
|
|
hint is ignored. The return value is the address of mapped memory region or
|
||
|
|
.B MAP_FAILED
|
||
|
|
in the case of an error.
|
||
|
|
.PP
|
||
|
|
.BR memkind_pmem_get_mmap_flags ()
|
||
|
|
sets
|
||
|
|
.I flags
|
||
|
|
to
|
||
|
|
.BR "MAP_SHARED" .
|
||
|
|
See
|
||
|
|
.BR mmap (2)
|
||
|
|
for more information about these flags.
|
||
|
|
.TP
|
||
|
|
.B MEMKIND_PMEM_CHUNK_SIZE
|
||
|
|
The size of the PMEM chunk size.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
Copyright (C) 2015 - 2018 Intel Corporation. All rights reserved.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR memkind (3),
|
||
|
|
.BR memkind_arena (3),
|
||
|
|
.BR memkind_default (3),
|
||
|
|
.BR memkind_hbw (3),
|
||
|
|
.BR memkind_hugetlb (3),
|
||
|
|
.BR libvmem (3),
|
||
|
|
.BR jemalloc (3),
|
||
|
|
.BR mbind (2),
|
||
|
|
.BR mmap (2)
|