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