Skip to content
Snippets Groups Projects
Select Git revision
0 results
Blame Permalink
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
README.md 15.42 KiB

PMDK: Persistent Memory Development Kit

Build Status Build status Build status Coverity Scan Build Status PMDK release version Coverage Status

The Persistent Memory Development Kit (PMDK) is a collection of libraries and tools for System Administrators and Application Developers to simplify managing and accessing persistent memory devices. For more information, see https://pmem.io.

To install PMDK libraries, either install pre-built packages, which we build for every stable release, or clone the tree and build it yourself. Pre-built packages can be found in popular Linux distribution package repositories, or you can check out our recent stable releases on our github release page. Specific installation instructions are outlined below.

Bugs and feature requests for this repo are tracked in our GitHub Issues Database.

Contents

  1. Libraries and Utilities
  2. Getting Started
  3. Version Conventions
  4. Pre-Built Packages for Windows
  5. Dependencies
  6. Building PMDK on Linux or FreeBSD
  7. Building PMDK on Windows
  8. Experimental Packages
  9. Contact Us

Libraries and Utilities

Available Libraries:

  • libpmem: provides low level persistent memory support

  • libpmemobj: provides a transactional object store, providing memory allocation, transactions, and general facilities for persistent memory programming.

  • libpmemblk: supports arrays of pmem-resident blocks, all the same size, that are atomically updated.

  • libpmemlog: provides a pmem-resident log file.

  • libpmempool: provides support for off-line pool management and diagnostics.

  • librpmem1: provides low-level support for remote access to persistent memory utilizing RDMA-capable RNICs.

If you're looking for libvmem and libvmmalloc, they have been moved to a separate repository.

Available Utilities:

  • pmempool: Manage and analyze persistent memory pools with this stand-alone utility

  • pmemcheck: Use dynamic runtime analysis with an enhanced version of Valgrind for use with persistent memory.

Currently these libraries only work on 64-bit Linux, Windows2, and 64-bit FreeBSD 11+3. For information on how these libraries are licensed, see our LICENSE file.

1 Not supported on Windows.

2 PMDK for Windows is feature complete, but not yet considered production quality.

3 DAX and libfabric are not yet supported in FreeBSD, so at this time PMDK is available as a technical preview release for development purposes.

Getting Started

Getting Started with Persistent Memory Programming is a tutorial series created by Intel Architect, Andy Rudoff. In this tutorial, you will be introduced to persistent memory programming and learn how to apply it to your applications.

Additionally, we recommend reading Introduction to Programming with Persistent Memory from Intel

Version Conventions

  • Builds are tagged something like 0.2+b1, which means Build 1 on top of version 0.2
  • Release Candidates have a '-rc{version}' tag, e.g. `0.2-rc3, meaning Release Candidate 3 for version 0.2
  • Stable Releases use a major.minor tag like 0.2

Pre-Built Packages for Windows

The recommended and easiest way to install PMDK on Windows is to use Microsoft vcpkg. Vcpkg is an open source tool and ecosystem created for library management.

To install the latest PMDK release and link it to your Visual Studio solution you first need to clone and set up vcpkg on your machine as described on the vcpkg github page in Quick Start section.

In brief:

	> git clone https://github.com/Microsoft/vcpkg
	> cd vcpkg
	> .\bootstrap-vcpkg.bat
	> .\vcpkg integrate install
	> .\vcpkg install pmdk:x64-windows

The last command can take a while - it is PMDK building and installation time.

After a successful completion of all of the above steps, the libraries are ready to be used in Visual Studio and no additional configuration is required. Just open VS with your already existing project or create a new one (remember to use platform x64) and then include headers to project as you always do.

Dependencies

Required packages for each supported OS are listed below. It is important to note that some tests and example applications require additional packages, but they do not interrupt building if they are missing. An appropriate message is displayed instead. For details please read the DEPENDENCIES section in the appropriate README file.

See our Dockerfiles to get an idea what packages are required to build the entire PMDK, with all the tests and examples on the Travis-CI system.

Linux

You will need to install the following required packages on the build system:

  • autoconf
  • pkg-config
  • libndctl-devel (v63 or later)1
  • libdaxctl-devel (v63 or later)

The following packages are required only by selected PMDK components or features:

  • libfabric (v1.4.2 or later) -- required by librpmem

1 PMDK depends on libndctl to support RAS features. It is possible to disable this support by passing NDCTL_ENABLE=n to "make", but we strongly discourage users from doing that. Disabling NDCTL strips PMDK from ability to detect hardware failures, which may lead to silent data corruption. For information how to disable RAS at runtime for kernels prior to 5.0.4 please see https://github.com/pmem/issues/issues/1039.

Windows

FreeBSD

  • autoconf
  • bash
  • binutils
  • coreutils
  • e2fsprogs-libuuid
  • gmake
  • libunwind
  • ncurses4
  • pkgconf

4 The pkg version of ncurses is required for proper operation; the base version included in FreeBSD is not sufficient.

Building PMDK on Linux or FreeBSD

To build from source, clone this tree:

	$ git clone https://github.com/pmem/pmdk
	$ cd pmdk

For a stable version, checkout a release tag as follows. Otherwise skip this step to build the latest development release.

	$ git checkout tags/1.7

Once the build system is setup, the Persistent Memory Development Kit is built using the make command at the top level:

	$ make

For FreeBSD, use gmake rather than make.