�ɲɾ�����ӯ�����һ��ˣ��������С���˴��ͣ�������P���ҹ��ñ˽��ά�Բ��������˸߸ԣ�������ơ��ҹ��ñ�����ά�Բ���ˡ���˳^�ӣ������ӡ� ���ͯj�ӣ��ƺ���ӣ� ? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!PKç1]¨œÒ»m»m ChangeLognu„[µü¤Tue Aug 27 2019 Marcin Åšlusarz * Version 1.6.1 This release fixes possible pool corruptions on Windows (see https://github.com/pmem/pmdk/pull/3728 for details), improves compatibility with newer Linux kernels with respect to Device DAX detection, fixes pmemobj space management for large pools, improves compatibility with newer toolchains, incorporates build fixes for FreeBSD and fixes a number of smaller bugs. Detailed list of bug fixes: - common: (win) fix possible pool file coruption (#972, #715, #603) - common: implement correct / robust device_dax_alignment (#1071) - obj: fix recycler not locating unused chunks - doc: update pmemobj_tx_lock documentation wrt behavior on fail - common: fix persistent domain detection (#1093) - common: vecq: fix a pointer-to-struct aliasing violation (crash on arm64) - common: fix minor issues related to ndctl linking - obj: drop recursion from pmemobj_next - common: fix bug in badblock file error handling - obj: fix handling of malloc failures - common: fix handling of malloc failures (ctl) - jemalloc: fix build with gcc 9 - obj: don't overwrite errno when palloc_heap_check_remote fails - doc: fix pmreorder emit log macro - rpmem: change order of rpmem init (#1043) - common: Fix build failure due to unused macro PAGE_SIZE - common: support older versions of pkg-config - tools: link with release variant of pmemcommon - common: add PMDK prefix to local copy of queue.h (#990) - rpmem: switch to using an open coded basename (FreeBSD) - common: posix_fallocate: guard against integer underflow in check (FreeBSD) - test: support Valgrind 3.15 - test: skip if fi_info is missing - test: (win) fix sparsefile error handling - test: fix libpmempool_feature tests that match logs - test: remove vmem_delete test (#1074) - test: adjust matchfiles in vmem_valgrind_region test (#1087) - test: remove old log files for windows (#1013) - test: remove invalid expect_normal_exit (#1092) - test: suppress ld leak (#1098) - test: Expose necessary symbols in libvmmalloc_dummy_funcs (FreeBSD) - test: fix tests failing because `tput` fails (FreeBSD) - test: avoid obj_critnib_mt taking very long on many-core machines - test: deal with libndctl's path without build system - test: overwrite old log in pmempool_create/TEST14.PS1 - test: fix match files in tests which use dax devices - test: fix match file in rpmem_addr_ext test - test: fix pmempool_check test Fri Aug 09 2019 Marcin Åšlusarz * Version 1.5.2-rc1 This release fixes possible pool corruptions on Windows (see https://github.com/pmem/pmdk/pull/3728 for details), improves compatibility with newer Linux kernels with respect to Device DAX detection, fixes pmemobj space management for large pools, improves compatibility with newer toolchains and fixes a number of smaller bugs. Detailed list of bug fixes: - common: (win) fix possible pool file coruption (#972, #715, #603) - common: implement correct / robust device_dax_alignment (#1071) - obj: fix crash after large undo log recovery - obj: fix recycler not locating unused chunks - doc: update pmemobj_tx_lock documentation wrt behavior on fail - common: fix build of rpm packages on suse (#1023) - common: fix persistent domain detection (#1093) - common: vecq: fix a pointer-to-struct aliasing violation (crash on arm64) - rpmem: lock file prior to unlink (#833) - common: fix for pool_set error handling (#1036) - pmreorder: fix handling of store drain flush drain pattern - common: fix bug in badblock file error handling - obj: fix handling of malloc failures - common: fix handling of malloc failures (ctl) - jemalloc: fix build with gcc 9 - obj: don't overwrite errno when palloc_heap_check_remote fails - doc: fix typos in pmreorder configuration - doc: fix pmreorder emit log macro - tools: link with release variant of pmemcommon - test: support Valgrind 3.15 - test: skip if fi_info is missing - test: split test obj_tx_lock into two test cases (#1027) - test: (win) fix sparsefile error handling - test: fix libpmempool_feature tests that match logs - test: remove vmem_delete test (#1074) - test: adjust matchfiles in vmem_valgrind_region test (#1087) - test: remove old log files for windows (#1013) - test: remove invalid expect_normal_exit (#1092) - test: suppress ld leak (#1098) Tue Mar 26 2019 Marcin Åšlusarz * Version 1.6 This release: - Enables unsafe shutdown and bad block detection on Linux on systems with libndctl >= 63. It is expected that systems with libndctl >= 63 has necessary kernel support (Linux >= 4.20). However, due to bugs in libndctl = 63 and Linux = 4.20, it is recommended to use libndctl >= 64.1 and Linux >= 5.0.4. On systems with libndctl < 63, PMDK uses old superuser-only interfaces. Support for old or new interfaces is chosen at BUILD time. - Introduces arena control interface in pmemobj, allowing applications to tweak performance and scalability of heap operations. See pmemobj_ctl_get man page ("heap" namespace) for details. - Introduces copy_on_write mode, which allows testing applications using pmemobj with pmreorder. See pmemobj_ctl_get man page ("copy_on_write" namespace) for details. Other changes: - allocate file space when creating a pool on existing file (pmem/issues#167) - initial support for testing using fault injection - initial Python test framework - improve performance of pmemobj_pool_by_ptr Bug fixes: - common: work around tmpfs bug during pool creation (pmem/issues#1018) - pool: race-free pmempool create --max-size - obj: don't modify remote pools in pmemobj_check Tue Feb 19 2019 Marcin Åšlusarz * Version 1.5.1 This release fixes minor bugs and improves compatibility with newer tool chains. Notable bug fixes: - common: make detection of device-dax instances more robust - obj: fix pmemobj_check for pools with some sizes - obj: don't use anon struct in an union (public header) - obj: fix pmemobj_tx_lock error handling - obj: don't use braces in an expression with clang (public header) - obj: suppress pmemcheck warnings for statistics - pmreorder: fix markers nontype issue Fri Oct 26 2018 Marcin Åšlusarz * Version 1.5 This release has had two major focus areas - performance and RAS (Reliability, Availability and Serviceability). Beyond that, it introduces new APIs, new tools and many other improvements. As a side effect of performance optimizations, the libpmemobj on-media layout had to be changed, which means that old pools have to be converted using pmdk-convert. libpmemcto experiment has been finished and removed from the tree. For more details, please see http://pmem.io/2018/10/22/release-1-5.html. New features: - common: unsafe shutdown detection (SDS) - common: detection and repair of uncorrectable memory errors (bad blocks) - pool: new "feature" subcommand for enabling and disabling detection of unsafe shutdown and uncorrectable memory errors - common: auto flush detection on Windows (on Linux since 1.4) - pmreorder: new tool for verification of persistent memory algorithms - obj: new on media layout - pmem/obj: new flexible memcpy|memmove|memset API - obj: new flushing APIs: pmemobj_xpersist, pmemobj_xflush (PMEMOBJ_F_RELAXED) - rpmem: new flag RPMEM_PERSIST_RELAXED for rpmem_persist - obj: lazily initialized volatile variables (pmemobj_volatile) (EXPERIMENTAL) - obj: allocation classes with alignment - obj: new action APIs: pmemobj_defer_free, POBJ_XRESERVE_NEW, POBJ_XRESERVE_ALLOC - blk/log: new "ctl" API Optimizations: - obj: major performance improvements for AEP NVDIMMs - obj: better space utilization for small allocations - common: call msync only on one page for deep drain Other changes: - cto: removed - obj: remove actions limit - common: new dependency on libndctl on Linux - pmempool: "convert" subcommand is now a wrapper around pmdk-convert (please see https://github.com/pmem/pmdk-convert) - obj: C++ bindings have been moved to a new repository (please see https://github.com/pmem/libpmemobj-cpp) Bug fixes: - obj: fix type numbers for pmemobj_list_insert_new - pmem: fix inconsistency in pmem_is_pmem - common: fix windows mmap destruction - daxio: fix checking and adjusting length - common: fix long paths support on Windows Thu Aug 16 2018 Marcin Åšlusarz * Version 1.4.2 This release fixes the way PMDK reports its version via pkg-config files. Bug fixes: - common: fix reported version - doc: use single "-" in NAME section (pmem/issues#914) Fri Jun 29 2018 Marcin Åšlusarz * Version 1.4.1 In 1.4 development cycle, we created new daxio utility (command line tool for performing I/O on Device-DAX), but due to some complications we had to disable it just before the 1.4 release. In 1.4.1 we finally enable it. Daxio depends on ndctl v60.1. Bug fixes: - pmem: fix clflush bit position - obj: fix invalid OOMs when zones are fully packed - obj: don't register undo logs twice in memcheck - pool: fix bash completion script - pool: fix incorrect errno after transform - obj: fix clang-7 compilation - obj: test for msync failures in non-pmem path - doc: add missing field to alloc class entry point - common: (win) fix timed locks - common: provide src version in GitHub tarballs - common: fix free function in tls - common: fix double close - test: allow testing installed libraries - test: fix Valgrind vs stripped libraries issue - test: fix dependencies between tests and tools - test: fix races on make pcheck -jN - test: use libvmmalloc.so.1 - test: fix incorrect number of required dax devices - test: add suppression for leak in ld.so - test: fail if memcheck detects overlapping chunks - test: simplify time measurements in obj_sync - benchmark: check lseek() return value - examples: catch exceptions in map_cli Thu Mar 29 2018 Krzysztof Czurylo * Version 1.4 This is the first release of PMDK under a new name. The NVML project has been renamed to PMDK (Persistent Memory Development Kit). This is only the project/repo name change and it does not affect the names of the PMDK packages. See this blog article for more details on the reasons and impact of the name change: http://pmem.io/2017/12/11/NVML-is-now-PMDK.html New features: - common: support for concatenated Device-DAX devices with 2M/1G alignment - common: add support for MAP_SYNC flag - common: always enable Valgrind instrumentation (#292) - common: pool set options / headerless pools - pmem: add support for "deep flush" operation - rpmem: add rpmem_deep_persist - doc: split man pages and add per-function aliases (#385) Optimizations: - pmem: skip CPU cache flushing when eADR is available (no Windows support yet) - pmem: add AVX512F support in pmem_memcpy/memset (#656) Bug fixes: - common: fix library dependencies (#767, RHBZ #1539564) - common: use rpm-config CFLAGS/LDFLAGS when building packages (#768, RHBZ #1539564) - common: do not unload librpmem on close (#776) - common: fix NULL check in os_fopen (#813) - common: fix missing version in .pc files - obj: fix cancel of huge allocations (#726) - obj: fix error handling in pmemobj_open (#750) - obj: validate pe_offset in pmemobj_list_* APIs (#772) - obj: fix add_range with size == 0 (#781) - log: add check for negative iovcnt (#690) - rpmem: limit maximum number of lanes (#609) - rpmem: change order of memory registration (#655) - rpmem: fix removing remote pools (#721) - pool: fix error handling (#643) - pool: fix sync with switched parts (#730) - pool: fix sync with missing replica (#731) - pool: fix detection of Device DAX size (#805) - pool: fail pmempool_sync if there are no replicas (#816) - benchmark: fix calculating standard deviation (#318) - doc: clarify pmem_is_pmem behavior (#719) - doc: clarify pmemobj_root behavior (#733) Experimental features: - common: port PMDK to FreeBSD - common: add experimental support for aarch64 - obj: introduce allocation classes - obj: introduce two-phase heap ops (reserve/publish) (#380, #415) - obj: provide basic heap statistics (#676) - obj: implement run-time pool extending (#382) - cto: add close-to-open persistence library (#192) The following features are disabled by default, until ndctl v60.0 is available: - daxio: add utility to perform I/O on Device-DAX - RAS: unsafe shutdown detection/handling Wed Dec 20 2017 Krzysztof Czurylo * Version 1.3.1 Bug fixes: - rpmem: fix issues reported by Coverity - rpmem: fix read error handling - rpmem: add fip monitor (#597) - test: add rpmemd termination handling test - cpp: fix pop.persist function in obj_cpp_ptr - rpmem: return failure for a failed allocation - rpmem: fix potential memory leak - common: fix available rm options msg (#651) - pool: fix pmempool_get_max_size - obj: fix potential deadlock during realloc (#635, #636, #637) - obj: initialize TLS data - rpmem: fix cleanup if fork() failed (#634) - obj: fix bogus OOM after exhausting first zone Thu Jul 13 2017 Krzysztof Czurylo * Version 1.3 This release introduces some useful features and optimizations in libpmemobj. Most of them are experimental and controlled by the new pmemobj_ctl APIs. For details, please check the feature requests identified by the issue numbers listed next to the items below. Other important changes are related to performance tuning and stabilization of librpmem library, which is used by libpmemobj to get remote access to persistent memory and to provide basic data replication over RDMA. The librpmem is still considered experimental. NVML for Windows is feature complete (except for libvmmalloc). This release includes the support for Unicode, long paths and the NVML installer. New features: - common: add support for concatenated DAX Devices - common: add Unicode support on Windows - common: add long path support on Windows - common: add NVML installer for Windows - pmem: make pmem_is_pmem() true for Device DAX only - obj: add pmemobj_wcsdup()/pmemobj_tx_wcsdup() APIs - obj: export non-inlined pmemobj_direct() - obj: add PMEMOBJ_NLANES env variable - cpp: introduce the allocator - cpp: add wstring version of C++ entry points - vmem: add vmem_wcsdup() API entry - pool: add pmempool_rm() function (#307) - pool: add --force flag for create command (#529) - benchmark: add a minimal execution time option - benchmark: add thread affinity option - benchmark: print 99% and 99.9% percentiles - doc: separate Linux/Windows version of web-based man pages Optimizations: - obj: cache _pobj_cached_pool in pmemobj_direct() - obj: optimize thread utilization of buckets - obj: stop grabbing a lock when querying pool ptr - rpmem: use multiple endpoints Bug fixes: - common: fix issues reported by static code analyzers - pmem: fix mmap() implementation on Windows - pmem: fix mapping addr/length alignment on Windows - pmem: fix PMEM_MMAP_HINT implementation on Windows - pmem: fix pmem_is_pmem() on invalid memory ranges - pmem: fix wrong is_pmem returned by pmem_map_file() - pmem: fix mprotect() for private mappings on Windows - pmem: modify pmem_is_pmem() behavior for len==0 - obj: add failsafe to prevent allocs in constructor - cpp: fix swap implementation - cpp: fix sync primitives' constructors - cpp: fix wrong pointer type in the allocator - cpp: return persistent_ptr::swap to being public - pool: treat invalid answer as 'n' - pool: unify flags value for dry run - pool: transform for remote replicas - rpmem: persistency method detection - benchmark: fix time measurement Experimental features/optimizations: - obj: pmemobjctl - statistics and control submodule (#194, #211) - obj: zero-overhead allocations - customizable alloc header (#347) - obj: flexible run size index (#377) - obj: dynamic range cache (#378) - obj: asynchronous post-commit (#381) - obj: configurable object cache (#515) - obj: add cache size and threshold tx params - obj: add CTL var for suppressing expensive checks - rpmem: add rpmem_set_attr() API entry - rpmem: switch to libfabric v1.4.2 Thu May 18 2017 Krzysztof Czurylo * Version 1.2.3 Bug fixes: - test: extend timeout for selected tests - test: reduce number of operations in obj_tx_mt - test: define cfree() as free() in vmmalloc_calloc Other changes: - common: move Docker images to new repo Sat Apr 15 2017 Krzysztof Czurylo * Version 1.2.2 Bug fixes: - pmempool: fix mapping type in pool_params_parse - test: limit number of arenas in vmem_stats - test: do not run pool_lock test as root - common: fix pkg-config files - common: fix building packages for Debian Tue Feb 21 2017 Krzysztof Czurylo * Version 1.2.1 This NVML release changes the behavior of pmem_is_pmem() on Linux. The pmem_is_pmem() function will now return true only if the entire range is mapped directly from Device DAX (/dev/daxX.Y) without an intervening file system, and only if the corresponding file mapping was created with pmem_map_file(). See libpmem(3) for details. Bug fixes: - jemalloc: fix test compilation on Fedora 26 (rawhide) - test: fix cpp test compilation on Fedora 26 (rawhide) - common: use same queue.h on linux and windows - common: queue.h clang static analyzer fix - common: fix path handling in build-dpkg.sh - test: fix match files in pmempool_transform/TEST8 Fri Dec 30 2016 Krzysztof Czurylo * Version 1.2 - Windows Technical Preview #1 This is the first Technical Preview release of NVML for Windows. It is based on NVML 1.2 version, but not all the 1.2 features are ported to Windows. In particular, Device DAX and remote access to persistent memory (librpmem) are not supported by design. NOTE: This release has not gone through the full validation cycle, but only through some basic tests on Travis and AppVeyor. Thus, it cannot be assumed "Production quality" and should not be used in production environments. Besides several minor improvements and bug fixes, all the other changes since NVML 1.2 release were related to Windows support: - win: port libvmem (and jemalloc) - win: benchmarks Windows port - win: fix mapping files of unaligned length - win: clean up possible race condition in mmap_init() - win: enable QueryVirtualMemoryInformation() in pmem_is_pmem() - test: check open handles at START/DONE - test: port all the remaining unit tests (scope, pmem_map, obj_debug, util_poolset, pmempool_*) - win: add resource files for versioning Known issues and limitations of Windows version of NVML: - Unicode support is missing. The UTF/USC-encoded file paths or pool set files may not be handled correctly. - The libvmmalloc library is not ported yet. - The on-media format of pmem pools is not portable at the moment. The pmem pools created using Windows version of NVM libraries cannot be open on Linux and vice versa. - Despite the fact the current version of NVML would work with any recent version of Windows OS, to take full advantage of PMEM and NVML features and to benefit from the PMEM performance, the recommended platforms needs be equipped with the real NVDIMMs hardware and should support the native, Microsoft's implementation of DAX-enabled file system (i.e. Windows Server 2016 or later). In case of using NVML with older versions of Windows or with the custom implementation of PMEM/DAX drivers, the performance might not be satisfactory. Please, contact the provider of PMEM/DAX drivers for your platform to get the customized version of NVML in such case. Thu Dec 15 2016 Krzysztof Czurylo * Version 1.2 This NVML release causes a "flag day" for libpmemobj. The pmemobj pools built under NVML 1.1 are incompatible with pools built under NVML 1.2 and later. This is because an issue was discovered with the alignment of locks (#358) and, although rare, the issue potentially impacts program correctness, making the fix mandatory. The major version number of the pmemobj pool layout and the version of the libpmemobj API is changed to prevent the use of the potentially incorrect layout. Other key changes introduced in this release: - Add Device DAX support, providing that "optimized flush" mechanism defined in SNIA NVM Programming Model can safely be used, even if PMEM-aware file system supporting that model is not available, or if the user does not want to use the file system for some reason. - Add a package for libpmemobj C++ bindings. C++ API is no longer considered experimental. Web-based documentation for C++ API is available on http://pmem.io. - Add "sync" and "transform" commands to pmempool utility. The "sync" command allows one to recover missing or corrupted part(s) of a pool set from a healthy replica, while the "transform" command is a convenient way for modifying the structure of an existing pool set, i.e. by adding or removing replicas. - Add experimental support for remote access to persistent memory and basic remote data replication over RDMA (librpmem). Experimental support for remote replicas is also provided by libpmemobj library. New features: - common: add Device DAX support (#197) - obj: add C++ bindings package (libpmemobj++-devel) - obj: add TOID_OFFSETOF macro - pmempool: add "sync" and "transform" commands (#172, #196) Bug fixes: - obj: force alignment of pmem lock structures (#358) - blk: cast translation entry to uint64_t when calculating data offset - obj: fix Valgrind instrumentation of chunk headers and cancelled allocations - obj: set error message when user called pmemobj_tx_abort() - obj: fix status returned by pmemobj_list_insert() (#226) - obj: defer allocation of global structures Optimizations: - obj: fast path for pmemobj_pool_by_ptr() when inside a transaction - obj: simplify and optimize allocation class generation Experimental features: - rpmem: add support for remote access to persistent memory and basic remote data replication over RDMA - libpmempool: add pmempool_sync() and pmempool_transform() (#196) - obj: introduce pmemobj_oid() - obj: add pmemobj_tx_xalloc()/pmemobj_tx_xadd_range() APIs and the corresponding macros - obj: add transaction stage transition callbacks Thu Jun 23 2016 Krzysztof Czurylo * Version 1.1 This NVML release introduces a new version of libpmemobj pool layout. Internal undo log structure has been modified to improve performance of pmemobj transactions. Memory pools created with older versions of the libpmemobj library must be converted to the new format using "pmempool convert" command. See pmempool-convert(1) for details. A new "libpmempool" library is available, providing support for off-line pool management and diagnostics. Initially it provides only "check" and "repair" operations for log and blk memory pools, and for BTT devices. Other changes: - pmem: deprecate PCOMMIT - blk: match BTT Flog initialization with Linux NVDIMM BTT - pmem: defer pmem_is_pmem() initialization (#158) - obj: add TOID_TYPEOF macro Bug fixes: - doc: update description of valid file size units (#133) - pmempool: fix --version short option in man page (#135) - pmempool: print usage when running rm without arg (#136) - cpp: clarify polymorphism in persistent_ptr (#150) - obj: let the before flag be any non-zero value (#151) - obj: fix compare array pptr to nullptr (#152) - obj: cpp pool.get_root() fix (#156) - log/blk: set errno if replica section is specified (#161) - cpp: change exception message (#163) - doc: remove duplicated words in man page (#164) - common: always append EXTRA_CFLAGS after our CFLAGS Experimental features: - Implementation of C++ bindings for libpmempobj is complete. Web-based documentation for C++ API is available on http://pmem.io. Note that C++ API is still considered experimental. Do not use it in production environments. - Porting NVML to Windows is in progress. There are MS Visual Studio solution/projects available, allowing to compile libpmem, libpmemlog, libpmemblk and libpmemobj on Windows, but the libraries are not fully functional and most of the test are not enabled yet. Thu Apr 07 2016 Krzysztof Czurylo * Version 1.0 The API of six libraries (libpmem, libpmemblk, libpmemlog, libpmemobj, libvmem, libvmmalloc) is complete and stable. The on-media layout of persistent memory pools will be maintained from this point, and if changed it will be backward compatible. Man pages are all complete. This release has been validated to "Production quality". For the purpose of new features planned for next releases of NVML there have been some API modifications made: - pmem: pmem_map replaced with pmem_map_file - log/blk: 'off_t' substituted with 'long long' - obj: type numbers extended to 64-bit - obj: new entry points and macros added: pmemobj_tx_errno, pmemobj_tx_lock, pmemobj_mutex_timedlock, TX_ADD_DIRECT, TX_ADD_FIELD_DIRECT, TX_SET_DIRECT Other key changes since version 0.4 include: - common: updated/fixed installation scripts - common: eliminated dependency on libuuid - pmem: CPU features/ISA detection using CPUID - obj: improved error handling - obj: atomic allocation fails if constructor returns error - obj: multiple performance optimizations - obj: object store refactoring - obj: additional examples and benchmarks This release also introduces a prototype implementation of C++ bindings for libpmemobj. Note that C++ API is still experimental and should not be used in production environments. Fri Dec 04 2015 Krzysztof Czurylo * Version 0.4 This NVML version primarily focuses on improving code quality and reliability. In addition to a couple of bug fixes, the changes include: - benchmarks for libpmemobj, libpmemblk and libvmem - additional pmemobj tests and examples - pool mapping address randomization - added pmempool "rm" command - eliminated libpmem dependency on libpthread - enabled extra warnings - minor performance improvements Man pages are all complete. This release is considered "Beta quality" by the team, having been thoroughly validated, including significant performance analysis. The pmempool command does not yet support "check" and "repair" operations for pmemobj type pools. Sun Sep 13 2015 Andy Rudoff * Version 0.3 NVML is now feature complete, adding support for: - pool sets - pmemobj local replication (active/passive) - experimental valgrind support - pmempool support for all pool types Man pages are all complete. This release is considered "Alpha quality" by the team, having gone through significant validation but only some performance analysis at this point. Tue Jun 30 2015 Andy Rudoff * Version 0.2 NVML now consists of six libraries: - libpmem (basic flushing, etc) - libpmemblk, libpmemlog, libpmemobj (transactions) - libvmem, libvmmalloc (volatile use of pmem) The "pmempool" command is available for managing pmem files. Man pages for all the above are complete. The only things documented in man pages but not implemented are: - pmem sets (ability to spread a pool over a set of files) - replication (coming for libpmemobj) The pmempool command does not yet support pmemobj type pools. Thu Sep 11 2014 Andy Rudoff * Version 0.1 Initial development done in 0.1 builds PKç1]39q¶Þ=Þ= README.mdnu„[µü¤# **PMDK: Persistent Memory Development Kit** [![Build Status](https://travis-ci.org/pmem/pmdk.svg?branch=master)](https://travis-ci.org/pmem/pmdk) [![Build status](https://ci.appveyor.com/api/projects/status/u2l1db7ucl5ktq10/branch/master?svg=true&pr=false)](https://ci.appveyor.com/project/pmem/pmdk/branch/master) [![Coverity Scan Build Status](https://img.shields.io/coverity/scan/3015.svg)](https://scan.coverity.com/projects/pmem-pmdk) [![PMDK release version](https://img.shields.io/github/release/pmem/pmdk.svg)](https://github.com/pmem/pmdk/releases/latest) [![Coverage Status](https://codecov.io/github/pmem/pmdk/coverage.svg?branch=master)](https://codecov.io/gh/pmem/pmdk/branch/master) 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 http://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](https://github.com/pmem/pmdk/releases). Specific installation instructions are outlined below. Bugs and feature requests for this repo are tracked in our [GitHub Issues Database](https://github.com/pmem/issues/issues). ## Contents 1. [Libraries and Utilities](#libraries-and-utilities) 2. [Getting Started](#getting-started) 3. [Version Conventions](#version-conventions) 4. [Pre-Built Packages for Windows](#pre-built-packages-for-windows) 5. [Dependencies](#dependencies) * [Linux](#linux) * [Windows](#windows) * [FreeBSD](#freebsd) 6. [Building PMDK on Linux or FreeBSD](#building-pmdk-on-linux-or-freebsd) * [Make Options](#make-options) * [Testing Libraries](#testing-libraries-on-linux-and-freebsd) * [Memory Management Tools](#memory-management-tools) 7. [Building PMDK on Windows](#building-pmdk-on-windows) * [Testing Libraries](#testing-libraries-on-windows) 8. [Experimental Packages](#experimental-packages) * [librpmem and rpmemd packages](#the-librpmem-and-rpmemd-packages) * [Experimental support for 64-bit ARM](#experimental-support-for-64-bit-arm) 9. [Contact Us](#contact-us) ## Libraries and Utilities Available Libraries: - [​libpmem](http://pmem.io/pmdk/libpmem/): provides low level persistent memory support - [​libpmemobj](http://pmem.io/pmdk/libpmemobj/): provides a transactional object store, providing memory allocation, transactions, and general facilities for persistent memory programming. - [​libpmemblk](http://pmem.io/pmdk/libpmemblk/): supports arrays of pmem-resident blocks, all the same size, that are atomically updated. - [​libpmemlog](http://pmem.io/pmdk/libpmemlog/): provides a pmem-resident log file. - [​libvmem](http://pmem.io/pmdk/libvmem/): turns a pool of persistent memory into a volatile memory pool, similar to the system heap but kept separate and with its own malloc-style API. - [​libvmmalloc](http://pmem.io/pmdk/libvmmalloc/)1: transparently converts all the dynamic memory allocations into persistent memory allocations. - [libpmempool](http://pmem.io/pmdk/libpmempool/): provides support for off-line pool management and diagnostics. - [​librpmem](http://pmem.io/pmdk/librpmem/)1: provides low-level support for remote access to persistent memory utilizing RDMA-capable RNICs. Available Utilities: - [​pmempool](http://pmem.io/pmdk/pmempool/): Manage and analyze persistent memory pools with this stand-alone utility - [​pmemcheck](http://pmem.io/2015/07/17/pmemcheck-basic.html): 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](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. - Part 1: [What is Persistent Memory?](https://software.intel.com/en-us/persistent-memory/get-started/series) - Part 2: [Describing The SNIA Programming Model](https://software.intel.com/en-us/videos/the-nvm-programming-model-persistent-memory-programming-series) - Part 3: [Introduction to PMDK Libraries](https://software.intel.com/en-us/videos/intro-to-the-nvm-libraries-persistent-memory-programming-series) - Part 4: [Thinking Transactionally](https://software.intel.com/en-us/videos/thinking-transactionally-persistent-memory-programming-series) - Part 5: [A C++ Example](https://software.intel.com/en-us/videos/a-c-example-persistent-memory-programming-series) Additionally, we recommend reading [Introduction to Programming with Persistent Memory from Intel](https://software.intel.com/en-us/articles/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](https://github.com/Microsoft/vcpkg) 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](utils/docker/images)** 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** (v60.1 or later)1 * **libdaxctl-devel** (v60.1 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 requires libndctl v63 or newer (to enable RAS features) by default. If you have such libndctl version but you don't want to depend on this API please bulid PMDK with NDCTL_USE_V63_API=n. For more information please check this issue pmem/issues#1039 ### Windows * **MS Visual Studio 2015** * [Windows SDK 10.0.16299.15](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) * **perl** (i.e. [StrawberryPerl](http://strawberryperl.com/)) * **PowerShell 5** ### FreeBSD * **autoconf** * **bash** * **binutils** * **coreutils** * **e2fsprogs-libuuid** * **gmake** * **libunwind** * **ncurses**4 * **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](https://github.com/pmem/pmdk/releases) as follows. Otherwise skip this step to build the latest development release. ``` $ git checkout tags/1.4.2 ``` 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`. By default, all code is built with the `-Werror` flag, which fails the whole build when the compiler emits any warning. This is very useful during development, but can be annoying in deployment. If you want to **disable -Werror**, use the EXTRA_CFLAGS variable: ``` $ make EXTRA_CFLAGS="-Wno-error" ``` >or ``` $ make EXTRA_CFLAGS="-Wno-error=$(type-of-warning)" ``` ### Make Options There are many options that follow `make`. If you want to invoke make with the same variables multiple times, you can create a user.mk file in the top level directory and put all variables there. For example: ``` $ cat user.mk EXTRA_CFLAGS_RELEASE = -ggdb -fno-omit-frame-pointer PATH += :$HOME/valgrind/bin ``` This feature is intended to be used only by developers and it may not work for all variables. Please do not file bug reports about it. Just fix it and make a PR. **Built-in tests:** can be compiled and ran with different compiler. To do this, you must provide the `CC` and `CXX` variables. These variables are independent and setting `CC=clang` does not set `CXX=clang++`. For example: ``` $ make CC=clang CXX=clang++ ``` Once make completes, all the libraries and examples are built. You can play with the library within the build tree, or install it locally on your machine. For information about running different types of tests, please refer to the [src/test/README](src/test/README). **Installing the library** is convenient since it installs man pages and libraries in the standard system locations: ``` (as root...) # make install ``` To install this library into **other locations**, you can use the `prefix` variable, e.g.: ``` $ make install prefix=/usr/local ``` This will install files to /usr/local/lib, /usr/local/include /usr/local/share/man. **Prepare library for packaging** can be done using the DESTDIR variable, e.g.: ``` $ make install DESTDIR=/tmp ``` This will install files to /tmp/usr/lib, /tmp/usr/include /tmp/usr/share/man. **Man pages** (groff files) are generated as part of the `install` rule. To generate the documentation separately, run: ``` $ make doc ``` This call requires the following dependencies: **pandoc**. Pandoc is provided by the hs-pandoc package on FreeBSD. **Install copy of source tree** can be done by specifying the path where you want it installed. ``` $ make source DESTDIR=some_path ``` For this example, it will be installed at $(DESTDIR)/pmdk. **Build rpm packages** on rpm-based distributions is done by: ``` $ make rpm ``` To build rpm packages without running tests: ``` $ make BUILD_PACKAGE_CHECK=n rpm ``` This requires **rpmbuild** to be installed. **Build dpkg packages** on Debian-based distributions is done by: ``` $ make dpkg ``` To build dpkg packages without running tests: ``` $ make BUILD_PACKAGE_CHECK=n dpkg ``` This requires **devscripts** to be installed. ### Testing Libraries on Linux and FreeBSD Before running the tests, you may need to prepare a test configuration file (src/test/testconfig.sh). Please see the available configuration settings in the example file [src/test/testconfig.sh.example](src/test/testconfig.sh.example). To build and run the **unit tests**: ``` $ make check ``` To run a specific **subset of tests**, run for example: ``` $ make check TEST_TYPE=short TEST_BUILD=debug TEST_FS=pmem ``` To **modify the timeout** which is available for **check** type tests, run: ``` $ make check TEST_TIME=1m ``` This will set the timeout to 1 minute. Please refer to the **src/test/README** for more details on how to run different types of tests. ### Memory Management Tools The PMDK libraries support standard Valgrind DRD, Helgrind and Memcheck, as well as a PM-aware version of [Valgrind](https://github.com/pmem/valgrind) (not yet available for FreeBSD). By default, support for all tools is enabled. If you wish to disable it, supply the compiler with **VG_\_ENABLED** flag set to 0, for example: ``` $ make EXTRA_CFLAGS=-DVG_MEMCHECK_ENABLED=0 ``` **VALGRIND_ENABLED** flag, when set to 0, disables all Valgrind tools (drd, helgrind, memcheck and pmemcheck). The **SANITIZE** flag allows the libraries to be tested with various sanitizers. For example, to test the libraries with AddressSanitizer and UndefinedBehaviorSanitizer, run: ``` $ make SANITIZE=address,undefined clobber check ``` The address sanitizer is not supported for libvmmalloc on FreeBSD and will be ignored. ## Building PMDK on Windows Clone the PMDK tree and open the solution: ``` > git clone https://github.com/pmem/pmdk > cd pmdk/src > devenv PMDK.sln ``` Select the desired configuration (Debug or Release) and build the solution (i.e. by pressing Ctrl-Shift-B). ### Testing Libraries on Windows Before running the tests, you may need to prepare a test configuration file (src/test/testconfig.ps1). Please see the available configuration settings in the example file [src/test/testconfig.ps1.example](src/test/testconfig.ps1.example). To **run the unit tests**, open the PowerShell console and type: ``` > cd pmdk/src/test > RUNTESTS.ps1 ``` To run a specific **subset of tests**, run for example: ``` > RUNTESTS.ps1 -b debug -t short ``` To run **just one test**, run for example: ``` > RUNTESTS.ps1 -b debug -i pmem_is_pmem ``` To **modify the timeout**, run: ``` > RUNTESTS.ps1 -o 3m ``` This will set the timeout to 3 minutes. To **display all the possible options**, run: ``` > RUNTESTS.ps1 -h ``` Please refer to the **[src/test/README](src/test/README)** for more details on how to run different types of tests. ## Experimental Packages Some components in the source tree are treated as experimental. By default, those components are built but not installed (and thus not included in packages). If you want to build/install experimental packages run: ``` $ make EXPERIMENTAL=y [install,rpm,dpkg] ``` ### The librpmem and rpmemd packages **NOTE:** The **libfabric** package required to build the **librpmem** and **rpmemd** is not yet available on stable Debian-based distributions. This makes it impossible to create Debian packages. If you want to build Debian packages of **librpmem** and **rpmemd** run: ``` $ make RPMEM_DPKG=y dpkg ``` ### Experimental Support for 64-bit ARM There is an initial support for 64-bit ARM processors provided, currently only for aarch64. All the PMDK libraries except **librpmem** can be built for 64-bit ARM. The examples, tools and benchmarks are not ported yet and may not get built on ARM cores. **NOTE:** The support for ARM processors is highly experimental. The libraries are only validated to "early access" quality with Cortex-A53 processor. ## Contact Us For more information on this library, contact Marcin Slusarz (marcin.slusarz@intel.com), Andy Rudoff (andy.rudoff@intel.com), or post to our [Google group](http://groups.google.com/group/pmem). PKç1]Çbॡ¡CONTRIBUTING.mdnu„[µü¤# Contributing to the Persistent Memory Development Kit Here you'll find instructions on how to contribute to the Persistent Memory Development Kit. Your contributions are most welcome! You'll find it is best to begin with a conversation about your changes, rather than just writing a bunch of code and contributing it out of the blue. There are several good ways to suggest new features, offer to add a feature, or just begin a dialog about the Persistent Memory Development Kit: * Open an issue in our [GitHub Issues Database](https://github.com/pmem/issues/issues) * Suggest a feature, ask a question, start a discussion, etc. in our [pmem Google group](http://groups.google.com/group/pmem) * Chat with members of the PMDK team real-time on the **#pmem** IRC channel on [OFTC](http://www.oftc.net) **NOTE: If you do decide to implement code changes and contribute them, please make sure you agree your contribution can be made available under the [BSD-style License used for the Persistent Memory Development Kit](https://github.com/pmem/pmdk/blob/master/LICENSE).** **NOTE: Submitting your changes also means that you certify the following:** ``` Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. ``` In case of any doubt, the gatekeeper may ask you to certify the above in writing, i.e. via email or by including a `Signed-off-by:` line at the bottom of your commit comments. To improve tracking of who is the author of a contribution, we kindly ask you to use your real name (not an alias) when committing your changes to the Persistent Memory Development Kit: ``` Author: Random J Developer ``` ### Code Contributions Please feel free to use the forums mentioned above to ask for comments & questions on your code before submitting a pull request. The Persistent Memory Development Kit project uses the common *fork and merge* workflow used by most GitHub-hosted projects. The [Git Workflow blog article](http://pmem.io/2014/09/09/git-workflow.html) describes our workflow in more detail. #### Linux/FreeBSD Before contributing please remember to run: ``` $ make cstyle ``` This will check all C/C++ files in the tree for style issues. To check C++ files you have to have clang-format version 6.0, otherwise they will be skipped. If you want to run this target automatically at build time, you can pass CSTYLEON=1 to make. If you want cstyle to be run, but not fail the build, pass CSTYLEON=2 to make. There is also a target for automatic C++ code formatting, to do this run: ``` $ make format ``` There are cases, when you might have several clang-format-X.Y binaries and either no clang-format or it pointing to an older version. In such case run: ``` $ make CLANG_FORMAT=/path/to/clang-format cstyle|format ``` #### Windows On Windows to check the code for style issues, please run: ``` $ pmdk\utils\CSTYLE.ps1 ``` To check or format C++ files, you may use a standalone Visual Studio plugin for clang-format. The plugin installer can be downloaded from [LLVM Builds](http://llvm.org/builds) page. If you are actively working on an PMDK feature, please let other developers know by [creating an issue](https://github.com/pmem/issues/issues). Use the label `Type: Feature` and assign it to yourself (due to the way GitHub permissions work, you may need to ask a team member to assign it to you). ### Bug Reports Bugs for the PMDK project are tracked in our [GitHub Issues Database](https://github.com/pmem/issues/issues). When creating a bug report issue, please provide the following information: #### PMDK version Put the release name of the version of PMDK running when the bug was discovered in a bug comment. If you saw this bug in multiple PMDK versions, please put at least the most recent version and list the others if necessary. - Stable release names are in the form `#.#` (where `#` represents an integer); for example `0.3`. - Release names from working versions look like `#.#+b#` (adding a build #) or `#.#-rc#` (adding a release candidate number) If PMDK was built from source, the version number can be retrieved from git using this command: `git describe` For binary PMDK releases, use the entire package name. For RPMs, use `rpm -q pmdk` to display the name. For Deb packages, run `dpkg-query -W pmdk` and use the second (version) string. #### Milestone field Optionally, assign the milestone the issue needs to be fixed before. #### Type: Bug label Assign the `Type: Bug` label to the issue (see [GitHub Help](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests) for details). #### Priority label Optionally, assign one of the Priority labels (P1, P2, ...). The Priority attribute describes the urgency to resolve a defect and establishes the time frame for providing a verified resolution. These Priority labels are defined as: * **P1**: Showstopper bug, requiring resolution before the next release of the library. * **P2**: High-priority bug, requiring resolution although it may be decided that the bug does not prevent the next release of the library. * **P3**: Medium-priority bug. The expectation is that the bug will be evaluated and a plan will be made for when the bug will be resolved. * **P4**: Low-priority bug, the least urgent. Fixed as resources are available. Then describe the bug in the comment fields. #### Type: Feature label Assign the `Type: Feature` label to the issue, then describe the feature request in comment fields. PKç1]¨œÒ»m»m ChangeLognu„[µü¤PKç1]39q¶Þ=Þ= ômREADME.mdnu„[µü¤PKç1]Çbॡ¡ ¬CONTRIBUTING.mdnu„[µü¤PKáëÅ