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-08-13 06:03:55 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 sequence */
     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             :  * Scan attached controllers for events.
    1105             :  *
    1106             :  * This function lets user act on events such as hot-remove without a need to
    1107             :  * enable hotplug explicitly. Only attached devices will be checked.
    1108             :  *
    1109             :  * \param trid Transport ID.
    1110             :  *
    1111             :  * \returns 0 on success, negative on failure.
    1112             :  */
    1113             : int spdk_nvme_scan_attached(const struct spdk_nvme_transport_id *trid);
    1114             : 
    1115             : /**
    1116             :  * Update the transport ID for a given controller.
    1117             :  *
    1118             :  * This function allows the user to set a new trid for a controller only if the
    1119             :  * controller is failed. The controller's failed state can be obtained from
    1120             :  * spdk_nvme_ctrlr_is_failed(). The controller can also be forced to the failed
    1121             :  * state using spdk_nvme_ctrlr_fail().
    1122             :  *
    1123             :  * This function also requires that the transport type and subnqn of the new trid
    1124             :  * be the same as the old trid.
    1125             :  *
    1126             :  * \param ctrlr Opaque handle to an NVMe controller.
    1127             :  * \param trid The new transport ID.
    1128             :  *
    1129             :  * \return 0 on success, -EINVAL if the trid is invalid,
    1130             :  * -EPERM if the ctrlr is not failed.
    1131             :  */
    1132             : int spdk_nvme_ctrlr_set_trid(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_transport_id *trid);
    1133             : 
    1134             : /**
    1135             :  * Set the remove callback and context to be invoked if the controller is removed.
    1136             :  *
    1137             :  * This will override any remove_cb and/or ctx specified when the controller was
    1138             :  * probed.
    1139             :  *
    1140             :  * This function may only be called from the primary process.  This function has
    1141             :  * no effect if called from a secondary process.
    1142             :  *
    1143             :  * \param ctrlr Opaque handle to an NVMe controller.
    1144             :  * \param remove_cb remove callback
    1145             :  * \param remove_ctx remove callback context
    1146             :  */
    1147             : void spdk_nvme_ctrlr_set_remove_cb(struct spdk_nvme_ctrlr *ctrlr,
    1148             :                                    spdk_nvme_remove_cb remove_cb, void *remove_ctx);
    1149             : 
    1150             : /**
    1151             :  * Perform a full hardware reset of the NVMe controller.
    1152             :  *
    1153             :  * This function should be called from a single thread while no other threads
    1154             :  * are actively using the NVMe device.
    1155             :  *
    1156             :  * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
    1157             :  * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
    1158             :  * may be invalidated by calling this function. The number of namespaces as returned
    1159             :  * by spdk_nvme_ctrlr_get_num_ns() may also change.
    1160             :  *
    1161             :  * \param ctrlr Opaque handle to NVMe controller.
    1162             :  *
    1163             :  * \return 0 on success, -1 on failure.
    1164             :  */
    1165             : int spdk_nvme_ctrlr_reset(struct spdk_nvme_ctrlr *ctrlr);
    1166             : 
    1167             : /**
    1168             :  * Disconnect the given NVMe controller.
    1169             :  *
    1170             :  * This function is used as the first operation of a full reset sequence of the given NVMe
    1171             :  * controller. The NVMe controller is ready to reconnect after completing this function.
    1172             :  *
    1173             :  * \param ctrlr Opaque handle to NVMe controller.
    1174             :  *
    1175             :  * \return 0 on success, -EBUSY if controller is already resetting, or -ENXIO if controller
    1176             :  * has been removed.
    1177             :  */
    1178             : int spdk_nvme_ctrlr_disconnect(struct spdk_nvme_ctrlr *ctrlr);
    1179             : 
    1180             : /**
    1181             :  * Start re-enabling the given NVMe controller in a full reset sequence
    1182             :  *
    1183             :  * \param ctrlr Opaque handle to NVMe controller.
    1184             :  */
    1185             : void spdk_nvme_ctrlr_reconnect_async(struct spdk_nvme_ctrlr *ctrlr);
    1186             : 
    1187             : /**
    1188             :  * Proceed with re-enabling the given NVMe controller.
    1189             :  *
    1190             :  * Users must call this function in a full reset sequence until it returns a value other
    1191             :  * than -EAGAIN.
    1192             :  *
    1193             :  * \return 0 if the given NVMe controller is enabled, or -EBUSY if there are still
    1194             :  * pending operations to enable it.
    1195             :  */
    1196             : int spdk_nvme_ctrlr_reconnect_poll_async(struct spdk_nvme_ctrlr *ctrlr);
    1197             : 
    1198             : /**
    1199             :  * Perform a NVMe subsystem reset.
    1200             :  *
    1201             :  * This function should be called from a single thread while no other threads
    1202             :  * are actively using the NVMe device.
    1203             :  * A subsystem reset is typically seen by the OS as a hot remove, followed by a
    1204             :  * hot add event.
    1205             :  *
    1206             :  * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
    1207             :  * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
    1208             :  * may be invalidated by calling this function. The number of namespaces as returned
    1209             :  * by spdk_nvme_ctrlr_get_num_ns() may also change.
    1210             :  *
    1211             :  * \param ctrlr Opaque handle to NVMe controller.
    1212             :  *
    1213             :  * \return 0 on success, -1 on failure, -ENOTSUP if subsystem reset is not supported.
    1214             :  */
    1215             : int spdk_nvme_ctrlr_reset_subsystem(struct spdk_nvme_ctrlr *ctrlr);
    1216             : 
    1217             : /**
    1218             :  * Fail the given NVMe controller.
    1219             :  *
    1220             :  * This function gives the application the opportunity to fail a controller
    1221             :  * at will. When a controller is failed, any calls to process completions or
    1222             :  * submit I/O on qpairs associated with that controller will fail with an error
    1223             :  * code of -ENXIO.
    1224             :  * The controller can only be taken from the failed state by
    1225             :  * calling spdk_nvme_ctrlr_reset. After the controller has been successfully
    1226             :  * reset, any I/O pending when the controller was moved to failed will be
    1227             :  * aborted back to the application and can be resubmitted. I/O can then resume.
    1228             :  *
    1229             :  * \param ctrlr Opaque handle to an NVMe controller.
    1230             :  */
    1231             : void spdk_nvme_ctrlr_fail(struct spdk_nvme_ctrlr *ctrlr);
    1232             : 
    1233             : /**
    1234             :  * This function returns the failed status of a given controller.
    1235             :  *
    1236             :  * \param ctrlr Opaque handle to an NVMe controller.
    1237             :  *
    1238             :  * \return True if the controller is failed, false otherwise.
    1239             :  */
    1240             : bool spdk_nvme_ctrlr_is_failed(struct spdk_nvme_ctrlr *ctrlr);
    1241             : 
    1242             : /**
    1243             :  * Get the identify controller data as defined by the NVMe specification.
    1244             :  *
    1245             :  * This function is thread safe and can be called at any point while the controller
    1246             :  * is attached to the SPDK NVMe driver.
    1247             :  *
    1248             :  * \param ctrlr Opaque handle to NVMe controller.
    1249             :  *
    1250             :  * \return pointer to the identify controller data.
    1251             :  */
    1252             : const struct spdk_nvme_ctrlr_data *spdk_nvme_ctrlr_get_data(struct spdk_nvme_ctrlr *ctrlr);
    1253             : 
    1254             : /**
    1255             :  * Get the NVMe controller CSTS (Status) register.
    1256             :  *
    1257             :  * \param ctrlr Opaque handle to NVMe controller.
    1258             :  *
    1259             :  * \return the NVMe controller CSTS (Status) register.
    1260             :  */
    1261             : union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts(struct spdk_nvme_ctrlr *ctrlr);
    1262             : 
    1263             : /**
    1264             :  * Get the NVMe controller CC (Configuration) register.
    1265             :  *
    1266             :  * \param ctrlr Opaque handle to NVMe controller.
    1267             :  *
    1268             :  * \return the NVMe controller CC (Configuration) register.
    1269             :  */
    1270             : union spdk_nvme_cc_register spdk_nvme_ctrlr_get_regs_cc(struct spdk_nvme_ctrlr *ctrlr);
    1271             : 
    1272             : /**
    1273             :  * Get the NVMe controller CAP (Capabilities) register.
    1274             :  *
    1275             :  * \param ctrlr Opaque handle to NVMe controller.
    1276             :  *
    1277             :  * \return the NVMe controller CAP (Capabilities) register.
    1278             :  */
    1279             : union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap(struct spdk_nvme_ctrlr *ctrlr);
    1280             : 
    1281             : /**
    1282             :  * Get the NVMe controller VS (Version) register.
    1283             :  *
    1284             :  * \param ctrlr Opaque handle to NVMe controller.
    1285             :  *
    1286             :  * \return the NVMe controller VS (Version) register.
    1287             :  */
    1288             : union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs(struct spdk_nvme_ctrlr *ctrlr);
    1289             : 
    1290             : /**
    1291             :  * Get the NVMe controller CMBSZ (Controller Memory Buffer Size) register
    1292             :  *
    1293             :  * \param ctrlr Opaque handle to NVMe controller.
    1294             :  *
    1295             :  * \return the NVMe controller CMBSZ (Controller Memory Buffer Size) register.
    1296             :  */
    1297             : union spdk_nvme_cmbsz_register spdk_nvme_ctrlr_get_regs_cmbsz(struct spdk_nvme_ctrlr *ctrlr);
    1298             : 
    1299             : /**
    1300             :  * Get the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
    1301             :  *
    1302             :  * \param ctrlr Opaque handle to NVMe controller.
    1303             :  *
    1304             :  * \return the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
    1305             :  */
    1306             : union spdk_nvme_pmrcap_register spdk_nvme_ctrlr_get_regs_pmrcap(struct spdk_nvme_ctrlr *ctrlr);
    1307             : 
    1308             : /**
    1309             :  * Get the NVMe controller BPINFO (Boot Partition Information) register.
    1310             :  *
    1311             :  * \param ctrlr Opaque handle to NVMe controller.
    1312             :  *
    1313             :  * \return the NVMe controller BPINFO (Boot Partition Information) register.
    1314             :  */
    1315             : union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo(struct spdk_nvme_ctrlr *ctrlr);
    1316             : 
    1317             : /**
    1318             :  * Get the NVMe controller PMR size.
    1319             :  *
    1320             :  * \param ctrlr Opaque handle to NVMe controller.
    1321             :  *
    1322             :  * \return the NVMe controller PMR size or 0 if PMR is not supported.
    1323             :  */
    1324             : uint64_t spdk_nvme_ctrlr_get_pmrsz(struct spdk_nvme_ctrlr *ctrlr);
    1325             : 
    1326             : /**
    1327             :  * Get the maximum NSID value that will ever be used for the given controller
    1328             :  *
    1329             :  * This function is thread safe and can be called at any point while the
    1330             :  * controller is attached to the SPDK NVMe driver.
    1331             :  *
    1332             :  * This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the
    1333             :  * spdk_nvme_ctrlr_data and then reading the nn field.
    1334             :  *
    1335             :  * The NN field in the NVMe specification represents the maximum value that a
    1336             :  * namespace ID can ever have. Prior to NVMe 1.2, this was also the number of
    1337             :  * active namespaces, but from 1.2 onward the list of namespaces may be
    1338             :  * sparsely populated. Unfortunately, the meaning of this field is often
    1339             :  * misinterpreted by drive manufacturers and NVMe-oF implementers so it is
    1340             :  * not considered reliable. AVOID USING THIS FUNCTION WHENEVER POSSIBLE.
    1341             :  *
    1342             :  * \param ctrlr Opaque handle to NVMe controller.
    1343             :  *
    1344             :  * \return the number of namespaces.
    1345             :  */
    1346             : uint32_t spdk_nvme_ctrlr_get_num_ns(struct spdk_nvme_ctrlr *ctrlr);
    1347             : 
    1348             : /**
    1349             :  * Get the PCI device of a given NVMe controller.
    1350             :  *
    1351             :  * This only works for local (PCIe-attached) NVMe controllers; other transports
    1352             :  * will return NULL.
    1353             :  *
    1354             :  * \param ctrlr Opaque handle to NVMe controller.
    1355             :  *
    1356             :  * \return PCI device of the NVMe controller, or NULL if not available.
    1357             :  */
    1358             : struct spdk_pci_device *spdk_nvme_ctrlr_get_pci_device(struct spdk_nvme_ctrlr *ctrlr);
    1359             : 
    1360             : /**
    1361             :  * Get the maximum data transfer size of a given NVMe controller.
    1362             :  *
    1363             :  * \param ctrlr Opaque handle to NVMe controller.
    1364             :  *
    1365             :  * \return Maximum data transfer size of the NVMe controller in bytes.
    1366             :  *
    1367             :  * The I/O command helper functions, such as spdk_nvme_ns_cmd_read(), will split
    1368             :  * large I/Os automatically; however, it is up to the user to obey this limit for
    1369             :  * commands submitted with the raw command functions, such as spdk_nvme_ctrlr_cmd_io_raw().
    1370             :  */
    1371             : uint32_t spdk_nvme_ctrlr_get_max_xfer_size(const struct spdk_nvme_ctrlr *ctrlr);
    1372             : 
    1373             : /**
    1374             :  * Get the maximum number of SGEs per request for the given NVMe controller.
    1375             :  *
    1376             :  * Controllers that do not support SGL will return UINT16_MAX.
    1377             :  *
    1378             :  * \param ctrlr Opaque handle to NVMe controller.
    1379             :  *
    1380             :  * \return Maximum number of SGEs per request
    1381             :  */
    1382             : uint16_t spdk_nvme_ctrlr_get_max_sges(const struct spdk_nvme_ctrlr *ctrlr);
    1383             : 
    1384             : /**
    1385             :  * Check whether the nsid is an active nv for the given NVMe controller.
    1386             :  *
    1387             :  * This function is thread safe and can be called at any point while the controller
    1388             :  * is attached to the SPDK NVMe driver.
    1389             :  *
    1390             :  * \param ctrlr Opaque handle to NVMe controller.
    1391             :  * \param nsid Namespace id.
    1392             :  *
    1393             :  * \return true if nsid is an active ns, or false otherwise.
    1394             :  */
    1395             : bool spdk_nvme_ctrlr_is_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
    1396             : 
    1397             : /**
    1398             :  * Get the nsid of the first active namespace.
    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             :  *
    1405             :  * \return the nsid of the first active namespace, 0 if there are no active namespaces.
    1406             :  */
    1407             : uint32_t spdk_nvme_ctrlr_get_first_active_ns(struct spdk_nvme_ctrlr *ctrlr);
    1408             : 
    1409             : /**
    1410             :  * Get next active namespace given the previous nsid.
    1411             :  *
    1412             :  * This function is thread safe and can be called at any point while the controller
    1413             :  * is attached to the SPDK NVMe driver.
    1414             :  *
    1415             :  * \param ctrlr Opaque handle to NVMe controller.
    1416             :  * \param prev_nsid Namespace id.
    1417             :  *
    1418             :  * \return a next active namespace given the previous nsid, 0 when there are no
    1419             :  * more active namespaces.
    1420             :  */
    1421             : uint32_t spdk_nvme_ctrlr_get_next_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t prev_nsid);
    1422             : 
    1423             : /**
    1424             :  * Determine if a particular log page is supported by the given NVMe controller.
    1425             :  *
    1426             :  * This function is thread safe and can be called at any point while the controller
    1427             :  * is attached to the SPDK NVMe driver.
    1428             :  *
    1429             :  * \sa spdk_nvme_ctrlr_cmd_get_log_page().
    1430             :  *
    1431             :  * \param ctrlr Opaque handle to NVMe controller.
    1432             :  * \param log_page Log page to query.
    1433             :  *
    1434             :  * \return true if supported, or false otherwise.
    1435             :  */
    1436             : bool spdk_nvme_ctrlr_is_log_page_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page);
    1437             : 
    1438             : /**
    1439             :  * Determine if a particular feature is supported by the given NVMe controller.
    1440             :  *
    1441             :  * This function is thread safe and can be called at any point while the controller
    1442             :  * is attached to the SPDK NVMe driver.
    1443             :  *
    1444             :  * \sa spdk_nvme_ctrlr_cmd_get_feature().
    1445             :  *
    1446             :  * \param ctrlr Opaque handle to NVMe controller.
    1447             :  * \param feature_code Feature to query.
    1448             :  *
    1449             :  * \return true if supported, or false otherwise.
    1450             :  */
    1451             : bool spdk_nvme_ctrlr_is_feature_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature_code);
    1452             : 
    1453             : /**
    1454             :  * Signature for callback function invoked when a command is completed.
    1455             :  *
    1456             :  * \param ctx Callback context provided when the command was submitted.
    1457             :  * \param cpl Completion queue entry that contains the completion status.
    1458             :  */
    1459             : typedef void (*spdk_nvme_cmd_cb)(void *ctx, const struct spdk_nvme_cpl *cpl);
    1460             : 
    1461             : /**
    1462             :  * Signature for callback function invoked when an asynchronous event request
    1463             :  * command is completed.
    1464             :  *
    1465             :  * \param aer_cb_arg Context specified by spdk_nvme_register_aer_callback().
    1466             :  * \param cpl Completion queue entry that contains the completion status
    1467             :  * of the asynchronous event request that was completed.
    1468             :  */
    1469             : typedef void (*spdk_nvme_aer_cb)(void *aer_cb_arg,
    1470             :                                  const struct spdk_nvme_cpl *cpl);
    1471             : 
    1472             : /**
    1473             :  * Register callback function invoked when an AER command is completed for the
    1474             :  * given NVMe controller.
    1475             :  *
    1476             :  * \param ctrlr Opaque handle to NVMe controller.
    1477             :  * \param aer_cb_fn Callback function invoked when an asynchronous event request
    1478             :  * command is completed.
    1479             :  * \param aer_cb_arg Argument passed to callback function.
    1480             :  */
    1481             : void spdk_nvme_ctrlr_register_aer_callback(struct spdk_nvme_ctrlr *ctrlr,
    1482             :                 spdk_nvme_aer_cb aer_cb_fn,
    1483             :                 void *aer_cb_arg);
    1484             : 
    1485             : /**
    1486             :  * Disable reading the CHANGED_NS_LIST log page for the specified controller.
    1487             :  *
    1488             :  * Applications that register an AER callback may wish to read the CHANGED_NS_LIST
    1489             :  * log page itself, rather than relying on the driver to do it.  Calling this
    1490             :  * function will ensure that the driver does not read this log page if the
    1491             :  * controller returns a NS_ATTR_CHANGED AEN.
    1492             :  *
    1493             :  * Reading of this log page can alternatively be disabled by setting the
    1494             :  * disable_read_changed_ns_list_log_page flag in the spdk_nvme_ctrlr_opts
    1495             :  * when attaching the controller.
    1496             :  *
    1497             :  * \param ctrlr NVMe controller on which to disable the log page read.
    1498             :  */
    1499             : void spdk_nvme_ctrlr_disable_read_changed_ns_list_log_page(struct spdk_nvme_ctrlr *ctrlr);
    1500             : 
    1501             : /**
    1502             :  * Opaque handle to a queue pair.
    1503             :  *
    1504             :  * I/O queue pairs may be allocated using spdk_nvme_ctrlr_alloc_io_qpair().
    1505             :  */
    1506             : struct spdk_nvme_qpair;
    1507             : 
    1508             : /**
    1509             :  * Signature for the callback function invoked when a timeout is detected on a
    1510             :  * request.
    1511             :  *
    1512             :  * For timeouts detected on the admin queue pair, the qpair returned here will
    1513             :  * be NULL.  If the controller has a serious error condition and is unable to
    1514             :  * communicate with driver via completion queue, the controller can set Controller
    1515             :  * Fatal Status field to 1, then reset is required to recover from such error.
    1516             :  * Users may detect Controller Fatal Status when timeout happens.
    1517             :  *
    1518             :  * \param cb_arg Argument passed to callback function.
    1519             :  * \param ctrlr Opaque handle to NVMe controller.
    1520             :  * \param qpair Opaque handle to a queue pair.
    1521             :  * \param cid Command ID.
    1522             :  */
    1523             : typedef void (*spdk_nvme_timeout_cb)(void *cb_arg,
    1524             :                                      struct spdk_nvme_ctrlr *ctrlr,
    1525             :                                      struct spdk_nvme_qpair *qpair,
    1526             :                                      uint16_t cid);
    1527             : 
    1528             : /**
    1529             :  * Register for timeout callback on a controller.
    1530             :  *
    1531             :  * The application can choose to register for timeout callback or not register
    1532             :  * for timeout callback.
    1533             :  *
    1534             :  * \param ctrlr NVMe controller on which to monitor for timeout.
    1535             :  * \param timeout_io_us Timeout value in microseconds for io commands.
    1536             :  * \param timeout_admin_us Timeout value in microseconds for admin commands.
    1537             :  * \param cb_fn A function pointer that points to the callback function.
    1538             :  * \param cb_arg Argument to the callback function.
    1539             :  */
    1540             : void spdk_nvme_ctrlr_register_timeout_callback(struct spdk_nvme_ctrlr *ctrlr,
    1541             :                 uint64_t timeout_io_us, uint64_t timeout_admin_us,
    1542             :                 spdk_nvme_timeout_cb cb_fn, void *cb_arg);
    1543             : 
    1544             : /**
    1545             :  * Signature for the callback function when a
    1546             :  * \ref spdk_nvme_ctrlr_get_discovery_log_page operation is completed.
    1547             :  *
    1548             :  * \param cb_arg Argument passed to callback function.
    1549             :  * \param rc Status of operation. 0 means success, and that the cpl argument is valid.
    1550             :  *           Failure indicated by negative errno value.
    1551             :  * \param cpl NVMe completion status of the operation. NULL if rc != 0. If multiple
    1552             :  *            completions with error status occurred during the operation, the cpl
    1553             :  *            value for the first error will be used here.
    1554             :  * \param log_page Pointer to the full discovery log page. The application is
    1555             :  *                 responsible for freeing this buffer using free().
    1556             :  */
    1557             : typedef void (*spdk_nvme_discovery_cb)(void *cb_arg, int rc,
    1558             :                                        const struct spdk_nvme_cpl *cpl,
    1559             :                                        struct spdk_nvmf_discovery_log_page *log_page);
    1560             : 
    1561             : /**
    1562             :  * Get a full discovery log page from the specified controller.
    1563             :  *
    1564             :  * This function will first read the discovery log header to determine the
    1565             :  * total number of valid entries in the discovery log, then it will allocate
    1566             :  * a buffer to hold the entire log and issue multiple GET_LOG_PAGE commands to
    1567             :  * get all of the entries.
    1568             :  *
    1569             :  * The application is responsible for calling
    1570             :  * \ref spdk_nvme_ctrlr_process_admin_completions to trigger processing of
    1571             :  * completions submitted by this function.
    1572             :  *
    1573             :  * \param ctrlr Pointer to the discovery controller.
    1574             :  * \param cb_fn Function to call when the operation is complete.
    1575             :  * \param cb_arg Argument to pass to cb_fn.
    1576             :  */
    1577             : int spdk_nvme_ctrlr_get_discovery_log_page(struct spdk_nvme_ctrlr *ctrlr,
    1578             :                 spdk_nvme_discovery_cb cb_fn, void *cb_arg);
    1579             : 
    1580             : /**
    1581             :  * NVMe I/O queue pair initialization options.
    1582             :  *
    1583             :  * These options may be passed to spdk_nvme_ctrlr_alloc_io_qpair() to configure queue pair
    1584             :  * options at queue creation time.
    1585             :  *
    1586             :  * The user may retrieve the default I/O queue pair creation options for a controller using
    1587             :  * spdk_nvme_ctrlr_get_default_io_qpair_opts().
    1588             :  */
    1589             : struct spdk_nvme_io_qpair_opts {
    1590             :         /**
    1591             :          * Queue priority for weighted round robin arbitration.  If a different arbitration
    1592             :          * method is in use, pass 0.
    1593             :          */
    1594             :         enum spdk_nvme_qprio qprio;
    1595             : 
    1596             :         /**
    1597             :          * The queue depth of this NVMe I/O queue. Overrides spdk_nvme_ctrlr_opts::io_queue_size.
    1598             :          */
    1599             :         uint32_t io_queue_size;
    1600             : 
    1601             :         /**
    1602             :          * The number of requests to allocate for this NVMe I/O queue.
    1603             :          *
    1604             :          * Overrides spdk_nvme_ctrlr_opts::io_queue_requests.
    1605             :          *
    1606             :          * This should be at least as large as io_queue_size.
    1607             :          *
    1608             :          * A single I/O may allocate more than one request, since splitting may be
    1609             :          * necessary to conform to the device's maximum transfer size, PRP list
    1610             :          * compatibility requirements, or driver-assisted striping.
    1611             :          */
    1612             :         uint32_t io_queue_requests;
    1613             : 
    1614             :         /**
    1615             :          * When submitting I/O via spdk_nvme_ns_read/write and similar functions,
    1616             :          * don't immediately submit it to hardware. Instead, queue up new commands
    1617             :          * and submit them to the hardware inside spdk_nvme_qpair_process_completions().
    1618             :          *
    1619             :          * This results in better batching of I/O commands. Often, it is more efficient
    1620             :          * to submit batches of commands to the underlying hardware than each command
    1621             :          * individually.
    1622             :          *
    1623             :          * This only applies to PCIe and RDMA transports.
    1624             :          *
    1625             :          * The flag was originally named delay_pcie_doorbell. To allow backward compatibility
    1626             :          * both names are kept in unnamed union.
    1627             :          */
    1628             :         union {
    1629             :                 bool delay_cmd_submit;
    1630             :                 bool delay_pcie_doorbell;
    1631             :         };
    1632             : 
    1633             :         /* Hole at bytes 13-15. */
    1634             :         uint8_t reserved13[3];
    1635             : 
    1636             :         /**
    1637             :          * These fields allow specifying the memory buffers for the submission and/or
    1638             :          * completion queues.
    1639             :          * By default, vaddr is set to NULL meaning SPDK will allocate the memory to be used.
    1640             :          * If vaddr is NULL then paddr must be set to 0.
    1641             :          * If vaddr is non-NULL, and paddr is zero, SPDK derives the physical
    1642             :          * address for the NVMe device, in this case the memory must be registered.
    1643             :          * If a paddr value is non-zero, SPDK uses the vaddr and paddr as passed
    1644             :          * SPDK assumes that the memory passed is both virtually and physically
    1645             :          * contiguous.
    1646             :          * If these fields are used, SPDK will NOT impose any restriction
    1647             :          * on the number of elements in the queues.
    1648             :          * The buffer sizes are in number of bytes, and are used to confirm
    1649             :          * that the buffers are large enough to contain the appropriate queue.
    1650             :          * These fields are only used by PCIe attached NVMe devices.  They
    1651             :          * are presently ignored for other transports.
    1652             :          */
    1653             :         struct {
    1654             :                 struct spdk_nvme_cmd *vaddr;
    1655             :                 uint64_t paddr;
    1656             :                 uint64_t buffer_size;
    1657             :         } sq;
    1658             :         struct {
    1659             :                 struct spdk_nvme_cpl *vaddr;
    1660             :                 uint64_t paddr;
    1661             :                 uint64_t buffer_size;
    1662             :         } cq;
    1663             : 
    1664             :         /**
    1665             :          * This flag indicates to the alloc_io_qpair function that it should not perform
    1666             :          * the connect portion on this qpair. This allows the user to add the qpair to a
    1667             :          * poll group and then connect it later.
    1668             :          */
    1669             :         bool create_only;
    1670             : 
    1671             :         /**
    1672             :          * This flag if set to true enables the creation of submission and completion queue
    1673             :          * asynchronously. Default mode is set to false to create io qpair synchronously.
    1674             :          */
    1675             :         bool async_mode;
    1676             : 
    1677             :         /**
    1678             :          * This flag if set to true disables the merging of physically
    1679             :          * contiguous SGL elements. Default mode is set to false to allow
    1680             :          * merging of physically contiguous SGL elements.
    1681             :          */
    1682             :         bool disable_pcie_sgl_merge;
    1683             : 
    1684             :         /* Hole at bytes 67-71. */
    1685             :         uint8_t reserved67[5];
    1686             : };
    1687             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_io_qpair_opts) == 72, "Incorrect size");
    1688             : 
    1689             : /**
    1690             :  * Get the default options for I/O qpair creation for a specific NVMe controller.
    1691             :  *
    1692             :  * \param ctrlr NVMe controller to retrieve the defaults from.
    1693             :  * \param[out] opts Will be filled with the default options for
    1694             :  * spdk_nvme_ctrlr_alloc_io_qpair().
    1695             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts).
    1696             :  */
    1697             : void spdk_nvme_ctrlr_get_default_io_qpair_opts(struct spdk_nvme_ctrlr *ctrlr,
    1698             :                 struct spdk_nvme_io_qpair_opts *opts,
    1699             :                 size_t opts_size);
    1700             : 
    1701             : /**
    1702             :  * Allocate an I/O queue pair (submission and completion queue).
    1703             :  *
    1704             :  * This function by default also performs any connection activities required for
    1705             :  * a newly created qpair. To avoid that behavior, the user should set the create_only
    1706             :  * flag in the opts structure to true.
    1707             :  *
    1708             :  * Each queue pair should only be used from a single thread at a time (mutual
    1709             :  * exclusion must be enforced by the user).
    1710             :  *
    1711             :  * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
    1712             :  * \param opts I/O qpair creation options, or NULL to use the defaults as returned
    1713             :  * by spdk_nvme_ctrlr_get_default_io_qpair_opts().
    1714             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts), or 0
    1715             :  * if opts is NULL.
    1716             :  *
    1717             :  * \return a pointer to the allocated I/O queue pair.
    1718             :  */
    1719             : struct spdk_nvme_qpair *spdk_nvme_ctrlr_alloc_io_qpair(struct spdk_nvme_ctrlr *ctrlr,
    1720             :                 const struct spdk_nvme_io_qpair_opts *opts,
    1721             :                 size_t opts_size);
    1722             : 
    1723             : /**
    1724             :  * Connect a newly created I/O qpair.
    1725             :  *
    1726             :  * This function does any connection activities required for a newly created qpair.
    1727             :  * It should be called after spdk_nvme_ctrlr_alloc_io_qpair has been called with the
    1728             :  * create_only flag set to true in the spdk_nvme_io_qpair_opts structure.
    1729             :  *
    1730             :  * This call will fail if performed on a qpair that is already connected.
    1731             :  * For reconnecting qpairs, see spdk_nvme_ctrlr_reconnect_io_qpair.
    1732             :  *
    1733             :  * For fabrics like TCP and RDMA, this function actually sends the commands over the wire
    1734             :  * that connect the qpair. For PCIe, this function performs some internal state machine operations.
    1735             :  *
    1736             :  * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
    1737             :  * \param qpair Opaque handle to the qpair to connect.
    1738             :  *
    1739             :  * return 0 on success or negated errno on failure. Specifically -EISCONN if the qpair is already connected.
    1740             :  *
    1741             :  */
    1742             : int spdk_nvme_ctrlr_connect_io_qpair(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    1743             : 
    1744             : /**
    1745             :  * Disconnect the given I/O qpair.
    1746             :  *
    1747             :  * This function must be called from the same thread as spdk_nvme_qpair_process_completions
    1748             :  * and the spdk_nvme_ns_cmd_* functions.
    1749             :  *
    1750             :  * After disconnect, calling spdk_nvme_qpair_process_completions or one of the
    1751             :  * spdk_nvme_ns_cmd* on a qpair will result in a return value of -ENXIO. A
    1752             :  * disconnected qpair may be reconnected with either the spdk_nvme_ctrlr_connect_io_qpair
    1753             :  * or spdk_nvme_ctrlr_reconnect_io_qpair APIs.
    1754             :  *
    1755             :  * \param qpair The qpair to disconnect.
    1756             :  */
    1757             : void spdk_nvme_ctrlr_disconnect_io_qpair(struct spdk_nvme_qpair *qpair);
    1758             : 
    1759             : /**
    1760             :  * Attempt to reconnect the given qpair.
    1761             :  *
    1762             :  * This function is intended to be called on qpairs that have already been connected,
    1763             :  * but have since entered a failed state as indicated by a return value of -ENXIO from
    1764             :  * either spdk_nvme_qpair_process_completions or one of the spdk_nvme_ns_cmd_* functions.
    1765             :  * This function must be called from the same thread as spdk_nvme_qpair_process_completions
    1766             :  * and the spdk_nvme_ns_cmd_* functions.
    1767             :  *
    1768             :  * Calling this function has the same effect as calling spdk_nvme_ctrlr_disconnect_io_qpair
    1769             :  * followed by spdk_nvme_ctrlr_connect_io_qpair.
    1770             :  *
    1771             :  * This function may be called on newly created qpairs, but it does extra checks and attempts
    1772             :  * to disconnect the qpair before connecting it. The recommended API for newly created qpairs
    1773             :  * is spdk_nvme_ctrlr_connect_io_qpair.
    1774             :  *
    1775             :  * \param qpair The qpair to reconnect.
    1776             :  *
    1777             :  * \return 0 on success, or if the qpair was already connected.
    1778             :  * -EAGAIN if the driver was unable to reconnect during this call,
    1779             :  * but the controller is still connected and is either resetting or enabled.
    1780             :  * -ENODEV if the controller is removed. In this case, the controller cannot be recovered
    1781             :  * and the application will have to destroy it and the associated qpairs.
    1782             :  * -ENXIO if the controller is in a failed state but is not yet resetting. In this case,
    1783             :  * the application should call spdk_nvme_ctrlr_reset to reset the entire controller.
    1784             :  */
    1785             : int spdk_nvme_ctrlr_reconnect_io_qpair(struct spdk_nvme_qpair *qpair);
    1786             : 
    1787             : /**
    1788             :  * Returns the reason the admin qpair for a given controller is disconnected.
    1789             :  *
    1790             :  * \param ctrlr The controller to check.
    1791             :  *
    1792             :  * \return a valid spdk_nvme_qp_failure_reason.
    1793             :  */
    1794             : spdk_nvme_qp_failure_reason spdk_nvme_ctrlr_get_admin_qp_failure_reason(
    1795             :         struct spdk_nvme_ctrlr *ctrlr);
    1796             : 
    1797             : /**
    1798             :  * Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1799             :  *
    1800             :  * The qpair must not be accessed after calling this function.
    1801             :  *
    1802             :  * \param qpair I/O queue pair to free.
    1803             :  *
    1804             :  * \return 0 on success.  This function will never return any value other than 0.
    1805             :  */
    1806             : int spdk_nvme_ctrlr_free_io_qpair(struct spdk_nvme_qpair *qpair);
    1807             : 
    1808             : /**
    1809             :  * Send the given NVM I/O command, I/O buffers, lists and all to the NVMe controller.
    1810             :  *
    1811             :  * This is a low level interface for submitting I/O commands directly.
    1812             :  *
    1813             :  * This function allows a caller to submit an I/O request that is
    1814             :  * COMPLETELY pre-defined, right down to the "physical" memory buffers.
    1815             :  * It is intended for testing hardware, specifying exact buffer location,
    1816             :  * alignment, and offset.  It also allows for specific choice of PRP
    1817             :  * and SGLs.
    1818             :  *
    1819             :  * The driver sets the CID.  EVERYTHING else is assumed set by the caller.
    1820             :  * Needless to say, this is potentially extremely dangerous for both the host
    1821             :  * (accidental/malicious storage usage/corruption), and the device.
    1822             :  * Thus its intent is for very specific hardware testing and environment
    1823             :  * reproduction.
    1824             :  *
    1825             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1826             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1827             :  * given time.
    1828             :  *
    1829             :  * This function can only be used on PCIe controllers and qpairs.
    1830             :  *
    1831             :  * \param ctrlr Opaque handle to NVMe controller.
    1832             :  * \param qpair I/O qpair to submit command.
    1833             :  * \param cmd NVM I/O command to submit.
    1834             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1835             :  * \param cb_arg Argument passed to callback function.
    1836             :  *
    1837             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    1838             :  * -ENOMEM: The request cannot be allocated.
    1839             :  * -ENXIO: The qpair is failed at the transport level.
    1840             :  */
    1841             : 
    1842             : int spdk_nvme_ctrlr_io_cmd_raw_no_payload_build(struct spdk_nvme_ctrlr *ctrlr,
    1843             :                 struct spdk_nvme_qpair *qpair,
    1844             :                 struct spdk_nvme_cmd *cmd,
    1845             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    1846             : 
    1847             : /**
    1848             :  * Send the given NVM I/O command to the NVMe controller.
    1849             :  *
    1850             :  * This is a low level interface for submitting I/O commands directly. Prefer
    1851             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    1852             :  * not be checked!
    1853             :  *
    1854             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    1855             :  * list/SGL or the CID. The driver will handle both of those for you.
    1856             :  *
    1857             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1858             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1859             :  * given time.
    1860             :  *
    1861             :  * \param ctrlr Opaque handle to NVMe controller.
    1862             :  * \param qpair I/O qpair to submit command.
    1863             :  * \param cmd NVM I/O command to submit.
    1864             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    1865             :  * \param len Size of buffer.
    1866             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1867             :  * \param cb_arg Argument passed to callback function.
    1868             :  *
    1869             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    1870             :  * -ENOMEM: The request cannot be allocated.
    1871             :  * -ENXIO: The qpair is failed at the transport level.
    1872             :  */
    1873             : int spdk_nvme_ctrlr_cmd_io_raw(struct spdk_nvme_ctrlr *ctrlr,
    1874             :                                struct spdk_nvme_qpair *qpair,
    1875             :                                struct spdk_nvme_cmd *cmd,
    1876             :                                void *buf, uint32_t len,
    1877             :                                spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    1878             : 
    1879             : /**
    1880             :  * Send the given NVM I/O command with metadata to the NVMe controller.
    1881             :  *
    1882             :  * This is a low level interface for submitting I/O commands directly. Prefer
    1883             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    1884             :  * not be checked!
    1885             :  *
    1886             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    1887             :  * list/SGL or the CID. The driver will handle both of those for you.
    1888             :  *
    1889             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    1890             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1891             :  * given time.
    1892             :  *
    1893             :  * \param ctrlr Opaque handle to NVMe controller.
    1894             :  * \param qpair I/O qpair to submit command.
    1895             :  * \param cmd NVM I/O command to submit.
    1896             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    1897             :  * \param len Size of buffer.
    1898             :  * \param md_buf Virtual memory address of a single physically contiguous metadata
    1899             :  * buffer.
    1900             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1901             :  * \param cb_arg Argument passed to callback function.
    1902             :  *
    1903             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    1904             :  * -ENOMEM: The request cannot be allocated.
    1905             :  * -ENXIO: The qpair is failed at the transport level.
    1906             :  */
    1907             : int spdk_nvme_ctrlr_cmd_io_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
    1908             :                                        struct spdk_nvme_qpair *qpair,
    1909             :                                        struct spdk_nvme_cmd *cmd,
    1910             :                                        void *buf, uint32_t len, void *md_buf,
    1911             :                                        spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    1912             : 
    1913             : /**
    1914             :  * Restart the SGL walk to the specified offset when the command has scattered
    1915             :  * payloads.
    1916             :  *
    1917             :  * \param cb_arg Argument passed to readv/writev.
    1918             :  * \param offset Offset for SGL.
    1919             :  */
    1920             : typedef void (*spdk_nvme_req_reset_sgl_cb)(void *cb_arg, uint32_t offset);
    1921             : 
    1922             : /**
    1923             :  * Fill out *address and *length with the current SGL entry and advance to the
    1924             :  * next entry for the next time the callback is invoked.
    1925             :  *
    1926             :  * The described segment must be physically contiguous.
    1927             :  *
    1928             :  * \param cb_arg Argument passed to readv/writev.
    1929             :  * \param address Virtual address of this segment, a value of UINT64_MAX
    1930             :  * means the segment should be described via Bit Bucket SGL.
    1931             :  * \param length Length of this physical segment.
    1932             :  */
    1933             : typedef int (*spdk_nvme_req_next_sge_cb)(void *cb_arg, void **address,
    1934             :                 uint32_t *length);
    1935             : 
    1936             : /**
    1937             :  * Send the given NVM I/O command with metadata to the NVMe controller.
    1938             :  *
    1939             :  * This is a low level interface for submitting I/O commands directly. Prefer
    1940             :  * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
    1941             :  * not be checked!
    1942             :  *
    1943             :  * The command is submitted to a qpair allocated by  spdk_nvme_ctrlr_alloc_io_qpair().
    1944             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    1945             :  * given time.
    1946             :  *
    1947             :  * \param ctrlr Opaque handle to NVMe controller.
    1948             :  * \param qpair I/O qpair to submit command.
    1949             :  * \param cmd NVM I/O command to submit.
    1950             :  * \param len Size of buffer.
    1951             :  * \param md_buf Virtual memory address of a single physically contiguous metadata buffer.
    1952             :  * \param cb_fn Callback function invoked when the I/O command completes.
    1953             :  * \param cb_arg Argument passed to callback function.
    1954             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    1955             :  * \param next_sge_fn Callback function to iterate each scattered payload memory segment.
    1956             :  *
    1957             :  * \return 0 if successfully submitted, negated errnos on the following error
    1958             :  conditions:
    1959             :  * -ENOMEM: The request cannot be allocated.
    1960             :  * -ENXIO: The qpair is failed at the transport level.
    1961             :  */
    1962             : int spdk_nvme_ctrlr_cmd_iov_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
    1963             :                                         struct spdk_nvme_qpair *qpair,
    1964             :                                         struct spdk_nvme_cmd *cmd, uint32_t len,
    1965             :                                         void *md_buf, spdk_nvme_cmd_cb cb_fn,
    1966             :                                         void *cb_arg,
    1967             :                                         spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    1968             :                                         spdk_nvme_req_next_sge_cb next_sge_fn);
    1969             : 
    1970             : /**
    1971             :  * Process any outstanding completions for I/O submitted on a queue pair.
    1972             :  *
    1973             :  * This call is non-blocking, i.e. it only processes completions that are ready
    1974             :  * at the time of this function call. It does not wait for outstanding commands
    1975             :  * to finish.
    1976             :  *
    1977             :  * For each completed command, the request's callback function will be called if
    1978             :  * specified as non-NULL when the request was submitted.
    1979             :  *
    1980             :  * The caller must ensure that each queue pair is only used from one thread at a
    1981             :  * time.
    1982             :  *
    1983             :  * This function may be called at any point while the controller is attached to
    1984             :  * the SPDK NVMe driver.
    1985             :  *
    1986             :  * \sa spdk_nvme_cmd_cb
    1987             :  *
    1988             :  * \param qpair Queue pair to check for completions.
    1989             :  * \param max_completions Limit the number of completions to be processed in one
    1990             :  * call, or 0 for unlimited.
    1991             :  *
    1992             :  * \return number of completions processed (may be 0) or negated on error. -ENXIO
    1993             :  * in the special case that the qpair is failed at the transport layer.
    1994             :  */
    1995             : int32_t spdk_nvme_qpair_process_completions(struct spdk_nvme_qpair *qpair,
    1996             :                 uint32_t max_completions);
    1997             : 
    1998             : /**
    1999             :  * Returns the reason the qpair is disconnected.
    2000             :  *
    2001             :  * \param qpair The qpair to check.
    2002             :  *
    2003             :  * \return a valid spdk_nvme_qp_failure_reason.
    2004             :  */
    2005             : spdk_nvme_qp_failure_reason spdk_nvme_qpair_get_failure_reason(struct spdk_nvme_qpair *qpair);
    2006             : 
    2007             : /**
    2008             :  * Control if DNR is set or not for aborted commands.
    2009             :  *
    2010             :  * The default value is false.
    2011             :  *
    2012             :  * \param qpair The qpair to set.
    2013             :  * \param dnr Set the DNR bit to 1 if true or 0 if false for aborted commands.
    2014             :  */
    2015             : void spdk_nvme_qpair_set_abort_dnr(struct spdk_nvme_qpair *qpair, bool dnr);
    2016             : 
    2017             : /**
    2018             :  * Return the connection status of a given qpair.
    2019             :  *
    2020             :  * \param qpair The qpair to check.
    2021             :  *
    2022             :  * \return true if the qpair is connected, or false otherwise.
    2023             :  */
    2024             : bool spdk_nvme_qpair_is_connected(struct spdk_nvme_qpair *qpair);
    2025             : 
    2026             : /**
    2027             :  * Send the given admin command to the NVMe controller.
    2028             :  *
    2029             :  * This is a low level interface for submitting admin commands directly. Prefer
    2030             :  * the spdk_nvme_ctrlr_cmd_* functions instead. The validity of the command will
    2031             :  * not be checked!
    2032             :  *
    2033             :  * When constructing the nvme_command it is not necessary to fill out the PRP
    2034             :  * list/SGL or the CID. The driver will handle both of those for you.
    2035             :  *
    2036             :  * This function is thread safe and can be called at any point while the controller
    2037             :  * is attached to the SPDK NVMe driver.
    2038             :  *
    2039             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2040             :  * of commands submitted through this function.
    2041             :  *
    2042             :  * \param ctrlr Opaque handle to NVMe controller.
    2043             :  * \param cmd NVM admin command to submit.
    2044             :  * \param buf Virtual memory address of a single physically contiguous buffer.
    2045             :  * \param len Size of buffer.
    2046             :  * \param cb_fn Callback function invoked when the admin command completes.
    2047             :  * \param cb_arg Argument passed to callback function.
    2048             :  *
    2049             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2050             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2051             :  */
    2052             : int spdk_nvme_ctrlr_cmd_admin_raw(struct spdk_nvme_ctrlr *ctrlr,
    2053             :                                   struct spdk_nvme_cmd *cmd,
    2054             :                                   void *buf, uint32_t len,
    2055             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2056             : 
    2057             : /**
    2058             :  * Process any outstanding completions for admin commands.
    2059             :  *
    2060             :  * This will process completions for admin commands submitted on any thread.
    2061             :  *
    2062             :  * This call is non-blocking, i.e. it only processes completions that are ready
    2063             :  * at the time of this function call. It does not wait for outstanding commands
    2064             :  * to finish.
    2065             :  *
    2066             :  * This function is thread safe and can be called at any point while the controller
    2067             :  * is attached to the SPDK NVMe driver.
    2068             :  *
    2069             :  * \param ctrlr Opaque handle to NVMe controller.
    2070             :  *
    2071             :  * \return number of completions processed (may be 0) or negated on error. -ENXIO
    2072             :  * in the special case that the qpair is failed at the transport layer.
    2073             :  */
    2074             : int32_t spdk_nvme_ctrlr_process_admin_completions(struct spdk_nvme_ctrlr *ctrlr);
    2075             : 
    2076             : 
    2077             : /**
    2078             :  * Opaque handle to a namespace. Obtained by calling spdk_nvme_ctrlr_get_ns().
    2079             :  */
    2080             : struct spdk_nvme_ns;
    2081             : 
    2082             : /**
    2083             :  * Get a handle to a namespace for the given controller.
    2084             :  *
    2085             :  * Namespaces are numbered from 1 to the total number of namespaces. There will
    2086             :  * never be any gaps in the numbering. The number of namespaces is obtained by
    2087             :  * calling spdk_nvme_ctrlr_get_num_ns().
    2088             :  *
    2089             :  * This function is thread safe and can be called at any point while the controller
    2090             :  * is attached to the SPDK NVMe driver.
    2091             :  *
    2092             :  * \param ctrlr Opaque handle to NVMe controller.
    2093             :  * \param ns_id Namespace id.
    2094             :  *
    2095             :  * \return a pointer to the namespace.
    2096             :  */
    2097             : struct spdk_nvme_ns *spdk_nvme_ctrlr_get_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t ns_id);
    2098             : 
    2099             : /**
    2100             :  * Get a specific log page from the NVMe controller.
    2101             :  *
    2102             :  * This function is thread safe and can be called at any point while the controller
    2103             :  * is attached to the SPDK NVMe driver.
    2104             :  *
    2105             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2106             :  * commands submitted through this function.
    2107             :  *
    2108             :  * \sa spdk_nvme_ctrlr_is_log_page_supported()
    2109             :  *
    2110             :  * \param ctrlr Opaque handle to NVMe controller.
    2111             :  * \param log_page The log page identifier.
    2112             :  * \param nsid Depending on the log page, this may be 0, a namespace identifier,
    2113             :  * or SPDK_NVME_GLOBAL_NS_TAG.
    2114             :  * \param payload The pointer to the payload buffer.
    2115             :  * \param payload_size The size of payload buffer.
    2116             :  * \param offset Offset in bytes within the log page to start retrieving log page
    2117             :  * data. May only be non-zero if the controller supports extended data for Get Log
    2118             :  * Page as reported in the controller data log page attributes.
    2119             :  * \param cb_fn Callback function to invoke when the log page has been retrieved.
    2120             :  * \param cb_arg Argument to pass to the callback function.
    2121             :  *
    2122             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2123             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2124             :  */
    2125             : int spdk_nvme_ctrlr_cmd_get_log_page(struct spdk_nvme_ctrlr *ctrlr,
    2126             :                                      uint8_t log_page, uint32_t nsid,
    2127             :                                      void *payload, uint32_t payload_size,
    2128             :                                      uint64_t offset,
    2129             :                                      spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2130             : 
    2131             : /**
    2132             :  * Get a specific log page from the NVMe controller.
    2133             :  *
    2134             :  * This function is thread safe and can be called at any point while the controller
    2135             :  * is attached to the SPDK NVMe driver.
    2136             :  *
    2137             :  * This function allows specifying extra fields in cdw10 and cdw11 such as
    2138             :  * Retain Asynchronous Event and Log Specific Field.
    2139             :  *
    2140             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2141             :  * commands submitted through this function.
    2142             :  *
    2143             :  * \sa spdk_nvme_ctrlr_is_log_page_supported()
    2144             :  *
    2145             :  * \param ctrlr Opaque handle to NVMe controller.
    2146             :  * \param log_page The log page identifier.
    2147             :  * \param nsid Depending on the log page, this may be 0, a namespace identifier,
    2148             :  * or SPDK_NVME_GLOBAL_NS_TAG.
    2149             :  * \param payload The pointer to the payload buffer.
    2150             :  * \param payload_size The size of payload buffer.
    2151             :  * \param offset Offset in bytes within the log page to start retrieving log page
    2152             :  * data. May only be non-zero if the controller supports extended data for Get Log
    2153             :  * Page as reported in the controller data log page attributes.
    2154             :  * \param cdw10 Value to specify for cdw10.  Specify 0 for numdl - it will be
    2155             :  * set by this function based on the payload_size parameter.  Specify 0 for lid -
    2156             :  * it will be set by this function based on the log_page parameter.
    2157             :  * \param cdw11 Value to specify for cdw11.  Specify 0 for numdu - it will be
    2158             :  * set by this function based on the payload_size.
    2159             :  * \param cdw14 Value to specify for cdw14.
    2160             :  * \param cb_fn Callback function to invoke when the log page has been retrieved.
    2161             :  * \param cb_arg Argument to pass to the callback function.
    2162             :  *
    2163             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2164             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2165             :  */
    2166             : int spdk_nvme_ctrlr_cmd_get_log_page_ext(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page,
    2167             :                 uint32_t nsid, void *payload, uint32_t payload_size,
    2168             :                 uint64_t offset, uint32_t cdw10, uint32_t cdw11,
    2169             :                 uint32_t cdw14, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2170             : 
    2171             : /**
    2172             :  * Abort a specific previously-submitted NVMe command.
    2173             :  *
    2174             :  * \sa spdk_nvme_ctrlr_register_timeout_callback()
    2175             :  *
    2176             :  * \param ctrlr NVMe controller to which the command was submitted.
    2177             :  * \param qpair NVMe queue pair to which the command was submitted. For admin
    2178             :  *  commands, pass NULL for the qpair.
    2179             :  * \param cid Command ID of the command to abort.
    2180             :  * \param cb_fn Callback function to invoke when the abort has completed.
    2181             :  * \param cb_arg Argument to pass to the callback function.
    2182             :  *
    2183             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2184             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2185             :  */
    2186             : int spdk_nvme_ctrlr_cmd_abort(struct spdk_nvme_ctrlr *ctrlr,
    2187             :                               struct spdk_nvme_qpair *qpair,
    2188             :                               uint16_t cid,
    2189             :                               spdk_nvme_cmd_cb cb_fn,
    2190             :                               void *cb_arg);
    2191             : 
    2192             : /**
    2193             :  * Abort previously submitted commands which have cmd_cb_arg as its callback argument.
    2194             :  *
    2195             :  * \param ctrlr NVMe controller to which the commands were submitted.
    2196             :  * \param qpair NVMe queue pair to which the commands were submitted. For admin
    2197             :  * commands, pass NULL for the qpair.
    2198             :  * \param cmd_cb_arg Callback argument for the NVMe commands which this function
    2199             :  * attempts to abort.
    2200             :  * \param cb_fn Callback function to invoke when this function has completed.
    2201             :  * \param cb_arg Argument to pass to the callback function.
    2202             :  *
    2203             :  * \return 0 if successfully submitted, negated errno otherwise.
    2204             :  */
    2205             : int spdk_nvme_ctrlr_cmd_abort_ext(struct spdk_nvme_ctrlr *ctrlr,
    2206             :                                   struct spdk_nvme_qpair *qpair,
    2207             :                                   void *cmd_cb_arg,
    2208             :                                   spdk_nvme_cmd_cb cb_fn,
    2209             :                                   void *cb_arg);
    2210             : 
    2211             : /**
    2212             :  * Set specific feature for the given NVMe controller.
    2213             :  *
    2214             :  * This function is thread safe and can be called at any point while the controller
    2215             :  * is attached to the SPDK NVMe driver.
    2216             :  *
    2217             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2218             :  * commands submitted through this function.
    2219             :  *
    2220             :  * \sa spdk_nvme_ctrlr_cmd_get_feature().
    2221             :  *
    2222             :  * \param ctrlr NVMe controller to manipulate.
    2223             :  * \param feature The feature identifier.
    2224             :  * \param cdw11 as defined by the specification for this command.
    2225             :  * \param cdw12 as defined by the specification for this command.
    2226             :  * \param payload The pointer to the payload buffer.
    2227             :  * \param payload_size The size of payload buffer.
    2228             :  * \param cb_fn Callback function to invoke when the feature has been set.
    2229             :  * \param cb_arg Argument to pass to the callback function.
    2230             :  *
    2231             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2232             :  * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2233             :  */
    2234             : int spdk_nvme_ctrlr_cmd_set_feature(struct spdk_nvme_ctrlr *ctrlr,
    2235             :                                     uint8_t feature, uint32_t cdw11, uint32_t cdw12,
    2236             :                                     void *payload, uint32_t payload_size,
    2237             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2238             : 
    2239             : /**
    2240             :  * Get specific feature from given NVMe controller.
    2241             :  *
    2242             :  * This function is thread safe and can be called at any point while the controller
    2243             :  * is attached to the SPDK NVMe driver.
    2244             :  *
    2245             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2246             :  * commands submitted through this function.
    2247             :  *
    2248             :  * \sa spdk_nvme_ctrlr_cmd_set_feature()
    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             :  *
    2258             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2259             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2260             :  */
    2261             : int spdk_nvme_ctrlr_cmd_get_feature(struct spdk_nvme_ctrlr *ctrlr,
    2262             :                                     uint8_t feature, uint32_t cdw11,
    2263             :                                     void *payload, uint32_t payload_size,
    2264             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2265             : 
    2266             : /**
    2267             :  * Get specific feature from given NVMe controller.
    2268             :  *
    2269             :  * \param ctrlr NVMe controller to query.
    2270             :  * \param feature The feature identifier.
    2271             :  * \param cdw11 as defined by the specification for this command.
    2272             :  * \param payload The pointer to the payload buffer.
    2273             :  * \param payload_size The size of payload buffer.
    2274             :  * \param cb_fn Callback function to invoke when the feature has been retrieved.
    2275             :  * \param cb_arg Argument to pass to the callback function.
    2276             :  * \param ns_id The namespace identifier.
    2277             :  *
    2278             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2279             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2280             :  *
    2281             :  * This function is thread safe and can be called at any point while the controller
    2282             :  * is attached to the SPDK NVMe driver.
    2283             :  *
    2284             :  * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2285             :  * of commands submitted through this function.
    2286             :  *
    2287             :  * \sa spdk_nvme_ctrlr_cmd_set_feature_ns()
    2288             :  */
    2289             : int spdk_nvme_ctrlr_cmd_get_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
    2290             :                                        uint32_t cdw11, void *payload, uint32_t payload_size,
    2291             :                                        spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id);
    2292             : 
    2293             : /**
    2294             :  * Set specific feature for the given NVMe controller and namespace ID.
    2295             :  *
    2296             :  * \param ctrlr NVMe controller to manipulate.
    2297             :  * \param feature The feature identifier.
    2298             :  * \param cdw11 as defined by the specification for this command.
    2299             :  * \param cdw12 as defined by the specification for this command.
    2300             :  * \param payload The pointer to the payload buffer.
    2301             :  * \param payload_size The size of payload buffer.
    2302             :  * \param cb_fn Callback function to invoke when the feature has been set.
    2303             :  * \param cb_arg Argument to pass to the callback function.
    2304             :  * \param ns_id The namespace identifier.
    2305             :  *
    2306             :  * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
    2307             :  * for this request, -ENXIO if the admin qpair is failed at the transport layer.
    2308             :  *
    2309             :  * This function is thread safe and can be called at any point while the controller
    2310             :  * is attached to the SPDK NVMe driver.
    2311             :  *
    2312             :  * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
    2313             :  * of commands submitted through this function.
    2314             :  *
    2315             :  * \sa spdk_nvme_ctrlr_cmd_get_feature_ns()
    2316             :  */
    2317             : int spdk_nvme_ctrlr_cmd_set_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
    2318             :                                        uint32_t cdw11, uint32_t cdw12, void *payload,
    2319             :                                        uint32_t payload_size, spdk_nvme_cmd_cb cb_fn,
    2320             :                                        void *cb_arg, uint32_t ns_id);
    2321             : 
    2322             : /**
    2323             :  * Receive security protocol data from controller.
    2324             :  *
    2325             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2326             :  *
    2327             :  * \param ctrlr NVMe controller to use for security receive command submission.
    2328             :  * \param secp Security Protocol that is used.
    2329             :  * \param spsp Security Protocol Specific field.
    2330             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2331             :  * Protocol EAh.
    2332             :  * \param payload The pointer to the payload buffer.
    2333             :  * \param payload_size The size of payload buffer.
    2334             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2335             :  * \param cb_arg Argument to pass to the callback function.
    2336             :  *
    2337             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2338             :  * for this request.
    2339             :  */
    2340             : int spdk_nvme_ctrlr_cmd_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2341             :                 uint16_t spsp, uint8_t nssf, void *payload,
    2342             :                 uint32_t payload_size,
    2343             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2344             : 
    2345             : /**
    2346             :  * Send security protocol data to controller.
    2347             :  *
    2348             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2349             :  *
    2350             :  * \param ctrlr NVMe controller to use for security send command submission.
    2351             :  * \param secp Security Protocol that is used.
    2352             :  * \param spsp Security Protocol Specific field.
    2353             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2354             :  * Protocol EAh.
    2355             :  * \param payload The pointer to the payload buffer.
    2356             :  * \param payload_size The size of payload buffer.
    2357             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2358             :  * \param cb_arg Argument to pass to the callback function.
    2359             :  *
    2360             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2361             :  * for this request.
    2362             :  */
    2363             : int spdk_nvme_ctrlr_cmd_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2364             :                                       uint16_t spsp, uint8_t nssf, void *payload,
    2365             :                                       uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2366             : 
    2367             : /**
    2368             :  * Receive security protocol data from 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 receive 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_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2384             :                                      uint16_t spsp, uint8_t nssf, void *payload, size_t size);
    2385             : 
    2386             : /**
    2387             :  * Send security protocol data to controller.
    2388             :  *
    2389             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2390             :  *
    2391             :  * \param ctrlr NVMe controller to use for security send command submission.
    2392             :  * \param secp Security Protocol that is used.
    2393             :  * \param spsp Security Protocol Specific field.
    2394             :  * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
    2395             :  * Protocol EAh.
    2396             :  * \param payload The pointer to the payload buffer.
    2397             :  * \param size The size of payload buffer.
    2398             :  *
    2399             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2400             :  * for this request.
    2401             :  */
    2402             : int spdk_nvme_ctrlr_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
    2403             :                                   uint16_t spsp, uint8_t nssf, void *payload, size_t size);
    2404             : 
    2405             : /**
    2406             :  * Receive data related to a specific Directive Type from the controller.
    2407             :  *
    2408             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2409             :  *
    2410             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2411             :  * commands submitted through this function.
    2412             :  *
    2413             :  * \param ctrlr NVMe controller to use for directive receive command submission.
    2414             :  * \param nsid Specific Namespace Identifier.
    2415             :  * \param doper Directive Operation defined in nvme_spec.h.
    2416             :  * \param dtype Directive Type defined in nvme_spec.h.
    2417             :  * \param dspec Directive Specific defined in nvme_spec.h.
    2418             :  * \param payload The pointer to the payload buffer.
    2419             :  * \param payload_size The size of payload buffer.
    2420             :  * \param cdw12 Command dword 12.
    2421             :  * \param cdw13 Command dword 13.
    2422             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2423             :  * \param cb_arg Argument to pass to the callback function.
    2424             :  *
    2425             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2426             :  * for this request.
    2427             :  */
    2428             : int spdk_nvme_ctrlr_cmd_directive_receive(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2429             :                 uint32_t doper, uint32_t dtype, uint32_t dspec,
    2430             :                 void *payload, uint32_t payload_size, uint32_t cdw12,
    2431             :                 uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2432             : 
    2433             : /**
    2434             :  * Send data related to a specific Directive Type to the controller.
    2435             :  *
    2436             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2437             :  *
    2438             :  * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
    2439             :  * commands submitted through this function.
    2440             :  *
    2441             :  * \param ctrlr NVMe controller to use for directive send command submission.
    2442             :  * \param nsid Specific Namespace Identifier.
    2443             :  * \param doper Directive Operation defined in nvme_spec.h.
    2444             :  * \param dtype Directive Type defined in nvme_spec.h.
    2445             :  * \param dspec Directive Specific defined in nvme_spec.h.
    2446             :  * \param payload The pointer to the payload buffer.
    2447             :  * \param payload_size The size of payload buffer.
    2448             :  * \param cdw12 Command dword 12.
    2449             :  * \param cdw13 Command dword 13.
    2450             :  * \param cb_fn Callback function to invoke when the command has been completed.
    2451             :  * \param cb_arg Argument to pass to the callback function.
    2452             :  *
    2453             :  * \return 0 if successfully submitted, negated errno if resources could not be allocated
    2454             :  * for this request.
    2455             :  */
    2456             : int spdk_nvme_ctrlr_cmd_directive_send(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2457             :                                        uint32_t doper, uint32_t dtype, uint32_t dspec,
    2458             :                                        void *payload, uint32_t payload_size, uint32_t cdw12,
    2459             :                                        uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2460             : 
    2461             : /**
    2462             :  * Get supported flags of the controller.
    2463             :  *
    2464             :  * \param ctrlr NVMe controller to get flags.
    2465             :  *
    2466             :  * \return supported flags of this controller.
    2467             :  */
    2468             : uint64_t spdk_nvme_ctrlr_get_flags(struct spdk_nvme_ctrlr *ctrlr);
    2469             : 
    2470             : /**
    2471             :  * Attach the specified namespace to controllers.
    2472             :  *
    2473             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2474             :  *
    2475             :  * \param ctrlr NVMe controller to use for command submission.
    2476             :  * \param nsid Namespace identifier for namespace to attach.
    2477             :  * \param payload The pointer to the controller list.
    2478             :  *
    2479             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2480             :  * for this request.
    2481             :  */
    2482             : int spdk_nvme_ctrlr_attach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2483             :                               struct spdk_nvme_ctrlr_list *payload);
    2484             : 
    2485             : /**
    2486             :  * Detach the specified namespace from controllers.
    2487             :  *
    2488             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2489             :  *
    2490             :  * \param ctrlr NVMe controller to use for command submission.
    2491             :  * \param nsid Namespace ID to detach.
    2492             :  * \param payload The pointer to the controller list.
    2493             :  *
    2494             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2495             :  * for this request
    2496             :  */
    2497             : int spdk_nvme_ctrlr_detach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2498             :                               struct spdk_nvme_ctrlr_list *payload);
    2499             : 
    2500             : /**
    2501             :  * Create a namespace.
    2502             :  *
    2503             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2504             :  *
    2505             :  * \param ctrlr NVMe controller to create namespace on.
    2506             :  * \param payload The pointer to the NVMe namespace data.
    2507             :  *
    2508             :  * \return Namespace ID (>= 1) if successfully created, or 0 if the request failed.
    2509             :  */
    2510             : uint32_t spdk_nvme_ctrlr_create_ns(struct spdk_nvme_ctrlr *ctrlr,
    2511             :                                    struct spdk_nvme_ns_data *payload);
    2512             : 
    2513             : /**
    2514             :  * Delete a namespace.
    2515             :  *
    2516             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2517             :  *
    2518             :  * \param ctrlr NVMe controller to delete namespace from.
    2519             :  * \param nsid The namespace identifier.
    2520             :  *
    2521             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2522             :  * allocated
    2523             :  * for this request
    2524             :  */
    2525             : int spdk_nvme_ctrlr_delete_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
    2526             : 
    2527             : /**
    2528             :  * Format NVM.
    2529             :  *
    2530             :  * This function requests a low-level format of the media.
    2531             :  *
    2532             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2533             :  *
    2534             :  * \param ctrlr NVMe controller to format.
    2535             :  * \param nsid The namespace identifier. May be SPDK_NVME_GLOBAL_NS_TAG to format
    2536             :  * all namespaces.
    2537             :  * \param format The format information for the command.
    2538             :  *
    2539             :  * \return 0 if successfully submitted, negated errno if resources could not be
    2540             :  * allocated for this request
    2541             :  */
    2542             : int spdk_nvme_ctrlr_format(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    2543             :                            struct spdk_nvme_format *format);
    2544             : 
    2545             : /**
    2546             :  * Download a new firmware image.
    2547             :  *
    2548             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2549             :  *
    2550             :  * \param ctrlr NVMe controller to perform firmware operation on.
    2551             :  * \param payload The data buffer for the firmware image.
    2552             :  * \param size The data size will be downloaded.
    2553             :  * \param slot The slot that the firmware image will be committed to.
    2554             :  * \param commit_action The action to perform when firmware is committed.
    2555             :  * \param completion_status output parameter. Contains the completion status of
    2556             :  * the firmware commit operation.
    2557             :  *
    2558             :  * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
    2559             :  * for this request, -1 if the size is not multiple of 4.
    2560             :  */
    2561             : int spdk_nvme_ctrlr_update_firmware(struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size,
    2562             :                                     int slot, enum spdk_nvme_fw_commit_action commit_action,
    2563             :                                     struct spdk_nvme_status *completion_status);
    2564             : 
    2565             : /**
    2566             :  * Start the Read from a Boot Partition.
    2567             :  *
    2568             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2569             :  *
    2570             :  * \param ctrlr NVMe controller to perform the Boot Partition read.
    2571             :  * \param payload The data buffer for Boot Partition read.
    2572             :  * \param bprsz Read size in multiples of 4 KiB to copy into the Boot Partition Memory Buffer.
    2573             :  * \param bprof Boot Partition offset to read from in 4 KiB units.
    2574             :  * \param bpid Boot Partition identifier for the Boot Partition read operation.
    2575             :  *
    2576             :  * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
    2577             :  * -ENOMEM: if resources could not be allocated.
    2578             :  * -ENOTSUP: Boot Partition is not supported by the Controller.
    2579             :  * -EIO: Registers access failure.
    2580             :  * -EINVAL: Parameters are invalid.
    2581             :  * -EFAULT: Invalid address was specified as part of payload.
    2582             :  * -EALREADY: Boot Partition read already initiated.
    2583             :  */
    2584             : int spdk_nvme_ctrlr_read_boot_partition_start(struct spdk_nvme_ctrlr *ctrlr, void *payload,
    2585             :                 uint32_t bprsz, uint32_t bprof, uint32_t bpid);
    2586             : 
    2587             : /**
    2588             :  * Poll the status of the Read from a Boot Partition.
    2589             :  *
    2590             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2591             :  *
    2592             :  * \param ctrlr NVMe controller to perform the Boot Partition read.
    2593             :  *
    2594             :  * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
    2595             :  * -EIO: Registers access failure.
    2596             :  * -EINVAL: Invalid read status or the Boot Partition read is not initiated yet.
    2597             :  * -EAGAIN: If the read is still in progress; users must call
    2598             :  * spdk_nvme_ctrlr_read_boot_partition_poll again to check the read status.
    2599             :  */
    2600             : int spdk_nvme_ctrlr_read_boot_partition_poll(struct spdk_nvme_ctrlr *ctrlr);
    2601             : 
    2602             : /**
    2603             :  * Write to a Boot Partition.
    2604             :  *
    2605             :  * This function is thread safe and can be called at any point after spdk_nvme_probe().
    2606             :  * Users will get the completion after the data is downloaded, image is replaced and
    2607             :  * Boot Partition is activated or when the sequence encounters an error.
    2608             :  *
    2609             :  * \param ctrlr NVMe controller to perform the Boot Partition write.
    2610             :  * \param payload The data buffer for Boot Partition write.
    2611             :  * \param size Data size to write to the Boot Partition.
    2612             :  * \param bpid Boot Partition identifier for the Boot Partition write operation.
    2613             :  * \param cb_fn Callback function to invoke when the operation is completed.
    2614             :  * \param cb_arg Argument to pass to the callback function.
    2615             :  *
    2616             :  * \return 0 if Boot Partition write submit is successful. Negated errno on the following error conditions:
    2617             :  * -ENOMEM: if resources could not be allocated.
    2618             :  * -ENOTSUP: Boot Partition is not supported by the Controller.
    2619             :  * -EIO: Registers access failure.
    2620             :  * -EINVAL: Parameters are invalid.
    2621             :  */
    2622             : int spdk_nvme_ctrlr_write_boot_partition(struct spdk_nvme_ctrlr *ctrlr, void *payload,
    2623             :                 uint32_t size, uint32_t bpid, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    2624             : 
    2625             : /**
    2626             :  * Return virtual address of PCIe NVM I/O registers
    2627             :  *
    2628             :  * This function returns a pointer to the PCIe I/O registers for a controller
    2629             :  * or NULL if unsupported for this transport.
    2630             :  *
    2631             :  * \param ctrlr Controller whose registers are to be accessed.
    2632             :  *
    2633             :  * \return Pointer to virtual address of register bank, or NULL.
    2634             :  */
    2635             : volatile struct spdk_nvme_registers *spdk_nvme_ctrlr_get_registers(struct spdk_nvme_ctrlr *ctrlr);
    2636             : 
    2637             : /**
    2638             :  * Reserve the controller memory buffer for data transfer use.
    2639             :  *
    2640             :  * This function reserves the full size of the controller memory buffer
    2641             :  * for use in data transfers. If submission queues or completion queues are
    2642             :  * already placed in the controller memory buffer, this call will fail.
    2643             :  *
    2644             :  * \param ctrlr Controller from which to allocate memory buffer
    2645             :  *
    2646             :  * \return The size of the controller memory buffer on success. Negated errno
    2647             :  * on failure.
    2648             :  */
    2649             : int spdk_nvme_ctrlr_reserve_cmb(struct spdk_nvme_ctrlr *ctrlr);
    2650             : 
    2651             : /**
    2652             :  * Map a previously reserved controller memory buffer so that it's data is
    2653             :  * visible from the CPU. This operation is not always possible.
    2654             :  *
    2655             :  * \param ctrlr Controller that contains the memory buffer
    2656             :  * \param size Size of buffer that was mapped.
    2657             :  *
    2658             :  * \return Pointer to controller memory buffer, or NULL on failure.
    2659             :  */
    2660             : void *spdk_nvme_ctrlr_map_cmb(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    2661             : 
    2662             : /**
    2663             :  * Free a controller memory I/O buffer.
    2664             :  *
    2665             :  * \param ctrlr Controller from which to unmap the memory buffer.
    2666             :  */
    2667             : void spdk_nvme_ctrlr_unmap_cmb(struct spdk_nvme_ctrlr *ctrlr);
    2668             : 
    2669             : /**
    2670             :  * Enable the Persistent Memory Region
    2671             :  *
    2672             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2673             :  *
    2674             :  * \return 0 on success. Negated errno on the following error conditions:
    2675             :  * -ENOTSUP: PMR is not supported by the Controller.
    2676             :  * -EIO: Registers access failure.
    2677             :  * -EINVAL: PMR Time Units Invalid or PMR is already enabled.
    2678             :  * -ETIMEDOUT: Timed out to Enable PMR.
    2679             :  * -ENOSYS: Transport does not support Enable PMR function.
    2680             :  */
    2681             : int spdk_nvme_ctrlr_enable_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2682             : 
    2683             : /**
    2684             :  * Disable the Persistent Memory Region
    2685             :  *
    2686             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2687             :  *
    2688             :  * \return 0 on success. Negated errno on the following error conditions:
    2689             :  * -ENOTSUP: PMR is not supported by the Controller.
    2690             :  * -EIO: Registers access failure.
    2691             :  * -EINVAL: PMR Time Units Invalid or PMR is already disabled.
    2692             :  * -ETIMEDOUT: Timed out to Disable PMR.
    2693             :  * -ENOSYS: Transport does not support Disable PMR function.
    2694             :  */
    2695             : int spdk_nvme_ctrlr_disable_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2696             : 
    2697             : /**
    2698             :  * Map the Persistent Memory Region so that it's data is
    2699             :  * visible from the CPU.
    2700             :  *
    2701             :  * \param ctrlr Controller that contains the Persistent Memory Region
    2702             :  * \param size Size of the region that was mapped.
    2703             :  *
    2704             :  * \return Pointer to Persistent Memory Region, or NULL on failure.
    2705             :  */
    2706             : void *spdk_nvme_ctrlr_map_pmr(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    2707             : 
    2708             : /**
    2709             :  * Free the Persistent Memory Region.
    2710             :  *
    2711             :  * \param ctrlr Controller from which to unmap the Persistent Memory Region.
    2712             :  *
    2713             :  * \return 0 on success, negative errno on failure.
    2714             :  * -ENXIO: Either PMR is not supported by the Controller or the PMR is already unmapped.
    2715             :  * -ENOSYS: Transport does not support Unmap PMR function.
    2716             :  */
    2717             : int spdk_nvme_ctrlr_unmap_pmr(struct spdk_nvme_ctrlr *ctrlr);
    2718             : 
    2719             : /**
    2720             :  * Get the transport ID for a given NVMe controller.
    2721             :  *
    2722             :  * \param ctrlr Controller to get the transport ID.
    2723             :  * \return Pointer to the controller's transport ID.
    2724             :  */
    2725             : const struct spdk_nvme_transport_id *spdk_nvme_ctrlr_get_transport_id(
    2726             :         struct spdk_nvme_ctrlr *ctrlr);
    2727             : 
    2728             : /**
    2729             :  * \brief Alloc NVMe I/O queue identifier.
    2730             :  *
    2731             :  * This function is only needed for the non-standard case of allocating queues using the raw
    2732             :  * command interface. In most cases \ref spdk_nvme_ctrlr_alloc_io_qpair should be sufficient.
    2733             :  *
    2734             :  * \param ctrlr Opaque handle to NVMe controller.
    2735             :  * \return qid on success, -1 on failure.
    2736             :  */
    2737             : int32_t spdk_nvme_ctrlr_alloc_qid(struct spdk_nvme_ctrlr *ctrlr);
    2738             : 
    2739             : /**
    2740             :  * \brief Free NVMe I/O queue identifier.
    2741             :  *
    2742             :  * This function must only be called with qids previously allocated with \ref spdk_nvme_ctrlr_alloc_qid.
    2743             :  *
    2744             :  * \param ctrlr Opaque handle to NVMe controller.
    2745             :  * \param qid NVMe Queue Identifier.
    2746             :  */
    2747             : void spdk_nvme_ctrlr_free_qid(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid);
    2748             : 
    2749             : /**
    2750             :  * Opaque handle for a poll group. A poll group is a collection of spdk_nvme_qpair
    2751             :  * objects that are polled for completions as a unit.
    2752             :  *
    2753             :  * Returned by spdk_nvme_poll_group_create().
    2754             :  */
    2755             : struct spdk_nvme_poll_group;
    2756             : 
    2757             : 
    2758             : /**
    2759             :  * This function alerts the user to disconnected qpairs when calling
    2760             :  * spdk_nvme_poll_group_process_completions.
    2761             :  */
    2762             : typedef void (*spdk_nvme_disconnected_qpair_cb)(struct spdk_nvme_qpair *qpair,
    2763             :                 void *poll_group_ctx);
    2764             : 
    2765             : /**
    2766             :  * Create a new poll group.
    2767             :  *
    2768             :  * \param ctx A user supplied context that can be retrieved later with spdk_nvme_poll_group_get_ctx
    2769             :  * \param table The call back table defined by users which contains the accelerated functions
    2770             :  * which can be used to accelerate some operations such as crc32c.
    2771             :  *
    2772             :  * \return Pointer to the new poll group, or NULL on error.
    2773             :  */
    2774             : struct spdk_nvme_poll_group *spdk_nvme_poll_group_create(void *ctx,
    2775             :                 struct spdk_nvme_accel_fn_table *table);
    2776             : 
    2777             : /**
    2778             :  * Get a optimal poll group.
    2779             :  *
    2780             :  * \param qpair The qpair to get the optimal poll group.
    2781             :  *
    2782             :  * \return Pointer to the optimal poll group, or NULL if not found.
    2783             :  */
    2784             : struct spdk_nvme_poll_group *spdk_nvme_qpair_get_optimal_poll_group(struct spdk_nvme_qpair *qpair);
    2785             : 
    2786             : /**
    2787             :  * Add an spdk_nvme_qpair to a poll group. qpairs may only be added to
    2788             :  * a poll group if they are in the disconnected state; i.e. either they were
    2789             :  * just allocated and not yet connected or they have been disconnected with a call
    2790             :  * to spdk_nvme_ctrlr_disconnect_io_qpair.
    2791             :  *
    2792             :  * \param group The group to which the qpair will be added.
    2793             :  * \param qpair The qpair to add to the poll group.
    2794             :  *
    2795             :  * return 0 on success, -EINVAL if the qpair is not in the disabled state, -ENODEV if the transport
    2796             :  * doesn't exist, -ENOMEM on memory allocation failures, or -EPROTO on a protocol (transport) specific failure.
    2797             :  */
    2798             : int spdk_nvme_poll_group_add(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
    2799             : 
    2800             : /**
    2801             :  * Remove a disconnected spdk_nvme_qpair from a poll group.
    2802             :  *
    2803             :  * \param group The group from which to remove the qpair.
    2804             :  * \param qpair The qpair to remove from the poll group.
    2805             :  *
    2806             :  * return 0 on success, -ENOENT if the qpair is not found in the group, -EINVAL if the qpair is not
    2807             :  * disconnected in the group, or -EPROTO on a protocol (transport) specific failure.
    2808             :  */
    2809             : int spdk_nvme_poll_group_remove(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
    2810             : 
    2811             : /**
    2812             :  * Destroy an empty poll group.
    2813             :  *
    2814             :  * \param group The group to destroy.
    2815             :  *
    2816             :  * return 0 on success, -EBUSY if the poll group is not empty.
    2817             :  */
    2818             : int spdk_nvme_poll_group_destroy(struct spdk_nvme_poll_group *group);
    2819             : 
    2820             : /**
    2821             :  * Poll for completions on all qpairs in this poll group.
    2822             :  *
    2823             :  * the disconnected_qpair_cb will be called for all disconnected qpairs in the poll group
    2824             :  * including qpairs which fail within the context of this call.
    2825             :  * The user is responsible for trying to reconnect or destroy those qpairs.
    2826             :  *
    2827             :  * \param group The group on which to poll for completions.
    2828             :  * \param completions_per_qpair The maximum number of completions per qpair.
    2829             :  * \param disconnected_qpair_cb A callback function of type spdk_nvme_disconnected_qpair_cb. Must be non-NULL.
    2830             :  *
    2831             :  * return The number of completions across all qpairs, -EINVAL if no disconnected_qpair_cb is passed, or
    2832             :  * -EIO if the shared completion queue cannot be polled for the RDMA transport.
    2833             :  */
    2834             : int64_t spdk_nvme_poll_group_process_completions(struct spdk_nvme_poll_group *group,
    2835             :                 uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
    2836             : 
    2837             : /**
    2838             :  * Check if all qpairs in the poll group are connected.
    2839             :  *
    2840             :  * This function allows the caller to check if all qpairs in a poll group are
    2841             :  * connected. This API is generally only suitable during application startup,
    2842             :  * to check when a large number of async connections have completed.
    2843             :  *
    2844             :  * It is useful for applications like benchmarking tools to create
    2845             :  * a large number of qpairs, but then ensuring they are all fully connected before
    2846             :  * proceeding with I/O.
    2847             :  *
    2848             :  * \param group The group on which to poll connecting qpairs.
    2849             :  *
    2850             :  * return 0 if all qpairs are in CONNECTED state, -EIO if any connections failed to connect, -EAGAIN if
    2851             :  * any qpairs are still trying to connected.
    2852             :  */
    2853             : int spdk_nvme_poll_group_all_connected(struct spdk_nvme_poll_group *group);
    2854             : 
    2855             : /**
    2856             :  * Retrieve the user context for this specific poll group.
    2857             :  *
    2858             :  * \param group The poll group from which to retrieve the context.
    2859             :  *
    2860             :  * \return A pointer to the user provided poll group context.
    2861             :  */
    2862             : void *spdk_nvme_poll_group_get_ctx(struct spdk_nvme_poll_group *group);
    2863             : 
    2864             : /**
    2865             :  * Retrieves transport statistics for the given poll group.
    2866             :  *
    2867             :  * Note: the structure returned by this function should later be freed with
    2868             :  * @b spdk_nvme_poll_group_free_stats function
    2869             :  *
    2870             :  * \param group Pointer to NVME poll group
    2871             :  * \param stats Double pointer to statistics to be filled by this function
    2872             :  * \return 0 on success or negated errno on failure
    2873             :  */
    2874             : int spdk_nvme_poll_group_get_stats(struct spdk_nvme_poll_group *group,
    2875             :                                    struct spdk_nvme_poll_group_stat **stats);
    2876             : 
    2877             : /**
    2878             :  * Frees poll group statistics retrieved using @b spdk_nvme_poll_group_get_stats function
    2879             :  *
    2880             :  * @param group Pointer to a poll group
    2881             :  * @param stat Pointer to statistics to be released
    2882             :  */
    2883             : void spdk_nvme_poll_group_free_stats(struct spdk_nvme_poll_group *group,
    2884             :                                      struct spdk_nvme_poll_group_stat *stat);
    2885             : 
    2886             : /**
    2887             :  * Get the identify namespace data as defined by the NVMe specification.
    2888             :  *
    2889             :  * This function is thread safe and can be called at any point while the controller
    2890             :  * is attached to the SPDK NVMe driver.
    2891             :  *
    2892             :  * \param ns Namespace.
    2893             :  *
    2894             :  * \return a pointer to the namespace data.
    2895             :  */
    2896             : const struct spdk_nvme_ns_data *spdk_nvme_ns_get_data(struct spdk_nvme_ns *ns);
    2897             : 
    2898             : /**
    2899             :  * Get the I/O command set specific identify namespace data for NVM command set
    2900             :  * as defined by the NVMe specification.
    2901             :  *
    2902             :  * This function is thread safe and can be called at any point while the controller
    2903             :  * is attached to the SPDK NVMe driver.
    2904             :  *
    2905             :  * \param ns Namespace.
    2906             :  *
    2907             :  * \return a pointer to the identify namespace data.
    2908             :  */
    2909             : const struct spdk_nvme_nvm_ns_data *spdk_nvme_nvm_ns_get_data(struct spdk_nvme_ns *ns);
    2910             : 
    2911             : /**
    2912             :  * Get the namespace id (index number) from the given namespace handle.
    2913             :  *
    2914             :  * This function is thread safe and can be called at any point while the controller
    2915             :  * is attached to the SPDK NVMe driver.
    2916             :  *
    2917             :  * \param ns Namespace.
    2918             :  *
    2919             :  * \return namespace id.
    2920             :  */
    2921             : uint32_t spdk_nvme_ns_get_id(struct spdk_nvme_ns *ns);
    2922             : 
    2923             : /**
    2924             :  * Get the controller with which this namespace is associated.
    2925             :  *
    2926             :  * This function is thread safe and can be called at any point while the controller
    2927             :  * is attached to the SPDK NVMe driver.
    2928             :  *
    2929             :  * \param ns Namespace.
    2930             :  *
    2931             :  * \return a pointer to the controller.
    2932             :  */
    2933             : struct spdk_nvme_ctrlr *spdk_nvme_ns_get_ctrlr(struct spdk_nvme_ns *ns);
    2934             : 
    2935             : /**
    2936             :  * Determine whether a namespace is active.
    2937             :  *
    2938             :  * Inactive namespaces cannot be the target of I/O commands.
    2939             :  *
    2940             :  * \param ns Namespace to query.
    2941             :  *
    2942             :  * \return true if active, or false if inactive.
    2943             :  */
    2944             : bool spdk_nvme_ns_is_active(struct spdk_nvme_ns *ns);
    2945             : 
    2946             : /**
    2947             :  * Get the maximum transfer size, in bytes, for an I/O sent to the given namespace.
    2948             :  *
    2949             :  * This function is thread safe and can be called at any point while the controller
    2950             :  * is attached to the SPDK NVMe driver.
    2951             :  *
    2952             :  * \param ns Namespace to query.
    2953             :  *
    2954             :  * \return the maximum transfer size in bytes.
    2955             :  */
    2956             : uint32_t spdk_nvme_ns_get_max_io_xfer_size(struct spdk_nvme_ns *ns);
    2957             : 
    2958             : /**
    2959             :  * Get the sector size, in bytes, of the given namespace.
    2960             :  *
    2961             :  * This function returns the size of the data sector only.  It does not
    2962             :  * include metadata size.
    2963             :  *
    2964             :  * This function is thread safe and can be called at any point while the controller
    2965             :  * is attached to the SPDK NVMe driver.
    2966             :  *
    2967             :  * \param ns Namespace to query.
    2968             :  *
    2969             :  * /return the sector size in bytes.
    2970             :  */
    2971             : uint32_t spdk_nvme_ns_get_sector_size(struct spdk_nvme_ns *ns);
    2972             : 
    2973             : /**
    2974             :  * Get the extended sector size, in bytes, of the given namespace.
    2975             :  *
    2976             :  * This function returns the size of the data sector plus metadata.
    2977             :  *
    2978             :  * This function is thread safe and can be called at any point while the controller
    2979             :  * is attached to the SPDK NVMe driver.
    2980             :  *
    2981             :  * \param ns Namespace to query.
    2982             :  *
    2983             :  * /return the extended sector size in bytes.
    2984             :  */
    2985             : uint32_t spdk_nvme_ns_get_extended_sector_size(struct spdk_nvme_ns *ns);
    2986             : 
    2987             : /**
    2988             :  * Get the number of sectors for the given namespace.
    2989             :  *
    2990             :  * This function is thread safe and can be called at any point while the controller
    2991             :  * is attached to the SPDK NVMe driver.
    2992             :  *
    2993             :  * \param ns Namespace to query.
    2994             :  *
    2995             :  * \return the number of sectors.
    2996             :  */
    2997             : uint64_t spdk_nvme_ns_get_num_sectors(struct spdk_nvme_ns *ns);
    2998             : 
    2999             : /**
    3000             :  * Get the size, in bytes, of the given namespace.
    3001             :  *
    3002             :  * This function is thread safe and can be called at any point while the controller
    3003             :  * is attached to the SPDK NVMe driver.
    3004             :  *
    3005             :  * \param ns Namespace to query.
    3006             :  *
    3007             :  * \return the size of the given namespace in bytes.
    3008             :  */
    3009             : uint64_t spdk_nvme_ns_get_size(struct spdk_nvme_ns *ns);
    3010             : 
    3011             : /**
    3012             :  * Get the end-to-end data protection information type of the given namespace.
    3013             :  *
    3014             :  * This function is thread safe and can be called at any point while the controller
    3015             :  * is attached to the SPDK NVMe driver.
    3016             :  *
    3017             :  * \param ns Namespace to query.
    3018             :  *
    3019             :  * \return the end-to-end data protection information type.
    3020             :  */
    3021             : enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type(struct spdk_nvme_ns *ns);
    3022             : 
    3023             : /**
    3024             :  * Get the end-to-end data protection information format of the given namespace.
    3025             :  *
    3026             :  * This function is thread safe and can be called at any point while the controller
    3027             :  * is attached to the SPDK NVMe driver.
    3028             :  *
    3029             :  * \param ns Namespace to query.
    3030             :  *
    3031             :  * \return the end-to-end data protection information format.
    3032             :  */
    3033             : enum spdk_nvme_pi_format spdk_nvme_ns_get_pi_format(struct spdk_nvme_ns *ns);
    3034             : 
    3035             : /**
    3036             :  * Get the metadata size, in bytes, of the given namespace.
    3037             :  *
    3038             :  * This function is thread safe and can be called at any point while the controller
    3039             :  * is attached to the SPDK NVMe driver.
    3040             :  *
    3041             :  * \param ns Namespace to query.
    3042             :  *
    3043             :  * \return the metadata size of the given namespace in bytes.
    3044             :  */
    3045             : uint32_t spdk_nvme_ns_get_md_size(struct spdk_nvme_ns *ns);
    3046             : 
    3047             : /**
    3048             :  * Get the format index of the given namespace.
    3049             :  *
    3050             :  * This function is thread safe and can be called at any point while the controller
    3051             :  * is attached to the SPDK NVMe driver.
    3052             :  *
    3053             :  * \param nsdata pointer to the NVMe namespace data.
    3054             :  *
    3055             :  * \return the format index of the given namespace.
    3056             :  */
    3057             : uint32_t spdk_nvme_ns_get_format_index(const struct spdk_nvme_ns_data *nsdata);
    3058             : 
    3059             : /**
    3060             :  * Check whether if the namespace can support extended LBA when end-to-end data
    3061             :  * protection enabled.
    3062             :  *
    3063             :  * This function is thread safe and can be called at any point while the controller
    3064             :  * is attached to the SPDK NVMe driver.
    3065             :  *
    3066             :  * \param ns Namespace to query.
    3067             :  *
    3068             :  * \return true if the namespace can support extended LBA when end-to-end data
    3069             :  * protection enabled, or false otherwise.
    3070             :  */
    3071             : bool spdk_nvme_ns_supports_extended_lba(struct spdk_nvme_ns *ns);
    3072             : 
    3073             : /**
    3074             :  * Check whether if the namespace supports compare operation
    3075             :  *
    3076             :  * This function is thread safe and can be called at any point while the controller
    3077             :  * is attached to the SPDK NVMe driver.
    3078             :  *
    3079             :  * \param ns Namespace to query.
    3080             :  *
    3081             :  * \return true if the namespace supports compare operation, or false otherwise.
    3082             :  */
    3083             : bool spdk_nvme_ns_supports_compare(struct spdk_nvme_ns *ns);
    3084             : 
    3085             : /**
    3086             :  * Determine the value returned when reading deallocated blocks.
    3087             :  *
    3088             :  * If deallocated blocks return 0, the deallocate command can be used as a more
    3089             :  * efficient alternative to the write_zeroes command, especially for large requests.
    3090             :  *
    3091             :  * \param ns Namespace.
    3092             :  *
    3093             :  * \return the logical block read value.
    3094             :  */
    3095             : enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value(
    3096             :         struct spdk_nvme_ns *ns);
    3097             : 
    3098             : /**
    3099             :  * Get the optimal I/O boundary, in blocks, for the given namespace.
    3100             :  *
    3101             :  * Read and write commands should not cross the optimal I/O boundary for best
    3102             :  * performance.
    3103             :  *
    3104             :  * \param ns Namespace to query.
    3105             :  *
    3106             :  * \return Optimal granularity of I/O commands, in blocks, or 0 if no optimal
    3107             :  * granularity is reported.
    3108             :  */
    3109             : uint32_t spdk_nvme_ns_get_optimal_io_boundary(struct spdk_nvme_ns *ns);
    3110             : 
    3111             : /**
    3112             :  * Get the NGUID for the given namespace.
    3113             :  *
    3114             :  * \param ns Namespace to query.
    3115             :  *
    3116             :  * \return a pointer to namespace NGUID, or NULL if ns does not have a NGUID.
    3117             :  */
    3118             : const uint8_t *spdk_nvme_ns_get_nguid(const struct spdk_nvme_ns *ns);
    3119             : 
    3120             : /**
    3121             :  * Get the UUID for the given namespace.
    3122             :  *
    3123             :  * \param ns Namespace to query.
    3124             :  *
    3125             :  * \return a pointer to namespace UUID, or NULL if ns does not have a UUID.
    3126             :  */
    3127             : const struct spdk_uuid *spdk_nvme_ns_get_uuid(const struct spdk_nvme_ns *ns);
    3128             : 
    3129             : /**
    3130             :  * Get the Command Set Identifier for the given namespace.
    3131             :  *
    3132             :  * \param ns Namespace to query.
    3133             :  *
    3134             :  * \return the namespace Command Set Identifier.
    3135             :  */
    3136             : enum spdk_nvme_csi spdk_nvme_ns_get_csi(const struct spdk_nvme_ns *ns);
    3137             : 
    3138             : /**
    3139             :  * \brief Namespace command support flags.
    3140             :  */
    3141             : enum spdk_nvme_ns_flags {
    3142             :         SPDK_NVME_NS_DEALLOCATE_SUPPORTED       = 1 << 0, /**< The deallocate command is supported */
    3143             :         SPDK_NVME_NS_FLUSH_SUPPORTED            = 1 << 1, /**< The flush command is supported */
    3144             :         SPDK_NVME_NS_RESERVATION_SUPPORTED      = 1 << 2, /**< The reservation command is supported */
    3145             :         SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED     = 1 << 3, /**< The write zeroes command is supported */
    3146             :         SPDK_NVME_NS_DPS_PI_SUPPORTED           = 1 << 4, /**< The end-to-end data protection is supported */
    3147             :         SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED     = 1 << 5, /**< The extended lba format is supported,
    3148             :                                                               metadata is transferred as a contiguous
    3149             :                                                               part of the logical block that it is associated with */
    3150             :         SPDK_NVME_NS_WRITE_UNCORRECTABLE_SUPPORTED      = 1 << 6, /**< The write uncorrectable command is supported */
    3151             :         SPDK_NVME_NS_COMPARE_SUPPORTED          = 1 << 7, /**< The compare command is supported */
    3152             : };
    3153             : 
    3154             : /**
    3155             :  * Get the flags for the given namespace.
    3156             :  *
    3157             :  * See spdk_nvme_ns_flags for the possible flags returned.
    3158             :  *
    3159             :  * This function is thread safe and can be called at any point while the controller
    3160             :  * is attached to the SPDK NVMe driver.
    3161             :  *
    3162             :  * \param ns Namespace to query.
    3163             :  *
    3164             :  * \return the flags for the given namespace.
    3165             :  */
    3166             : uint32_t spdk_nvme_ns_get_flags(struct spdk_nvme_ns *ns);
    3167             : 
    3168             : /**
    3169             :  * Get the ANA group ID for the given namespace.
    3170             :  *
    3171             :  * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
    3172             :  * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
    3173             :  *
    3174             :  * This function is thread safe and can be called at any point while the controller
    3175             :  * is attached to the SPDK NVMe driver.
    3176             :  *
    3177             :  * \param ns Namespace to query.
    3178             :  *
    3179             :  * \return the ANA group ID for the given namespace.
    3180             :  */
    3181             : uint32_t spdk_nvme_ns_get_ana_group_id(const struct spdk_nvme_ns *ns);
    3182             : 
    3183             : /**
    3184             :  * Get the ANA state for the given namespace.
    3185             :  *
    3186             :  * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
    3187             :  * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
    3188             :  *
    3189             :  * This function is thread safe and can be called at any point while the controller
    3190             :  * is attached to the SPDK NVMe driver.
    3191             :  *
    3192             :  * \param ns Namespace to query.
    3193             :  *
    3194             :  * \return the ANA state for the given namespace.
    3195             :  */
    3196             : enum spdk_nvme_ana_state spdk_nvme_ns_get_ana_state(const struct spdk_nvme_ns *ns);
    3197             : 
    3198             : /**
    3199             :  * Submit a write I/O to the specified NVMe namespace.
    3200             :  *
    3201             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3202             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3203             :  * given time.
    3204             :  *
    3205             :  * \param ns NVMe namespace to submit the write I/O.
    3206             :  * \param qpair I/O queue pair to submit the request.
    3207             :  * \param payload Virtual address pointer to the data payload.
    3208             :  * \param lba Starting LBA to write the data.
    3209             :  * \param lba_count Length (in sectors) for the write operation.
    3210             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3211             :  * \param cb_arg Argument to pass to the callback function.
    3212             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3213             :  * spdk/nvme_spec.h, for this I/O.
    3214             :  *
    3215             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3216             :  * -EINVAL: The request is malformed.
    3217             :  * -ENOMEM: The request cannot be allocated.
    3218             :  * -ENXIO: The qpair is failed at the transport level.
    3219             :  */
    3220             : int spdk_nvme_ns_cmd_write(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3221             :                            uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3222             :                            void *cb_arg, uint32_t io_flags);
    3223             : 
    3224             : /**
    3225             :  * Submit a write I/O to the specified NVMe namespace.
    3226             :  *
    3227             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3228             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3229             :  * given time.
    3230             :  *
    3231             :  * \param ns NVMe namespace to submit the write I/O.
    3232             :  * \param qpair I/O queue pair to submit the request.
    3233             :  * \param lba Starting LBA to write the data.
    3234             :  * \param lba_count Length (in sectors) for the write operation.
    3235             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3236             :  * \param cb_arg Argument to pass to the callback function.
    3237             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3238             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3239             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3240             :  * segment.
    3241             :  *
    3242             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3243             :  * -EINVAL: The request is malformed.
    3244             :  * -ENOMEM: The request cannot be allocated.
    3245             :  * -ENXIO: The qpair is failed at the transport level.
    3246             :  */
    3247             : int spdk_nvme_ns_cmd_writev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3248             :                             uint64_t lba, uint32_t lba_count,
    3249             :                             spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3250             :                             spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3251             :                             spdk_nvme_req_next_sge_cb next_sge_fn);
    3252             : 
    3253             : /**
    3254             :  * Submit a write I/O to the specified NVMe namespace.
    3255             :  *
    3256             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3257             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3258             :  * given time.
    3259             :  *
    3260             :  * \param ns NVMe namespace to submit the write I/O
    3261             :  * \param qpair I/O queue pair to submit the request
    3262             :  * \param lba starting LBA to write the data
    3263             :  * \param lba_count length (in sectors) for the write operation
    3264             :  * \param cb_fn callback function to invoke when the I/O is completed
    3265             :  * \param cb_arg argument to pass to the callback function
    3266             :  * \param io_flags set flags, defined in nvme_spec.h, for this I/O
    3267             :  * \param reset_sgl_fn callback function to reset scattered payload
    3268             :  * \param next_sge_fn callback function to iterate each scattered
    3269             :  * payload memory segment
    3270             :  * \param metadata virtual address pointer to the metadata payload, the length
    3271             :  * of metadata is specified by spdk_nvme_ns_get_md_size()
    3272             :  * \param apptag_mask application tag mask.
    3273             :  * \param apptag application tag to use end-to-end protection information.
    3274             :  *
    3275             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3276             :  * -EINVAL: The request is malformed.
    3277             :  * -ENOMEM: The request cannot be allocated.
    3278             :  * -ENXIO: The qpair is failed at the transport level.
    3279             :  */
    3280             : int spdk_nvme_ns_cmd_writev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3281             :                                     uint64_t lba, uint32_t lba_count,
    3282             :                                     spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3283             :                                     spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3284             :                                     spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    3285             :                                     uint16_t apptag_mask, uint16_t apptag);
    3286             : 
    3287             : /**
    3288             :  * Submit a write I/O to the specified NVMe namespace.
    3289             :  *
    3290             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3291             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3292             :  * given time.
    3293             :  *
    3294             :  * \param ns NVMe namespace to submit the write I/O
    3295             :  * \param qpair I/O queue pair to submit the request
    3296             :  * \param lba starting LBA to write the data
    3297             :  * \param lba_count length (in sectors) for the write operation
    3298             :  * \param cb_fn callback function to invoke when the I/O is completed
    3299             :  * \param cb_arg argument to pass to the callback function
    3300             :  * \param reset_sgl_fn callback function to reset scattered payload
    3301             :  * \param next_sge_fn callback function to iterate each scattered
    3302             :  * payload memory segment
    3303             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3304             :  * guarantee that this structure is accessible until IO completes
    3305             :  *
    3306             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3307             :  * -EINVAL: The request is malformed.
    3308             :  * -ENOMEM: The request cannot be allocated.
    3309             :  * -ENXIO: The qpair is failed at the transport level.
    3310             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3311             :  *          with error status including dnr=1 in this case.
    3312             :  */
    3313             : int spdk_nvme_ns_cmd_writev_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3314             :                                 uint64_t lba, uint32_t lba_count,
    3315             :                                 spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3316             :                                 spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3317             :                                 spdk_nvme_req_next_sge_cb next_sge_fn,
    3318             :                                 struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3319             : 
    3320             : /**
    3321             :  * Submit a write I/O to the specified NVMe namespace.
    3322             :  *
    3323             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3324             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3325             :  * given time.
    3326             :  *
    3327             :  * \param ns NVMe namespace to submit the write I/O
    3328             :  * \param qpair I/O queue pair to submit the request
    3329             :  * \param payload Virtual address pointer to the data payload.
    3330             :  * \param lba starting LBA to write the data
    3331             :  * \param lba_count length (in sectors) for the write operation
    3332             :  * \param cb_fn callback function to invoke when the I/O is completed
    3333             :  * \param cb_arg argument to pass to the callback function
    3334             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3335             :  * guarantee that this structure is accessible until IO completes
    3336             :  *
    3337             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3338             :  * -EINVAL: The request is malformed.
    3339             :  * -ENOMEM: The request cannot be allocated.
    3340             :  * -ENXIO: The qpair is failed at the transport level.
    3341             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3342             :  *          with error status including dnr=1 in this case.
    3343             :  */
    3344             : int spdk_nvme_ns_cmd_write_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3345             :                                void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3346             :                                struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3347             : 
    3348             : /**
    3349             :  * Submit a write I/O to the specified NVMe namespace.
    3350             :  *
    3351             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3352             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3353             :  * given time.
    3354             :  *
    3355             :  * \param ns NVMe namespace to submit the write I/O.
    3356             :  * \param qpair I/O queue pair to submit the request.
    3357             :  * \param payload Virtual address pointer to the data payload.
    3358             :  * \param metadata Virtual address pointer to the metadata payload, the length
    3359             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    3360             :  * \param lba Starting LBA to write the data.
    3361             :  * \param lba_count Length (in sectors) for the write operation.
    3362             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3363             :  * \param cb_arg Argument to pass to the callback function.
    3364             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3365             :  * spdk/nvme_spec.h, for this I/O.
    3366             :  * \param apptag_mask Application tag mask.
    3367             :  * \param apptag Application tag to use end-to-end protection information.
    3368             :  *
    3369             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3370             :  * -EINVAL: The request is malformed.
    3371             :  * -ENOMEM: The request cannot be allocated.
    3372             :  * -ENXIO: The qpair is failed at the transport level.
    3373             :  */
    3374             : int spdk_nvme_ns_cmd_write_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3375             :                                    void *payload, void *metadata,
    3376             :                                    uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3377             :                                    void *cb_arg, uint32_t io_flags,
    3378             :                                    uint16_t apptag_mask, uint16_t apptag);
    3379             : 
    3380             : /**
    3381             :  * Submit a write zeroes I/O to the specified NVMe namespace.
    3382             :  *
    3383             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3384             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3385             :  * given time.
    3386             :  *
    3387             :  * \param ns NVMe namespace to submit the write zeroes I/O.
    3388             :  * \param qpair I/O queue pair to submit the request.
    3389             :  * \param lba Starting LBA for this command.
    3390             :  * \param lba_count Length (in sectors) for the write zero operation.
    3391             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3392             :  * \param cb_arg Argument to pass to the callback function.
    3393             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3394             :  * spdk/nvme_spec.h, for this I/O.
    3395             :  *
    3396             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3397             :  * -EINVAL: The request is malformed.
    3398             :  * -ENOMEM: The request cannot be allocated.
    3399             :  * -ENXIO: The qpair is failed at the transport level.
    3400             :  */
    3401             : int spdk_nvme_ns_cmd_write_zeroes(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3402             :                                   uint64_t lba, uint32_t lba_count,
    3403             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3404             :                                   uint32_t io_flags);
    3405             : 
    3406             : /**
    3407             :  * Submit a verify I/O to the specified NVMe namespace.
    3408             :  *
    3409             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3410             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3411             :  * given time.
    3412             :  *
    3413             :  * \param ns NVMe namespace to submit the verify I/O.
    3414             :  * \param qpair I/O queue pair to submit the request.
    3415             :  * \param lba Starting LBA to verify the data.
    3416             :  * \param lba_count Length (in sectors) for the verify operation.
    3417             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3418             :  * \param cb_arg Argument to pass to the callback function.
    3419             :  * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
    3420             :  * spdk/nvme_spec.h, for this I/O.
    3421             :  *
    3422             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3423             :  * -EINVAL: The request is malformed.
    3424             :  * -ENOMEM: The request cannot be allocated.
    3425             :  * -ENXIO: The qpair is failed at the transport level.
    3426             :  */
    3427             : int spdk_nvme_ns_cmd_verify(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3428             :                             uint64_t lba, uint32_t lba_count,
    3429             :                             spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3430             :                             uint32_t io_flags);
    3431             : 
    3432             : /**
    3433             :  * Submit a write uncorrectable I/O to the specified NVMe namespace.
    3434             :  *
    3435             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3436             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3437             :  * given time.
    3438             :  *
    3439             :  * \param ns NVMe namespace to submit the write uncorrectable I/O.
    3440             :  * \param qpair I/O queue pair to submit the request.
    3441             :  * \param lba Starting LBA for this command.
    3442             :  * \param lba_count Length (in sectors) for the write uncorrectable operation.
    3443             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3444             :  * \param cb_arg Argument to pass to the callback function.
    3445             :  *
    3446             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3447             :  * -EINVAL: The request is malformed.
    3448             :  * -ENOMEM: The request cannot be allocated.
    3449             :  * -ENXIO: The qpair is failed at the transport level.
    3450             :  */
    3451             : int spdk_nvme_ns_cmd_write_uncorrectable(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3452             :                 uint64_t lba, uint32_t lba_count,
    3453             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3454             : 
    3455             : /**
    3456             :  * \brief Submits a read I/O to the specified NVMe namespace.
    3457             :  *
    3458             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3459             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3460             :  * given time.
    3461             :  *
    3462             :  * \param ns NVMe namespace to submit the read I/O.
    3463             :  * \param qpair I/O queue pair to submit the request.
    3464             :  * \param payload Virtual address pointer to the data payload.
    3465             :  * \param lba Starting LBA to read the data.
    3466             :  * \param lba_count Length (in sectors) for the read operation.
    3467             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3468             :  * \param cb_arg Argument to pass to the callback function.
    3469             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3470             :  *
    3471             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3472             :  * -EINVAL: The request is malformed.
    3473             :  * -ENOMEM: The request cannot be allocated.
    3474             :  * -ENXIO: The qpair is failed at the transport level.
    3475             :  */
    3476             : int spdk_nvme_ns_cmd_read(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3477             :                           uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3478             :                           void *cb_arg, uint32_t io_flags);
    3479             : 
    3480             : /**
    3481             :  * Submit a read I/O to the specified NVMe namespace.
    3482             :  *
    3483             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3484             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3485             :  * given time.
    3486             :  *
    3487             :  * \param ns NVMe namespace to submit the read I/O.
    3488             :  * \param qpair I/O queue pair to submit the request.
    3489             :  * \param lba Starting LBA to read the data.
    3490             :  * \param lba_count Length (in sectors) for the read operation.
    3491             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3492             :  * \param cb_arg Argument to pass to the callback function.
    3493             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3494             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3495             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3496             :  * segment.
    3497             :  *
    3498             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3499             :  * -EINVAL: The request is malformed.
    3500             :  * -ENOMEM: The request cannot be allocated.
    3501             :  * -ENXIO: The qpair is failed at the transport level.
    3502             :  */
    3503             : int spdk_nvme_ns_cmd_readv(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3504             :                            uint64_t lba, uint32_t lba_count,
    3505             :                            spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3506             :                            spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3507             :                            spdk_nvme_req_next_sge_cb next_sge_fn);
    3508             : 
    3509             : /**
    3510             :  * Submit a read I/O to the specified NVMe namespace.
    3511             :  *
    3512             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3513             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3514             :  *
    3515             :  * \param ns NVMe namespace to submit the read I/O
    3516             :  * \param qpair I/O queue pair to submit the request
    3517             :  * \param lba starting LBA to read the data
    3518             :  * \param lba_count length (in sectors) for the read operation
    3519             :  * \param cb_fn callback function to invoke when the I/O is completed
    3520             :  * \param cb_arg argument to pass to the callback function
    3521             :  * \param io_flags set flags, defined in nvme_spec.h, for this I/O
    3522             :  * \param reset_sgl_fn callback function to reset scattered payload
    3523             :  * \param next_sge_fn callback function to iterate each scattered
    3524             :  * payload memory segment
    3525             :  * \param metadata virtual address pointer to the metadata payload, the length
    3526             :  *                 of metadata is specified by spdk_nvme_ns_get_md_size()
    3527             :  * \param apptag_mask application tag mask.
    3528             :  * \param apptag application tag to use end-to-end protection information.
    3529             :  *
    3530             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3531             :  * -EINVAL: The request is malformed.
    3532             :  * -ENOMEM: The request cannot be allocated.
    3533             :  * -ENXIO: The qpair is failed at the transport level.
    3534             :  */
    3535             : int spdk_nvme_ns_cmd_readv_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3536             :                                    uint64_t lba, uint32_t lba_count,
    3537             :                                    spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3538             :                                    spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3539             :                                    spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    3540             :                                    uint16_t apptag_mask, uint16_t apptag);
    3541             : 
    3542             : /**
    3543             :  * Submit a read I/O to the specified NVMe namespace.
    3544             :  *
    3545             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3546             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3547             :  *
    3548             :  * \param ns NVMe namespace to submit the read I/O
    3549             :  * \param qpair I/O queue pair to submit the request
    3550             :  * \param lba starting LBA to read the data
    3551             :  * \param lba_count length (in sectors) for the read operation
    3552             :  * \param cb_fn callback function to invoke when the I/O is completed
    3553             :  * \param cb_arg argument to pass to the callback function
    3554             :  * \param reset_sgl_fn callback function to reset scattered payload
    3555             :  * \param next_sge_fn callback function to iterate each scattered
    3556             :  * payload memory segment
    3557             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3558             :  * guarantee that this structure is accessible until IO completes
    3559             :  *
    3560             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3561             :  * -EINVAL: The request is malformed.
    3562             :  * -ENOMEM: The request cannot be allocated.
    3563             :  * -ENXIO: The qpair is failed at the transport level.
    3564             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3565             :  *          with error status including dnr=1 in this case.
    3566             :  */
    3567             : int spdk_nvme_ns_cmd_readv_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3568             :                                uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3569             :                                void *cb_arg, spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3570             :                                spdk_nvme_req_next_sge_cb next_sge_fn,
    3571             :                                struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3572             : 
    3573             : /**
    3574             :  * Submit a read I/O to the specified NVMe namespace.
    3575             :  *
    3576             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3577             :  * The user must ensure that only one thread submits I/O on a given qpair at any given time.
    3578             :  *
    3579             :  * \param ns NVMe namespace to submit the read I/O
    3580             :  * \param qpair I/O queue pair to submit the request
    3581             :  * \param payload virtual address pointer to the data payload
    3582             :  * \param lba starting LBA to read the data
    3583             :  * \param lba_count length (in sectors) for the read operation
    3584             :  * \param cb_fn callback function to invoke when the I/O is completed
    3585             :  * \param cb_arg argument to pass to the callback function
    3586             :  * \param opts Optional structure with extended IO request options. If provided, the caller must
    3587             :  * guarantee that this structure is accessible until IO completes
    3588             :  *
    3589             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3590             :  * -EINVAL: The request is malformed.
    3591             :  * -ENOMEM: The request cannot be allocated.
    3592             :  * -ENXIO: The qpair is failed at the transport level.
    3593             :  * -EFAULT: Invalid address was specified as part of payload.  cb_fn is also called
    3594             :  *          with error status including dnr=1 in this case.
    3595             :  */
    3596             : int spdk_nvme_ns_cmd_read_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3597             :                               uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
    3598             :                               struct spdk_nvme_ns_cmd_ext_io_opts *opts);
    3599             : 
    3600             : /**
    3601             :  * Submits a read I/O to the specified NVMe namespace.
    3602             :  *
    3603             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3604             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3605             :  * given time.
    3606             :  *
    3607             :  * \param ns NVMe namespace to submit the read I/O
    3608             :  * \param qpair I/O queue pair to submit the request
    3609             :  * \param payload virtual address pointer to the data payload
    3610             :  * \param metadata virtual address pointer to the metadata payload, the length
    3611             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    3612             :  * \param lba starting LBA to read the data.
    3613             :  * \param lba_count Length (in sectors) for the read operation.
    3614             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3615             :  * \param cb_arg Argument to pass to the callback function.
    3616             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3617             :  * \param apptag_mask Application tag mask.
    3618             :  * \param apptag Application tag to use end-to-end protection information.
    3619             :  *
    3620             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3621             :  * -EINVAL: The request is malformed.
    3622             :  * -ENOMEM: The request cannot be allocated.
    3623             :  * -ENXIO: The qpair is failed at the transport level.
    3624             :  */
    3625             : int spdk_nvme_ns_cmd_read_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3626             :                                   void *payload, void *metadata,
    3627             :                                   uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3628             :                                   void *cb_arg, uint32_t io_flags,
    3629             :                                   uint16_t apptag_mask, uint16_t apptag);
    3630             : 
    3631             : /**
    3632             :  * Submit a data set management request to the specified NVMe namespace.
    3633             :  *
    3634             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3635             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3636             :  * given time.
    3637             :  *
    3638             :  * This is a convenience wrapper that will automatically allocate and construct
    3639             :  * the correct data buffers. Therefore, ranges does not need to be allocated from
    3640             :  * pinned memory and can be placed on the stack. If a higher performance, zero-copy
    3641             :  * version of DSM is required, simply build and submit a raw command using
    3642             :  * spdk_nvme_ctrlr_cmd_io_raw().
    3643             :  *
    3644             :  * \param ns NVMe namespace to submit the DSM request
    3645             :  * \param type A bit field constructed from \ref spdk_nvme_dsm_attribute.
    3646             :  * \param qpair I/O queue pair to submit the request
    3647             :  * \param ranges An array of \ref spdk_nvme_dsm_range elements describing the LBAs
    3648             :  * to operate on.
    3649             :  * \param num_ranges The number of elements in the ranges array.
    3650             :  * \param cb_fn Callback function to invoke when the I/O is completed
    3651             :  * \param cb_arg Argument to pass to the callback function
    3652             :  *
    3653             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3654             :  * -ENOMEM: The request cannot be allocated.
    3655             :  * -ENXIO: The qpair is failed at the transport level.
    3656             :  */
    3657             : int spdk_nvme_ns_cmd_dataset_management(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3658             :                                         uint32_t type,
    3659             :                                         const struct spdk_nvme_dsm_range *ranges,
    3660             :                                         uint16_t num_ranges,
    3661             :                                         spdk_nvme_cmd_cb cb_fn,
    3662             :                                         void *cb_arg);
    3663             : 
    3664             : /**
    3665             :  * Submit a simple copy command request to the specified NVMe namespace.
    3666             :  *
    3667             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3668             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3669             :  * given time.
    3670             :  *
    3671             :  * This is a convenience wrapper that will automatically allocate and construct
    3672             :  * the correct data buffers. Therefore, ranges does not need to be allocated from
    3673             :  * pinned memory and can be placed on the stack. If a higher performance, zero-copy
    3674             :  * version of SCC is required, simply build and submit a raw command using
    3675             :  * spdk_nvme_ctrlr_cmd_io_raw().
    3676             :  *
    3677             :  * \param ns NVMe namespace to submit the SCC request
    3678             :  * \param qpair I/O queue pair to submit the request
    3679             :  * \param ranges An array of \ref spdk_nvme_scc_source_range elements describing the LBAs
    3680             :  * to operate on.
    3681             :  * \param num_ranges The number of elements in the ranges array.
    3682             :  * \param dest_lba Destination LBA to copy the data.
    3683             :  * \param cb_fn Callback function to invoke when the I/O is completed
    3684             :  * \param cb_arg Argument to pass to the callback function
    3685             :  *
    3686             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3687             :  * -ENOMEM: The request cannot be allocated.
    3688             :  * -EINVAL: Invalid ranges.
    3689             :  * -ENXIO: The qpair is failed at the transport level.
    3690             :  */
    3691             : int spdk_nvme_ns_cmd_copy(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3692             :                           const struct spdk_nvme_scc_source_range *ranges,
    3693             :                           uint16_t num_ranges,
    3694             :                           uint64_t dest_lba,
    3695             :                           spdk_nvme_cmd_cb cb_fn,
    3696             :                           void *cb_arg);
    3697             : 
    3698             : /**
    3699             :  * Submit a flush request 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 flush request.
    3706             :  * \param qpair I/O queue pair to submit the request.
    3707             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3708             :  * \param cb_arg Argument to pass to the callback function.
    3709             :  *
    3710             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3711             :  * -ENOMEM: The request cannot be allocated.
    3712             :  * -ENXIO: The qpair is failed at the transport level.
    3713             :  */
    3714             : int spdk_nvme_ns_cmd_flush(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3715             :                            spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3716             : 
    3717             : /**
    3718             :  * Submit a reservation register to the specified NVMe namespace.
    3719             :  *
    3720             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3721             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3722             :  * given time.
    3723             :  *
    3724             :  * \param ns NVMe namespace to submit the reservation register request.
    3725             :  * \param qpair I/O queue pair to submit the request.
    3726             :  * \param payload Virtual address pointer to the reservation register data.
    3727             :  * \param ignore_key '1' the current reservation key check is disabled.
    3728             :  * \param action Specifies the registration action.
    3729             :  * \param cptpl Change the Persist Through Power Loss state.
    3730             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3731             :  * \param cb_arg Argument to pass to the callback function.
    3732             :  *
    3733             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3734             :  * -ENOMEM: The request cannot be allocated.
    3735             :  * -ENXIO: The qpair is failed at the transport level.
    3736             :  */
    3737             : int spdk_nvme_ns_cmd_reservation_register(struct spdk_nvme_ns *ns,
    3738             :                 struct spdk_nvme_qpair *qpair,
    3739             :                 struct spdk_nvme_reservation_register_data *payload,
    3740             :                 bool ignore_key,
    3741             :                 enum spdk_nvme_reservation_register_action action,
    3742             :                 enum spdk_nvme_reservation_register_cptpl cptpl,
    3743             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3744             : 
    3745             : /**
    3746             :  * Submits a reservation release to the specified NVMe namespace.
    3747             :  *
    3748             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3749             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3750             :  * given time.
    3751             :  *
    3752             :  * \param ns NVMe namespace to submit the reservation release request.
    3753             :  * \param qpair I/O queue pair to submit the request.
    3754             :  * \param payload Virtual address pointer to current reservation key.
    3755             :  * \param ignore_key '1' the current reservation key check is disabled.
    3756             :  * \param action Specifies the reservation release action.
    3757             :  * \param type Reservation type for the namespace.
    3758             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3759             :  * \param cb_arg Argument to pass to the callback function.
    3760             :  *
    3761             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3762             :  * -ENOMEM: The request cannot be allocated.
    3763             :  * -ENXIO: The qpair is failed at the transport level.
    3764             :  */
    3765             : int spdk_nvme_ns_cmd_reservation_release(struct spdk_nvme_ns *ns,
    3766             :                 struct spdk_nvme_qpair *qpair,
    3767             :                 struct spdk_nvme_reservation_key_data *payload,
    3768             :                 bool ignore_key,
    3769             :                 enum spdk_nvme_reservation_release_action action,
    3770             :                 enum spdk_nvme_reservation_type type,
    3771             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3772             : 
    3773             : /**
    3774             :  * Submits a reservation acquire to the specified NVMe namespace.
    3775             :  *
    3776             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3777             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3778             :  * given time.
    3779             :  *
    3780             :  * \param ns NVMe namespace to submit the reservation acquire request.
    3781             :  * \param qpair I/O queue pair to submit the request.
    3782             :  * \param payload Virtual address pointer to reservation acquire data.
    3783             :  * \param ignore_key '1' the current reservation key check is disabled.
    3784             :  * \param action Specifies the reservation acquire action.
    3785             :  * \param type Reservation type for the namespace.
    3786             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3787             :  * \param cb_arg Argument to pass to the callback function.
    3788             :  *
    3789             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3790             :  * -ENOMEM: The request cannot be allocated.
    3791             :  * -ENXIO: The qpair is failed at the transport level.
    3792             :  */
    3793             : int spdk_nvme_ns_cmd_reservation_acquire(struct spdk_nvme_ns *ns,
    3794             :                 struct spdk_nvme_qpair *qpair,
    3795             :                 struct spdk_nvme_reservation_acquire_data *payload,
    3796             :                 bool ignore_key,
    3797             :                 enum spdk_nvme_reservation_acquire_action action,
    3798             :                 enum spdk_nvme_reservation_type type,
    3799             :                 spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3800             : 
    3801             : /**
    3802             :  * Submit a reservation report to the specified NVMe namespace.
    3803             :  *
    3804             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3805             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3806             :  * given time.
    3807             :  *
    3808             :  * \param ns NVMe namespace to submit the reservation report request.
    3809             :  * \param qpair I/O queue pair to submit the request.
    3810             :  * \param payload Virtual address pointer for reservation status data.
    3811             :  * \param len Length bytes for reservation status data structure.
    3812             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3813             :  * \param cb_arg Argument to pass to the callback function.
    3814             :  *
    3815             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3816             :  * -ENOMEM: The request cannot be allocated.
    3817             :  * -ENXIO: The qpair is failed at the transport level.
    3818             :  */
    3819             : int spdk_nvme_ns_cmd_reservation_report(struct spdk_nvme_ns *ns,
    3820             :                                         struct spdk_nvme_qpair *qpair,
    3821             :                                         void *payload, uint32_t len,
    3822             :                                         spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3823             : 
    3824             : /**
    3825             :  * Submit an I/O management receive command to the specified NVMe namespace.
    3826             :  *
    3827             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3828             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3829             :  * given time.
    3830             :  *
    3831             :  * \param ns NVMe namespace to submit the I/O mgmt receive request.
    3832             :  * \param qpair I/O queue pair to submit the request.
    3833             :  * \param payload Virtual address pointer for I/O mgmt receive data.
    3834             :  * \param len Length bytes for I/O mgmt receive data structure.
    3835             :  * \param mo Management operation to perform.
    3836             :  * \param mos Management operation specific field for the mo.
    3837             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3838             :  * \param cb_arg Argument to pass to the callback function.
    3839             :  *
    3840             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3841             :  * -ENOMEM: The request cannot be allocated.
    3842             :  * -ENXIO: The qpair is failed at the transport level.
    3843             :  */
    3844             : int spdk_nvme_ns_cmd_io_mgmt_recv(struct spdk_nvme_ns *ns,
    3845             :                                   struct spdk_nvme_qpair *qpair, void *payload,
    3846             :                                   uint32_t len, uint8_t mo, uint16_t mos,
    3847             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3848             : 
    3849             : /**
    3850             :  * Submit an I/O management send command to the specified NVMe namespace.
    3851             :  *
    3852             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3853             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3854             :  * given time.
    3855             :  *
    3856             :  * \param ns NVMe namespace to submit the I/O mgmt send request.
    3857             :  * \param qpair I/O queue pair to submit the request.
    3858             :  * \param payload Virtual address pointer for I/O mgmt send data.
    3859             :  * \param len Length bytes for I/O mgmt send data structure.
    3860             :  * \param mo Management operation to perform.
    3861             :  * \param mos Management operation specific field for the mo.
    3862             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3863             :  * \param cb_arg Argument to pass to the callback function.
    3864             :  *
    3865             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3866             :  * -ENOMEM: The request cannot be allocated.
    3867             :  * -ENXIO: The qpair is failed at the transport level.
    3868             :  */
    3869             : int spdk_nvme_ns_cmd_io_mgmt_send(struct spdk_nvme_ns *ns,
    3870             :                                   struct spdk_nvme_qpair *qpair, void *payload,
    3871             :                                   uint32_t len, uint8_t mo, uint16_t mos,
    3872             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg);
    3873             : 
    3874             : /**
    3875             :  * Submit a compare I/O to the specified NVMe namespace.
    3876             :  *
    3877             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3878             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3879             :  * given time.
    3880             :  *
    3881             :  * \param ns NVMe namespace to submit the compare I/O.
    3882             :  * \param qpair I/O queue pair to submit the request.
    3883             :  * \param payload Virtual address pointer to the data payload.
    3884             :  * \param lba Starting LBA to compare the data.
    3885             :  * \param lba_count Length (in sectors) for the compare operation.
    3886             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3887             :  * \param cb_arg Argument to pass to the callback function.
    3888             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3889             :  *
    3890             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3891             :  * -EINVAL: The request is malformed.
    3892             :  * -ENOMEM: The request cannot be allocated.
    3893             :  * -ENXIO: The qpair is failed at the transport level.
    3894             :  */
    3895             : int spdk_nvme_ns_cmd_compare(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
    3896             :                              uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3897             :                              void *cb_arg, uint32_t io_flags);
    3898             : 
    3899             : /**
    3900             :  * Submit a compare I/O to the specified NVMe namespace.
    3901             :  *
    3902             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3903             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3904             :  * given time.
    3905             :  *
    3906             :  * \param ns NVMe namespace to submit the compare I/O.
    3907             :  * \param qpair I/O queue pair to submit the request.
    3908             :  * \param lba Starting LBA to compare the data.
    3909             :  * \param lba_count Length (in sectors) for the compare operation.
    3910             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3911             :  * \param cb_arg Argument to pass to the callback function.
    3912             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3913             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3914             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3915             :  * segment.
    3916             :  *
    3917             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3918             :  * -EINVAL: The request is malformed.
    3919             :  * -ENOMEM: The request cannot be allocated.
    3920             :  * -ENXIO: The qpair is failed at the transport level.
    3921             :  */
    3922             : int spdk_nvme_ns_cmd_comparev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3923             :                               uint64_t lba, uint32_t lba_count,
    3924             :                               spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3925             :                               spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3926             :                               spdk_nvme_req_next_sge_cb next_sge_fn);
    3927             : 
    3928             : /**
    3929             :  * Submit a compare I/O to the specified NVMe namespace.
    3930             :  *
    3931             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3932             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3933             :  * given time.
    3934             :  *
    3935             :  * \param ns NVMe namespace to submit the compare I/O.
    3936             :  * \param qpair I/O queue pair to submit the request.
    3937             :  * \param lba Starting LBA to compare the data.
    3938             :  * \param lba_count Length (in sectors) for the compare operation.
    3939             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3940             :  * \param cb_arg Argument to pass to the callback function.
    3941             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3942             :  * \param reset_sgl_fn Callback function to reset scattered payload.
    3943             :  * \param next_sge_fn Callback function to iterate each scattered payload memory
    3944             :  * segment.
    3945             :  * \param metadata Virtual address pointer to the metadata payload, the length
    3946             :  * of metadata is specified by spdk_nvme_ns_get_md_size()
    3947             :  * \param apptag_mask Application tag mask.
    3948             :  * \param apptag Application tag to use end-to-end protection information.
    3949             :  *
    3950             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3951             :  * -EINVAL: The request is malformed.
    3952             :  * -ENOMEM: The request cannot be allocated.
    3953             :  * -ENXIO: The qpair is failed at the transport level.
    3954             :  */
    3955             : int
    3956             : spdk_nvme_ns_cmd_comparev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3957             :                                   uint64_t lba, uint32_t lba_count,
    3958             :                                   spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
    3959             :                                   spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
    3960             :                                   spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
    3961             :                                   uint16_t apptag_mask, uint16_t apptag);
    3962             : 
    3963             : /**
    3964             :  * Submit a compare I/O to the specified NVMe namespace.
    3965             :  *
    3966             :  * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
    3967             :  * The user must ensure that only one thread submits I/O on a given qpair at any
    3968             :  * given time.
    3969             :  *
    3970             :  * \param ns NVMe namespace to submit the compare I/O.
    3971             :  * \param qpair I/O queue pair to submit the request.
    3972             :  * \param payload Virtual address pointer to the data payload.
    3973             :  * \param metadata Virtual address pointer to the metadata payload, the length
    3974             :  * of metadata is specified by spdk_nvme_ns_get_md_size().
    3975             :  * \param lba Starting LBA to compare the data.
    3976             :  * \param lba_count Length (in sectors) for the compare operation.
    3977             :  * \param cb_fn Callback function to invoke when the I/O is completed.
    3978             :  * \param cb_arg Argument to pass to the callback function.
    3979             :  * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
    3980             :  * \param apptag_mask Application tag mask.
    3981             :  * \param apptag Application tag to use end-to-end protection information.
    3982             :  *
    3983             :  * \return 0 if successfully submitted, negated errnos on the following error conditions:
    3984             :  * -EINVAL: The request is malformed.
    3985             :  * -ENOMEM: The request cannot be allocated.
    3986             :  * -ENXIO: The qpair is failed at the transport level.
    3987             :  */
    3988             : int spdk_nvme_ns_cmd_compare_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
    3989             :                                      void *payload, void *metadata,
    3990             :                                      uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
    3991             :                                      void *cb_arg, uint32_t io_flags,
    3992             :                                      uint16_t apptag_mask, uint16_t apptag);
    3993             : 
    3994             : /**
    3995             :  * \brief Inject an error for the next request with a given opcode.
    3996             :  *
    3997             :  * \param ctrlr NVMe controller.
    3998             :  * \param qpair I/O queue pair to add the error command,
    3999             :  *              NULL for Admin queue pair.
    4000             :  * \param opc Opcode for Admin or I/O commands.
    4001             :  * \param do_not_submit True if matching requests should not be submitted
    4002             :  *                      to the controller, but instead completed manually
    4003             :  *                      after timeout_in_us has expired.  False if matching
    4004             :  *                      requests should be submitted to the controller and
    4005             :  *                      have their completion status modified after the
    4006             :  *                      controller completes the request.
    4007             :  * \param timeout_in_us Wait specified microseconds when do_not_submit is true.
    4008             :  * \param err_count Number of matching requests to inject errors.
    4009             :  * \param sct Status code type.
    4010             :  * \param sc Status code.
    4011             :  *
    4012             :  * \return 0 if successfully enabled, ENOMEM if an error command
    4013             :  *           structure cannot be allocated.
    4014             :  *
    4015             :  * The function can be called multiple times to inject errors for different
    4016             :  * commands.  If the opcode matches an existing entry, the existing entry
    4017             :  * will be updated with the values specified.
    4018             :  */
    4019             : int spdk_nvme_qpair_add_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
    4020             :                 struct spdk_nvme_qpair *qpair,
    4021             :                 uint8_t opc,
    4022             :                 bool do_not_submit,
    4023             :                 uint64_t timeout_in_us,
    4024             :                 uint32_t err_count,
    4025             :                 uint8_t sct, uint8_t sc);
    4026             : 
    4027             : /**
    4028             :  * \brief Clear the specified NVMe command with error status.
    4029             :  *
    4030             :  * \param ctrlr NVMe controller.
    4031             :  * \param qpair I/O queue pair to remove the error command,
    4032             :  * \            NULL for Admin queue pair.
    4033             :  * \param opc Opcode for Admin or I/O commands.
    4034             :  *
    4035             :  * The function will remove specified command in the error list.
    4036             :  */
    4037             : void spdk_nvme_qpair_remove_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
    4038             :                 struct spdk_nvme_qpair *qpair,
    4039             :                 uint8_t opc);
    4040             : 
    4041             : /**
    4042             :  * \brief Given NVMe status, return ASCII string for that error.
    4043             :  *
    4044             :  * \param status Status from NVMe completion queue element.
    4045             :  * \return Returns status as an ASCII string.
    4046             :  */
    4047             : const char *spdk_nvme_cpl_get_status_string(const struct spdk_nvme_status *status);
    4048             : 
    4049             : /**
    4050             :  * \brief Given NVMe status, return ASCII string for the type of that error.
    4051             :  *
    4052             :  * \param status Status from NVMe completion queue element.
    4053             :  * \return Returns status type as an ASCII string.
    4054             :  */
    4055             : const char *spdk_nvme_cpl_get_status_type_string(const struct spdk_nvme_status *status);
    4056             : 
    4057             : /**
    4058             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
    4059             :  *
    4060             :  * \param qpair Pointer to the NVMe queue pair - used to determine admin versus I/O queue.
    4061             :  * \param cmd Pointer to the submission queue command to be formatted.
    4062             :  */
    4063             : void spdk_nvme_qpair_print_command(struct spdk_nvme_qpair *qpair,
    4064             :                                    struct spdk_nvme_cmd *cmd);
    4065             : 
    4066             : /**
    4067             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
    4068             :  *
    4069             :  * \param qpair Pointer to the NVMe queue pair - presently unused.
    4070             :  * \param cpl Pointer to the completion queue element to be formatted.
    4071             :  */
    4072             : void spdk_nvme_qpair_print_completion(struct spdk_nvme_qpair *qpair,
    4073             :                                       struct spdk_nvme_cpl *cpl);
    4074             : 
    4075             : /**
    4076             :  * \brief Gets the NVMe qpair ID for the specified qpair.
    4077             :  *
    4078             :  * \param qpair Pointer to the NVMe queue pair.
    4079             :  * \returns ID for the specified qpair.
    4080             :  */
    4081             : uint16_t spdk_nvme_qpair_get_id(struct spdk_nvme_qpair *qpair);
    4082             : 
    4083             : /**
    4084             :  * Gets the number of outstanding requests for the specified qpair.
    4085             :  *
    4086             :  * This number is not decremented until after a request's callback function is completed.
    4087             :  *
    4088             :  * This number is not matched necessarily to the number of NVMe commands submitted by the
    4089             :  * user. For example, nvme driver may split a request due to MDTS limitations, that will
    4090             :  * also allocate a request for the parent, etc.
    4091             :  *
    4092             :  * \param qpair Pointer to the NVMe queue pair.
    4093             :  * \returns number of outstanding requests for the specified qpair.
    4094             :  */
    4095             : uint32_t spdk_nvme_qpair_get_num_outstanding_reqs(struct spdk_nvme_qpair *qpair);
    4096             : 
    4097             : /**
    4098             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
    4099             :  *
    4100             :  * \param qid Queue identifier.
    4101             :  * \param cmd Pointer to the submission queue command to be formatted.
    4102             :  */
    4103             : void spdk_nvme_print_command(uint16_t qid, struct spdk_nvme_cmd *cmd);
    4104             : 
    4105             : /**
    4106             :  * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
    4107             :  *
    4108             :  * \param qid Queue identifier.
    4109             :  * \param cpl Pointer to the completion queue element to be formatted.
    4110             :  */
    4111             : void spdk_nvme_print_completion(uint16_t qid, struct spdk_nvme_cpl *cpl);
    4112             : 
    4113             : /**
    4114             :  * Return the name of a digest.
    4115             :  *
    4116             :  * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
    4117             :  *
    4118             :  * \return Name of the digest.
    4119             :  */
    4120             : const char *spdk_nvme_dhchap_get_digest_name(int id);
    4121             : 
    4122             : /**
    4123             :  * Return the id of a digest.
    4124             :  *
    4125             :  * \param name Name of a digest.
    4126             :  *
    4127             :  * \return Digest id (see `enum spdk_nvmf_dhchap_hash`) or negative errno on failure.
    4128             :  */
    4129             : int spdk_nvme_dhchap_get_digest_id(const char *name);
    4130             : 
    4131             : /**
    4132             :  * Return the length of a digest.
    4133             :  *
    4134             :  * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
    4135             :  *
    4136             :  * \return Length of a digest or 0 if the id is unknown.
    4137             :  */
    4138             : uint8_t spdk_nvme_dhchap_get_digest_length(int id);
    4139             : 
    4140             : /**
    4141             :  * Return the name of a Diffie-Hellman group.
    4142             :  *
    4143             :  * \param id Diffie-Hellman group identifier (see `enum spdk_nvmf_dhchap_dhgroup`).
    4144             :  *
    4145             :  * \return Name of the Diffie-Hellman group.
    4146             :  */
    4147             : const char *spdk_nvme_dhchap_get_dhgroup_name(int id);
    4148             : 
    4149             : /**
    4150             :  * Return the id of a Diffie-Hellman group.
    4151             :  *
    4152             :  * \param name Name of a Diffie-Hellman group.
    4153             :  *
    4154             :  * \return Diffie-Hellman group id (see `enum spdk_nvmf_dhchap_dhgroup`) or negative errno
    4155             :  * on failure.
    4156             :  */
    4157             : int spdk_nvme_dhchap_get_dhgroup_id(const char *name);
    4158             : 
    4159             : struct ibv_context;
    4160             : struct ibv_pd;
    4161             : struct ibv_mr;
    4162             : 
    4163             : /**
    4164             :  * RDMA Transport Hooks
    4165             :  */
    4166             : struct spdk_nvme_rdma_hooks {
    4167             :         /**
    4168             :          * \brief Get an InfiniBand Verbs protection domain.
    4169             :          *
    4170             :          * \param trid the transport id
    4171             :          * \param verbs Infiniband verbs context
    4172             :          *
    4173             :          * \return pd of the nvme ctrlr
    4174             :          */
    4175             :         struct ibv_pd *(*get_ibv_pd)(const struct spdk_nvme_transport_id *trid,
    4176             :                                      struct ibv_context *verbs);
    4177             : 
    4178             :         /**
    4179             :          * \brief Get an InfiniBand Verbs memory region for a buffer.
    4180             :          *
    4181             :          * \param pd The protection domain returned from get_ibv_pd
    4182             :          * \param buf Memory buffer for which an rkey should be returned.
    4183             :          * \param size size of buf
    4184             :          *
    4185             :          * \return Infiniband remote key (rkey) for this buf
    4186             :          */
    4187             :         uint64_t (*get_rkey)(struct ibv_pd *pd, void *buf, size_t size);
    4188             : 
    4189             :         /**
    4190             :          * \brief Put back keys got from get_rkey.
    4191             :          *
    4192             :          * \param key The Infiniband remote key (rkey) got from get_rkey
    4193             :          *
    4194             :          */
    4195             :         void (*put_rkey)(uint64_t key);
    4196             : };
    4197             : 
    4198             : /**
    4199             :  * \brief Set the global hooks for the RDMA transport, if necessary.
    4200             :  *
    4201             :  * This call is optional and must be performed prior to probing for
    4202             :  * any devices. By default, the RDMA transport will use the ibverbs
    4203             :  * library to create protection domains and register memory. This
    4204             :  * is a mechanism to subvert that and use an existing registration.
    4205             :  *
    4206             :  * This function may only be called one time per process.
    4207             :  *
    4208             :  * \param hooks for initializing global hooks
    4209             :  */
    4210             : void spdk_nvme_rdma_init_hooks(struct spdk_nvme_rdma_hooks *hooks);
    4211             : 
    4212             : /**
    4213             :  * Get name of cuse device associated with NVMe controller.
    4214             :  *
    4215             :  * \param ctrlr Opaque handle to NVMe controller.
    4216             :  * \param name  Buffer of be filled with cuse device name.
    4217             :  * \param size  Size of name buffer.
    4218             :  *
    4219             :  * \return 0 on success. Negated errno on the following error conditions:
    4220             :  * -ENODEV: No cuse device registered for the controller.
    4221             :  * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
    4222             :  */
    4223             : int spdk_nvme_cuse_get_ctrlr_name(struct spdk_nvme_ctrlr *ctrlr, char *name, size_t *size);
    4224             : 
    4225             : /**
    4226             :  * Get name of cuse device associated with NVMe namespace.
    4227             :  *
    4228             :  * \param ctrlr Opaque handle to NVMe controller.
    4229             :  * \param nsid  Namespace id.
    4230             :  * \param name  Buffer of be filled with cuse device name.
    4231             :  * \param size  Size of name buffer.
    4232             :  *
    4233             :  * \return 0 on success. Negated errno on the following error conditions:
    4234             :  * -ENODEV: No cuse device registered for the namespace.
    4235             :  * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
    4236             :  */
    4237             : int spdk_nvme_cuse_get_ns_name(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
    4238             :                                char *name, size_t *size);
    4239             : 
    4240             : /**
    4241             :  * Create a character device at the path specified
    4242             :  *
    4243             :  * The character device can handle ioctls and is compatible with a standard
    4244             :  * Linux kernel NVMe device. Tools such as nvme-cli can be used to configure
    4245             :  * SPDK devices through this interface.
    4246             :  *
    4247             :  * The user is expected to be polling the admin qpair for this controller periodically
    4248             :  * for the CUSE device to function.
    4249             :  *
    4250             :  * \param ctrlr Opaque handle to the NVMe controller.
    4251             :  *
    4252             :  * \return 0 on success. Negated errno on failure.
    4253             :  */
    4254             : int spdk_nvme_cuse_register(struct spdk_nvme_ctrlr *ctrlr);
    4255             : 
    4256             : /**
    4257             :  * Remove a previously created character device
    4258             :  *
    4259             :  * \param ctrlr Opaque handle to the NVMe controller.
    4260             :  *
    4261             :  * \return 0 on success. Negated errno on failure.
    4262             :  */
    4263             : int spdk_nvme_cuse_unregister(struct spdk_nvme_ctrlr *ctrlr);
    4264             : 
    4265             : /**
    4266             :  * Get SPDK memory domains used by the given nvme controller.
    4267             :  *
    4268             :  * The user can call this function with \b domains set to NULL and \b array_size set to 0 to get the
    4269             :  * number of memory domains used by nvme controller
    4270             :  *
    4271             :  * \param ctrlr Opaque handle to the NVMe controller.
    4272             :  * \param domains Pointer to an array of memory domains to be filled by this function. The user should allocate big enough
    4273             :  * array to keep all memory domains used by nvme controller
    4274             :  * \param array_size size of \b domains array
    4275             :  * \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
    4276             :  * then the user should increase the size of \b domains array and call this function again. There is no guarantees that
    4277             :  * the content of \b domains array is valid in that case.
    4278             :  *         -EINVAL if input parameters were invalid
    4279             : 
    4280             :  */
    4281             : int spdk_nvme_ctrlr_get_memory_domains(const struct spdk_nvme_ctrlr *ctrlr,
    4282             :                                        struct spdk_memory_domain **domains, int array_size);
    4283             : 
    4284             : /**
    4285             :  * Opaque handle for a transport poll group. Used by the transport function table.
    4286             :  */
    4287             : struct spdk_nvme_transport_poll_group;
    4288             : 
    4289             : /**
    4290             :  * Update and populate namespace CUSE devices (Experimental)
    4291             :  *
    4292             :  * \param ctrlr Opaque handle to the NVMe controller.
    4293             :  *
    4294             :  */
    4295             : void spdk_nvme_cuse_update_namespaces(struct spdk_nvme_ctrlr *ctrlr);
    4296             : 
    4297             : /**
    4298             :  * Signature for callback invoked after completing a register read/write operation.
    4299             :  *
    4300             :  * \param ctx Context passed by the user.
    4301             :  * \param value Value of the register, undefined in case of a failure.
    4302             :  * \param cpl Completion queue entry that contains the status of the command.
    4303             :  */
    4304             : typedef void (*spdk_nvme_reg_cb)(void *ctx, uint64_t value, const struct spdk_nvme_cpl *cpl);
    4305             : 
    4306             : struct nvme_request;
    4307             : 
    4308             : struct spdk_nvme_transport;
    4309             : 
    4310             : struct spdk_nvme_transport_ops {
    4311             :         char name[SPDK_NVMF_TRSTRING_MAX_LEN + 1];
    4312             : 
    4313             :         enum spdk_nvme_transport_type type;
    4314             : 
    4315             :         struct spdk_nvme_ctrlr *(*ctrlr_construct)(const struct spdk_nvme_transport_id *trid,
    4316             :                         const struct spdk_nvme_ctrlr_opts *opts,
    4317             :                         void *devhandle);
    4318             : 
    4319             :         int (*ctrlr_scan)(struct spdk_nvme_probe_ctx *probe_ctx, bool direct_connect);
    4320             : 
    4321             :         int (*ctrlr_destruct)(struct spdk_nvme_ctrlr *ctrlr);
    4322             : 
    4323             :         int (*ctrlr_enable)(struct spdk_nvme_ctrlr *ctrlr);
    4324             : 
    4325             :         int (*ctrlr_set_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value);
    4326             : 
    4327             :         int (*ctrlr_set_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value);
    4328             : 
    4329             :         int (*ctrlr_get_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t *value);
    4330             : 
    4331             :         int (*ctrlr_get_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t *value);
    4332             : 
    4333             :         int (*ctrlr_set_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value,
    4334             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4335             : 
    4336             :         int (*ctrlr_set_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value,
    4337             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4338             : 
    4339             :         int (*ctrlr_get_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
    4340             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4341             : 
    4342             :         int (*ctrlr_get_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
    4343             :                                      spdk_nvme_reg_cb cb_fn, void *cb_arg);
    4344             : 
    4345             :         uint32_t (*ctrlr_get_max_xfer_size)(struct spdk_nvme_ctrlr *ctrlr);
    4346             : 
    4347             :         uint16_t (*ctrlr_get_max_sges)(struct spdk_nvme_ctrlr *ctrlr);
    4348             : 
    4349             :         int (*ctrlr_reserve_cmb)(struct spdk_nvme_ctrlr *ctrlr);
    4350             : 
    4351             :         void *(*ctrlr_map_cmb)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    4352             : 
    4353             :         int (*ctrlr_unmap_cmb)(struct spdk_nvme_ctrlr *ctrlr);
    4354             : 
    4355             :         int (*ctrlr_enable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4356             : 
    4357             :         int (*ctrlr_disable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4358             : 
    4359             :         void *(*ctrlr_map_pmr)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
    4360             : 
    4361             :         int (*ctrlr_unmap_pmr)(struct spdk_nvme_ctrlr *ctrlr);
    4362             : 
    4363             :         struct spdk_nvme_qpair *(*ctrlr_create_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid,
    4364             :                         const struct spdk_nvme_io_qpair_opts *opts);
    4365             : 
    4366             :         int (*ctrlr_delete_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4367             : 
    4368             :         int (*ctrlr_connect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4369             : 
    4370             :         void (*ctrlr_disconnect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
    4371             : 
    4372             :         void (*qpair_abort_reqs)(struct spdk_nvme_qpair *qpair, uint32_t dnr);
    4373             : 
    4374             :         int (*qpair_reset)(struct spdk_nvme_qpair *qpair);
    4375             : 
    4376             :         int (*qpair_submit_request)(struct spdk_nvme_qpair *qpair, struct nvme_request *req);
    4377             : 
    4378             :         int32_t (*qpair_process_completions)(struct spdk_nvme_qpair *qpair, uint32_t max_completions);
    4379             : 
    4380             :         int (*qpair_iterate_requests)(struct spdk_nvme_qpair *qpair,
    4381             :                                       int (*iter_fn)(struct nvme_request *req, void *arg),
    4382             :                                       void *arg);
    4383             : 
    4384             :         void (*admin_qpair_abort_aers)(struct spdk_nvme_qpair *qpair);
    4385             : 
    4386             :         struct spdk_nvme_transport_poll_group *(*poll_group_create)(void);
    4387             :         struct spdk_nvme_transport_poll_group *(*qpair_get_optimal_poll_group)(
    4388             :                 struct spdk_nvme_qpair *qpair);
    4389             : 
    4390             :         int (*poll_group_add)(struct spdk_nvme_transport_poll_group *tgroup, struct spdk_nvme_qpair *qpair);
    4391             : 
    4392             :         int (*poll_group_remove)(struct spdk_nvme_transport_poll_group *tgroup,
    4393             :                                  struct spdk_nvme_qpair *qpair);
    4394             : 
    4395             :         int (*poll_group_connect_qpair)(struct spdk_nvme_qpair *qpair);
    4396             : 
    4397             :         int (*poll_group_disconnect_qpair)(struct spdk_nvme_qpair *qpair);
    4398             : 
    4399             :         int64_t (*poll_group_process_completions)(struct spdk_nvme_transport_poll_group *tgroup,
    4400             :                         uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
    4401             : 
    4402             :         int (*poll_group_destroy)(struct spdk_nvme_transport_poll_group *tgroup);
    4403             : 
    4404             :         int (*poll_group_get_stats)(struct spdk_nvme_transport_poll_group *tgroup,
    4405             :                                     struct spdk_nvme_transport_poll_group_stat **stats);
    4406             : 
    4407             :         void (*poll_group_free_stats)(struct spdk_nvme_transport_poll_group *tgroup,
    4408             :                                       struct spdk_nvme_transport_poll_group_stat *stats);
    4409             : 
    4410             :         int (*ctrlr_get_memory_domains)(const struct spdk_nvme_ctrlr *ctrlr,
    4411             :                                         struct spdk_memory_domain **domains,
    4412             :                                         int array_size);
    4413             : 
    4414             :         int (*ctrlr_ready)(struct spdk_nvme_ctrlr *ctrlr);
    4415             : 
    4416             :         volatile struct spdk_nvme_registers *(*ctrlr_get_registers)(struct spdk_nvme_ctrlr *ctrlr);
    4417             : 
    4418             :         /* Optional callback for transports to process removal events of attached controllers. */
    4419             :         int (*ctrlr_scan_attached)(struct spdk_nvme_probe_ctx *probe_ctx);
    4420             : };
    4421             : 
    4422             : /**
    4423             :  * Register the operations for a given transport type.
    4424             :  *
    4425             :  * This function should be invoked by referencing the macro
    4426             :  * SPDK_NVME_TRANSPORT_REGISTER macro in the transport's .c file.
    4427             :  *
    4428             :  * \param ops The operations associated with an NVMe-oF transport.
    4429             :  */
    4430             : void spdk_nvme_transport_register(const struct spdk_nvme_transport_ops *ops);
    4431             : 
    4432             : /*
    4433             :  * Macro used to register new transports.
    4434             :  */
    4435             : #define SPDK_NVME_TRANSPORT_REGISTER(name, transport_ops) \
    4436             : static void __attribute__((constructor)) _spdk_nvme_transport_register_##name(void) \
    4437             : { \
    4438             :         spdk_nvme_transport_register(transport_ops); \
    4439             : }
    4440             : 
    4441             : /**
    4442             :  * NVMe transport options.
    4443             :  */
    4444             : struct spdk_nvme_transport_opts {
    4445             :         /**
    4446             :          * It is used for RDMA transport.
    4447             :          *
    4448             :          * The queue depth of a shared rdma receive queue.
    4449             :          */
    4450             :         uint32_t rdma_srq_size;
    4451             : 
    4452             :         /* Hole at bytes 4-7. */
    4453             :         uint8_t reserved4[4];
    4454             : 
    4455             :         /**
    4456             :          * The size of spdk_nvme_transport_opts according to the caller of this library is used for ABI
    4457             :          * compatibility.  The library uses this field to know how many fields in this
    4458             :          * structure are valid. And the library will populate any remaining fields with default values.
    4459             :          */
    4460             :         size_t opts_size;
    4461             : 
    4462             :         /**
    4463             :          * It is used for RDMA transport.
    4464             :          *
    4465             :          * The maximum queue depth of a rdma completion queue.
    4466             :          * It is zero, which means unlimited, by default.
    4467             :          */
    4468             :         uint32_t rdma_max_cq_size;
    4469             : 
    4470             :         /**
    4471             :          * It is used for RDMA transport.
    4472             :          *
    4473             :          * RDMA CM event timeout in milliseconds.
    4474             :          */
    4475             :         uint16_t rdma_cm_event_timeout_ms;
    4476             : };
    4477             : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_transport_opts) == 24, "Incorrect size");
    4478             : 
    4479             : /**
    4480             :  * Get the current NVMe transport options.
    4481             :  *
    4482             :  * \param[out] opts Will be filled with the current options for spdk_nvme_transport_set_opts().
    4483             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
    4484             :  */
    4485             : void spdk_nvme_transport_get_opts(struct spdk_nvme_transport_opts *opts, size_t opts_size);
    4486             : 
    4487             : /**
    4488             :  * Set the NVMe transport options.
    4489             :  *
    4490             :  * \param opts Pointer to the allocated spdk_nvme_transport_opts structure with new values.
    4491             :  * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
    4492             :  *
    4493             :  * \return 0 on success, or negated errno on failure.
    4494             :  */
    4495             : int spdk_nvme_transport_set_opts(const struct spdk_nvme_transport_opts *opts, size_t opts_size);
    4496             : 
    4497             : #ifdef __cplusplus
    4498             : }
    4499             : #endif
    4500             : 
    4501             : #endif

Generated by: LCOV version 1.15