diff --git a/doc/libpmem2/libpmem2.7.md b/doc/libpmem2/libpmem2.7.md index 4f6a6910538159ff01e533ec65dc7f2042f156ea..bf27135ef9cf8df8d84a3ad5ff8509ace03a4b7e 100644 --- a/doc/libpmem2/libpmem2.7.md +++ b/doc/libpmem2/libpmem2.7.md @@ -65,19 +65,19 @@ robust use of Persistent Memory. It relies on three core concepts: * *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), +APIs dedicated for creating *source* are: **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*. +but the only required parameter to set in the *config* is *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) +functions to configure target mapping, e.g., **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 @@ -91,7 +91,7 @@ set of functions: **pmem2_map_get_address**(3), **pmem2_map_get_size**(3), 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. +**libpmem2** also provides optimized functions for modifying the mapped data. This includes data flushing as well as memory copying. To get proper function for data flushing use: **pmem2_get_flush_fn**(3), @@ -114,9 +114,10 @@ and can be found in the **libpmem2_unsafe_shutdown**(7) man page. # GRANULARITY # The **libpmem2** library introduces the concept of granularity through which you -may easily distinguish between different types of -reaching *power-fail protected domain* by data. Data can reach this domain in -different ways depending on the platform capabilities. +may easily distinguish between different levels of storage performance +capabilities available to the application as related to *power-fail protected domain*. +The way data reaches this protected domain differs based on the platform +and storage device capabilities. Traditional block storage devices (SSD, HDD) must use system API calls such as `msync()`, `fsync()` on Linux, or `FlushFileBuffers()`,`FlushViewOfFile()` @@ -126,13 +127,14 @@ of flushing behavior is called **PMEM2_GRANULARITY_PAGE**. In systems with persistent memory support, a *power-fail protected domain* may cover different sets of resources: either the memory controller or the memory -controller and CPU caches. In this regard, **libpmem2** distinguishes two types +controller and CPU caches. For this reason, **libpmem2** distinguishes two types of granularity for persistent memory: **PMEM2_GRANULARITY_CACHE_LINE** and **PMEM2_GRANULARITY_BYTE**. -If the *power-fail protected domain* covers only the memory controller, it is -required to flush CPU caches, so the granularity type, in this case, is called -**PMEM2_GRANULARITY_CACHE_LINE**. Depending on the architecture, there are +If the *power-fail protected domain* covers only the memory controller, the +CPU appropriate cache lines must be flushed for the data to be considered +persistent. This granularity type is called **PMEM2_GRANULARITY_CACHE_LINE**. +Depending on the architecture, there are different types of machine instructions for flushing *cache lines* (e.g., *CLWB*, *CLFLUSHOPT*, *CLFLUSH* for Intel x86_64 architecture). Usually, to ensure the ordering of stores, such instructions must be followed @@ -151,6 +153,10 @@ that most accurately represents the target hardware characteristics and the storage patterns of the application. For example, a database storage engine that operates on large logical pages that reside either on SSDs or PMEM should set this value to **PMEM2_GRANULARITY_PAGE**. +The library will create mappings where the new map granularity is lower or +equal to the requested one. For example, a mapping with **PMEM2_GRANULARITY_CACHE_LINE** +can created for the requried granularity **PMEM2_GRANULARITY_PAGE**, but not +vice versa. # CAVEATS # diff --git a/doc/libpmem2/pmem2_config_new.3.md b/doc/libpmem2/pmem2_config_new.3.md index 324c88bb5a379ba7ee490b2e31943534f7143021..462f60a2ad52ab50f32af74fc287e590eb50f3a4 100644 --- a/doc/libpmem2/pmem2_config_new.3.md +++ b/doc/libpmem2/pmem2_config_new.3.md @@ -37,7 +37,9 @@ int pmem2_config_delete(struct pmem2_config **cfg); The **pmem2_config_new**() function instantiates a new (opaque) configuration structure, *pmem2_config*, which is used to define mapping parameters for a **pmem2_map_new**() function, and returns it through the pointer in *\*cfg*. -New configuration is always initialized with default values for all possible parameters, which are specified alongside the corresponding setter function. +New configuration is always initialized with default values for most parameters, +which are specified alongside the corresponding setter function. +The application must explicitly set the granularity value for the mapping. The **pmem2_config_delete**() function frees *\*cfg* returned by **pmem2_config_new**() and sets *\*cfg* to NULL. If *\*cfg* is NULL, no operation is performed. diff --git a/doc/libpmem2/pmem2_config_set_length.3.md b/doc/libpmem2/pmem2_config_set_length.3.md index 7f600e6a3515094e5b019b1f1b908ee7da466714..3c3cbd898e676d4e5769c49b2d646529a269601f 100644 --- a/doc/libpmem2/pmem2_config_set_length.3.md +++ b/doc/libpmem2/pmem2_config_set_length.3.md @@ -39,6 +39,7 @@ for details. The *\length* must be a multiple of the alignment required for the source which will be used for mapping alongside the config. To retrieve the alignment required for specific instance of *pmem2_source** use **pmem2_source_alignment**(3). +By default, the length is equal to the size of the file that is being mapped. # RETURN VALUE # diff --git a/doc/libpmem2/pmem2_config_set_offset.3.md b/doc/libpmem2/pmem2_config_set_offset.3.md index 937908bef2c2d0fd11cac1490c0dbf3c7a5dd6a4..523096e14a91dff4d74224e4bfee91d3542478c6 100644 --- a/doc/libpmem2/pmem2_config_set_offset.3.md +++ b/doc/libpmem2/pmem2_config_set_offset.3.md @@ -40,6 +40,7 @@ already initialized, please see **pmem2_config_new**(3) for details. The *\offse must be a multiple of the alignment required for the config. The alignment requirements are specific to a data source. To retrieve the alignment required for specific instance of *pmem2_source** use **pmem2_source_alignment**(3). +By default, the offset is 0. # RETURN VALUE # diff --git a/doc/libpmem2/pmem2_deep_flush.3.md b/doc/libpmem2/pmem2_deep_flush.3.md index 35662ca5c3f90df6a95e74f6b74d8ac783f1fce7..d9b2bb7a485a486b22c79823a0685b316d2ee837 100644 --- a/doc/libpmem2/pmem2_deep_flush.3.md +++ b/doc/libpmem2/pmem2_deep_flush.3.md @@ -43,9 +43,6 @@ should be used sparingly. Typically, the application should only ever use this function as a precaution against hardware failures, e.g., in code that detects silent data corruption caused by unsafe shutdown (see more in **libpmem2_unsafe_shutdown**(7)). -Applications should generally not assume the support for this functionality -in the platform, and not treat **PMEM2_E_NOSUPP** as a fatal error. - # RETURN VALUE # The **pmem2_deep_flush**() function returns 0 on success diff --git a/doc/libpmem2/pmem2_vm_reservation_new.3.md b/doc/libpmem2/pmem2_vm_reservation_new.3.md index b9cba1f4cf26abbbb269ea266f07e745eb2d7aac..7be5787be3582420d0f7b8aa69734cbd075c6839 100644 --- a/doc/libpmem2/pmem2_vm_reservation_new.3.md +++ b/doc/libpmem2/pmem2_vm_reservation_new.3.md @@ -41,29 +41,31 @@ The **pmem2_vm_reservation_new**() function creates a new blank mapping in the virtual address space of the calling process. Reservation serves as a placeholder of a given size on which sources can be mapped. -For the function to succeed, the *addr* must be either aligned to an appropriate allocation granularity, -or be a NULL, the size has to be aligned to an appropraite allocation granularity. +For the function to succeed, the *addr* must be either aligned to an appropriate +allocation granularity, +or **NULL**, the size has to be aligned to an appropraite allocation granularity. If the **pmem2_vm_reservation_new**() succeeds in creating a reservation, it instantiates a new -*struct pmem2_vm_reservation** object describing the reservation. The pointer to this object -is stored in the user-provided variable via the *rsv_ptr* pointer. If the function fails, an appropriate -error value will be returned. For a list of possible return values please see [RETURN VALUE](#return-value) +**struct pmem2_vm_reservation** object describing the reservation. The pointer to this object +is stored in the user-provided variable via the *rsv_ptr* pointer. If the function +fails, an appropriate error value will be returned. For a list of possible return +values please see [RETURN VALUE](#return-value) -After instantiating an object via the **pmem2_vm_reservation_new**() function, it is necessary to -finalize it using the **pmem2_vm_reservation_delete**() function. +After instantiating an object via the **pmem2_vm_reservation_new**() function, it +may be disposed of using the **pmem2_vm_reservation_delete**() function. -The **pmem2_vm_reservation_delete**() function destroys the object describing the reservation and unmaps -virtual memory region the *struct pmem2_vm_reservation** had assigned during the initialization. - -For the function to succeed, it is required that the reservation passed via the *rsv_ptr* pointer will not -contain any mappings. +The **pmem2_vm_reservation_delete**() function destroys the object describing +the reservation and unmaps virtual memory region +the *struct pmem2_vm_reservation** had assigned during the initialization. +For the delete function to succeed, it is required that the reservation passed via +the *rsv_ptr* pointer does not contain any mappings. # RETURN VALUE # The **pmem2_vm_reservation_new**() and **pmem2_vm_reservation_delete**() functions return 0 on success or a negative error code on failure. -The function returns 0 on success or a negative error code on failure. +The function returns 0 on success or a negative error code on failure. # ERRORS #