4 * Copyright (c) Intel Corporation.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
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
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.
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.
35 * Block device abstraction layer
41 #include "spdk/stdinc.h"
43 #include "spdk/scsi_spec.h"
44 #include "spdk/nvme_spec.h"
45 #include "spdk/json.h"
46 #include "spdk/queue.h"
52 #define SPDK_BDEV_SMALL_BUF_MAX_SIZE 8192
53 #define SPDK_BDEV_LARGE_BUF_MAX_SIZE (64 * 1024)
56 * Block device remove callback.
58 * \param remove_ctx Context for the removed block device.
60 typedef void (*spdk_bdev_remove_cb_t
)(void *remove_ctx
);
65 * This is an I/O that is passed to an spdk_bdev.
69 struct spdk_bdev_fn_table
;
70 struct spdk_io_channel
;
71 struct spdk_json_write_ctx
;
75 enum spdk_bdev_status
{
76 SPDK_BDEV_STATUS_INVALID
,
77 SPDK_BDEV_STATUS_READY
,
78 SPDK_BDEV_STATUS_REMOVING
,
82 * \brief SPDK block device.
84 * This is a virtual representation of a block device that is exported by the backend.
89 * \brief Handle to an opened SPDK block device.
91 struct spdk_bdev_desc
;
94 enum spdk_bdev_io_type
{
95 SPDK_BDEV_IO_TYPE_INVALID
= 0,
96 SPDK_BDEV_IO_TYPE_READ
,
97 SPDK_BDEV_IO_TYPE_WRITE
,
98 SPDK_BDEV_IO_TYPE_UNMAP
,
99 SPDK_BDEV_IO_TYPE_FLUSH
,
100 SPDK_BDEV_IO_TYPE_RESET
,
101 SPDK_BDEV_IO_TYPE_NVME_ADMIN
,
102 SPDK_BDEV_IO_TYPE_NVME_IO
,
103 SPDK_BDEV_IO_TYPE_NVME_IO_MD
,
104 SPDK_BDEV_IO_TYPE_WRITE_ZEROES
,
105 SPDK_BDEV_NUM_IO_TYPES
/* Keep last */
108 /** bdev QoS rate limit type */
109 enum spdk_bdev_qos_rate_limit_type
{
110 /** IOPS rate limit for both read and write */
111 SPDK_BDEV_QOS_RW_IOPS_RATE_LIMIT
= 0,
112 /** Byte per second rate limit for both read and write */
113 SPDK_BDEV_QOS_RW_BPS_RATE_LIMIT
,
115 SPDK_BDEV_QOS_NUM_RATE_LIMIT_TYPES
119 * Block device completion callback.
121 * \param bdev_io Block device I/O that has completed.
122 * \param success True if I/O completed successfully or false if it failed;
123 * additional error information may be retrieved from bdev_io by calling
124 * spdk_bdev_io_get_nvme_status() or spdk_bdev_io_get_scsi_status().
125 * \param cb_arg Callback argument specified when bdev_io was submitted.
127 typedef void (*spdk_bdev_io_completion_cb
)(struct spdk_bdev_io
*bdev_io
,
131 struct spdk_bdev_io_stat
{
133 uint64_t num_read_ops
;
134 uint64_t bytes_written
;
135 uint64_t num_write_ops
;
136 uint64_t read_latency_ticks
;
137 uint64_t write_latency_ticks
;
141 struct spdk_bdev_opts
{
142 uint32_t bdev_io_pool_size
;
143 uint32_t bdev_io_cache_size
;
146 void spdk_bdev_get_opts(struct spdk_bdev_opts
*opts
);
148 int spdk_bdev_set_opts(struct spdk_bdev_opts
*opts
);
151 * Block device initialization callback.
153 * \param cb_arg Callback argument.
154 * \param rc 0 if block device initialized successfully or negative errno if it failed.
156 typedef void (*spdk_bdev_init_cb
)(void *cb_arg
, int rc
);
159 * Block device finish callback.
161 * \param cb_arg Callback argument.
163 typedef void (*spdk_bdev_fini_cb
)(void *cb_arg
);
164 typedef void (*spdk_bdev_get_device_stat_cb
)(struct spdk_bdev
*bdev
,
165 struct spdk_bdev_io_stat
*stat
, void *cb_arg
, int rc
);
168 * Initialize block device modules.
170 * \param cb_fn Called when the initialization is complete.
171 * \param cb_arg Argument passed to function cb_fn.
173 void spdk_bdev_initialize(spdk_bdev_init_cb cb_fn
, void *cb_arg
);
176 * Perform cleanup work to remove the registered block device modules.
178 * \param cb_fn Called when the removal is complete.
179 * \param cb_arg Argument passed to function cb_fn.
181 void spdk_bdev_finish(spdk_bdev_fini_cb cb_fn
, void *cb_arg
);
184 * Get the configuration options for the registered block device modules.
186 * \param fp The pointer to a file that will be written to the configuration options.
188 void spdk_bdev_config_text(FILE *fp
);
191 * Get the full configuration options for the registered block device modules and created bdevs.
193 * \param w pointer to a JSON write context where the configuration will be written.
195 void spdk_bdev_subsystem_config_json(struct spdk_json_write_ctx
*w
);
198 * Get block device by the block device name.
200 * \param bdev_name The name of the block device.
201 * \return Block device associated with the name or NULL if no block device with
202 * bdev_name is currently registered.
204 struct spdk_bdev
*spdk_bdev_get_by_name(const char *bdev_name
);
207 * Get the first registered block device.
209 * \return The first registered block device.
211 struct spdk_bdev
*spdk_bdev_first(void);
214 * Get the next registered block device.
216 * \param prev The current block device.
217 * \return The next registered block device.
219 struct spdk_bdev
*spdk_bdev_next(struct spdk_bdev
*prev
);
222 * Get the first block device without virtual block devices on top.
224 * This function only traverses over block devices which have no virtual block
225 * devices on top of them, then get the first one.
227 * \return The first block device without virtual block devices on top.
229 struct spdk_bdev
*spdk_bdev_first_leaf(void);
232 * Get the next block device without virtual block devices on top.
234 * This function only traverses over block devices which have no virtual block
235 * devices on top of them, then get the next one.
237 * \param prev The current block device.
238 * \return The next block device without virtual block devices on top.
240 struct spdk_bdev
*spdk_bdev_next_leaf(struct spdk_bdev
*prev
);
243 * Open a block device for I/O operations.
245 * \param bdev Block device to open.
246 * \param write true is read/write access requested, false if read-only
247 * \param remove_cb callback function for hot remove the device. Will
248 * always be called on the same thread that spdk_bdev_open() was called on.
249 * \param remove_ctx param for hot removal callback function.
250 * \param desc output parameter for the descriptor when operation is successful
251 * \return 0 if operation is successful, suitable errno value otherwise
253 int spdk_bdev_open(struct spdk_bdev
*bdev
, bool write
, spdk_bdev_remove_cb_t remove_cb
,
254 void *remove_ctx
, struct spdk_bdev_desc
**desc
);
257 * Close a previously opened block device.
259 * Must be called on the same thread that the spdk_bdev_open()
262 * \param desc Block device descriptor to close.
264 void spdk_bdev_close(struct spdk_bdev_desc
*desc
);
267 * Get the bdev associated with a bdev descriptor.
269 * \param desc Open block device desciptor
270 * \return bdev associated with the descriptor
272 struct spdk_bdev
*spdk_bdev_desc_get_bdev(struct spdk_bdev_desc
*desc
);
275 * Check whether the block device supports the I/O type.
277 * \param bdev Block device to check.
278 * \param io_type The specific I/O type like read, write, flush, unmap.
279 * \return true if support, false otherwise.
281 bool spdk_bdev_io_type_supported(struct spdk_bdev
*bdev
, enum spdk_bdev_io_type io_type
);
284 * Output driver-specific information to a JSON stream.
286 * The JSON write context will be initialized with an open object, so the bdev
287 * driver should write a name(based on the driver name) followed by a JSON value
288 * (most likely another nested object).
290 * \param bdev Block device to query.
291 * \param w JSON write context. It will store the driver-specific configuration context.
292 * \return 0 on success, negated errno on failure.
294 int spdk_bdev_dump_info_json(struct spdk_bdev
*bdev
, struct spdk_json_write_ctx
*w
);
297 * Get block device name.
299 * \param bdev Block device to query.
300 * \return Name of bdev as a null-terminated string.
302 const char *spdk_bdev_get_name(const struct spdk_bdev
*bdev
);
305 * Get block device product name.
307 * \param bdev Block device to query.
308 * \return Product name of bdev as a null-terminated string.
310 const char *spdk_bdev_get_product_name(const struct spdk_bdev
*bdev
);
313 * Get block device logical block size.
315 * \param bdev Block device to query.
316 * \return Size of logical block for this bdev in bytes.
318 uint32_t spdk_bdev_get_block_size(const struct spdk_bdev
*bdev
);
321 * Get size of block device in logical blocks.
323 * \param bdev Block device to query.
324 * \return Size of bdev in logical blocks.
326 * Logical blocks are numbered from 0 to spdk_bdev_get_num_blocks(bdev) - 1, inclusive.
328 uint64_t spdk_bdev_get_num_blocks(const struct spdk_bdev
*bdev
);
331 * Get the string of quality of service rate limit.
333 * \param type Type of rate limit to query.
334 * \return String of QoS type.
336 const char *spdk_bdev_get_qos_rpc_type(enum spdk_bdev_qos_rate_limit_type type
);
339 * Get the quality of service rate limits on a bdev.
341 * \param bdev Block device to query.
342 * \param limits Pointer to the QoS rate limits array which holding the limits.
344 * The limits are ordered based on the @ref spdk_bdev_qos_rate_limit_type enum.
346 void spdk_bdev_get_qos_rate_limits(struct spdk_bdev
*bdev
, uint64_t *limits
);
349 * Set the quality of service rate limits on a bdev.
351 * \param bdev Block device.
352 * \param limits Pointer to the QoS rate limits array which holding the limits.
353 * \param cb_fn Callback function to be called when the QoS limit has been updated.
354 * \param cb_arg Argument to pass to cb_fn.
356 * The limits are ordered based on the @ref spdk_bdev_qos_rate_limit_type enum.
358 void spdk_bdev_set_qos_rate_limits(struct spdk_bdev
*bdev
, uint64_t *limits
,
359 void (*cb_fn
)(void *cb_arg
, int status
), void *cb_arg
);
362 * Get minimum I/O buffer address alignment for a bdev.
364 * \param bdev Block device to query.
365 * \return Required alignment of I/O buffers in bytes.
367 size_t spdk_bdev_get_buf_align(const struct spdk_bdev
*bdev
);
370 * Get optimal I/O boundary for a bdev.
372 * \param bdev Block device to query.
373 * \return Optimal I/O boundary in blocks that should not be crossed for best performance, or 0 if
374 * no optimal boundary is reported.
376 uint32_t spdk_bdev_get_optimal_io_boundary(const struct spdk_bdev
*bdev
);
379 * Query whether block device has an enabled write cache.
381 * \param bdev Block device to query.
382 * \return true if block device has a volatile write cache enabled.
384 * If this function returns true, written data may not be persistent until a flush command
387 bool spdk_bdev_has_write_cache(const struct spdk_bdev
*bdev
);
392 * \param bdev Block device to query.
393 * \return Pointer to UUID.
395 * Not all bdevs will have a UUID; in this case, the returned UUID will be
396 * the nil UUID (all bytes zero).
398 const struct spdk_uuid
*spdk_bdev_get_uuid(const struct spdk_bdev
*bdev
);
401 * Get the most recently measured queue depth from a bdev.
403 * The reported queue depth is the aggregate of outstanding I/O
404 * across all open channels associated with this bdev.
406 * \param bdev Block device to query.
408 * \return The most recent queue depth measurement for the bdev.
409 * If tracking is not enabled, the function will return UINT64_MAX
410 * It is also possible to receive UINT64_MAX after enabling tracking
411 * but before the first period has expired.
414 spdk_bdev_get_qd(const struct spdk_bdev
*bdev
);
417 * Get the queue depth polling period.
419 * The return value of this function is only valid if the bdev's
420 * queue depth tracking status is set to true.
422 * \param bdev Block device to query.
424 * \return The period at which this bdev's gueue depth is being refreshed.
427 spdk_bdev_get_qd_sampling_period(const struct spdk_bdev
*bdev
);
430 * Enable or disable queue depth sampling for this bdev.
432 * Enables queue depth sampling when period is greater than 0. Disables it when the period
433 * is equal to zero. The resulting queue depth is stored in the spdk_bdev object as
434 * measured_queue_depth.
436 * \param bdev Block device on which to enable queue depth tracking.
437 * \param period The period at which to poll this bdev's queue depth. If this is set
438 * to zero, polling will be disabled.
440 void spdk_bdev_set_qd_sampling_period(struct spdk_bdev
*bdev
, uint64_t period
);
443 * Get the time spent processing IO for this device.
445 * This value is dependent upon the queue depth sampling period and is
446 * incremented at sampling time by the sampling period only if the measured
447 * queue depth is greater than 0.
449 * The disk utilization can be calculated by the following formula:
450 * disk_util = (io_time_2 - io_time_1) / elapsed_time.
451 * The user is responsible for tracking the elapsed time between two measurements.
453 * \param bdev Block device to query.
455 * \return The io time for this device in microseconds.
457 uint64_t spdk_bdev_get_io_time(const struct spdk_bdev
*bdev
);
460 * Get the weighted IO processing time for this bdev.
462 * This value is dependent upon the queue depth sampling period and is
463 * equal to the time spent reading from or writing to a device times
464 * the measured queue depth during each sampling period.
466 * The average queue depth can be calculated by the following formula:
467 * queue_depth = (weighted_io_time_2 - weighted_io_time_1) / elapsed_time.
468 * The user is responsible for tracking the elapsed time between two measurements.
470 * \param bdev Block device to query.
472 * \return The weighted io time for this device in microseconds.
474 uint64_t spdk_bdev_get_weighted_io_time(const struct spdk_bdev
*bdev
);
477 * Obtain an I/O channel for the block device opened by the specified
478 * descriptor. I/O channels are bound to threads, so the resulting I/O
479 * channel may only be used from the thread it was originally obtained
482 * \param desc Block device descriptor.
484 * \return A handle to the I/O channel or NULL on failure.
486 struct spdk_io_channel
*spdk_bdev_get_io_channel(struct spdk_bdev_desc
*desc
);
489 * \defgroup bdev_io_submit_functions bdev I/O Submit Functions
491 * These functions submit a new I/O request to a bdev. The I/O request will
492 * be represented by an spdk_bdev_io structure allocated from a global pool.
493 * These functions will return -ENOMEM if the spdk_bdev_io pool is empty.
497 * Submit a read request to the bdev on the given channel.
499 * \ingroup bdev_io_submit_functions
501 * \param desc Block device descriptor.
502 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
503 * \param buf Data buffer to read into.
504 * \param offset The offset, in bytes, from the start of the block device.
505 * \param nbytes The number of bytes to read.
506 * \param cb Called when the request is complete.
507 * \param cb_arg Argument passed to cb.
509 * \return 0 on success. On success, the callback will always
510 * be called (even if the request ultimately failed). Return
511 * negated errno on failure, in which case the callback will not be called.
512 * * -EINVAL - offset and/or nbytes are not aligned or out of range
513 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
515 int spdk_bdev_read(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
516 void *buf
, uint64_t offset
, uint64_t nbytes
,
517 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
520 * Submit a read request to the bdev on the given channel.
522 * \ingroup bdev_io_submit_functions
524 * \param desc Block device descriptor.
525 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
526 * \param buf Data buffer to read into.
527 * \param offset_blocks The offset, in blocks, from the start of the block device.
528 * \param num_blocks The number of blocks to read.
529 * \param cb Called when the request is complete.
530 * \param cb_arg Argument passed to cb.
532 * \return 0 on success. On success, the callback will always
533 * be called (even if the request ultimately failed). Return
534 * negated errno on failure, in which case the callback will not be called.
535 * * -EINVAL - offset_blocks and/or num_blocks are out of range
536 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
538 int spdk_bdev_read_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
539 void *buf
, uint64_t offset_blocks
, uint64_t num_blocks
,
540 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
543 * Submit a read request to the bdev on the given channel. This differs from
544 * spdk_bdev_read by allowing the data buffer to be described in a scatter
545 * gather list. Some physical devices place memory alignment requirements on
546 * data and may not be able to directly transfer into the buffers provided. In
547 * this case, the request may fail.
549 * \ingroup bdev_io_submit_functions
551 * \param desc Block device descriptor.
552 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
553 * \param iov A scatter gather list of buffers to be read into.
554 * \param iovcnt The number of elements in iov.
555 * \param offset The offset, in bytes, from the start of the block device.
556 * \param nbytes The number of bytes to read.
557 * \param cb Called when the request is complete.
558 * \param cb_arg Argument passed to cb.
560 * \return 0 on success. On success, the callback will always
561 * be called (even if the request ultimately failed). Return
562 * negated errno on failure, in which case the callback will not be called.
563 * * -EINVAL - offset and/or nbytes are not aligned or out of range
564 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
566 int spdk_bdev_readv(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
567 struct iovec
*iov
, int iovcnt
,
568 uint64_t offset
, uint64_t nbytes
,
569 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
572 * Submit a read request to the bdev on the given channel. This differs from
573 * spdk_bdev_read by allowing the data buffer to be described in a scatter
574 * gather list. Some physical devices place memory alignment requirements on
575 * data and may not be able to directly transfer into the buffers provided. In
576 * this case, the request may fail.
578 * \ingroup bdev_io_submit_functions
580 * \param desc Block device descriptor.
581 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
582 * \param iov A scatter gather list of buffers to be read into.
583 * \param iovcnt The number of elements in iov.
584 * \param offset_blocks The offset, in blocks, from the start of the block device.
585 * \param num_blocks The number of blocks to read.
586 * \param cb Called when the request is complete.
587 * \param cb_arg Argument passed to cb.
589 * \return 0 on success. On success, the callback will always
590 * be called (even if the request ultimately failed). Return
591 * negated errno on failure, in which case the callback will not be called.
592 * * -EINVAL - offset_blocks and/or num_blocks are out of range
593 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
595 int spdk_bdev_readv_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
596 struct iovec
*iov
, int iovcnt
,
597 uint64_t offset_blocks
, uint64_t num_blocks
,
598 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
601 * Submit a write request to the bdev on the given channel.
603 * \ingroup bdev_io_submit_functions
605 * \param desc Block device descriptor.
606 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
607 * \param buf Data buffer to written from.
608 * \param offset The offset, in bytes, from the start of the block device.
609 * \param nbytes The number of bytes to write. buf must be greater than or equal to this size.
610 * \param cb Called when the request is complete.
611 * \param cb_arg Argument passed to cb.
613 * \return 0 on success. On success, the callback will always
614 * be called (even if the request ultimately failed). Return
615 * negated errno on failure, in which case the callback will not be called.
616 * * -EINVAL - offset and/or nbytes are not aligned or out of range
617 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
618 * * -EBADF - desc not open for writing
620 int spdk_bdev_write(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
621 void *buf
, uint64_t offset
, uint64_t nbytes
,
622 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
625 * Submit a write request to the bdev on the given channel.
627 * \ingroup bdev_io_submit_functions
629 * \param desc Block device descriptor.
630 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
631 * \param buf Data buffer to written from.
632 * \param offset_blocks The offset, in blocks, from the start of the block device.
633 * \param num_blocks The number of blocks to write. buf must be greater than or equal to this size.
634 * \param cb Called when the request is complete.
635 * \param cb_arg Argument passed to cb.
637 * \return 0 on success. On success, the callback will always
638 * be called (even if the request ultimately failed). Return
639 * negated errno on failure, in which case the callback will not be called.
640 * * -EINVAL - offset_blocks and/or num_blocks are out of range
641 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
642 * * -EBADF - desc not open for writing
644 int spdk_bdev_write_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
645 void *buf
, uint64_t offset_blocks
, uint64_t num_blocks
,
646 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
649 * Submit a write request to the bdev on the given channel. This differs from
650 * spdk_bdev_write by allowing the data buffer to be described in a scatter
651 * gather list. Some physical devices place memory alignment requirements on
652 * data and may not be able to directly transfer out of the buffers provided. In
653 * this case, the request may fail.
655 * \ingroup bdev_io_submit_functions
657 * \param desc Block device descriptor.
658 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
659 * \param iov A scatter gather list of buffers to be written from.
660 * \param iovcnt The number of elements in iov.
661 * \param offset The offset, in bytes, from the start of the block device.
662 * \param len The size of data to write.
663 * \param cb Called when the request is complete.
664 * \param cb_arg Argument passed to cb.
666 * \return 0 on success. On success, the callback will always
667 * be called (even if the request ultimately failed). Return
668 * negated errno on failure, in which case the callback will not be called.
669 * * -EINVAL - offset and/or nbytes are not aligned or out of range
670 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
671 * * -EBADF - desc not open for writing
673 int spdk_bdev_writev(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
674 struct iovec
*iov
, int iovcnt
,
675 uint64_t offset
, uint64_t len
,
676 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
679 * Submit a write request to the bdev on the given channel. This differs from
680 * spdk_bdev_write by allowing the data buffer to be described in a scatter
681 * gather list. Some physical devices place memory alignment requirements on
682 * data and may not be able to directly transfer out of the buffers provided. In
683 * this case, the request may fail.
685 * \ingroup bdev_io_submit_functions
687 * \param desc Block device descriptor.
688 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
689 * \param iov A scatter gather list of buffers to be written from.
690 * \param iovcnt The number of elements in iov.
691 * \param offset_blocks The offset, in blocks, from the start of the block device.
692 * \param num_blocks The number of blocks to write.
693 * \param cb Called when the request is complete.
694 * \param cb_arg Argument passed to cb.
696 * \return 0 on success. On success, the callback will always
697 * be called (even if the request ultimately failed). Return
698 * negated errno on failure, in which case the callback will not be called.
699 * * -EINVAL - offset_blocks and/or num_blocks are out of range
700 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
701 * * -EBADF - desc not open for writing
703 int spdk_bdev_writev_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
704 struct iovec
*iov
, int iovcnt
,
705 uint64_t offset_blocks
, uint64_t num_blocks
,
706 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
709 * Submit a write zeroes request to the bdev on the given channel. This command
710 * ensures that all bytes in the specified range are set to 00h
712 * \ingroup bdev_io_submit_functions
714 * \param desc Block device descriptor.
715 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
716 * \param offset The offset, in bytes, from the start of the block device.
717 * \param len The size of data to zero.
718 * \param cb Called when the request is complete.
719 * \param cb_arg Argument passed to cb.
721 * \return 0 on success. On success, the callback will always
722 * be called (even if the request ultimately failed). Return
723 * negated errno on failure, in which case the callback will not be called.
724 * * -EINVAL - offset and/or nbytes are not aligned or out of range
725 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
726 * * -EBADF - desc not open for writing
728 int spdk_bdev_write_zeroes(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
729 uint64_t offset
, uint64_t len
,
730 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
733 * Submit a write zeroes request to the bdev on the given channel. This command
734 * ensures that all bytes in the specified range are set to 00h
736 * \ingroup bdev_io_submit_functions
738 * \param desc Block device descriptor.
739 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
740 * \param offset_blocks The offset, in blocks, from the start of the block device.
741 * \param num_blocks The number of blocks to zero.
742 * \param cb Called when the request is complete.
743 * \param cb_arg Argument passed to cb.
745 * \return 0 on success. On success, the callback will always
746 * be called (even if the request ultimately failed). Return
747 * negated errno on failure, in which case the callback will not be called.
748 * * -EINVAL - offset_blocks and/or num_blocks are out of range
749 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
750 * * -EBADF - desc not open for writing
752 int spdk_bdev_write_zeroes_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
753 uint64_t offset_blocks
, uint64_t num_blocks
,
754 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
757 * Submit an unmap request to the block device. Unmap is sometimes also called trim or
758 * deallocate. This notifies the device that the data in the blocks described is no
759 * longer valid. Reading blocks that have been unmapped results in indeterminate data.
761 * \ingroup bdev_io_submit_functions
763 * \param desc Block device descriptor.
764 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
765 * \param offset The offset, in bytes, from the start of the block device.
766 * \param nbytes The number of bytes to unmap. Must be a multiple of the block size.
767 * \param cb Called when the request is complete.
768 * \param cb_arg Argument passed to cb.
770 * \return 0 on success. On success, the callback will always
771 * be called (even if the request ultimately failed). Return
772 * negated errno on failure, in which case the callback will not be called.
773 * * -EINVAL - offset and/or nbytes are not aligned or out of range
774 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
775 * * -EBADF - desc not open for writing
777 int spdk_bdev_unmap(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
778 uint64_t offset
, uint64_t nbytes
,
779 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
782 * Submit an unmap request to the block device. Unmap is sometimes also called trim or
783 * deallocate. This notifies the device that the data in the blocks described is no
784 * longer valid. Reading blocks that have been unmapped results in indeterminate data.
786 * \ingroup bdev_io_submit_functions
788 * \param desc Block device descriptor.
789 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
790 * \param offset_blocks The offset, in blocks, from the start of the block device.
791 * \param num_blocks The number of blocks to unmap.
792 * \param cb Called when the request is complete.
793 * \param cb_arg Argument passed to cb.
795 * \return 0 on success. On success, the callback will always
796 * be called (even if the request ultimately failed). Return
797 * negated errno on failure, in which case the callback will not be called.
798 * * -EINVAL - offset_blocks and/or num_blocks are out of range
799 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
800 * * -EBADF - desc not open for writing
802 int spdk_bdev_unmap_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
803 uint64_t offset_blocks
, uint64_t num_blocks
,
804 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
807 * Submit a flush request to the bdev on the given channel. For devices with volatile
808 * caches, data is not guaranteed to be persistent until the completion of a flush
809 * request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.
811 * \ingroup bdev_io_submit_functions
813 * \param desc Block device descriptor.
814 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
815 * \param offset The offset, in bytes, from the start of the block device.
816 * \param length The number of bytes.
817 * \param cb Called when the request is complete.
818 * \param cb_arg Argument passed to cb.
820 * \return 0 on success. On success, the callback will always
821 * be called (even if the request ultimately failed). Return
822 * negated errno on failure, in which case the callback will not be called.
823 * * -EINVAL - offset and/or nbytes are not aligned or out of range
824 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
825 * * -EBADF - desc not open for writing
827 int spdk_bdev_flush(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
828 uint64_t offset
, uint64_t length
,
829 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
832 * Submit a flush request to the bdev on the given channel. For devices with volatile
833 * caches, data is not guaranteed to be persistent until the completion of a flush
834 * request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.
836 * \ingroup bdev_io_submit_functions
838 * \param desc Block device descriptor.
839 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
840 * \param offset_blocks The offset, in blocks, from the start of the block device.
841 * \param num_blocks The number of blocks.
842 * \param cb Called when the request is complete.
843 * \param cb_arg Argument passed to cb.
845 * \return 0 on success. On success, the callback will always
846 * be called (even if the request ultimately failed). Return
847 * negated errno on failure, in which case the callback will not be called.
848 * * -EINVAL - offset_blocks and/or num_blocks are out of range
849 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
850 * * -EBADF - desc not open for writing
852 int spdk_bdev_flush_blocks(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
853 uint64_t offset_blocks
, uint64_t num_blocks
,
854 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
857 * Submit a reset request to the bdev on the given channel.
859 * \ingroup bdev_io_submit_functions
861 * \param desc Block device descriptor.
862 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
863 * \param cb Called when the request is complete.
864 * \param cb_arg Argument passed to cb.
866 * \return 0 on success. On success, the callback will always
867 * be called (even if the request ultimately failed). Return
868 * negated errno on failure, in which case the callback will not be called.
869 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
871 int spdk_bdev_reset(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
872 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
875 * Submit an NVMe Admin command to the bdev. This passes directly through
876 * the block layer to the device. Support for NVMe passthru is optional,
877 * indicated by calling spdk_bdev_io_type_supported().
879 * The SGL/PRP will be automated generated based on the given buffer,
880 * so that portion of the command may be left empty.
882 * \ingroup bdev_io_submit_functions
884 * \param desc Block device descriptor.
885 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
886 * \param cmd The raw NVMe command. Must be an admin command.
887 * \param buf Data buffer to written from.
888 * \param nbytes The number of bytes to transfer. buf must be greater than or equal to this size.
889 * \param cb Called when the request is complete.
890 * \param cb_arg Argument passed to cb.
892 * \return 0 on success. On success, the callback will always
893 * be called (even if the request ultimately failed). Return
894 * negated errno on failure, in which case the callback will not be called.
895 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
896 * * -EBADF - desc not open for writing
898 int spdk_bdev_nvme_admin_passthru(struct spdk_bdev_desc
*desc
,
899 struct spdk_io_channel
*ch
,
900 const struct spdk_nvme_cmd
*cmd
,
901 void *buf
, size_t nbytes
,
902 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
905 * Submit an NVMe I/O command to the bdev. This passes directly through
906 * the block layer to the device. Support for NVMe passthru is optional,
907 * indicated by calling spdk_bdev_io_type_supported().
909 * \ingroup bdev_io_submit_functions
911 * The SGL/PRP will be automated generated based on the given buffer,
912 * so that portion of the command may be left empty. Also, the namespace
913 * id (nsid) will be populated automatically.
915 * \param bdev_desc Block device descriptor.
916 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
917 * \param cmd The raw NVMe command. Must be in the NVM command set.
918 * \param buf Data buffer to written from.
919 * \param nbytes The number of bytes to transfer. buf must be greater than or equal to this size.
920 * \param cb Called when the request is complete.
921 * \param cb_arg Argument passed to cb.
923 * \return 0 on success. On success, the callback will always
924 * be called (even if the request ultimately failed). Return
925 * negated errno on failure, in which case the callback will not be called.
926 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
927 * * -EBADF - desc not open for writing
929 int spdk_bdev_nvme_io_passthru(struct spdk_bdev_desc
*bdev_desc
,
930 struct spdk_io_channel
*ch
,
931 const struct spdk_nvme_cmd
*cmd
,
932 void *buf
, size_t nbytes
,
933 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
936 * Submit an NVMe I/O command to the bdev. This passes directly through
937 * the block layer to the device. Support for NVMe passthru is optional,
938 * indicated by calling spdk_bdev_io_type_supported().
940 * \ingroup bdev_io_submit_functions
942 * The SGL/PRP will be automated generated based on the given buffer,
943 * so that portion of the command may be left empty. Also, the namespace
944 * id (nsid) will be populated automatically.
946 * \param bdev_desc Block device descriptor
947 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
948 * \param cmd The raw NVMe command. Must be in the NVM command set.
949 * \param buf Data buffer to written from.
950 * \param nbytes The number of bytes to transfer. buf must be greater than or equal to this size.
951 * \param md_buf Meta data buffer to written from.
952 * \param md_len md_buf size to transfer. md_buf must be greater than or equal to this size.
953 * \param cb Called when the request is complete.
954 * \param cb_arg Argument passed to cb.
956 * \return 0 on success. On success, the callback will always
957 * be called (even if the request ultimately failed). Return
958 * negated errno on failure, in which case the callback will not be called.
959 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
960 * * -EBADF - desc not open for writing
962 int spdk_bdev_nvme_io_passthru_md(struct spdk_bdev_desc
*bdev_desc
,
963 struct spdk_io_channel
*ch
,
964 const struct spdk_nvme_cmd
*cmd
,
965 void *buf
, size_t nbytes
, void *md_buf
, size_t md_len
,
966 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
969 * Free an I/O request. This should only be called after the completion callback
970 * for the I/O has been called and notifies the bdev layer that memory may now
973 * \param bdev_io I/O request.
975 void spdk_bdev_free_io(struct spdk_bdev_io
*bdev_io
);
978 * Block device I/O wait callback
980 * Callback function to notify when an spdk_bdev_io structure is available
981 * to satisfy a call to one of the @ref bdev_io_submit_functions.
983 typedef void (*spdk_bdev_io_wait_cb
)(void *cb_arg
);
986 * Structure to register a callback when an spdk_bdev_io becomes available.
988 struct spdk_bdev_io_wait_entry
{
989 struct spdk_bdev
*bdev
;
990 spdk_bdev_io_wait_cb cb_fn
;
992 TAILQ_ENTRY(spdk_bdev_io_wait_entry
) link
;
996 * Add an entry into the calling thread's queue to be notified when an
997 * spdk_bdev_io becomes available.
999 * When one of the @ref bdev_io_submit_functions returns -ENOMEM, it means
1000 * the spdk_bdev_io buffer pool has no available buffers. This function may
1001 * be called to register a callback to be notified when a buffer becomes
1002 * available on the calling thread.
1004 * The callback function will always be called on the same thread as this
1005 * function was called.
1007 * This function must only be called immediately after one of the
1008 * @ref bdev_io_submit_functions returns -ENOMEM.
1010 * \param bdev Block device. The block device that the caller will submit
1011 * an I/O to when the callback is invoked. Must match the bdev
1012 * member in the entry parameter.
1013 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
1014 * \param entry Data structure allocated by the caller specifying the callback
1015 * function and argument.
1017 * \return 0 on success.
1018 * -EINVAL if bdev parameter does not match bdev member in entry
1019 * -EINVAL if an spdk_bdev_io structure was available on this thread.
1021 int spdk_bdev_queue_io_wait(struct spdk_bdev
*bdev
, struct spdk_io_channel
*ch
,
1022 struct spdk_bdev_io_wait_entry
*entry
);
1025 * Return I/O statistics for this channel.
1027 * \param bdev Block device.
1028 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
1029 * \param stat The per-channel statistics.
1032 void spdk_bdev_get_io_stat(struct spdk_bdev
*bdev
, struct spdk_io_channel
*ch
,
1033 struct spdk_bdev_io_stat
*stat
);
1037 * Return I/O statistics for this bdev. All the required information will be passed
1038 * via the callback function.
1040 * \param bdev Block device to query.
1041 * \param stat Structure for aggregating collected statistics. Passed as argument to cb.
1042 * \param cb Called when this operation completes.
1043 * \param cb_arg Argument passed to callback function.
1045 void spdk_bdev_get_device_stat(struct spdk_bdev
*bdev
, struct spdk_bdev_io_stat
*stat
,
1046 spdk_bdev_get_device_stat_cb cb
, void *cb_arg
);
1049 * Get the status of bdev_io as an NVMe status code.
1051 * \param bdev_io I/O to get the status from.
1052 * \param sct Status Code Type return value, as defined by the NVMe specification.
1053 * \param sc Status Code return value, as defined by the NVMe specification.
1055 void spdk_bdev_io_get_nvme_status(const struct spdk_bdev_io
*bdev_io
, int *sct
, int *sc
);
1058 * Get the status of bdev_io as a SCSI status code.
1060 * \param bdev_io I/O to get the status from.
1061 * \param sc SCSI Status Code.
1062 * \param sk SCSI Sense Key.
1063 * \param asc SCSI Additional Sense Code.
1064 * \param ascq SCSI Additional Sense Code Qualifier.
1066 void spdk_bdev_io_get_scsi_status(const struct spdk_bdev_io
*bdev_io
,
1067 int *sc
, int *sk
, int *asc
, int *ascq
);
1070 * Get the iovec describing the data buffer of a bdev_io.
1072 * \param bdev_io I/O to describe with iovec.
1073 * \param iovp Pointer to be filled with iovec.
1074 * \param iovcntp Pointer to be filled with number of iovec entries.
1076 void spdk_bdev_io_get_iovec(struct spdk_bdev_io
*bdev_io
, struct iovec
**iovp
, int *iovcntp
);
1082 #endif /* SPDK_BDEV_H_ */