1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2017 Intel Corporation. 3 * All rights reserved. 4 * Copyright (c) 2022-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 5 */ 6 7 /** \file 8 * Logical Volume Interface 9 */ 10 11 #ifndef SPDK_LVOL_H 12 #define SPDK_LVOL_H 13 14 #include "spdk/stdinc.h" 15 #include "spdk/blob.h" 16 #include "spdk/uuid.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 struct spdk_bs_dev; 23 struct spdk_lvol_store; 24 struct spdk_lvol; 25 26 enum lvol_clear_method { 27 LVOL_CLEAR_WITH_DEFAULT = BLOB_CLEAR_WITH_DEFAULT, 28 LVOL_CLEAR_WITH_NONE = BLOB_CLEAR_WITH_NONE, 29 LVOL_CLEAR_WITH_UNMAP = BLOB_CLEAR_WITH_UNMAP, 30 LVOL_CLEAR_WITH_WRITE_ZEROES = BLOB_CLEAR_WITH_WRITE_ZEROES, 31 }; 32 33 enum lvs_clear_method { 34 LVS_CLEAR_WITH_UNMAP = BS_CLEAR_WITH_UNMAP, 35 LVS_CLEAR_WITH_WRITE_ZEROES = BS_CLEAR_WITH_WRITE_ZEROES, 36 LVS_CLEAR_WITH_NONE = BS_CLEAR_WITH_NONE, 37 }; 38 39 /* Must include null terminator. */ 40 #define SPDK_LVS_NAME_MAX 64 41 #define SPDK_LVOL_NAME_MAX 64 42 43 /** 44 * Parameters for lvolstore initialization. 45 */ 46 struct spdk_lvs_opts { 47 /** Size of cluster in bytes. Must be multiple of 4KiB page size. */ 48 uint32_t cluster_sz; 49 50 /** Clear method */ 51 enum lvs_clear_method clear_method; 52 53 /** Name of the lvolstore */ 54 char name[SPDK_LVS_NAME_MAX]; 55 56 /** num_md_pages_per_cluster_ratio = 100 means 1 page per cluster */ 57 uint32_t num_md_pages_per_cluster_ratio; 58 59 /** 60 * The size of spdk_lvol_opts according to the caller of this library is used for ABI 61 * compatibility. The library uses this field to know how many fields in this 62 * structure are valid. And the library will populate any remaining fields with default 63 * values. After that, new added fields should be put in the end of the struct. 64 */ 65 uint32_t opts_size; 66 67 /** 68 * A function to be called to load external snapshots. If this is NULL while the lvolstore 69 * is being loaded, the lvolstore will not support external snapshots. 70 */ 71 spdk_bs_esnap_dev_create esnap_bs_dev_create; 72 } __attribute__((packed)); 73 SPDK_STATIC_ASSERT(sizeof(struct spdk_lvs_opts) == 88, "Incorrect size"); 74 75 /** 76 * Initialize an spdk_lvs_opts structure to the defaults. 77 * 78 * \param opts Pointer to the spdk_lvs_opts structure to initialize. 79 */ 80 void spdk_lvs_opts_init(struct spdk_lvs_opts *opts); 81 82 /** 83 * Callback definition for lvolstore operations, including handle to lvs. 84 * 85 * \param cb_arg Custom arguments 86 * \param lvol_store Handle to lvol_store or NULL when lvserrno is set 87 * \param lvserrno Error 88 */ 89 typedef void (*spdk_lvs_op_with_handle_complete)(void *cb_arg, struct spdk_lvol_store *lvol_store, 90 int lvserrno); 91 92 /** 93 * Callback definition for lvolstore operations without handle. 94 * 95 * \param cb_arg Custom arguments 96 * \param lvserrno Error 97 */ 98 typedef void (*spdk_lvs_op_complete)(void *cb_arg, int lvserrno); 99 100 101 /** 102 * Callback definition for lvol operations with handle to lvol. 103 * 104 * \param cb_arg Custom arguments 105 * \param lvol Handle to lvol or NULL when lvserrno is set 106 * \param lvolerrno Error 107 */ 108 typedef void (*spdk_lvol_op_with_handle_complete)(void *cb_arg, struct spdk_lvol *lvol, 109 int lvolerrno); 110 111 /** 112 * Callback definition for lvol operations without handle to lvol. 113 * 114 * \param cb_arg Custom arguments 115 * \param lvolerrno Error 116 */ 117 typedef void (*spdk_lvol_op_complete)(void *cb_arg, int lvolerrno); 118 119 /** 120 * Callback definition for spdk_lvol_iter_clones. 121 * 122 * \param lvol An iterated lvol. 123 * \param cb_arg Opaque context passed to spdk_lvol_iter_clone(). 124 * \return 0 to continue iterating, any other value to stop iterating. 125 */ 126 typedef int (*spdk_lvol_iter_cb)(void *cb_arg, struct spdk_lvol *lvol); 127 128 /** 129 * Initialize lvolstore on given bs_bdev. 130 * 131 * \param bs_dev This is created on the given bdev by using spdk_bdev_create_bs_dev() 132 * beforehand. 133 * \param o Options for lvolstore. 134 * \param cb_fn Completion callback. 135 * \param cb_arg Completion callback custom arguments. 136 * 137 * \return 0 on success, negative errno on failure. 138 */ 139 int spdk_lvs_init(struct spdk_bs_dev *bs_dev, struct spdk_lvs_opts *o, 140 spdk_lvs_op_with_handle_complete cb_fn, void *cb_arg); 141 142 /** 143 * Rename the given lvolstore. 144 * 145 * \param lvs Pointer to lvolstore. 146 * \param new_name New name of lvs. 147 * \param cb_fn Completion callback. 148 * \param cb_arg Completion callback custom arguments. 149 */ 150 void spdk_lvs_rename(struct spdk_lvol_store *lvs, const char *new_name, 151 spdk_lvs_op_complete cb_fn, void *cb_arg); 152 153 /** 154 * Unload lvolstore. 155 * 156 * All lvols have to be closed beforehand, when doing unload. 157 * 158 * \param lvol_store Handle to lvolstore. 159 * \param cb_fn Completion callback. 160 * \param cb_arg Completion callback custom arguments. 161 * 162 * \return 0 on success, negative errno on failure. 163 */ 164 int spdk_lvs_unload(struct spdk_lvol_store *lvol_store, 165 spdk_lvs_op_complete cb_fn, void *cb_arg); 166 167 /** 168 * Destroy lvolstore. 169 * 170 * All lvols have to be closed beforehand, when doing destroy. 171 * 172 * \param lvol_store Handle to lvolstore. 173 * \param cb_fn Completion callback. 174 * \param cb_arg Completion callback custom arguments. 175 * 176 * \return 0 on success, negative errno on failure. 177 */ 178 int spdk_lvs_destroy(struct spdk_lvol_store *lvol_store, 179 spdk_lvs_op_complete cb_fn, void *cb_arg); 180 181 /** 182 * Create lvol on given lvolstore with specified size. 183 * 184 * \param lvs Handle to lvolstore. 185 * \param name Name of lvol. 186 * \param sz size of lvol in bytes. 187 * \param thin_provisioned Enables thin provisioning. 188 * \param clear_method Changes default data clusters clear method 189 * \param cb_fn Completion callback. 190 * \param cb_arg Completion callback custom arguments. 191 * 192 * \return 0 on success, negative errno on failure. 193 */ 194 int spdk_lvol_create(struct spdk_lvol_store *lvs, const char *name, uint64_t sz, 195 bool thin_provisioned, enum lvol_clear_method clear_method, 196 spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); 197 /** 198 * Create snapshot of given lvol. 199 * 200 * \param lvol Handle to lvol. 201 * \param snapshot_name Name of created snapshot. 202 * \param cb_fn Completion callback. 203 * \param cb_arg Completion callback custom arguments. 204 */ 205 void spdk_lvol_create_snapshot(struct spdk_lvol *lvol, const char *snapshot_name, 206 spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); 207 208 /** 209 * Create clone of given snapshot. 210 * 211 * \param lvol Handle to lvol snapshot. 212 * \param clone_name Name of created clone. 213 * \param cb_fn Completion callback. 214 * \param cb_arg Completion callback custom arguments. 215 */ 216 void spdk_lvol_create_clone(struct spdk_lvol *lvol, const char *clone_name, 217 spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); 218 219 /** 220 * Create clone of given non-lvol device. 221 * 222 * The bdev that is being cloned is commonly called an external snapshot or esnap. The clone is 223 * commonly called an esnap clone. 224 * 225 * \param esnap_id The identifier that will be passed to the spdk_bs_esnap_dev_create callback. 226 * \param id_len The length of esnap_id, in bytes. 227 * \param size_bytes The size of the external snapshot device, in bytes. This must be an integer 228 * multiple of the lvolstore's cluster size. See \c cluster_sz in \struct spdk_lvs_opts. 229 * \param lvs Handle to lvolstore. 230 * \param clone_name Name of created clone. 231 * \param cb_fn Completion callback. 232 * \param cb_arg Completion callback custom arguments. 233 * \return 0 if parameters pass verification checks and the esnap creation is started, in which case 234 * the \c cb_fn will be used to report the completion status. If an error is encountered, a negative 235 * errno will be returned and \c cb_fn will not be called. 236 */ 237 int spdk_lvol_create_esnap_clone(const void *esnap_id, uint32_t id_len, uint64_t size_bytes, 238 struct spdk_lvol_store *lvs, const char *clone_name, 239 spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); 240 241 /** 242 * Rename lvol with new_name. 243 * 244 * \param lvol Handle to lvol. 245 * \param new_name new name for lvol. 246 * \param cb_fn Completion callback. 247 * \param cb_arg Completion callback custom arguments. 248 */ 249 void 250 spdk_lvol_rename(struct spdk_lvol *lvol, const char *new_name, 251 spdk_lvol_op_complete cb_fn, void *cb_arg); 252 253 /** 254 * \brief Returns if it is possible to delete an lvol (i.e. lvol is not a snapshot that have at least one clone). 255 * \param lvol Handle to lvol 256 */ 257 bool spdk_lvol_deletable(struct spdk_lvol *lvol); 258 259 /** 260 * Close lvol and remove information about lvol from its lvolstore. 261 * 262 * \param lvol Handle to lvol. 263 * \param cb_fn Completion callback. 264 * \param cb_arg Completion callback custom arguments. 265 */ 266 void spdk_lvol_destroy(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); 267 268 /** 269 * Close lvol, but information is kept on lvolstore. 270 * 271 * \param lvol Handle to lvol. 272 * \param cb_fn Completion callback. 273 * \param cb_arg Completion callback custom arguments. 274 */ 275 void spdk_lvol_close(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); 276 277 /** 278 * Iterate clones of an lvol. 279 * 280 * Iteration stops if cb_fn(cb_arg, clone_lvol) returns non-zero. 281 * 282 * \param lvol Handle to lvol. 283 * \param cb_fn Function to call for each lvol that clones this lvol. 284 * \param cb_arg Context to pass with cb_fn. 285 * \return -ENOMEM if memory allocation failed, non-zero return from cb_fn(), or 0. 286 */ 287 int spdk_lvol_iter_immediate_clones(struct spdk_lvol *lvol, spdk_lvol_iter_cb cb_fn, void *cb_arg); 288 289 /** 290 * Get the lvol that has a particular UUID. 291 * 292 * \param uuid The lvol's UUID. 293 * \return A pointer to the requested lvol on success, else NULL. 294 */ 295 struct spdk_lvol *spdk_lvol_get_by_uuid(const struct spdk_uuid *uuid); 296 297 /** 298 * Get the lvol that has the specified name in the specified lvolstore. 299 * 300 * \param lvs_name Name of the lvolstore. 301 * \param lvol_name Name of the lvol. 302 * \return A pointer to the requested lvol on success, else NULL. 303 */ 304 struct spdk_lvol *spdk_lvol_get_by_names(const char *lvs_name, const char *lvol_name); 305 306 /** 307 * Get I/O channel of bdev associated with specified lvol. 308 * 309 * \param lvol Handle to lvol. 310 * 311 * \return a pointer to the I/O channel. 312 */ 313 struct spdk_io_channel *spdk_lvol_get_io_channel(struct spdk_lvol *lvol); 314 315 /** 316 * Load lvolstore from the given blobstore device. 317 * 318 * \param bs_dev Pointer to the blobstore device. 319 * \param cb_fn Completion callback. 320 * \param cb_arg Completion callback custom arguments. 321 */ 322 void spdk_lvs_load(struct spdk_bs_dev *bs_dev, spdk_lvs_op_with_handle_complete cb_fn, 323 void *cb_arg); 324 325 /** 326 * Load lvolstore from the given blobstore device with options. 327 * 328 * If lvs_opts is not NULL, it should be initialized with spdk_lvs_opts_init(). 329 * 330 * \param bs_dev Pointer to the blobstore device. 331 * \param lvs_opts lvolstore options. 332 * \param cb_fn Completion callback. 333 * \param cb_arg Completion callback custom arguments. 334 * blobstore. 335 */ 336 void spdk_lvs_load_ext(struct spdk_bs_dev *bs_dev, const struct spdk_lvs_opts *lvs_opts, 337 spdk_lvs_op_with_handle_complete cb_fn, void *cb_arg); 338 339 /** 340 * Grow a lvstore to fill the underlying device. 341 * Cannot be used on loaded lvstore. 342 * 343 * \param bs_dev Pointer to the blobstore device. 344 * \param cb_fn Completion callback. 345 * \param cb_arg Completion callback custom arguments. 346 */ 347 void spdk_lvs_grow(struct spdk_bs_dev *bs_dev, spdk_lvs_op_with_handle_complete cb_fn, 348 void *cb_arg); 349 350 /** 351 * Grow a loaded lvstore to fill the underlying device. 352 * 353 * \param lvs Pointer to lvolstore. 354 * \param cb_fn Completion callback. 355 * \param cb_arg Completion callback custom arguments. 356 */ 357 void spdk_lvs_grow_live(struct spdk_lvol_store *lvs, spdk_lvs_op_complete cb_fn, void *cb_arg); 358 359 /** 360 * Open a lvol. 361 * 362 * \param lvol Handle to lvol. 363 * \param cb_fn Completion callback. 364 * \param cb_arg Completion callback custom arguments. 365 */ 366 void spdk_lvol_open(struct spdk_lvol *lvol, spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); 367 368 /** 369 * Inflate lvol 370 * 371 * \param lvol Handle to lvol 372 * \param cb_fn Completion callback 373 * \param cb_arg Completion callback custom arguments 374 */ 375 void spdk_lvol_inflate(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); 376 377 /** 378 * Decouple parent of lvol 379 * 380 * \param lvol Handle to lvol 381 * \param cb_fn Completion callback 382 * \param cb_arg Completion callback custom arguments 383 */ 384 void spdk_lvol_decouple_parent(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); 385 386 /** 387 * Determine if an lvol is degraded. A degraded lvol cannot perform IO. 388 * 389 * \param lvol Handle to lvol 390 * \return true if the lvol has no open blob or the lvol's blob is degraded, else false. 391 */ 392 bool spdk_lvol_is_degraded(const struct spdk_lvol *lvol); 393 394 /** 395 * Make a shallow copy of lvol on given bs_dev. 396 * 397 * Lvol must be read only and lvol size must be less or equal than bs_dev size. 398 * 399 * \param lvol Handle to lvol 400 * \param ext_dev The bs_dev to copy on. This is created on the given bdev by using 401 * spdk_bdev_create_bs_dev_ext() beforehand 402 * \param status_cb_fn Called repeatedly during operation with status updates 403 * \param status_cb_arg Argument passed to function status_cb_fn. 404 * \param cb_fn Completion callback 405 * \param cb_arg Completion callback custom arguments 406 * 407 * \return 0 if operation starts correctly, negative errno on failure. 408 */ 409 int spdk_lvol_shallow_copy(struct spdk_lvol *lvol, struct spdk_bs_dev *ext_dev, 410 spdk_blob_shallow_copy_status status_cb_fn, void *status_cb_arg, 411 spdk_lvol_op_complete cb_fn, void *cb_arg); 412 413 /** 414 * Set a snapshot as the parent of a lvol 415 * 416 * This call set a snapshot as the parent of a lvol, making the lvol a clone of this snapshot. 417 * The previous parent of the lvol, if any, can be another snapshot or an external snapshot; if 418 * the lvol is not a clone, it must be thin-provisioned. 419 * Lvol and parent snapshot must have the same size and must belong to the same lvol store. 420 * 421 * \param lvol Handle to lvol 422 * \param snapshot Handle to the parent snapshot 423 * \param cb_fn Completion callback 424 * \param cb_arg Completion callback custom arguments 425 */ 426 void spdk_lvol_set_parent(struct spdk_lvol *lvol, struct spdk_lvol *snapshot, 427 spdk_lvol_op_complete cb_fn, void *cb_arg); 428 429 /** 430 * Set an external snapshot as the parent of a lvol 431 * 432 * This call set an external snapshot as the parent of a lvol, making the lvol a clone of this 433 * external snapshot. 434 * The previous parent of the lvol, if any, can be another external snapshot or a snapshot; if 435 * the lvol is not a clone, it must be thin-provisioned. 436 * The size of the external snapshot device must be an integer multiple of cluster size of 437 * lvol's lvolstore. 438 * 439 * \param lvol Handle to lvol 440 * \param esnap_id The identifier of the external snapshot. 441 * \param esnap_id_len The length of esnap_id, in bytes. 442 * \param cb_fn Completion callback 443 * \param cb_arg Completion callback custom arguments 444 */ 445 void spdk_lvol_set_external_parent(struct spdk_lvol *lvol, const void *esnap_id, 446 uint32_t esnap_id_len, 447 spdk_lvol_op_complete cb_fn, void *cb_arg); 448 449 #ifdef __cplusplus 450 } 451 #endif 452 453 #endif /* SPDK_LVOL_H */ 454