diff --git a/doc/libpmem2/libpmem2.7.md b/doc/libpmem2/libpmem2.7.md index 88d221a6dd21a41fb5d7caf80713ba13d083c883..b139e03752e15e32fdd809712c8fca9d1486a9c2 100644 --- a/doc/libpmem2/libpmem2.7.md +++ b/doc/libpmem2/libpmem2.7.md @@ -36,6 +36,81 @@ cc ... -lpmem2 # DESCRIPTION # +**libpmem2** provides low-level *persistent memory* (pmem) support for +applications using direct access storage (DAX), which is storage that +supports load/store access without paging blocks from a block storage +device. Some types of *non-volatile memory DIMMs* (NVDIMMs) provide this +type of byte addressable access to storage. A *persistent memory aware +file system* is typically used to expose the direct access to +applications. Memory mapping a file from this type of file system +results in the load/store, non-paged access to pmem. + +This library is for applications that use persistent memory directly, +without the help of any library-supplied transactions or memory +allocation. Higher-level libraries that *currently* build on **libpmem** +(previous variation of libpmem2) are available and are recommended for +most applications, see: + ++ **libpmemobj**(7), a general use persistent memory API, providing memory + allocation and transactional operations on variable-sized objects. + ++ **libpmemblk**(7), providing pmem-resident arrays of fixed-sized blocks + with atomic updates. + ++ **libpmemlog**(7), providing a pmem-resident log file. + +The **libpmem2** library provides a comprehensive set of functions for +robust use of Persistent Memory. It relies on three core concepts: +*struct pmem2_src source*, *struct pmem2_config config* and *struct pmem2_map map*: + +* *source* - an object describing the data source for mapping. +The data source can be a file descriptor, a file handle, or an anonymous mapping. +API dedicated to create a *source* is: **pmem2_source_from_fd**(3), + **pmem2_source_from_handle**(3), **pmem2_source_from_anon**(3). + +* *config* - an object containing parameters that are used to create a mapping from a *source*. +The configuration structure must always be provided to create a mapping, +but the only required parameter to set in the *config* is a *granularity*. +The granularity should by set using dedicated **libpmem2** function +**pmem2_config_set_required_store_granularity**(3) which defines a maximum permitted +granularity requested by the user. For more information about the granularity concept +read **GRANULARITY** section below. + +In addition to the granularity setting, libpmem2 provides multiple optional +functions to configure target mapping, eg. **pmem2_config_set_length**(3) +to set length which will be used for mapping, or **pmem2_config_set_offset**(3) +which will be used to map the contents from the specified location of the source, +**pmem2_config_set_sharing**(3) which defines the behavior and visibility of writes +to the mapping's pages. + +* *map* - an object created by **pmem2_map_new**(3) using *source* and +*config* as an input parameters. The map structure can be then used to +directly operate on the created mapping through the use of its associated +set of functions: **pmem2_map_get_address**(3), **pmem2_map_get_size**(3), +**pmem2_map_get_store_granularity**(3) - for getting address, +size and effective mapping granularity. + +In addition to the basic functionality of managing the virtual address mapping, +**libpmem2** also provides optimized functions for modifying the mapping data. +This includes data flushing as well as memory copying. + +To get proper function for data flushing use: **pmem2_get_flush_fn**(3), +**pmem2_get_persist_fn**(3) or **pmem2_get_drain_fn**(3). +To get proper function for copying to persistent memory, use *map* getters: +**pmem2_get_memcpy_fn**(3), **pmem2_get_memset_fn**(3), **pmem2_get_memmove_fn**(3). + +The **libpmem2** API also provides support for the badblock and unsafe shutdown +state handling. + +To read or clear badblocks, the following functions are provided: +**pmem2_badblock_context_new**(3), **pmem2_badblock_context_delete**(3), +**pmem2_badblock_next**(3) and **pmem2_badblock_clear**(3). + +To handle unsafe shutdown in the application, the following functions are provided: +**pmem2_source_device_id**(3), **pmem2_source_device_usc**(3). +More detailed information about unsafe shutdown detection and unsafe shutdown count +and can be found in the [libpmem2_unsafe_shutdown](https://pmem.io/pmdk/manpages/linux/master/libpmem2/libpmem2_unsafe_shutdown.7.html) man page. + # GRANULARITY # The **libpmem2** library introduces the concept of granularity through which you @@ -79,6 +154,8 @@ set this value to **PMEM2_GRANULARITY_PAGE**. # CAVEATS # +**libpmem2** relies on the library destructor being called from the main thread. For this reason, all functions that might trigger destruction (e.g. dlclose(3)) should be called in the main thread. Otherwise some of the resources associated with that thread might not be cleaned up properly. + # ENVIRONMENT # **libpmem2** can change its default behavior based on the following @@ -193,6 +270,18 @@ written to *stderr*. # EXAMPLE # +The following example uses **libpmem2** to flush changes made to raw, +memory-mapped persistent memory. + +>WARNING: +There is nothing transactional about the *persist* from **pmem2_get_persist_fn**(3) +call in this example. Interrupting the program may result in a partial write to pmem. +Use a transactional library such as **libpmemobj**(7) to avoid torn updates. + +<code data-gist-id='wlemkows/c7dc06875ee4aa9857020eba01114e75' data-gist-file='basic.c' data-gist-line='8-74' data-gist-hide-footer='true'></code> + +The above example is described in detail [here](https://pmem.io/pmdk/libpmem2/). + # ACKNOWLEDGEMENTS # **libpmem2** builds on the persistent memory programming model recommended @@ -202,7 +291,13 @@ by the SNIA NVM Programming Technical Work Group: # SEE ALSO # **FlushFileBuffers**(), **fsync**(2), **msync**(2), +**pmem2_config_set_length**(3), **pmem2_config_set_offset**(3), **pmem2_config_set_required_store_granularity**(3), -**pmem2_get_memset_fn**(3), **pmem2_map_get_store_granularity**(3), +**pmem2_config_set_sharing**(3),**pmem2_get_drain_fn**(3), +**pmem2_get_flush_fn**(3), **pmem2_get_memcpy_fn**(3), +**pmem2_get_memmove_fn**(3), **pmem2_get_memset_fn**(3), +**pmem2_get_persist_fn**(3),**pmem2_map_get_store_granularity**(3), +**pmem2_map_new**(3), **pmem2_source_from_anon**(3), +**pmem2_source_from_fd**(3), **pmem2_source_from_handle**(3), **libpmemblk**(7), **libpmemlog**(7), **libpmemobj**(7) and **<https://pmem.io>** diff --git a/src/examples/libpmem2/basic/basic.c b/src/examples/libpmem2/basic/basic.c index 76251f77fd2c453644adeb9193eb738dd4269797..b31506f3f386e884e797b3f85e4c0543b93b285c 100644 --- a/src/examples/libpmem2/basic/basic.c +++ b/src/examples/libpmem2/basic/basic.c @@ -5,7 +5,6 @@ * basic.c -- simple example for the libpmem2 */ -#include <sys/stat.h> #include <fcntl.h> #include <stdlib.h> #include <stdio.h>