1PMEM_MEMMOVE_PERSIST(3)    PMDK Programmer's Manual    PMEM_MEMMOVE_PERSIST(3)
2
3
4

NAME

6       pmem_memmove(),  pmem_memcpy(),  pmem_memset(), pmem_memmove_persist(),
7       pmem_memcpy_persist(),  pmem_memset_persist(),  pmem_memmove_nodrain(),
8       pmem_memcpy_nodrain(),  pmem_memset_nodrain()  - functions that provide
9       optimized copying to persistent memory
10

SYNOPSIS

12              #include <libpmem.h>
13
14              void *pmem_memmove(void *pmemdest, const void *src, size_t len, unsigned flags);
15              void *pmem_memcpy(void *pmemdest, const void *src, size_t len, unsigned flags);
16              void *pmem_memset(void *pmemdest, int c, size_t len, unsigned flags);
17              void *pmem_memmove_persist(void *pmemdest, const void *src, size_t len);
18              void *pmem_memcpy_persist(void *pmemdest, const void *src, size_t len);
19              void *pmem_memset_persist(void *pmemdest, int c, size_t len);
20              void *pmem_memmove_nodrain(void *pmemdest, const void *src, size_t len);
21              void *pmem_memcpy_nodrain(void *pmemdest, const void *src, size_t len);
22              void *pmem_memset_nodrain(void *pmemdest, int c, size_t len);
23

DESCRIPTION

25       pmem_memmove(), pmem_memcpy() and pmem_memset() functions  provide  the
26       same  memory  copying as their namesakes memmove(3), memcpy(3) and mem‐
27       set(3), and ensure that the result has been flushed to persistence  be‐
28       fore returning (unless PMEM_F_MEM_NOFLUSH flag was used).
29
30       For example, the following code is functionally equivalent to pmem_mem‐
31       move() (with flags equal to 0):
32
33                  memmove(dest, src, len);
34                  pmem_persist(dest, len);
35
36       Calling pmem_memmove() may out-perform the above  code,  because  libp‐
37       mem(7)  implementation  may take advantage of the fact that pmemdest is
38       persistent memory and use instructions such as non-temporal  stores  to
39       avoid the need to flush processor caches.
40
41              WARNING:  Using  these  functions  where pmem_is_pmem(3) returns
42              false may not do anything useful.  Use libc  functions  in  that
43              case.
44
45       Unlike  libc implementation, libpmem functions guarantee that if desti‐
46       nation buffer address and length are 8 byte  aligned  then  all  stores
47       will be performed using at least 8 byte store instructions.  This means
48       that a series of 8 byte stores followed by pmem_persist(3) can be safe‐
49       ly replaced by a single call to one of the above functions.
50
51       The  flags argument of all of the above functions has the same meaning.
52       It can be 0 or a bitwise OR of one or more of the following flags:
53
54PMEM_F_MEM_NODRAIN  -  modifies  the  behavior  to  skip  the   final
55         pmem_drain()  step.  This allows applications to optimize cases where
56         several ranges are being copied to persistent memory, followed  by  a
57         single  call  to pmem_drain().  The following example illustrates how
58         this flag might be used to avoid multiple calls to pmem_drain()  when
59         copying several ranges of memory to pmem:
60
61         /* ... write several ranges to pmem ... */
62         pmem_memcpy(pmemdest1, src1, len1, PMEM_F_MEM_NODRAIN);
63         pmem_memcpy(pmemdest2, src2, len2, PMEM_F_MEM_NODRAIN);
64
65         /* ... */
66
67         /* wait for any pmem stores to drain from HW buffers */
68         pmem_drain();
69
70PMEM_F_MEM_NOFLUSH    -   Don’t   flush   anything.    This   implies
71         PMEM_F_MEM_NODRAIN.  Using this flag only makes sense when it’s  fol‐
72         lowed by any function that flushes data.
73
74       The remaining flags say how the operation should be done, and are mere‐
75       ly hints.
76
77PMEM_F_MEM_NONTEMPORAL - Use non-temporal instructions.  This flag is
78         mutually  exclusive with PMEM_F_MEM_TEMPORAL.  On x86_64 this flag is
79         mutually exclusive with PMEM_F_MEM_NOFLUSH.
80
81PMEM_F_MEM_TEMPORAL - Use temporal instructions.  This flag is  mutu‐
82         ally exclusive with PMEM_F_MEM_NONTEMPORAL.
83
84PMEM_F_MEM_WC  - Use write combining mode.  This flag is mutually ex‐
85         clusive with PMEM_F_MEM_WB.  On x86_64 this flag is  mutually  exclu‐
86         sive with PMEM_F_MEM_NOFLUSH.
87
88PMEM_F_MEM_WB - Use write back mode.  This flag is mutually exclusive
89         with PMEM_F_MEM_WC.  On x86_64 this is an alias for PMEM_F_MEM_TEMPO‐
90         RAL.
91
92       Using an invalid combination of flags has undefined behavior.
93
94       Without  any  of  the  above  flags  libpmem will try to guess the best
95       strategy based on size.  See PMEM_MOVNT_THRESHOLD description in  libp‐
96       mem(7) for details.
97
98       pmem_memmove_persist()  is an alias for pmem_memmove() with flags equal
99       to 0.
100
101       pmem_memcpy_persist() is an alias for pmem_memcpy() with flags equal to
102       0.
103
104       pmem_memset_persist() is an alias for pmem_memset() with flags equal to
105       0.
106
107       pmem_memmove_nodrain() is an alias for pmem_memmove() with flags  equal
108       to PMEM_F_MEM_NODRAIN.
109
110       pmem_memcpy_nodrain() is an alias for pmem_memcpy() with flags equal to
111       PMEM_F_MEM_NODRAIN.
112
113       pmem_memset_nodrain() is an alias for pmem_memset() with flags equal to
114       PMEM_F_MEM_NODRAIN.
115

RETURN VALUE

117       All of the above functions return address of the destination buffer.
118

CAVEATS

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

SEE ALSO

129       memcpy(3), memmove(3), memset(3), libpmem(7) and <https://pmem.io>
130
131
132
133PMDK - pmem API version 1.1       2020-10-28           PMEM_MEMMOVE_PERSIST(3)
Impressum