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

Generated by: LCOV version 1.15