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

Generated by: LCOV version 1.15