ceph/src/spdk/include/spdk/nvmf_transport.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright (c) Intel Corporation. All rights reserved.
   5  *   Copyright (c) 2019 Mellanox Technologies LTD. All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /** \file
  35  * NVMe-oF Target transport plugin API
  36  */
  37
  38 #ifndef SPDK_NVMF_TRANSPORT_H_
  39 #define SPDK_NVMF_TRANSPORT_H_
  40
  41 #include "spdk/bdev.h"
  42 #include "spdk/nvme_spec.h"
  43 #include "spdk/nvmf.h"
  44 #include "spdk/nvmf_cmd.h"
  45 #include "spdk/nvmf_spec.h"
  46 #include "spdk/memory.h"
  47
  48 #define SPDK_NVMF_MAX_SGL_ENTRIES       16
  49
  50 /* The maximum number of buffers per request */
  51 #define NVMF_REQ_MAX_BUFFERS    (SPDK_NVMF_MAX_SGL_ENTRIES * 2)
  52
  53 /* AIO backend requires block size aligned data buffers,
  54  * extra 4KiB aligned data buffer should work for most devices.
  55  */
  56 #define NVMF_DATA_BUFFER_ALIGNMENT      VALUE_4KB
  57 #define NVMF_DATA_BUFFER_MASK           (NVMF_DATA_BUFFER_ALIGNMENT - 1LL)
  58
  59 union nvmf_h2c_msg {
  60         struct spdk_nvmf_capsule_cmd                    nvmf_cmd;
  61         struct spdk_nvme_cmd                            nvme_cmd;
  62         struct spdk_nvmf_fabric_prop_set_cmd            prop_set_cmd;
  63         struct spdk_nvmf_fabric_prop_get_cmd            prop_get_cmd;
  64         struct spdk_nvmf_fabric_connect_cmd             connect_cmd;
  65 };
  66 SPDK_STATIC_ASSERT(sizeof(union nvmf_h2c_msg) == 64, "Incorrect size");
  67
  68 union nvmf_c2h_msg {
  69         struct spdk_nvme_cpl                            nvme_cpl;
  70         struct spdk_nvmf_fabric_prop_get_rsp            prop_get_rsp;
  71         struct spdk_nvmf_fabric_connect_rsp             connect_rsp;
  72 };
  73 SPDK_STATIC_ASSERT(sizeof(union nvmf_c2h_msg) == 16, "Incorrect size");
  74
  75 struct spdk_nvmf_dif_info {
  76         struct spdk_dif_ctx                     dif_ctx;
  77         bool                                    dif_insert_or_strip;
  78         uint32_t                                elba_length;
  79         uint32_t                                orig_length;
  80 };
  81
  82 struct spdk_nvmf_request {
  83         struct spdk_nvmf_qpair          *qpair;
  84         uint32_t                        length;
  85         enum spdk_nvme_data_transfer    xfer;
  86         void                            *data;
  87         union nvmf_h2c_msg              *cmd;
  88         union nvmf_c2h_msg              *rsp;
  89         void                            *buffers[NVMF_REQ_MAX_BUFFERS];
  90         struct iovec                    iov[NVMF_REQ_MAX_BUFFERS];
  91         uint32_t                        iovcnt;
  92         bool                            data_from_pool;
  93         struct spdk_bdev_io_wait_entry  bdev_io_wait;
  94         struct spdk_nvmf_dif_info       dif;
  95         spdk_nvmf_nvme_passthru_cmd_cb  cmd_cb_fn;
  96         struct spdk_nvmf_request        *first_fused_req;
  97         struct spdk_nvmf_request        *req_to_abort;
  98         struct spdk_poller              *poller;
  99         uint64_t                        timeout_tsc;
 100
 101         STAILQ_ENTRY(spdk_nvmf_request) buf_link;
 102         TAILQ_ENTRY(spdk_nvmf_request)  link;
 103 };
 104
 105 enum spdk_nvmf_qpair_state {
 106         SPDK_NVMF_QPAIR_UNINITIALIZED = 0,
 107         SPDK_NVMF_QPAIR_ACTIVE,
 108         SPDK_NVMF_QPAIR_DEACTIVATING,
 109         SPDK_NVMF_QPAIR_ERROR,
 110 };
 111
 112 typedef void (*spdk_nvmf_state_change_done)(void *cb_arg, int status);
 113
 114 struct spdk_nvmf_qpair {
 115         enum spdk_nvmf_qpair_state              state;
 116         spdk_nvmf_state_change_done             state_cb;
 117         void                                    *state_cb_arg;
 118
 119         struct spdk_nvmf_transport              *transport;
 120         struct spdk_nvmf_ctrlr                  *ctrlr;
 121         struct spdk_nvmf_poll_group             *group;
 122
 123         uint16_t                                qid;
 124         uint16_t                                sq_head;
 125         uint16_t                                sq_head_max;
 126
 127         struct spdk_nvmf_request                *first_fused_req;
 128
 129         TAILQ_HEAD(, spdk_nvmf_request)         outstanding;
 130         TAILQ_ENTRY(spdk_nvmf_qpair)            link;
 131 };
 132
 133 struct spdk_nvmf_transport_pg_cache_buf {
 134         STAILQ_ENTRY(spdk_nvmf_transport_pg_cache_buf) link;
 135 };
 136
 137 struct spdk_nvmf_transport_poll_group {
 138         struct spdk_nvmf_transport                                      *transport;
 139         /* Requests that are waiting to obtain a data buffer */
 140         STAILQ_HEAD(, spdk_nvmf_request)                                pending_buf_queue;
 141         STAILQ_HEAD(, spdk_nvmf_transport_pg_cache_buf)                 buf_cache;
 142         uint32_t                                                        buf_cache_count;
 143         uint32_t                                                        buf_cache_size;
 144         struct spdk_nvmf_poll_group                                     *group;
 145         TAILQ_ENTRY(spdk_nvmf_transport_poll_group)                     link;
 146 };
 147
 148 struct spdk_nvmf_poll_group {
 149         struct spdk_thread                              *thread;
 150         struct spdk_poller                              *poller;
 151
 152         TAILQ_HEAD(, spdk_nvmf_transport_poll_group)    tgroups;
 153
 154         /* Array of poll groups indexed by subsystem id (sid) */
 155         struct spdk_nvmf_subsystem_poll_group           *sgroups;
 156         uint32_t                                        num_sgroups;
 157
 158         /* All of the queue pairs that belong to this poll group */
 159         TAILQ_HEAD(, spdk_nvmf_qpair)                   qpairs;
 160
 161         /* Statistics */
 162         struct spdk_nvmf_poll_group_stat                stat;
 163
 164         spdk_nvmf_poll_group_destroy_done_fn            destroy_cb_fn;
 165         void                                            *destroy_cb_arg;
 166
 167         TAILQ_ENTRY(spdk_nvmf_poll_group)               link;
 168 };
 169
 170 struct spdk_nvmf_listener {
 171         struct spdk_nvme_transport_id   trid;
 172         uint32_t                        ref;
 173
 174         TAILQ_ENTRY(spdk_nvmf_listener) link;
 175 };
 176
 177 /**
 178  * A subset of struct spdk_nvme_ctrlr_data that are emulated by a fabrics device.
 179  */
 180 struct spdk_nvmf_ctrlr_data {
 181         uint16_t kas;
 182         struct spdk_nvme_cdata_sgls sgls;
 183         struct spdk_nvme_cdata_nvmf_specific nvmf_specific;
 184 };
 185
 186 struct spdk_nvmf_transport {
 187         struct spdk_nvmf_tgt                    *tgt;
 188         const struct spdk_nvmf_transport_ops    *ops;
 189         struct spdk_nvmf_transport_opts         opts;
 190
 191         /* A mempool for transport related data transfers */
 192         struct spdk_mempool                     *data_buf_pool;
 193
 194         TAILQ_HEAD(, spdk_nvmf_listener)        listeners;
 195         TAILQ_ENTRY(spdk_nvmf_transport)        link;
 196 };
 197
 198 struct spdk_nvmf_transport_ops {
 199         /**
 200          * Transport name
 201          */
 202         char name[SPDK_NVMF_TRSTRING_MAX_LEN];
 203
 204         /**
 205          * Transport type
 206          */
 207         enum spdk_nvme_transport_type type;
 208
 209         /**
 210          * Initialize transport options to default value
 211          */
 212         void (*opts_init)(struct spdk_nvmf_transport_opts *opts);
 213
 214         /**
 215          * Create a transport for the given transport opts
 216          */
 217         struct spdk_nvmf_transport *(*create)(struct spdk_nvmf_transport_opts *opts);
 218
 219         /**
 220          * Destroy the transport
 221          */
 222         int (*destroy)(struct spdk_nvmf_transport *transport);
 223
 224         /**
 225           * Instruct the transport to accept new connections at the address
 226           * provided. This may be called multiple times.
 227           */
 228         int (*listen)(struct spdk_nvmf_transport *transport,
 229                       const struct spdk_nvme_transport_id *trid);
 230
 231         /**
 232           * Stop accepting new connections at the given address.
 233           */
 234         void (*stop_listen)(struct spdk_nvmf_transport *transport,
 235                             const struct spdk_nvme_transport_id *trid);
 236
 237         /**
 238          * A listener has been associated with a subsystem with the given NQN.
 239          * This is only a notification. Most transports will not need to take any
 240          * action here, as the enforcement of the association is done in the generic
 241          * code.
 242          *
 243          * The association is not considered complete until cb_fn is called. New
 244          * connections on the listener targeting this subsystem will be rejected
 245          * until that time.
 246          *
 247          * Pass a negated errno code to `cb_fn` to block the association. 0 to allow.
 248          */
 249         void (*listen_associate)(struct spdk_nvmf_transport *transport,
 250                                  const struct spdk_nvmf_subsystem *subsystem,
 251                                  const struct spdk_nvme_transport_id *trid,
 252                                  spdk_nvmf_tgt_subsystem_listen_done_fn cb_fn,
 253                                  void *cb_arg);
 254
 255         /**
 256          * Check for new connections on the transport.
 257          */
 258         uint32_t (*accept)(struct spdk_nvmf_transport *transport);
 259
 260         /**
 261          * Initialize subset of identify controller data.
 262          */
 263         void (*cdata_init)(struct spdk_nvmf_transport *transport, struct spdk_nvmf_subsystem *subsystem,
 264                            struct spdk_nvmf_ctrlr_data *cdata);
 265
 266         /**
 267          * Fill out a discovery log entry for a specific listen address.
 268          */
 269         void (*listener_discover)(struct spdk_nvmf_transport *transport,
 270                                   struct spdk_nvme_transport_id *trid,
 271                                   struct spdk_nvmf_discovery_log_page_entry *entry);
 272
 273         /**
 274          * Create a new poll group
 275          */
 276         struct spdk_nvmf_transport_poll_group *(*poll_group_create)(struct spdk_nvmf_transport *transport);
 277
 278         /**
 279          * Get the polling group of the queue pair optimal for the specific transport
 280          */
 281         struct spdk_nvmf_transport_poll_group *(*get_optimal_poll_group)(struct spdk_nvmf_qpair *qpair);
 282
 283         /**
 284          * Destroy a poll group
 285          */
 286         void (*poll_group_destroy)(struct spdk_nvmf_transport_poll_group *group);
 287
 288         /**
 289          * Add a qpair to a poll group
 290          */
 291         int (*poll_group_add)(struct spdk_nvmf_transport_poll_group *group,
 292                               struct spdk_nvmf_qpair *qpair);
 293
 294         /**
 295          * Remove a qpair from a poll group
 296          */
 297         int (*poll_group_remove)(struct spdk_nvmf_transport_poll_group *group,
 298                                  struct spdk_nvmf_qpair *qpair);
 299
 300         /**
 301          * Poll the group to process I/O
 302          */
 303         int (*poll_group_poll)(struct spdk_nvmf_transport_poll_group *group);
 304
 305         /*
 306          * Free the request without sending a response
 307          * to the originator. Release memory tied to this request.
 308          */
 309         int (*req_free)(struct spdk_nvmf_request *req);
 310
 311         /*
 312          * Signal request completion, which sends a response
 313          * to the originator.
 314          */
 315         int (*req_complete)(struct spdk_nvmf_request *req);
 316
 317         /*
 318          * Deinitialize a connection.
 319          */
 320         void (*qpair_fini)(struct spdk_nvmf_qpair *qpair);
 321
 322         /*
 323          * Get the peer transport ID for the queue pair.
 324          */
 325         int (*qpair_get_peer_trid)(struct spdk_nvmf_qpair *qpair,
 326                                    struct spdk_nvme_transport_id *trid);
 327
 328         /*
 329          * Get the local transport ID for the queue pair.
 330          */
 331         int (*qpair_get_local_trid)(struct spdk_nvmf_qpair *qpair,
 332                                     struct spdk_nvme_transport_id *trid);
 333
 334         /*
 335          * Get the listener transport ID that accepted this qpair originally.
 336          */
 337         int (*qpair_get_listen_trid)(struct spdk_nvmf_qpair *qpair,
 338                                      struct spdk_nvme_transport_id *trid);
 339
 340         /*
 341          * Abort the request which the abort request specifies.
 342          * This function can complete synchronously or asynchronously, but
 343          * is expected to call spdk_nvmf_request_complete() in the end
 344          * for both cases.
 345          */
 346         void (*qpair_abort_request)(struct spdk_nvmf_qpair *qpair,
 347                                     struct spdk_nvmf_request *req);
 348
 349         /*
 350          * Get transport poll group statistics
 351          */
 352         int (*poll_group_get_stat)(struct spdk_nvmf_tgt *tgt,
 353                                    struct spdk_nvmf_transport_poll_group_stat **stat);
 354
 355         /*
 356          * Free transport poll group statistics previously allocated with poll_group_get_stat()
 357          */
 358         void (*poll_group_free_stat)(struct spdk_nvmf_transport_poll_group_stat *stat);
 359 };
 360
 361 /**
 362  * Register the operations for a given transport type.
 363  *
 364  * This function should be invoked by referencing the macro
 365  * SPDK_NVMF_TRANSPORT_REGISTER macro in the transport's .c file.
 366  *
 367  * \param ops The operations associated with an NVMe-oF transport.
 368  */
 369 void spdk_nvmf_transport_register(const struct spdk_nvmf_transport_ops *ops);
 370
 371 int spdk_nvmf_ctrlr_connect(struct spdk_nvmf_request *req);
 372
 373 /**
 374  * Function to be called for each newly discovered qpair.
 375  *
 376  * \param tgt The nvmf target
 377  * \param qpair The newly discovered qpair.
 378  */
 379 void spdk_nvmf_tgt_new_qpair(struct spdk_nvmf_tgt *tgt, struct spdk_nvmf_qpair *qpair);
 380
 381 /**
 382  * A subset of struct spdk_nvme_registers that are emulated by a fabrics device.
 383  */
 384 struct spdk_nvmf_registers {
 385         union spdk_nvme_cap_register    cap;
 386         union spdk_nvme_vs_register     vs;
 387         union spdk_nvme_cc_register     cc;
 388         union spdk_nvme_csts_register   csts;
 389         union spdk_nvme_aqa_register    aqa;
 390         uint64_t                        asq;
 391         uint64_t                        acq;
 392 };
 393
 394 const struct spdk_nvmf_registers *spdk_nvmf_ctrlr_get_regs(struct spdk_nvmf_ctrlr *ctrlr);
 395
 396 void spdk_nvmf_request_free_buffers(struct spdk_nvmf_request *req,
 397                                     struct spdk_nvmf_transport_poll_group *group,
 398                                     struct spdk_nvmf_transport *transport);
 399 int spdk_nvmf_request_get_buffers(struct spdk_nvmf_request *req,
 400                                   struct spdk_nvmf_transport_poll_group *group,
 401                                   struct spdk_nvmf_transport *transport,
 402                                   uint32_t length);
 403 int spdk_nvmf_request_get_buffers_multi(struct spdk_nvmf_request *req,
 404                                         struct spdk_nvmf_transport_poll_group *group,
 405                                         struct spdk_nvmf_transport *transport,
 406                                         uint32_t *lengths, uint32_t num_lengths);
 407
 408 bool spdk_nvmf_request_get_dif_ctx(struct spdk_nvmf_request *req, struct spdk_dif_ctx *dif_ctx);
 409
 410 void spdk_nvmf_request_exec(struct spdk_nvmf_request *req);
 411 void spdk_nvmf_request_exec_fabrics(struct spdk_nvmf_request *req);
 412 int spdk_nvmf_request_free(struct spdk_nvmf_request *req);
 413 int spdk_nvmf_request_complete(struct spdk_nvmf_request *req);
 414
 415 /**
 416  * Remove the given qpair from the poll group.
 417  *
 418  * \param qpair The qpair to remove.
 419  */
 420 void spdk_nvmf_poll_group_remove(struct spdk_nvmf_qpair *qpair);
 421
 422 /**
 423  * Get the NVMe-oF subsystem associated with this controller.
 424  *
 425  * \param ctrlr The NVMe-oF controller
 426  *
 427  * \return The NVMe-oF subsystem
 428  */
 429 struct spdk_nvmf_subsystem *
 430 spdk_nvmf_ctrlr_get_subsystem(struct spdk_nvmf_ctrlr *ctrlr);
 431
 432 /**
 433  * Get the NVMe-oF controller ID.
 434  *
 435  * \param ctrlr The NVMe-oF controller
 436  *
 437  * \return The NVMe-oF controller ID
 438  */
 439 uint16_t
 440 spdk_nvmf_ctrlr_get_id(struct spdk_nvmf_ctrlr *ctrlr);
 441
 442 static inline enum spdk_nvme_data_transfer
 443 spdk_nvmf_req_get_xfer(struct spdk_nvmf_request *req) {
 444         enum spdk_nvme_data_transfer xfer;
 445         struct spdk_nvme_cmd *cmd = &req->cmd->nvme_cmd;
 446         struct spdk_nvme_sgl_descriptor *sgl = &cmd->dptr.sgl1;
 447
 448         /* Figure out data transfer direction */
 449         if (cmd->opc == SPDK_NVME_OPC_FABRIC)
 450         {
 451                 xfer = spdk_nvme_opc_get_data_transfer(req->cmd->nvmf_cmd.fctype);
 452         } else
 453         {
 454                 xfer = spdk_nvme_opc_get_data_transfer(cmd->opc);
 455         }
 456
 457         if (xfer == SPDK_NVME_DATA_NONE)
 458         {
 459                 return xfer;
 460         }
 461
 462         /* Even for commands that may transfer data, they could have specified 0 length.
 463          * We want those to show up with xfer SPDK_NVME_DATA_NONE.
 464          */
 465         switch (sgl->generic.type)
 466         {
 467         case SPDK_NVME_SGL_TYPE_DATA_BLOCK:
 468         case SPDK_NVME_SGL_TYPE_BIT_BUCKET:
 469         case SPDK_NVME_SGL_TYPE_SEGMENT:
 470         case SPDK_NVME_SGL_TYPE_LAST_SEGMENT:
 471         case SPDK_NVME_SGL_TYPE_TRANSPORT_DATA_BLOCK:
 472                 if (sgl->unkeyed.length == 0) {
 473                         xfer = SPDK_NVME_DATA_NONE;
 474                 }
 475                 break;
 476         case SPDK_NVME_SGL_TYPE_KEYED_DATA_BLOCK:
 477                 if (sgl->keyed.length == 0) {
 478                         xfer = SPDK_NVME_DATA_NONE;
 479                 }
 480                 break;
 481         }
 482
 483         return xfer;
 484 }
 485
 486 /*
 487  * Macro used to register new transports.
 488  */
 489 #define SPDK_NVMF_TRANSPORT_REGISTER(name, transport_ops) \
 490 static void __attribute__((constructor)) _spdk_nvmf_transport_register_##name(void) \
 491 { \
 492         spdk_nvmf_transport_register(transport_ops); \
 493 }\
 494
 495 #endif