LCOV - code coverage report
Current view: top level - include/spdk - bdev_module.h (source / functions) Hit Total Coverage
Test: ut_cov_unit.info Lines: 2 2 100.0 %
Date: 2024-07-15 10:25:28 Functions: 1 1 100.0 %

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

Generated by: LCOV version 1.15