.\" SPDX-License-Identifier: BSD-2-Clause
.\" Copyright (C) 2014 - 2020 Intel Corporation.
.\"
.TH "MEMKIND_PMEM" 3 "2015-04-21" "Intel Corporation" "MEMKIND_PMEM" \" -*- nroff -*-
.SH "NAME"
memkind_pmem \- file-backed memory memkind operations.
.br
.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"
.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
.BI "int memkind_pmem_validate_dir(const char " "*dir" );
.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 kinds are most useful when used with DAX (direct mapping of persistent memory), 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 kinds is to use
.BR memkind_create_pmem ()
or
.BR memkind_create_pmem_with_config ()
(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.
.PP
.BR memkind_pmem_validate_dir ()
returns zero if file created in specified
.I pmem_dir
supports DAX (direct mapping of persistent memory) or an error code from the
.B ERRORS
if
not.
.TP
.B MEMKIND_PMEM_CHUNK_SIZE
The size of the PMEM chunk size.
.SH "COPYRIGHT"
Copyright (C) 2015 - 2020 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)