Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PMEM_MEMMOVE_PERSIST(3)	   PMDK	Programmer's Manual    PMEM_MEMMOVE_PERSIST(3)

NAME
       pmem_memmove(),	pmem_memcpy(),	pmem_memset(), pmem_memmove_persist(),
       pmem_memcpy_persist(),  pmem_memset_persist(),  pmem_memmove_nodrain(),
       pmem_memcpy_nodrain(),  pmem_memset_nodrain()  -	functions that provide
       optimized copying to persistent memory

SYNOPSIS
	      #include <libpmem.h>

	      void *pmem_memmove(void *pmemdest, const void *src, size_t len, unsigned flags);
	      void *pmem_memcpy(void *pmemdest,	const void *src, size_t	len, unsigned flags);
	      void *pmem_memset(void *pmemdest,	int c, size_t len, unsigned flags);
	      void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len);
	      void *pmem_memcpy_persist(void *pmemdest,	const void *src, size_t	len);
	      void *pmem_memset_persist(void *pmemdest,	int c, size_t len);
	      void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len);
	      void *pmem_memcpy_nodrain(void *pmemdest,	const void *src, size_t	len);
	      void *pmem_memset_nodrain(void *pmemdest,	int c, size_t len);

DESCRIPTION
       pmem_memmove(), pmem_memcpy() and pmem_memset() functions  provide  the
       same  memory  copying as	their namesakes	memmove(3), memcpy(3) and mem-
       set(3), and ensure that the result has been flushed to persistence  be-
       fore returning (unless PMEM_F_MEM_NOFLUSH flag was used).

       For example, the	following code is functionally equivalent to pmem_mem-
       move() (with flags equal	to 0):

		  memmove(dest,	src, len);
		  pmem_persist(dest, len);

       Calling pmem_memmove() may out-perform the above	 code,	because	 libp-
       mem(7)  implementation  may take	advantage of the fact that pmemdest is
       persistent memory and use instructions such as non-temporal  stores  to
       avoid the need to flush processor caches.

	      WARNING:	Using  these  functions	 where pmem_is_pmem(3) returns
	      false may	not do anything	useful.	 Use libc  functions  in  that
	      case.

       Unlike  libc implementation, libpmem functions guarantee	that if	desti-
       nation buffer address and length	are 8 byte  aligned  then  all	stores
       will be performed using at least	8 byte store instructions.  This means
       that a series of	8 byte stores followed by pmem_persist(3) can be safe-
       ly replaced by a	single call to one of the above	functions.

       The  flags argument of all of the above functions has the same meaning.
       It can be 0 or a	bitwise	OR of one or more of the following flags:

       o PMEM_F_MEM_NODRAIN  -	modifies  the  behavior	 to  skip  the	 final
	 pmem_drain()  step.  This allows applications to optimize cases where
	 several ranges	are being copied to persistent memory, followed	 by  a
	 single	 call  to pmem_drain().	 The following example illustrates how
	 this flag might be used to avoid multiple calls to pmem_drain()  when
	 copying several ranges	of memory to pmem:

	 /* ...	write several ranges to	pmem ... */
	 pmem_memcpy(pmemdest1,	src1, len1, PMEM_F_MEM_NODRAIN);
	 pmem_memcpy(pmemdest2,	src2, len2, PMEM_F_MEM_NODRAIN);

	 /* ...	*/

	 /* wait for any pmem stores to	drain from HW buffers */
	 pmem_drain();

       o PMEM_F_MEM_NOFLUSH    -   Don't   flush   anything.	This   implies
	 PMEM_F_MEM_NODRAIN.  Using this flag only makes sense when it's  fol-
	 lowed by any function that flushes data.

       The remaining flags say how the operation should	be done, and are mere-
       ly hints.

       o PMEM_F_MEM_NONTEMPORAL	- Use non-temporal instructions.  This flag is
	 mutually  exclusive with PMEM_F_MEM_TEMPORAL.	On x86_64 this flag is
	 mutually exclusive with PMEM_F_MEM_NOFLUSH.

       o PMEM_F_MEM_TEMPORAL - Use temporal instructions.  This	flag is	 mutu-
	 ally exclusive	with PMEM_F_MEM_NONTEMPORAL.

       o PMEM_F_MEM_WC	- Use write combining mode.  This flag is mutually ex-
	 clusive  with	PMEM_F_MEM_WB.	 On  x86_64  this  is  an  alias   for
	 PMEM_F_MEM_NONTEMPORAL.   On  x86_64  this flag is mutually exclusive
	 with PMEM_F_MEM_NOFLUSH.

       o PMEM_F_MEM_WB - Use write back	mode.  This flag is mutually exclusive
	 with PMEM_F_MEM_WC.  On x86_64	this is	an alias for PMEM_F_MEM_TEMPO-
	 RAL.

       Using an	invalid	combination of flags has undefined behavior.

       Without any of the above	flags libpmem  will  try  to  guess  the  best
       strategy	 based on size.	 See PMEM_MOVNT_THRESHOLD description in libp-
       mem(7) for details.

       pmem_memmove_persist() is an alias for pmem_memmove() with flags	 equal
       to 0.

       pmem_memcpy_persist() is	an alias for pmem_memcpy() with	flags equal to
       0.

       pmem_memset_persist() is	an alias for pmem_memset() with	flags equal to
       0.

       pmem_memmove_nodrain()  is an alias for pmem_memmove() with flags equal
       to PMEM_F_MEM_NODRAIN.

       pmem_memcpy_nodrain() is	an alias for pmem_memcpy() with	flags equal to
       PMEM_F_MEM_NODRAIN.

       pmem_memset_nodrain() is	an alias for pmem_memset() with	flags equal to
       PMEM_F_MEM_NODRAIN.

RETURN VALUE
       All of the above	functions return address of the	destination buffer.

CAVEATS
       After calling any of the	functions  with	 PMEM_F_MEM_NODRAIN  flag  you
       should  not expect memory to be visible to other	threads	before calling
       pmem_drain(3) or	any of the _persist functions.	 This  is  because  on
       x86_64  those  functions	may use	non-temporal store instructions, which
       are weakly ordered.  See	"Intel 64 and IA-32 Architectures Software De-
       veloper's  Manual", Volume 1, "Caching of Temporal vs. Non-Temporal Da-
       ta" section for details.

SEE ALSO
       memcpy(3), memmove(3), memset(3), libpmem(7) and	<http://pmem.io>

PMDK - pmem API	version	1.1	  2019-07-10	       PMEM_MEMMOVE_PERSIST(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | CAVEATS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pmem_memmove_persist&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help