LCOV - code coverage report
Current view: top level - include/spdk - nvme.h (source / functions) Hit Total Coverage
Test: ut_cov_unit.info Lines: 2 2 100.0 %
Date: 2024-11-18 08:59:14 Functions: 1 1 100.0 %

          Line data    Source code
       1             : /*   SPDX-License-Identifier: BSD-3-Clause
       2             :  *   Copyright (C) 2015 Intel Corporation. All rights reserved.
       3             :  *   Copyright (c) 2019-2021 Mellanox Technologies LTD. All rights reserved.
       4             :  *   Copyright (c) 2021-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
       5             :  *   Copyright (c) 2023 Samsung Electronics Co., Ltd. All rights reserved.
       6             :  */
       7             : 
       8             : /** \file
       9             :  * NVMe driver public API
      10             :  */
      11             : 
      12             : #ifndef SPDK_NVME_H
      13             : #define SPDK_NVME_H
      14             : 
      15             : #include "spdk/stdinc.h"
      16             : 
      17             : #ifdef __cplusplus
      18             : extern "C" {
      19             : #endif
      20             : 
      21             : #include "spdk/dma.h"
      22             : #include "spdk/env.h"
      23             : #include "spdk/keyring.h"
      24             : #include "spdk/nvme_spec.h"
      25             : #include "spdk/nvmf_spec.h"
      26             : 
      27             : #define SPDK_NVME_TRANSPORT_NAME_FC             "FC"
      28             : #define SPDK_NVME_TRANSPORT_NAME_PCIE           "PCIE"
      29             : #define SPDK_NVME_TRANSPORT_NAME_RDMA           "RDMA"
      30             : #define SPDK_NVME_TRANSPORT_NAME_TCP            "TCP"
      31             : #define SPDK_NVME_TRANSPORT_NAME_VFIOUSER       "VFIOUSER"
      32             : #define SPDK_NVME_TRANSPORT_NAME_CUSTOM         "CUSTOM"
      33             : 
      34             : #define SPDK_NVMF_PRIORITY_MAX_LEN 4
      35             : 
      36             : /**
      37             :  * Opaque handle to a controller. Returned by spdk_nvme_probe()'s attach_cb.
      38             :  */
      39             : struct spdk_nvme_ctrlr;
      40             : 
      41             : /**
      42             :  * NVMe controller initialization options.
      43             :  *
      44             :  * A pointer to this structure will be provided for each probe callback from spdk_nvme_probe() to
      45             :  * allow the user to request non-default options, and the actual options enabled on the controller
      46             :  * will be provided during the attach callback.
      47             :  */
      48             : struct spdk_nvme_ctrlr_opts {
      49             :         /**
      50             :          * Number of I/O queues to request (used to set Number of Queues feature)
      51             :          */
      52             :         uint32_t num_io_queues;
      53             : 
      54             :         /**
      55             :          * Enable submission queue in controller memory buffer
      56             :          */
      57             :         bool use_cmb_sqs;
      58             : 
      59             :         /**
      60             :          * Don't initiate shutdown processing
      61             :          */
      62             :         bool no_shn_notification;
      63             : 
      64             :         /* Hole at bytes 6-7. */
      65             :         uint8_t reserved6[2];
      66             : 
      67             :         /**
      68             :          * Type of arbitration mechanism
      69             :          */
      70             :         enum spdk_nvme_cc_ams arb_mechanism;
      71             : 
      72             :         /**
      73             :          * Maximum number of commands that the controller may launch at one time.  The
      74             :          * value is expressed as a power of two, valid values are from 0-7, and 7 means
      75             :          * unlimited.
      76             :          */
      77             :         uint8_t arbitration_burst;
      78             : 
      79             :         /**
      80             :          * Number of commands that may be executed from the low priority queue in each
      81             :          * arbitration round.  This field is only valid when arb_mechanism is set to
      82             :          * SPDK_NVME_CC_AMS_WRR (weighted round robin).
      83             :          */
      84             :         uint8_t low_priority_weight;
      85             : 
      86             :         /**
      87             :          * Number of commands that may be executed from the medium priority queue in each
      88             :          * arbitration round.  This field is only valid when arb_mechanism is set to
      89             :          * SPDK_NVME_CC_AMS_WRR (weighted round robin).
      90             :          */
      91             :         uint8_t medium_priority_weight;
      92             : 
      93             :         /**
      94             :          * Number of commands that may be executed from the high priority queue in each
      95             :          * arbitration round.  This field is only valid when arb_mechanism is set to
      96             :          * SPDK_NVME_CC_AMS_WRR (weighted round robin).
      97             :          */
      98             :         uint8_t high_priority_weight;
      99             : 
     100             :         /**
     101             :          * Keep alive timeout in milliseconds (0 = disabled).
     102             :          *
     103             :          * The NVMe library will set the Keep Alive Timer feature to this value and automatically
     104             :          * send Keep Alive commands as needed.  The library user must call
     105             :          * spdk_nvme_ctrlr_process_admin_completions() periodically to ensure Keep Alive commands
     106             :          * are sent.
     107             :          */
     108             :         uint32_t keep_alive_timeout_ms;
     109             : 
     110             :         /**
     111             :          * Specify the retry number when there is issue with the transport
     112             :          */
     113             :         uint8_t transport_retry_count;
     114             : 
     115             :         /* Hole at bytes 21-23. */
     116             :         uint8_t reserved21[3];
     117             : 
     118             :         /**
     119             :          * The queue depth of each NVMe I/O queue.
     120             :          */
     121             :         uint32_t io_queue_size;
     122             : 
     123             :         /**
     124             :          * The host NQN to use when connecting to NVMe over Fabrics controllers.
     125             :          *
     126             :          * If empty, a default value will be used.
     127             :          */
     128             :         char hostnqn[SPDK_NVMF_NQN_MAX_LEN + 1];
     129             : 
     130             :         /**
     131             :          * The number of requests to allocate for each NVMe I/O queue.
     132             :          *
     133             :          * This should be at least as large as io_queue_size.
     134             :          *
     135             :          * A single I/O may allocate more than one request, since splitting may be necessary to
     136             :          * conform to the device's maximum transfer size, PRP list compatibility requirements,
     137             :          * or driver-assisted striping.
     138             :          */
     139             :         uint32_t io_queue_requests;
     140             : 
     141             :         /**
     142             :          * Source address for NVMe-oF connections.
     143             :          * Set src_addr and src_svcid to empty strings if no source address should be
     144             :          * specified.
     145             :          */
     146             :         char src_addr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
     147             : 
     148             :         /**
     149             :          * Source service ID (port) for NVMe-oF connections.
     150             :          * Set src_addr and src_svcid to empty strings if no source address should be
     151             :          * specified.
     152             :          */
     153             :         char src_svcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
     154             : 
     155             :         /**
     156             :          * The host identifier to use when connecting to controllers with 64-bit host ID support.
     157             :          *
     158             :          * Set to all zeroes to specify that no host ID should be provided to the controller.
     159             :          */
     160             :         uint8_t host_id[8];
     161             : 
     162             :         /**
     163             :          * The host identifier to use when connecting to controllers with extended (128-bit) host ID support.
     164             :          *
     165             :          * Set to all zeroes to specify that no host ID should be provided to the controller.
     166             :          */
     167             :         uint8_t extended_host_id[16];
     168             : 
     169             :         /* Hole at bytes 570-571. */
     170             :         uint8_t reserved570[2];
     171             : 
     172             :         /**
     173             :          * The I/O command set to select.
     174             :          *
     175             :          * If the requested command set is not supported, the controller
     176             :          * initialization process will not proceed. By default, the NVM
     177             :          * command set is used.
     178             :          */
     179             :         enum spdk_nvme_cc_css command_set;
     180             : 
     181             :         /**
     182             :          * Admin commands timeout in milliseconds (0 = no timeout).
     183             :          *
     184             :          * The timeout value is used for admin commands submitted internally
     185             :          * by the nvme driver during initialization, before the user is able
     186             :          * to call spdk_nvme_ctrlr_register_timeout_callback(). By default,
     187             :          * this is set to 120 seconds, users can change it in the probing
     188             :          * callback.
     189             :          */
     190             :         uint32_t admin_timeout_ms;
     191             : 
     192             :         /**
     193             :          * It is used for TCP transport.
     194             :          *
     195             :          * Set to true, means having header digest for the header in the NVMe/TCP PDU
     196             :          */
     197             :         bool header_digest;
     198             : 
     199             :         /**
     200             :          * It is used for TCP transport.
     201             :          *
     202             :          * Set to true, means having data digest for the data in the NVMe/TCP PDU
     203             :          */
     204             :         bool data_digest;
     205             : 
     206             :         /**
     207             :          * Disable logging of requests that are completed with error status.
     208             :          *
     209             :          * Defaults to 'false' (errors are logged).
     210             :          */
     211             :         bool disable_error_logging;
     212             : 
     213             :         /**
     214             :          * It is used for both RDMA & TCP transport
     215             :          * Specify the transport ACK timeout. The value should be in range 0-31 where 0 means
     216             :          * use driver-specific default value.
     217             :          * RDMA: The value is applied to each qpair
     218             :          * and affects the time that qpair waits for transport layer acknowledgement
     219             :          * until it retransmits a packet. The value should be chosen empirically
     220             :          * to meet the needs of a particular application. A low value means less time
     221             :          * the qpair waits for ACK which can increase the number of retransmissions.
     222             :          * A large value can increase the time the connection is closed.
     223             :          * The value of ACK timeout is calculated according to the formula
     224             :          * 4.096 * 2^(transport_ack_timeout) usec.
     225             :          * TCP: The value is applied to each qpair
     226             :          * and affects the time that qpair waits for transport layer acknowledgement
     227             :          * until connection is closed forcefully.
     228             :          * The value of ACK timeout is calculated according to the formula
     229             :          * 2^(transport_ack_timeout) msec.
     230             :          */
     231             :         uint8_t transport_ack_timeout;
     232             : 
     233             :         /**
     234             :          * The queue depth of NVMe Admin queue.
     235             :          */
     236             :         uint16_t admin_queue_size;
     237             : 
     238             :         /* Hole at bytes 586-591. */
     239             :         uint8_t reserved586[6];
     240             : 
     241             :         /**
     242             :          * The size of spdk_nvme_ctrlr_opts according to the caller of this library is used for ABI
     243             :          * compatibility.  The library uses this field to know how many fields in this
     244             :          * structure are valid. And the library will populate any remaining fields with default values.
     245             :          */
     246             :         size_t opts_size;
     247             : 
     248             :         /**
     249             :          * The amount of time to spend before timing out during fabric connect on qpairs associated with
     250             :          * this controller in microseconds.
     251             :          */
     252             :         uint64_t fabrics_connect_timeout_us;
     253             : 
     254             :         /**
     255             :          * Disable reading ANA log page. The upper layer should reading ANA log page instead
     256             :          * if set to true.
     257             :          *
     258             :          * Default is `false` (ANA log page is read).
     259             :          */
     260             :         bool disable_read_ana_log_page;
     261             : 
     262             :         /* Hole at bytes 610-616. */
     263             :         uint8_t reserved610[7];
     264             : 
     265             :         /**
     266             :          * Disable reading CHANGED_NS_LIST log page in response to an NS_ATTR_CHANGED AEN
     267             :          * The upper layer should reading CHANGED_NS_LIST log page instead if set to true.
     268             :          *
     269             :          * Default is `false` (CHANGED_NS_LIST log page is read).
     270             :          */
     271             :         uint8_t disable_read_changed_ns_list_log_page;
     272             : 
     273             :         /* Hole at bytes 617-816. */
     274             :         uint8_t reserved617[200];
     275             : 
     276             :         /**
     277             :          * It is used for RDMA transport.
     278             :          *
     279             :          * Set the IP protocol type of service value for RDMA transport. Default is 0, which means that the TOS will not be set.
     280             :          */
     281             :         uint8_t transport_tos;
     282             : 
     283             :         /**
     284             :          * Pre-shared key for NVMe/TCP's TLS connection.
     285             :          */
     286             :         struct spdk_key *tls_psk;
     287             : 
     288             :         /**
     289             :          * In-band authentication DH-HMAC-CHAP host key.
     290             :          */
     291             :         struct spdk_key *dhchap_key;
     292             : 
     293             :         /**
     294             :          * In-band authentication DH-HMAC-CHAP controller key.
     295             :          */
     296             :         struct spdk_key *dhchap_ctrlr_key;
     297             : 
     298             :         /**
     299             :          * Allowed digests in in-band authentication.  Each bit corresponds to one of the
     300             :          * spdk_nvmf_dhchap_hash values.
     301             :          */
     302             :         uint32_t dhchap_digests;
     303             : 
     304             :         /**
     305             :          * Allowed Diffie-Hellman groups in in-band authentication.  Each bit corresponds to one of
     306             :          * the spdk_nvmf_dhchap_dhgroup values.
     307             :          */
     308             :         uint32_t dhchap_dhgroups;
     309             : };
     310             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_ctrlr_opts) == 856, "Incorrect size");
     311             : 
     312             : /**
     313             :  * NVMe acceleration operation callback.
     314             :  *
     315             :  * \param cb_arg The user provided arg which is passed to the corresponding accelerated function call
     316             :  * defined in struct spdk_nvme_accel_fn_table.
     317             :  * \param status 0 if it completed successfully, or negative errno if it failed.
     318             :  */
     319             : typedef void (*spdk_nvme_accel_completion_cb)(void *cb_arg, int status);
     320             : 
     321             : /**
     322             :  * Completion callback for a single operation in a sequence.
     323             :  *
     324             :  * \param cb_arg Argument provided by the user when appending an operation to a sequence.
     325             :  */
     326             : typedef void (*spdk_nvme_accel_step_cb)(void *cb_arg);
     327             : 
     328             : /**
     329             :  * Function table for the NVMe accelerator device.
     330             :  *
     331             :  * This table provides a set of APIs to allow user to leverage
     332             :  * accelerator functions.
     333             :  */
     334             : struct spdk_nvme_accel_fn_table {
     335             :         /**
     336             :          * The size of spdk_nvme_accel_fun_table according to the caller of
     337             :          * this library is used for ABI compatibility. The library uses this
     338             :          * field to know how many fields in this structure are valid.
     339             :          * And the library will populate any remaining fields with default values.
     340             :          * Newly added fields should be put at the end of the struct.
     341             :          */
     342             :         size_t table_size;
     343             : 
     344             :         /** The accelerated crc32c function. */
     345             :         void (*submit_accel_crc32c)(void *ctx, uint32_t *dst, struct iovec *iov,
     346             :                                     uint32_t iov_cnt, uint32_t seed, spdk_nvme_accel_completion_cb cb_fn, void *cb_arg);
     347             : 
     348             :         /** Finish an accel sequence */
     349             :         void (*finish_sequence)(void *seq, spdk_nvme_accel_completion_cb cb_fn, void *cb_arg);
     350             : 
     351             :         /** Reverse an accel sequence */
     352             :         void (*reverse_sequence)(void *seq);
     353             : 
     354             :         /** Abort an accel sequence */
     355             :         void (*abort_sequence)(void *seq);
     356             : 
     357             :         /** Append a crc32c operation to a sequence */
     358             :         int (*append_crc32c)(void *ctx, void **seq, uint32_t *dst, struct iovec *iovs, uint32_t iovcnt,
     359             :                              struct spdk_memory_domain *memory_domain, void *domain_ctx,
     360             :                              uint32_t seed, spdk_nvme_accel_step_cb cb_fn, void *cb_arg);
     361             : 
     362             :         /** Append a copy operation to a sequence */
     363             :         int (*append_copy)(void *ctx, void **seq, struct iovec *dst_iovs, uint32_t dst_iovcnt,
     364             :                            struct spdk_memory_domain *dst_domain, void *dst_domain_ctx,
     365             :                            struct iovec *src_iovs, uint32_t src_iovcnt,
     366             :                            struct spdk_memory_domain *src_domain, void *src_domain_ctx,
     367             :                            spdk_nvme_accel_step_cb cb_fn, void *cb_arg);
     368             : };
     369             : 
     370             : /**
     371             :  * Indicate whether a ctrlr handle is associated with a Discovery controller.
     372             :  *
     373             :  * \param ctrlr Opaque handle to NVMe controller.
     374             :  *
     375             :  * \return true if a discovery controller, else false.
     376             :  */
     377             : bool spdk_nvme_ctrlr_is_discovery(struct spdk_nvme_ctrlr *ctrlr);
     378             : 
     379             : /**
     380             :  * Indicate whether a ctrlr handle is associated with a fabrics controller.
     381             :  *
     382             :  * \param ctrlr Opaque handle to NVMe controller.
     383             :  *
     384             :  * \return true if a fabrics controller, else false.
     385             :  */
     386             : bool spdk_nvme_ctrlr_is_fabrics(struct spdk_nvme_ctrlr *ctrlr);
     387             : 
     388             : /**
     389             :  * Get the default options for the creation of a specific NVMe controller.
     390             :  *
     391             :  * \param[out] opts Will be filled with the default option.
     392             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts).
     393             :  */
     394             : void spdk_nvme_ctrlr_get_default_ctrlr_opts(struct spdk_nvme_ctrlr_opts *opts,
     395             :                 size_t opts_size);
     396             : 
     397             : /*
     398             :  * Get the options in use for a given controller.
     399             :  *
     400             :  * \param ctrlr Opaque handle to NVMe controller.
     401             :  */
     402             : const struct spdk_nvme_ctrlr_opts *spdk_nvme_ctrlr_get_opts(struct spdk_nvme_ctrlr *ctrlr);
     403             : 
     404             : /**
     405             :  * Reason for qpair disconnect at the transport layer.
     406             :  *
     407             :  * NONE implies that the qpair is still connected while UNKNOWN means that the
     408             :  * qpair is disconnected, but the cause was not apparent.
     409             :  */
     410             : enum spdk_nvme_qp_failure_reason {
     411             :         SPDK_NVME_QPAIR_FAILURE_NONE = 0,
     412             :         SPDK_NVME_QPAIR_FAILURE_LOCAL,
     413             :         SPDK_NVME_QPAIR_FAILURE_REMOTE,
     414             :         SPDK_NVME_QPAIR_FAILURE_UNKNOWN,
     415             :         SPDK_NVME_QPAIR_FAILURE_RESET,
     416             : };
     417             : 
     418             : typedef enum spdk_nvme_qp_failure_reason spdk_nvme_qp_failure_reason;
     419             : 
     420             : /**
     421             :  * NVMe library transports
     422             :  *
     423             :  * NOTE: These are mapped directly to the NVMe over Fabrics TRTYPE values, except for PCIe,
     424             :  * which is a special case since NVMe over Fabrics does not define a TRTYPE for local PCIe.
     425             :  *
     426             :  * Currently, this uses 256 for PCIe which is intentionally outside of the 8-bit range of TRTYPE.
     427             :  * If the NVMe-oF specification ever defines a PCIe TRTYPE, this should be updated.
     428             :  */
     429             : enum spdk_nvme_transport_type {
     430             :         /**
     431             :          * PCIe Transport (locally attached devices)
     432             :          */
     433             :         SPDK_NVME_TRANSPORT_PCIE = 256,
     434             : 
     435             :         /**
     436             :          * RDMA Transport (RoCE, iWARP, etc.)
     437             :          */
     438             :         SPDK_NVME_TRANSPORT_RDMA = SPDK_NVMF_TRTYPE_RDMA,
     439             : 
     440             :         /**
     441             :          * Fibre Channel (FC) Transport
     442             :          */
     443             :         SPDK_NVME_TRANSPORT_FC = SPDK_NVMF_TRTYPE_FC,
     444             : 
     445             :         /**
     446             :          * TCP Transport
     447             :          */
     448             :         SPDK_NVME_TRANSPORT_TCP = SPDK_NVMF_TRTYPE_TCP,
     449             : 
     450             :         /**
     451             :          * Custom VFIO User Transport (Not spec defined)
     452             :          */
     453             :         SPDK_NVME_TRANSPORT_VFIOUSER = 1024,
     454             : 
     455             :         /**
     456             :          * Custom Transport (Not spec defined)
     457             :          */
     458             :         SPDK_NVME_TRANSPORT_CUSTOM = 4096,
     459             : 
     460             :         /**
     461             :          * Custom Fabric Transport (Not spec defined)
     462             :          */
     463             :         SPDK_NVME_TRANSPORT_CUSTOM_FABRICS = 4097,
     464             : };
     465             : 
     466          30 : static inline bool spdk_nvme_trtype_is_fabrics(enum spdk_nvme_transport_type trtype)
     467             : {
     468             :         /* We always define non-fabrics trtypes outside of the 8-bit range
     469             :          * of NVMe-oF trtype.
     470             :          */
     471          30 :         return trtype <= UINT8_MAX || trtype == SPDK_NVME_TRANSPORT_CUSTOM_FABRICS;
     472             : }
     473             : 
     474             : /* typedef added for coding style reasons */
     475             : typedef enum spdk_nvme_transport_type spdk_nvme_transport_type_t;
     476             : 
     477             : /**
     478             :  * NVMe transport identifier.
     479             :  *
     480             :  * This identifies a unique endpoint on an NVMe fabric.
     481             :  *
     482             :  * A string representation of a transport ID may be converted to this type using
     483             :  * spdk_nvme_transport_id_parse().
     484             :  */
     485             : struct spdk_nvme_transport_id {
     486             :         /**
     487             :          * NVMe transport string.
     488             :          */
     489             :         char trstring[SPDK_NVMF_TRSTRING_MAX_LEN + 1];
     490             : 
     491             :         /**
     492             :          * NVMe transport type.
     493             :          */
     494             :         enum spdk_nvme_transport_type trtype;
     495             : 
     496             :         /**
     497             :          * Address family of the transport address.
     498             :          *
     499             :          * For PCIe, this value is ignored.
     500             :          */
     501             :         enum spdk_nvmf_adrfam adrfam;
     502             : 
     503             :         /**
     504             :          * Transport address of the NVMe-oF endpoint. For transports which use IP
     505             :          * addressing (e.g. RDMA), this should be an IP address. For PCIe, this
     506             :          * can either be a zero length string (the whole bus) or a PCI address
     507             :          * in the format DDDD:BB:DD.FF or DDDD.BB.DD.FF. For FC the string is
     508             :          * formatted as: nn-0xWWNN:pn-0xWWPN” where WWNN is the Node_Name of the
     509             :          * target NVMe_Port and WWPN is the N_Port_Name of the target NVMe_Port.
     510             :          */
     511             :         char traddr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
     512             : 
     513             :         /**
     514             :          * Transport service id of the NVMe-oF endpoint.  For transports which use
     515             :          * IP addressing (e.g. RDMA), this field should be the port number. For PCIe,
     516             :          * and FC this is always a zero length string.
     517             :          */
     518             :         char trsvcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
     519             : 
     520             :         /**
     521             :          * Subsystem NQN of the NVMe over Fabrics endpoint. May be a zero length string.
     522             :          */
     523             :         char subnqn[SPDK_NVMF_NQN_MAX_LEN + 1];
     524             : 
     525             :         /**
     526             :          * The Transport connection priority of the NVMe-oF endpoint. Currently this is
     527             :          * only supported by posix based sock implementation on Kernel TCP stack. More
     528             :          * information of this field can be found from the socket(7) man page.
     529             :          */
     530             :         int priority;
     531             : };
     532             : 
     533             : /**
     534             :  * NVMe host identifier
     535             :  *
     536             :  * Used for defining the host identity for an NVMe-oF connection.
     537             :  *
     538             :  * In terms of configuration, this object can be considered a subtype of TransportID
     539             :  * Please see etc/spdk/nvmf.conf.in for more details.
     540             :  *
     541             :  * A string representation of this type may be converted to this type using
     542             :  * spdk_nvme_host_id_parse().
     543             :  */
     544             : struct spdk_nvme_host_id {
     545             :         /**
     546             :          * Transport address to be used by the host when connecting to the NVMe-oF endpoint.
     547             :          * May be an IP address or a zero length string for transports which
     548             :          * use IP addressing (e.g. RDMA).
     549             :          * For PCIe and FC this is always a zero length string.
     550             :          */
     551             :         char hostaddr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
     552             : 
     553             :         /**
     554             :          * Transport service ID used by the host when connecting to the NVMe.
     555             :          * May be a port number or a zero length string for transports which
     556             :          * use IP addressing (e.g. RDMA).
     557             :          * For PCIe and FC this is always a zero length string.
     558             :          */
     559             :         char hostsvcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
     560             : };
     561             : 
     562             : struct spdk_nvme_rdma_device_stat {
     563             :         const char *name;
     564             :         uint64_t polls;
     565             :         uint64_t idle_polls;
     566             :         uint64_t completions;
     567             :         uint64_t queued_requests;
     568             :         uint64_t total_send_wrs;
     569             :         uint64_t send_doorbell_updates;
     570             :         uint64_t total_recv_wrs;
     571             :         uint64_t recv_doorbell_updates;
     572             : };
     573             : 
     574             : struct spdk_nvme_pcie_stat {
     575             :         uint64_t polls;
     576             :         uint64_t idle_polls;
     577             :         uint64_t completions;
     578             :         uint64_t cq_mmio_doorbell_updates;
     579             :         uint64_t cq_shadow_doorbell_updates;
     580             :         uint64_t submitted_requests;
     581             :         uint64_t queued_requests;
     582             :         uint64_t sq_mmio_doorbell_updates;
     583             :         uint64_t sq_shadow_doorbell_updates;
     584             : };
     585             : 
     586             : struct spdk_nvme_tcp_stat {
     587             :         uint64_t polls;
     588             :         uint64_t idle_polls;
     589             :         uint64_t socket_completions;
     590             :         uint64_t nvme_completions;
     591             :         uint64_t submitted_requests;
     592             :         uint64_t queued_requests;
     593             : };
     594             : 
     595             : struct spdk_nvme_transport_poll_group_stat {
     596             :         spdk_nvme_transport_type_t trtype;
     597             :         union {
     598             :                 struct {
     599             :                         uint32_t num_devices;
     600             :                         struct spdk_nvme_rdma_device_stat *device_stats;
     601             :                 } rdma;
     602             :                 struct spdk_nvme_pcie_stat pcie;
     603             :                 struct spdk_nvme_tcp_stat tcp;
     604             :         };
     605             : };
     606             : 
     607             : struct spdk_nvme_poll_group_stat {
     608             :         uint32_t num_transports;
     609             :         struct spdk_nvme_transport_poll_group_stat **transport_stat;
     610             : };
     611             : 
     612             : /*
     613             :  * Controller support flags
     614             :  *
     615             :  * Used for identifying if the controller supports these flags.
     616             :  */
     617             : enum spdk_nvme_ctrlr_flags {
     618             :         SPDK_NVME_CTRLR_SGL_SUPPORTED                   = 1 << 0, /**< SGL is supported */
     619             :         SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED    = 1 << 1, /**< security send/receive is supported */
     620             :         SPDK_NVME_CTRLR_WRR_SUPPORTED                   = 1 << 2, /**< Weighted Round Robin is supported */
     621             :         SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED     = 1 << 3, /**< Compare and write fused operations supported */
     622             :         SPDK_NVME_CTRLR_SGL_REQUIRES_DWORD_ALIGNMENT    = 1 << 4, /**< Dword alignment is required for SGL */
     623             :         SPDK_NVME_CTRLR_ZONE_APPEND_SUPPORTED           = 1 << 5, /**< Zone Append is supported (within Zoned Namespaces) */
     624             :         SPDK_NVME_CTRLR_DIRECTIVES_SUPPORTED            = 1 << 6, /**< The Directives is supported */
     625             :         SPDK_NVME_CTRLR_MPTR_SGL_SUPPORTED              = 1 << 7, /**< MPTR containing SGL descriptor is supported */
     626             :         SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED        = 1 << 8, /**< Support for sending I/O requests with accel sequence */
     627             : };
     628             : 
     629             : /**
     630             :  * Structure with optional IO request parameters
     631             :  */
     632             : struct spdk_nvme_ns_cmd_ext_io_opts {
     633             :         /** size of this structure in bytes, use SPDK_SIZEOF(opts, last_member) to obtain it */
     634             :         size_t size;
     635             :         /** Memory domain which describes data payload in IO request. The controller must support
     636             :          * the corresponding memory domain type, refer to \ref spdk_nvme_ctrlr_get_memory_domains */
     637             :         struct spdk_memory_domain *memory_domain;
     638             :         /** User context to be passed to memory domain operations */
     639             :         void *memory_domain_ctx;
     640             :         /** Flags for this IO, defined in nvme_spec.h */
     641             :         uint32_t io_flags;
     642             :         /* Hole at bytes 28-31. */
     643             :         uint8_t reserved28[4];
     644             :         /** Virtual address pointer to the metadata payload, the length of metadata is specified by \ref spdk_nvme_ns_get_md_size */
     645             :         void *metadata;
     646             :         /** Application tag mask to use end-to-end protection information. */
     647             :         uint16_t apptag_mask;
     648             :         /** Application tag to use end-to-end protection information. */
     649             :         uint16_t apptag;
     650             :         /** Command dword 13 specific field. */
     651             :         uint32_t cdw13;
     652             :         /** Accel sequence (only valid if SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED is set and the
     653             :          *  qpair is part of a poll group).
     654             :          */
     655             :         void *accel_sequence;
     656             : };
     657             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_ns_cmd_ext_io_opts) == 56, "Incorrect size");
     658             : 
     659             : /**
     660             :  * Parse the string representation of a transport ID.
     661             :  *
     662             :  * \param trid Output transport ID structure (must be allocated and initialized by caller).
     663             :  * \param str Input string representation of a transport ID to parse.
     664             :  *
     665             :  * str must be a zero-terminated C string containing one or more key:value pairs
     666             :  * separated by whitespace.
     667             :  *
     668             :  * Key          | Value
     669             :  * ------------ | -----
     670             :  * trtype       | Transport type (e.g. PCIe, RDMA)
     671             :  * adrfam       | Address family (e.g. IPv4, IPv6)
     672             :  * traddr       | Transport address (e.g. 0000:04:00.0 for PCIe, 192.168.100.8 for RDMA, or WWN for FC)
     673             :  * trsvcid      | Transport service identifier (e.g. 4420)
     674             :  * subnqn       | Subsystem NQN
     675             :  *
     676             :  * Unspecified fields of trid are left unmodified, so the caller must initialize
     677             :  * trid (for example, memset() to 0) before calling this function.
     678             :  *
     679             :  * \return 0 if parsing was successful and trid is filled out, or negated errno
     680             :  * values on failure.
     681             :  */
     682             : int spdk_nvme_transport_id_parse(struct spdk_nvme_transport_id *trid, const char *str);
     683             : 
     684             : 
     685             : /**
     686             :  * Fill in the trtype and trstring fields of this trid based on a known transport type.
     687             :  *
     688             :  * \param trid The trid to fill out.
     689             :  * \param trtype The transport type to use for filling the trid fields. Only valid for
     690             :  * transport types referenced in the NVMe-oF spec.
     691             :  */
     692             : void spdk_nvme_trid_populate_transport(struct spdk_nvme_transport_id *trid,
     693             :                                        enum spdk_nvme_transport_type trtype);
     694             : 
     695             : /**
     696             :  * Parse the string representation of a host ID.
     697             :  *
     698             :  * \param hostid Output host ID structure (must be allocated and initialized by caller).
     699             :  * \param str Input string representation of a transport ID to parse (hostid is a sub-configuration).
     700             :  *
     701             :  * str must be a zero-terminated C string containing one or more key:value pairs
     702             :  * separated by whitespace.
     703             :  *
     704             :  * Key            | Value
     705             :  * -------------- | -----
     706             :  * hostaddr       | Transport address (e.g. 192.168.100.8 for RDMA)
     707             :  * hostsvcid      | Transport service identifier (e.g. 4420)
     708             :  *
     709             :  * Unspecified fields of trid are left unmodified, so the caller must initialize
     710             :  * hostid (for example, memset() to 0) before calling this function.
     711             :  *
     712             :  * This function should not be used with Fiber Channel or PCIe as these transports
     713             :  * do not require host information for connections.
     714             :  *
     715             :  * \return 0 if parsing was successful and hostid is filled out, or negated errno
     716             :  * values on failure.
     717             :  */
     718             : int spdk_nvme_host_id_parse(struct spdk_nvme_host_id *hostid, const char *str);
     719             : 
     720             : /**
     721             :  * Parse the string representation of a transport ID transport type into the trid struct.
     722             :  *
     723             :  * \param trid The trid to write to
     724             :  * \param trstring Input string representation of transport type (e.g. "PCIe", "RDMA").
     725             :  *
     726             :  * \return 0 if parsing was successful and trtype is filled out, or negated errno
     727             :  * values if the provided string was an invalid transport string.
     728             :  */
     729             : int spdk_nvme_transport_id_populate_trstring(struct spdk_nvme_transport_id *trid,
     730             :                 const char *trstring);
     731             : 
     732             : /**
     733             :  * Parse the string representation of a transport ID transport type.
     734             :  *
     735             :  * \param trtype Output transport type (allocated by caller).
     736             :  * \param str Input string representation of transport type (e.g. "PCIe", "RDMA").
     737             :  *
     738             :  * \return 0 if parsing was successful and trtype is filled out, or negated errno
     739             :  * values on failure.
     740             :  */
     741             : int spdk_nvme_transport_id_parse_trtype(enum spdk_nvme_transport_type *trtype, const char *str);
     742             : 
     743             : /**
     744             :  * Look up the string representation of a transport ID transport type.
     745             :  *
     746             :  * \param trtype Transport type to convert.
     747             :  *
     748             :  * \return static string constant describing trtype, or NULL if trtype not found.
     749             :  */
     750             : const char *spdk_nvme_transport_id_trtype_str(enum spdk_nvme_transport_type trtype);
     751             : 
     752             : /**
     753             :  * Look up the string representation of a transport ID address family.
     754             :  *
     755             :  * \param adrfam Address family to convert.
     756             :  *
     757             :  * \return static string constant describing adrfam, or NULL if adrfam not found.
     758             :  */
     759             : const char *spdk_nvme_transport_id_adrfam_str(enum spdk_nvmf_adrfam adrfam);
     760             : 
     761             : /**
     762             :  * Parse the string representation of a transport ID address family.
     763             :  *
     764             :  * \param adrfam Output address family (allocated by caller).
     765             :  * \param str Input string representation of address family (e.g. "IPv4", "IPv6").
     766             :  *
     767             :  * \return 0 if parsing was successful and adrfam is filled out, or negated errno
     768             :  * values on failure.
     769             :  */
     770             : int spdk_nvme_transport_id_parse_adrfam(enum spdk_nvmf_adrfam *adrfam, const char *str);
     771             : 
     772             : /**
     773             :  * Compare two transport IDs.
     774             :  *
     775             :  * The result of this function may be used to sort transport IDs in a consistent
     776             :  * order; however, the comparison result is not guaranteed to be consistent across
     777             :  * library versions.
     778             :  *
     779             :  * This function uses a case-insensitive comparison for string fields, but it does
     780             :  * not otherwise normalize the transport ID. It is the caller's responsibility to
     781             :  * provide the transport IDs in a consistent format.
     782             :  *
     783             :  * \param trid1 First transport ID to compare.
     784             :  * \param trid2 Second transport ID to compare.
     785             :  *
     786             :  * \return 0 if trid1 == trid2, less than 0 if trid1 < trid2, greater than 0 if
     787             :  * trid1 > trid2.
     788             :  */
     789             : int spdk_nvme_transport_id_compare(const struct spdk_nvme_transport_id *trid1,
     790             :                                    const struct spdk_nvme_transport_id *trid2);
     791             : 
     792             : /**
     793             :  * Parse the string representation of PI check settings (prchk:guard|reftag)
     794             :  *
     795             :  * \param prchk_flags Output PI check flags.
     796             :  * \param str Input string representation of PI check settings.
     797             :  *
     798             :  * \return 0 if parsing was successful and prchk_flags is set, or negated errno
     799             :  * values on failure.
     800             :  */
     801             : int spdk_nvme_prchk_flags_parse(uint32_t *prchk_flags, const char *str);
     802             : 
     803             : /**
     804             :  * Look up the string representation of PI check settings  (prchk:guard|reftag)
     805             :  *
     806             :  * \param prchk_flags PI check flags to convert.
     807             :  *
     808             :  * \return static string constant describing PI check settings. If prchk_flags is 0,
     809             :  * NULL is returned.
     810             :  */
     811             : const char *spdk_nvme_prchk_flags_str(uint32_t prchk_flags);
     812             : 
     813             : /**
     814             :  * Determine whether the NVMe library can handle a specific NVMe over Fabrics
     815             :  * transport type.
     816             :  *
     817             :  * \param trtype NVMe over Fabrics transport type to check.
     818             :  *
     819             :  * \return true if trtype is supported or false if it is not supported or if
     820             :  * SPDK_NVME_TRANSPORT_CUSTOM is supplied as trtype since it can represent multiple
     821             :  * transports.
     822             :  */
     823             : bool spdk_nvme_transport_available(enum spdk_nvme_transport_type trtype);
     824             : 
     825             : /**
     826             :  * Determine whether the NVMe library can handle a specific NVMe over Fabrics
     827             :  * transport type.
     828             :  *
     829             :  * \param transport_name Name of the NVMe over Fabrics transport type to check.
     830             :  *
     831             :  * \return true if transport_name is supported or false if it is not supported.
     832             :  */
     833             : bool spdk_nvme_transport_available_by_name(const char *transport_name);
     834             : 
     835             : /**
     836             :  * Callback for spdk_nvme_probe() enumeration.
     837             :  *
     838             :  * \param cb_ctx Opaque value passed to spdk_nvme_probe().
     839             :  * \param trid NVMe transport identifier.
     840             :  * \param opts NVMe controller initialization options. This structure will be
     841             :  * populated with the default values on entry, and the user callback may update
     842             :  * any options to request a different value. The controller may not support all
     843             :  * requested parameters, so the final values will be provided during the attach
     844             :  * callback.
     845             :  *
     846             :  * \return true to attach to this device.
     847             :  */
     848             : typedef bool (*spdk_nvme_probe_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
     849             :                                    struct spdk_nvme_ctrlr_opts *opts);
     850             : 
     851             : /**
     852             :  * Callback for spdk_nvme_attach() to report a device that has been attached to
     853             :  * the userspace NVMe driver.
     854             :  *
     855             :  * \param cb_ctx Opaque value passed to spdk_nvme_attach_cb().
     856             :  * \param trid NVMe transport identifier.
     857             :  * \param ctrlr Opaque handle to NVMe controller.
     858             :  * \param opts NVMe controller initialization options that were actually used.
     859             :  * Options may differ from the requested options from the attach call depending
     860             :  * on what the controller supports.
     861             :  */
     862             : typedef void (*spdk_nvme_attach_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
     863             :                                     struct spdk_nvme_ctrlr *ctrlr,
     864             :                                     const struct spdk_nvme_ctrlr_opts *opts);
     865             : 
     866             : /**
     867             :  * Callback for spdk_nvme_probe*_ext() to report a device that has been probed but
     868             :  * unable to attach to the userspace NVMe driver.
     869             :  *
     870             :  * \param cb_ctx Opaque value passed to spdk_nvme_probe*_ext().
     871             :  * \param trid NVMe transport identifier.
     872             :  * \param rc Negative error code that provides information about the failure.
     873             :  */
     874             : typedef void (*spdk_nvme_attach_fail_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
     875             :                 int rc);
     876             : 
     877             : /**
     878             :  * Callback for spdk_nvme_remove() to report that a device attached to the userspace
     879             :  * NVMe driver has been removed from the system.
     880             :  *
     881             :  * The controller will remain in a failed state (any new I/O submitted will fail).
     882             :  *
     883             :  * The controller must be detached from the userspace driver by calling spdk_nvme_detach()
     884             :  * once the controller is no longer in use. It is up to the library user to ensure
     885             :  * that no other threads are using the controller before calling spdk_nvme_detach().
     886             :  *
     887             :  * \param cb_ctx Opaque value passed to spdk_nvme_remove_cb().
     888             :  * \param ctrlr NVMe controller instance that was removed.
     889             :  */
     890             : typedef void (*spdk_nvme_remove_cb)(void *cb_ctx, struct spdk_nvme_ctrlr *ctrlr);
     891             : 
     892             : typedef bool (*spdk_nvme_pcie_hotplug_filter_cb)(const struct spdk_pci_addr *addr);
     893             : 
     894             : /**
     895             :  * Register the associated function to allow filtering of hot-inserted PCIe SSDs.
     896             :  *
     897             :  * If an application is using spdk_nvme_probe() to detect hot-inserted SSDs,
     898             :  * this function may be used to register a function to filter those SSDs.
     899             :  * If the filter function returns true, the nvme library will notify the SPDK
     900             :  * env layer to allow probing of the device.
     901             :  *
     902             :  * Registering a filter function is optional.  If none is registered, the nvme
     903             :  * library will allow probing of all hot-inserted SSDs.
     904             :  *
     905             :  * \param filter_cb Filter function callback routine
     906             :  */
     907             : void
     908             : spdk_nvme_pcie_set_hotplug_filter(spdk_nvme_pcie_hotplug_filter_cb filter_cb);
     909             : 
     910             : /**
     911             :  * Enumerate the bus indicated by the transport ID and attach the userspace NVMe
     912             :  * driver to each device found if desired.
     913             :  *
     914             :  * This function is not thread safe and should only be called from one thread at
     915             :  * a time while no other threads are actively using any NVMe devices.
     916             :  *
     917             :  * If called from a secondary process, only devices that have been attached to
     918             :  * the userspace driver in the primary process will be probed.
     919             :  *
     920             :  * If called more than once, only devices that are not already attached to the
     921             :  * SPDK NVMe driver will be reported.
     922             :  *
     923             :  * To stop using the the controller and release its associated resources,
     924             :  * call spdk_nvme_detach() with the spdk_nvme_ctrlr instance from the attach_cb()
     925             :  * function.
     926             :  *
     927             :  * \param trid The transport ID indicating which bus to enumerate. If the trtype
     928             :  * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
     929             :  * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
     930             :  * NVMe-oF discovery service.
     931             :  * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
     932             :  * the callbacks.
     933             :  * \param probe_cb will be called once per NVMe device found in the system.
     934             :  * \param attach_cb will be called for devices for which probe_cb returned true
     935             :  * once that NVMe controller has been attached to the userspace driver.
     936             :  * \param remove_cb will be called for devices that were attached in a previous
     937             :  * spdk_nvme_probe() call but are no longer attached to the system. Optional;
     938             :  * specify NULL if removal notices are not desired.
     939             :  *
     940             :  * \return 0 on success, -1 on failure.
     941             :  */
     942             : int spdk_nvme_probe(const struct spdk_nvme_transport_id *trid,
     943             :                     void *cb_ctx,
     944             :                     spdk_nvme_probe_cb probe_cb,
     945             :                     spdk_nvme_attach_cb attach_cb,
     946             :                     spdk_nvme_remove_cb remove_cb);
     947             : 
     948             : /**
     949             :  * Enumerate the bus indicated by the transport ID and attach the userspace NVMe
     950             :  * driver to each device found if desired.
     951             :  *
     952             :  * This works just the same as spdk_nvme_probe(), except that it calls attach_fail_cb
     953             :  * for devices that are probed but unabled to attach.
     954             :  *
     955             :  * \param trid The transport ID indicating which bus to enumerate. If the trtype
     956             :  * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
     957             :  * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
     958             :  * NVMe-oF discovery service.
     959             :  * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
     960             :  * the callbacks.
     961             :  * \param probe_cb will be called once per NVMe device found in the system.
     962             :  * \param attach_cb will be called for devices for which probe_cb returned true
     963             :  * once that NVMe controller has been attached to the userspace driver.
     964             :  * \param attach_fail_cb will be called for devices which probe_cb returned true
     965             :  * but failed to attach to the userspace driver.
     966             :  * \param remove_cb will be called for devices that were attached in a previous
     967             :  * spdk_nvme_probe() call but are no longer attached to the system. Optional;
     968             :  * specify NULL if removal notices are not desired.
     969             :  *
     970             :  * \return 0 on success, -1 on failure.
     971             :  */
     972             : int spdk_nvme_probe_ext(const struct spdk_nvme_transport_id *trid,
     973             :                         void *cb_ctx,
     974             :                         spdk_nvme_probe_cb probe_cb,
     975             :                         spdk_nvme_attach_cb attach_cb,
     976             :                         spdk_nvme_attach_fail_cb attach_fail_cb,
     977             :                         spdk_nvme_remove_cb remove_cb);
     978             : 
     979             : /**
     980             :  * Connect the NVMe driver to the device located at the given transport ID.
     981             :  *
     982             :  * This function is not thread safe and should only be called from one thread at
     983             :  * a time while no other threads are actively using this NVMe device.
     984             :  *
     985             :  * If called from a secondary process, only the device that has been attached to
     986             :  * the userspace driver in the primary process will be connected.
     987             :  *
     988             :  * If connecting to multiple controllers, it is suggested to use spdk_nvme_probe()
     989             :  * and filter the requested controllers with the probe callback. For PCIe controllers,
     990             :  * spdk_nvme_probe() will be more efficient since the controller resets will happen
     991             :  * in parallel.
     992             :  *
     993             :  * To stop using the the controller and release its associated resources, call
     994             :  * spdk_nvme_detach() with the spdk_nvme_ctrlr instance returned by this function.
     995             :  *
     996             :  * \param trid The transport ID indicating which device to connect. If the trtype
     997             :  * is PCIe, this will connect the local PCIe bus. If the trtype is fabrics
     998             :  * (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an NVMe-oF
     999             :  * service.
    1000             :  * \param opts NVMe controller initialization options. Default values will be used
    1001             :  * if the user does not specify the options. The controller may not support all
    1002             :  * requested parameters.
    1003             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts), or 0 if
    1004             :  * opts is NULL.
    1005             :  *
    1006             :  * \return pointer to the connected NVMe controller or NULL if there is any failure.
    1007             :  *
    1008             :  */
    1009             : struct spdk_nvme_ctrlr *spdk_nvme_connect(const struct spdk_nvme_transport_id *trid,
    1010             :                 const struct spdk_nvme_ctrlr_opts *opts,
    1011             :                 size_t opts_size);
    1012             : 
    1013             : struct spdk_nvme_probe_ctx;
    1014             : 
    1015             : /**
    1016             :  * Connect the NVMe driver to the device located at the given transport ID.
    1017             :  *
    1018             :  * The function will return a probe context on success, controller associates with
    1019             :  * the context is not ready for use, user must call spdk_nvme_probe_poll_async()
    1020             :  * until spdk_nvme_probe_poll_async() returns 0.
    1021             :  *
    1022             :  * \param trid The transport ID indicating which device to connect. If the trtype
    1023             :  * is PCIe, this will connect the local PCIe bus. If the trtype is fabrics
    1024             :  * (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an NVMe-oF
    1025             :  * service.
    1026             :  * \param opts NVMe controller initialization options. Default values will be used
    1027             :  * if the user does not specify the options. The controller may not support all
    1028             :  * requested parameters.
    1029             :  * \param attach_cb will be called once the NVMe controller has been attached
    1030             :  * to the userspace driver.
    1031             :  *
    1032             :  * \return probe context on success, NULL on failure.
    1033             :  *
    1034             :  */
    1035             : struct spdk_nvme_probe_ctx *spdk_nvme_connect_async(const struct spdk_nvme_transport_id *trid,
    1036             :                 const struct spdk_nvme_ctrlr_opts *opts,
    1037             :                 spdk_nvme_attach_cb attach_cb);
    1038             : 
    1039             : /**
    1040             :  * Probe and add controllers to the probe context list.
    1041             :  *
    1042             :  * Users must call spdk_nvme_probe_poll_async() to initialize
    1043             :  * controllers in the probe context list to the READY state.
    1044             :  *
    1045             :  * \param trid The transport ID indicating which bus to enumerate. If the trtype
    1046             :  * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
    1047             :  * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
    1048             :  * NVMe-oF discovery service.
    1049             :  * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
    1050             :  * the callbacks.
    1051             :  * \param probe_cb will be called once per NVMe device found in the system.
    1052             :  * \param attach_cb will be called for devices for which probe_cb returned true
    1053             :  * once that NVMe controller has been attached to the userspace driver.
    1054             :  * \param remove_cb will be called for devices that were attached in a previous
    1055             :  * spdk_nvme_probe() call but are no longer attached to the system. Optional;
    1056             :  * specify NULL if removal notices are not desired.
    1057             :  *
    1058             :  * \return probe context on success, NULL on failure.
    1059             :  */
    1060             : struct spdk_nvme_probe_ctx *spdk_nvme_probe_async(const struct spdk_nvme_transport_id *trid,
    1061             :                 void *cb_ctx,
    1062             :                 spdk_nvme_probe_cb probe_cb,
    1063             :                 spdk_nvme_attach_cb attach_cb,
    1064             :                 spdk_nvme_remove_cb remove_cb);
    1065             : 
    1066             : /**
    1067             :  * Probe and add controllers to the probe context list.
    1068             :  *
    1069             :  * Users must call spdk_nvme_probe_poll_async() to initialize
    1070             :  * controllers in the probe context list to the READY state.
    1071             :  *
    1072             :  * This works just the same as spdk_nvme_probe_async(), except that it calls
    1073             :  * attach_fail_cb for devices that are probed but unabled to attach.
    1074             :  *
    1075             :  * \param trid The transport ID indicating which bus to enumerate. If the trtype
    1076             :  * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
    1077             :  * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
    1078             :  * NVMe-oF discovery service.
    1079             :  * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
    1080             :  * the callbacks.
    1081             :  * \param probe_cb will be called once per NVMe device found in the system.
    1082             :  * \param attach_cb will be called for devices for which probe_cb returned true
    1083             :  * once that NVMe controller has been attached to the userspace driver.
    1084             :  * \param attach_fail_cb will be called for devices which probe_cb returned true
    1085             :  * but failed to attach to the userspace driver.
    1086             :  * \param remove_cb will be called for devices that were attached in a previous
    1087             :  * spdk_nvme_probe() call but are no longer attached to the system. Optional;
    1088             :  * specify NULL if removal notices are not desired.
    1089             :  *
    1090             :  * \return probe context on success, NULL on failure.
    1091             :  */
    1092             : struct spdk_nvme_probe_ctx *spdk_nvme_probe_async_ext(const struct spdk_nvme_transport_id *trid,
    1093             :                 void *cb_ctx,
    1094             :                 spdk_nvme_probe_cb probe_cb,
    1095             :                 spdk_nvme_attach_cb attach_cb,
    1096             :                 spdk_nvme_attach_fail_cb attach_fail_cb,
    1097             :                 spdk_nvme_remove_cb remove_cb);
    1098             : 
    1099             : /**
    1100             :  * Proceed with attaching controllers associated with the probe context.
    1101             :  *
    1102             :  * The probe context is one returned from a previous call to
    1103             :  * spdk_nvme_probe_async().  Users must call this function on the
    1104             :  * probe context until it returns 0.
    1105             :  *
    1106             :  * If any controllers fail to attach, there is no explicit notification.
    1107             :  * Users can detect attachment failure by comparing attach_cb invocations
    1108             :  * with the number of times where the user returned true for the
    1109             :  * probe_cb.
    1110             :  *
    1111             :  * \param probe_ctx Context used to track probe actions.
    1112             :  *
    1113             :  * \return 0 if all probe operations are complete; the probe_ctx
    1114             :  * is also freed and no longer valid.
    1115             :  * \return -EAGAIN if there are still pending probe operations; user must call
    1116             :  * spdk_nvme_probe_poll_async again to continue progress.
    1117             :  */
    1118             : int spdk_nvme_probe_poll_async(struct spdk_nvme_probe_ctx *probe_ctx);
    1119             : 
    1120             : /**
    1121             :  * Detach specified device returned by spdk_nvme_probe()'s attach_cb from the
    1122             :  * NVMe driver.
    1123             :  *
    1124             :  * On success, the spdk_nvme_ctrlr handle is no longer valid.
    1125             :  *
    1126             :  * This function should be called from a single thread while no other threads
    1127             :  * are actively using the NVMe device.
    1128             :  *
    1129             :  * \param ctrlr Opaque handle to NVMe controller.
    1130             :  *
    1131             :  * \return 0 on success, -1 on failure.
    1132             :  */
    1133             : int spdk_nvme_detach(struct spdk_nvme_ctrlr *ctrlr);
    1134             : 
    1135             : struct spdk_nvme_detach_ctx;
    1136             : 
    1137             : /**
    1138             :  * Allocate a context to track detachment of multiple controllers if this call is the
    1139             :  * first successful start of detachment in a sequence, or use the passed context otherwise.
    1140             :  *
    1141             :  * Then, start detaching the specified device returned by spdk_nvme_probe()'s attach_cb
    1142             :  * from the NVMe driver, and append this detachment to the context.
    1143             :  *
    1144             :  * User must call spdk_nvme_detach_poll_async() to complete the detachment.
    1145             :  *
    1146             :  * If the context is not allocated before this call, and if the specified device is detached
    1147             :  * locally from the caller process but any other process still attaches it or failed to be
    1148             :  * detached, context is not allocated.
    1149             :  *
    1150             :  * This function should be called from a single thread while no other threads are
    1151             :  * actively using the NVMe device.
    1152             :  *
    1153             :  * \param ctrlr Opaque handle to NVMe controller.
    1154             :  * \param detach_ctx Reference to the context in a sequence. An new context is allocated
    1155             :  * if this call is the first successful start of detachment in a sequence, or use the
    1156             :  * passed context.
    1157             :  */
    1158             : int spdk_nvme_detach_async(struct spdk_nvme_ctrlr *ctrlr,
    1159             :                            struct spdk_nvme_detach_ctx **detach_ctx);
    1160             : 
    1161             : /**
    1162             :  * Poll detachment of multiple controllers until they complete.
    1163             :  *
    1164             :  * User must call this function until it returns 0.
    1165             :  *
    1166             :  * \param detach_ctx Context to track the detachment.
    1167             :  *
    1168             :  * \return 0 if all detachments complete; the context is also freed and no longer valid.
    1169             :  * \return -EAGAIN if any detachment is still in progress; users must call
    1170             :  * spdk_nvme_detach_poll_async() again to continue progress.
    1171             :  */
    1172             : int spdk_nvme_detach_poll_async(struct spdk_nvme_detach_ctx *detach_ctx);
    1173             : 
    1174             : /**
    1175             :  * Continue calling spdk_nvme_detach_poll_async() internally until it returns 0.
    1176             :  *
    1177             :  * \param detach_ctx Context to track the detachment.
    1178             :  */
    1179             : void spdk_nvme_detach_poll(struct spdk_nvme_detach_ctx *detach_ctx);
    1180             : 
    1181             : /**
    1182             :  * Scan attached controllers for events.
    1183             :  *
    1184             :  * This function lets user act on events such as hot-remove without a need to
    1185             :  * enable hotplug explicitly. Only attached devices will be checked.
    1186             :  *
    1187             :  * \param trid Transport ID.
    1188             :  *
    1189             :  * \returns 0 on success, negative on failure.
    1190             :  */
    1191             : int spdk_nvme_scan_attached(const struct spdk_nvme_transport_id *trid);
    1192             : 
    1193             : /**
    1194             :  * Update the transport ID for a given controller.
    1195             :  *
    1196             :  * This function allows the user to set a new trid for a controller only if the
    1197             :  * controller is failed. The controller's failed state can be obtained from
    1198             :  * spdk_nvme_ctrlr_is_failed(). The controller can also be forced to the failed
    1199             :  * state using spdk_nvme_ctrlr_fail().
    1200             :  *
    1201             :  * This function also requires that the transport type and subnqn of the new trid
    1202             :  * be the same as the old trid.
    1203             :  *
    1204             :  * \param ctrlr Opaque handle to an NVMe controller.
    1205             :  * \param trid The new transport ID.
    1206             :  *
    1207             :  * \return 0 on success, -EINVAL if the trid is invalid,
    1208             :  * -EPERM if the ctrlr is not failed.
    1209             :  */
    1210             : int spdk_nvme_ctrlr_set_trid(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_transport_id *trid);
    1211             : 
    1212             : /**
    1213             :  * Set the remove callback and context to be invoked if the controller is removed.
    1214             :  *
    1215             :  * This will override any remove_cb and/or ctx specified when the controller was
    1216             :  * probed.
    1217             :  *
    1218             :  * This function may only be called from the primary process.  This function has
    1219             :  * no effect if called from a secondary process.
    1220             :  *
    1221             :  * \param ctrlr Opaque handle to an NVMe controller.
    1222             :  * \param remove_cb remove callback
    1223             :  * \param remove_ctx remove callback context
    1224             :  */
    1225             : void spdk_nvme_ctrlr_set_remove_cb(struct spdk_nvme_ctrlr *ctrlr,
    1226             :                                    spdk_nvme_remove_cb remove_cb, void *remove_ctx);
    1227             : 
    1228             : struct spdk_nvme_ctrlr_key_opts {
    1229             :         /** Size of this structure */
    1230             :         size_t size;
    1231             :         /** DH-HMAC-CHAP host key */
    1232             :         struct spdk_key *dhchap_key;
    1233             :         /** DH-HMAC-CHAP controller key */
    1234             :         struct spdk_key *dhchap_ctrlr_key;
    1235             : };
    1236             : 
    1237             : /**
    1238             :  * Set keys for a given NVMe controller.  These keys will override the keys specified in
    1239             :  * `spdk_nvme_ctrlr_opts` when attaching the controller and will be used from now on to authenticate
    1240             :  * all qpairs associated with this controller.
    1241             :  *
    1242             :  * This function only sets the keys, it doesn't force existing qpairs to use them.  To do that,
    1243             :  * users need to call `spdk_nvme_ctrlr_authenticate()` to authenticate the admin queue and
    1244             :  * `spdk_nvme_qpair_authenticate()` to authenticate IO queues.
    1245             :  *
    1246             :  * \param ctrlr NVMe controller.
    1247             :  * \param opts Key options.
    1248             :  *
    1249             :  * \return 0 on success, negative errno on failure.
    1250             :  */
    1251             : int spdk_nvme_ctrlr_set_keys(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_ctrlr_key_opts *opts);
    1252             : 
    1253             : /**
    1254             :  * Perform a full hardware reset of the NVMe controller.
    1255             :  *
    1256             :  * This function should be called from a single thread while no other threads
    1257             :  * are actively using the NVMe device.
    1258             :  *
    1259             :  * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
    1260             :  * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
    1261             :  * may be invalidated by calling this function. The number of namespaces as returned
    1262             :  * by spdk_nvme_ctrlr_get_num_ns() may also change.
    1263             :  *
    1264             :  * \param ctrlr Opaque handle to NVMe controller.
    1265             :  *
    1266             :  * \return 0 on success, -1 on failure.
    1267             :  */
    1268             : int spdk_nvme_ctrlr_reset(struct spdk_nvme_ctrlr *ctrlr);
    1269             : 
    1270             : /**
    1271             :  * Disconnect the given NVMe controller.
    1272             :  *
    1273             :  * This function is used as the first operation of a full reset sequence of the given NVMe
    1274             :  * controller. The NVMe controller is ready to reconnect after completing this function.
    1275             :  *
    1276             :  * \param ctrlr Opaque handle to NVMe controller.
    1277             :  *
    1278             :  * \return 0 on success, -EBUSY if controller is already resetting, or -ENXIO if controller
    1279             :  * has been removed.
    1280             :  */
    1281             : int spdk_nvme_ctrlr_disconnect(struct spdk_nvme_ctrlr *ctrlr);
    1282             : 
    1283             : /**
    1284             :  * Start re-enabling the given NVMe controller in a full reset sequence
    1285             :  *
    1286             :  * \param ctrlr Opaque handle to NVMe controller.
    1287             :  */
    1288             : void spdk_nvme_ctrlr_reconnect_async(struct spdk_nvme_ctrlr *ctrlr);
    1289             : 
    1290             : /**
    1291             :  * Proceed with re-enabling the given NVMe controller.
    1292             :  *
    1293             :  * Users must call this function in a full reset sequence until it returns a value other
    1294             :  * than -EAGAIN.
    1295             :  *
    1296             :  * \return 0 if the given NVMe controller is enabled, or -EBUSY if there are still
    1297             :  * pending operations to enable it.
    1298             :  */
    1299             : int spdk_nvme_ctrlr_reconnect_poll_async(struct spdk_nvme_ctrlr *ctrlr);
    1300             : 
    1301             : /**
    1302             :  * Perform a NVMe subsystem reset.
    1303             :  *
    1304             :  * This function should be called from a single thread while no other threads
    1305             :  * are actively using the NVMe device.
    1306             :  * A subsystem reset is typically seen by the OS as a hot remove, followed by a
    1307             :  * hot add event.
    1308             :  *
    1309             :  * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
    1310             :  * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
    1311             :  * may be invalidated by calling this function. The number of namespaces as returned
    1312             :  * by spdk_nvme_ctrlr_get_num_ns() may also change.
    1313             :  *
    1314             :  * \param ctrlr Opaque handle to NVMe controller.
    1315             :  *
    1316             :  * \return 0 on success, -1 on failure, -ENOTSUP if subsystem reset is not supported.
    1317             :  */
    1318             : int spdk_nvme_ctrlr_reset_subsystem(struct spdk_nvme_ctrlr *ctrlr);
    1319             : 
    1320             : /**
    1321             :  * Fail the given NVMe controller.
    1322             :  *
    1323             :  * This function gives the application the opportunity to fail a controller
    1324             :  * at will. When a controller is failed, any calls to process completions or
    1325             :  * submit I/O on qpairs associated with that controller will fail with an error
    1326             :  * code of -ENXIO.
    1327             :  * The controller can only be taken from the failed state by
    1328             :  * calling spdk_nvme_ctrlr_reset. After the controller has been successfully
    1329             :  * reset, any I/O pending when the controller was moved to failed will be
    1330             :  * aborted back to the application and can be resubmitted. I/O can then resume.
    1331             :  *
    1332             :  * \param ctrlr Opaque handle to an NVMe controller.
    1333             :  */
    1334             : void spdk_nvme_ctrlr_fail(struct spdk_nvme_ctrlr *ctrlr);
    1335             : 
    1336             : /**
    1337             :  * This function returns the failed status of a given controller.
    1338             :  *
    1339             :  * \param ctrlr Opaque handle to an NVMe controller.
    1340             :  *
    1341             :  * \return True if the controller is failed, false otherwise.
    1342             :  */
    1343             : bool spdk_nvme_ctrlr_is_failed(struct spdk_nvme_ctrlr *ctrlr);
    1344             : 
    1345             : /**
    1346             :  * Get the identify controller data as defined by the NVMe specification.
    1347             :  *
    1348             :  * This function is thread safe and can be called at any point while the controller
    1349             :  * is attached to the SPDK NVMe driver.
    1350             :  *
    1351             :  * \param ctrlr Opaque handle to NVMe controller.
    1352             :  *
    1353             :  * \return pointer to the identify controller data.
    1354             :  */
    1355             : const struct spdk_nvme_ctrlr_data *spdk_nvme_ctrlr_get_data(struct spdk_nvme_ctrlr *ctrlr);
    1356             : 
    1357             : /**
    1358             :  * Get the NVMe controller CSTS (Status) register.
    1359             :  *
    1360             :  * \param ctrlr Opaque handle to NVMe controller.
    1361             :  *
    1362             :  * \return the NVMe controller CSTS (Status) register.
    1363             :  */
    1364             : union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts(struct spdk_nvme_ctrlr *ctrlr);
    1365             : 
    1366             : /**
    1367             :  * Get the NVMe controller CC (Configuration) register.
    1368             :  *
    1369             :  * \param ctrlr Opaque handle to NVMe controller.
    1370             :  *
    1371             :  * \return the NVMe controller CC (Configuration) register.
    1372             :  */
    1373             : union spdk_nvme_cc_register spdk_nvme_ctrlr_get_regs_cc(struct spdk_nvme_ctrlr *ctrlr);
    1374             : 
    1375             : /**
    1376             :  * Get the NVMe controller CAP (Capabilities) register.
    1377             :  *
    1378             :  * \param ctrlr Opaque handle to NVMe controller.
    1379             :  *
    1380             :  * \return the NVMe controller CAP (Capabilities) register.
    1381             :  */
    1382             : union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap(struct spdk_nvme_ctrlr *ctrlr);
    1383             : 
    1384             : /**
    1385             :  * Get the NVMe controller VS (Version) register.
    1386             :  *
    1387             :  * \param ctrlr Opaque handle to NVMe controller.
    1388             :  *
    1389             :  * \return the NVMe controller VS (Version) register.
    1390             :  */
    1391             : union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs(struct spdk_nvme_ctrlr *ctrlr);
    1392             : 
    1393             : /**
    1394             :  * Get the NVMe controller CMBSZ (Controller Memory Buffer Size) register
    1395             :  *
    1396             :  * \param ctrlr Opaque handle to NVMe controller.
    1397             :  *
    1398             :  * \return the NVMe controller CMBSZ (Controller Memory Buffer Size) register.
    1399             :  */
    1400             : union spdk_nvme_cmbsz_register spdk_nvme_ctrlr_get_regs_cmbsz(struct spdk_nvme_ctrlr *ctrlr);
    1401             : 
    1402             : /**
    1403             :  * Get the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
    1404             :  *
    1405             :  * \param ctrlr Opaque handle to NVMe controller.
    1406             :  *
    1407             :  * \return the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
    1408             :  */
    1409             : union spdk_nvme_pmrcap_register spdk_nvme_ctrlr_get_regs_pmrcap(struct spdk_nvme_ctrlr *ctrlr);
    1410             : 
    1411             : /**
    1412             :  * Get the NVMe controller BPINFO (Boot Partition Information) register.
    1413             :  *
    1414             :  * \param ctrlr Opaque handle to NVMe controller.
    1415             :  *
    1416             :  * \return the NVMe controller BPINFO (Boot Partition Information) register.
    1417             :  */
    1418             : union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo(struct spdk_nvme_ctrlr *ctrlr);
    1419             : 
    1420             : /**
    1421             :  * Get the NVMe controller PMR size.
    1422             :  *
    1423             :  * \param ctrlr Opaque handle to NVMe controller.
    1424             :  *
    1425             :  * \return the NVMe controller PMR size or 0 if PMR is not supported.
    1426             :  */
    1427             : uint64_t spdk_nvme_ctrlr_get_pmrsz(struct spdk_nvme_ctrlr *ctrlr);
    1428             : 
    1429             : /**
    1430             :  * Get the maximum NSID value that will ever be used for the given controller
    1431             :  *
    1432             :  * This function is thread safe and can be called at any point while the
    1433             :  * controller is attached to the SPDK NVMe driver.
    1434             :  *
    1435             :  * This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the
    1436             :  * spdk_nvme_ctrlr_data and then reading the nn field.
    1437             :  *
    1438             :  * The NN field in the NVMe specification represents the maximum value that a
    1439             :  * namespace ID can ever have. Prior to NVMe 1.2, this was also the number of
    1440             :  * active namespaces, but from 1.2 onward the list of namespaces may be
    1441             :  * sparsely populated. Unfortunately, the meaning of this field is often
    1442             :  * misinterpreted by drive manufacturers and NVMe-oF implementers so it is
    1443             :  * not considered reliable. AVOID USING THIS FUNCTION WHENEVER POSSIBLE.
    1444             :  *
    1445             :  * \param ctrlr Opaque handle to NVMe controller.
    1446             :  *
    1447             :  * \return the number of namespaces.
    1448             :  */
    1449             : uint32_t spdk_nvme_ctrlr_get_num_ns(struct spdk_nvme_ctrlr *ctrlr);
    1450             : 
    1451             : /**
    1452             :  * Get the PCI device of a given NVMe controller.
    1453             :  *
    1454             :  * This only works for local (PCIe-attached) NVMe controllers; other transports
    1455             :  * will return NULL.
    1456             :  *
    1457             :  * \param ctrlr Opaque handle to NVMe controller.
    1458             :  *
    1459             :  * \return PCI device of the NVMe controller, or NULL if not available.
    1460             :  */
    1461             : struct spdk_pci_device *spdk_nvme_ctrlr_get_pci_device(struct spdk_nvme_ctrlr *ctrlr);
    1462             : 
    1463             : /**
    1464             :  * Get the NUMA ID for the given NVMe controller.
    1465             :  *
    1466             :  * For network-based transports, the NUMA ID will be correlated to the
    1467             :  * network interface.
    1468             :  *
    1469             :  * \param ctrlr Opaque handle to NVMe controller
    1470             :  *
    1471             :  * \return NUMA ID of the NVMe controller, or SPDK_ENV_NUMA_ID_ANY if
    1472             :  *         the NUMA ID is unknown
    1473             :  */
    1474             : int32_t spdk_nvme_ctrlr_get_numa_id(struct spdk_nvme_ctrlr *ctrlr);
    1475             : 
    1476             : /**
    1477             :  * Get the maximum data transfer size of a given NVMe controller.
    1478             :  *
    1479             :  * \param ctrlr Opaque handle to NVMe controller.
    1480             :  *
    1481             :  * \return Maximum data transfer size of the NVMe controller in bytes.
    1482             :  *
    1483             :  * The I/O command helper functions, such as spdk_nvme_ns_cmd_read(), will split
    1484             :  * large I/Os automatically; however, it is up to the user to obey this limit for
    1485             :  * commands submitted with the raw command functions, such as spdk_nvme_ctrlr_cmd_io_raw().
    1486             :  */
    1487             : uint32_t spdk_nvme_ctrlr_get_max_xfer_size(const struct spdk_nvme_ctrlr *ctrlr);
    1488             : 
    1489             : /**
    1490             :  * Get the maximum number of SGEs per request for the given NVMe controller.
    1491             :  *
    1492             :  * Controllers that do not support SGL will return UINT16_MAX.
    1493             :  *
    1494             :  * \param ctrlr Opaque handle to NVMe controller.
    1495             :  *
    1496             :  * \return Maximum number of SGEs per request
    1497             :  */
    1498             : uint16_t spdk_nvme_ctrlr_get_max_sges(const struct spdk_nvme_ctrlr *ctrlr);
    1499             : 
    1500             : /**
    1501             :  * Check whether the nsid is an active nv for the given NVMe controller.
    1502             :  *
    1503             :  * This function is thread safe and can be called at any point while the controller
    1504             :  * is attached to the SPDK NVMe driver.
    1505             :  *
    1506             :  * \param ctrlr Opaque handle to NVMe controller.
    1507             :  * \param nsid Namespace id.
    1508             :  *
    1509             :  * \return true if nsid is an active ns, or false otherwise.
    1510             :  */
    1511             : bool spdk_nvme_ctrlr_is_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
    1512             : 
    1513             : /**
    1514             :  * Get the nsid of the first active namespace.
    1515             :  *
    1516             :  * This function is thread safe and can be called at any point while the controller
    1517             :  * is attached to the SPDK NVMe driver.
    1518             :  *
    1519             :  * \param ctrlr Opaque handle to NVMe controller.
    1520             :  *
    1521             :  * \return the nsid of the first active namespace, 0 if there are no active namespaces.
    1522             :  */
    1523             : uint32_t spdk_nvme_ctrlr_get_first_active_ns(struct spdk_nvme_ctrlr *ctrlr);
    1524             : 
    1525             : /**
    1526             :  * Get next active namespace given the previous nsid.
    1527             :  *
    1528             :  * This function is thread safe and can be called at any point while the controller
    1529             :  * is attached to the SPDK NVMe driver.
    1530             :  *
    1531             :  * \param ctrlr Opaque handle to NVMe controller.
    1532             :  * \param prev_nsid Namespace id.
    1533             :  *
    1534             :  * \return a next active namespace given the previous nsid, 0 when there are no
    1535             :  * more active namespaces.
    1536             :  */
    1537             : uint32_t spdk_nvme_ctrlr_get_next_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t prev_nsid);
    1538             : 
    1539             : /**
    1540             :  * Determine if a particular log page is supported by the given NVMe controller.
    1541             :  *
    1542             :  * This function is thread safe and can be called at any point while the controller
    1543             :  * is attached to the SPDK NVMe driver.
    1544             :  *
    1545             :  * \sa spdk_nvme_ctrlr_cmd_get_log_page().
    1546             :  *
    1547             :  * \param ctrlr Opaque handle to NVMe controller.
    1548             :  * \param log_page Log page to query.
    1549             :  *
    1550             :  * \return true if supported, or false otherwise.
    1551             :  */
    1552             : bool spdk_nvme_ctrlr_is_log_page_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page);
    1553             : 
    1554             : /**
    1555             :  * Determine if a particular feature is supported by the given NVMe controller.
    1556             :  *
    1557             :  * This function is thread safe and can be called at any point while the controller
    1558             :  * is attached to the SPDK NVMe driver.
    1559             :  *
    1560             :  * \sa spdk_nvme_ctrlr_cmd_get_feature().
    1561             :  *
    1562             :  * \param ctrlr Opaque handle to NVMe controller.
    1563             :  * \param feature_code Feature to query.
    1564             :  *
    1565             :  * \return true if supported, or false otherwise.
    1566             :  */
    1567             : bool spdk_nvme_ctrlr_is_feature_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature_code);
    1568             : 
    1569             : /**
    1570             :  * Signature for callback function invoked when a command is completed.
    1571             :  *
    1572             :  * \param ctx Callback context provided when the command was submitted.
    1573             :  * \param cpl Completion queue entry that contains the completion status.
    1574             :  */
    1575             : typedef void (*spdk_nvme_cmd_cb)(void *ctx, const struct spdk_nvme_cpl *cpl);
    1576             : 
    1577             : /**
    1578             :  * Signature for callback function invoked when an asynchronous event request
    1579             :  * command is completed.
    1580             :  *
    1581             :  * \param aer_cb_arg Context specified by spdk_nvme_register_aer_callback().
    1582             :  * \param cpl Completion queue entry that contains the completion status
    1583             :  * of the asynchronous event request that was completed.
    1584             :  */
    1585             : typedef void (*spdk_nvme_aer_cb)(void *aer_cb_arg,
    1586             :                                  const struct spdk_nvme_cpl *cpl);
    1587             : 
    1588             : /**
    1589             :  * Register callback function invoked when an AER command is completed for the
    1590             :  * given NVMe controller.
    1591             :  *
    1592             :  * \param ctrlr Opaque handle to NVMe controller.
    1593             :  * \param aer_cb_fn Callback function invoked when an asynchronous event request
    1594             :  * command is completed.
    1595             :  * \param aer_cb_arg Argument passed to callback function.
    1596             :  */
    1597             : void spdk_nvme_ctrlr_register_aer_callback(struct spdk_nvme_ctrlr *ctrlr,
    1598             :                 spdk_nvme_aer_cb aer_cb_fn,
    1599             :                 void *aer_cb_arg);
    1600             : 
    1601             : /**
    1602             :  * Disable reading the CHANGED_NS_LIST log page for the specified controller.
    1603             :  *
    1604             :  * Applications that register an AER callback may wish to read the CHANGED_NS_LIST
    1605             :  * log page itself, rather than relying on the driver to do it.  Calling this
    1606             :  * function will ensure that the driver does not read this log page if the
    1607             :  * controller returns a NS_ATTR_CHANGED AEN.
    1608             :  *
    1609             :  * Reading of this log page can alternatively be disabled by setting the
    1610             :  * disable_read_changed_ns_list_log_page flag in the spdk_nvme_ctrlr_opts
    1611             :  * when attaching the controller.
    1612             :  *
    1613             :  * \param ctrlr NVMe controller on which to disable the log page read.
    1614             :  */
    1615             : void spdk_nvme_ctrlr_disable_read_changed_ns_list_log_page(struct spdk_nvme_ctrlr *ctrlr);
    1616             : 
    1617             : /**
    1618             :  * Opaque handle to a queue pair.
    1619             :  *
    1620             :  * I/O queue pairs may be allocated using spdk_nvme_ctrlr_alloc_io_qpair().
    1621             :  */
    1622             : struct spdk_nvme_qpair;
    1623             : 
    1624             : /**
    1625             :  * Signature for the callback function invoked when a timeout is detected on a
    1626             :  * request.
    1627             :  *
    1628             :  * For timeouts detected on the admin queue pair, the qpair returned here will
    1629             :  * be NULL.  If the controller has a serious error condition and is unable to
    1630             :  * communicate with driver via completion queue, the controller can set Controller
    1631             :  * Fatal Status field to 1, then reset is required to recover from such error.
    1632             :  * Users may detect Controller Fatal Status when timeout happens.
    1633             :  *
    1634             :  * \param cb_arg Argument passed to callback function.
    1635             :  * \param ctrlr Opaque handle to NVMe controller.
    1636             :  * \param qpair Opaque handle to a queue pair.
    1637             :  * \param cid Command ID.
    1638             :  */
    1639             : typedef void (*spdk_nvme_timeout_cb)(void *cb_arg,
    1640             :                                      struct spdk_nvme_ctrlr *ctrlr,
    1641             :                                      struct spdk_nvme_qpair *qpair,
    1642             :                                      uint16_t cid);
    1643             : 
    1644             : /**
    1645             :  * Register for timeout callback on a controller.
    1646             :  *
    1647             :  * The application can choose to register for timeout callback or not register
    1648             :  * for timeout callback.
    1649             :  *
    1650             :  * \param ctrlr NVMe controller on which to monitor for timeout.
    1651             :  * \param timeout_io_us Timeout value in microseconds for io commands.
    1652             :  * \param timeout_admin_us Timeout value in microseconds for admin commands.
    1653             :  * \param cb_fn A function pointer that points to the callback function.
    1654             :  * \param cb_arg Argument to the callback function.
    1655             :  */
    1656             : void spdk_nvme_ctrlr_register_timeout_callback(struct spdk_nvme_ctrlr *ctrlr,
    1657             :                 uint64_t timeout_io_us, uint64_t timeout_admin_us,
    1658             :                 spdk_nvme_timeout_cb cb_fn, void *cb_arg);
    1659             : 
    1660             : /**
    1661             :  * Signature for the callback function when a
    1662             :  * \ref spdk_nvme_ctrlr_get_discovery_log_page operation is completed.
    1663             :  *
    1664             :  * \param cb_arg Argument passed to callback function.
    1665             :  * \param rc Status of operation. 0 means success, and that the cpl argument is valid.
    1666             :  *           Failure indicated by negative errno value.
    1667             :  * \param cpl NVMe completion status of the operation. NULL if rc != 0. If multiple
    1668             :  *            completions with error status occurred during the operation, the cpl
    1669             :  *            value for the first error will be used here.
    1670             :  * \param log_page Pointer to the full discovery log page. The application is
    1671             :  *                 responsible for freeing this buffer using free().
    1672             :  */
    1673             : typedef void (*spdk_nvme_discovery_cb)(void *cb_arg, int rc,
    1674             :                                        const struct spdk_nvme_cpl *cpl,
    1675             :                                        struct spdk_nvmf_discovery_log_page *log_page);
    1676             : 
    1677             : /**
    1678             :  * Get a full discovery log page from the specified controller.
    1679             :  *
    1680             :  * This function will first read the discovery log header to determine the
    1681             :  * total number of valid entries in the discovery log, then it will allocate
    1682             :  * a buffer to hold the entire log and issue multiple GET_LOG_PAGE commands to
    1683             :  * get all of the entries.
    1684             :  *
    1685             :  * The application is responsible for calling
    1686             :  * \ref spdk_nvme_ctrlr_process_admin_completions to trigger processing of
    1687             :  * completions submitted by this function.
    1688             :  *
    1689             :  * \param ctrlr Pointer to the discovery controller.
    1690             :  * \param cb_fn Function to call when the operation is complete.
    1691             :  * \param cb_arg Argument to pass to cb_fn.
    1692             :  */
    1693             : int spdk_nvme_ctrlr_get_discovery_log_page(struct spdk_nvme_ctrlr *ctrlr,
    1694             :                 spdk_nvme_discovery_cb cb_fn, void *cb_arg);
    1695             : 
    1696             : /**
    1697             :  * NVMe I/O queue pair initialization options.
    1698             :  *
    1699             :  * These options may be passed to spdk_nvme_ctrlr_alloc_io_qpair() to configure queue pair
    1700             :  * options at queue creation time.
    1701             :  *
    1702             :  * The user may retrieve the default I/O queue pair creation options for a controller using
    1703             :  * spdk_nvme_ctrlr_get_default_io_qpair_opts().
    1704             :  */
    1705             : struct spdk_nvme_io_qpair_opts {
    1706             :         /**
    1707             :          * Queue priority for weighted round robin arbitration.  If a different arbitration
    1708             :          * method is in use, pass 0.
    1709             :          */
    1710             :         enum spdk_nvme_qprio qprio;
    1711             : 
    1712             :         /**
    1713             :          * The queue depth of this NVMe I/O queue. Overrides spdk_nvme_ctrlr_opts::io_queue_size.
    1714             :          */
    1715             :         uint32_t io_queue_size;
    1716             : 
    1717             :         /**
    1718             :          * The number of requests to allocate for this NVMe I/O queue.
    1719             :          *
    1720             :          * Overrides spdk_nvme_ctrlr_opts::io_queue_requests.
    1721             :          *
    1722             :          * This should be at least as large as io_queue_size.
    1723             :          *
    1724             :          * A single I/O may allocate more than one request, since splitting may be
    1725             :          * necessary to conform to the device's maximum transfer size, PRP list
    1726             :          * compatibility requirements, or driver-assisted striping.
    1727             :          */
    1728             :         uint32_t io_queue_requests;
    1729             : 
    1730             :         /**
    1731             :          * When submitting I/O via spdk_nvme_ns_read/write and similar functions,
    1732             :          * don't immediately submit it to hardware. Instead, queue up new commands
    1733             :          * and submit them to the hardware inside spdk_nvme_qpair_process_completions().
    1734             :          *
    1735             :          * This results in better batching of I/O commands. Often, it is more efficient
    1736             :          * to submit batches of commands to the underlying hardware than each command
    1737             :          * individually.
    1738             :          *
    1739             :          * This only applies to PCIe and RDMA transports.
    1740             :          *
    1741             :          * The flag was originally named delay_pcie_doorbell. To allow backward compatibility
    1742             :          * both names are kept in unnamed union.
    1743             :          */
    1744             :         union {
    1745             :                 bool delay_cmd_submit;
    1746             :                 bool delay_pcie_doorbell;
    1747             :         };
    1748             : 
    1749             :         /* Hole at bytes 13-15. */
    1750             :         uint8_t reserved13[3];
    1751             : 
    1752             :         /**
    1753             :          * These fields allow specifying the memory buffers for the submission and/or
    1754             :          * completion queues.
    1755             :          * By default, vaddr is set to NULL meaning SPDK will allocate the memory to be used.
    1756             :          * If vaddr is NULL then paddr must be set to 0.
    1757             :          * If vaddr is non-NULL, and paddr is zero, SPDK derives the physical
    1758             :          * address for the NVMe device, in this case the memory must be registered.
    1759             :          * If a paddr value is non-zero, SPDK uses the vaddr and paddr as passed
    1760             :          * SPDK assumes that the memory passed is both virtually and physically
    1761             :          * contiguous.
    1762             :          * If these fields are used, SPDK will NOT impose any restriction
    1763             :          * on the number of elements in the queues.
    1764             :          * The buffer sizes are in number of bytes, and are used to confirm
    1765             :          * that the buffers are large enough to contain the appropriate queue.
    1766             :          * These fields are only used by PCIe attached NVMe devices.  They
    1767             :          * are presently ignored for other transports.
    1768             :          */
    1769             :         struct {
    1770             :                 struct spdk_nvme_cmd *vaddr;
    1771             :                 uint64_t paddr;
    1772             :                 uint64_t buffer_size;
    1773             :         } sq;
    1774             :         struct {
    1775             :                 struct spdk_nvme_cpl *vaddr;
    1776             :                 uint64_t paddr;
    1777             :                 uint64_t buffer_size;
    1778             :         } cq;
    1779             : 
    1780             :         /**
    1781             :          * This flag indicates to the alloc_io_qpair function that it should not perform
    1782             :          * the connect portion on this qpair. This allows the user to add the qpair to a
    1783             :          * poll group and then connect it later.
    1784             :          */
    1785             :         bool create_only;
    1786             : 
    1787             :         /**
    1788             :          * This flag if set to true enables the creation of submission and completion queue
    1789             :          * asynchronously. Default mode is set to false to create io qpair synchronously.
    1790             :          */
    1791             :         bool async_mode;
    1792             : 
    1793             :         /**
    1794             :          * This flag if set to true disables the merging of physically
    1795             :          * contiguous SGL elements. Default mode is set to false to allow
    1796             :          * merging of physically contiguous SGL elements.
    1797             :          */
    1798             :         bool disable_pcie_sgl_merge;
    1799             : 
    1800             :         /* Hole at bytes 67-71. */
    1801             :         uint8_t reserved67[5];
    1802             : };
    1803             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_io_qpair_opts) == 72, "Incorrect size");
    1804             : 
    1805             : /**
    1806             :  * Get the default options for I/O qpair creation for a specific NVMe controller.
    1807             :  *
    1808             :  * \param ctrlr NVMe controller to retrieve the defaults from.
    1809             :  * \param[out] opts Will be filled with the default options for
    1810             :  * spdk_nvme_ctrlr_alloc_io_qpair().
    1811             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts).
    1812             :  */
    1813             : void spdk_nvme_ctrlr_get_default_io_qpair_opts(struct spdk_nvme_ctrlr *ctrlr,
    1814             :                 struct spdk_nvme_io_qpair_opts *opts,
    1815             :                 size_t opts_size);
    1816             : 
    1817             : /**
    1818             :  * Allocate an I/O queue pair (submission and completion queue).
    1819             :  *
    1820             :  * This function by default also performs any connection activities required for
    1821             :  * a newly created qpair. To avoid that behavior, the user should set the create_only
    1822             :  * flag in the opts structure to true.
    1823             :  *
    1824             :  * Each queue pair should only be used from a single thread at a time (mutual
    1825             :  * exclusion must be enforced by the user).
    1826             :  *
    1827             :  * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
    1828             :  * \param opts I/O qpair creation options, or NULL to use the defaults as returned
    1829             :  * by spdk_nvme_ctrlr_get_default_io_qpair_opts().
    1830             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts), or 0
    1831             :  * if opts is NULL.
    1832             :  *
    1833             :  * \return a pointer to the allocated I/O queue pair.
    1834             :  */
    1835             : struct spdk_nvme_qpair *spdk_nvme_ctrlr_alloc_io_qpair(struct spdk_nvme_ctrlr *ctrlr,
    1836             :                 const struct spdk_nvme_io_qpair_opts *opts,
    1837             :                 size_t opts_size);
    1838             : 
    1839             : /**
    1840             :  * Connect a newly created I/O qpair.
    1841             :  *
    1842             :  * This function does any connection activities required for a newly created qpair.
    1843             :  * It should be called after spdk_nvme_ctrlr_alloc_io_qpair has been called with the
    1844             :  * create_only flag set to true in the spdk_nvme_io_qpair_opts structure.
    1845             :  *
    1846             :  * This call will fail if performed on a qpair that is already connected.
    1847             :  * For reconnecting qpairs, see spdk_nvme_ctrlr_reconnect_io_qpair.
    1848             :  *
    1849             :  * For fabrics like TCP and RDMA, this function actually sends the commands over the wire
    1850             :  * that connect the qpair. For PCIe, this function performs some internal state machine operations.
    1851             :  *
    1852             :  * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
    1853             :  * \param qpair Opaque handle to the qpair to connect.
    1854             :  *
    1855             :  * return 0 on success or negated errno on failure. Specifically -EISCONN if the qpair is already connected.
    1856             :  *
    1857             :  */
    1858             : int spdk_nvme_ctrlr_connect_io_qpair(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    1859             : 
    1860             : /**
    1861             :  * Disconnect the given I/O qpair.
    1862             :  *
    1863             :  * This function must be called from the same thread as spdk_nvme_qpair_process_completions
    1864             :  * and the spdk_nvme_ns_cmd_* functions.
    1865             :  *
    1866             :  * After disconnect, calling spdk_nvme_qpair_process_completions or one of the
    1867             :  * spdk_nvme_ns_cmd* on a qpair will result in a return value of -ENXIO. A
    1868             :  * disconnected qpair may be reconnected with either the spdk_nvme_ctrlr_connect_io_qpair
    1869             :  * or spdk_nvme_ctrlr_reconnect_io_qpair APIs.
    1870             :  *
    1871             :  * \param qpair The qpair to disconnect.
    1872             :  */
    1873             : void spdk_nvme_ctrlr_disconnect_io_qpair(struct spdk_nvme_qpair *qpair);
    1874             : 
    1875             : /**
    1876             :  * Attempt to reconnect the given qpair.
    1877             :  *
    1878             :  * This function is intended to be called on qpairs that have already been connected,
    1879             :  * but have since entered a failed state as indicated by a return value of -ENXIO from
    1880             :  * either spdk_nvme_qpair_process_completions or one of the spdk_nvme_ns_cmd_* functions.
    1881             :  * This function must be called from the same thread as spdk_nvme_qpair_process_completions
    1882             :  * and the spdk_nvme_ns_cmd_* functions.
    1883             :  *
    1884             :  * Calling this function has the same effect as calling spdk_nvme_ctrlr_disconnect_io_qpair
    1885             :  * followed by spdk_nvme_ctrlr_connect_io_qpair.
    1886             :  *
    1887             :  * This function may be called on newly created qpairs, but it does extra checks and attempts
    1888             :  * to disconnect the qpair before connecting it. The recommended API for newly created qpairs
    1889             :  * is spdk_nvme_ctrlr_connect_io_qpair.
    1890             :  *
    1891             :  * \param qpair The qpair to reconnect.
    1892             :  *
    1893             :  * \return 0 on success, or if the qpair was already connected.
    1894             :  * -EAGAIN if the driver was unable to reconnect during this call,
    1895             :  * but the controller is still connected and is either resetting or enabled.
    1896             :  * -ENODEV if the controller is removed. In this case, the controller cannot be recovered
    1897             :  * and the application will have to destroy it and the associated qpairs.
    1898             :  * -ENXIO if the controller is in a failed state but is not yet resetting. In this case,
    1899             :  * the application should call spdk_nvme_ctrlr_reset to reset the entire controller.
    1900             :  */
    1901             : int spdk_nvme_ctrlr_reconnect_io_qpair(struct spdk_nvme_qpair *qpair);
    1902             : 
    1903             : /**
    1904             :  * Returns the reason the admin qpair for a given controller is disconnected.
    1905             :  *
    1906             :  * \param ctrlr The controller to check.
    1907             :  *
    1908             :  * \return a valid spdk_nvme_qp_failure_reason.
    1909             :  */
    1910             : spdk_nvme_qp_failure_reason spdk_nvme_ctrlr_get_admin_qp_failure_reason(
    1911             :         struct spdk_nvme_ctrlr *ctrlr);
    1912             : 
    1913             : /**
    1914             :  * Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1915             :  *
    1916             :  * The qpair must not be accessed after calling this function.
    1917             :  *
    1918             :  * \param qpair I/O queue pair to free.
    1919             :  *
    1920             :  * \return 0 on success.  This function will never return any value other than 0.
    1921             :  */
    1922             : int spdk_nvme_ctrlr_free_io_qpair(struct spdk_nvme_qpair *qpair);
    1923             : 
    1924             : /**
    1925             :  * Send the given NVM I/O command, I/O buffers, lists and all to the NVMe controller.
    1926             :  *
    1927             :  * This is a low level interface for submitting I/O commands directly.
    1928             :  *
    1929             :  * This function allows a caller to submit an I/O request that is
    1930             :  * COMPLETELY pre-defined, right down to the "physical" memory buffers.
    1931             :  * It is intended for testing hardware, specifying exact buffer location,
    1932             :  * alignment, and offset.  It also allows for specific choice of PRP
    1933             :  * and SGLs.
    1934             :  *
    1935             :  * The driver sets the CID.  EVERYTHING else is assumed set by the caller.
    1936             :  * Needless to say, this is potentially extremely dangerous for both the host
    1937             :  * (accidental/malicious storage usage/corruption), and the device.
    1938             :  * Thus its intent is for very specific hardware testing and environment
    1939             :  * reproduction.
    1940             :  *
    1941             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1942             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1943             :  * given time.
    1944             :  *
    1945             :  * This function can only be used on PCIe controllers and qpairs.
    1946             :  *
    1947             :  * \param ctrlr Opaque handle to NVMe controller.
    1948             :  * \param qpair I/O qpair to submit command.
    1949             :  * \param cmd NVM I/O command to submit.
    1950             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1951             :  * \param cb_arg Argument passed to callback function.
    1952             :  *
    1953             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    1954             :  * -ENOMEM: The request cannot be allocated.
    1955             :  * -ENXIO: The qpair is failed at the transport level.
    1956             :  */
    1957             : 
    1958             : int spdk_nvme_ctrlr_io_cmd_raw_no_payload_build(struct spdk_nvme_ctrlr *ctrlr,
    1959             :                 struct spdk_nvme_qpair *qpair,
    1960             :                 struct spdk_nvme_cmd *cmd,
    1961             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    1962             : 
    1963             : /**
    1964             :  * Send the given NVM I/O command to the NVMe controller.
    1965             :  *
    1966             :  * This is a low level interface for submitting I/O commands directly. Prefer
    1967             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    1968             :  * not be checked!
    1969             :  *
    1970             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    1971             :  * list/SGL or the CID. The driver will handle both of those for you.
    1972             :  *
    1973             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1974             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1975             :  * given time.
    1976             :  *
    1977             :  * \param ctrlr Opaque handle to NVMe controller.
    1978             :  * \param qpair I/O qpair to submit command.
    1979             :  * \param cmd NVM I/O command to submit.
    1980             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    1981             :  * \param len Size of buffer.
    1982             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1983             :  * \param cb_arg Argument passed to callback function.
    1984             :  *
    1985             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    1986             :  * -ENOMEM: The request cannot be allocated.
    1987             :  * -ENXIO: The qpair is failed at the transport level.
    1988             :  */
    1989             : int spdk_nvme_ctrlr_cmd_io_raw(struct spdk_nvme_ctrlr *ctrlr,
    1990             :                                struct spdk_nvme_qpair *qpair,
    1991             :                                struct spdk_nvme_cmd *cmd,
    1992             :                                void *buf, uint32_t len,
    1993             :                                spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    1994             : 
    1995             : /**
    1996             :  * Send the given NVM I/O command with metadata to the NVMe controller.
    1997             :  *
    1998             :  * This is a low level interface for submitting I/O commands directly. Prefer
    1999             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    2000             :  * not be checked!
    2001             :  *
    2002             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    2003             :  * list/SGL or the CID. The driver will handle both of those for you.
    2004             :  *
    2005             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    2006             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    2007             :  * given time.
    2008             :  *
    2009             :  * \param ctrlr Opaque handle to NVMe controller.
    2010             :  * \param qpair I/O qpair to submit command.
    2011             :  * \param cmd NVM I/O command to submit.
    2012             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    2013             :  * \param len Size of buffer.
    2014             :  * \param md_buf Virtual memory address of a single physically contiguous metadata
    2015             :  * buffer.
    2016             :  * \param cb_fn Callback function invoked when the I/O command completes.
    2017             :  * \param cb_arg Argument passed to callback function.
    2018             :  *
    2019             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    2020             :  * -ENOMEM: The request cannot be allocated.
    2021             :  * -ENXIO: The qpair is failed at the transport level.
    2022             :  */
    2023             : int spdk_nvme_ctrlr_cmd_io_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
    2024             :                                        struct spdk_nvme_qpair *qpair,
    2025             :                                        struct spdk_nvme_cmd *cmd,
    2026             :                                        void *buf, uint32_t len, void *md_buf,
    2027             :                                        spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2028             : 
    2029             : /**
    2030             :  * Restart the SGL walk to the specified offset when the command has scattered
    2031             :  * payloads.
    2032             :  *
    2033             :  * \param cb_arg Argument passed to readv/writev.
    2034             :  * \param offset Offset for SGL.
    2035             :  */
    2036             : typedef void (*spdk_nvme_req_reset_sgl_cb)(void *cb_arg, uint32_t offset);
    2037             : 
    2038             : /**
    2039             :  * Fill out *address and *length with the current SGL entry and advance to the
    2040             :  * next entry for the next time the callback is invoked.
    2041             :  *
    2042             :  * The described segment must be physically contiguous.
    2043             :  *
    2044             :  * \param cb_arg Argument passed to readv/writev.
    2045             :  * \param address Virtual address of this segment, a value of UINT64_MAX
    2046             :  * means the segment should be described via Bit Bucket SGL.
    2047             :  * \param length Length of this physical segment.
    2048             :  */
    2049             : typedef int (*spdk_nvme_req_next_sge_cb)(void *cb_arg, void **address,
    2050             :                 uint32_t *length);
    2051             : 
    2052             : /**
    2053             :  * Send the given NVM I/O command with metadata to the NVMe controller.
    2054             :  *
    2055             :  * This is a low level interface for submitting I/O commands directly. Prefer
    2056             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    2057             :  * not be checked!
    2058             :  *
    2059             :  * The command is submitted to a qpair allocated by  spdk_nvme_ctrlr_alloc_io_qpair().
    2060             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    2061             :  * given time.
    2062             :  *
    2063             :  * \param ctrlr Opaque handle to NVMe controller.
    2064             :  * \param qpair I/O qpair to submit command.
    2065             :  * \param cmd NVM I/O command to submit.
    2066             :  * \param len Size of buffer.
    2067             :  * \param md_buf Virtual memory address of a single physically contiguous metadata buffer.
    2068             :  * \param cb_fn Callback function invoked when the I/O command completes.
    2069             :  * \param cb_arg Argument passed to callback function.
    2070             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    2071             :  * \param next_sge_fn Callback function to iterate each scattered payload memory segment.
    2072             :  *
    2073             :  * \return 0 if successfully submitted, negated errnos on the following error
    2074             :  conditions:
    2075             :  * -ENOMEM: The request cannot be allocated.
    2076             :  * -ENXIO: The qpair is failed at the transport level.
    2077             :  */
    2078             : int spdk_nvme_ctrlr_cmd_iov_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
    2079             :                                         struct spdk_nvme_qpair *qpair,
    2080             :                                         struct spdk_nvme_cmd *cmd, uint32_t len,
    2081             :                                         void *md_buf, spdk_nvme_cmd_cb cb_fn,
    2082             :                                         void *cb_arg,
    2083             :                                         spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    2084             :                                         spdk_nvme_req_next_sge_cb next_sge_fn);
    2085             : 
    2086             : /**
    2087             :  * Process any outstanding completions for I/O submitted on a queue pair.
    2088             :  *
    2089             :  * This call is non-blocking, i.e. it only processes completions that are ready
    2090             :  * at the time of this function call. It does not wait for outstanding commands
    2091             :  * to finish.
    2092             :  *
    2093             :  * For each completed command, the request's callback function will be called if
    2094             :  * specified as non-NULL when the request was submitted.
    2095             :  *
    2096             :  * The caller must ensure that each queue pair is only used from one thread at a
    2097             :  * time.
    2098             :  *
    2099             :  * This function may be called at any point while the controller is attached to
    2100             :  * the SPDK NVMe driver.
    2101             :  *
    2102             :  * \sa spdk_nvme_cmd_cb
    2103             :  *
    2104             :  * \param qpair Queue pair to check for completions.
    2105             :  * \param max_completions Limit the number of completions to be processed in one
    2106             :  * call, or 0 for unlimited.
    2107             :  *
    2108             :  * \return number of completions processed (may be 0) or negated on error. -ENXIO
    2109             :  * in the special case that the qpair is failed at the transport layer.
    2110             :  */
    2111             : int32_t spdk_nvme_qpair_process_completions(struct spdk_nvme_qpair *qpair,
    2112             :                 uint32_t max_completions);
    2113             : 
    2114             : /**
    2115             :  * Returns the reason the qpair is disconnected.
    2116             :  *
    2117             :  * \param qpair The qpair to check.
    2118             :  *
    2119             :  * \return a valid spdk_nvme_qp_failure_reason.
    2120             :  */
    2121             : spdk_nvme_qp_failure_reason spdk_nvme_qpair_get_failure_reason(struct spdk_nvme_qpair *qpair);
    2122             : 
    2123             : /**
    2124             :  * Control if DNR is set or not for aborted commands.
    2125             :  *
    2126             :  * The default value is false.
    2127             :  *
    2128             :  * \param qpair The qpair to set.
    2129             :  * \param dnr Set the DNR bit to 1 if true or 0 if false for aborted commands.
    2130             :  */
    2131             : void spdk_nvme_qpair_set_abort_dnr(struct spdk_nvme_qpair *qpair, bool dnr);
    2132             : 
    2133             : /**
    2134             :  * Return the connection status of a given qpair.
    2135             :  *
    2136             :  * \param qpair The qpair to check.
    2137             :  *
    2138             :  * \return true if the qpair is connected, or false otherwise.
    2139             :  */
    2140             : bool spdk_nvme_qpair_is_connected(struct spdk_nvme_qpair *qpair);
    2141             : 
    2142             : typedef void (*spdk_nvme_authenticate_cb)(void *ctx, int status);
    2143             : 
    2144             : /**
    2145             :  * Force a qpair to authenticate.  As part of initialization, qpairs are authenticated automatically
    2146             :  * if the controller is configured with DH-HMAC-CHAP keys.  However, this function can be used to
    2147             :  * force authentication after a connection has already been established.
    2148             :  *
    2149             :  * This function doesn't disconnect the qpair if the authentication is successful.
    2150             :  *
    2151             :  * \param qpair The qpair to authenticate.
    2152             :  * \param cb_fn Callback to be executed after the authentication is done.
    2153             :  * \param cb_ctx Context passed to `cb_fn`.
    2154             :  *
    2155             :  * \return 0 on success, negative errno on failure.
    2156             :  */
    2157             : int spdk_nvme_qpair_authenticate(struct spdk_nvme_qpair *qpair,
    2158             :                                  spdk_nvme_authenticate_cb cb_fn, void *cb_ctx);
    2159             : 
    2160             : /**
    2161             :  * Force authentication on the admin qpair of a controller.  As part of initialization, the admin
    2162             :  * qpair is authenticated automatically if the controller is configured with DH-HMAC-CHAP keys.
    2163             :  * However, this function can be used to force authentication after a connection has already been
    2164             :  * established.
    2165             :  *
    2166             :  * This function doesn't disconnect the admin qpair if the authentication is successful.
    2167             :  *
    2168             :  * \param ctrlr Controller to authenticate.
    2169             :  * \param cb_fn Callback to be executed after the authentication is done.
    2170             :  * \param cb_ctx Context passed to `cb_fn`.
    2171             :  *
    2172             :  * \return 0 on success, negative errno on failure.
    2173             :  */
    2174             : int spdk_nvme_ctrlr_authenticate(struct spdk_nvme_ctrlr *ctrlr,
    2175             :                                  spdk_nvme_authenticate_cb cb_fn, void *cb_ctx);
    2176             : 
    2177             : /**
    2178             :  * Send the given admin command to the NVMe controller.
    2179             :  *
    2180             :  * This is a low level interface for submitting admin commands directly. Prefer
    2181             :  * the spdk_nvme_ctrlr_cmd_* functions instead. The validity of the command will
    2182             :  * not be checked!
    2183             :  *
    2184             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    2185             :  * list/SGL or the CID. The driver will handle both of those for you.
    2186             :  *
    2187             :  * This function is thread safe and can be called at any point while the controller
    2188             :  * is attached to the SPDK NVMe driver.
    2189             :  *
    2190             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2191             :  * of commands submitted through this function.
    2192             :  *
    2193             :  * \param ctrlr Opaque handle to NVMe controller.
    2194             :  * \param cmd NVM admin command to submit.
    2195             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    2196             :  * \param len Size of buffer.
    2197             :  * \param cb_fn Callback function invoked when the admin command completes.
    2198             :  * \param cb_arg Argument passed to callback function.
    2199             :  *
    2200             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2201             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2202             :  */
    2203             : int spdk_nvme_ctrlr_cmd_admin_raw(struct spdk_nvme_ctrlr *ctrlr,
    2204             :                                   struct spdk_nvme_cmd *cmd,
    2205             :                                   void *buf, uint32_t len,
    2206             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2207             : 
    2208             : /**
    2209             :  * Process any outstanding completions for admin commands.
    2210             :  *
    2211             :  * This will process completions for admin commands submitted on any thread.
    2212             :  *
    2213             :  * This call is non-blocking, i.e. it only processes completions that are ready
    2214             :  * at the time of this function call. It does not wait for outstanding commands
    2215             :  * to finish.
    2216             :  *
    2217             :  * This function is thread safe and can be called at any point while the controller
    2218             :  * is attached to the SPDK NVMe driver.
    2219             :  *
    2220             :  * \param ctrlr Opaque handle to NVMe controller.
    2221             :  *
    2222             :  * \return number of completions processed (may be 0) or negated on error. -ENXIO
    2223             :  * in the special case that the qpair is failed at the transport layer.
    2224             :  */
    2225             : int32_t spdk_nvme_ctrlr_process_admin_completions(struct spdk_nvme_ctrlr *ctrlr);
    2226             : 
    2227             : 
    2228             : /**
    2229             :  * Opaque handle to a namespace. Obtained by calling spdk_nvme_ctrlr_get_ns().
    2230             :  */
    2231             : struct spdk_nvme_ns;
    2232             : 
    2233             : /**
    2234             :  * Get a handle to a namespace for the given controller.
    2235             :  *
    2236             :  * Namespaces are numbered from 1 to the total number of namespaces. There will
    2237             :  * never be any gaps in the numbering. The number of namespaces is obtained by
    2238             :  * calling spdk_nvme_ctrlr_get_num_ns().
    2239             :  *
    2240             :  * This function is thread safe and can be called at any point while the controller
    2241             :  * is attached to the SPDK NVMe driver.
    2242             :  *
    2243             :  * \param ctrlr Opaque handle to NVMe controller.
    2244             :  * \param ns_id Namespace id.
    2245             :  *
    2246             :  * \return a pointer to the namespace.
    2247             :  */
    2248             : struct spdk_nvme_ns *spdk_nvme_ctrlr_get_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t ns_id);
    2249             : 
    2250             : /**
    2251             :  * Get a specific log page from the NVMe controller.
    2252             :  *
    2253             :  * This function is thread safe and can be called at any point while the controller
    2254             :  * is attached to the SPDK NVMe driver.
    2255             :  *
    2256             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2257             :  * commands submitted through this function.
    2258             :  *
    2259             :  * \sa spdk_nvme_ctrlr_is_log_page_supported()
    2260             :  *
    2261             :  * \param ctrlr Opaque handle to NVMe controller.
    2262             :  * \param log_page The log page identifier.
    2263             :  * \param nsid Depending on the log page, this may be 0, a namespace identifier,
    2264             :  * or SPDK_NVME_GLOBAL_NS_TAG.
    2265             :  * \param payload The pointer to the payload buffer.
    2266             :  * \param payload_size The size of payload buffer.
    2267             :  * \param offset Offset in bytes within the log page to start retrieving log page
    2268             :  * data. May only be non-zero if the controller supports extended data for Get Log
    2269             :  * Page as reported in the controller data log page attributes.
    2270             :  * \param cb_fn Callback function to invoke when the log page has been retrieved.
    2271             :  * \param cb_arg Argument to pass to the callback function.
    2272             :  *
    2273             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2274             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2275             :  */
    2276             : int spdk_nvme_ctrlr_cmd_get_log_page(struct spdk_nvme_ctrlr *ctrlr,
    2277             :                                      uint8_t log_page, uint32_t nsid,
    2278             :                                      void *payload, uint32_t payload_size,
    2279             :                                      uint64_t offset,
    2280             :                                      spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2281             : 
    2282             : /**
    2283             :  * Get a specific log page from the NVMe controller.
    2284             :  *
    2285             :  * This function is thread safe and can be called at any point while the controller
    2286             :  * is attached to the SPDK NVMe driver.
    2287             :  *
    2288             :  * This function allows specifying extra fields in cdw10 and cdw11 such as
    2289             :  * Retain Asynchronous Event and Log Specific Field.
    2290             :  *
    2291             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2292             :  * commands submitted through this function.
    2293             :  *
    2294             :  * \sa spdk_nvme_ctrlr_is_log_page_supported()
    2295             :  *
    2296             :  * \param ctrlr Opaque handle to NVMe controller.
    2297             :  * \param log_page The log page identifier.
    2298             :  * \param nsid Depending on the log page, this may be 0, a namespace identifier,
    2299             :  * or SPDK_NVME_GLOBAL_NS_TAG.
    2300             :  * \param payload The pointer to the payload buffer.
    2301             :  * \param payload_size The size of payload buffer.
    2302             :  * \param offset Offset in bytes within the log page to start retrieving log page
    2303             :  * data. May only be non-zero if the controller supports extended data for Get Log
    2304             :  * Page as reported in the controller data log page attributes.
    2305             :  * \param cdw10 Value to specify for cdw10.  Specify 0 for numdl - it will be
    2306             :  * set by this function based on the payload_size parameter.  Specify 0 for lid -
    2307             :  * it will be set by this function based on the log_page parameter.
    2308             :  * \param cdw11 Value to specify for cdw11.  Specify 0 for numdu - it will be
    2309             :  * set by this function based on the payload_size.
    2310             :  * \param cdw14 Value to specify for cdw14.
    2311             :  * \param cb_fn Callback function to invoke when the log page has been retrieved.
    2312             :  * \param cb_arg Argument to pass to the callback function.
    2313             :  *
    2314             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2315             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2316             :  */
    2317             : int spdk_nvme_ctrlr_cmd_get_log_page_ext(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page,
    2318             :                 uint32_t nsid, void *payload, uint32_t payload_size,
    2319             :                 uint64_t offset, uint32_t cdw10, uint32_t cdw11,
    2320             :                 uint32_t cdw14, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2321             : 
    2322             : /**
    2323             :  * Abort a specific previously-submitted NVMe command.
    2324             :  *
    2325             :  * \sa spdk_nvme_ctrlr_register_timeout_callback()
    2326             :  *
    2327             :  * \param ctrlr NVMe controller to which the command was submitted.
    2328             :  * \param qpair NVMe queue pair to which the command was submitted. For admin
    2329             :  *  commands, pass NULL for the qpair.
    2330             :  * \param cid Command ID of the command to abort.
    2331             :  * \param cb_fn Callback function to invoke when the abort has completed.
    2332             :  * \param cb_arg Argument to pass to the callback function.
    2333             :  *
    2334             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2335             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2336             :  */
    2337             : int spdk_nvme_ctrlr_cmd_abort(struct spdk_nvme_ctrlr *ctrlr,
    2338             :                               struct spdk_nvme_qpair *qpair,
    2339             :                               uint16_t cid,
    2340             :                               spdk_nvme_cmd_cb cb_fn,
    2341             :                               void *cb_arg);
    2342             : 
    2343             : /**
    2344             :  * Abort previously submitted commands which have cmd_cb_arg as its callback argument.
    2345             :  *
    2346             :  * \param ctrlr NVMe controller to which the commands were submitted.
    2347             :  * \param qpair NVMe queue pair to which the commands were submitted. For admin
    2348             :  * commands, pass NULL for the qpair.
    2349             :  * \param cmd_cb_arg Callback argument for the NVMe commands which this function
    2350             :  * attempts to abort.
    2351             :  * \param cb_fn Callback function to invoke when this function has completed.
    2352             :  * \param cb_arg Argument to pass to the callback function.
    2353             :  *
    2354             :  * \return 0 if successfully submitted, negated errno otherwise.
    2355             :  */
    2356             : int spdk_nvme_ctrlr_cmd_abort_ext(struct spdk_nvme_ctrlr *ctrlr,
    2357             :                                   struct spdk_nvme_qpair *qpair,
    2358             :                                   void *cmd_cb_arg,
    2359             :                                   spdk_nvme_cmd_cb cb_fn,
    2360             :                                   void *cb_arg);
    2361             : 
    2362             : /**
    2363             :  * Set specific feature for the given NVMe controller.
    2364             :  *
    2365             :  * This function is thread safe and can be called at any point while the controller
    2366             :  * is attached to the SPDK NVMe driver.
    2367             :  *
    2368             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2369             :  * commands submitted through this function.
    2370             :  *
    2371             :  * \sa spdk_nvme_ctrlr_cmd_get_feature().
    2372             :  *
    2373             :  * \param ctrlr NVMe controller to manipulate.
    2374             :  * \param feature The feature identifier.
    2375             :  * \param cdw11 as defined by the specification for this command.
    2376             :  * \param cdw12 as defined by the specification for this command.
    2377             :  * \param payload The pointer to the payload buffer.
    2378             :  * \param payload_size The size of payload buffer.
    2379             :  * \param cb_fn Callback function to invoke when the feature has been set.
    2380             :  * \param cb_arg Argument to pass to the callback function.
    2381             :  *
    2382             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2383             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2384             :  */
    2385             : int spdk_nvme_ctrlr_cmd_set_feature(struct spdk_nvme_ctrlr *ctrlr,
    2386             :                                     uint8_t feature, uint32_t cdw11, uint32_t cdw12,
    2387             :                                     void *payload, uint32_t payload_size,
    2388             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2389             : 
    2390             : /**
    2391             :  * Get specific feature from given NVMe controller.
    2392             :  *
    2393             :  * This function is thread safe and can be called at any point while the controller
    2394             :  * is attached to the SPDK NVMe driver.
    2395             :  *
    2396             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2397             :  * commands submitted through this function.
    2398             :  *
    2399             :  * \sa spdk_nvme_ctrlr_cmd_set_feature()
    2400             :  *
    2401             :  * \param ctrlr NVMe controller to query.
    2402             :  * \param feature The feature identifier.
    2403             :  * \param cdw11 as defined by the specification for this command.
    2404             :  * \param payload The pointer to the payload buffer.
    2405             :  * \param payload_size The size of payload buffer.
    2406             :  * \param cb_fn Callback function to invoke when the feature has been retrieved.
    2407             :  * \param cb_arg Argument to pass to the callback function.
    2408             :  *
    2409             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2410             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2411             :  */
    2412             : int spdk_nvme_ctrlr_cmd_get_feature(struct spdk_nvme_ctrlr *ctrlr,
    2413             :                                     uint8_t feature, uint32_t cdw11,
    2414             :                                     void *payload, uint32_t payload_size,
    2415             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2416             : 
    2417             : /**
    2418             :  * Get specific feature from given NVMe controller.
    2419             :  *
    2420             :  * \param ctrlr NVMe controller to query.
    2421             :  * \param feature The feature identifier.
    2422             :  * \param cdw11 as defined by the specification for this command.
    2423             :  * \param payload The pointer to the payload buffer.
    2424             :  * \param payload_size The size of payload buffer.
    2425             :  * \param cb_fn Callback function to invoke when the feature has been retrieved.
    2426             :  * \param cb_arg Argument to pass to the callback function.
    2427             :  * \param ns_id The namespace identifier.
    2428             :  *
    2429             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2430             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2431             :  *
    2432             :  * This function is thread safe and can be called at any point while the controller
    2433             :  * is attached to the SPDK NVMe driver.
    2434             :  *
    2435             :  * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2436             :  * of commands submitted through this function.
    2437             :  *
    2438             :  * \sa spdk_nvme_ctrlr_cmd_set_feature_ns()
    2439             :  */
    2440             : int spdk_nvme_ctrlr_cmd_get_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
    2441             :                                        uint32_t cdw11, void *payload, uint32_t payload_size,
    2442             :                                        spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id);
    2443             : 
    2444             : /**
    2445             :  * Set specific feature for the given NVMe controller and namespace ID.
    2446             :  *
    2447             :  * \param ctrlr NVMe controller to manipulate.
    2448             :  * \param feature The feature identifier.
    2449             :  * \param cdw11 as defined by the specification for this command.
    2450             :  * \param cdw12 as defined by the specification for this command.
    2451             :  * \param payload The pointer to the payload buffer.
    2452             :  * \param payload_size The size of payload buffer.
    2453             :  * \param cb_fn Callback function to invoke when the feature has been set.
    2454             :  * \param cb_arg Argument to pass to the callback function.
    2455             :  * \param ns_id The namespace identifier.
    2456             :  *
    2457             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2458             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2459             :  *
    2460             :  * This function is thread safe and can be called at any point while the controller
    2461             :  * is attached to the SPDK NVMe driver.
    2462             :  *
    2463             :  * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2464             :  * of commands submitted through this function.
    2465             :  *
    2466             :  * \sa spdk_nvme_ctrlr_cmd_get_feature_ns()
    2467             :  */
    2468             : int spdk_nvme_ctrlr_cmd_set_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
    2469             :                                        uint32_t cdw11, uint32_t cdw12, void *payload,
    2470             :                                        uint32_t payload_size, spdk_nvme_cmd_cb cb_fn,
    2471             :                                        void *cb_arg, uint32_t ns_id);
    2472             : 
    2473             : /**
    2474             :  * Receive security protocol data from controller.
    2475             :  *
    2476             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2477             :  *
    2478             :  * \param ctrlr NVMe controller to use for security receive command submission.
    2479             :  * \param secp Security Protocol that is used.
    2480             :  * \param spsp Security Protocol Specific field.
    2481             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2482             :  * Protocol EAh.
    2483             :  * \param payload The pointer to the payload buffer.
    2484             :  * \param payload_size The size of payload buffer.
    2485             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2486             :  * \param cb_arg Argument to pass to the callback function.
    2487             :  *
    2488             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2489             :  * for this request.
    2490             :  */
    2491             : int spdk_nvme_ctrlr_cmd_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2492             :                 uint16_t spsp, uint8_t nssf, void *payload,
    2493             :                 uint32_t payload_size,
    2494             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2495             : 
    2496             : /**
    2497             :  * Send security protocol data to controller.
    2498             :  *
    2499             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2500             :  *
    2501             :  * \param ctrlr NVMe controller to use for security send command submission.
    2502             :  * \param secp Security Protocol that is used.
    2503             :  * \param spsp Security Protocol Specific field.
    2504             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2505             :  * Protocol EAh.
    2506             :  * \param payload The pointer to the payload buffer.
    2507             :  * \param payload_size The size of payload buffer.
    2508             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2509             :  * \param cb_arg Argument to pass to the callback function.
    2510             :  *
    2511             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2512             :  * for this request.
    2513             :  */
    2514             : int spdk_nvme_ctrlr_cmd_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2515             :                                       uint16_t spsp, uint8_t nssf, void *payload,
    2516             :                                       uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2517             : 
    2518             : /**
    2519             :  * Receive security protocol data from controller.
    2520             :  *
    2521             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2522             :  *
    2523             :  * \param ctrlr NVMe controller to use for security receive command submission.
    2524             :  * \param secp Security Protocol that is used.
    2525             :  * \param spsp Security Protocol Specific field.
    2526             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2527             :  * Protocol EAh.
    2528             :  * \param payload The pointer to the payload buffer.
    2529             :  * \param size The size of payload buffer.
    2530             :  *
    2531             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2532             :  * for this request.
    2533             :  */
    2534             : int spdk_nvme_ctrlr_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2535             :                                      uint16_t spsp, uint8_t nssf, void *payload, size_t size);
    2536             : 
    2537             : /**
    2538             :  * Send security protocol data to controller.
    2539             :  *
    2540             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2541             :  *
    2542             :  * \param ctrlr NVMe controller to use for security send command submission.
    2543             :  * \param secp Security Protocol that is used.
    2544             :  * \param spsp Security Protocol Specific field.
    2545             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2546             :  * Protocol EAh.
    2547             :  * \param payload The pointer to the payload buffer.
    2548             :  * \param size The size of payload buffer.
    2549             :  *
    2550             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2551             :  * for this request.
    2552             :  */
    2553             : int spdk_nvme_ctrlr_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2554             :                                   uint16_t spsp, uint8_t nssf, void *payload, size_t size);
    2555             : 
    2556             : /**
    2557             :  * Receive data related to a specific Directive Type from the controller.
    2558             :  *
    2559             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2560             :  *
    2561             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2562             :  * commands submitted through this function.
    2563             :  *
    2564             :  * \param ctrlr NVMe controller to use for directive receive command submission.
    2565             :  * \param nsid Specific Namespace Identifier.
    2566             :  * \param doper Directive Operation defined in nvme_spec.h.
    2567             :  * \param dtype Directive Type defined in nvme_spec.h.
    2568             :  * \param dspec Directive Specific defined in nvme_spec.h.
    2569             :  * \param payload The pointer to the payload buffer.
    2570             :  * \param payload_size The size of payload buffer.
    2571             :  * \param cdw12 Command dword 12.
    2572             :  * \param cdw13 Command dword 13.
    2573             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2574             :  * \param cb_arg Argument to pass to the callback function.
    2575             :  *
    2576             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2577             :  * for this request.
    2578             :  */
    2579             : int spdk_nvme_ctrlr_cmd_directive_receive(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2580             :                 uint32_t doper, uint32_t dtype, uint32_t dspec,
    2581             :                 void *payload, uint32_t payload_size, uint32_t cdw12,
    2582             :                 uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2583             : 
    2584             : /**
    2585             :  * Send data related to a specific Directive Type to the controller.
    2586             :  *
    2587             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2588             :  *
    2589             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2590             :  * commands submitted through this function.
    2591             :  *
    2592             :  * \param ctrlr NVMe controller to use for directive send command submission.
    2593             :  * \param nsid Specific Namespace Identifier.
    2594             :  * \param doper Directive Operation defined in nvme_spec.h.
    2595             :  * \param dtype Directive Type defined in nvme_spec.h.
    2596             :  * \param dspec Directive Specific defined in nvme_spec.h.
    2597             :  * \param payload The pointer to the payload buffer.
    2598             :  * \param payload_size The size of payload buffer.
    2599             :  * \param cdw12 Command dword 12.
    2600             :  * \param cdw13 Command dword 13.
    2601             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2602             :  * \param cb_arg Argument to pass to the callback function.
    2603             :  *
    2604             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2605             :  * for this request.
    2606             :  */
    2607             : int spdk_nvme_ctrlr_cmd_directive_send(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2608             :                                        uint32_t doper, uint32_t dtype, uint32_t dspec,
    2609             :                                        void *payload, uint32_t payload_size, uint32_t cdw12,
    2610             :                                        uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2611             : 
    2612             : /**
    2613             :  * Get supported flags of the controller.
    2614             :  *
    2615             :  * \param ctrlr NVMe controller to get flags.
    2616             :  *
    2617             :  * \return supported flags of this controller.
    2618             :  */
    2619             : uint64_t spdk_nvme_ctrlr_get_flags(struct spdk_nvme_ctrlr *ctrlr);
    2620             : 
    2621             : /**
    2622             :  * Attach the specified namespace to controllers.
    2623             :  *
    2624             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2625             :  *
    2626             :  * \param ctrlr NVMe controller to use for command submission.
    2627             :  * \param nsid Namespace identifier for namespace to attach.
    2628             :  * \param payload The pointer to the controller list.
    2629             :  *
    2630             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2631             :  * for this request.
    2632             :  */
    2633             : int spdk_nvme_ctrlr_attach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2634             :                               struct spdk_nvme_ctrlr_list *payload);
    2635             : 
    2636             : /**
    2637             :  * Detach the specified namespace from controllers.
    2638             :  *
    2639             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2640             :  *
    2641             :  * \param ctrlr NVMe controller to use for command submission.
    2642             :  * \param nsid Namespace ID to detach.
    2643             :  * \param payload The pointer to the controller list.
    2644             :  *
    2645             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2646             :  * for this request
    2647             :  */
    2648             : int spdk_nvme_ctrlr_detach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2649             :                               struct spdk_nvme_ctrlr_list *payload);
    2650             : 
    2651             : /**
    2652             :  * Create a namespace.
    2653             :  *
    2654             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2655             :  *
    2656             :  * \param ctrlr NVMe controller to create namespace on.
    2657             :  * \param payload The pointer to the NVMe namespace data.
    2658             :  *
    2659             :  * \return Namespace ID (>= 1) if successfully created, or 0 if the request failed.
    2660             :  */
    2661             : uint32_t spdk_nvme_ctrlr_create_ns(struct spdk_nvme_ctrlr *ctrlr,
    2662             :                                    struct spdk_nvme_ns_data *payload);
    2663             : 
    2664             : /**
    2665             :  * Delete a namespace.
    2666             :  *
    2667             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2668             :  *
    2669             :  * \param ctrlr NVMe controller to delete namespace from.
    2670             :  * \param nsid The namespace identifier.
    2671             :  *
    2672             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2673             :  * allocated
    2674             :  * for this request
    2675             :  */
    2676             : int spdk_nvme_ctrlr_delete_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
    2677             : 
    2678             : /**
    2679             :  * Format NVM.
    2680             :  *
    2681             :  * This function requests a low-level format of the media.
    2682             :  *
    2683             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2684             :  *
    2685             :  * \param ctrlr NVMe controller to format.
    2686             :  * \param nsid The namespace identifier. May be SPDK_NVME_GLOBAL_NS_TAG to format
    2687             :  * all namespaces.
    2688             :  * \param format The format information for the command.
    2689             :  *
    2690             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2691             :  * allocated for this request
    2692             :  */
    2693             : int spdk_nvme_ctrlr_format(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2694             :                            struct spdk_nvme_format *format);
    2695             : 
    2696             : /**
    2697             :  * Download a new firmware image.
    2698             :  *
    2699             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2700             :  *
    2701             :  * \param ctrlr NVMe controller to perform firmware operation on.
    2702             :  * \param payload The data buffer for the firmware image.
    2703             :  * \param size The data size will be downloaded.
    2704             :  * \param slot The slot that the firmware image will be committed to.
    2705             :  * \param commit_action The action to perform when firmware is committed.
    2706             :  * \param completion_status output parameter. Contains the completion status of
    2707             :  * the firmware commit operation.
    2708             :  *
    2709             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2710             :  * for this request, -1 if the size is not multiple of 4.
    2711             :  */
    2712             : int spdk_nvme_ctrlr_update_firmware(struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size,
    2713             :                                     int slot, enum spdk_nvme_fw_commit_action commit_action,
    2714             :                                     struct spdk_nvme_status *completion_status);
    2715             : 
    2716             : /**
    2717             :  * Start the Read from a Boot Partition.
    2718             :  *
    2719             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2720             :  *
    2721             :  * \param ctrlr NVMe controller to perform the Boot Partition read.
    2722             :  * \param payload The data buffer for Boot Partition read.
    2723             :  * \param bprsz Read size in multiples of 4 KiB to copy into the Boot Partition Memory Buffer.
    2724             :  * \param bprof Boot Partition offset to read from in 4 KiB units.
    2725             :  * \param bpid Boot Partition identifier for the Boot Partition read operation.
    2726             :  *
    2727             :  * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
    2728             :  * -ENOMEM: if resources could not be allocated.
    2729             :  * -ENOTSUP: Boot Partition is not supported by the Controller.
    2730             :  * -EIO: Registers access failure.
    2731             :  * -EINVAL: Parameters are invalid.
    2732             :  * -EFAULT: Invalid address was specified as part of payload.
    2733             :  * -EALREADY: Boot Partition read already initiated.
    2734             :  */
    2735             : int spdk_nvme_ctrlr_read_boot_partition_start(struct spdk_nvme_ctrlr *ctrlr, void *payload,
    2736             :                 uint32_t bprsz, uint32_t bprof, uint32_t bpid);
    2737             : 
    2738             : /**
    2739             :  * Poll the status of the Read from a Boot Partition.
    2740             :  *
    2741             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2742             :  *
    2743             :  * \param ctrlr NVMe controller to perform the Boot Partition read.
    2744             :  *
    2745             :  * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
    2746             :  * -EIO: Registers access failure.
    2747             :  * -EINVAL: Invalid read status or the Boot Partition read is not initiated yet.
    2748             :  * -EAGAIN: If the read is still in progress; users must call
    2749             :  * spdk_nvme_ctrlr_read_boot_partition_poll again to check the read status.
    2750             :  */
    2751             : int spdk_nvme_ctrlr_read_boot_partition_poll(struct spdk_nvme_ctrlr *ctrlr);
    2752             : 
    2753             : /**
    2754             :  * Write to a Boot Partition.
    2755             :  *
    2756             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2757             :  * Users will get the completion after the data is downloaded, image is replaced and
    2758             :  * Boot Partition is activated or when the sequence encounters an error.
    2759             :  *
    2760             :  * \param ctrlr NVMe controller to perform the Boot Partition write.
    2761             :  * \param payload The data buffer for Boot Partition write.
    2762             :  * \param size Data size to write to the Boot Partition.
    2763             :  * \param bpid Boot Partition identifier for the Boot Partition write operation.
    2764             :  * \param cb_fn Callback function to invoke when the operation is completed.
    2765             :  * \param cb_arg Argument to pass to the callback function.
    2766             :  *
    2767             :  * \return 0 if Boot Partition write submit is successful. Negated errno on the following error conditions:
    2768             :  * -ENOMEM: if resources could not be allocated.
    2769             :  * -ENOTSUP: Boot Partition is not supported by the Controller.
    2770             :  * -EIO: Registers access failure.
    2771             :  * -EINVAL: Parameters are invalid.
    2772             :  */
    2773             : int spdk_nvme_ctrlr_write_boot_partition(struct spdk_nvme_ctrlr *ctrlr, void *payload,
    2774             :                 uint32_t size, uint32_t bpid, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2775             : 
    2776             : /**
    2777             :  * Return virtual address of PCIe NVM I/O registers
    2778             :  *
    2779             :  * This function returns a pointer to the PCIe I/O registers for a controller
    2780             :  * or NULL if unsupported for this transport.
    2781             :  *
    2782             :  * \param ctrlr Controller whose registers are to be accessed.
    2783             :  *
    2784             :  * \return Pointer to virtual address of register bank, or NULL.
    2785             :  */
    2786             : volatile struct spdk_nvme_registers *spdk_nvme_ctrlr_get_registers(struct spdk_nvme_ctrlr *ctrlr);
    2787             : 
    2788             : /**
    2789             :  * Reserve the controller memory buffer for data transfer use.
    2790             :  *
    2791             :  * This function reserves the full size of the controller memory buffer
    2792             :  * for use in data transfers. If submission queues or completion queues are
    2793             :  * already placed in the controller memory buffer, this call will fail.
    2794             :  *
    2795             :  * \param ctrlr Controller from which to allocate memory buffer
    2796             :  *
    2797             :  * \return The size of the controller memory buffer on success. Negated errno
    2798             :  * on failure.
    2799             :  */
    2800             : int spdk_nvme_ctrlr_reserve_cmb(struct spdk_nvme_ctrlr *ctrlr);
    2801             : 
    2802             : /**
    2803             :  * Map a previously reserved controller memory buffer so that it's data is
    2804             :  * visible from the CPU. This operation is not always possible.
    2805             :  *
    2806             :  * \param ctrlr Controller that contains the memory buffer
    2807             :  * \param size Size of buffer that was mapped.
    2808             :  *
    2809             :  * \return Pointer to controller memory buffer, or NULL on failure.
    2810             :  */
    2811             : void *spdk_nvme_ctrlr_map_cmb(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    2812             : 
    2813             : /**
    2814             :  * Free a controller memory I/O buffer.
    2815             :  *
    2816             :  * \param ctrlr Controller from which to unmap the memory buffer.
    2817             :  */
    2818             : void spdk_nvme_ctrlr_unmap_cmb(struct spdk_nvme_ctrlr *ctrlr);
    2819             : 
    2820             : /**
    2821             :  * Enable the Persistent Memory Region
    2822             :  *
    2823             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2824             :  *
    2825             :  * \return 0 on success. Negated errno on the following error conditions:
    2826             :  * -ENOTSUP: PMR is not supported by the Controller.
    2827             :  * -EIO: Registers access failure.
    2828             :  * -EINVAL: PMR Time Units Invalid or PMR is already enabled.
    2829             :  * -ETIMEDOUT: Timed out to Enable PMR.
    2830             :  * -ENOSYS: Transport does not support Enable PMR function.
    2831             :  */
    2832             : int spdk_nvme_ctrlr_enable_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2833             : 
    2834             : /**
    2835             :  * Disable the Persistent Memory Region
    2836             :  *
    2837             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2838             :  *
    2839             :  * \return 0 on success. Negated errno on the following error conditions:
    2840             :  * -ENOTSUP: PMR is not supported by the Controller.
    2841             :  * -EIO: Registers access failure.
    2842             :  * -EINVAL: PMR Time Units Invalid or PMR is already disabled.
    2843             :  * -ETIMEDOUT: Timed out to Disable PMR.
    2844             :  * -ENOSYS: Transport does not support Disable PMR function.
    2845             :  */
    2846             : int spdk_nvme_ctrlr_disable_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2847             : 
    2848             : /**
    2849             :  * Map the Persistent Memory Region so that it's data is
    2850             :  * visible from the CPU.
    2851             :  *
    2852             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2853             :  * \param size Size of the region that was mapped.
    2854             :  *
    2855             :  * \return Pointer to Persistent Memory Region, or NULL on failure.
    2856             :  */
    2857             : void *spdk_nvme_ctrlr_map_pmr(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    2858             : 
    2859             : /**
    2860             :  * Free the Persistent Memory Region.
    2861             :  *
    2862             :  * \param ctrlr Controller from which to unmap the Persistent Memory Region.
    2863             :  *
    2864             :  * \return 0 on success, negative errno on failure.
    2865             :  * -ENXIO: Either PMR is not supported by the Controller or the PMR is already unmapped.
    2866             :  * -ENOSYS: Transport does not support Unmap PMR function.
    2867             :  */
    2868             : int spdk_nvme_ctrlr_unmap_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2869             : 
    2870             : /**
    2871             :  * Get the transport ID for a given NVMe controller.
    2872             :  *
    2873             :  * \param ctrlr Controller to get the transport ID.
    2874             :  * \return Pointer to the controller's transport ID.
    2875             :  */
    2876             : const struct spdk_nvme_transport_id *spdk_nvme_ctrlr_get_transport_id(
    2877             :         struct spdk_nvme_ctrlr *ctrlr);
    2878             : 
    2879             : /**
    2880             :  * \brief Alloc NVMe I/O queue identifier.
    2881             :  *
    2882             :  * This function is only needed for the non-standard case of allocating queues using the raw
    2883             :  * command interface. In most cases \ref spdk_nvme_ctrlr_alloc_io_qpair should be sufficient.
    2884             :  *
    2885             :  * \param ctrlr Opaque handle to NVMe controller.
    2886             :  * \return qid on success, -1 on failure.
    2887             :  */
    2888             : int32_t spdk_nvme_ctrlr_alloc_qid(struct spdk_nvme_ctrlr *ctrlr);
    2889             : 
    2890             : /**
    2891             :  * \brief Free NVMe I/O queue identifier.
    2892             :  *
    2893             :  * This function must only be called with qids previously allocated with \ref spdk_nvme_ctrlr_alloc_qid.
    2894             :  *
    2895             :  * \param ctrlr Opaque handle to NVMe controller.
    2896             :  * \param qid NVMe Queue Identifier.
    2897             :  */
    2898             : void spdk_nvme_ctrlr_free_qid(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid);
    2899             : 
    2900             : /**
    2901             :  * Opaque handle for a poll group. A poll group is a collection of spdk_nvme_qpair
    2902             :  * objects that are polled for completions as a unit.
    2903             :  *
    2904             :  * Returned by spdk_nvme_poll_group_create().
    2905             :  */
    2906             : struct spdk_nvme_poll_group;
    2907             : 
    2908             : 
    2909             : /**
    2910             :  * This function alerts the user to disconnected qpairs when calling
    2911             :  * spdk_nvme_poll_group_process_completions.
    2912             :  */
    2913             : typedef void (*spdk_nvme_disconnected_qpair_cb)(struct spdk_nvme_qpair *qpair,
    2914             :                 void *poll_group_ctx);
    2915             : 
    2916             : /**
    2917             :  * Create a new poll group.
    2918             :  *
    2919             :  * \param ctx A user supplied context that can be retrieved later with spdk_nvme_poll_group_get_ctx
    2920             :  * \param table The call back table defined by users which contains the accelerated functions
    2921             :  * which can be used to accelerate some operations such as crc32c.
    2922             :  *
    2923             :  * \return Pointer to the new poll group, or NULL on error.
    2924             :  */
    2925             : struct spdk_nvme_poll_group *spdk_nvme_poll_group_create(void *ctx,
    2926             :                 struct spdk_nvme_accel_fn_table *table);
    2927             : 
    2928             : /**
    2929             :  * Get a optimal poll group.
    2930             :  *
    2931             :  * \param qpair The qpair to get the optimal poll group.
    2932             :  *
    2933             :  * \return Pointer to the optimal poll group, or NULL if not found.
    2934             :  */
    2935             : struct spdk_nvme_poll_group *spdk_nvme_qpair_get_optimal_poll_group(struct spdk_nvme_qpair *qpair);
    2936             : 
    2937             : /**
    2938             :  * Add an spdk_nvme_qpair to a poll group. qpairs may only be added to
    2939             :  * a poll group if they are in the disconnected state; i.e. either they were
    2940             :  * just allocated and not yet connected or they have been disconnected with a call
    2941             :  * to spdk_nvme_ctrlr_disconnect_io_qpair.
    2942             :  *
    2943             :  * \param group The group to which the qpair will be added.
    2944             :  * \param qpair The qpair to add to the poll group.
    2945             :  *
    2946             :  * return 0 on success, -EINVAL if the qpair is not in the disabled state, -ENODEV if the transport
    2947             :  * doesn't exist, -ENOMEM on memory allocation failures, or -EPROTO on a protocol (transport) specific failure.
    2948             :  */
    2949             : int spdk_nvme_poll_group_add(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
    2950             : 
    2951             : /**
    2952             :  * Remove a disconnected spdk_nvme_qpair from a poll group.
    2953             :  *
    2954             :  * \param group The group from which to remove the qpair.
    2955             :  * \param qpair The qpair to remove from the poll group.
    2956             :  *
    2957             :  * return 0 on success, -ENOENT if the qpair is not found in the group, -EINVAL if the qpair is not
    2958             :  * disconnected in the group, or -EPROTO on a protocol (transport) specific failure.
    2959             :  */
    2960             : int spdk_nvme_poll_group_remove(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
    2961             : 
    2962             : /**
    2963             :  * Destroy an empty poll group.
    2964             :  *
    2965             :  * \param group The group to destroy.
    2966             :  *
    2967             :  * return 0 on success, -EBUSY if the poll group is not empty.
    2968             :  */
    2969             : int spdk_nvme_poll_group_destroy(struct spdk_nvme_poll_group *group);
    2970             : 
    2971             : /**
    2972             :  * Poll for completions on all qpairs in this poll group.
    2973             :  *
    2974             :  * the disconnected_qpair_cb will be called for all disconnected qpairs in the poll group
    2975             :  * including qpairs which fail within the context of this call.
    2976             :  * The user is responsible for trying to reconnect or destroy those qpairs.
    2977             :  *
    2978             :  * \param group The group on which to poll for completions.
    2979             :  * \param completions_per_qpair The maximum number of completions per qpair.
    2980             :  * \param disconnected_qpair_cb A callback function of type spdk_nvme_disconnected_qpair_cb. Must be non-NULL.
    2981             :  *
    2982             :  * return The number of completions across all qpairs, -EINVAL if no disconnected_qpair_cb is passed, or
    2983             :  * -EIO if the shared completion queue cannot be polled for the RDMA transport.
    2984             :  */
    2985             : int64_t spdk_nvme_poll_group_process_completions(struct spdk_nvme_poll_group *group,
    2986             :                 uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
    2987             : 
    2988             : /**
    2989             :  * Check if all qpairs in the poll group are connected.
    2990             :  *
    2991             :  * This function allows the caller to check if all qpairs in a poll group are
    2992             :  * connected. This API is generally only suitable during application startup,
    2993             :  * to check when a large number of async connections have completed.
    2994             :  *
    2995             :  * It is useful for applications like benchmarking tools to create
    2996             :  * a large number of qpairs, but then ensuring they are all fully connected before
    2997             :  * proceeding with I/O.
    2998             :  *
    2999             :  * \param group The group on which to poll connecting qpairs.
    3000             :  *
    3001             :  * return 0 if all qpairs are in CONNECTED state, -EIO if any connections failed to connect, -EAGAIN if
    3002             :  * any qpairs are still trying to connected.
    3003             :  */
    3004             : int spdk_nvme_poll_group_all_connected(struct spdk_nvme_poll_group *group);
    3005             : 
    3006             : /**
    3007             :  * Retrieve the user context for this specific poll group.
    3008             :  *
    3009             :  * \param group The poll group from which to retrieve the context.
    3010             :  *
    3011             :  * \return A pointer to the user provided poll group context.
    3012             :  */
    3013             : void *spdk_nvme_poll_group_get_ctx(struct spdk_nvme_poll_group *group);
    3014             : 
    3015             : /**
    3016             :  * Retrieves transport statistics for the given poll group.
    3017             :  *
    3018             :  * Note: the structure returned by this function should later be freed with
    3019             :  * @b spdk_nvme_poll_group_free_stats function
    3020             :  *
    3021             :  * \param group Pointer to NVME poll group
    3022             :  * \param stats Double pointer to statistics to be filled by this function
    3023             :  * \return 0 on success or negated errno on failure
    3024             :  */
    3025             : int spdk_nvme_poll_group_get_stats(struct spdk_nvme_poll_group *group,
    3026             :                                    struct spdk_nvme_poll_group_stat **stats);
    3027             : 
    3028             : /**
    3029             :  * Frees poll group statistics retrieved using @b spdk_nvme_poll_group_get_stats function
    3030             :  *
    3031             :  * @param group Pointer to a poll group
    3032             :  * @param stat Pointer to statistics to be released
    3033             :  */
    3034             : void spdk_nvme_poll_group_free_stats(struct spdk_nvme_poll_group *group,
    3035             :                                      struct spdk_nvme_poll_group_stat *stat);
    3036             : 
    3037             : /**
    3038             :  * Get the identify namespace data as defined by the NVMe specification.
    3039             :  *
    3040             :  * This function is thread safe and can be called at any point while the controller
    3041             :  * is attached to the SPDK NVMe driver.
    3042             :  *
    3043             :  * \param ns Namespace.
    3044             :  *
    3045             :  * \return a pointer to the namespace data.
    3046             :  */
    3047             : const struct spdk_nvme_ns_data *spdk_nvme_ns_get_data(struct spdk_nvme_ns *ns);
    3048             : 
    3049             : /**
    3050             :  * Get the I/O command set specific identify namespace data for NVM command set
    3051             :  * as defined by the NVMe specification.
    3052             :  *
    3053             :  * This function is thread safe and can be called at any point while the controller
    3054             :  * is attached to the SPDK NVMe driver.
    3055             :  *
    3056             :  * \param ns Namespace.
    3057             :  *
    3058             :  * \return a pointer to the identify namespace data.
    3059             :  */
    3060             : const struct spdk_nvme_nvm_ns_data *spdk_nvme_nvm_ns_get_data(struct spdk_nvme_ns *ns);
    3061             : 
    3062             : /**
    3063             :  * Get the namespace id (index number) from the given namespace handle.
    3064             :  *
    3065             :  * This function is thread safe and can be called at any point while the controller
    3066             :  * is attached to the SPDK NVMe driver.
    3067             :  *
    3068             :  * \param ns Namespace.
    3069             :  *
    3070             :  * \return namespace id.
    3071             :  */
    3072             : uint32_t spdk_nvme_ns_get_id(struct spdk_nvme_ns *ns);
    3073             : 
    3074             : /**
    3075             :  * Get the controller with which this namespace is associated.
    3076             :  *
    3077             :  * This function is thread safe and can be called at any point while the controller
    3078             :  * is attached to the SPDK NVMe driver.
    3079             :  *
    3080             :  * \param ns Namespace.
    3081             :  *
    3082             :  * \return a pointer to the controller.
    3083             :  */
    3084             : struct spdk_nvme_ctrlr *spdk_nvme_ns_get_ctrlr(struct spdk_nvme_ns *ns);
    3085             : 
    3086             : /**
    3087             :  * Determine whether a namespace is active.
    3088             :  *
    3089             :  * Inactive namespaces cannot be the target of I/O commands.
    3090             :  *
    3091             :  * \param ns Namespace to query.
    3092             :  *
    3093             :  * \return true if active, or false if inactive.
    3094             :  */
    3095             : bool spdk_nvme_ns_is_active(struct spdk_nvme_ns *ns);
    3096             : 
    3097             : /**
    3098             :  * Get the maximum transfer size, in bytes, for an I/O sent to the given namespace.
    3099             :  *
    3100             :  * This function is thread safe and can be called at any point while the controller
    3101             :  * is attached to the SPDK NVMe driver.
    3102             :  *
    3103             :  * \param ns Namespace to query.
    3104             :  *
    3105             :  * \return the maximum transfer size in bytes.
    3106             :  */
    3107             : uint32_t spdk_nvme_ns_get_max_io_xfer_size(struct spdk_nvme_ns *ns);
    3108             : 
    3109             : /**
    3110             :  * Get the sector size, in bytes, of the given namespace.
    3111             :  *
    3112             :  * This function returns the size of the data sector only.  It does not
    3113             :  * include metadata size.
    3114             :  *
    3115             :  * This function is thread safe and can be called at any point while the controller
    3116             :  * is attached to the SPDK NVMe driver.
    3117             :  *
    3118             :  * \param ns Namespace to query.
    3119             :  *
    3120             :  * /return the sector size in bytes.
    3121             :  */
    3122             : uint32_t spdk_nvme_ns_get_sector_size(struct spdk_nvme_ns *ns);
    3123             : 
    3124             : /**
    3125             :  * Get the extended sector size, in bytes, of the given namespace.
    3126             :  *
    3127             :  * This function returns the size of the data sector plus metadata.
    3128             :  *
    3129             :  * This function is thread safe and can be called at any point while the controller
    3130             :  * is attached to the SPDK NVMe driver.
    3131             :  *
    3132             :  * \param ns Namespace to query.
    3133             :  *
    3134             :  * /return the extended sector size in bytes.
    3135             :  */
    3136             : uint32_t spdk_nvme_ns_get_extended_sector_size(struct spdk_nvme_ns *ns);
    3137             : 
    3138             : /**
    3139             :  * Get the number of sectors for the given namespace.
    3140             :  *
    3141             :  * This function is thread safe and can be called at any point while the controller
    3142             :  * is attached to the SPDK NVMe driver.
    3143             :  *
    3144             :  * \param ns Namespace to query.
    3145             :  *
    3146             :  * \return the number of sectors.
    3147             :  */
    3148             : uint64_t spdk_nvme_ns_get_num_sectors(struct spdk_nvme_ns *ns);
    3149             : 
    3150             : /**
    3151             :  * Get the size, in bytes, of the given namespace.
    3152             :  *
    3153             :  * This function is thread safe and can be called at any point while the controller
    3154             :  * is attached to the SPDK NVMe driver.
    3155             :  *
    3156             :  * \param ns Namespace to query.
    3157             :  *
    3158             :  * \return the size of the given namespace in bytes.
    3159             :  */
    3160             : uint64_t spdk_nvme_ns_get_size(struct spdk_nvme_ns *ns);
    3161             : 
    3162             : /**
    3163             :  * Get the end-to-end data protection information type of the given namespace.
    3164             :  *
    3165             :  * This function is thread safe and can be called at any point while the controller
    3166             :  * is attached to the SPDK NVMe driver.
    3167             :  *
    3168             :  * \param ns Namespace to query.
    3169             :  *
    3170             :  * \return the end-to-end data protection information type.
    3171             :  */
    3172             : enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type(struct spdk_nvme_ns *ns);
    3173             : 
    3174             : /**
    3175             :  * Get the end-to-end data protection information format of the given namespace.
    3176             :  *
    3177             :  * This function is thread safe and can be called at any point while the controller
    3178             :  * is attached to the SPDK NVMe driver.
    3179             :  *
    3180             :  * \param ns Namespace to query.
    3181             :  *
    3182             :  * \return the end-to-end data protection information format.
    3183             :  */
    3184             : enum spdk_nvme_pi_format spdk_nvme_ns_get_pi_format(struct spdk_nvme_ns *ns);
    3185             : 
    3186             : /**
    3187             :  * Get the metadata size, in bytes, of the given namespace.
    3188             :  *
    3189             :  * This function is thread safe and can be called at any point while the controller
    3190             :  * is attached to the SPDK NVMe driver.
    3191             :  *
    3192             :  * \param ns Namespace to query.
    3193             :  *
    3194             :  * \return the metadata size of the given namespace in bytes.
    3195             :  */
    3196             : uint32_t spdk_nvme_ns_get_md_size(struct spdk_nvme_ns *ns);
    3197             : 
    3198             : /**
    3199             :  * Get the format index of the given namespace.
    3200             :  *
    3201             :  * This function is thread safe and can be called at any point while the controller
    3202             :  * is attached to the SPDK NVMe driver.
    3203             :  *
    3204             :  * \param nsdata pointer to the NVMe namespace data.
    3205             :  *
    3206             :  * \return the format index of the given namespace.
    3207             :  */
    3208             : uint32_t spdk_nvme_ns_get_format_index(const struct spdk_nvme_ns_data *nsdata);
    3209             : 
    3210             : /**
    3211             :  * Check whether if the namespace can support extended LBA when end-to-end data
    3212             :  * protection enabled.
    3213             :  *
    3214             :  * This function is thread safe and can be called at any point while the controller
    3215             :  * is attached to the SPDK NVMe driver.
    3216             :  *
    3217             :  * \param ns Namespace to query.
    3218             :  *
    3219             :  * \return true if the namespace can support extended LBA when end-to-end data
    3220             :  * protection enabled, or false otherwise.
    3221             :  */
    3222             : bool spdk_nvme_ns_supports_extended_lba(struct spdk_nvme_ns *ns);
    3223             : 
    3224             : /**
    3225             :  * Check whether if the namespace supports compare operation
    3226             :  *
    3227             :  * This function is thread safe and can be called at any point while the controller
    3228             :  * is attached to the SPDK NVMe driver.
    3229             :  *
    3230             :  * \param ns Namespace to query.
    3231             :  *
    3232             :  * \return true if the namespace supports compare operation, or false otherwise.
    3233             :  */
    3234             : bool spdk_nvme_ns_supports_compare(struct spdk_nvme_ns *ns);
    3235             : 
    3236             : /**
    3237             :  * Determine the value returned when reading deallocated blocks.
    3238             :  *
    3239             :  * If deallocated blocks return 0, the deallocate command can be used as a more
    3240             :  * efficient alternative to the write_zeroes command, especially for large requests.
    3241             :  *
    3242             :  * \param ns Namespace.
    3243             :  *
    3244             :  * \return the logical block read value.
    3245             :  */
    3246             : enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value(
    3247             :         struct spdk_nvme_ns *ns);
    3248             : 
    3249             : /**
    3250             :  * Get the optimal I/O boundary, in blocks, for the given namespace.
    3251             :  *
    3252             :  * Read and write commands should not cross the optimal I/O boundary for best
    3253             :  * performance.
    3254             :  *
    3255             :  * \param ns Namespace to query.
    3256             :  *
    3257             :  * \return Optimal granularity of I/O commands, in blocks, or 0 if no optimal
    3258             :  * granularity is reported.
    3259             :  */
    3260             : uint32_t spdk_nvme_ns_get_optimal_io_boundary(struct spdk_nvme_ns *ns);
    3261             : 
    3262             : /**
    3263             :  * Get the NGUID for the given namespace.
    3264             :  *
    3265             :  * \param ns Namespace to query.
    3266             :  *
    3267             :  * \return a pointer to namespace NGUID, or NULL if ns does not have a NGUID.
    3268             :  */
    3269             : const uint8_t *spdk_nvme_ns_get_nguid(const struct spdk_nvme_ns *ns);
    3270             : 
    3271             : /**
    3272             :  * Get the UUID for the given namespace.
    3273             :  *
    3274             :  * \param ns Namespace to query.
    3275             :  *
    3276             :  * \return a pointer to namespace UUID, or NULL if ns does not have a UUID.
    3277             :  */
    3278             : const struct spdk_uuid *spdk_nvme_ns_get_uuid(const struct spdk_nvme_ns *ns);
    3279             : 
    3280             : /**
    3281             :  * Get the Command Set Identifier for the given namespace.
    3282             :  *
    3283             :  * \param ns Namespace to query.
    3284             :  *
    3285             :  * \return the namespace Command Set Identifier.
    3286             :  */
    3287             : enum spdk_nvme_csi spdk_nvme_ns_get_csi(const struct spdk_nvme_ns *ns);
    3288             : 
    3289             : /**
    3290             :  * \brief Namespace command support flags.
    3291             :  */
    3292             : enum spdk_nvme_ns_flags {
    3293             :         SPDK_NVME_NS_DEALLOCATE_SUPPORTED       = 1 << 0, /**< The deallocate command is supported */
    3294             :         SPDK_NVME_NS_FLUSH_SUPPORTED            = 1 << 1, /**< The flush command is supported */
    3295             :         SPDK_NVME_NS_RESERVATION_SUPPORTED      = 1 << 2, /**< The reservation command is supported */
    3296             :         SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED     = 1 << 3, /**< The write zeroes command is supported */
    3297             :         SPDK_NVME_NS_DPS_PI_SUPPORTED           = 1 << 4, /**< The end-to-end data protection is supported */
    3298             :         SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED     = 1 << 5, /**< The extended lba format is supported,
    3299             :                                                               metadata is transferred as a contiguous
    3300             :                                                               part of the logical block that it is associated with */
    3301             :         SPDK_NVME_NS_WRITE_UNCORRECTABLE_SUPPORTED      = 1 << 6, /**< The write uncorrectable command is supported */
    3302             :         SPDK_NVME_NS_COMPARE_SUPPORTED          = 1 << 7, /**< The compare command is supported */
    3303             : };
    3304             : 
    3305             : /**
    3306             :  * Get the flags for the given namespace.
    3307             :  *
    3308             :  * See spdk_nvme_ns_flags for the possible flags returned.
    3309             :  *
    3310             :  * This function is thread safe and can be called at any point while the controller
    3311             :  * is attached to the SPDK NVMe driver.
    3312             :  *
    3313             :  * \param ns Namespace to query.
    3314             :  *
    3315             :  * \return the flags for the given namespace.
    3316             :  */
    3317             : uint32_t spdk_nvme_ns_get_flags(struct spdk_nvme_ns *ns);
    3318             : 
    3319             : /**
    3320             :  * Get the ANA group ID for the given namespace.
    3321             :  *
    3322             :  * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
    3323             :  * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
    3324             :  *
    3325             :  * This function is thread safe and can be called at any point while the controller
    3326             :  * is attached to the SPDK NVMe driver.
    3327             :  *
    3328             :  * \param ns Namespace to query.
    3329             :  *
    3330             :  * \return the ANA group ID for the given namespace.
    3331             :  */
    3332             : uint32_t spdk_nvme_ns_get_ana_group_id(const struct spdk_nvme_ns *ns);
    3333             : 
    3334             : /**
    3335             :  * Get the ANA state for the given namespace.
    3336             :  *
    3337             :  * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
    3338             :  * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
    3339             :  *
    3340             :  * This function is thread safe and can be called at any point while the controller
    3341             :  * is attached to the SPDK NVMe driver.
    3342             :  *
    3343             :  * \param ns Namespace to query.
    3344             :  *
    3345             :  * \return the ANA state for the given namespace.
    3346             :  */
    3347             : enum spdk_nvme_ana_state spdk_nvme_ns_get_ana_state(const struct spdk_nvme_ns *ns);
    3348             : 
    3349             : /**
    3350             :  * Submit a write I/O to the specified NVMe namespace.
    3351             :  *
    3352             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3353             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3354             :  * given time.
    3355             :  *
    3356             :  * \param ns NVMe namespace to submit the write I/O.
    3357             :  * \param qpair I/O queue pair to submit the request.
    3358             :  * \param payload Virtual address pointer to the data payload.
    3359             :  * \param lba Starting LBA to write the data.
    3360             :  * \param lba_count Length (in sectors) for the write operation.
    3361             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3362             :  * \param cb_arg Argument to pass to the callback function.
    3363             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3364             :  * spdk/nvme_spec.h, for this I/O.
    3365             :  *
    3366             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3367             :  * -EINVAL: The request is malformed.
    3368             :  * -ENOMEM: The request cannot be allocated.
    3369             :  * -ENXIO: The qpair is failed at the transport level.
    3370             :  */
    3371             : int spdk_nvme_ns_cmd_write(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3372             :                            uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3373             :                            void *cb_arg, uint32_t io_flags);
    3374             : 
    3375             : /**
    3376             :  * Submit a write I/O to the specified NVMe namespace.
    3377             :  *
    3378             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3379             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3380             :  * given time.
    3381             :  *
    3382             :  * \param ns NVMe namespace to submit the write I/O.
    3383             :  * \param qpair I/O queue pair to submit the request.
    3384             :  * \param lba Starting LBA to write the data.
    3385             :  * \param lba_count Length (in sectors) for the write operation.
    3386             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3387             :  * \param cb_arg Argument to pass to the callback function.
    3388             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3389             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3390             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3391             :  * segment.
    3392             :  *
    3393             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3394             :  * -EINVAL: The request is malformed.
    3395             :  * -ENOMEM: The request cannot be allocated.
    3396             :  * -ENXIO: The qpair is failed at the transport level.
    3397             :  */
    3398             : int spdk_nvme_ns_cmd_writev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3399             :                             uint64_t lba, uint32_t lba_count,
    3400             :                             spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3401             :                             spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3402             :                             spdk_nvme_req_next_sge_cb next_sge_fn);
    3403             : 
    3404             : /**
    3405             :  * Submit a write I/O to the specified NVMe namespace.
    3406             :  *
    3407             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3408             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3409             :  * given time.
    3410             :  *
    3411             :  * \param ns NVMe namespace to submit the write I/O
    3412             :  * \param qpair I/O queue pair to submit the request
    3413             :  * \param lba starting LBA to write the data
    3414             :  * \param lba_count length (in sectors) for the write operation
    3415             :  * \param cb_fn callback function to invoke when the I/O is completed
    3416             :  * \param cb_arg argument to pass to the callback function
    3417             :  * \param io_flags set flags, defined in nvme_spec.h, for this I/O
    3418             :  * \param reset_sgl_fn callback function to reset scattered payload
    3419             :  * \param next_sge_fn callback function to iterate each scattered
    3420             :  * payload memory segment
    3421             :  * \param metadata virtual address pointer to the metadata payload, the length
    3422             :  * of metadata is specified by spdk_nvme_ns_get_md_size()
    3423             :  * \param apptag_mask application tag mask.
    3424             :  * \param apptag application tag to use end-to-end protection information.
    3425             :  *
    3426             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3427             :  * -EINVAL: The request is malformed.
    3428             :  * -ENOMEM: The request cannot be allocated.
    3429             :  * -ENXIO: The qpair is failed at the transport level.
    3430             :  */
    3431             : int spdk_nvme_ns_cmd_writev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3432             :                                     uint64_t lba, uint32_t lba_count,
    3433             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3434             :                                     spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3435             :                                     spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    3436             :                                     uint16_t apptag_mask, uint16_t apptag);
    3437             : 
    3438             : /**
    3439             :  * Submit a write I/O to the specified NVMe namespace.
    3440             :  *
    3441             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3442             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3443             :  * given time.
    3444             :  *
    3445             :  * \param ns NVMe namespace to submit the write I/O
    3446             :  * \param qpair I/O queue pair to submit the request
    3447             :  * \param lba starting LBA to write the data
    3448             :  * \param lba_count length (in sectors) for the write operation
    3449             :  * \param cb_fn callback function to invoke when the I/O is completed
    3450             :  * \param cb_arg argument to pass to the callback function
    3451             :  * \param reset_sgl_fn callback function to reset scattered payload
    3452             :  * \param next_sge_fn callback function to iterate each scattered
    3453             :  * payload memory segment
    3454             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3455             :  * guarantee that this structure is accessible until IO completes
    3456             :  *
    3457             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3458             :  * -EINVAL: The request is malformed.
    3459             :  * -ENOMEM: The request cannot be allocated.
    3460             :  * -ENXIO: The qpair is failed at the transport level.
    3461             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3462             :  *          with error status including dnr=1 in this case.
    3463             :  */
    3464             : int spdk_nvme_ns_cmd_writev_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3465             :                                 uint64_t lba, uint32_t lba_count,
    3466             :                                 spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3467             :                                 spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3468             :                                 spdk_nvme_req_next_sge_cb next_sge_fn,
    3469             :                                 struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3470             : 
    3471             : /**
    3472             :  * Submit a write I/O to the specified NVMe namespace.
    3473             :  *
    3474             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3475             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3476             :  * given time.
    3477             :  *
    3478             :  * \param ns NVMe namespace to submit the write I/O
    3479             :  * \param qpair I/O queue pair to submit the request
    3480             :  * \param payload Virtual address pointer to the data payload.
    3481             :  * \param lba starting LBA to write the data
    3482             :  * \param lba_count length (in sectors) for the write operation
    3483             :  * \param cb_fn callback function to invoke when the I/O is completed
    3484             :  * \param cb_arg argument to pass to the callback function
    3485             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3486             :  * guarantee that this structure is accessible until IO completes
    3487             :  *
    3488             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3489             :  * -EINVAL: The request is malformed.
    3490             :  * -ENOMEM: The request cannot be allocated.
    3491             :  * -ENXIO: The qpair is failed at the transport level.
    3492             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3493             :  *          with error status including dnr=1 in this case.
    3494             :  */
    3495             : int spdk_nvme_ns_cmd_write_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3496             :                                void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3497             :                                struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3498             : 
    3499             : /**
    3500             :  * Submit a write I/O to the specified NVMe namespace.
    3501             :  *
    3502             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3503             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3504             :  * given time.
    3505             :  *
    3506             :  * \param ns NVMe namespace to submit the write I/O.
    3507             :  * \param qpair I/O queue pair to submit the request.
    3508             :  * \param payload Virtual address pointer to the data payload.
    3509             :  * \param metadata Virtual address pointer to the metadata payload, the length
    3510             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    3511             :  * \param lba Starting LBA to write the data.
    3512             :  * \param lba_count Length (in sectors) for the write operation.
    3513             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3514             :  * \param cb_arg Argument to pass to the callback function.
    3515             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3516             :  * spdk/nvme_spec.h, for this I/O.
    3517             :  * \param apptag_mask Application tag mask.
    3518             :  * \param apptag Application tag to use end-to-end protection information.
    3519             :  *
    3520             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3521             :  * -EINVAL: The request is malformed.
    3522             :  * -ENOMEM: The request cannot be allocated.
    3523             :  * -ENXIO: The qpair is failed at the transport level.
    3524             :  */
    3525             : int spdk_nvme_ns_cmd_write_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3526             :                                    void *payload, void *metadata,
    3527             :                                    uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3528             :                                    void *cb_arg, uint32_t io_flags,
    3529             :                                    uint16_t apptag_mask, uint16_t apptag);
    3530             : 
    3531             : /**
    3532             :  * Submit a write zeroes I/O to the specified NVMe namespace.
    3533             :  *
    3534             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3535             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3536             :  * given time.
    3537             :  *
    3538             :  * \param ns NVMe namespace to submit the write zeroes I/O.
    3539             :  * \param qpair I/O queue pair to submit the request.
    3540             :  * \param lba Starting LBA for this command.
    3541             :  * \param lba_count Length (in sectors) for the write zero operation.
    3542             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3543             :  * \param cb_arg Argument to pass to the callback function.
    3544             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3545             :  * spdk/nvme_spec.h, for this I/O.
    3546             :  *
    3547             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3548             :  * -EINVAL: The request is malformed.
    3549             :  * -ENOMEM: The request cannot be allocated.
    3550             :  * -ENXIO: The qpair is failed at the transport level.
    3551             :  */
    3552             : int spdk_nvme_ns_cmd_write_zeroes(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3553             :                                   uint64_t lba, uint32_t lba_count,
    3554             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3555             :                                   uint32_t io_flags);
    3556             : 
    3557             : /**
    3558             :  * Submit a verify I/O to the specified NVMe namespace.
    3559             :  *
    3560             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3561             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3562             :  * given time.
    3563             :  *
    3564             :  * \param ns NVMe namespace to submit the verify I/O.
    3565             :  * \param qpair I/O queue pair to submit the request.
    3566             :  * \param lba Starting LBA to verify the data.
    3567             :  * \param lba_count Length (in sectors) for the verify operation.
    3568             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3569             :  * \param cb_arg Argument to pass to the callback function.
    3570             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3571             :  * spdk/nvme_spec.h, for this I/O.
    3572             :  *
    3573             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3574             :  * -EINVAL: The request is malformed.
    3575             :  * -ENOMEM: The request cannot be allocated.
    3576             :  * -ENXIO: The qpair is failed at the transport level.
    3577             :  */
    3578             : int spdk_nvme_ns_cmd_verify(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3579             :                             uint64_t lba, uint32_t lba_count,
    3580             :                             spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3581             :                             uint32_t io_flags);
    3582             : 
    3583             : /**
    3584             :  * Submit a write uncorrectable I/O to the specified NVMe namespace.
    3585             :  *
    3586             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3587             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3588             :  * given time.
    3589             :  *
    3590             :  * \param ns NVMe namespace to submit the write uncorrectable I/O.
    3591             :  * \param qpair I/O queue pair to submit the request.
    3592             :  * \param lba Starting LBA for this command.
    3593             :  * \param lba_count Length (in sectors) for the write uncorrectable operation.
    3594             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3595             :  * \param cb_arg Argument to pass to the callback function.
    3596             :  *
    3597             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3598             :  * -EINVAL: The request is malformed.
    3599             :  * -ENOMEM: The request cannot be allocated.
    3600             :  * -ENXIO: The qpair is failed at the transport level.
    3601             :  */
    3602             : int spdk_nvme_ns_cmd_write_uncorrectable(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3603             :                 uint64_t lba, uint32_t lba_count,
    3604             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3605             : 
    3606             : /**
    3607             :  * \brief Submits a read I/O to the specified NVMe namespace.
    3608             :  *
    3609             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3610             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3611             :  * given time.
    3612             :  *
    3613             :  * \param ns NVMe namespace to submit the read I/O.
    3614             :  * \param qpair I/O queue pair to submit the request.
    3615             :  * \param payload Virtual address pointer to the data payload.
    3616             :  * \param lba Starting LBA to read the data.
    3617             :  * \param lba_count Length (in sectors) for the read operation.
    3618             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3619             :  * \param cb_arg Argument to pass to the callback function.
    3620             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3621             :  *
    3622             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3623             :  * -EINVAL: The request is malformed.
    3624             :  * -ENOMEM: The request cannot be allocated.
    3625             :  * -ENXIO: The qpair is failed at the transport level.
    3626             :  */
    3627             : int spdk_nvme_ns_cmd_read(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3628             :                           uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3629             :                           void *cb_arg, uint32_t io_flags);
    3630             : 
    3631             : /**
    3632             :  * Submit a read I/O to the specified NVMe namespace.
    3633             :  *
    3634             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3635             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3636             :  * given time.
    3637             :  *
    3638             :  * \param ns NVMe namespace to submit the read I/O.
    3639             :  * \param qpair I/O queue pair to submit the request.
    3640             :  * \param lba Starting LBA to read the data.
    3641             :  * \param lba_count Length (in sectors) for the read operation.
    3642             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3643             :  * \param cb_arg Argument to pass to the callback function.
    3644             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3645             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3646             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3647             :  * segment.
    3648             :  *
    3649             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3650             :  * -EINVAL: The request is malformed.
    3651             :  * -ENOMEM: The request cannot be allocated.
    3652             :  * -ENXIO: The qpair is failed at the transport level.
    3653             :  */
    3654             : int spdk_nvme_ns_cmd_readv(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3655             :                            uint64_t lba, uint32_t lba_count,
    3656             :                            spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3657             :                            spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3658             :                            spdk_nvme_req_next_sge_cb next_sge_fn);
    3659             : 
    3660             : /**
    3661             :  * Submit a read I/O to the specified NVMe namespace.
    3662             :  *
    3663             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3664             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3665             :  *
    3666             :  * \param ns NVMe namespace to submit the read I/O
    3667             :  * \param qpair I/O queue pair to submit the request
    3668             :  * \param lba starting LBA to read the data
    3669             :  * \param lba_count length (in sectors) for the read operation
    3670             :  * \param cb_fn callback function to invoke when the I/O is completed
    3671             :  * \param cb_arg argument to pass to the callback function
    3672             :  * \param io_flags set flags, defined in nvme_spec.h, for this I/O
    3673             :  * \param reset_sgl_fn callback function to reset scattered payload
    3674             :  * \param next_sge_fn callback function to iterate each scattered
    3675             :  * payload memory segment
    3676             :  * \param metadata virtual address pointer to the metadata payload, the length
    3677             :  *                 of metadata is specified by spdk_nvme_ns_get_md_size()
    3678             :  * \param apptag_mask application tag mask.
    3679             :  * \param apptag application tag to use end-to-end protection information.
    3680             :  *
    3681             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3682             :  * -EINVAL: The request is malformed.
    3683             :  * -ENOMEM: The request cannot be allocated.
    3684             :  * -ENXIO: The qpair is failed at the transport level.
    3685             :  */
    3686             : int spdk_nvme_ns_cmd_readv_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3687             :                                    uint64_t lba, uint32_t lba_count,
    3688             :                                    spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3689             :                                    spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3690             :                                    spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    3691             :                                    uint16_t apptag_mask, uint16_t apptag);
    3692             : 
    3693             : /**
    3694             :  * Submit a read I/O to the specified NVMe namespace.
    3695             :  *
    3696             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3697             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3698             :  *
    3699             :  * \param ns NVMe namespace to submit the read I/O
    3700             :  * \param qpair I/O queue pair to submit the request
    3701             :  * \param lba starting LBA to read the data
    3702             :  * \param lba_count length (in sectors) for the read operation
    3703             :  * \param cb_fn callback function to invoke when the I/O is completed
    3704             :  * \param cb_arg argument to pass to the callback function
    3705             :  * \param reset_sgl_fn callback function to reset scattered payload
    3706             :  * \param next_sge_fn callback function to iterate each scattered
    3707             :  * payload memory segment
    3708             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3709             :  * guarantee that this structure is accessible until IO completes
    3710             :  *
    3711             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3712             :  * -EINVAL: The request is malformed.
    3713             :  * -ENOMEM: The request cannot be allocated.
    3714             :  * -ENXIO: The qpair is failed at the transport level.
    3715             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3716             :  *          with error status including dnr=1 in this case.
    3717             :  */
    3718             : int spdk_nvme_ns_cmd_readv_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3719             :                                uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3720             :                                void *cb_arg, spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3721             :                                spdk_nvme_req_next_sge_cb next_sge_fn,
    3722             :                                struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3723             : 
    3724             : /**
    3725             :  * Submit a read I/O to the specified NVMe namespace.
    3726             :  *
    3727             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3728             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3729             :  *
    3730             :  * \param ns NVMe namespace to submit the read I/O
    3731             :  * \param qpair I/O queue pair to submit the request
    3732             :  * \param payload virtual address pointer to the data payload
    3733             :  * \param lba starting LBA to read the data
    3734             :  * \param lba_count length (in sectors) for the read operation
    3735             :  * \param cb_fn callback function to invoke when the I/O is completed
    3736             :  * \param cb_arg argument to pass to the callback function
    3737             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3738             :  * guarantee that this structure is accessible until IO completes
    3739             :  *
    3740             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3741             :  * -EINVAL: The request is malformed.
    3742             :  * -ENOMEM: The request cannot be allocated.
    3743             :  * -ENXIO: The qpair is failed at the transport level.
    3744             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3745             :  *          with error status including dnr=1 in this case.
    3746             :  */
    3747             : int spdk_nvme_ns_cmd_read_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3748             :                               uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3749             :                               struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3750             : 
    3751             : /**
    3752             :  * Submits a read I/O to the specified NVMe namespace.
    3753             :  *
    3754             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3755             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3756             :  * given time.
    3757             :  *
    3758             :  * \param ns NVMe namespace to submit the read I/O
    3759             :  * \param qpair I/O queue pair to submit the request
    3760             :  * \param payload virtual address pointer to the data payload
    3761             :  * \param metadata virtual address pointer to the metadata payload, the length
    3762             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    3763             :  * \param lba starting LBA to read the data.
    3764             :  * \param lba_count Length (in sectors) for the read operation.
    3765             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3766             :  * \param cb_arg Argument to pass to the callback function.
    3767             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3768             :  * \param apptag_mask Application tag mask.
    3769             :  * \param apptag Application tag to use end-to-end protection information.
    3770             :  *
    3771             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3772             :  * -EINVAL: The request is malformed.
    3773             :  * -ENOMEM: The request cannot be allocated.
    3774             :  * -ENXIO: The qpair is failed at the transport level.
    3775             :  */
    3776             : int spdk_nvme_ns_cmd_read_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3777             :                                   void *payload, void *metadata,
    3778             :                                   uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3779             :                                   void *cb_arg, uint32_t io_flags,
    3780             :                                   uint16_t apptag_mask, uint16_t apptag);
    3781             : 
    3782             : /**
    3783             :  * Submit a data set management request to the specified NVMe namespace.
    3784             :  *
    3785             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3786             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3787             :  * given time.
    3788             :  *
    3789             :  * This is a convenience wrapper that will automatically allocate and construct
    3790             :  * the correct data buffers. Therefore, ranges does not need to be allocated from
    3791             :  * pinned memory and can be placed on the stack. If a higher performance, zero-copy
    3792             :  * version of DSM is required, simply build and submit a raw command using
    3793             :  * spdk_nvme_ctrlr_cmd_io_raw().
    3794             :  *
    3795             :  * \param ns NVMe namespace to submit the DSM request
    3796             :  * \param type A bit field constructed from \ref spdk_nvme_dsm_attribute.
    3797             :  * \param qpair I/O queue pair to submit the request
    3798             :  * \param ranges An array of \ref spdk_nvme_dsm_range elements describing the LBAs
    3799             :  * to operate on.
    3800             :  * \param num_ranges The number of elements in the ranges array.
    3801             :  * \param cb_fn Callback function to invoke when the I/O is completed
    3802             :  * \param cb_arg Argument to pass to the callback function
    3803             :  *
    3804             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3805             :  * -ENOMEM: The request cannot be allocated.
    3806             :  * -ENXIO: The qpair is failed at the transport level.
    3807             :  */
    3808             : int spdk_nvme_ns_cmd_dataset_management(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3809             :                                         uint32_t type,
    3810             :                                         const struct spdk_nvme_dsm_range *ranges,
    3811             :                                         uint16_t num_ranges,
    3812             :                                         spdk_nvme_cmd_cb cb_fn,
    3813             :                                         void *cb_arg);
    3814             : 
    3815             : /**
    3816             :  * Submit a simple copy command request to the specified NVMe namespace.
    3817             :  *
    3818             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3819             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3820             :  * given time.
    3821             :  *
    3822             :  * This is a convenience wrapper that will automatically allocate and construct
    3823             :  * the correct data buffers. Therefore, ranges does not need to be allocated from
    3824             :  * pinned memory and can be placed on the stack. If a higher performance, zero-copy
    3825             :  * version of SCC is required, simply build and submit a raw command using
    3826             :  * spdk_nvme_ctrlr_cmd_io_raw().
    3827             :  *
    3828             :  * \param ns NVMe namespace to submit the SCC request
    3829             :  * \param qpair I/O queue pair to submit the request
    3830             :  * \param ranges An array of \ref spdk_nvme_scc_source_range elements describing the LBAs
    3831             :  * to operate on.
    3832             :  * \param num_ranges The number of elements in the ranges array.
    3833             :  * \param dest_lba Destination LBA to copy the data.
    3834             :  * \param cb_fn Callback function to invoke when the I/O is completed
    3835             :  * \param cb_arg Argument to pass to the callback function
    3836             :  *
    3837             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3838             :  * -ENOMEM: The request cannot be allocated.
    3839             :  * -EINVAL: Invalid ranges.
    3840             :  * -ENXIO: The qpair is failed at the transport level.
    3841             :  */
    3842             : int spdk_nvme_ns_cmd_copy(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3843             :                           const struct spdk_nvme_scc_source_range *ranges,
    3844             :                           uint16_t num_ranges,
    3845             :                           uint64_t dest_lba,
    3846             :                           spdk_nvme_cmd_cb cb_fn,
    3847             :                           void *cb_arg);
    3848             : 
    3849             : /**
    3850             :  * Submit a flush request to the specified NVMe namespace.
    3851             :  *
    3852             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3853             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3854             :  * given time.
    3855             :  *
    3856             :  * \param ns NVMe namespace to submit the flush request.
    3857             :  * \param qpair I/O queue pair to submit the request.
    3858             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3859             :  * \param cb_arg Argument to pass to the callback function.
    3860             :  *
    3861             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3862             :  * -ENOMEM: The request cannot be allocated.
    3863             :  * -ENXIO: The qpair is failed at the transport level.
    3864             :  */
    3865             : int spdk_nvme_ns_cmd_flush(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3866             :                            spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3867             : 
    3868             : /**
    3869             :  * Submit a reservation register to the specified NVMe namespace.
    3870             :  *
    3871             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3872             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3873             :  * given time.
    3874             :  *
    3875             :  * \param ns NVMe namespace to submit the reservation register request.
    3876             :  * \param qpair I/O queue pair to submit the request.
    3877             :  * \param payload Virtual address pointer to the reservation register data.
    3878             :  * \param ignore_key '1' the current reservation key check is disabled.
    3879             :  * \param action Specifies the registration action.
    3880             :  * \param cptpl Change the Persist Through Power Loss state.
    3881             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3882             :  * \param cb_arg Argument to pass to the callback function.
    3883             :  *
    3884             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3885             :  * -ENOMEM: The request cannot be allocated.
    3886             :  * -ENXIO: The qpair is failed at the transport level.
    3887             :  */
    3888             : int spdk_nvme_ns_cmd_reservation_register(struct spdk_nvme_ns *ns,
    3889             :                 struct spdk_nvme_qpair *qpair,
    3890             :                 struct spdk_nvme_reservation_register_data *payload,
    3891             :                 bool ignore_key,
    3892             :                 enum spdk_nvme_reservation_register_action action,
    3893             :                 enum spdk_nvme_reservation_register_cptpl cptpl,
    3894             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3895             : 
    3896             : /**
    3897             :  * Submits a reservation release to the specified NVMe namespace.
    3898             :  *
    3899             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3900             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3901             :  * given time.
    3902             :  *
    3903             :  * \param ns NVMe namespace to submit the reservation release request.
    3904             :  * \param qpair I/O queue pair to submit the request.
    3905             :  * \param payload Virtual address pointer to current reservation key.
    3906             :  * \param ignore_key '1' the current reservation key check is disabled.
    3907             :  * \param action Specifies the reservation release action.
    3908             :  * \param type Reservation type for the namespace.
    3909             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3910             :  * \param cb_arg Argument to pass to the callback function.
    3911             :  *
    3912             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3913             :  * -ENOMEM: The request cannot be allocated.
    3914             :  * -ENXIO: The qpair is failed at the transport level.
    3915             :  */
    3916             : int spdk_nvme_ns_cmd_reservation_release(struct spdk_nvme_ns *ns,
    3917             :                 struct spdk_nvme_qpair *qpair,
    3918             :                 struct spdk_nvme_reservation_key_data *payload,
    3919             :                 bool ignore_key,
    3920             :                 enum spdk_nvme_reservation_release_action action,
    3921             :                 enum spdk_nvme_reservation_type type,
    3922             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3923             : 
    3924             : /**
    3925             :  * Submits a reservation acquire to the specified NVMe namespace.
    3926             :  *
    3927             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3928             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3929             :  * given time.
    3930             :  *
    3931             :  * \param ns NVMe namespace to submit the reservation acquire request.
    3932             :  * \param qpair I/O queue pair to submit the request.
    3933             :  * \param payload Virtual address pointer to reservation acquire data.
    3934             :  * \param ignore_key '1' the current reservation key check is disabled.
    3935             :  * \param action Specifies the reservation acquire action.
    3936             :  * \param type Reservation type for the namespace.
    3937             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3938             :  * \param cb_arg Argument to pass to the callback function.
    3939             :  *
    3940             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3941             :  * -ENOMEM: The request cannot be allocated.
    3942             :  * -ENXIO: The qpair is failed at the transport level.
    3943             :  */
    3944             : int spdk_nvme_ns_cmd_reservation_acquire(struct spdk_nvme_ns *ns,
    3945             :                 struct spdk_nvme_qpair *qpair,
    3946             :                 struct spdk_nvme_reservation_acquire_data *payload,
    3947             :                 bool ignore_key,
    3948             :                 enum spdk_nvme_reservation_acquire_action action,
    3949             :                 enum spdk_nvme_reservation_type type,
    3950             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3951             : 
    3952             : /**
    3953             :  * Submit a reservation report to the specified NVMe namespace.
    3954             :  *
    3955             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3956             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3957             :  * given time.
    3958             :  *
    3959             :  * \param ns NVMe namespace to submit the reservation report request.
    3960             :  * \param qpair I/O queue pair to submit the request.
    3961             :  * \param payload Virtual address pointer for reservation status data.
    3962             :  * \param len Length bytes for reservation status data structure.
    3963             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3964             :  * \param cb_arg Argument to pass to the callback function.
    3965             :  *
    3966             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3967             :  * -ENOMEM: The request cannot be allocated.
    3968             :  * -ENXIO: The qpair is failed at the transport level.
    3969             :  */
    3970             : int spdk_nvme_ns_cmd_reservation_report(struct spdk_nvme_ns *ns,
    3971             :                                         struct spdk_nvme_qpair *qpair,
    3972             :                                         void *payload, uint32_t len,
    3973             :                                         spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3974             : 
    3975             : /**
    3976             :  * Submit an I/O management receive command to the specified NVMe namespace.
    3977             :  *
    3978             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3979             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3980             :  * given time.
    3981             :  *
    3982             :  * \param ns NVMe namespace to submit the I/O mgmt receive request.
    3983             :  * \param qpair I/O queue pair to submit the request.
    3984             :  * \param payload Virtual address pointer for I/O mgmt receive data.
    3985             :  * \param len Length bytes for I/O mgmt receive data structure.
    3986             :  * \param mo Management operation to perform.
    3987             :  * \param mos Management operation specific field for the mo.
    3988             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3989             :  * \param cb_arg Argument to pass to the callback function.
    3990             :  *
    3991             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3992             :  * -ENOMEM: The request cannot be allocated.
    3993             :  * -ENXIO: The qpair is failed at the transport level.
    3994             :  */
    3995             : int spdk_nvme_ns_cmd_io_mgmt_recv(struct spdk_nvme_ns *ns,
    3996             :                                   struct spdk_nvme_qpair *qpair, void *payload,
    3997             :                                   uint32_t len, uint8_t mo, uint16_t mos,
    3998             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3999             : 
    4000             : /**
    4001             :  * Submit an I/O management send command to the specified NVMe namespace.
    4002             :  *
    4003             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    4004             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    4005             :  * given time.
    4006             :  *
    4007             :  * \param ns NVMe namespace to submit the I/O mgmt send request.
    4008             :  * \param qpair I/O queue pair to submit the request.
    4009             :  * \param payload Virtual address pointer for I/O mgmt send data.
    4010             :  * \param len Length bytes for I/O mgmt send data structure.
    4011             :  * \param mo Management operation to perform.
    4012             :  * \param mos Management operation specific field for the mo.
    4013             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    4014             :  * \param cb_arg Argument to pass to the callback function.
    4015             :  *
    4016             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    4017             :  * -ENOMEM: The request cannot be allocated.
    4018             :  * -ENXIO: The qpair is failed at the transport level.
    4019             :  */
    4020             : int spdk_nvme_ns_cmd_io_mgmt_send(struct spdk_nvme_ns *ns,
    4021             :                                   struct spdk_nvme_qpair *qpair, void *payload,
    4022             :                                   uint32_t len, uint8_t mo, uint16_t mos,
    4023             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    4024             : 
    4025             : /**
    4026             :  * Submit a compare I/O to the specified NVMe namespace.
    4027             :  *
    4028             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    4029             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    4030             :  * given time.
    4031             :  *
    4032             :  * \param ns NVMe namespace to submit the compare I/O.
    4033             :  * \param qpair I/O queue pair to submit the request.
    4034             :  * \param payload Virtual address pointer to the data payload.
    4035             :  * \param lba Starting LBA to compare the data.
    4036             :  * \param lba_count Length (in sectors) for the compare operation.
    4037             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    4038             :  * \param cb_arg Argument to pass to the callback function.
    4039             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    4040             :  *
    4041             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    4042             :  * -EINVAL: The request is malformed.
    4043             :  * -ENOMEM: The request cannot be allocated.
    4044             :  * -ENXIO: The qpair is failed at the transport level.
    4045             :  */
    4046             : int spdk_nvme_ns_cmd_compare(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    4047             :                              uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    4048             :                              void *cb_arg, uint32_t io_flags);
    4049             : 
    4050             : /**
    4051             :  * Submit a compare I/O to the specified NVMe namespace.
    4052             :  *
    4053             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    4054             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    4055             :  * given time.
    4056             :  *
    4057             :  * \param ns NVMe namespace to submit the compare I/O.
    4058             :  * \param qpair I/O queue pair to submit the request.
    4059             :  * \param lba Starting LBA to compare the data.
    4060             :  * \param lba_count Length (in sectors) for the compare operation.
    4061             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    4062             :  * \param cb_arg Argument to pass to the callback function.
    4063             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    4064             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    4065             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    4066             :  * segment.
    4067             :  *
    4068             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    4069             :  * -EINVAL: The request is malformed.
    4070             :  * -ENOMEM: The request cannot be allocated.
    4071             :  * -ENXIO: The qpair is failed at the transport level.
    4072             :  */
    4073             : int spdk_nvme_ns_cmd_comparev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    4074             :                               uint64_t lba, uint32_t lba_count,
    4075             :                               spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    4076             :                               spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    4077             :                               spdk_nvme_req_next_sge_cb next_sge_fn);
    4078             : 
    4079             : /**
    4080             :  * Submit a compare I/O to the specified NVMe namespace.
    4081             :  *
    4082             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    4083             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    4084             :  * given time.
    4085             :  *
    4086             :  * \param ns NVMe namespace to submit the compare I/O.
    4087             :  * \param qpair I/O queue pair to submit the request.
    4088             :  * \param lba Starting LBA to compare the data.
    4089             :  * \param lba_count Length (in sectors) for the compare operation.
    4090             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    4091             :  * \param cb_arg Argument to pass to the callback function.
    4092             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    4093             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    4094             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    4095             :  * segment.
    4096             :  * \param metadata Virtual address pointer to the metadata payload, the length
    4097             :  * of metadata is specified by spdk_nvme_ns_get_md_size()
    4098             :  * \param apptag_mask Application tag mask.
    4099             :  * \param apptag Application tag to use end-to-end protection information.
    4100             :  *
    4101             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    4102             :  * -EINVAL: The request is malformed.
    4103             :  * -ENOMEM: The request cannot be allocated.
    4104             :  * -ENXIO: The qpair is failed at the transport level.
    4105             :  */
    4106             : int
    4107             : spdk_nvme_ns_cmd_comparev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    4108             :                                   uint64_t lba, uint32_t lba_count,
    4109             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    4110             :                                   spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    4111             :                                   spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    4112             :                                   uint16_t apptag_mask, uint16_t apptag);
    4113             : 
    4114             : /**
    4115             :  * Submit a compare I/O to the specified NVMe namespace.
    4116             :  *
    4117             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    4118             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    4119             :  * given time.
    4120             :  *
    4121             :  * \param ns NVMe namespace to submit the compare I/O.
    4122             :  * \param qpair I/O queue pair to submit the request.
    4123             :  * \param payload Virtual address pointer to the data payload.
    4124             :  * \param metadata Virtual address pointer to the metadata payload, the length
    4125             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    4126             :  * \param lba Starting LBA to compare the data.
    4127             :  * \param lba_count Length (in sectors) for the compare operation.
    4128             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    4129             :  * \param cb_arg Argument to pass to the callback function.
    4130             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    4131             :  * \param apptag_mask Application tag mask.
    4132             :  * \param apptag Application tag to use end-to-end protection information.
    4133             :  *
    4134             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    4135             :  * -EINVAL: The request is malformed.
    4136             :  * -ENOMEM: The request cannot be allocated.
    4137             :  * -ENXIO: The qpair is failed at the transport level.
    4138             :  */
    4139             : int spdk_nvme_ns_cmd_compare_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    4140             :                                      void *payload, void *metadata,
    4141             :                                      uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    4142             :                                      void *cb_arg, uint32_t io_flags,
    4143             :                                      uint16_t apptag_mask, uint16_t apptag);
    4144             : 
    4145             : /**
    4146             :  * \brief Inject an error for the next request with a given opcode.
    4147             :  *
    4148             :  * \param ctrlr NVMe controller.
    4149             :  * \param qpair I/O queue pair to add the error command,
    4150             :  *              NULL for Admin queue pair.
    4151             :  * \param opc Opcode for Admin or I/O commands.
    4152             :  * \param do_not_submit True if matching requests should not be submitted
    4153             :  *                      to the controller, but instead completed manually
    4154             :  *                      after timeout_in_us has expired.  False if matching
    4155             :  *                      requests should be submitted to the controller and
    4156             :  *                      have their completion status modified after the
    4157             :  *                      controller completes the request.
    4158             :  * \param timeout_in_us Wait specified microseconds when do_not_submit is true.
    4159             :  * \param err_count Number of matching requests to inject errors.
    4160             :  * \param sct Status code type.
    4161             :  * \param sc Status code.
    4162             :  *
    4163             :  * \return 0 if successfully enabled, ENOMEM if an error command
    4164             :  *           structure cannot be allocated.
    4165             :  *
    4166             :  * The function can be called multiple times to inject errors for different
    4167             :  * commands.  If the opcode matches an existing entry, the existing entry
    4168             :  * will be updated with the values specified.
    4169             :  */
    4170             : int spdk_nvme_qpair_add_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
    4171             :                 struct spdk_nvme_qpair *qpair,
    4172             :                 uint8_t opc,
    4173             :                 bool do_not_submit,
    4174             :                 uint64_t timeout_in_us,
    4175             :                 uint32_t err_count,
    4176             :                 uint8_t sct, uint8_t sc);
    4177             : 
    4178             : /**
    4179             :  * \brief Clear the specified NVMe command with error status.
    4180             :  *
    4181             :  * \param ctrlr NVMe controller.
    4182             :  * \param qpair I/O queue pair to remove the error command,
    4183             :  * \            NULL for Admin queue pair.
    4184             :  * \param opc Opcode for Admin or I/O commands.
    4185             :  *
    4186             :  * The function will remove specified command in the error list.
    4187             :  */
    4188             : void spdk_nvme_qpair_remove_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
    4189             :                 struct spdk_nvme_qpair *qpair,
    4190             :                 uint8_t opc);
    4191             : 
    4192             : /**
    4193             :  * \brief Given NVMe status, return ASCII string for that error.
    4194             :  *
    4195             :  * \param status Status from NVMe completion queue element.
    4196             :  * \return Returns status as an ASCII string.
    4197             :  */
    4198             : const char *spdk_nvme_cpl_get_status_string(const struct spdk_nvme_status *status);
    4199             : 
    4200             : /**
    4201             :  * \brief Given NVMe status, return ASCII string for the type of that error.
    4202             :  *
    4203             :  * \param status Status from NVMe completion queue element.
    4204             :  * \return Returns status type as an ASCII string.
    4205             :  */
    4206             : const char *spdk_nvme_cpl_get_status_type_string(const struct spdk_nvme_status *status);
    4207             : 
    4208             : /**
    4209             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
    4210             :  *
    4211             :  * \param qpair Pointer to the NVMe queue pair - used to determine admin versus I/O queue.
    4212             :  * \param cmd Pointer to the submission queue command to be formatted.
    4213             :  */
    4214             : void spdk_nvme_qpair_print_command(struct spdk_nvme_qpair *qpair,
    4215             :                                    struct spdk_nvme_cmd *cmd);
    4216             : 
    4217             : /**
    4218             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
    4219             :  *
    4220             :  * \param qpair Pointer to the NVMe queue pair - presently unused.
    4221             :  * \param cpl Pointer to the completion queue element to be formatted.
    4222             :  */
    4223             : void spdk_nvme_qpair_print_completion(struct spdk_nvme_qpair *qpair,
    4224             :                                       struct spdk_nvme_cpl *cpl);
    4225             : 
    4226             : /**
    4227             :  * \brief Gets the NVMe qpair ID for the specified qpair.
    4228             :  *
    4229             :  * \param qpair Pointer to the NVMe queue pair.
    4230             :  * \returns ID for the specified qpair.
    4231             :  */
    4232             : uint16_t spdk_nvme_qpair_get_id(struct spdk_nvme_qpair *qpair);
    4233             : 
    4234             : /**
    4235             :  * Gets the number of outstanding requests for the specified qpair.
    4236             :  *
    4237             :  * This number is not decremented until after a request's callback function is completed.
    4238             :  *
    4239             :  * This number is not matched necessarily to the number of NVMe commands submitted by the
    4240             :  * user. For example, nvme driver may split a request due to MDTS limitations, that will
    4241             :  * also allocate a request for the parent, etc.
    4242             :  *
    4243             :  * \param qpair Pointer to the NVMe queue pair.
    4244             :  * \returns number of outstanding requests for the specified qpair.
    4245             :  */
    4246             : uint32_t spdk_nvme_qpair_get_num_outstanding_reqs(struct spdk_nvme_qpair *qpair);
    4247             : 
    4248             : /**
    4249             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
    4250             :  *
    4251             :  * \param qid Queue identifier.
    4252             :  * \param cmd Pointer to the submission queue command to be formatted.
    4253             :  */
    4254             : void spdk_nvme_print_command(uint16_t qid, struct spdk_nvme_cmd *cmd);
    4255             : 
    4256             : /**
    4257             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
    4258             :  *
    4259             :  * \param qid Queue identifier.
    4260             :  * \param cpl Pointer to the completion queue element to be formatted.
    4261             :  */
    4262             : void spdk_nvme_print_completion(uint16_t qid, struct spdk_nvme_cpl *cpl);
    4263             : 
    4264             : /**
    4265             :  * Return the name of a digest.
    4266             :  *
    4267             :  * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
    4268             :  *
    4269             :  * \return Name of the digest.
    4270             :  */
    4271             : const char *spdk_nvme_dhchap_get_digest_name(int id);
    4272             : 
    4273             : /**
    4274             :  * Return the id of a digest.
    4275             :  *
    4276             :  * \param name Name of a digest.
    4277             :  *
    4278             :  * \return Digest id (see `enum spdk_nvmf_dhchap_hash`) or negative errno on failure.
    4279             :  */
    4280             : int spdk_nvme_dhchap_get_digest_id(const char *name);
    4281             : 
    4282             : /**
    4283             :  * Return the length of a digest.
    4284             :  *
    4285             :  * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
    4286             :  *
    4287             :  * \return Length of a digest or 0 if the id is unknown.
    4288             :  */
    4289             : uint8_t spdk_nvme_dhchap_get_digest_length(int id);
    4290             : 
    4291             : /**
    4292             :  * Return the name of a Diffie-Hellman group.
    4293             :  *
    4294             :  * \param id Diffie-Hellman group identifier (see `enum spdk_nvmf_dhchap_dhgroup`).
    4295             :  *
    4296             :  * \return Name of the Diffie-Hellman group.
    4297             :  */
    4298             : const char *spdk_nvme_dhchap_get_dhgroup_name(int id);
    4299             : 
    4300             : /**
    4301             :  * Return the id of a Diffie-Hellman group.
    4302             :  *
    4303             :  * \param name Name of a Diffie-Hellman group.
    4304             :  *
    4305             :  * \return Diffie-Hellman group id (see `enum spdk_nvmf_dhchap_dhgroup`) or negative errno
    4306             :  * on failure.
    4307             :  */
    4308             : int spdk_nvme_dhchap_get_dhgroup_id(const char *name);
    4309             : 
    4310             : struct ibv_context;
    4311             : struct ibv_pd;
    4312             : struct ibv_mr;
    4313             : 
    4314             : /**
    4315             :  * RDMA Transport Hooks
    4316             :  */
    4317             : struct spdk_nvme_rdma_hooks {
    4318             :         /**
    4319             :          * \brief Get an InfiniBand Verbs protection domain.
    4320             :          *
    4321             :          * \param trid the transport id
    4322             :          * \param verbs Infiniband verbs context
    4323             :          *
    4324             :          * \return pd of the nvme ctrlr
    4325             :          */
    4326             :         struct ibv_pd *(*get_ibv_pd)(const struct spdk_nvme_transport_id *trid,
    4327             :                                      struct ibv_context *verbs);
    4328             : 
    4329             :         /**
    4330             :          * \brief Get an InfiniBand Verbs memory region for a buffer.
    4331             :          *
    4332             :          * \param pd The protection domain returned from get_ibv_pd
    4333             :          * \param buf Memory buffer for which an rkey should be returned.
    4334             :          * \param size size of buf
    4335             :          *
    4336             :          * \return Infiniband remote key (rkey) for this buf
    4337             :          */
    4338             :         uint64_t (*get_rkey)(struct ibv_pd *pd, void *buf, size_t size);
    4339             : 
    4340             :         /**
    4341             :          * \brief Put back keys got from get_rkey.
    4342             :          *
    4343             :          * \param key The Infiniband remote key (rkey) got from get_rkey
    4344             :          *
    4345             :          */
    4346             :         void (*put_rkey)(uint64_t key);
    4347             : };
    4348             : 
    4349             : /**
    4350             :  * \brief Set the global hooks for the RDMA transport, if necessary.
    4351             :  *
    4352             :  * This call is optional and must be performed prior to probing for
    4353             :  * any devices. By default, the RDMA transport will use the ibverbs
    4354             :  * library to create protection domains and register memory. This
    4355             :  * is a mechanism to subvert that and use an existing registration.
    4356             :  *
    4357             :  * This function may only be called one time per process.
    4358             :  *
    4359             :  * \param hooks for initializing global hooks
    4360             :  */
    4361             : void spdk_nvme_rdma_init_hooks(struct spdk_nvme_rdma_hooks *hooks);
    4362             : 
    4363             : /**
    4364             :  * Get name of cuse device associated with NVMe controller.
    4365             :  *
    4366             :  * \param ctrlr Opaque handle to NVMe controller.
    4367             :  * \param name  Buffer of be filled with cuse device name.
    4368             :  * \param size  Size of name buffer.
    4369             :  *
    4370             :  * \return 0 on success. Negated errno on the following error conditions:
    4371             :  * -ENODEV: No cuse device registered for the controller.
    4372             :  * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
    4373             :  */
    4374             : int spdk_nvme_cuse_get_ctrlr_name(struct spdk_nvme_ctrlr *ctrlr, char *name, size_t *size);
    4375             : 
    4376             : /**
    4377             :  * Get name of cuse device associated with NVMe namespace.
    4378             :  *
    4379             :  * \param ctrlr Opaque handle to NVMe controller.
    4380             :  * \param nsid  Namespace id.
    4381             :  * \param name  Buffer of be filled with cuse device name.
    4382             :  * \param size  Size of name buffer.
    4383             :  *
    4384             :  * \return 0 on success. Negated errno on the following error conditions:
    4385             :  * -ENODEV: No cuse device registered for the namespace.
    4386             :  * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
    4387             :  */
    4388             : int spdk_nvme_cuse_get_ns_name(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    4389             :                                char *name, size_t *size);
    4390             : 
    4391             : /**
    4392             :  * Create a character device at the path specified
    4393             :  *
    4394             :  * The character device can handle ioctls and is compatible with a standard
    4395             :  * Linux kernel NVMe device. Tools such as nvme-cli can be used to configure
    4396             :  * SPDK devices through this interface.
    4397             :  *
    4398             :  * The user is expected to be polling the admin qpair for this controller periodically
    4399             :  * for the CUSE device to function.
    4400             :  *
    4401             :  * \param ctrlr Opaque handle to the NVMe controller.
    4402             :  *
    4403             :  * \return 0 on success. Negated errno on failure.
    4404             :  */
    4405             : int spdk_nvme_cuse_register(struct spdk_nvme_ctrlr *ctrlr);
    4406             : 
    4407             : /**
    4408             :  * Remove a previously created character device
    4409             :  *
    4410             :  * \param ctrlr Opaque handle to the NVMe controller.
    4411             :  *
    4412             :  * \return 0 on success. Negated errno on failure.
    4413             :  */
    4414             : int spdk_nvme_cuse_unregister(struct spdk_nvme_ctrlr *ctrlr);
    4415             : 
    4416             : /**
    4417             :  * Get SPDK memory domains used by the given nvme controller.
    4418             :  *
    4419             :  * The user can call this function with \b domains set to NULL and \b array_size set to 0 to get the
    4420             :  * number of memory domains used by nvme controller
    4421             :  *
    4422             :  * \param ctrlr Opaque handle to the NVMe controller.
    4423             :  * \param domains Pointer to an array of memory domains to be filled by this function. The user should allocate big enough
    4424             :  * array to keep all memory domains used by nvme controller
    4425             :  * \param array_size size of \b domains array
    4426             :  * \return the number of entries in \b domains array or negated errno. If returned value is bigger than \b array_size passed by the user
    4427             :  * then the user should increase the size of \b domains array and call this function again. There is no guarantees that
    4428             :  * the content of \b domains array is valid in that case.
    4429             :  *         -EINVAL if input parameters were invalid
    4430             : 
    4431             :  */
    4432             : int spdk_nvme_ctrlr_get_memory_domains(const struct spdk_nvme_ctrlr *ctrlr,
    4433             :                                        struct spdk_memory_domain **domains, int array_size);
    4434             : 
    4435             : /**
    4436             :  * Opaque handle for a transport poll group. Used by the transport function table.
    4437             :  */
    4438             : struct spdk_nvme_transport_poll_group;
    4439             : 
    4440             : /**
    4441             :  * Update and populate namespace CUSE devices (Experimental)
    4442             :  *
    4443             :  * \param ctrlr Opaque handle to the NVMe controller.
    4444             :  *
    4445             :  */
    4446             : void spdk_nvme_cuse_update_namespaces(struct spdk_nvme_ctrlr *ctrlr);
    4447             : 
    4448             : /**
    4449             :  * Signature for callback invoked after completing a register read/write operation.
    4450             :  *
    4451             :  * \param ctx Context passed by the user.
    4452             :  * \param value Value of the register, undefined in case of a failure.
    4453             :  * \param cpl Completion queue entry that contains the status of the command.
    4454             :  */
    4455             : typedef void (*spdk_nvme_reg_cb)(void *ctx, uint64_t value, const struct spdk_nvme_cpl *cpl);
    4456             : 
    4457             : struct nvme_request;
    4458             : 
    4459             : struct spdk_nvme_transport;
    4460             : 
    4461             : struct spdk_nvme_transport_ops {
    4462             :         char name[SPDK_NVMF_TRSTRING_MAX_LEN + 1];
    4463             : 
    4464             :         enum spdk_nvme_transport_type type;
    4465             : 
    4466             :         struct spdk_nvme_ctrlr *(*ctrlr_construct)(const struct spdk_nvme_transport_id *trid,
    4467             :                         const struct spdk_nvme_ctrlr_opts *opts,
    4468             :                         void *devhandle);
    4469             : 
    4470             :         int (*ctrlr_scan)(struct spdk_nvme_probe_ctx *probe_ctx, bool direct_connect);
    4471             : 
    4472             :         int (*ctrlr_destruct)(struct spdk_nvme_ctrlr *ctrlr);
    4473             : 
    4474             :         int (*ctrlr_enable)(struct spdk_nvme_ctrlr *ctrlr);
    4475             : 
    4476             :         int (*ctrlr_set_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value);
    4477             : 
    4478             :         int (*ctrlr_set_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value);
    4479             : 
    4480             :         int (*ctrlr_get_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t *value);
    4481             : 
    4482             :         int (*ctrlr_get_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t *value);
    4483             : 
    4484             :         int (*ctrlr_set_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value,
    4485             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4486             : 
    4487             :         int (*ctrlr_set_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value,
    4488             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4489             : 
    4490             :         int (*ctrlr_get_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
    4491             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4492             : 
    4493             :         int (*ctrlr_get_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
    4494             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4495             : 
    4496             :         uint32_t (*ctrlr_get_max_xfer_size)(struct spdk_nvme_ctrlr *ctrlr);
    4497             : 
    4498             :         uint16_t (*ctrlr_get_max_sges)(struct spdk_nvme_ctrlr *ctrlr);
    4499             : 
    4500             :         int (*ctrlr_reserve_cmb)(struct spdk_nvme_ctrlr *ctrlr);
    4501             : 
    4502             :         void *(*ctrlr_map_cmb)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    4503             : 
    4504             :         int (*ctrlr_unmap_cmb)(struct spdk_nvme_ctrlr *ctrlr);
    4505             : 
    4506             :         int (*ctrlr_enable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4507             : 
    4508             :         int (*ctrlr_disable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4509             : 
    4510             :         void *(*ctrlr_map_pmr)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    4511             : 
    4512             :         int (*ctrlr_unmap_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4513             : 
    4514             :         struct spdk_nvme_qpair *(*ctrlr_create_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid,
    4515             :                         const struct spdk_nvme_io_qpair_opts *opts);
    4516             : 
    4517             :         int (*ctrlr_delete_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4518             : 
    4519             :         int (*ctrlr_connect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4520             : 
    4521             :         void (*ctrlr_disconnect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4522             : 
    4523             :         void (*qpair_abort_reqs)(struct spdk_nvme_qpair *qpair, uint32_t dnr);
    4524             : 
    4525             :         int (*qpair_reset)(struct spdk_nvme_qpair *qpair);
    4526             : 
    4527             :         int (*qpair_submit_request)(struct spdk_nvme_qpair *qpair, struct nvme_request *req);
    4528             : 
    4529             :         int (*qpair_authenticate)(struct spdk_nvme_qpair *qpair);
    4530             : 
    4531             :         int32_t (*qpair_process_completions)(struct spdk_nvme_qpair *qpair, uint32_t max_completions);
    4532             : 
    4533             :         int (*qpair_iterate_requests)(struct spdk_nvme_qpair *qpair,
    4534             :                                       int (*iter_fn)(struct nvme_request *req, void *arg),
    4535             :                                       void *arg);
    4536             : 
    4537             :         void (*admin_qpair_abort_aers)(struct spdk_nvme_qpair *qpair);
    4538             : 
    4539             :         struct spdk_nvme_transport_poll_group *(*poll_group_create)(void);
    4540             :         struct spdk_nvme_transport_poll_group *(*qpair_get_optimal_poll_group)(
    4541             :                 struct spdk_nvme_qpair *qpair);
    4542             : 
    4543             :         int (*poll_group_add)(struct spdk_nvme_transport_poll_group *tgroup, struct spdk_nvme_qpair *qpair);
    4544             : 
    4545             :         int (*poll_group_remove)(struct spdk_nvme_transport_poll_group *tgroup,
    4546             :                                  struct spdk_nvme_qpair *qpair);
    4547             : 
    4548             :         int (*poll_group_connect_qpair)(struct spdk_nvme_qpair *qpair);
    4549             : 
    4550             :         int (*poll_group_disconnect_qpair)(struct spdk_nvme_qpair *qpair);
    4551             : 
    4552             :         int64_t (*poll_group_process_completions)(struct spdk_nvme_transport_poll_group *tgroup,
    4553             :                         uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
    4554             : 
    4555             :         int (*poll_group_destroy)(struct spdk_nvme_transport_poll_group *tgroup);
    4556             : 
    4557             :         int (*poll_group_get_stats)(struct spdk_nvme_transport_poll_group *tgroup,
    4558             :                                     struct spdk_nvme_transport_poll_group_stat **stats);
    4559             : 
    4560             :         void (*poll_group_free_stats)(struct spdk_nvme_transport_poll_group *tgroup,
    4561             :                                       struct spdk_nvme_transport_poll_group_stat *stats);
    4562             : 
    4563             :         int (*ctrlr_get_memory_domains)(const struct spdk_nvme_ctrlr *ctrlr,
    4564             :                                         struct spdk_memory_domain **domains,
    4565             :                                         int array_size);
    4566             : 
    4567             :         int (*ctrlr_ready)(struct spdk_nvme_ctrlr *ctrlr);
    4568             : 
    4569             :         volatile struct spdk_nvme_registers *(*ctrlr_get_registers)(struct spdk_nvme_ctrlr *ctrlr);
    4570             : 
    4571             :         /* Optional callback for transports to process removal events of attached controllers. */
    4572             :         int (*ctrlr_scan_attached)(struct spdk_nvme_probe_ctx *probe_ctx);
    4573             : };
    4574             : 
    4575             : /**
    4576             :  * Register the operations for a given transport type.
    4577             :  *
    4578             :  * This function should be invoked by referencing the macro
    4579             :  * SPDK_NVME_TRANSPORT_REGISTER macro in the transport's .c file.
    4580             :  *
    4581             :  * \param ops The operations associated with an NVMe-oF transport.
    4582             :  */
    4583             : void spdk_nvme_transport_register(const struct spdk_nvme_transport_ops *ops);
    4584             : 
    4585             : /*
    4586             :  * Macro used to register new transports.
    4587             :  */
    4588             : #define SPDK_NVME_TRANSPORT_REGISTER(name, transport_ops) \
    4589             : static void __attribute__((constructor)) _spdk_nvme_transport_register_##name(void) \
    4590             : { \
    4591             :         spdk_nvme_transport_register(transport_ops); \
    4592             : }
    4593             : 
    4594             : /**
    4595             :  * NVMe transport options.
    4596             :  */
    4597             : struct spdk_nvme_transport_opts {
    4598             :         /**
    4599             :          * It is used for RDMA transport.
    4600             :          *
    4601             :          * The queue depth of a shared rdma receive queue.
    4602             :          */
    4603             :         uint32_t rdma_srq_size;
    4604             : 
    4605             :         /* Hole at bytes 4-7. */
    4606             :         uint8_t reserved4[4];
    4607             : 
    4608             :         /**
    4609             :          * The size of spdk_nvme_transport_opts according to the caller of this library is used for ABI
    4610             :          * compatibility.  The library uses this field to know how many fields in this
    4611             :          * structure are valid. And the library will populate any remaining fields with default values.
    4612             :          */
    4613             :         size_t opts_size;
    4614             : 
    4615             :         /**
    4616             :          * It is used for RDMA transport.
    4617             :          *
    4618             :          * The maximum queue depth of a rdma completion queue.
    4619             :          * It is zero, which means unlimited, by default.
    4620             :          */
    4621             :         uint32_t rdma_max_cq_size;
    4622             : 
    4623             :         /**
    4624             :          * It is used for RDMA transport.
    4625             :          *
    4626             :          * RDMA CM event timeout in milliseconds.
    4627             :          */
    4628             :         uint16_t rdma_cm_event_timeout_ms;
    4629             : };
    4630             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_transport_opts) == 24, "Incorrect size");
    4631             : 
    4632             : /**
    4633             :  * Get the current NVMe transport options.
    4634             :  *
    4635             :  * \param[out] opts Will be filled with the current options for spdk_nvme_transport_set_opts().
    4636             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
    4637             :  */
    4638             : void spdk_nvme_transport_get_opts(struct spdk_nvme_transport_opts *opts, size_t opts_size);
    4639             : 
    4640             : /**
    4641             :  * Set the NVMe transport options.
    4642             :  *
    4643             :  * \param opts Pointer to the allocated spdk_nvme_transport_opts structure with new values.
    4644             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
    4645             :  *
    4646             :  * \return 0 on success, or negated errno on failure.
    4647             :  */
    4648             : int spdk_nvme_transport_set_opts(const struct spdk_nvme_transport_opts *opts, size_t opts_size);
    4649             : 
    4650             : #ifdef __cplusplus
    4651             : }
    4652             : #endif
    4653             : 
    4654             : #endif

Generated by: LCOV version 1.15