ceph/src/spdk/include/spdk/blob.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /** \file
  35  * Blob Storage System
  36  *
  37  * The blob storage system, or the blobstore for short, is a low level
  38  * library for placing opaque blobs of data onto a storage device such
  39  * that scattered physical blocks on the storage device appear as a
  40  * single, contiguous storage region. These blobs are also persistent,
  41  * which means they are rediscoverable after reboot or power loss.
  42  *
  43  * The blobstore is designed to be very high performance, and thus has
  44  * a few general rules regarding thread safety to avoid taking locks
  45  * in the I/O path.  This is primarily done by only allowing most
  46  * functions to be called on the metadata thread.  The metadata thread is
  47  * the thread which called spdk_bs_init() or spdk_bs_load().
  48  *
  49  * Functions starting with the prefix "spdk_blob_io" are passed a channel
  50  * as an argument, and channels may only be used from the thread they were
  51  * created on. See \ref spdk_bs_alloc_io_channel.  These are the only
  52  * functions that may be called from a thread other than the metadata
  53  * thread.
  54  *
  55  * The blobstore returns errors using negated POSIX errno values, either
  56  * returned in the callback or as a return value. An errno value of 0 means
  57  * success.
  58  */
  59
  60 #ifndef SPDK_BLOB_H
  61 #define SPDK_BLOB_H
  62
  63 #include "spdk/stdinc.h"
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 typedef uint64_t spdk_blob_id;
  70 #define SPDK_BLOBID_INVALID     (uint64_t)-1
  71 #define SPDK_BLOBSTORE_TYPE_LENGTH 16
  72
  73 struct spdk_blob_store;
  74 struct spdk_io_channel;
  75 struct spdk_blob;
  76 struct spdk_xattr_names;
  77
  78 /**
  79  * Blobstore operation completion callback.
  80  *
  81  * \param cb_arg Callback argument.
  82  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
  83  */
  84 typedef void (*spdk_bs_op_complete)(void *cb_arg, int bserrno);
  85
  86 /**
  87  * Blobstore operation completion callback with handle.
  88  *
  89  * \param cb_arg Callback argument.
  90  * \param bs Handle to a blobstore.
  91  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
  92  */
  93 typedef void (*spdk_bs_op_with_handle_complete)(void *cb_arg, struct spdk_blob_store *bs,
  94                 int bserrno);
  95
  96 /**
  97  * Blob operation completion callback.
  98  *
  99  * \param cb_arg Callback argument.
 100  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
 101  */
 102 typedef void (*spdk_blob_op_complete)(void *cb_arg, int bserrno);
 103
 104 /**
 105  * Blob operation completion callback with blob ID.
 106  *
 107  * \param cb_arg Callback argument.
 108  * \param blobid Blob ID.
 109  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
 110  */
 111 typedef void (*spdk_blob_op_with_id_complete)(void *cb_arg, spdk_blob_id blobid, int bserrno);
 112
 113 /**
 114  * Blob operation completion callback with handle.
 115  *
 116  * \param cb_arg Callback argument.
 117  * \param bs Handle to a blob.
 118  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
 119  */
 120 typedef void (*spdk_blob_op_with_handle_complete)(void *cb_arg, struct spdk_blob *blb, int bserrno);
 121
 122 /**
 123  * Blobstore device completion callback.
 124  *
 125  * \param channel I/O channel the operation was initiated on.
 126  * \param cb_arg Callback argument.
 127  * \param bserrno 0 if it completed successfully, or negative errno if it failed.
 128  */
 129 typedef void (*spdk_bs_dev_cpl)(struct spdk_io_channel *channel,
 130                                 void *cb_arg, int bserrno);
 131
 132 struct spdk_bs_dev_cb_args {
 133         spdk_bs_dev_cpl         cb_fn;
 134         struct spdk_io_channel  *channel;
 135         void                    *cb_arg;
 136 };
 137
 138 struct spdk_bs_dev {
 139         /* Create a new channel which is a software construct that is used
 140          * to submit I/O. */
 141         struct spdk_io_channel *(*create_channel)(struct spdk_bs_dev *dev);
 142
 143         /* Destroy a previously created channel */
 144         void (*destroy_channel)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel);
 145
 146         /* Destroy this blobstore device.  Applications must not destroy the blobstore device,
 147          *  rather the blobstore will destroy it using this function pointer once all
 148          *  references to it during unload callback context have been completed.
 149          */
 150         void (*destroy)(struct spdk_bs_dev *dev);
 151
 152         void (*read)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, void *payload,
 153                      uint64_t lba, uint32_t lba_count,
 154                      struct spdk_bs_dev_cb_args *cb_args);
 155
 156         void (*write)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel, void *payload,
 157                       uint64_t lba, uint32_t lba_count,
 158                       struct spdk_bs_dev_cb_args *cb_args);
 159
 160         void (*readv)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel,
 161                       struct iovec *iov, int iovcnt,
 162                       uint64_t lba, uint32_t lba_count,
 163                       struct spdk_bs_dev_cb_args *cb_args);
 164
 165         void (*writev)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel,
 166                        struct iovec *iov, int iovcnt,
 167                        uint64_t lba, uint32_t lba_count,
 168                        struct spdk_bs_dev_cb_args *cb_args);
 169
 170         void (*flush)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel,
 171                       struct spdk_bs_dev_cb_args *cb_args);
 172
 173         void (*write_zeroes)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel,
 174                              uint64_t lba, uint32_t lba_count,
 175                              struct spdk_bs_dev_cb_args *cb_args);
 176
 177         void (*unmap)(struct spdk_bs_dev *dev, struct spdk_io_channel *channel,
 178                       uint64_t lba, uint32_t lba_count,
 179                       struct spdk_bs_dev_cb_args *cb_args);
 180
 181         uint64_t        blockcnt;
 182         uint32_t        blocklen; /* In bytes */
 183 };
 184
 185 struct spdk_bs_type {
 186         char bstype[SPDK_BLOBSTORE_TYPE_LENGTH];
 187 };
 188
 189 struct spdk_bs_opts {
 190         /** Size of cluster in bytes. Must be multiple of 4KiB page size. */
 191         uint32_t cluster_sz;
 192
 193         /** Count of the number of pages reserved for metadata */
 194         uint32_t num_md_pages;
 195
 196         /** Maximum simultaneous metadata operations */
 197         uint32_t max_md_ops;
 198
 199         /** Maximum simultaneous operations per channel */
 200         uint32_t max_channel_ops;
 201
 202         /** Blobstore type */
 203         struct spdk_bs_type bstype;
 204
 205         /** Callback function to invoke for each blob. */
 206         spdk_blob_op_with_handle_complete iter_cb_fn;
 207
 208         /** Argument passed to iter_cb_fn for each blob. */
 209         void *iter_cb_arg;
 210 };
 211
 212 /**
 213  * Initialize a spdk_bs_opts structure to the default blobstore option values.
 214  *
 215  * \param opts The spdk_bs_opts structure to be initialized.
 216  */
 217 void spdk_bs_opts_init(struct spdk_bs_opts *opts);
 218
 219 /**
 220  * Load a blobstore from the given device.
 221  *
 222  * \param dev Blobstore block device.
 223  * \param opts The structure which contains the option values for the blobstore.
 224  * \param cb_fn Called when the loading is complete.
 225  * \param cb_arg Argument passed to function cb_fn.
 226  */
 227 void spdk_bs_load(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts,
 228                   spdk_bs_op_with_handle_complete cb_fn, void *cb_arg);
 229
 230 /**
 231  * Initialize a blobstore on the given device.
 232  *
 233  * \param dev Blobstore block device.
 234  * \param opts The structure which contains the option values for the blobstore.
 235  * \param cb_fn Called when the initialization is complete.
 236  * \param cb_arg Argument passed to function cb_fn.
 237  */
 238 void spdk_bs_init(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts,
 239                   spdk_bs_op_with_handle_complete cb_fn, void *cb_arg);
 240
 241 typedef void (*spdk_bs_dump_print_xattr)(FILE *fp, const char *bstype, const char *name,
 242                 const void *value, size_t value_length);
 243
 244 /**
 245  * Dump a blobstore's metadata to a given FILE in human-readable format.
 246  *
 247  * \param dev Blobstore block device.
 248  * \param fp FILE pointer to dump the metadata contents.
 249  * \param print_xattr_fn Callback function to interpret external xattrs.
 250  * \param cb_fn Called when the dump is complete.
 251  * \param cb_arg Argument passed to function cb_fn.
 252  */
 253 void spdk_bs_dump(struct spdk_bs_dev *dev, FILE *fp, spdk_bs_dump_print_xattr print_xattr_fn,
 254                   spdk_bs_op_complete cb_fn, void *cb_arg);
 255 /**
 256  * Destroy the blobstore.
 257  *
 258  * It will destroy the blobstore by zeroing the super block.
 259  *
 260  * \param bs blobstore to destroy.
 261  * \param cb_fn Called when the destruction is complete.
 262  * \param cb_arg Argument passed to function cb_fn.
 263  */
 264 void spdk_bs_destroy(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn,
 265                      void *cb_arg);
 266
 267 /**
 268  * Unload the blobstore.
 269  *
 270  * It will flush all volatile data to disk.
 271  *
 272  * \param bs blobstore to unload.
 273  * \param cb_fn Called when the unloading is complete.
 274  * \param cb_arg Argument passed to function cb_fn.
 275  */
 276 void spdk_bs_unload(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg);
 277
 278 /**
 279  * Set a super blob on the given blobstore.
 280  *
 281  * This will be retrievable immediately after spdk_bs_load() on the next initializaiton.
 282  *
 283  * \param bs blobstore.
 284  * \param blobid The id of the blob which will be set as the super blob.
 285  * \param cb_fn Called when the setting is complete.
 286  * \param cb_arg Argument passed to function cb_fn.
 287  */
 288 void spdk_bs_set_super(struct spdk_blob_store *bs, spdk_blob_id blobid,
 289                        spdk_bs_op_complete cb_fn, void *cb_arg);
 290
 291 /**
 292  * Get the super blob. The obtained blob id will be passed to the callback function.
 293  *
 294  * \param bs blobstore.
 295  * \param cb_fn Called when the operation is complete.
 296  * \param cb_arg Argument passed to function cb_fn.
 297  */
 298 void spdk_bs_get_super(struct spdk_blob_store *bs,
 299                        spdk_blob_op_with_id_complete cb_fn, void *cb_arg);
 300
 301 /**
 302  * Get the cluster size in bytes.
 303  *
 304  * \param bs blobstore to query.
 305  *
 306  * \return cluster size.
 307  */
 308 uint64_t spdk_bs_get_cluster_size(struct spdk_blob_store *bs);
 309
 310 /**
 311  * Get the page size in bytes. This is the write and read granularity of blobs.
 312  *
 313  * \param bs blobstore to query.
 314  *
 315  * \return page size.
 316  */
 317 uint64_t spdk_bs_get_page_size(struct spdk_blob_store *bs);
 318
 319 /**
 320  * Get the io unit size in bytes.
 321  *
 322  * \param bs blobstore to query.
 323  *
 324  * \return io unit size.
 325  */
 326 uint64_t spdk_bs_get_io_unit_size(struct spdk_blob_store *bs);
 327
 328 /**
 329  * Get the number of free clusters.
 330  *
 331  * \param bs blobstore to query.
 332  *
 333  * \return the number of free clusters.
 334  */
 335 uint64_t spdk_bs_free_cluster_count(struct spdk_blob_store *bs);
 336
 337 /**
 338  * Get the total number of clusters accessible by user.
 339  *
 340  * \param bs blobstore to query.
 341  *
 342  * \return the total number of clusters accessible by user.
 343  */
 344 uint64_t spdk_bs_total_data_cluster_count(struct spdk_blob_store *bs);
 345
 346 /**
 347  * Get the blob id.
 348  *
 349  * \param blob Blob struct to query.
 350  *
 351  * \return blob id.
 352  */
 353 spdk_blob_id spdk_blob_get_id(struct spdk_blob *blob);
 354
 355 /**
 356  * Get the number of pages allocated to the blob.
 357  *
 358  * \param blob Blob struct to query.
 359  *
 360  * \return the number of pages.
 361  */
 362 uint64_t spdk_blob_get_num_pages(struct spdk_blob *blob);
 363
 364 /**
 365  * Get the number of io_units allocated to the blob.
 366  *
 367  * \param blob Blob struct to query.
 368  *
 369  * \return the number of io_units.
 370  */
 371 uint64_t spdk_blob_get_num_io_units(struct spdk_blob *blob);
 372
 373 /**
 374  * Get the number of clusters allocated to the blob.
 375  *
 376  * \param blob Blob struct to query.
 377  *
 378  * \return the number of clusters.
 379  */
 380 uint64_t spdk_blob_get_num_clusters(struct spdk_blob *blob);
 381
 382 struct spdk_blob_xattr_opts {
 383         /* Number of attributes */
 384         size_t  count;
 385         /* Array of attribute names. Caller should free this array after use. */
 386         char    **names;
 387         /* User context passed to get_xattr_value function */
 388         void    *ctx;
 389         /* Callback that will return value for each attribute name. */
 390         void    (*get_value)(void *xattr_ctx, const char *name,
 391                              const void **value, size_t *value_len);
 392 };
 393
 394 struct spdk_blob_opts {
 395         uint64_t  num_clusters;
 396         bool    thin_provision;
 397         struct spdk_blob_xattr_opts xattrs;
 398 };
 399
 400 /**
 401  * Initialize a spdk_blob_opts structure to the default blob option values.
 402  *
 403  * \param opts spdk_blob_opts structure to initialize.
 404  */
 405 void spdk_blob_opts_init(struct spdk_blob_opts *opts);
 406
 407 /**
 408  * Create a new blob with options on the given blobstore. The new blob id will
 409  * be passed to the callback function.
 410  *
 411  * \param bs blobstore.
 412  * \param opts The structure which contains the option values for the new blob.
 413  * \param cb_fn Called when the operation is complete.
 414  * \param cb_arg Argument passed to funcion cb_fn.
 415  */
 416 void spdk_bs_create_blob_ext(struct spdk_blob_store *bs, const struct spdk_blob_opts *opts,
 417                              spdk_blob_op_with_id_complete cb_fn, void *cb_arg);
 418
 419 /**
 420  * Create a new blob with default option values on the given blobstore.
 421  * The new blob id will be passed to the callback function.
 422  *
 423  * \param bs blobstore.
 424  * \param cb_fn Called when the operation is complete.
 425  * \param cb_arg Argument passed to function cb_fn.
 426  */
 427 void spdk_bs_create_blob(struct spdk_blob_store *bs,
 428                          spdk_blob_op_with_id_complete cb_fn, void *cb_arg);
 429
 430 /**
 431  * Create a read-only snapshot of specified blob with provided options.
 432  * This will automatically sync specified blob.
 433  *
 434  * When operation is done, original blob is converted to the thin-provisioned
 435  * blob with a newly created read-only snapshot set as a backing blob.
 436  * Structure snapshot_xattrs as well as anything it references (like e.g. names
 437  * array) must be valid until the completion is called.
 438  *
 439  * \param bs blobstore.
 440  * \param blobid Id of the source blob used to create a snapshot.
 441  * \param snapshot_xattrs xattrs specified for snapshot.
 442  * \param cb_fn Called when the operation is complete.
 443  * \param cb_arg Argument passed to function cb_fn.
 444  */
 445 void spdk_bs_create_snapshot(struct spdk_blob_store *bs, spdk_blob_id blobid,
 446                              const struct spdk_blob_xattr_opts *snapshot_xattrs,
 447                              spdk_blob_op_with_id_complete cb_fn, void *cb_arg);
 448
 449 /**
 450  * Create a clone of specified read-only blob.
 451  *
 452  * Structure clone_xattrs as well as anything it references (like e.g. names
 453  * array) must be valid until the completion is called.
 454  *
 455  * \param bs blobstore.
 456  * \param blobid Id of the read only blob used as a snapshot for new clone.
 457  * \param clone_xattrs xattrs specified for clone.
 458  * \param cb_fn Called when the operation is complete.
 459  * \param cb_arg Argument passed to function cb_fn.
 460  */
 461 void spdk_bs_create_clone(struct spdk_blob_store *bs, spdk_blob_id blobid,
 462                           const struct spdk_blob_xattr_opts *clone_xattrs,
 463                           spdk_blob_op_with_id_complete cb_fn, void *cb_arg);
 464
 465 /**
 466  * Provide table with blob id's of clones are dependent on specified snapshot.
 467  *
 468  * Ids array should be allocated and the count parameter set to the number of
 469  * id's it can store, before calling this function.
 470  *
 471  * If ids is NULL or count parameter is not sufficient to handle ids of all
 472  * clones, -ENOMEM error is returned and count parameter is updated to the
 473  * total number of clones.
 474  *
 475  * \param bs blobstore.
 476  * \param blobid Snapshots blob id.
 477  * \param ids Array of the clone ids or NULL to get required size in count.
 478  * \param count Size of ids. After call it is updated to the number of clones.
 479  *
 480  * \return -ENOMEM if count is not sufficient to store all clones.
 481  */
 482 int spdk_blob_get_clones(struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_id *ids,
 483                          size_t *count);
 484
 485 /**
 486  * Get the blob id for the parent snapshot of this blob.
 487  *
 488  * \param bs blobstore.
 489  * \param blobid Blob id.
 490  *
 491  * \return blob id of parent blob or SPDK_BLOBID_INVALID if have no parent
 492  */
 493 spdk_blob_id spdk_blob_get_parent_snapshot(struct spdk_blob_store *bs, spdk_blob_id blobid);
 494
 495 /**
 496  * Check if blob is read only.
 497  *
 498  * \param blob Blob.
 499  *
 500  * \return true if blob is read only.
 501  */
 502 bool spdk_blob_is_read_only(struct spdk_blob *blob);
 503
 504 /**
 505  * Check if blob is a snapshot.
 506  *
 507  * \param blob Blob.
 508  *
 509  * \return true if blob is a snapshot.
 510  */
 511 bool spdk_blob_is_snapshot(struct spdk_blob *blob);
 512
 513 /**
 514  * Check if blob is a clone.
 515  *
 516  * \param blob Blob.
 517  *
 518  * \return true if blob is a clone.
 519  */
 520 bool spdk_blob_is_clone(struct spdk_blob *blob);
 521
 522 /**
 523  * Check if blob is thin-provisioned.
 524  *
 525  * \param blob Blob.
 526  *
 527  * \return true if blob is thin-provisioned.
 528  */
 529 bool spdk_blob_is_thin_provisioned(struct spdk_blob *blob);
 530
 531 /**
 532  * Delete an existing blob from the given blobstore.
 533  *
 534  * \param bs blobstore.
 535  * \param blobid The id of the blob to delete.
 536  * \param cb_fn Called when the operation is complete.
 537  * \param cb_arg Argument passed to function cb_fn.
 538  */
 539 void spdk_bs_delete_blob(struct spdk_blob_store *bs, spdk_blob_id blobid,
 540                          spdk_blob_op_complete cb_fn, void *cb_arg);
 541
 542 /**
 543  * Allocate all clusters in this blob. Data for allocated clusters is copied
 544  * from backing blob(s) if they exist.
 545  *
 546  * This call removes all dependencies on any backing blobs.
 547  *
 548  * \param bs blobstore.
 549  * \param channel IO channel used to inflate blob.
 550  * \param blobid The id of the blob to inflate.
 551  * \param cb_fn Called when the operation is complete.
 552  * \param cb_arg Argument passed to function cb_fn.
 553  */
 554 void spdk_bs_inflate_blob(struct spdk_blob_store *bs, struct spdk_io_channel *channel,
 555                           spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg);
 556
 557 /**
 558  * Remove dependency on parent blob.
 559  *
 560  * This call allocates and copies data for any clusters that are allocated in
 561  * the parent blob, and decouples parent updating dependencies of blob to
 562  * its ancestor.
 563  *
 564  * If blob have no parent -EINVAL error is reported.
 565  *
 566  * \param bs blobstore.
 567  * \param channel IO channel used to inflate blob.
 568  * \param blobid The id of the blob.
 569  * \param cb_fn Called when the operation is complete.
 570  * \param cb_arg Argument passed to function cb_fn.
 571  */
 572 void spdk_bs_blob_decouple_parent(struct spdk_blob_store *bs, struct spdk_io_channel *channel,
 573                                   spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg);
 574
 575 /**
 576  * Open a blob from the given blobstore.
 577  *
 578  * \param bs blobstore.
 579  * \param blobid The id of the blob to open.
 580  * \param cb_fn Called when the operation is complete.
 581  * \param cb_arg Argument passed to function cb_fn.
 582  */
 583 void spdk_bs_open_blob(struct spdk_blob_store *bs, spdk_blob_id blobid,
 584                        spdk_blob_op_with_handle_complete cb_fn, void *cb_arg);
 585
 586 /**
 587  * Resize a blob to 'sz' clusters. These changes are not persisted to disk until
 588  * spdk_bs_md_sync_blob() is called.
 589  * If called before previous resize finish, it will fail with errno -EBUSY
 590  *
 591  * \param blob Blob to resize.
 592  * \param sz The new number of clusters.
 593  * \param cb_fn Called when the operation is complete.
 594  * \param cb_arg Argument passed to function cb_fn.
 595  *
 596  */
 597 void spdk_blob_resize(struct spdk_blob *blob, uint64_t sz, spdk_blob_op_complete cb_fn,
 598                       void *cb_arg);
 599
 600 /**
 601  * Set blob as read only.
 602  *
 603  * These changes do not take effect until spdk_blob_sync_md() is called.
 604  *
 605  * \param blob Blob to set.
 606  */
 607 int spdk_blob_set_read_only(struct spdk_blob *blob);
 608
 609 /**
 610  * Sync a blob.
 611  *
 612  * Make a blob persistent. This applies to open, resize, set xattr, and remove
 613  * xattr. These operations will not be persistent until the blob has been synced.
 614  *
 615  * \param blob Blob to sync.
 616  * \param cb_fn Called when the operation is complete.
 617  * \param cb_arg Argument passed to function cb_fn.
 618  */
 619 void spdk_blob_sync_md(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg);
 620
 621 /**
 622  * Close a blob. This will automatically sync.
 623  *
 624  * \param blob Blob to close.
 625  * \param cb_fn Called when the operation is complete.
 626  * \param cb_arg Argument passed to function cb_fn.
 627  */
 628 void spdk_blob_close(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg);
 629
 630 /**
 631  * Allocate an I/O channel for the given blobstore.
 632  *
 633  * \param bs blobstore.
 634  * \return a pointer to the allocated I/O channel.
 635  */
 636 struct spdk_io_channel *spdk_bs_alloc_io_channel(struct spdk_blob_store *bs);
 637
 638 /**
 639  * Free the I/O channel.
 640  *
 641  * \param channel I/O channel to free.
 642  */
 643 void spdk_bs_free_io_channel(struct spdk_io_channel *channel);
 644
 645 /**
 646  * Write data to a blob.
 647  *
 648  * \param blob Blob to write.
 649  * \param channel The I/O channel used to submit requests.
 650  * \param payload The specified buffer which should contain the data to be written.
 651  * \param offset Offset is in io units from the beginning of the blob.
 652  * \param length Size of data in io units.
 653  * \param cb_fn Called when the operation is complete.
 654  * \param cb_arg Argument passed to function cb_fn.
 655  */
 656 void spdk_blob_io_write(struct spdk_blob *blob, struct spdk_io_channel *channel,
 657                         void *payload, uint64_t offset, uint64_t length,
 658                         spdk_blob_op_complete cb_fn, void *cb_arg);
 659
 660 /**
 661  * Read data from a blob.
 662  *
 663  * \param blob Blob to read.
 664  * \param channel The I/O channel used to submit requests.
 665  * \param payload The specified buffer which will store the obtained data.
 666  * \param offset Offset is in io units from the beginning of the blob.
 667  * \param length Size of data in io units.
 668  * \param cb_fn Called when the operation is complete.
 669  * \param cb_arg Argument passed to function cb_fn.
 670  */
 671 void spdk_blob_io_read(struct spdk_blob *blob, struct spdk_io_channel *channel,
 672                        void *payload, uint64_t offset, uint64_t length,
 673                        spdk_blob_op_complete cb_fn, void *cb_arg);
 674
 675 /**
 676  * Write the data described by 'iov' to 'length' pages beginning at 'offset' pages
 677  * into the blob.
 678  *
 679  * \param blob Blob to write.
 680  * \param channel I/O channel used to submit requests.
 681  * \param iov The pointer points to an array of iovec structures.
 682  * \param iovcnt The number of buffers.
 683  * \param offset Offset is in io units from the beginning of the blob.
 684  * \param length Size of data in io units.
 685  * \param cb_fn Called when the operation is complete.
 686  * \param cb_arg Argument passed to function cb_fn.
 687  */
 688 void spdk_blob_io_writev(struct spdk_blob *blob, struct spdk_io_channel *channel,
 689                          struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length,
 690                          spdk_blob_op_complete cb_fn, void *cb_arg);
 691
 692 /**
 693  * Read 'length' pages starting at 'offset' pages into the blob into the memory
 694  * described by 'iov'.
 695  *
 696  * \param blob Blob to read.
 697  * \param channel I/O channel used to submit requests.
 698  * \param iov The pointer points to an array of iovec structures.
 699  * \param iovcnt The number of buffers.
 700  * \param offset Offset is in io units from the beginning of the blob.
 701  * \param length Size of data in io units.
 702  * \param cb_fn Called when the operation is complete.
 703  * \param cb_arg Argument passed to function cb_fn.
 704  */
 705 void spdk_blob_io_readv(struct spdk_blob *blob, struct spdk_io_channel *channel,
 706                         struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length,
 707                         spdk_blob_op_complete cb_fn, void *cb_arg);
 708
 709 /**
 710  * Unmap 'length' pages beginning at 'offset' pages on the blob as unused. Unmapped
 711  * pages may allow the underlying storage media to behave more effciently.
 712  *
 713  * \param blob Blob to unmap.
 714  * \param channel I/O channel used to submit requests.
 715  * \param offset Offset is in io units from the beginning of the blob.
 716  * \param length Size of unmap area in pages.
 717  * \param cb_fn Called when the operation is complete.
 718  * \param cb_arg Argument passed to function cb_fn.
 719  */
 720 void spdk_blob_io_unmap(struct spdk_blob *blob, struct spdk_io_channel *channel,
 721                         uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg);
 722
 723 /**
 724  * Write zeros into area of a blob.
 725  *
 726  * \param blob Blob to write.
 727  * \param channel I/O channel used to submit requests.
 728  * \param offset Offset is in io units from the beginning of the blob.
 729  * \param length Size of data in io units.
 730  * \param cb_fn Called when the operation is complete.
 731  * \param cb_arg Argument passed to function cb_fn.
 732  */
 733 void spdk_blob_io_write_zeroes(struct spdk_blob *blob, struct spdk_io_channel *channel,
 734                                uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg);
 735
 736 /**
 737  * Get the first blob of the blobstore. The obtained blob will be passed to
 738  * the callback function.
 739  *
 740  * \param bs blobstore to traverse.
 741  * \param cb_fn Called when the operation is complete.
 742  * \param cb_arg Argument passed to function cb_fn.
 743  */
 744 void spdk_bs_iter_first(struct spdk_blob_store *bs,
 745                         spdk_blob_op_with_handle_complete cb_fn, void *cb_arg);
 746
 747 /**
 748  * Get the next blob by using the current blob. The obtained blob will be passed
 749  * to the callback function.
 750  *
 751  * \param bs blobstore to traverse.
 752  * \param blob The current blob.
 753  * \param cb_fn Called when the operation is complete.
 754  * \param cb_arg Argument passed to function cb_fn.
 755  */
 756 void spdk_bs_iter_next(struct spdk_blob_store *bs, struct spdk_blob *blob,
 757                        spdk_blob_op_with_handle_complete cb_fn, void *cb_arg);
 758
 759 /**
 760  * Set an extended attribute for the given blob.
 761  *
 762  * \param blob Blob to set attribute.
 763  * \param name Name of the extended attribute.
 764  * \param value Value of the extended attribute.
 765  * \param value_len Length of the value.
 766  *
 767  * \return 0 on success, -1 on failure.
 768  */
 769 int spdk_blob_set_xattr(struct spdk_blob *blob, const char *name, const void *value,
 770                         uint16_t value_len);
 771
 772 /**
 773  * Remove the extended attribute from the given blob.
 774  *
 775  * \param blob Blob to remove attribute.
 776  * \param name Name of the extended attribute.
 777  *
 778  * \return 0 on success, negative errno on failure.
 779  */
 780 int spdk_blob_remove_xattr(struct spdk_blob *blob, const char *name);
 781
 782 /**
 783  * Get the value of the specified extended attribute. The obtained value and its
 784  * size will be stored in value and value_len.
 785  *
 786  * \param blob Blob to query.
 787  * \param name Name of the extended attribute.
 788  * \param value Parameter as output.
 789  * \param value_len Parameter as output.
 790  *
 791  * \return 0 on success, negative errno on failure.
 792  */
 793 int spdk_blob_get_xattr_value(struct spdk_blob *blob, const char *name,
 794                               const void **value, size_t *value_len);
 795
 796 /**
 797  * Iterate through all extended attributes of the blob. Get the names of all extended
 798  * attributes that will be stored in names.
 799  *
 800  * \param blob Blob to query.
 801  * \param names Parameter as output.
 802  *
 803  * \return 0 on success, negative errno on failure.
 804  */
 805 int spdk_blob_get_xattr_names(struct spdk_blob *blob, struct spdk_xattr_names **names);
 806
 807 /**
 808  * Get the number of extended attributes.
 809  *
 810  * \param names Names of total extended attributes of the blob.
 811  *
 812  * \return the number of extended attributes.
 813  */
 814 uint32_t spdk_xattr_names_get_count(struct spdk_xattr_names *names);
 815
 816 /**
 817  * Get the attribute name specified by the index.
 818  *
 819  * \param names Names of total extended attributes of the blob.
 820  * \param index Index position of the specified attribute.
 821  *
 822  * \return attribute name.
 823  */
 824 const char *spdk_xattr_names_get_name(struct spdk_xattr_names *names, uint32_t index);
 825
 826 /**
 827  * Free the attribute names.
 828  *
 829  * \param names Names of total extended attributes of the blob.
 830  */
 831 void spdk_xattr_names_free(struct spdk_xattr_names *names);
 832
 833 /**
 834  * Get blobstore type of the given device.
 835  *
 836  * \param bs blobstore to query.
 837  *
 838  * \return blobstore type.
 839  */
 840 struct spdk_bs_type spdk_bs_get_bstype(struct spdk_blob_store *bs);
 841
 842 /**
 843  * Set blobstore type to the given device.
 844  *
 845  * \param bs blobstore to set to.
 846  * \param bstype Type label to set.
 847  */
 848 void spdk_bs_set_bstype(struct spdk_blob_store *bs, struct spdk_bs_type bstype);
 849
 850 #ifdef __cplusplus
 851 }
 852 #endif
 853
 854 #endif /* SPDK_BLOB_H_ */