Merge pull request #4973 from pbalcer/doc-pmem2-fixes

doc: tiny man page fixes

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 #
 

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.

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 #
 

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 #
 

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

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 #