ceph/src/spdk/include/spdk/blobfs.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  * SPDK Filesystem
  36  */
  37
  38 #ifndef SPDK_FS_H
  39 #define SPDK_FS_H
  40
  41 #include "spdk/stdinc.h"
  42
  43 #include "spdk/blob.h"
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 #define SPDK_FILE_NAME_MAX      255
  50
  51 struct spdk_file;
  52 struct spdk_filesystem;
  53
  54 typedef struct spdk_file *spdk_fs_iter;
  55
  56 struct spdk_blobfs_opts {
  57         uint32_t        cluster_sz;
  58 };
  59
  60 struct spdk_file_stat {
  61         spdk_blob_id    blobid;
  62         uint64_t        size;
  63 };
  64
  65 /**
  66  * Filesystem operation completion callback with handle.
  67  *
  68  * \param ctx Context for the operation.
  69  * \param fs Handle to a blobfs.
  70  * \param fserrno 0 if it completed successfully, or negative errno if it failed.
  71  */
  72 typedef void (*spdk_fs_op_with_handle_complete)(void *ctx, struct spdk_filesystem *fs,
  73                 int fserrno);
  74
  75 /**
  76  * File operation completion callback with handle.
  77  *
  78  * \param ctx Context for the operation.
  79  * \param f Handle to a file.
  80  * \param fserrno 0 if it completed successfully, or negative errno if it failed.
  81  */
  82 typedef void (*spdk_file_op_with_handle_complete)(void *ctx, struct spdk_file *f, int fserrno);
  83 typedef spdk_bs_op_complete spdk_fs_op_complete;
  84
  85 /**
  86  * File operation completion callback.
  87  *
  88  * \param ctx Context for the operation.
  89  * \param fserrno 0 if it completed successfully, or negative errno if it failed.
  90  */
  91 typedef void (*spdk_file_op_complete)(void *ctx, int fserrno);
  92
  93 /**
  94  * File stat operation completion callback.
  95  *
  96  * \param ctx Context for the operation.
  97  * \param stat Handle to the stat about the file.
  98  * \param fserrno 0 if it completed successfully, or negative errno if it failed.
  99  */
 100 typedef void (*spdk_file_stat_op_complete)(void *ctx, struct spdk_file_stat *stat, int fserrno);
 101
 102 /**
 103  * Function for a request of file system.
 104  *
 105  * \param arg Argument to the request function.
 106  */
 107 typedef void (*fs_request_fn)(void *arg);
 108
 109 /**
 110  * Function for sending request.
 111  *
 112  * This function will be invoked any time when the filesystem wants to pass a
 113  * message to the main dispatch thread.
 114  *
 115  * \param fs_request_fn A pointer to the request function.
 116  * \param arg Argument to the request function.
 117  */
 118 typedef void (*fs_send_request_fn)(fs_request_fn, void *arg);
 119
 120 /**
 121  * Initialize a spdk_blobfs_opts structure to the default option values.
 122  *
 123  * \param opts spdk_blobf_opts struture to intialize.
 124  */
 125 void spdk_fs_opts_init(struct spdk_blobfs_opts *opts);
 126
 127 /**
 128  * Initialize blobstore filesystem.
 129  *
 130  * Initialize the blobstore filesystem on the blobstore block device which has
 131  * been created by the function spdk_bdev_create_bs_dev() in the blob_bdev.h.
 132  * The obtained blobstore filesystem will be passed to the callback function.
 133  *
 134  * \param dev Blobstore block device used by this blobstore filesystem.
 135  * \param opt Initialization options used for this blobstore filesystem.
 136  * \param send_request_fn The function for sending request. This function will
 137  * be invoked any time when the blobstore filesystem wants to pass a message to
 138  * the main dispatch thread.
 139  * \param cb_fn Called when the initialization is complete.
 140  * \param cb_arg Argument passed to function cb_fn.
 141  */
 142 void spdk_fs_init(struct spdk_bs_dev *dev, struct spdk_blobfs_opts *opt,
 143                   fs_send_request_fn send_request_fn,
 144                   spdk_fs_op_with_handle_complete cb_fn, void *cb_arg);
 145
 146 /**
 147  * Load blobstore filesystem from the given blobstore block device.
 148  *
 149  * The obtained blobstore filesystem will be passed to the callback function.
 150  *
 151  * \param dev Blobstore block device used by this blobstore filesystem.
 152  * \param send_request_fn The function for sending request. This function will
 153  * be invoked any time when the blobstore filesystem wants to pass a message to
 154  * the main dispatch thread.
 155  * \param cb_fn Called when the loading is complete.
 156  * \param cb_arg Argument passed to function cb_fn.
 157  */
 158 void spdk_fs_load(struct spdk_bs_dev *dev, fs_send_request_fn send_request_fn,
 159                   spdk_fs_op_with_handle_complete cb_fn, void *cb_arg);
 160
 161 /**
 162  * Unload blobstore filesystem.
 163  *
 164  * \param fs Blobstore filesystem to unload.
 165  * \param cb_fn Called when the unloading is complete.
 166  * \param cb_arg Argument passed to function cb_fn.
 167  */
 168 void spdk_fs_unload(struct spdk_filesystem *fs, spdk_fs_op_complete cb_fn, void *cb_arg);
 169
 170 /**
 171  * Allocate an I/O channel for asynchronous operations.
 172  *
 173  * \param fs Blobstore filesystem to allocate I/O channel.
 174  *
 175  * \return a pointer to the I/O channel on success or NULL otherwise.
 176  */
 177 struct spdk_io_channel *spdk_fs_alloc_io_channel(struct spdk_filesystem *fs);
 178
 179 /**
 180  * Free I/O channel.
 181  *
 182  * This function will decrease the references of this I/O channel. If the reference
 183  * is reduced to 0, the I/O channel will be freed.
 184  *
 185  * \param channel I/O channel to free.
 186  */
 187 void spdk_fs_free_io_channel(struct spdk_io_channel *channel);
 188
 189 /**
 190  * Allocate a context for synchronous operations.
 191  *
 192  * \param fs Blobstore filesystem for this context.
 193  *
 194  * \return a pointer to the context on success or NULL otherwise.
 195  */
 196 struct spdk_fs_thread_ctx *spdk_fs_alloc_thread_ctx(struct spdk_filesystem *fs);
 197
 198 /**
 199  * Free thread context.
 200  *
 201  * \param ctx Thread context to free.
 202  */
 203 void spdk_fs_free_thread_ctx(struct spdk_fs_thread_ctx *ctx);
 204
 205 /**
 206  * Get statistics about the file including the underlying blob id and the file size.
 207  *
 208  * \param fs Blobstore filesystem.
 209  * \param ctx The thread context for this operation
 210  * \param name The file name used to look up the matched file in the blobstore filesystem.
 211  * \param stat Caller allocated structure to store the obtained information about
 212  * this file.
 213  *
 214  * \return 0 on success, negative errno on failure.
 215  */
 216 int spdk_fs_file_stat(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx,
 217                       const char *name, struct spdk_file_stat *stat);
 218
 219 #define SPDK_BLOBFS_OPEN_CREATE (1ULL << 0)
 220
 221 /**
 222  * Create a new file on the given blobstore filesystem.
 223  *
 224  * \param fs Blobstore filesystem.
 225  * \param ctx The thread context for this operation
 226  * \param name The file name for this new file.
 227  *
 228  * \return 0 on success, negative errno on failure.
 229  */
 230 int spdk_fs_create_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx,
 231                         const char *name);
 232
 233 /**
 234  * Open the file.
 235  *
 236  * \param fs Blobstore filesystem.
 237  * \param ctx The thread context for this operation
 238  * \param name The file name used to look up the matched file in the blobstore filesystem.
 239  * \param flags This flags will be used to control the open mode.
 240  * \param file It will point to the open file if sccessful or NULL otherwirse.
 241  *
 242  * \return 0 on success, negative errno on failure.
 243  */
 244 int spdk_fs_open_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx,
 245                       const char *name, uint32_t flags, struct spdk_file **file);
 246
 247 /**
 248  * Close the file.
 249  *
 250  * \param file File to close.
 251  * \param ctx The thread context for this operation
 252  *
 253  * \return 0 on success, negative errno on failure.
 254  */
 255 int spdk_file_close(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx);
 256
 257 /**
 258  * Change the file name.
 259  *
 260  * This operation will overwrite an existing file if there is a file with the
 261  * same name.
 262  *
 263  * \param fs Blobstore filesystem.
 264  * \param ctx The thread context for this operation
 265  * \param old_name Old name of the file.
 266  * \param new_name New name of the file.
 267  *
 268  * \return 0 on success, negative errno on failure.
 269  */
 270 int spdk_fs_rename_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx,
 271                         const char *old_name, const char *new_name);
 272
 273 /**
 274  * Delete the file.
 275  *
 276  * \param fs Blobstore filesystem.
 277  * \param ctx The thread context for this operation
 278  * \param name The name of the file to be deleted.
 279  *
 280  * \return 0 on success, negative errno on failure.
 281  */
 282 int spdk_fs_delete_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx,
 283                         const char *name);
 284
 285 /**
 286  * Get the first file in the blobstore filesystem.
 287  *
 288  * \param fs Blobstore filesystem to traverse.
 289  *
 290  * \return an iterator which points to the first file in the blobstore filesystem.
 291  */
 292 spdk_fs_iter spdk_fs_iter_first(struct spdk_filesystem *fs);
 293
 294 /**
 295  * Get the next file in the blobstore filesystem by using the input iterator.
 296  *
 297  * \param iter The iterator which points to the current file struct.
 298  *
 299  * \return an iterator which points to the next file in the blobstore filesystem.
 300  */
 301 spdk_fs_iter spdk_fs_iter_next(spdk_fs_iter iter);
 302
 303 #define spdk_fs_iter_get_file(iter)     ((struct spdk_file *)(iter))
 304
 305 /**
 306  * Truncate the file.
 307  *
 308  * \param file File to truncate.
 309  * \param ctx The thread context for this operation
 310  * \param length New size in bytes of the file.
 311  *
 312  * \return 0 on success, negative errno on failure.
 313  */
 314 int spdk_file_truncate(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx,
 315                        uint64_t length);
 316
 317 /**
 318  * Get file name.
 319  *
 320  * \param file File to query.
 321  *
 322  * \return the name of the file.
 323  */
 324 const char *spdk_file_get_name(struct spdk_file *file);
 325
 326 /**
 327  * Obtain the size of the file.
 328  *
 329  * \param file File to query.
 330  *
 331  * \return the size in bytes of the file.
 332  */
 333 uint64_t spdk_file_get_length(struct spdk_file *file);
 334
 335 /**
 336  * Write data to the given file.
 337  *
 338  * \param file File to write.
 339  * \param ctx The thread context for this operation
 340  * \param payload The specified buffer which should contain the data to be transmitted.
 341  * \param offset The beginning position to write data.
 342  * \param length The size in bytes of data to write.
 343  *
 344  * \return 0 on success, negative errno on failure.
 345  */
 346 int spdk_file_write(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx,
 347                     void *payload, uint64_t offset, uint64_t length);
 348
 349 /**
 350  * Read data to user buffer from the given file.
 351  *
 352  * \param file File to read.
 353  * \param ctx The thread context for this operation
 354  * \param payload The specified buffer which will store the obtained data.
 355  * \param offset The beginning position to read.
 356  * \param length The size in bytes of data to read.
 357  *
 358  * \return the end position of this read operation on success, negated errno on failure.
 359  */
 360 int64_t spdk_file_read(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx,
 361                        void *payload, uint64_t offset, uint64_t length);
 362
 363 /**
 364  * Set cache size for the blobstore filesystem.
 365  *
 366  * \param size_in_mb Cache size in megabytes.
 367  */
 368 void spdk_fs_set_cache_size(uint64_t size_in_mb);
 369
 370 /**
 371  * Obtain the cache size.
 372  *
 373  * \return cache size in megabytes.
 374  */
 375 uint64_t spdk_fs_get_cache_size(void);
 376
 377 #define SPDK_FILE_PRIORITY_LOW  0 /* default */
 378 #define SPDK_FILE_PRIORITY_HIGH 1
 379
 380 /**
 381  * Set priority for the file.
 382  *
 383  * \param file File to set priority.
 384  * \param priority Priority level (SPDK_FILE_PRIORITY_LOW or SPDK_FILE_PRIORITY_HIGH).
 385  */
 386 void spdk_file_set_priority(struct spdk_file *file, uint32_t priority);
 387
 388 /**
 389  * Synchronize the data from the cache to the disk.
 390  *
 391  * \param file File to sync.
 392  * \param ctx The thread context for this operation
 393  *
 394  * \return 0 on success.
 395  */
 396 int spdk_file_sync(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx);
 397
 398 /**
 399  * Get the unique ID for the file.
 400  *
 401  * \param file File to get the ID.
 402  * \param id ID buffer.
 403  * \param size Size of the ID buffer.
 404  *
 405  * \return the length of ID on success.
 406  */
 407 int spdk_file_get_id(struct spdk_file *file, void *id, size_t size);
 408
 409 #ifdef __cplusplus
 410 }
 411 #endif
 412
 413 #endif /* SPDK_FS_H_ */