1PMEM_MEMMOVE_PERSIST(3) PMDK Programmer's Manual PMEM_MEMMOVE_PERSIST(3)
2
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
12 #include <libpmem.h>
13 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
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 For example, the following code is functionally equivalent to pmem_mem‐
31 move() (with flags equal to 0):
32 memmove(dest, src, len);
34 pmem_persist(dest, len);
35 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 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 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 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 • PMEM_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 /* ... 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 /* ... */
66 /* wait for any pmem stores to drain from HW buffers */
68 pmem_drain();
69 • PMEM_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 The remaining flags say how the operation should be done, and are mere‐
75 ly hints.
76 • PMEM_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 • PMEM_F_MEM_TEMPORAL - Use temporal instructions. This flag is mutu‐
82 ally exclusive with PMEM_F_MEM_NONTEMPORAL.
83 • PMEM_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 • PMEM_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 Using an invalid combination of flags has undefined behavior.
93 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 pmem_memmove_persist() is an alias for pmem_memmove() with flags equal
99 to 0.
100 pmem_memcpy_persist() is an alias for pmem_memcpy() with flags equal to
102 0.
103 pmem_memset_persist() is an alias for pmem_memset() with flags equal to
105 0.
106 pmem_memmove_nodrain() is an alias for pmem_memmove() with flags equal
108 to PMEM_F_MEM_NODRAIN.
109 pmem_memcpy_nodrain() is an alias for pmem_memcpy() with flags equal to
111 PMEM_F_MEM_NODRAIN.
112 pmem_memset_nodrain() is an alias for pmem_memset() with flags equal to
114 PMEM_F_MEM_NODRAIN.
115
117 All of the above functions return address of the destination buffer.
118
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
129 memcpy(3), memmove(3), memset(3), libpmem(7) and <https://pmem.io>
130PMDK - pmem API version 1.1 2020-10-28 PMEM_MEMMOVE_PERSIST(3)