1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2017 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 /** \file 7 * SPDK Filesystem 8 */ 9 10 #ifndef SPDK_FS_H 11 #define SPDK_FS_H 12 13 #include "spdk/stdinc.h" 14 15 #include "spdk/blob.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #define SPDK_FILE_NAME_MAX 255 22 23 struct spdk_file; 24 struct spdk_filesystem; 25 26 typedef struct spdk_file *spdk_fs_iter; 27 28 struct spdk_blobfs_opts { 29 uint32_t cluster_sz; 30 }; 31 32 struct spdk_file_stat { 33 spdk_blob_id blobid; 34 uint64_t size; 35 }; 36 37 /** 38 * Filesystem operation completion callback with handle. 39 * 40 * \param ctx Context for the operation. 41 * \param fs Handle to a blobfs. 42 * \param fserrno 0 if it completed successfully, or negative errno if it failed. 43 */ 44 typedef void (*spdk_fs_op_with_handle_complete)(void *ctx, struct spdk_filesystem *fs, 45 int fserrno); 46 47 /** 48 * File operation completion callback with handle. 49 * 50 * \param ctx Context for the operation. 51 * \param f Handle to a file. 52 * \param fserrno 0 if it completed successfully, or negative errno if it failed. 53 */ 54 typedef void (*spdk_file_op_with_handle_complete)(void *ctx, struct spdk_file *f, int fserrno); 55 typedef spdk_bs_op_complete spdk_fs_op_complete; 56 57 /** 58 * File operation completion callback. 59 * 60 * \param ctx Context for the operation. 61 * \param fserrno 0 if it completed successfully, or negative errno if it failed. 62 */ 63 typedef void (*spdk_file_op_complete)(void *ctx, int fserrno); 64 65 /** 66 * File stat operation completion callback. 67 * 68 * \param ctx Context for the operation. 69 * \param stat Handle to the stat about the file. 70 * \param fserrno 0 if it completed successfully, or negative errno if it failed. 71 */ 72 typedef void (*spdk_file_stat_op_complete)(void *ctx, struct spdk_file_stat *stat, int fserrno); 73 74 /** 75 * Function for a request of file system. 76 * 77 * \param arg Argument to the request function. 78 */ 79 typedef void (*fs_request_fn)(void *arg); 80 81 /** 82 * Function for sending request. 83 * 84 * This function will be invoked any time when the filesystem wants to pass a 85 * message to the main dispatch thread. 86 * 87 * \param fn A pointer to the request function. 88 * \param arg Argument to the request function. 89 */ 90 typedef void (*fs_send_request_fn)(fs_request_fn fn, void *arg); 91 92 /** 93 * Initialize a spdk_blobfs_opts structure to the default option values. 94 * 95 * \param opts spdk_blobf_opts structure to initialize. 96 */ 97 void spdk_fs_opts_init(struct spdk_blobfs_opts *opts); 98 99 /** 100 * Initialize blobstore filesystem. 101 * 102 * Initialize the blobstore filesystem on the blobstore block device which has 103 * been created by the function spdk_bdev_create_bs_dev() in the blob_bdev.h. 104 * The obtained blobstore filesystem will be passed to the callback function. 105 * 106 * \param dev Blobstore block device used by this blobstore filesystem. 107 * \param opt Initialization options used for this blobstore filesystem. 108 * \param send_request_fn The function for sending request. This function will 109 * be invoked any time when the blobstore filesystem wants to pass a message to 110 * the main dispatch thread. 111 * \param cb_fn Called when the initialization is complete. 112 * \param cb_arg Argument passed to function cb_fn. 113 */ 114 void spdk_fs_init(struct spdk_bs_dev *dev, struct spdk_blobfs_opts *opt, 115 fs_send_request_fn send_request_fn, 116 spdk_fs_op_with_handle_complete cb_fn, void *cb_arg); 117 118 /** 119 * Load blobstore filesystem from the given blobstore block device. 120 * 121 * The obtained blobstore filesystem will be passed to the callback function. 122 * 123 * \param dev Blobstore block device used by this blobstore filesystem. 124 * \param send_request_fn The function for sending request. This function will 125 * be invoked any time when the blobstore filesystem wants to pass a message to 126 * the main dispatch thread. 127 * \param cb_fn Called when the loading is complete. 128 * \param cb_arg Argument passed to function cb_fn. 129 */ 130 void spdk_fs_load(struct spdk_bs_dev *dev, fs_send_request_fn send_request_fn, 131 spdk_fs_op_with_handle_complete cb_fn, void *cb_arg); 132 133 /** 134 * Unload blobstore filesystem. 135 * 136 * \param fs Blobstore filesystem to unload. 137 * \param cb_fn Called when the unloading is complete. 138 * \param cb_arg Argument passed to function cb_fn. 139 */ 140 void spdk_fs_unload(struct spdk_filesystem *fs, spdk_fs_op_complete cb_fn, void *cb_arg); 141 142 /** 143 * Allocate an I/O channel for asynchronous operations. 144 * 145 * \param fs Blobstore filesystem to allocate I/O channel. 146 * 147 * \return a pointer to the I/O channel on success or NULL otherwise. 148 */ 149 struct spdk_io_channel *spdk_fs_alloc_io_channel(struct spdk_filesystem *fs); 150 151 /** 152 * Free I/O channel. 153 * 154 * This function will decrease the references of this I/O channel. If the reference 155 * is reduced to 0, the I/O channel will be freed. 156 * 157 * \param channel I/O channel to free. 158 */ 159 void spdk_fs_free_io_channel(struct spdk_io_channel *channel); 160 161 /** 162 * Allocate a context for synchronous operations. 163 * 164 * \param fs Blobstore filesystem for this context. 165 * 166 * \return a pointer to the context on success or NULL otherwise. 167 */ 168 struct spdk_fs_thread_ctx *spdk_fs_alloc_thread_ctx(struct spdk_filesystem *fs); 169 170 /** 171 * Free thread context. 172 * 173 * \param ctx Thread context to free. 174 */ 175 void spdk_fs_free_thread_ctx(struct spdk_fs_thread_ctx *ctx); 176 177 /** 178 * Get statistics about the file including the underlying blob id and the file size. 179 * 180 * \param fs Blobstore filesystem. 181 * \param ctx The thread context for this operation 182 * \param name The file name used to look up the matched file in the blobstore filesystem. 183 * \param stat Caller allocated structure to store the obtained information about 184 * this file. 185 * 186 * \return 0 on success, negative errno on failure. 187 */ 188 int spdk_fs_file_stat(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, 189 const char *name, struct spdk_file_stat *stat); 190 191 #define SPDK_BLOBFS_OPEN_CREATE (1ULL << 0) 192 193 /** 194 * Create a new file on the given blobstore filesystem. 195 * 196 * \param fs Blobstore filesystem. 197 * \param ctx The thread context for this operation 198 * \param name The file name for this new file. 199 * 200 * \return 0 on success, negative errno on failure. 201 */ 202 int spdk_fs_create_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, 203 const char *name); 204 205 /** 206 * Open the file. 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 flags This flags will be used to control the open mode. 212 * \param file It will point to the open file if successful or NULL otherwise. 213 * 214 * \return 0 on success, negative errno on failure. 215 */ 216 int spdk_fs_open_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, 217 const char *name, uint32_t flags, struct spdk_file **file); 218 219 /** 220 * Close the file. 221 * 222 * \param file File to close. 223 * \param ctx The thread context for this operation 224 * 225 * \return 0 on success, negative errno on failure. 226 */ 227 int spdk_file_close(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx); 228 229 /** 230 * Change the file name. 231 * 232 * This operation will overwrite an existing file if there is a file with the 233 * same name. 234 * 235 * \param fs Blobstore filesystem. 236 * \param ctx The thread context for this operation 237 * \param old_name Old name of the file. 238 * \param new_name New name of the file. 239 * 240 * \return 0 on success, negative errno on failure. 241 */ 242 int spdk_fs_rename_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, 243 const char *old_name, const char *new_name); 244 245 /** 246 * Delete the file. 247 * 248 * \param fs Blobstore filesystem. 249 * \param ctx The thread context for this operation 250 * \param name The name of the file to be deleted. 251 * 252 * \return 0 on success, negative errno on failure. 253 */ 254 int spdk_fs_delete_file(struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, 255 const char *name); 256 257 /** 258 * Get the first file in the blobstore filesystem. 259 * 260 * \param fs Blobstore filesystem to traverse. 261 * 262 * \return an iterator which points to the first file in the blobstore filesystem. 263 */ 264 spdk_fs_iter spdk_fs_iter_first(struct spdk_filesystem *fs); 265 266 /** 267 * Get the next file in the blobstore filesystem by using the input iterator. 268 * 269 * \param iter The iterator which points to the current file struct. 270 * 271 * \return an iterator which points to the next file in the blobstore filesystem. 272 */ 273 spdk_fs_iter spdk_fs_iter_next(spdk_fs_iter iter); 274 275 #define spdk_fs_iter_get_file(iter) ((struct spdk_file *)(iter)) 276 277 /** 278 * Truncate the file. 279 * 280 * \param file File to truncate. 281 * \param ctx The thread context for this operation 282 * \param length New size in bytes of the file. 283 * 284 * \return 0 on success, negative errno on failure. 285 */ 286 int spdk_file_truncate(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, 287 uint64_t length); 288 289 /** 290 * Get file name. 291 * 292 * \param file File to query. 293 * 294 * \return the name of the file. 295 */ 296 const char *spdk_file_get_name(struct spdk_file *file); 297 298 /** 299 * Obtain the size of the file. 300 * 301 * \param file File to query. 302 * 303 * \return the size in bytes of the file. 304 */ 305 uint64_t spdk_file_get_length(struct spdk_file *file); 306 307 /** 308 * Write data to the given file. 309 * 310 * \param file File to write. 311 * \param ctx The thread context for this operation 312 * \param payload The specified buffer which should contain the data to be transmitted. 313 * \param offset The beginning position to write data. 314 * \param length The size in bytes of data to write. 315 * 316 * \return 0 on success, negative errno on failure. 317 */ 318 int spdk_file_write(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, 319 void *payload, uint64_t offset, uint64_t length); 320 321 /** 322 * Read data to user buffer from the given file. 323 * 324 * \param file File to read. 325 * \param ctx The thread context for this operation 326 * \param payload The specified buffer which will store the obtained data. 327 * \param offset The beginning position to read. 328 * \param length The size in bytes of data to read. 329 * 330 * \return the end position of this read operation on success, negated errno on failure. 331 */ 332 int64_t spdk_file_read(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, 333 void *payload, uint64_t offset, uint64_t length); 334 335 /** 336 * Set cache size for the blobstore filesystem. 337 * 338 * \param size_in_mb Cache size in megabytes. 339 * 340 * \return 0 on success, negative errno on failure. 341 */ 342 int spdk_fs_set_cache_size(uint64_t size_in_mb); 343 344 /** 345 * Obtain the cache size. 346 * 347 * \return cache size in megabytes. 348 */ 349 uint64_t spdk_fs_get_cache_size(void); 350 351 #define SPDK_FILE_PRIORITY_LOW 0 /* default */ 352 #define SPDK_FILE_PRIORITY_HIGH 1 353 354 /** 355 * Set priority for the file. 356 * 357 * \param file File to set priority. 358 * \param priority Priority level (SPDK_FILE_PRIORITY_LOW or SPDK_FILE_PRIORITY_HIGH). 359 */ 360 void spdk_file_set_priority(struct spdk_file *file, uint32_t priority); 361 362 /** 363 * Synchronize the data from the cache to the disk. 364 * 365 * \param file File to sync. 366 * \param ctx The thread context for this operation 367 * 368 * \return 0 on success. 369 */ 370 int spdk_file_sync(struct spdk_file *file, struct spdk_fs_thread_ctx *ctx); 371 372 /** 373 * Get the unique ID for the file. 374 * 375 * \param file File to get the ID. 376 * \param id ID buffer. 377 * \param size Size of the ID buffer. 378 * 379 * \return the length of ID on success. 380 */ 381 int spdk_file_get_id(struct spdk_file *file, void *id, size_t size); 382 383 /** 384 * Read data to user buffer from the given file. 385 * 386 * \param file File to read. 387 * \param channel I/O channel for asynchronous operations. 388 * \param iovs A scatter gather list of buffers to be read into. 389 * \param iovcnt The number of elements in iov. 390 * \param offset The beginning position to read. 391 * \param length The size in bytes of data to read. 392 * \param cb_fn Called when the request is complete. 393 * \param cb_arg Argument passed to cb_fn. 394 */ 395 void spdk_file_readv_async(struct spdk_file *file, struct spdk_io_channel *channel, 396 struct iovec *iovs, uint32_t iovcnt, uint64_t offset, uint64_t length, 397 spdk_file_op_complete cb_fn, void *cb_arg); 398 399 /** 400 * Write data to the given file. 401 * 402 * \param file File to write. 403 * \param channel I/O channel for asynchronous operations. 404 * \param iovs A scatter gather list of buffers to be written from. 405 * \param iovcnt The number of elements in iov. 406 * \param offset The beginning position to write. 407 * \param length The size in bytes of data to write. 408 * \param cb_fn Called when the request is complete. 409 * \param cb_arg Argument passed to cb_fn. 410 */ 411 void spdk_file_writev_async(struct spdk_file *file, struct spdk_io_channel *channel, 412 struct iovec *iovs, uint32_t iovcnt, uint64_t offset, uint64_t length, 413 spdk_file_op_complete cb_fn, void *cb_arg); 414 415 /** 416 * Get statistics about the file including the underlying blob id and the file size. 417 * 418 * \param fs Blobstore filesystem. 419 * \param name The file name used to look up the matched file in the blobstore filesystem. 420 * \param cb_fn Called when the request is complete. 421 * \param cb_arg Argument passed to cb_fn. 422 */ 423 void spdk_fs_file_stat_async(struct spdk_filesystem *fs, const char *name, 424 spdk_file_stat_op_complete cb_fn, void *cb_arg); 425 426 /** 427 * Create a new file on the given blobstore filesystem. 428 * 429 * \param fs Blobstore filesystem. 430 * \param name The file name for this new file. 431 * \param cb_fn Called when the request is complete. 432 * \param cb_arg Argument passed to cb_fn. 433 */ 434 void spdk_fs_create_file_async(struct spdk_filesystem *fs, const char *name, 435 spdk_file_op_complete cb_fn, void *cb_arg); 436 437 /** 438 * Open the file. 439 * 440 * \param fs Blobstore filesystem. 441 * \param name The file name used to look up the matched file in the blobstore filesystem. 442 * \param flags This flags will be used to control the open mode. 443 * \param cb_fn Called when the request is complete. 444 * \param cb_arg Argument passed to cb_fn. 445 */ 446 void spdk_fs_open_file_async(struct spdk_filesystem *fs, const char *name, uint32_t flags, 447 spdk_file_op_with_handle_complete cb_fn, void *cb_arg); 448 449 /** 450 * Close the file. 451 * 452 * \param file File to close. 453 * \param cb_fn Called when the request is complete. 454 * \param cb_arg Argument passed to cb_fn. 455 */ 456 void spdk_file_close_async(struct spdk_file *file, spdk_file_op_complete cb_fn, void *cb_arg); 457 458 459 /** 460 * Change the file name. 461 * 462 * This operation will overwrite an existing file if there is a file with the 463 * same name. 464 * 465 * \param fs Blobstore filesystem. 466 * \param old_name Old name of the file. 467 * \param new_name New name of the file. 468 * \param cb_fn Called when the request is complete. 469 * \param cb_arg Argument passed to cb_fn. 470 */ 471 void spdk_fs_rename_file_async(struct spdk_filesystem *fs, const char *old_name, 472 const char *new_name, spdk_fs_op_complete cb_fn, 473 void *cb_arg); 474 475 /** 476 * Delete the file. 477 * 478 * \param fs Blobstore filesystem. 479 * \param name The name of the file to be deleted. 480 * \param cb_fn Called when the request is complete. 481 * \param cb_arg Argument passed to cb_fn. 482 */ 483 void spdk_fs_delete_file_async(struct spdk_filesystem *fs, const char *name, 484 spdk_file_op_complete cb_fn, void *cb_arg); 485 486 /** 487 * Truncate the file. 488 * 489 * \param file File to truncate. 490 * \param length New size in bytes of the file. 491 * \param cb_fn Called when the request is complete. 492 * \param cb_arg Argument passed to cb_fn. 493 */ 494 void spdk_file_truncate_async(struct spdk_file *file, uint64_t length, 495 spdk_file_op_complete cb_fn, void *cb_arg); 496 497 /** 498 * Write data to the given file. 499 * 500 * \param file File to write. 501 * \param channel I/O channel for asynchronous operations. 502 * \param payload The specified buffer which should contain the data to be transmitted. 503 * \param offset The beginning position to write data. 504 * \param length The size in bytes of data to write. 505 * \param cb_fn Called when the request is complete. 506 * \param cb_arg Argument passed to cb_fn. 507 */ 508 void spdk_file_write_async(struct spdk_file *file, struct spdk_io_channel *channel, 509 void *payload, uint64_t offset, uint64_t length, 510 spdk_file_op_complete cb_fn, void *cb_arg); 511 512 /** 513 * Read data to user buffer from the given file. 514 * 515 * \param file File to write. 516 * \param channel I/O channel for asynchronous operations. 517 * \param payload The specified buffer which will store the obtained data. 518 * \param offset The beginning position to read. 519 * \param length The size in bytes of data to read. 520 * \param cb_fn Called when the request is complete. 521 * \param cb_arg Argument passed to cb_fn. 522 */ 523 void spdk_file_read_async(struct spdk_file *file, struct spdk_io_channel *channel, 524 void *payload, uint64_t offset, uint64_t length, 525 spdk_file_op_complete cb_fn, void *cb_arg); 526 527 /** 528 * Sync all dirty cache buffers to the backing block device. For async 529 * usage models, completion of the sync indicates only that data written 530 * when the sync command was issued have been flushed to disk - it does 531 * not guarantee any writes submitted after the sync have been flushed, 532 * even if those writes are completed before the sync. 533 * 534 * \param file File to write. 535 * \param channel I/O channel for asynchronous operations. 536 * \param cb_fn Called when the request is complete. 537 * \param cb_arg Argument passed to cb_fn. 538 */ 539 void spdk_file_sync_async(struct spdk_file *file, struct spdk_io_channel *channel, 540 spdk_file_op_complete cb_fn, void *cb_arg); 541 542 #ifdef __cplusplus 543 } 544 #endif 545 546 #endif /* SPDK_FS_H_ */ 547