Line data Source code
1 : /* SPDX-License-Identifier: BSD-3-Clause
2 : * Copyright (C) 2016 Intel Corporation.
3 : * All rights reserved.
4 : * Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
5 : */
6 :
7 : /** \file
8 : * Block Device Module Interface
9 : *
10 : * For information on how to write a bdev module, see @ref bdev_module.
11 : */
12 :
13 : #ifndef SPDK_BDEV_MODULE_H
14 : #define SPDK_BDEV_MODULE_H
15 :
16 : #include "spdk/stdinc.h"
17 :
18 : #include "spdk/bdev.h"
19 : #include "spdk/bdev_zone.h"
20 : #include "spdk/log.h"
21 : #include "spdk/queue.h"
22 : #include "spdk/scsi_spec.h"
23 : #include "spdk/thread.h"
24 : #include "spdk/tree.h"
25 : #include "spdk/util.h"
26 : #include "spdk/uuid.h"
27 :
28 : #ifdef __cplusplus
29 : extern "C" {
30 : #endif
31 :
32 : #define SPDK_BDEV_CLAIM_NAME_LEN 32
33 :
34 : /* This parameter is best defined for bdevs that share an underlying bdev,
35 : * such as multiple lvol bdevs sharing an nvme device, to avoid unnecessarily
36 : * resetting the underlying bdev and affecting other bdevs that are sharing it. */
37 : #define SPDK_BDEV_RESET_IO_DRAIN_RECOMMENDED_VALUE 5
38 :
39 : /** Block device module */
40 : struct spdk_bdev_module {
41 : /**
42 : * Initialization function for the module. Called by the bdev library
43 : * during startup.
44 : *
45 : * Modules are required to define this function.
46 : */
47 : int (*module_init)(void);
48 :
49 : /**
50 : * Optional callback for modules that require notification of when
51 : * the bdev subsystem has completed initialization.
52 : *
53 : * Modules are not required to define this function.
54 : */
55 : void (*init_complete)(void);
56 :
57 : /**
58 : * Optional callback for modules that require notification of when
59 : * the bdev subsystem is starting the fini process. Called by
60 : * the bdev library before starting to unregister the bdevs.
61 : *
62 : * If a module claimed a bdev without presenting virtual bdevs on top of it,
63 : * it has to release that claim during this call.
64 : *
65 : * Modules are not required to define this function.
66 : */
67 : void (*fini_start)(void);
68 :
69 : /**
70 : * Finish function for the module. Called by the bdev library
71 : * after all bdevs for all modules have been unregistered. This allows
72 : * the module to do any final cleanup before the bdev library finishes operation.
73 : *
74 : * Modules are not required to define this function.
75 : */
76 : void (*module_fini)(void);
77 :
78 : /**
79 : * Function called to return a text string representing the module-level
80 : * JSON RPCs required to regenerate the current configuration. This will
81 : * include module-level configuration options, or methods to construct
82 : * bdevs when one RPC may generate multiple bdevs (for example, an NVMe
83 : * controller with multiple namespaces).
84 : *
85 : * Per-bdev JSON RPCs (where one "construct" RPC always creates one bdev)
86 : * may be implemented here, or by the bdev's write_config_json function -
87 : * but not both. Bdev module implementers may choose which mechanism to
88 : * use based on the module's design.
89 : *
90 : * \return 0 on success or Bdev specific negative error code.
91 : */
92 : int (*config_json)(struct spdk_json_write_ctx *w);
93 :
94 : /** Name for the modules being defined. */
95 : const char *name;
96 :
97 : /**
98 : * Returns the allocation size required for the backend for uses such as local
99 : * command structs, local SGL, iovecs, or other user context.
100 : */
101 : int (*get_ctx_size)(void);
102 :
103 : /**
104 : * First notification that a bdev should be examined by a virtual bdev module.
105 : * Virtual bdev modules may use this to examine newly-added bdevs and automatically
106 : * create their own vbdevs, but no I/O to device can be send to bdev at this point.
107 : * Only vbdevs based on config files can be created here. This callback must make
108 : * its decision to claim the module synchronously.
109 : * It must also call spdk_bdev_module_examine_done() before returning. If the module
110 : * needs to perform asynchronous operations such as I/O after claiming the bdev,
111 : * it may define an examine_disk callback. The examine_disk callback will then
112 : * be called immediately after the examine_config callback returns.
113 : */
114 : void (*examine_config)(struct spdk_bdev *bdev);
115 :
116 : /**
117 : * Second notification that a bdev should be examined by a virtual bdev module.
118 : * Virtual bdev modules may use this to examine newly-added bdevs and automatically
119 : * create their own vbdevs. This callback may use I/O operations and finish asynchronously.
120 : * Once complete spdk_bdev_module_examine_done() must be called.
121 : */
122 : void (*examine_disk)(struct spdk_bdev *bdev);
123 :
124 : /**
125 : * Denotes if the module_init function may complete asynchronously. If set to true,
126 : * the module initialization has to be explicitly completed by calling
127 : * spdk_bdev_module_init_done().
128 : */
129 : bool async_init;
130 :
131 : /**
132 : * Denotes if the module_fini function may complete asynchronously.
133 : * If set to true finishing has to be explicitly completed by calling
134 : * spdk_bdev_module_fini_done().
135 : */
136 : bool async_fini;
137 :
138 : /**
139 : * Denotes if the fini_start function may complete asynchronously.
140 : * If set to true finishing has to be explicitly completed by calling
141 : * spdk_bdev_module_fini_start_done().
142 : */
143 : bool async_fini_start;
144 :
145 : /**
146 : * Fields that are used by the internal bdev subsystem. Bdev modules
147 : * must not read or write to these fields.
148 : */
149 : struct __bdev_module_internal_fields {
150 : /**
151 : * Protects action_in_progress and quiesced_ranges.
152 : * Take no locks while holding this one.
153 : */
154 : struct spdk_spinlock spinlock;
155 :
156 : /**
157 : * Count of bdev inits/examinations in progress. Used by generic bdev
158 : * layer and must not be modified by bdev modules.
159 : *
160 : * \note Used internally by bdev subsystem, don't change this value in bdev module.
161 : */
162 : uint32_t action_in_progress;
163 :
164 : /**
165 : * List of quiesced lba ranges in all bdevs of this module.
166 : */
167 : TAILQ_HEAD(, lba_range) quiesced_ranges;
168 :
169 : TAILQ_ENTRY(spdk_bdev_module) tailq;
170 : } internal;
171 : };
172 :
173 : /** Claim types */
174 : enum spdk_bdev_claim_type {
175 : /* Not claimed. Must not be used to request a claim. */
176 : SPDK_BDEV_CLAIM_NONE = 0,
177 :
178 : /**
179 : * Exclusive writer, with allowances for legacy behavior. This matches the behavior of
180 : * `spdk_bdev_module_claim_bdev()` as of SPDK 22.09. New consumer should use
181 : * SPDK_BDEV_CLAIM_READ_MANY_WRITE_ONE instead.
182 : */
183 : SPDK_BDEV_CLAIM_EXCL_WRITE,
184 :
185 : /**
186 : * The descriptor passed with this claim request is the only writer. Other claimless readers
187 : * are allowed.
188 : */
189 : SPDK_BDEV_CLAIM_READ_MANY_WRITE_ONE,
190 :
191 : /**
192 : * Any number of readers, no writers. Readers without a claim are allowed.
193 : */
194 : SPDK_BDEV_CLAIM_READ_MANY_WRITE_NONE,
195 :
196 : /**
197 : * Any number of writers with matching shared_claim_key. After the first writer establishes
198 : * a claim, future aspiring writers should open read-only and pass the read-only descriptor.
199 : * If the shared claim is granted to the aspiring writer, the descriptor will be upgraded to
200 : * read-write.
201 : */
202 : SPDK_BDEV_CLAIM_READ_MANY_WRITE_SHARED
203 : };
204 :
205 : /** Options used when requesting a claim. */
206 : struct spdk_bdev_claim_opts {
207 : /* Size of this structure in bytes */
208 : size_t opts_size;
209 : /**
210 : * An arbitrary name for the claim. If set, it should be a string suitable for printing in
211 : * error messages. Must be '\0' terminated.
212 : */
213 : char name[SPDK_BDEV_CLAIM_NAME_LEN];
214 : /**
215 : * Used with SPDK_BDEV_CLAIM_READ_MANY_WRITE_SHARED claims. Any non-zero value is considered
216 : * a key.
217 : */
218 : uint64_t shared_claim_key;
219 : };
220 : SPDK_STATIC_ASSERT(sizeof(struct spdk_bdev_claim_opts) == 48, "Incorrect size");
221 :
222 : /**
223 : * Retrieve the name of the bdev module claim type. The mapping between claim types and their names
224 : * is:
225 : *
226 : * SPDK_BDEV_CLAIM_NONE "not_claimed"
227 : * SPDK_BDEV_CLAIM_EXCL_WRITE "exclusive_write"
228 : * SPDK_BDEV_CLAIM_READ_MANY_WRITE_ONE "read_many_write_one"
229 : * SPDK_BDEV_CLAIM_READ_MANY_WRITE_NONE "read_many_write_none"
230 : * SPDK_BDEV_CLAIM_READ_MANY_WRITE_SHARED "read_many_write_shared"
231 : *
232 : * Any other value will return "invalid_claim".
233 : *
234 : * \param claim_type The claim type.
235 : * \return A string that describes the claim type.
236 : */
237 : const char *spdk_bdev_claim_get_name(enum spdk_bdev_claim_type claim_type);
238 :
239 : /**
240 : * Initialize bdev module claim options structure.
241 : *
242 : * \param opts The structure to initialize.
243 : * \param size The size of *opts.
244 : */
245 : void spdk_bdev_claim_opts_init(struct spdk_bdev_claim_opts *opts, size_t size);
246 :
247 : /**
248 : * Claim the bdev referenced by the open descriptor. The claim is released as the descriptor is
249 : * closed.
250 : *
251 : * \param desc An open bdev descriptor. Some claim types may upgrade this from read-only to
252 : * read-write.
253 : * \param type The type of claim to establish.
254 : * \param opts NULL or options required by the particular claim type.
255 : * \param module The bdev module making this claim.
256 : * \return 0 on success
257 : * \return -ENOMEM if insufficient memory to track the claim
258 : * \return -EBUSY if the claim cannot be granted due to a conflict
259 : * \return -EINVAL if the claim type required options that were not passed or required parameters
260 : * were NULL.
261 : */
262 : int spdk_bdev_module_claim_bdev_desc(struct spdk_bdev_desc *desc,
263 : enum spdk_bdev_claim_type type,
264 : struct spdk_bdev_claim_opts *opts,
265 : struct spdk_bdev_module *module);
266 :
267 : /**
268 : * Called by a bdev module to lay exclusive claim to a bdev.
269 : *
270 : * Also upgrades that bdev's descriptor to have write access if desc
271 : * is not NULL.
272 : *
273 : * \param bdev Block device to be claimed.
274 : * \param desc Descriptor for the above block device or NULL.
275 : * \param module Bdev module attempting to claim bdev.
276 : *
277 : * \return 0 on success
278 : * \return -EPERM if the bdev is already claimed by another module.
279 : */
280 : int spdk_bdev_module_claim_bdev(struct spdk_bdev *bdev, struct spdk_bdev_desc *desc,
281 : struct spdk_bdev_module *module);
282 :
283 : /**
284 : * Called to release a write claim on a block device.
285 : *
286 : * \param bdev Block device to be released.
287 : */
288 : void spdk_bdev_module_release_bdev(struct spdk_bdev *bdev);
289 :
290 : /* Libraries may define __SPDK_BDEV_MODULE_ONLY so that they include
291 : * only the struct spdk_bdev_module definition, and the relevant APIs
292 : * to claim/release a bdev. This may be useful in some cases to avoid
293 : * abidiff errors related to including the struct spdk_bdev structure
294 : * unnecessarily.
295 : */
296 : #ifndef __SPDK_BDEV_MODULE_ONLY
297 :
298 : typedef void (*spdk_bdev_unregister_cb)(void *cb_arg, int rc);
299 :
300 : /**
301 : * Function table for a block device backend.
302 : *
303 : * The backend block device function table provides a set of APIs to allow
304 : * communication with a backend. The main commands are read/write API
305 : * calls for I/O via submit_request.
306 : */
307 : struct spdk_bdev_fn_table {
308 : /** Destroy the backend block device object. If the destruct process
309 : * for the bdev is asynchronous, return 1 from this function, and
310 : * then call spdk_bdev_destruct_done() once the async work is
311 : * complete. If the destruct process is synchronous, return 0 if
312 : * successful, or <0 if unsuccessful.
313 : */
314 : int (*destruct)(void *ctx);
315 :
316 : /** Process the IO. */
317 : void (*submit_request)(struct spdk_io_channel *ch, struct spdk_bdev_io *);
318 :
319 : /** Check if the block device supports a specific I/O type. */
320 : bool (*io_type_supported)(void *ctx, enum spdk_bdev_io_type);
321 :
322 : /** Get an I/O channel for the specific bdev for the calling thread. */
323 : struct spdk_io_channel *(*get_io_channel)(void *ctx);
324 :
325 : /**
326 : * Output driver-specific information to a JSON stream. Optional - may be NULL.
327 : *
328 : * The JSON write context will be initialized with an open object, so the bdev
329 : * driver should write a name (based on the driver name) followed by a JSON value
330 : * (most likely another nested object).
331 : */
332 : int (*dump_info_json)(void *ctx, struct spdk_json_write_ctx *w);
333 :
334 : /**
335 : * Output bdev-specific RPC configuration to a JSON stream. Optional - may be NULL.
336 : *
337 : * This function should only be implemented for bdevs which can be configured
338 : * independently of other bdevs. For example, RPCs to create a bdev for an NVMe
339 : * namespace may not be generated by this function, since enumerating an NVMe
340 : * namespace requires attaching to an NVMe controller, and that controller may
341 : * contain multiple namespaces. The spdk_bdev_module's config_json function should
342 : * be used instead for these cases.
343 : *
344 : * The JSON write context will be initialized with an open object, so the bdev
345 : * driver should write all data necessary to recreate this bdev by invoking
346 : * constructor method. No other data should be written.
347 : */
348 : void (*write_config_json)(struct spdk_bdev *bdev, struct spdk_json_write_ctx *w);
349 :
350 : /** Get spin-time per I/O channel in microseconds.
351 : * Optional - may be NULL.
352 : */
353 : uint64_t (*get_spin_time)(struct spdk_io_channel *ch);
354 :
355 : /** Get bdev module context. */
356 : void *(*get_module_ctx)(void *ctx);
357 :
358 : /** Get memory domains used by bdev. Optional - may be NULL.
359 : * Vbdev module implementation should call \ref spdk_bdev_get_memory_domains for underlying bdev.
360 : * Vbdev module must inspect types of memory domains returned by base bdev and report only those
361 : * memory domains that it can work with. */
362 : int (*get_memory_domains)(void *ctx, struct spdk_memory_domain **domains, int array_size);
363 :
364 : /**
365 : * Reset I/O statistics specific for this bdev context.
366 : */
367 : void (*reset_device_stat)(void *ctx);
368 :
369 : /**
370 : * Dump I/O statistics specific for this bdev context.
371 : */
372 : void (*dump_device_stat_json)(void *ctx, struct spdk_json_write_ctx *w);
373 :
374 : /** Check if bdev can handle spdk_accel_sequence to handle I/O of specific type. */
375 : bool (*accel_sequence_supported)(void *ctx, enum spdk_bdev_io_type type);
376 : };
377 :
378 : /** bdev I/O completion status */
379 : enum spdk_bdev_io_status {
380 : SPDK_BDEV_IO_STATUS_AIO_ERROR = -8,
381 : SPDK_BDEV_IO_STATUS_ABORTED = -7,
382 : SPDK_BDEV_IO_STATUS_FIRST_FUSED_FAILED = -6,
383 : SPDK_BDEV_IO_STATUS_MISCOMPARE = -5,
384 : /*
385 : * NOMEM should be returned when a bdev module cannot start an I/O because of
386 : * some lack of resources. It may not be returned for RESET I/O. I/O completed
387 : * with NOMEM status will be retried after some I/O from the same channel have
388 : * completed.
389 : */
390 : SPDK_BDEV_IO_STATUS_NOMEM = -4,
391 : SPDK_BDEV_IO_STATUS_SCSI_ERROR = -3,
392 : SPDK_BDEV_IO_STATUS_NVME_ERROR = -2,
393 : SPDK_BDEV_IO_STATUS_FAILED = -1,
394 : SPDK_BDEV_IO_STATUS_PENDING = 0,
395 : SPDK_BDEV_IO_STATUS_SUCCESS = 1,
396 :
397 : /* This may be used as the size of an error status array by negation.
398 : * Hence, this should be updated when adding new error statuses.
399 : */
400 : SPDK_MIN_BDEV_IO_STATUS = SPDK_BDEV_IO_STATUS_AIO_ERROR,
401 : };
402 :
403 : struct spdk_bdev_name {
404 : char *name;
405 : struct spdk_bdev *bdev;
406 : RB_ENTRY(spdk_bdev_name) node;
407 : };
408 :
409 : struct spdk_bdev_alias {
410 : struct spdk_bdev_name alias;
411 : TAILQ_ENTRY(spdk_bdev_alias) tailq;
412 : };
413 :
414 : struct spdk_bdev_module_claim {
415 : struct spdk_bdev_module *module;
416 : struct spdk_bdev_desc *desc;
417 : char name[SPDK_BDEV_CLAIM_NAME_LEN];
418 : TAILQ_ENTRY(spdk_bdev_module_claim) link;
419 : };
420 :
421 : typedef TAILQ_HEAD(, spdk_bdev_io) bdev_io_tailq_t;
422 : typedef STAILQ_HEAD(, spdk_bdev_io) bdev_io_stailq_t;
423 : typedef TAILQ_HEAD(, lba_range) lba_range_tailq_t;
424 :
425 : struct spdk_bdev {
426 : /** User context passed in by the backend */
427 : void *ctxt;
428 :
429 : /** Unique name for this block device. */
430 : char *name;
431 :
432 : /** Unique aliases for this block device. */
433 : TAILQ_HEAD(spdk_bdev_aliases_list, spdk_bdev_alias) aliases;
434 :
435 : /** Unique product name for this kind of block device. */
436 : char *product_name;
437 :
438 : /** write cache enabled, not used at the moment */
439 : int write_cache;
440 :
441 : /** Size in bytes of a logical block for the backend */
442 : uint32_t blocklen;
443 :
444 : /** Size in bytes of a physical block for the backend */
445 : uint32_t phys_blocklen;
446 :
447 : /** Number of blocks */
448 : uint64_t blockcnt;
449 :
450 : /**
451 : * Specifies whether the write_unit_size is mandatory or
452 : * only advisory. If set to true, the bdev layer will split
453 : * WRITE I/O that span the write_unit_size before
454 : * submitting them to the bdev module.
455 : *
456 : * This field takes precedence over split_on_optimal_io_boundary
457 : * for WRITE I/O if both are set to true.
458 : *
459 : * Note that this field cannot be used to force splitting of
460 : * UNMAP, WRITE_ZEROES or FLUSH I/O.
461 : */
462 : bool split_on_write_unit;
463 :
464 : /** Number of blocks required for write */
465 : uint32_t write_unit_size;
466 :
467 : /** Atomic compare & write unit */
468 : uint16_t acwu;
469 :
470 : /**
471 : * Specifies an alignment requirement for data buffers associated with an spdk_bdev_io.
472 : * 0 = no alignment requirement
473 : * >0 = alignment requirement is 2 ^ required_alignment.
474 : * bdev layer will automatically double buffer any spdk_bdev_io that violates this
475 : * alignment, before the spdk_bdev_io is submitted to the bdev module.
476 : */
477 : uint8_t required_alignment;
478 :
479 : /**
480 : * Specifies whether the optimal_io_boundary is mandatory or
481 : * only advisory. If set to true, the bdev layer will split
482 : * READ and WRITE I/O that span the optimal_io_boundary before
483 : * submitting them to the bdev module.
484 : *
485 : * Note that this field cannot be used to force splitting of
486 : * UNMAP, WRITE_ZEROES or FLUSH I/O.
487 : */
488 : bool split_on_optimal_io_boundary;
489 :
490 : /**
491 : * Optimal I/O boundary in blocks, or 0 for no value reported.
492 : */
493 : uint32_t optimal_io_boundary;
494 :
495 : /**
496 : * Max io size in bytes of a single segment
497 : *
498 : * Note: both max_segment_size and max_num_segments
499 : * should be zero or non-zero.
500 : */
501 : uint32_t max_segment_size;
502 :
503 : /* Maximum number of segments in a I/O */
504 : uint32_t max_num_segments;
505 :
506 : /* Maximum unmap in unit of logical block */
507 : uint32_t max_unmap;
508 :
509 : /* Maximum unmap block segments */
510 : uint32_t max_unmap_segments;
511 :
512 : /* Maximum write zeroes in unit of logical block */
513 : uint32_t max_write_zeroes;
514 :
515 : /**
516 : * Maximum copy size in unit of logical block
517 : * Should be set explicitly when backing device support copy command
518 : */
519 : uint32_t max_copy;
520 :
521 : /**
522 : * Maximum number of blocks in a single read/write I/O. Requests exceeding this value will
523 : * be split by the bdev layer.
524 : */
525 : uint32_t max_rw_size;
526 :
527 : /**
528 : * UUID for this bdev.
529 : *
530 : * If not provided, it will be generated by bdev layer.
531 : */
532 : struct spdk_uuid uuid;
533 :
534 : /** Size in bytes of a metadata for the backend */
535 : uint32_t md_len;
536 :
537 : /**
538 : * Specify metadata location and set to true if metadata is interleaved
539 : * with block data or false if metadata is separated with block data.
540 : *
541 : * Note that this field is valid only if there is metadata.
542 : */
543 : bool md_interleave;
544 :
545 : /**
546 : * DIF type for this bdev.
547 : *
548 : * Note that this field is valid only if there is metadata.
549 : */
550 : enum spdk_dif_type dif_type;
551 :
552 : /**
553 : * DIF protection information format for this bdev.
554 : *
555 : * Note that this field is valid only if there is metadata and dif_type is
556 : * not SPDK_DIF_DISABLE.
557 : */
558 : enum spdk_dif_pi_format dif_pi_format;
559 :
560 : /*
561 : * DIF location.
562 : *
563 : * Set to true if DIF is set in the first 8/16 bytes of metadata or false
564 : * if DIF is set in the last 8/16 bytes of metadata.
565 : *
566 : * Note that this field is valid only if DIF is enabled.
567 : */
568 : bool dif_is_head_of_md;
569 :
570 : /**
571 : * Specify whether each DIF check type is enabled.
572 : */
573 : uint32_t dif_check_flags;
574 :
575 : /**
576 : * Specify whether bdev is zoned device.
577 : */
578 : bool zoned;
579 :
580 : /**
581 : * Default size of each zone (in blocks).
582 : */
583 : uint64_t zone_size;
584 :
585 : /**
586 : * Maximum zone append data transfer size (in blocks).
587 : */
588 : uint32_t max_zone_append_size;
589 :
590 : /**
591 : * Maximum number of open zones.
592 : */
593 : uint32_t max_open_zones;
594 :
595 : /**
596 : * Maximum number of active zones.
597 : */
598 : uint32_t max_active_zones;
599 :
600 : /**
601 : * Optimal number of open zones.
602 : */
603 : uint32_t optimal_open_zones;
604 :
605 : /**
606 : * Specifies whether bdev supports media management events.
607 : */
608 : bool media_events;
609 :
610 : /**
611 : * Specifies the bdev nvme controller attributes.
612 : */
613 : union spdk_bdev_nvme_ctratt ctratt;
614 :
615 : /**
616 : * NVMe namespace ID.
617 : */
618 : uint32_t nsid;
619 :
620 : /* Upon receiving a reset request, this is the amount of time in seconds
621 : * to wait for all I/O to complete before moving forward with the reset.
622 : * If all I/O completes prior to this time out, the reset will be skipped.
623 : * A value of 0 is special and will always send resets immediately, even
624 : * if there is no I/O outstanding.
625 : *
626 : * Use case example:
627 : * A shared bdev (e.g. multiple lvol bdevs sharing an underlying nvme bdev)
628 : * needs to be reset. For a non-zero value bdev reset code will wait
629 : * `reset_io_drain_timeout` seconds for outstanding IO that are present
630 : * on any bdev channel, before sending a reset down to the underlying device.
631 : * That way we can avoid sending "empty" resets and interrupting work of
632 : * other lvols that use the same bdev. SPDK_BDEV_RESET_IO_DRAIN_RECOMMENDED_VALUE
633 : * is a good choice for the value of this parameter.
634 : *
635 : * If this parameter remains equal to zero, the bdev reset will be forcefully
636 : * sent down to the device, without any delays and waiting for outstanding IO. */
637 : uint16_t reset_io_drain_timeout;
638 :
639 : struct {
640 : /** Is numa.id valid? Needed to know whether numa.id == 0 was
641 : * explicitly set by bdev module or implicitly set when
642 : * calloc()'ing the structure.
643 : */
644 : uint32_t id_valid : 1;
645 : /** NUMA node ID for the bdev */
646 : int32_t id : 31;
647 : } numa;
648 :
649 : /**
650 : * Pointer to the bdev module that registered this bdev.
651 : */
652 : struct spdk_bdev_module *module;
653 :
654 : /** function table for all LUN ops */
655 : const struct spdk_bdev_fn_table *fn_table;
656 :
657 : /** Fields that are used internally by the bdev subsystem. Bdev modules
658 : * must not read or write to these fields.
659 : */
660 : struct __bdev_internal_fields {
661 : /** Quality of service parameters */
662 : struct spdk_bdev_qos *qos;
663 :
664 : /** True if the state of the QoS is being modified */
665 : bool qos_mod_in_progress;
666 :
667 : /** Trace ID for this bdev. */
668 : uint16_t trace_id;
669 :
670 : /**
671 : * SPDK spinlock protecting many of the internal fields of this structure. If
672 : * multiple locks need to be held, the following order must be used:
673 : * g_bdev_mgr.spinlock
674 : * bdev->internal.spinlock
675 : * bdev_desc->spinlock
676 : * bdev_module->internal.spinlock
677 : */
678 : struct spdk_spinlock spinlock;
679 :
680 : /** The bdev status */
681 : enum spdk_bdev_status status;
682 :
683 : /**
684 : * How many bdev_examine() calls are iterating claim.v2.claims. When non-zero claims
685 : * that are released will be cleared but remain on the claims list until
686 : * bdev_examine() finishes. Must hold spinlock on all updates.
687 : */
688 : uint32_t examine_in_progress;
689 :
690 : /**
691 : * The claim type: used in conjunction with claim. Must hold spinlock on all
692 : * updates.
693 : */
694 : enum spdk_bdev_claim_type claim_type;
695 :
696 : /** Which module has claimed this bdev. Must hold spinlock on all updates. */
697 : union __bdev_internal_claim {
698 : /** Claims acquired with spdk_bdev_module_claim_bdev() */
699 : struct __bdev_internal_claim_v1 {
700 : /**
701 : * Pointer to the module that has claimed this bdev for purposes of
702 : * creating virtual bdevs on top of it. Set to NULL and set
703 : * claim_type to SPDK_BDEV_CLAIM_NONE if the bdev has not been
704 : * claimed.
705 : */
706 : struct spdk_bdev_module *module;
707 : } v1;
708 : /** Claims acquired with spdk_bdev_module_claim_bdev_desc() */
709 : struct __bdev_internal_claim_v2 {
710 : /** The claims on this bdev */
711 : TAILQ_HEAD(v2_claims, spdk_bdev_module_claim) claims;
712 : /** See spdk_bdev_claim_opts.shared_claim_key */
713 : uint64_t key;
714 : } v2;
715 : } claim;
716 :
717 : /** Callback function that will be called after bdev destruct is completed. */
718 : spdk_bdev_unregister_cb unregister_cb;
719 :
720 : /** Unregister call context */
721 : void *unregister_ctx;
722 :
723 : /** Thread that issued the unregister. The cb must be called on this thread. */
724 : struct spdk_thread *unregister_td;
725 :
726 : /** List of open descriptors for this block device. */
727 : TAILQ_HEAD(, spdk_bdev_desc) open_descs;
728 :
729 : TAILQ_ENTRY(spdk_bdev) link;
730 :
731 : /** points to a reset bdev_io if one is in progress. */
732 : struct spdk_bdev_io *reset_in_progress;
733 :
734 : /** List of reset bdev_ios that are not submitted to the underlying device. */
735 : bdev_io_tailq_t queued_resets;
736 :
737 : /** poller for tracking the queue_depth of a device, NULL if not tracking */
738 : struct spdk_poller *qd_poller;
739 :
740 : /** open descriptor to use qd_poller safely */
741 : struct spdk_bdev_desc *qd_desc;
742 :
743 : /** period at which we poll for queue depth information */
744 : uint64_t period;
745 :
746 : /** new period to be used to poll for queue depth information */
747 : uint64_t new_period;
748 :
749 : /** used to aggregate queue depth while iterating across the bdev's open channels */
750 : uint64_t temporary_queue_depth;
751 :
752 : /** queue depth as calculated the last time the telemetry poller checked. */
753 : uint64_t measured_queue_depth;
754 :
755 : /** most recent value of ticks spent performing I/O. Used to calculate the weighted time doing I/O */
756 : uint64_t io_time;
757 :
758 : /** weighted time performing I/O. Equal to measured_queue_depth * period */
759 : uint64_t weighted_io_time;
760 :
761 : /** accumulated I/O statistics for previously deleted channels of this bdev */
762 : struct spdk_bdev_io_stat *stat;
763 :
764 : /** true if tracking the queue_depth of a device is in progress */
765 : bool qd_poll_in_progress;
766 :
767 : /** histogram enabled on this bdev */
768 : bool histogram_enabled;
769 : bool histogram_in_progress;
770 : uint8_t histogram_io_type;
771 :
772 : /** Currently locked ranges for this bdev. Used to populate new channels. */
773 : lba_range_tailq_t locked_ranges;
774 :
775 : /** Pending locked ranges for this bdev. These ranges are not currently
776 : * locked due to overlapping with another locked range.
777 : */
778 : lba_range_tailq_t pending_locked_ranges;
779 :
780 : /** Bdev name used for quick lookup */
781 : struct spdk_bdev_name bdev_name;
782 : } internal;
783 : };
784 :
785 : /**
786 : * Callback when buffer is allocated for the bdev I/O.
787 : *
788 : * \param ch The I/O channel the bdev I/O was handled on.
789 : * \param bdev_io The bdev I/O
790 : * \param success True if buffer is allocated successfully or the bdev I/O has an SGL
791 : * assigned already, or false if it failed. The possible reason of failure is the size
792 : * of the buffer to allocate is greater than the permitted maximum.
793 : */
794 : typedef void (*spdk_bdev_io_get_buf_cb)(struct spdk_io_channel *ch, struct spdk_bdev_io *bdev_io,
795 : bool success);
796 :
797 : /**
798 : * Callback when an auxiliary buffer is allocated for the bdev I/O.
799 : *
800 : * \param ch The I/O channel the bdev I/O was handled on.
801 : * \param bdev_io The bdev I/O
802 : * \param aux_buf Pointer to the allocated buffer. NULL if there was a failure such as
803 : * the size of the buffer to allocate is greater than the permitted maximum.
804 : */
805 : typedef void (*spdk_bdev_io_get_aux_buf_cb)(struct spdk_io_channel *ch,
806 : struct spdk_bdev_io *bdev_io, void *aux_buf);
807 :
808 : /* Maximum number of IOVs used for I/O splitting */
809 : #define SPDK_BDEV_IO_NUM_CHILD_IOV 32
810 :
811 : struct spdk_bdev_io_block_params {
812 : /** For SG buffer cases, array of iovecs to transfer. */
813 : struct iovec *iovs;
814 :
815 : /** For SG buffer cases, number of iovecs in iovec array. */
816 : int iovcnt;
817 :
818 : /** Total size of data to be transferred. */
819 : uint64_t num_blocks;
820 :
821 : /** Starting offset (in blocks) of the bdev for this I/O. */
822 : uint64_t offset_blocks;
823 :
824 : /** Memory domain and its context to be used by bdev modules */
825 : struct spdk_memory_domain *memory_domain;
826 : void *memory_domain_ctx;
827 :
828 : /* Sequence of accel operations */
829 : struct spdk_accel_sequence *accel_sequence;
830 :
831 : /* Metadata buffer */
832 : void *md_buf;
833 :
834 : /** For fused operations such as COMPARE_AND_WRITE, array of iovecs
835 : * for the second operation.
836 : */
837 : struct iovec *fused_iovs;
838 :
839 : /** Number of iovecs in fused_iovs. */
840 : int fused_iovcnt;
841 :
842 : /** Specify whether each DIF check type is enabled. */
843 : uint32_t dif_check_flags;
844 :
845 : /** defined by \ref spdk_bdev_nvme_cdw12 */
846 : union spdk_bdev_nvme_cdw12 nvme_cdw12;
847 :
848 : /** defined by \ref spdk_bdev_nvme_cdw13 */
849 : union spdk_bdev_nvme_cdw13 nvme_cdw13;
850 :
851 : struct {
852 : /** Whether the buffer should be populated with the real data */
853 : uint8_t populate : 1;
854 :
855 : /** Whether the buffer should be committed back to disk */
856 : uint8_t commit : 1;
857 :
858 : /** True if this request is in the 'start' phase of zcopy. False if in 'end'. */
859 : uint8_t start : 1;
860 : } zcopy;
861 :
862 : struct {
863 : /** The callback argument for the outstanding request which this abort
864 : * attempts to cancel.
865 : */
866 : void *bio_cb_arg;
867 : } abort;
868 :
869 : struct {
870 : /** The offset of next data/hole. */
871 : uint64_t offset;
872 : } seek;
873 :
874 : struct {
875 : /** Starting source offset (in blocks) of the bdev for copy I/O. */
876 : uint64_t src_offset_blocks;
877 : } copy;
878 :
879 : /** DIF context */
880 : struct spdk_dif_ctx dif_ctx;
881 :
882 : /** DIF error information */
883 : struct spdk_dif_error dif_err;
884 : };
885 :
886 : struct spdk_bdev_io_reset_params {
887 : /** Channel reference held while messages for this reset are in progress. */
888 : struct spdk_io_channel *ch_ref;
889 : struct {
890 : /* Handle to timed poller that checks each channel for outstanding IO. */
891 : struct spdk_poller *poller;
892 : /* Store calculated time value, when a poller should stop its work. */
893 : uint64_t stop_time_tsc;
894 : } wait_poller;
895 : };
896 :
897 : struct spdk_bdev_io_abort_params {
898 : /** The outstanding request matching bio_cb_arg which this abort attempts to cancel. */
899 : struct spdk_bdev_io *bio_to_abort;
900 : };
901 :
902 : struct spdk_bdev_io_nvme_passthru_params {
903 : /* The NVMe command to execute */
904 : struct spdk_nvme_cmd cmd;
905 :
906 : /* For SG buffer cases, array of iovecs to transfer. */
907 : struct iovec *iovs;
908 :
909 : /* For SG buffer cases, number of iovecs in iovec array. */
910 : int iovcnt;
911 :
912 : /* The data buffer to transfer */
913 : void *buf;
914 :
915 : /* The number of bytes to transfer */
916 : size_t nbytes;
917 :
918 : /* The meta data buffer to transfer */
919 : void *md_buf;
920 :
921 : /* meta data buffer size to transfer */
922 : size_t md_len;
923 : };
924 :
925 : struct spdk_bdev_io_zone_mgmt_params {
926 : /* First logical block of a zone */
927 : uint64_t zone_id;
928 :
929 : /* Number of zones */
930 : uint32_t num_zones;
931 :
932 : /* Used to change zoned device zone state */
933 : enum spdk_bdev_zone_action zone_action;
934 :
935 : /* The data buffer */
936 : void *buf;
937 : };
938 :
939 : /**
940 : * Fields that are used internally by the bdev subsystem. Bdev modules
941 : * must not read or write to these fields.
942 : */
943 : struct spdk_bdev_io_internal_fields {
944 : /** The bdev I/O channel that this was handled on. */
945 : struct spdk_bdev_channel *ch;
946 :
947 : union {
948 : struct {
949 :
950 : /** Whether the accel_sequence member is valid */
951 : uint8_t has_accel_sequence : 1;
952 :
953 : /** Whether memory_domain member is valid */
954 : uint8_t has_memory_domain : 1;
955 :
956 : /** Whether the split data structure is valid */
957 : uint8_t split : 1;
958 :
959 : /** Whether ptr in the buf data structure is valid */
960 : uint8_t has_buf : 1;
961 :
962 : /** Whether the bounce_buf data structure is valid */
963 : uint8_t has_bounce_buf : 1;
964 :
965 : /** Whether we are currently inside the submit request call */
966 : uint8_t in_submit_request : 1;
967 :
968 : uint8_t reserved : 2;
969 : };
970 : uint8_t raw;
971 : } f;
972 :
973 : /** Status for the IO */
974 : int8_t status;
975 :
976 : /** Retry state (resubmit, re-pull, re-push, etc.) */
977 : uint8_t retry_state;
978 :
979 : uint8_t reserved[5];
980 :
981 : /** The bdev descriptor that was used when submitting this I/O. */
982 : struct spdk_bdev_desc *desc;
983 :
984 : /** User function that will be called when this completes */
985 : spdk_bdev_io_completion_cb cb;
986 :
987 : /** Context that will be passed to the completion callback */
988 : void *caller_ctx;
989 :
990 : /** Current tsc at submit time. Used to calculate latency at completion. */
991 : uint64_t submit_tsc;
992 :
993 : /** Entry to the list io_submitted of struct spdk_bdev_channel */
994 : TAILQ_ENTRY(spdk_bdev_io) ch_link;
995 :
996 : /** bdev_io pool entry */
997 : STAILQ_ENTRY(spdk_bdev_io) buf_link;
998 :
999 : /** Error information from a device */
1000 : union {
1001 : struct {
1002 : /** NVMe completion queue entry DW0 */
1003 : uint32_t cdw0;
1004 : /** NVMe status code type */
1005 : uint8_t sct;
1006 : /** NVMe status code */
1007 : uint8_t sc;
1008 : } nvme;
1009 : /** Only valid when status is SPDK_BDEV_IO_STATUS_SCSI_ERROR */
1010 : struct {
1011 : /** SCSI status code */
1012 : uint8_t sc;
1013 : /** SCSI sense key */
1014 : uint8_t sk;
1015 : /** SCSI additional sense code */
1016 : uint8_t asc;
1017 : /** SCSI additional sense code qualifier */
1018 : uint8_t ascq;
1019 : } scsi;
1020 : /** Only valid when status is SPDK_BDEV_IO_STATUS_AIO_ERROR */
1021 : int aio_result;
1022 : } error;
1023 :
1024 : struct {
1025 : /** stored user callback in case we split the I/O and use a temporary callback */
1026 : spdk_bdev_io_completion_cb stored_user_cb;
1027 :
1028 : /** number of blocks remaining in a split i/o */
1029 : uint64_t remaining_num_blocks;
1030 :
1031 : /** current offset of the split I/O in the bdev */
1032 : uint64_t current_offset_blocks;
1033 :
1034 : /** count of outstanding batched split I/Os */
1035 : uint32_t outstanding;
1036 : } split;
1037 :
1038 : struct {
1039 : /** bdev allocated memory associated with this request */
1040 : void *ptr;
1041 :
1042 : /** requested size of the buffer associated with this I/O */
1043 : uint64_t len;
1044 : } buf;
1045 :
1046 : /** if the request is double buffered, store original request iovs here */
1047 : struct {
1048 : struct iovec iov;
1049 : struct iovec md_iov;
1050 : struct iovec orig_md_iov;
1051 : struct iovec *orig_iovs;
1052 : int orig_iovcnt;
1053 : } bounce_buf;
1054 :
1055 : /** Callback for when the aux buf is allocated */
1056 : spdk_bdev_io_get_aux_buf_cb get_aux_buf_cb;
1057 :
1058 : /** Callback for when buf is allocated */
1059 : spdk_bdev_io_get_buf_cb get_buf_cb;
1060 :
1061 : /**
1062 : * Queue entry used in several cases:
1063 : * 1. IOs awaiting retry due to NOMEM status,
1064 : * 2. IOs awaiting submission due to QoS,
1065 : * 3. IOs with an accel sequence being executed,
1066 : * 4. IOs awaiting memory domain pull/push,
1067 : * 5. queued reset requests.
1068 : */
1069 : TAILQ_ENTRY(spdk_bdev_io) link;
1070 :
1071 : /** iobuf queue entry */
1072 : struct spdk_iobuf_entry iobuf;
1073 :
1074 : /** Enables queuing parent I/O when no bdev_ios available for split children. */
1075 : struct spdk_bdev_io_wait_entry waitq_entry;
1076 :
1077 : /** Memory domain and its context passed by the user in ext API */
1078 : struct spdk_memory_domain *memory_domain;
1079 : void *memory_domain_ctx;
1080 :
1081 : /* Sequence of accel operations passed by the user */
1082 : struct spdk_accel_sequence *accel_sequence;
1083 :
1084 : /** Data transfer completion callback */
1085 : void (*data_transfer_cpl)(void *ctx, int rc);
1086 : };
1087 :
1088 : struct spdk_bdev_io {
1089 : /** The block device that this I/O belongs to. */
1090 : struct spdk_bdev *bdev;
1091 :
1092 : /** Enumerated value representing the I/O type. */
1093 : uint8_t type;
1094 :
1095 : uint8_t reserved0;
1096 :
1097 : /** Number of IO submission retries */
1098 : uint16_t num_retries;
1099 :
1100 : uint32_t reserved1;
1101 :
1102 : /** A single iovec element for use by this bdev_io. */
1103 : struct iovec iov;
1104 :
1105 : /** Array of iovecs used for I/O splitting. */
1106 : struct iovec child_iov[SPDK_BDEV_IO_NUM_CHILD_IOV];
1107 :
1108 : uint8_t reserved2[32];
1109 :
1110 : /** Parameters filled in by the user */
1111 : union {
1112 : struct spdk_bdev_io_block_params bdev;
1113 : struct spdk_bdev_io_reset_params reset;
1114 : struct spdk_bdev_io_abort_params abort;
1115 : struct spdk_bdev_io_nvme_passthru_params nvme_passthru;
1116 : struct spdk_bdev_io_zone_mgmt_params zone_mgmt;
1117 : } u;
1118 :
1119 : uint8_t reserved3[40];
1120 :
1121 : /**
1122 : * Fields that are used internally by the bdev subsystem. Bdev modules
1123 : * must not read or write to these fields.
1124 : */
1125 : struct spdk_bdev_io_internal_fields internal;
1126 :
1127 : /**
1128 : * Per I/O context for use by the bdev module.
1129 : */
1130 : uint8_t driver_ctx[0];
1131 :
1132 : /* No members may be added after driver_ctx! */
1133 : };
1134 : SPDK_STATIC_ASSERT(offsetof(struct spdk_bdev_io, driver_ctx) % SPDK_CACHE_LINE_SIZE == 0,
1135 : "driver_ctx not cache line aligned");
1136 :
1137 : /**
1138 : * Register a new bdev.
1139 : *
1140 : * This function must be called from the SPDK app thread.
1141 : *
1142 : * \param bdev Block device to register.
1143 : *
1144 : * \return 0 on success.
1145 : * \return -EINVAL if the bdev name is NULL.
1146 : * \return -EEXIST if a bdev or bdev alias with the same name already exists.
1147 : */
1148 : int spdk_bdev_register(struct spdk_bdev *bdev);
1149 :
1150 : /**
1151 : * Start unregistering a bdev. This will notify each currently open descriptor
1152 : * on this bdev of the hotremoval to request the upper layers to stop using this bdev
1153 : * and manually close all the descriptors with spdk_bdev_close().
1154 : * The actual bdev unregistration may be deferred until all descriptors are closed.
1155 : *
1156 : * The cb_fn will be called from the context of the same spdk_thread that called
1157 : * spdk_bdev_unregister.
1158 : *
1159 : * Note: spdk_bdev_unregister() can be unsafe unless the bdev is not opened before and
1160 : * closed after unregistration. It is recommended to use spdk_bdev_unregister_by_name().
1161 : *
1162 : * \param bdev Block device to unregister.
1163 : * \param cb_fn Callback function to be called when the unregister is complete.
1164 : * \param cb_arg Argument to be supplied to cb_fn
1165 : */
1166 : void spdk_bdev_unregister(struct spdk_bdev *bdev, spdk_bdev_unregister_cb cb_fn, void *cb_arg);
1167 :
1168 : /**
1169 : * Start unregistering a bdev. This will notify each currently open descriptor
1170 : * on this bdev of the hotremoval to request the upper layer to stop using this bdev
1171 : * and manually close all the descriptors with spdk_bdev_close().
1172 : * The actual bdev unregistration may be deferred until all descriptors are closed.
1173 : *
1174 : * The cb_fn will be called from the context of the same spdk_thread that called
1175 : * spdk_bdev_unregister.
1176 : *
1177 : * \param bdev_name Block device name to unregister.
1178 : * \param module Module by which the block device was registered.
1179 : * \param cb_fn Callback function to be called when the unregister is complete.
1180 : * \param cb_arg Argument to be supplied to cb_fn
1181 : *
1182 : * \return 0 on success, or suitable errno value otherwise
1183 : */
1184 : int spdk_bdev_unregister_by_name(const char *bdev_name, struct spdk_bdev_module *module,
1185 : spdk_bdev_unregister_cb cb_fn, void *cb_arg);
1186 :
1187 : /**
1188 : * Notify the bdev layer that an asynchronous destruct operation is complete.
1189 : *
1190 : * A Bdev with an asynchronous destruct path should return 1 from its
1191 : * destruct function and call this function at the conclusion of that path.
1192 : * Bdevs with synchronous destruct paths should return 0 from their destruct
1193 : * path.
1194 : *
1195 : * \param bdev Block device that was destroyed.
1196 : * \param bdeverrno Error code returned from bdev's destruct callback.
1197 : */
1198 : void spdk_bdev_destruct_done(struct spdk_bdev *bdev, int bdeverrno);
1199 :
1200 : /**
1201 : * Indicate to the bdev layer that the module is done examining a bdev.
1202 : *
1203 : * To be called during examine_config function or asynchronously in response to the
1204 : * module's examine_disk function being called.
1205 : *
1206 : * \param module Pointer to the module completing the examination.
1207 : */
1208 : void spdk_bdev_module_examine_done(struct spdk_bdev_module *module);
1209 :
1210 : /**
1211 : * Indicate to the bdev layer that the module is done initializing.
1212 : *
1213 : * To be called once after an asynchronous operation required for module initialization is
1214 : * completed. If module->async_init is false, the module must not call this function.
1215 : *
1216 : * \param module Pointer to the module completing the initialization.
1217 : */
1218 : void spdk_bdev_module_init_done(struct spdk_bdev_module *module);
1219 :
1220 : /**
1221 : * Indicate that the module finish has completed.
1222 : *
1223 : * To be called in response to the module_fini, only if async_fini is set.
1224 : *
1225 : */
1226 : void spdk_bdev_module_fini_done(void);
1227 :
1228 : /**
1229 : * Indicate that the module fini start has completed.
1230 : *
1231 : * To be called in response to the fini_start, only if async_fini_start is set.
1232 : * May be called during fini_start or asynchronously.
1233 : *
1234 : */
1235 : void spdk_bdev_module_fini_start_done(void);
1236 :
1237 : /**
1238 : * Add alias to block device names list.
1239 : * Aliases can be add only to registered bdev.
1240 : *
1241 : * \param bdev Block device to query.
1242 : * \param alias Alias to be added to list.
1243 : *
1244 : * \return 0 on success
1245 : * \return -EEXIST if alias already exists as name or alias on any bdev
1246 : * \return -ENOMEM if memory cannot be allocated to store alias
1247 : * \return -EINVAL if passed alias is empty
1248 : */
1249 : int spdk_bdev_alias_add(struct spdk_bdev *bdev, const char *alias);
1250 :
1251 : /**
1252 : * Removes name from block device names list.
1253 : *
1254 : * \param bdev Block device to query.
1255 : * \param alias Alias to be deleted from list.
1256 : * \return 0 on success
1257 : * \return -ENOENT if alias does not exists
1258 : */
1259 : int spdk_bdev_alias_del(struct spdk_bdev *bdev, const char *alias);
1260 :
1261 : /**
1262 : * Removes all alias from block device alias list.
1263 : *
1264 : * \param bdev Block device to operate.
1265 : */
1266 : void spdk_bdev_alias_del_all(struct spdk_bdev *bdev);
1267 :
1268 : /**
1269 : * Get pointer to block device aliases list.
1270 : *
1271 : * \param bdev Block device to query.
1272 : * \return Pointer to bdev aliases list.
1273 : */
1274 : const struct spdk_bdev_aliases_list *spdk_bdev_get_aliases(const struct spdk_bdev *bdev);
1275 :
1276 : /**
1277 : * Allocate a buffer for given bdev_io. Allocation will happen
1278 : * only if the bdev_io has no assigned SGL yet or SGL is not
1279 : * aligned to \c bdev->required_alignment. If SGL is not aligned,
1280 : * this call will cause copy from SGL to bounce buffer on write
1281 : * path or copy from bounce buffer to SGL before completion
1282 : * callback on read path. The buffer will be freed automatically
1283 : * on \c spdk_bdev_free_io() call. This call will never fail.
1284 : * In case of lack of memory given callback \c cb will be deferred
1285 : * until enough memory is freed. This function *must* be called
1286 : * from the thread issuing \c bdev_io.
1287 : *
1288 : * \param bdev_io I/O to allocate buffer for.
1289 : * \param cb callback to be called when the buffer is allocated
1290 : * or the bdev_io has an SGL assigned already.
1291 : * \param len size of the buffer to allocate. In case the bdev_io
1292 : * doesn't have an SGL assigned this field must be no bigger than
1293 : * \c SPDK_BDEV_LARGE_BUF_MAX_SIZE.
1294 : */
1295 : void spdk_bdev_io_get_buf(struct spdk_bdev_io *bdev_io, spdk_bdev_io_get_buf_cb cb, uint64_t len);
1296 :
1297 : /**
1298 : * Allocate an auxiliary buffer for given bdev_io. The length of the
1299 : * buffer will be the same size as the bdev_io primary buffer. The buffer
1300 : * must be freed using \c spdk_bdev_io_put_aux_buf() before completing
1301 : * the associated bdev_io. This call will never fail. In case of lack of
1302 : * memory given callback \c cb will be deferred until enough memory is freed.
1303 : *
1304 : * \param bdev_io I/O to allocate buffer for.
1305 : * \param cb callback to be called when the buffer is allocated
1306 : */
1307 : void spdk_bdev_io_get_aux_buf(struct spdk_bdev_io *bdev_io, spdk_bdev_io_get_aux_buf_cb cb);
1308 :
1309 : /**
1310 : * Free an auxiliary buffer previously allocated by \c spdk_bdev_io_get_aux_buf().
1311 : *
1312 : * \param bdev_io bdev_io specified when the aux_buf was allocated.
1313 : * \param aux_buf auxiliary buffer to free
1314 : */
1315 : void spdk_bdev_io_put_aux_buf(struct spdk_bdev_io *bdev_io, void *aux_buf);
1316 :
1317 : /**
1318 : * Set the given buffer as the data buffer described by this bdev_io.
1319 : *
1320 : * The portion of the buffer used may be adjusted for memory alignment
1321 : * purposes.
1322 : *
1323 : * \param bdev_io I/O to set the buffer on.
1324 : * \param buf The buffer to set as the active data buffer.
1325 : * \param len The length of the buffer.
1326 : *
1327 : */
1328 : void spdk_bdev_io_set_buf(struct spdk_bdev_io *bdev_io, void *buf, size_t len);
1329 :
1330 : /**
1331 : * Set the given buffer as metadata buffer described by this bdev_io.
1332 : *
1333 : * \param bdev_io I/O to set the buffer on.
1334 : * \param md_buf The buffer to set as the active metadata buffer.
1335 : * \param len The length of the metadata buffer.
1336 : */
1337 : void spdk_bdev_io_set_md_buf(struct spdk_bdev_io *bdev_io, void *md_buf, size_t len);
1338 :
1339 : /**
1340 : * Complete a bdev_io
1341 : *
1342 : * \param bdev_io I/O to complete.
1343 : * \param status The I/O completion status.
1344 : */
1345 : void spdk_bdev_io_complete(struct spdk_bdev_io *bdev_io,
1346 : enum spdk_bdev_io_status status);
1347 :
1348 : /**
1349 : * Complete a bdev_io with an NVMe status code and DW0 completion queue entry
1350 : *
1351 : * \param bdev_io I/O to complete.
1352 : * \param cdw0 NVMe Completion Queue DW0 value (set to 0 if not applicable)
1353 : * \param sct NVMe Status Code Type.
1354 : * \param sc NVMe Status Code.
1355 : */
1356 : void spdk_bdev_io_complete_nvme_status(struct spdk_bdev_io *bdev_io, uint32_t cdw0, int sct,
1357 : int sc);
1358 :
1359 : /**
1360 : * Complete a bdev_io with a SCSI status code.
1361 : *
1362 : * \param bdev_io I/O to complete.
1363 : * \param sc SCSI Status Code.
1364 : * \param sk SCSI Sense Key.
1365 : * \param asc SCSI Additional Sense Code.
1366 : * \param ascq SCSI Additional Sense Code Qualifier.
1367 : */
1368 : void spdk_bdev_io_complete_scsi_status(struct spdk_bdev_io *bdev_io, enum spdk_scsi_status sc,
1369 : enum spdk_scsi_sense sk, uint8_t asc, uint8_t ascq);
1370 :
1371 : /**
1372 : * Complete a bdev_io with AIO errno.
1373 : *
1374 : * \param bdev_io I/O to complete.
1375 : * \param aio_result Negative errno returned from AIO.
1376 : */
1377 : void spdk_bdev_io_complete_aio_status(struct spdk_bdev_io *bdev_io, int aio_result);
1378 :
1379 : /**
1380 : * Complete a bdev_io copying a status from another bdev_io.
1381 : *
1382 : * \param bdev_io I/O to complete.
1383 : * \param base_io I/O from which to copy the status.
1384 : */
1385 : void spdk_bdev_io_complete_base_io_status(struct spdk_bdev_io *bdev_io,
1386 : const struct spdk_bdev_io *base_io);
1387 :
1388 : /**
1389 : * Get a thread that given bdev_io was submitted on.
1390 : *
1391 : * \param bdev_io I/O
1392 : * \return thread that submitted the I/O
1393 : */
1394 : struct spdk_thread *spdk_bdev_io_get_thread(struct spdk_bdev_io *bdev_io);
1395 :
1396 : /**
1397 : * Get the bdev module's I/O channel that the given bdev_io was submitted on.
1398 : *
1399 : * \param bdev_io I/O
1400 : * \return the bdev module's I/O channel that the given bdev_io was submitted on.
1401 : */
1402 : struct spdk_io_channel *spdk_bdev_io_get_io_channel(struct spdk_bdev_io *bdev_io);
1403 :
1404 : /**
1405 : * Get the submit_tsc of a bdev I/O.
1406 : *
1407 : * \param bdev_io The bdev I/O to get the submit_tsc.
1408 : *
1409 : * \return The submit_tsc of the specified bdev I/O.
1410 : */
1411 : uint64_t spdk_bdev_io_get_submit_tsc(struct spdk_bdev_io *bdev_io);
1412 :
1413 : /**
1414 : * Query if metadata is hidden from the bdev I/O.
1415 : *
1416 : * \param bdev_io The bdev I/O to query.
1417 : *
1418 : * \return true if metadata is hidden from the bdev I/O, or false otherwise.
1419 : */
1420 : bool spdk_bdev_io_hide_metadata(struct spdk_bdev_io *bdev_io);
1421 :
1422 : /**
1423 : * Resize for a bdev.
1424 : *
1425 : * Change number of blocks for provided block device.
1426 : * It can only be called on a registered bdev.
1427 : *
1428 : * \param bdev Block device to change.
1429 : * \param size New size of bdev.
1430 : * \return 0 on success, negated errno on failure.
1431 : */
1432 : int spdk_bdev_notify_blockcnt_change(struct spdk_bdev *bdev, uint64_t size);
1433 :
1434 : /**
1435 : * Translates NVMe status codes to SCSI status information.
1436 : *
1437 : * The codes are stored in the user supplied integers.
1438 : *
1439 : * \param bdev_io I/O containing status codes to translate.
1440 : * \param sc SCSI Status Code will be stored here.
1441 : * \param sk SCSI Sense Key will be stored here.
1442 : * \param asc SCSI Additional Sense Code will be stored here.
1443 : * \param ascq SCSI Additional Sense Code Qualifier will be stored here.
1444 : */
1445 : void spdk_scsi_nvme_translate(const struct spdk_bdev_io *bdev_io,
1446 : int *sc, int *sk, int *asc, int *ascq);
1447 :
1448 : /**
1449 : * Add the given module to the list of registered modules.
1450 : * This function should be invoked by referencing the macro
1451 : * SPDK_BDEV_MODULE_REGISTER in the module c file.
1452 : *
1453 : * \param bdev_module Module to be added.
1454 : */
1455 : void spdk_bdev_module_list_add(struct spdk_bdev_module *bdev_module);
1456 :
1457 : /**
1458 : * Find registered module with name pointed by \c name.
1459 : *
1460 : * \param name name of module to be searched for.
1461 : * \return pointer to module or NULL if no module with \c name exist
1462 : */
1463 : struct spdk_bdev_module *spdk_bdev_module_list_find(const char *name);
1464 :
1465 : static inline struct spdk_bdev_io *
1466 804 : spdk_bdev_io_from_ctx(void *ctx)
1467 : {
1468 804 : return SPDK_CONTAINEROF(ctx, struct spdk_bdev_io, driver_ctx);
1469 : }
1470 :
1471 : struct spdk_bdev_part_base;
1472 :
1473 : /**
1474 : * Returns a pointer to the spdk_bdev associated with an spdk_bdev_part_base
1475 : *
1476 : * \param part_base A pointer to an spdk_bdev_part_base object.
1477 : *
1478 : * \return A pointer to the base's spdk_bdev struct.
1479 : */
1480 : struct spdk_bdev *spdk_bdev_part_base_get_bdev(struct spdk_bdev_part_base *part_base);
1481 :
1482 : /**
1483 : * Returns a spdk_bdev name of the corresponding spdk_bdev_part_base
1484 : *
1485 : * \param part_base A pointer to an spdk_bdev_part_base object.
1486 : *
1487 : * \return A text string representing the name of the base bdev.
1488 : */
1489 : const char *spdk_bdev_part_base_get_bdev_name(struct spdk_bdev_part_base *part_base);
1490 :
1491 : /**
1492 : * Returns a pointer to the spdk_bdev_descriptor associated with an spdk_bdev_part_base
1493 : *
1494 : * \param part_base A pointer to an spdk_bdev_part_base object.
1495 : *
1496 : * \return A pointer to the base's spdk_bdev_desc struct.
1497 : */
1498 : struct spdk_bdev_desc *spdk_bdev_part_base_get_desc(struct spdk_bdev_part_base *part_base);
1499 :
1500 : /**
1501 : * Returns a pointer to the tailq associated with an spdk_bdev_part_base
1502 : *
1503 : * \param part_base A pointer to an spdk_bdev_part_base object.
1504 : *
1505 : * \return The head of a tailq of spdk_bdev_part structs registered to the base's module.
1506 : */
1507 : struct bdev_part_tailq *spdk_bdev_part_base_get_tailq(struct spdk_bdev_part_base *part_base);
1508 :
1509 : /**
1510 : * Returns a pointer to the module level context associated with an spdk_bdev_part_base
1511 : *
1512 : * \param part_base A pointer to an spdk_bdev_part_base object.
1513 : *
1514 : * \return A pointer to the module level context registered with the base in spdk_bdev_part_base_construct.
1515 : */
1516 : void *spdk_bdev_part_base_get_ctx(struct spdk_bdev_part_base *part_base);
1517 :
1518 : typedef void (*spdk_bdev_part_base_free_fn)(void *ctx);
1519 :
1520 : struct spdk_bdev_part {
1521 : /* Entry into the module's global list of bdev parts */
1522 : TAILQ_ENTRY(spdk_bdev_part) tailq;
1523 :
1524 : /**
1525 : * Fields that are used internally by part.c These fields should only
1526 : * be accessed from a module using any pertinent get and set methods.
1527 : */
1528 : struct bdev_part_internal_fields {
1529 :
1530 : /* This part's corresponding bdev object. Not to be confused with the base bdev */
1531 : struct spdk_bdev bdev;
1532 :
1533 : /* The base to which this part belongs */
1534 : struct spdk_bdev_part_base *base;
1535 :
1536 : /* number of blocks from the start of the base bdev to the start of this part */
1537 : uint64_t offset_blocks;
1538 : } internal;
1539 : };
1540 :
1541 : struct spdk_bdev_part_channel {
1542 : struct spdk_bdev_part *part;
1543 : struct spdk_io_channel *base_ch;
1544 : };
1545 :
1546 : typedef TAILQ_HEAD(bdev_part_tailq, spdk_bdev_part) SPDK_BDEV_PART_TAILQ;
1547 :
1548 : /**
1549 : * Free the base corresponding to one or more spdk_bdev_part.
1550 : *
1551 : * \param base The base to free.
1552 : */
1553 : void spdk_bdev_part_base_free(struct spdk_bdev_part_base *base);
1554 :
1555 : /**
1556 : * Free an spdk_bdev_part context.
1557 : *
1558 : * \param part The part to free.
1559 : *
1560 : * \return 1 always. To indicate that the operation is asynchronous.
1561 : */
1562 : int spdk_bdev_part_free(struct spdk_bdev_part *part);
1563 :
1564 : /**
1565 : * Calls spdk_bdev_unregister on the bdev for each part associated with base_bdev.
1566 : *
1567 : * \param part_base The part base object built on top of an spdk_bdev
1568 : * \param tailq The list of spdk_bdev_part bdevs associated with this base bdev.
1569 : */
1570 : void spdk_bdev_part_base_hotremove(struct spdk_bdev_part_base *part_base,
1571 : struct bdev_part_tailq *tailq);
1572 :
1573 : /**
1574 : * Construct a new spdk_bdev_part_base on top of the provided bdev.
1575 : *
1576 : * \param bdev_name Name of the bdev upon which this base will be built.
1577 : * \param remove_cb Function to be called upon hotremove of the bdev.
1578 : * \param module The module to which this bdev base belongs.
1579 : * \param fn_table Function table for communicating with the bdev backend.
1580 : * \param tailq The head of the list of all spdk_bdev_part structures registered to this base's module.
1581 : * \param free_fn User provided function to free base related context upon bdev removal or shutdown.
1582 : * \param ctx Module specific context for this bdev part base.
1583 : * \param channel_size Channel size in bytes.
1584 : * \param ch_create_cb Called after a new channel is allocated.
1585 : * \param ch_destroy_cb Called upon channel deletion.
1586 : * \param base output parameter for the part object when operation is successful.
1587 : *
1588 : * \return 0 if operation is successful, or suitable errno value otherwise.
1589 : */
1590 : int spdk_bdev_part_base_construct_ext(const char *bdev_name,
1591 : spdk_bdev_remove_cb_t remove_cb,
1592 : struct spdk_bdev_module *module,
1593 : struct spdk_bdev_fn_table *fn_table,
1594 : struct bdev_part_tailq *tailq,
1595 : spdk_bdev_part_base_free_fn free_fn,
1596 : void *ctx,
1597 : uint32_t channel_size,
1598 : spdk_io_channel_create_cb ch_create_cb,
1599 : spdk_io_channel_destroy_cb ch_destroy_cb,
1600 : struct spdk_bdev_part_base **base);
1601 :
1602 : /** Options used when constructing a part bdev. */
1603 : struct spdk_bdev_part_construct_opts {
1604 : /* Size of this structure in bytes */
1605 : uint64_t opts_size;
1606 : /** UUID of the bdev */
1607 : struct spdk_uuid uuid;
1608 : };
1609 :
1610 : SPDK_STATIC_ASSERT(sizeof(struct spdk_bdev_part_construct_opts) == 24, "Incorrect size");
1611 :
1612 : /**
1613 : * Initialize options that will be passed to spdk_bdev_part_construct_ext().
1614 : *
1615 : * \param opts Options structure to initialize
1616 : * \param size Size of opts structure.
1617 : */
1618 : void spdk_bdev_part_construct_opts_init(struct spdk_bdev_part_construct_opts *opts, uint64_t size);
1619 :
1620 : /**
1621 : * Create a logical spdk_bdev_part on top of a base.
1622 : *
1623 : * \param part The part object allocated by the user.
1624 : * \param base The base from which to create the part.
1625 : * \param name The name of the new spdk_bdev_part.
1626 : * \param offset_blocks The offset into the base bdev at which this part begins.
1627 : * \param num_blocks The number of blocks that this part will span.
1628 : * \param product_name Unique name for this type of block device.
1629 : *
1630 : * \return 0 on success.
1631 : * \return -1 if the bases underlying bdev cannot be claimed by the current module.
1632 : */
1633 : int spdk_bdev_part_construct(struct spdk_bdev_part *part, struct spdk_bdev_part_base *base,
1634 : char *name, uint64_t offset_blocks, uint64_t num_blocks,
1635 : char *product_name);
1636 :
1637 : /**
1638 : * Create a logical spdk_bdev_part on top of a base with a non-NULL bdev UUID
1639 : *
1640 : * \param part The part object allocated by the user.
1641 : * \param base The base from which to create the part.
1642 : * \param name The name of the new spdk_bdev_part.
1643 : * \param offset_blocks The offset into the base bdev at which this part begins.
1644 : * \param num_blocks The number of blocks that this part will span.
1645 : * \param product_name Unique name for this type of block device.
1646 : * \param opts Additional options.
1647 : *
1648 : * \return 0 on success.
1649 : * \return -1 if the bases underlying bdev cannot be claimed by the current module.
1650 : */
1651 : int spdk_bdev_part_construct_ext(struct spdk_bdev_part *part, struct spdk_bdev_part_base *base,
1652 : char *name, uint64_t offset_blocks, uint64_t num_blocks,
1653 : char *product_name,
1654 : const struct spdk_bdev_part_construct_opts *opts);
1655 :
1656 : /**
1657 : * Forwards I/O from an spdk_bdev_part to the underlying base bdev.
1658 : *
1659 : * This function will apply the offset_blocks the user provided to
1660 : * spdk_bdev_part_construct to the I/O. The user should not manually
1661 : * apply this offset before submitting any I/O through this function.
1662 : *
1663 : * \param ch The I/O channel associated with the spdk_bdev_part.
1664 : * \param bdev_io The I/O to be submitted to the underlying bdev.
1665 : * \return 0 on success or non-zero if submit request failed.
1666 : */
1667 : int spdk_bdev_part_submit_request(struct spdk_bdev_part_channel *ch, struct spdk_bdev_io *bdev_io);
1668 :
1669 : /**
1670 : * Forwards I/O from an spdk_bdev_part to the underlying base bdev.
1671 : *
1672 : * This function will apply the offset_blocks the user provided to
1673 : * spdk_bdev_part_construct to the I/O. The user should not manually
1674 : * apply this offset before submitting any I/O through this function.
1675 : *
1676 : * This function enables user to specify a completion callback. It is required that
1677 : * the completion callback calls spdk_bdev_io_complete() for the forwarded I/O.
1678 : *
1679 : * \param ch The I/O channel associated with the spdk_bdev_part.
1680 : * \param bdev_io The I/O to be submitted to the underlying bdev.
1681 : * \param cb Called when the forwarded I/O completes.
1682 : * \return 0 on success or non-zero if submit request failed.
1683 : */
1684 : int spdk_bdev_part_submit_request_ext(struct spdk_bdev_part_channel *ch,
1685 : struct spdk_bdev_io *bdev_io,
1686 : spdk_bdev_io_completion_cb cb);
1687 :
1688 : /**
1689 : * Return a pointer to this part's spdk_bdev.
1690 : *
1691 : * \param part An spdk_bdev_part object.
1692 : *
1693 : * \return A pointer to this part's spdk_bdev object.
1694 : */
1695 : struct spdk_bdev *spdk_bdev_part_get_bdev(struct spdk_bdev_part *part);
1696 :
1697 : /**
1698 : * Return a pointer to this part's base.
1699 : *
1700 : * \param part An spdk_bdev_part object.
1701 : *
1702 : * \return A pointer to this part's spdk_bdev_part_base object.
1703 : */
1704 : struct spdk_bdev_part_base *spdk_bdev_part_get_base(struct spdk_bdev_part *part);
1705 :
1706 : /**
1707 : * Return a pointer to this part's base bdev.
1708 : *
1709 : * The return value of this function is equivalent to calling
1710 : * spdk_bdev_part_base_get_bdev on this part's base.
1711 : *
1712 : * \param part An spdk_bdev_part object.
1713 : *
1714 : * \return A pointer to the bdev belonging to this part's base.
1715 : */
1716 : struct spdk_bdev *spdk_bdev_part_get_base_bdev(struct spdk_bdev_part *part);
1717 :
1718 : /**
1719 : * Return this part's offset from the beginning of the base bdev.
1720 : *
1721 : * This function should not be called in the I/O path. Any block
1722 : * translations to I/O will be handled in spdk_bdev_part_submit_request.
1723 : *
1724 : * \param part An spdk_bdev_part object.
1725 : *
1726 : * \return the block offset of this part from it's underlying bdev.
1727 : */
1728 : uint64_t spdk_bdev_part_get_offset_blocks(struct spdk_bdev_part *part);
1729 :
1730 : /**
1731 : * Push media management events. To send the notification that new events are
1732 : * available, spdk_bdev_notify_media_management needs to be called.
1733 : *
1734 : * \param bdev Block device
1735 : * \param events Array of media events
1736 : * \param num_events Size of the events array
1737 : *
1738 : * \return number of events pushed or negative errno in case of failure
1739 : */
1740 : int spdk_bdev_push_media_events(struct spdk_bdev *bdev, const struct spdk_bdev_media_event *events,
1741 : size_t num_events);
1742 :
1743 : /**
1744 : * Send SPDK_BDEV_EVENT_MEDIA_MANAGEMENT to all open descriptors that have
1745 : * pending media events.
1746 : *
1747 : * \param bdev Block device
1748 : */
1749 : void spdk_bdev_notify_media_management(struct spdk_bdev *bdev);
1750 :
1751 : typedef int (*spdk_bdev_io_fn)(void *ctx, struct spdk_bdev_io *bdev_io);
1752 : typedef void (*spdk_bdev_for_each_io_cb)(void *ctx, int rc);
1753 :
1754 : /**
1755 : * Call the provided function on the appropriate thread for each bdev_io submitted
1756 : * to the provided bdev.
1757 : *
1758 : * Note: This function should be used only in the bdev module and it should be
1759 : * ensured that the bdev is not unregistered while executing the function.
1760 : * Both fn and cb are required to specify.
1761 : *
1762 : * \param bdev Block device to query.
1763 : * \param ctx Context passed to the function for each bdev_io and the completion
1764 : * callback function.
1765 : * \param fn Called on the appropriate thread for each bdev_io submitted to the bdev.
1766 : * \param cb Called when this operation completes.
1767 : */
1768 : void spdk_bdev_for_each_bdev_io(struct spdk_bdev *bdev, void *ctx, spdk_bdev_io_fn fn,
1769 : spdk_bdev_for_each_io_cb cb);
1770 :
1771 : typedef void (*spdk_bdev_get_current_qd_cb)(struct spdk_bdev *bdev, uint64_t current_qd,
1772 : void *cb_arg, int rc);
1773 :
1774 : /**
1775 : * Measure and return the queue depth from a bdev.
1776 : *
1777 : * Note: spdk_bdev_get_qd() works only when the user enables queue depth sampling,
1778 : * while this new function works even when queue depth sampling is disabled.
1779 : * The returned queue depth may not be exact, for example, some additional I/Os may
1780 : * have been submitted or completed during the for_each_channel operation.
1781 : * This function should be used only in the bdev module and it should be ensured
1782 : * that the dev is not unregistered while executing the function.
1783 : * cb_fn is required to specify.
1784 : *
1785 : * \param bdev Block device to query.
1786 : * \param cb_fn Callback function to be called with queue depth measured for a bdev.
1787 : * \param cb_arg Argument to pass to callback function.
1788 : */
1789 : void spdk_bdev_get_current_qd(struct spdk_bdev *bdev,
1790 : spdk_bdev_get_current_qd_cb cb_fn, void *cb_arg);
1791 :
1792 : /**
1793 : * Add I/O statistics.
1794 : *
1795 : * \param total The aggregated I/O statistics.
1796 : * \param add The I/O statistics to be added.
1797 : */
1798 : void spdk_bdev_add_io_stat(struct spdk_bdev_io_stat *total, struct spdk_bdev_io_stat *add);
1799 :
1800 : /**
1801 : * Output bdev I/O statistics information to a JSON stream.
1802 : *
1803 : * \param stat The bdev I/O statistics to output.
1804 : * \param w JSON write context.
1805 : */
1806 : void spdk_bdev_dump_io_stat_json(struct spdk_bdev_io_stat *stat, struct spdk_json_write_ctx *w);
1807 :
1808 : /**
1809 : * Reset I/O statistics structure.
1810 : *
1811 : * \param stat The I/O statistics to reset.
1812 : * \param mode The mode to reset I/O statistics.
1813 : */
1814 : void spdk_bdev_reset_io_stat(struct spdk_bdev_io_stat *stat, enum spdk_bdev_reset_stat_mode mode);
1815 :
1816 : typedef void (*spdk_bdev_quiesce_cb)(void *ctx, int status);
1817 :
1818 : /**
1819 : * Quiesce a bdev. All I/O submitted after this function is called will be queued until
1820 : * the bdev is unquiesced. A callback will be called when all outstanding I/O on this bdev
1821 : * submitted before calling this function have completed.
1822 : *
1823 : * Only the module that registered the bdev may call this function.
1824 : *
1825 : * \param bdev Block device.
1826 : * \param module The module that registered the bdev.
1827 : * \param cb_fn Callback function to be called when the bdev is quiesced. Optional.
1828 : * \param cb_arg Argument to be supplied to cb_fn.
1829 : *
1830 : * \return 0 on success, or suitable errno value otherwise.
1831 : */
1832 : int spdk_bdev_quiesce(struct spdk_bdev *bdev, struct spdk_bdev_module *module,
1833 : spdk_bdev_quiesce_cb cb_fn, void *cb_arg);
1834 :
1835 : /**
1836 : * Unquiesce a previously quiesced bdev. All I/O queued after the bdev was quiesced
1837 : * will be submitted.
1838 : *
1839 : * Only the module that registered the bdev may call this function.
1840 : *
1841 : * \param bdev Block device.
1842 : * \param module The module that registered the bdev.
1843 : * \param cb_fn Callback function to be called when the bdev is unquiesced. Optional.
1844 : * \param cb_arg Argument to be supplied to cb_fn.
1845 : *
1846 : * \return 0 on success, or suitable errno value otherwise.
1847 : */
1848 : int spdk_bdev_unquiesce(struct spdk_bdev *bdev, struct spdk_bdev_module *module,
1849 : spdk_bdev_quiesce_cb cb_fn, void *cb_arg);
1850 :
1851 : /**
1852 : * Quiesce a bdev LBA range.
1853 : * Same as spdk_bdev_quiesce() but limited to the specified LBA range.
1854 : *
1855 : * \param bdev Block device.
1856 : * \param module The module that registered the bdev.
1857 : * \param offset The offset of the start of the range, in blocks,
1858 : * from the start of the block device.
1859 : * \param length The length of the range, in blocks.
1860 : * \param cb_fn Callback function to be called when the range is quiesced. Optional.
1861 : * \param cb_arg Argument to be supplied to cb_fn.
1862 : *
1863 : * \return 0 on success, or suitable errno value otherwise.
1864 : */
1865 : int spdk_bdev_quiesce_range(struct spdk_bdev *bdev, struct spdk_bdev_module *module,
1866 : uint64_t offset, uint64_t length,
1867 : spdk_bdev_quiesce_cb cb_fn, void *cb_arg);
1868 :
1869 : /**
1870 : * Unquiesce a previously quiesced bdev LBA range.
1871 : * Same as spdk_bdev_unquiesce() but limited to the specified LBA range.
1872 : * The specified range must match exactly a previously quiesced LBA range.
1873 : *
1874 : * \param bdev Block device.
1875 : * \param module The module that registered the bdev.
1876 : * \param offset The offset of the start of the range, in blocks,
1877 : * from the start of the block device.
1878 : * \param length The length of the range, in blocks.
1879 : * \param cb_fn Callback function to be called when the range is unquiesced. Optional.
1880 : * \param cb_arg Argument to be supplied to cb_fn.
1881 : *
1882 : * \return 0 on success, or suitable errno value otherwise.
1883 : */
1884 : int spdk_bdev_unquiesce_range(struct spdk_bdev *bdev, struct spdk_bdev_module *module,
1885 : uint64_t offset, uint64_t length,
1886 : spdk_bdev_quiesce_cb cb_fn, void *cb_arg);
1887 :
1888 : /*
1889 : * Macro used to register module for later initialization.
1890 : */
1891 : #define SPDK_BDEV_MODULE_REGISTER(name, module) \
1892 : static void __attribute__((constructor)) _spdk_bdev_module_register_##name(void) \
1893 : { \
1894 : spdk_bdev_module_list_add(module); \
1895 : }
1896 :
1897 : #endif /* __SPDK_BDEV_MODULE_ONLY */
1898 :
1899 : #ifdef __cplusplus
1900 : }
1901 : #endif
1902 :
1903 : #endif /* SPDK_BDEV_MODULE_H */
|
