ceph/src/pmdk/src/include/libpmem2.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /* Copyright 2019-2020, Intel Corporation */
   3
   4 /*
   5  * libpmem2.h -- definitions of libpmem2 entry points
   6  *
   7  * This library provides support for programming with persistent memory (pmem).
   8  *
   9  * libpmem2 provides support for using raw pmem directly.
  10  *
  11  * See libpmem2(7) for details.
  12  */
  13
  14 #ifndef LIBPMEM2_H
  15 #define LIBPMEM2_H 1
  16
  17 #include <stddef.h>
  18 #include <stdint.h>
  19
  20 #ifdef _WIN32
  21 #include <pmemcompat.h>
  22
  23 #ifndef PMDK_UTF8_API
  24 #define pmem2_source_device_id pmem2_source_device_idW
  25 #define pmem2_errormsg pmem2_errormsgW
  26 #define pmem2_perror pmem2_perrorW
  27 #else
  28 #define pmem2_source_device_id pmem2_source_device_idU
  29 #define pmem2_errormsg pmem2_errormsgU
  30 #define pmem2_perror pmem2_perrorU
  31 #endif
  32
  33 #endif
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #define PMEM2_E_UNKNOWN                         (-100000)
  40 #define PMEM2_E_NOSUPP                          (-100001)
  41 #define PMEM2_E_FILE_HANDLE_NOT_SET             (-100003)
  42 #define PMEM2_E_INVALID_FILE_HANDLE             (-100004)
  43 #define PMEM2_E_INVALID_FILE_TYPE               (-100005)
  44 #define PMEM2_E_MAP_RANGE                       (-100006)
  45 #define PMEM2_E_MAPPING_EXISTS                  (-100007)
  46 #define PMEM2_E_GRANULARITY_NOT_SET             (-100008)
  47 #define PMEM2_E_GRANULARITY_NOT_SUPPORTED       (-100009)
  48 #define PMEM2_E_OFFSET_OUT_OF_RANGE             (-100010)
  49 #define PMEM2_E_OFFSET_UNALIGNED                (-100011)
  50 #define PMEM2_E_INVALID_ALIGNMENT_FORMAT        (-100012)
  51 #define PMEM2_E_INVALID_ALIGNMENT_VALUE         (-100013)
  52 #define PMEM2_E_INVALID_SIZE_FORMAT             (-100014)
  53 #define PMEM2_E_LENGTH_UNALIGNED                (-100015)
  54 #define PMEM2_E_MAPPING_NOT_FOUND               (-100016)
  55 #define PMEM2_E_BUFFER_TOO_SMALL                (-100017)
  56 #define PMEM2_E_SOURCE_EMPTY                    (-100018)
  57 #define PMEM2_E_INVALID_SHARING_VALUE           (-100019)
  58 #define PMEM2_E_SRC_DEVDAX_PRIVATE              (-100020)
  59 #define PMEM2_E_INVALID_ADDRESS_REQUEST_TYPE    (-100021)
  60 #define PMEM2_E_ADDRESS_UNALIGNED               (-100022)
  61 #define PMEM2_E_ADDRESS_NULL                    (-100023)
  62 #define PMEM2_E_DEEP_FLUSH_RANGE                (-100024)
  63 #define PMEM2_E_INVALID_REGION_FORMAT           (-100025)
  64 #define PMEM2_E_DAX_REGION_NOT_FOUND            (-100026)
  65 #define PMEM2_E_INVALID_DEV_FORMAT              (-100027)
  66 #define PMEM2_E_CANNOT_READ_BOUNDS              (-100028)
  67 #define PMEM2_E_NO_BAD_BLOCK_FOUND              (-100029)
  68 #define PMEM2_E_LENGTH_OUT_OF_RANGE             (-100030)
  69 #define PMEM2_E_INVALID_PROT_FLAG               (-100031)
  70 #define PMEM2_E_NO_ACCESS                       (-100032)
  71 #define PMEM2_E_VM_RESERVATION_NOT_EMPTY        (-100033)
  72 #define PMEM2_E_MAP_EXISTS                      (-100034)
  73 #define PMEM2_E_FILE_DESCRIPTOR_NOT_SET         (-100035)
  74
  75 /* source setup */
  76
  77 struct pmem2_source;
  78
  79 int pmem2_source_from_fd(struct pmem2_source **src, int fd);
  80 int pmem2_source_from_anon(struct pmem2_source **src, size_t size);
  81 #ifdef _WIN32
  82 int pmem2_source_from_handle(struct pmem2_source **src, HANDLE handle);
  83 int pmem2_source_get_handle(const struct pmem2_source *src, HANDLE *h);
  84 #else
  85 int pmem2_source_get_fd(const struct pmem2_source *src, int *fd);
  86 #endif
  87
  88 int pmem2_source_size(const struct pmem2_source *src, size_t *size);
  89
  90 int pmem2_source_alignment(const struct pmem2_source *src,
  91                 size_t *alignment);
  92
  93 int pmem2_source_delete(struct pmem2_source **src);
  94
  95 /* vm reservation setup */
  96
  97 struct pmem2_vm_reservation;
  98
  99 void *pmem2_vm_reservation_get_address(struct pmem2_vm_reservation *rsv);
 100
 101 size_t pmem2_vm_reservation_get_size(struct pmem2_vm_reservation *rsv);
 102
 103 int pmem2_vm_reservation_new(struct pmem2_vm_reservation **rsv_ptr,
 104                 void *addr, size_t size);
 105
 106 int pmem2_vm_reservation_delete(struct pmem2_vm_reservation **rsv_ptr);
 107
 108 /* config setup */
 109
 110 struct pmem2_config;
 111
 112 int pmem2_config_new(struct pmem2_config **cfg);
 113
 114 int pmem2_config_delete(struct pmem2_config **cfg);
 115
 116 enum pmem2_granularity {
 117         PMEM2_GRANULARITY_BYTE,
 118         PMEM2_GRANULARITY_CACHE_LINE,
 119         PMEM2_GRANULARITY_PAGE,
 120 };
 121
 122 int pmem2_config_set_required_store_granularity(struct pmem2_config *cfg,
 123         enum pmem2_granularity g);
 124
 125 int pmem2_config_set_offset(struct pmem2_config *cfg, size_t offset);
 126
 127 int pmem2_config_set_length(struct pmem2_config *cfg, size_t length);
 128
 129 enum pmem2_sharing_type {
 130         PMEM2_SHARED,
 131         PMEM2_PRIVATE,
 132 };
 133
 134 int pmem2_config_set_sharing(struct pmem2_config *cfg,
 135                                 enum pmem2_sharing_type type);
 136
 137 #define PMEM2_PROT_EXEC (1U << 29)
 138 #define PMEM2_PROT_READ (1U << 30)
 139 #define PMEM2_PROT_WRITE        (1U << 31)
 140 #define PMEM2_PROT_NONE 0
 141
 142 int pmem2_config_set_protection(struct pmem2_config *cfg,
 143                                 unsigned prot);
 144
 145 int pmem2_config_set_vm_reservation(struct pmem2_config *cfg,
 146                 struct pmem2_vm_reservation *rsv, size_t offset);
 147
 148 /* mapping */
 149
 150 struct pmem2_map;
 151 int pmem2_map_from_existing(struct pmem2_map **map,
 152         const struct pmem2_source *src, void *addr, size_t len,
 153         enum pmem2_granularity gran);
 154
 155 int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *cfg,
 156                 const struct pmem2_source *src);
 157
 158 int pmem2_map_delete(struct pmem2_map **map_ptr);
 159
 160 void *pmem2_map_get_address(struct pmem2_map *map);
 161
 162 size_t pmem2_map_get_size(struct pmem2_map *map);
 163
 164 enum pmem2_granularity pmem2_map_get_store_granularity(struct pmem2_map *map);
 165
 166 /* flushing */
 167
 168 typedef void (*pmem2_persist_fn)(const void *ptr, size_t size);
 169
 170 typedef void (*pmem2_flush_fn)(const void *ptr, size_t size);
 171
 172 typedef void (*pmem2_drain_fn)(void);
 173
 174 pmem2_persist_fn pmem2_get_persist_fn(struct pmem2_map *map);
 175
 176 pmem2_flush_fn pmem2_get_flush_fn(struct pmem2_map *map);
 177
 178 pmem2_drain_fn pmem2_get_drain_fn(struct pmem2_map *map);
 179
 180 #define PMEM2_F_MEM_NODRAIN     (1U << 0)
 181
 182 #define PMEM2_F_MEM_NONTEMPORAL (1U << 1)
 183 #define PMEM2_F_MEM_TEMPORAL    (1U << 2)
 184
 185 #define PMEM2_F_MEM_WC          (1U << 3)
 186 #define PMEM2_F_MEM_WB          (1U << 4)
 187
 188 #define PMEM2_F_MEM_NOFLUSH     (1U << 5)
 189
 190 #define PMEM2_F_MEM_VALID_FLAGS (PMEM2_F_MEM_NODRAIN | \
 191                 PMEM2_F_MEM_NONTEMPORAL | \
 192                 PMEM2_F_MEM_TEMPORAL | \
 193                 PMEM2_F_MEM_WC | \
 194                 PMEM2_F_MEM_WB | \
 195                 PMEM2_F_MEM_NOFLUSH)
 196
 197 typedef void *(*pmem2_memmove_fn)(void *pmemdest, const void *src, size_t len,
 198                 unsigned flags);
 199
 200 typedef void *(*pmem2_memcpy_fn)(void *pmemdest, const void *src, size_t len,
 201                 unsigned flags);
 202
 203 typedef void *(*pmem2_memset_fn)(void *pmemdest, int c, size_t len,
 204                 unsigned flags);
 205
 206 pmem2_memmove_fn pmem2_get_memmove_fn(struct pmem2_map *map);
 207
 208 pmem2_memcpy_fn pmem2_get_memcpy_fn(struct pmem2_map *map);
 209
 210 pmem2_memset_fn pmem2_get_memset_fn(struct pmem2_map *map);
 211
 212 /* RAS */
 213
 214 int pmem2_deep_flush(struct pmem2_map *map, void *ptr, size_t size);
 215
 216 #ifndef _WIN32
 217 int pmem2_source_device_id(const struct pmem2_source *src,
 218         char *id, size_t *len);
 219 #else
 220 int pmem2_source_device_idW(const struct pmem2_source *src,
 221         wchar_t *id, size_t *len);
 222
 223 int pmem2_source_device_idU(const struct pmem2_source *src,
 224         char *id, size_t *len);
 225 #endif
 226
 227 int pmem2_source_device_usc(const struct pmem2_source *src, uint64_t *usc);
 228
 229 struct pmem2_badblock_context;
 230
 231 struct pmem2_badblock {
 232         size_t offset;
 233         size_t length;
 234 };
 235
 236 int pmem2_badblock_context_new(struct pmem2_badblock_context **bbctx,
 237                 const struct pmem2_source *src);
 238
 239 int pmem2_badblock_next(struct pmem2_badblock_context *bbctx,
 240                 struct pmem2_badblock *bb);
 241
 242 void pmem2_badblock_context_delete(
 243                 struct pmem2_badblock_context **bbctx);
 244
 245 int pmem2_badblock_clear(struct pmem2_badblock_context *bbctx,
 246                 const struct pmem2_badblock *bb);
 247
 248 /* error handling */
 249
 250 #ifndef _WIN32
 251 const char *pmem2_errormsg(void);
 252 #else
 253 const char *pmem2_errormsgU(void);
 254
 255 const wchar_t *pmem2_errormsgW(void);
 256 #endif
 257
 258 int pmem2_err_to_errno(int);
 259
 260 #ifndef _WIN32
 261 void pmem2_perror(const char *format,
 262                 ...) __attribute__((__format__(__printf__, 1, 2)));
 263 #else
 264 void pmem2_perrorU(const char *format, ...);
 265
 266 void pmem2_perrorW(const wchar_t *format, ...);
 267 #endif
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272 #endif  /* libpmem2.h */