1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Copyright (c) 2016, Avago Technologies 4 */ 5 6 #ifndef _NVME_FC_DRIVER_H 7 #define _NVME_FC_DRIVER_H 1 8 9 #include <linux/scatterlist.h> 10 #include <linux/blk-mq.h> 11 12 13 /* 14 * ********************** FC-NVME LS API ******************** 15 * 16 * Data structures used by both FC-NVME hosts and FC-NVME 17 * targets to perform FC-NVME LS requests or transmit 18 * responses. 19 * 20 * *********************************************************** 21 */ 22 23 /** 24 * struct nvmefc_ls_req - Request structure passed from the transport 25 * to the LLDD to perform a NVME-FC LS request and obtain 26 * a response. 27 * Used by nvme-fc transport (host) to send LS's such as 28 * Create Association, Create Connection and Disconnect 29 * Association. 30 * Used by the nvmet-fc transport (controller) to send 31 * LS's such as Disconnect Association. 32 * 33 * Values set by the requestor prior to calling the LLDD ls_req entrypoint: 34 * @rqstaddr: pointer to request buffer 35 * @rqstdma: PCI DMA address of request buffer 36 * @rqstlen: Length, in bytes, of request buffer 37 * @rspaddr: pointer to response buffer 38 * @rspdma: PCI DMA address of response buffer 39 * @rsplen: Length, in bytes, of response buffer 40 * @timeout: Maximum amount of time, in seconds, to wait for the LS response. 41 * If timeout exceeded, LLDD to abort LS exchange and complete 42 * LS request with error status. 43 * @private: pointer to memory allocated alongside the ls request structure 44 * that is specifically for the LLDD to use while processing the 45 * request. The length of the buffer corresponds to the 46 * lsrqst_priv_sz value specified in the xxx_template supplied 47 * by the LLDD. 48 * @done: The callback routine the LLDD is to invoke upon completion of 49 * the LS request. req argument is the pointer to the original LS 50 * request structure. Status argument must be 0 upon success, a 51 * negative errno on failure (example: -ENXIO). 52 */ 53 struct nvmefc_ls_req { 54 void *rqstaddr; 55 dma_addr_t rqstdma; 56 u32 rqstlen; 57 void *rspaddr; 58 dma_addr_t rspdma; 59 u32 rsplen; 60 u32 timeout; 61 62 void *private; 63 64 void (*done)(struct nvmefc_ls_req *req, int status); 65 66 } __aligned(sizeof(u64)); /* alignment for other things alloc'd with */ 67 68 69 /** 70 * struct nvmefc_ls_rsp - Structure passed from the transport to the LLDD 71 * to request the transmit the NVME-FC LS response to a 72 * NVME-FC LS request. The structure originates in the LLDD 73 * and is given to the transport via the xxx_rcv_ls_req() 74 * transport routine. As such, the structure represents the 75 * FC exchange context for the NVME-FC LS request that was 76 * received and which the response is to be sent for. 77 * Used by the LLDD to pass the nvmet-fc transport (controller) 78 * received LS's such as Create Association, Create Connection 79 * and Disconnect Association. 80 * Used by the LLDD to pass the nvme-fc transport (host) 81 * received LS's such as Disconnect Association or Disconnect 82 * Connection. 83 * 84 * The structure is allocated by the LLDD whenever a LS Request is received 85 * from the FC link. The address of the structure is passed to the nvmet-fc 86 * or nvme-fc layer via the xxx_rcv_ls_req() transport routines. 87 * 88 * The address of the structure is to be passed back to the LLDD 89 * when the response is to be transmit. The LLDD will use the address to 90 * map back to the LLDD exchange structure which maintains information such 91 * the remote N_Port that sent the LS as well as any FC exchange context. 92 * Upon completion of the LS response transmit, the LLDD will pass the 93 * address of the structure back to the transport LS rsp done() routine, 94 * allowing the transport release dma resources. Upon completion of 95 * the done() routine, no further access to the structure will be made by 96 * the transport and the LLDD can de-allocate the structure. 97 * 98 * Field initialization: 99 * At the time of the xxx_rcv_ls_req() call, there is no content that 100 * is valid in the structure. 101 * 102 * When the structure is used for the LLDD->xmt_ls_rsp() call, the 103 * transport layer will fully set the fields in order to specify the 104 * response payload buffer and its length as well as the done routine 105 * to be called upon completion of the transmit. The transport layer 106 * will also set a private pointer for its own use in the done routine. 107 * 108 * Values set by the transport layer prior to calling the LLDD xmt_ls_rsp 109 * entrypoint: 110 * @rspbuf: pointer to the LS response buffer 111 * @rspdma: PCI DMA address of the LS response buffer 112 * @rsplen: Length, in bytes, of the LS response buffer 113 * @done: The callback routine the LLDD is to invoke upon completion of 114 * transmitting the LS response. req argument is the pointer to 115 * the original ls request. 116 * @nvme_fc_private: pointer to an internal transport-specific structure 117 * used as part of the transport done() processing. The LLDD is 118 * not to access this pointer. 119 */ 120 struct nvmefc_ls_rsp { 121 void *rspbuf; 122 dma_addr_t rspdma; 123 u16 rsplen; 124 125 void (*done)(struct nvmefc_ls_rsp *rsp); 126 void *nvme_fc_private; /* LLDD is not to access !! */ 127 }; 128 129 130 131 /* 132 * ********************** LLDD FC-NVME Host API ******************** 133 * 134 * For FC LLDD's that are the NVME Host role. 135 * 136 * ****************************************************************** 137 */ 138 139 140 /** 141 * struct nvme_fc_port_info - port-specific ids and FC connection-specific 142 * data element used during NVME Host role 143 * registrations 144 * 145 * Static fields describing the port being registered: 146 * @node_name: FC WWNN for the port 147 * @port_name: FC WWPN for the port 148 * @port_role: What NVME roles are supported (see FC_PORT_ROLE_xxx) 149 * @dev_loss_tmo: maximum delay for reconnects to an association on 150 * this device. Used only on a remoteport. 151 * 152 * Initialization values for dynamic port fields: 153 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must 154 * be set to 0. 155 */ 156 struct nvme_fc_port_info { 157 u64 node_name; 158 u64 port_name; 159 u32 port_role; 160 u32 port_id; 161 u32 dev_loss_tmo; 162 }; 163 164 enum nvmefc_fcp_datadir { 165 NVMEFC_FCP_NODATA, /* payload_length and sg_cnt will be zero */ 166 NVMEFC_FCP_WRITE, 167 NVMEFC_FCP_READ, 168 }; 169 170 171 /** 172 * struct nvmefc_fcp_req - Request structure passed from NVME-FC transport 173 * to LLDD in order to perform a NVME FCP IO operation. 174 * 175 * Values set by the NVME-FC layer prior to calling the LLDD fcp_io 176 * entrypoint. 177 * @cmdaddr: pointer to the FCP CMD IU buffer 178 * @rspaddr: pointer to the FCP RSP IU buffer 179 * @cmddma: PCI DMA address of the FCP CMD IU buffer 180 * @rspdma: PCI DMA address of the FCP RSP IU buffer 181 * @cmdlen: Length, in bytes, of the FCP CMD IU buffer 182 * @rsplen: Length, in bytes, of the FCP RSP IU buffer 183 * @payload_length: Length of DATA_IN or DATA_OUT payload data to transfer 184 * @sg_table: scatter/gather structure for payload data 185 * @first_sgl: memory for 1st scatter/gather list segment for payload data 186 * @sg_cnt: number of elements in the scatter/gather list 187 * @io_dir: direction of the FCP request (see NVMEFC_FCP_xxx) 188 * @sqid: The nvme SQID the command is being issued on 189 * @done: The callback routine the LLDD is to invoke upon completion of 190 * the FCP operation. req argument is the pointer to the original 191 * FCP IO operation. 192 * @private: pointer to memory allocated alongside the FCP operation 193 * request structure that is specifically for the LLDD to use 194 * while processing the operation. The length of the buffer 195 * corresponds to the fcprqst_priv_sz value specified in the 196 * nvme_fc_port_template supplied by the LLDD. 197 * 198 * Values set by the LLDD indicating completion status of the FCP operation. 199 * Must be set prior to calling the done() callback. 200 * @transferred_length: amount of payload data, in bytes, that were 201 * transferred. Should equal payload_length on success. 202 * @rcv_rsplen: length, in bytes, of the FCP RSP IU received. 203 * @status: Completion status of the FCP operation. must be 0 upon success, 204 * negative errno value upon failure (ex: -EIO). Note: this is 205 * NOT a reflection of the NVME CQE completion status. Only the 206 * status of the FCP operation at the NVME-FC level. 207 */ 208 struct nvmefc_fcp_req { 209 void *cmdaddr; 210 void *rspaddr; 211 dma_addr_t cmddma; 212 dma_addr_t rspdma; 213 u16 cmdlen; 214 u16 rsplen; 215 216 u32 payload_length; 217 struct sg_table sg_table; 218 struct scatterlist *first_sgl; 219 int sg_cnt; 220 enum nvmefc_fcp_datadir io_dir; 221 222 __le16 sqid; 223 224 void (*done)(struct nvmefc_fcp_req *req); 225 226 void *private; 227 228 u32 transferred_length; 229 u16 rcv_rsplen; 230 u32 status; 231 } __aligned(sizeof(u64)); /* alignment for other things alloc'd with */ 232 233 234 /* 235 * Direct copy of fc_port_state enum. For later merging 236 */ 237 enum nvme_fc_obj_state { 238 FC_OBJSTATE_UNKNOWN, 239 FC_OBJSTATE_NOTPRESENT, 240 FC_OBJSTATE_ONLINE, 241 FC_OBJSTATE_OFFLINE, /* User has taken Port Offline */ 242 FC_OBJSTATE_BLOCKED, 243 FC_OBJSTATE_BYPASSED, 244 FC_OBJSTATE_DIAGNOSTICS, 245 FC_OBJSTATE_LINKDOWN, 246 FC_OBJSTATE_ERROR, 247 FC_OBJSTATE_LOOPBACK, 248 FC_OBJSTATE_DELETED, 249 }; 250 251 252 /** 253 * struct nvme_fc_local_port - structure used between NVME-FC transport and 254 * a LLDD to reference a local NVME host port. 255 * Allocated/created by the nvme_fc_register_localport() 256 * transport interface. 257 * 258 * Fields with static values for the port. Initialized by the 259 * port_info struct supplied to the registration call. 260 * @port_num: NVME-FC transport host port number 261 * @port_role: NVME roles are supported on the port (see FC_PORT_ROLE_xxx) 262 * @node_name: FC WWNN for the port 263 * @port_name: FC WWPN for the port 264 * @private: pointer to memory allocated alongside the local port 265 * structure that is specifically for the LLDD to use. 266 * The length of the buffer corresponds to the local_priv_sz 267 * value specified in the nvme_fc_port_template supplied by 268 * the LLDD. 269 * @dev_loss_tmo: maximum delay for reconnects to an association on 270 * this device. To modify, lldd must call 271 * nvme_fc_set_remoteport_devloss(). 272 * 273 * Fields with dynamic values. Values may change base on link state. LLDD 274 * may reference fields directly to change them. Initialized by the 275 * port_info struct supplied to the registration call. 276 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must 277 * be set to 0. 278 * @port_state: Operational state of the port. 279 */ 280 struct nvme_fc_local_port { 281 /* static/read-only fields */ 282 u32 port_num; 283 u32 port_role; 284 u64 node_name; 285 u64 port_name; 286 287 void *private; 288 289 /* dynamic fields */ 290 u32 port_id; 291 enum nvme_fc_obj_state port_state; 292 } __aligned(sizeof(u64)); /* alignment for other things alloc'd with */ 293 294 295 /** 296 * struct nvme_fc_remote_port - structure used between NVME-FC transport and 297 * a LLDD to reference a remote NVME subsystem port. 298 * Allocated/created by the nvme_fc_register_remoteport() 299 * transport interface. 300 * 301 * Fields with static values for the port. Initialized by the 302 * port_info struct supplied to the registration call. 303 * @port_num: NVME-FC transport remote subsystem port number 304 * @port_role: NVME roles are supported on the port (see FC_PORT_ROLE_xxx) 305 * @node_name: FC WWNN for the port 306 * @port_name: FC WWPN for the port 307 * @localport: pointer to the NVME-FC local host port the subsystem is 308 * connected to. 309 * @private: pointer to memory allocated alongside the remote port 310 * structure that is specifically for the LLDD to use. 311 * The length of the buffer corresponds to the remote_priv_sz 312 * value specified in the nvme_fc_port_template supplied by 313 * the LLDD. 314 * 315 * Fields with dynamic values. Values may change base on link or login 316 * state. LLDD may reference fields directly to change them. Initialized by 317 * the port_info struct supplied to the registration call. 318 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must 319 * be set to 0. 320 * @port_state: Operational state of the remote port. Valid values are 321 * ONLINE or UNKNOWN. 322 */ 323 struct nvme_fc_remote_port { 324 /* static fields */ 325 u32 port_num; 326 u32 port_role; 327 u64 node_name; 328 u64 port_name; 329 struct nvme_fc_local_port *localport; 330 void *private; 331 u32 dev_loss_tmo; 332 333 /* dynamic fields */ 334 u32 port_id; 335 enum nvme_fc_obj_state port_state; 336 } __aligned(sizeof(u64)); /* alignment for other things alloc'd with */ 337 338 339 /** 340 * struct nvme_fc_port_template - structure containing static entrypoints and 341 * operational parameters for an LLDD that supports NVME host 342 * behavior. Passed by reference in port registrations. 343 * NVME-FC transport remembers template reference and may 344 * access it during runtime operation. 345 * 346 * Host/Initiator Transport Entrypoints/Parameters: 347 * 348 * @localport_delete: The LLDD initiates deletion of a localport via 349 * nvme_fc_deregister_localport(). However, the teardown is 350 * asynchronous. This routine is called upon the completion of the 351 * teardown to inform the LLDD that the localport has been deleted. 352 * Entrypoint is Mandatory. 353 * 354 * @remoteport_delete: The LLDD initiates deletion of a remoteport via 355 * nvme_fc_deregister_remoteport(). However, the teardown is 356 * asynchronous. This routine is called upon the completion of the 357 * teardown to inform the LLDD that the remoteport has been deleted. 358 * Entrypoint is Mandatory. 359 * 360 * @create_queue: Upon creating a host<->controller association, queues are 361 * created such that they can be affinitized to cpus/cores. This 362 * callback into the LLDD to notify that a controller queue is being 363 * created. The LLDD may choose to allocate an associated hw queue 364 * or map it onto a shared hw queue. Upon return from the call, the 365 * LLDD specifies a handle that will be given back to it for any 366 * command that is posted to the controller queue. The handle can 367 * be used by the LLDD to map quickly to the proper hw queue for 368 * command execution. The mask of cpu's that will map to this queue 369 * at the block-level is also passed in. The LLDD should use the 370 * queue id and/or cpu masks to ensure proper affinitization of the 371 * controller queue to the hw queue. 372 * Entrypoint is Optional. 373 * 374 * @delete_queue: This is the inverse of the crete_queue. During 375 * host<->controller association teardown, this routine is called 376 * when a controller queue is being terminated. Any association with 377 * a hw queue should be termined. If there is a unique hw queue, the 378 * hw queue should be torn down. 379 * Entrypoint is Optional. 380 * 381 * @poll_queue: Called to poll for the completion of an io on a blk queue. 382 * Entrypoint is Optional. 383 * 384 * @ls_req: Called to issue a FC-NVME FC-4 LS service request. 385 * The nvme_fc_ls_req structure will fully describe the buffers for 386 * the request payload and where to place the response payload. The 387 * LLDD is to allocate an exchange, issue the LS request, obtain the 388 * LS response, and call the "done" routine specified in the request 389 * structure (argument to done is the ls request structure itself). 390 * Entrypoint is Mandatory. 391 * 392 * @fcp_io: called to issue a FC-NVME I/O request. The I/O may be for 393 * an admin queue or an i/o queue. The nvmefc_fcp_req structure will 394 * fully describe the io: the buffer containing the FC-NVME CMD IU 395 * (which contains the SQE), the sg list for the payload if applicable, 396 * and the buffer to place the FC-NVME RSP IU into. The LLDD will 397 * complete the i/o, indicating the amount of data transferred or 398 * any transport error, and call the "done" routine specified in the 399 * request structure (argument to done is the fcp request structure 400 * itself). 401 * Entrypoint is Mandatory. 402 * 403 * @ls_abort: called to request the LLDD to abort the indicated ls request. 404 * The call may return before the abort has completed. After aborting 405 * the request, the LLDD must still call the ls request done routine 406 * indicating an FC transport Aborted status. 407 * Entrypoint is Mandatory. 408 * 409 * @fcp_abort: called to request the LLDD to abort the indicated fcp request. 410 * The call may return before the abort has completed. After aborting 411 * the request, the LLDD must still call the fcp request done routine 412 * indicating an FC transport Aborted status. 413 * Entrypoint is Mandatory. 414 * 415 * @xmt_ls_rsp: Called to transmit the response to a FC-NVME FC-4 LS service. 416 * The nvmefc_ls_rsp structure is the same LLDD-supplied exchange 417 * structure specified in the nvme_fc_rcv_ls_req() call made when 418 * the LS request was received. The structure will fully describe 419 * the buffers for the response payload and the dma address of the 420 * payload. The LLDD is to transmit the response (or return a 421 * non-zero errno status), and upon completion of the transmit, call 422 * the "done" routine specified in the nvmefc_ls_rsp structure 423 * (argument to done is the address of the nvmefc_ls_rsp structure 424 * itself). Upon the completion of the done routine, the LLDD shall 425 * consider the LS handling complete and the nvmefc_ls_rsp structure 426 * may be freed/released. 427 * Entrypoint is mandatory if the LLDD calls the nvme_fc_rcv_ls_req() 428 * entrypoint. 429 * 430 * @max_hw_queues: indicates the maximum number of hw queues the LLDD 431 * supports for cpu affinitization. 432 * Value is Mandatory. Must be at least 1. 433 * 434 * @max_sgl_segments: indicates the maximum number of sgl segments supported 435 * by the LLDD 436 * Value is Mandatory. Must be at least 1. Recommend at least 256. 437 * 438 * @max_dif_sgl_segments: indicates the maximum number of sgl segments 439 * supported by the LLDD for DIF operations. 440 * Value is Mandatory. Must be at least 1. Recommend at least 256. 441 * 442 * @dma_boundary: indicates the dma address boundary where dma mappings 443 * will be split across. 444 * Value is Mandatory. Typical value is 0xFFFFFFFF to split across 445 * 4Gig address boundarys 446 * 447 * @local_priv_sz: The LLDD sets this field to the amount of additional 448 * memory that it would like fc nvme layer to allocate on the LLDD's 449 * behalf whenever a localport is allocated. The additional memory 450 * area solely for the of the LLDD and its location is specified by 451 * the localport->private pointer. 452 * Value is Mandatory. Allowed to be zero. 453 * 454 * @remote_priv_sz: The LLDD sets this field to the amount of additional 455 * memory that it would like fc nvme layer to allocate on the LLDD's 456 * behalf whenever a remoteport is allocated. The additional memory 457 * area solely for the of the LLDD and its location is specified by 458 * the remoteport->private pointer. 459 * Value is Mandatory. Allowed to be zero. 460 * 461 * @lsrqst_priv_sz: The LLDD sets this field to the amount of additional 462 * memory that it would like fc nvme layer to allocate on the LLDD's 463 * behalf whenever a ls request structure is allocated. The additional 464 * memory area is solely for use by the LLDD and its location is 465 * specified by the ls_request->private pointer. 466 * Value is Mandatory. Allowed to be zero. 467 * 468 * @fcprqst_priv_sz: The LLDD sets this field to the amount of additional 469 * memory that it would like fc nvme layer to allocate on the LLDD's 470 * behalf whenever a fcp request structure is allocated. The additional 471 * memory area solely for the of the LLDD and its location is 472 * specified by the fcp_request->private pointer. 473 * Value is Mandatory. Allowed to be zero. 474 */ 475 struct nvme_fc_port_template { 476 /* initiator-based functions */ 477 void (*localport_delete)(struct nvme_fc_local_port *); 478 void (*remoteport_delete)(struct nvme_fc_remote_port *); 479 int (*create_queue)(struct nvme_fc_local_port *, 480 unsigned int qidx, u16 qsize, 481 void **handle); 482 void (*delete_queue)(struct nvme_fc_local_port *, 483 unsigned int qidx, void *handle); 484 int (*ls_req)(struct nvme_fc_local_port *, 485 struct nvme_fc_remote_port *, 486 struct nvmefc_ls_req *); 487 int (*fcp_io)(struct nvme_fc_local_port *, 488 struct nvme_fc_remote_port *, 489 void *hw_queue_handle, 490 struct nvmefc_fcp_req *); 491 void (*ls_abort)(struct nvme_fc_local_port *, 492 struct nvme_fc_remote_port *, 493 struct nvmefc_ls_req *); 494 void (*fcp_abort)(struct nvme_fc_local_port *, 495 struct nvme_fc_remote_port *, 496 void *hw_queue_handle, 497 struct nvmefc_fcp_req *); 498 int (*xmt_ls_rsp)(struct nvme_fc_local_port *localport, 499 struct nvme_fc_remote_port *rport, 500 struct nvmefc_ls_rsp *ls_rsp); 501 void (*map_queues)(struct nvme_fc_local_port *localport, 502 struct blk_mq_queue_map *map); 503 504 u32 max_hw_queues; 505 u16 max_sgl_segments; 506 u16 max_dif_sgl_segments; 507 u64 dma_boundary; 508 509 /* sizes of additional private data for data structures */ 510 u32 local_priv_sz; 511 u32 remote_priv_sz; 512 u32 lsrqst_priv_sz; 513 u32 fcprqst_priv_sz; 514 }; 515 516 517 /* 518 * Initiator/Host functions 519 */ 520 521 int nvme_fc_register_localport(struct nvme_fc_port_info *pinfo, 522 struct nvme_fc_port_template *template, 523 struct device *dev, 524 struct nvme_fc_local_port **lport_p); 525 526 int nvme_fc_unregister_localport(struct nvme_fc_local_port *localport); 527 528 int nvme_fc_register_remoteport(struct nvme_fc_local_port *localport, 529 struct nvme_fc_port_info *pinfo, 530 struct nvme_fc_remote_port **rport_p); 531 532 int nvme_fc_unregister_remoteport(struct nvme_fc_remote_port *remoteport); 533 534 void nvme_fc_rescan_remoteport(struct nvme_fc_remote_port *remoteport); 535 536 int nvme_fc_set_remoteport_devloss(struct nvme_fc_remote_port *remoteport, 537 u32 dev_loss_tmo); 538 539 /* 540 * Routine called to pass a NVME-FC LS request, received by the lldd, 541 * to the nvme-fc transport. 542 * 543 * If the return value is zero: the LS was successfully accepted by the 544 * transport. 545 * If the return value is non-zero: the transport has not accepted the 546 * LS. The lldd should ABTS-LS the LS. 547 * 548 * Note: if the LLDD receives and ABTS for the LS prior to the transport 549 * calling the ops->xmt_ls_rsp() routine to transmit a response, the LLDD 550 * shall mark the LS as aborted, and when the xmt_ls_rsp() is called: the 551 * response shall not be transmit and the struct nvmefc_ls_rsp() done 552 * routine shall be called. The LLDD may transmit the ABTS response as 553 * soon as the LS was marked or can delay until the xmt_ls_rsp() call is 554 * made. 555 * Note: if an RCV LS was successfully posted to the transport and the 556 * remoteport is then unregistered before xmt_ls_rsp() was called for 557 * the lsrsp structure, the transport will still call xmt_ls_rsp() 558 * afterward to cleanup the outstanding lsrsp structure. The LLDD should 559 * noop the transmission of the rsp and call the lsrsp->done() routine 560 * to allow the lsrsp structure to be released. 561 */ 562 int nvme_fc_rcv_ls_req(struct nvme_fc_remote_port *remoteport, 563 struct nvmefc_ls_rsp *lsrsp, 564 void *lsreqbuf, u32 lsreqbuf_len); 565 566 567 /* 568 * Routine called to get the appid field associated with request by the lldd 569 * 570 * If the return value is NULL : the user/libvirt has not set the appid to VM 571 * If the return value is non-zero: Returns the appid associated with VM 572 * 573 * @req: IO request from nvme fc to driver 574 */ 575 char *nvme_fc_io_getuuid(struct nvmefc_fcp_req *req); 576 577 /* 578 * *************** LLDD FC-NVME Target/Subsystem API *************** 579 * 580 * For FC LLDD's that are the NVME Subsystem role 581 * 582 * ****************************************************************** 583 */ 584 585 /** 586 * struct nvmet_fc_port_info - port-specific ids and FC connection-specific 587 * data element used during NVME Subsystem role 588 * registrations 589 * 590 * Static fields describing the port being registered: 591 * @node_name: FC WWNN for the port 592 * @port_name: FC WWPN for the port 593 * 594 * Initialization values for dynamic port fields: 595 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must 596 * be set to 0. 597 */ 598 struct nvmet_fc_port_info { 599 u64 node_name; 600 u64 port_name; 601 u32 port_id; 602 }; 603 604 605 /* Operations that NVME-FC layer may request the LLDD to perform for FCP */ 606 enum { 607 NVMET_FCOP_READDATA = 1, /* xmt data to initiator */ 608 NVMET_FCOP_WRITEDATA = 2, /* xmt data from initiator */ 609 NVMET_FCOP_READDATA_RSP = 3, /* xmt data to initiator and send 610 * rsp as well 611 */ 612 NVMET_FCOP_RSP = 4, /* send rsp frame */ 613 }; 614 615 /** 616 * struct nvmefc_tgt_fcp_req - Structure used between LLDD and NVMET-FC 617 * layer to represent the exchange context and 618 * the specific FC-NVME IU operation(s) to perform 619 * for a FC-NVME FCP IO. 620 * 621 * Structure used between LLDD and nvmet-fc layer to represent the exchange 622 * context for a FC-NVME FCP I/O operation (e.g. a nvme sqe, the sqe-related 623 * memory transfers, and its assocated cqe transfer). 624 * 625 * The structure is allocated by the LLDD whenever a FCP CMD IU is received 626 * from the FC link. The address of the structure is passed to the nvmet-fc 627 * layer via the nvmet_fc_rcv_fcp_req() call. The address of the structure 628 * will be passed back to the LLDD for the data operations and transmit of 629 * the response. The LLDD is to use the address to map back to the LLDD 630 * exchange structure which maintains information such as the targetport 631 * the FCP I/O was received on, the remote FC NVME initiator that sent the 632 * FCP I/O, and any FC exchange context. Upon completion of the FCP target 633 * operation, the address of the structure will be passed back to the FCP 634 * op done() routine, allowing the nvmet-fc layer to release dma resources. 635 * Upon completion of the done() routine for either RSP or ABORT ops, no 636 * further access will be made by the nvmet-fc layer and the LLDD can 637 * de-allocate the structure. 638 * 639 * Field initialization: 640 * At the time of the nvmet_fc_rcv_fcp_req() call, there is no content that 641 * is valid in the structure. 642 * 643 * When the structure is used for an FCP target operation, the nvmet-fc 644 * layer will fully set the fields in order to specify the scattergather 645 * list, the transfer length, as well as the done routine to be called 646 * upon compeletion of the operation. The nvmet-fc layer will also set a 647 * private pointer for its own use in the done routine. 648 * 649 * Values set by the NVMET-FC layer prior to calling the LLDD fcp_op 650 * entrypoint. 651 * @op: Indicates the FCP IU operation to perform (see NVMET_FCOP_xxx) 652 * @hwqid: Specifies the hw queue index (0..N-1, where N is the 653 * max_hw_queues value from the LLD's nvmet_fc_target_template) 654 * that the operation is to use. 655 * @offset: Indicates the DATA_OUT/DATA_IN payload offset to be tranferred. 656 * Field is only valid on WRITEDATA, READDATA, or READDATA_RSP ops. 657 * @timeout: amount of time, in seconds, to wait for a response from the NVME 658 * host. A value of 0 is an infinite wait. 659 * Valid only for the following ops: 660 * WRITEDATA: caps the wait for data reception 661 * READDATA_RSP & RSP: caps wait for FCP_CONF reception (if used) 662 * @transfer_length: the length, in bytes, of the DATA_OUT or DATA_IN payload 663 * that is to be transferred. 664 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops. 665 * @ba_rjt: Contains the BA_RJT payload that is to be transferred. 666 * Valid only for the NVMET_FCOP_BA_RJT op. 667 * @sg: Scatter/gather list for the DATA_OUT/DATA_IN payload data. 668 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops. 669 * @sg_cnt: Number of valid entries in the scatter/gather list. 670 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops. 671 * @rspaddr: pointer to the FCP RSP IU buffer to be transmit 672 * Used by RSP and READDATA_RSP ops 673 * @rspdma: PCI DMA address of the FCP RSP IU buffer 674 * Used by RSP and READDATA_RSP ops 675 * @rsplen: Length, in bytes, of the FCP RSP IU buffer 676 * Used by RSP and READDATA_RSP ops 677 * @done: The callback routine the LLDD is to invoke upon completion of 678 * the operation. req argument is the pointer to the original 679 * FCP subsystem op request. 680 * @nvmet_fc_private: pointer to an internal NVMET-FC layer structure used 681 * as part of the NVMET-FC processing. The LLDD is not to 682 * reference this field. 683 * 684 * Values set by the LLDD indicating completion status of the FCP operation. 685 * Must be set prior to calling the done() callback. 686 * @transferred_length: amount of DATA_OUT payload data received by a 687 * WRITEDATA operation. If not a WRITEDATA operation, value must 688 * be set to 0. Should equal transfer_length on success. 689 * @fcp_error: status of the FCP operation. Must be 0 on success; on failure 690 * must be a NVME_SC_FC_xxxx value. 691 */ 692 struct nvmefc_tgt_fcp_req { 693 u8 op; 694 u16 hwqid; 695 u32 offset; 696 u32 timeout; 697 u32 transfer_length; 698 struct fc_ba_rjt ba_rjt; 699 struct scatterlist *sg; 700 int sg_cnt; 701 void *rspaddr; 702 dma_addr_t rspdma; 703 u16 rsplen; 704 705 void (*done)(struct nvmefc_tgt_fcp_req *); 706 707 void *nvmet_fc_private; /* LLDD is not to access !! */ 708 709 u32 transferred_length; 710 int fcp_error; 711 }; 712 713 714 /* Target Features (Bit fields) LLDD supports */ 715 enum { 716 NVMET_FCTGTFEAT_READDATA_RSP = (1 << 0), 717 /* Bit 0: supports the NVMET_FCPOP_READDATA_RSP op, which 718 * sends (the last) Read Data sequence followed by the RSP 719 * sequence in one LLDD operation. Errors during Data 720 * sequence transmit must not allow RSP sequence to be sent. 721 */ 722 }; 723 724 725 /** 726 * struct nvmet_fc_target_port - structure used between NVME-FC transport and 727 * a LLDD to reference a local NVME subsystem port. 728 * Allocated/created by the nvme_fc_register_targetport() 729 * transport interface. 730 * 731 * Fields with static values for the port. Initialized by the 732 * port_info struct supplied to the registration call. 733 * @port_num: NVME-FC transport subsystem port number 734 * @node_name: FC WWNN for the port 735 * @port_name: FC WWPN for the port 736 * @private: pointer to memory allocated alongside the local port 737 * structure that is specifically for the LLDD to use. 738 * The length of the buffer corresponds to the target_priv_sz 739 * value specified in the nvme_fc_target_template supplied by 740 * the LLDD. 741 * 742 * Fields with dynamic values. Values may change base on link state. LLDD 743 * may reference fields directly to change them. Initialized by the 744 * port_info struct supplied to the registration call. 745 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must 746 * be set to 0. 747 * @port_state: Operational state of the port. 748 */ 749 struct nvmet_fc_target_port { 750 /* static/read-only fields */ 751 u32 port_num; 752 u64 node_name; 753 u64 port_name; 754 755 void *private; 756 757 /* dynamic fields */ 758 u32 port_id; 759 enum nvme_fc_obj_state port_state; 760 } __aligned(sizeof(u64)); /* alignment for other things alloc'd with */ 761 762 763 /** 764 * struct nvmet_fc_target_template - structure containing static entrypoints 765 * and operational parameters for an LLDD that supports NVME 766 * subsystem behavior. Passed by reference in port 767 * registrations. NVME-FC transport remembers template 768 * reference and may access it during runtime operation. 769 * 770 * Subsystem/Target Transport Entrypoints/Parameters: 771 * 772 * @targetport_delete: The LLDD initiates deletion of a targetport via 773 * nvmet_fc_unregister_targetport(). However, the teardown is 774 * asynchronous. This routine is called upon the completion of the 775 * teardown to inform the LLDD that the targetport has been deleted. 776 * Entrypoint is Mandatory. 777 * 778 * @xmt_ls_rsp: Called to transmit the response to a FC-NVME FC-4 LS service. 779 * The nvmefc_ls_rsp structure is the same LLDD-supplied exchange 780 * structure specified in the nvmet_fc_rcv_ls_req() call made when 781 * the LS request was received. The structure will fully describe 782 * the buffers for the response payload and the dma address of the 783 * payload. The LLDD is to transmit the response (or return a 784 * non-zero errno status), and upon completion of the transmit, call 785 * the "done" routine specified in the nvmefc_ls_rsp structure 786 * (argument to done is the address of the nvmefc_ls_rsp structure 787 * itself). Upon the completion of the done() routine, the LLDD shall 788 * consider the LS handling complete and the nvmefc_ls_rsp structure 789 * may be freed/released. 790 * The transport will always call the xmt_ls_rsp() routine for any 791 * LS received. 792 * Entrypoint is Mandatory. 793 * 794 * @map_queues: This functions lets the driver expose the queue mapping 795 * to the block layer. 796 * Entrypoint is Optional. 797 * 798 * @fcp_op: Called to perform a data transfer or transmit a response. 799 * The nvmefc_tgt_fcp_req structure is the same LLDD-supplied 800 * exchange structure specified in the nvmet_fc_rcv_fcp_req() call 801 * made when the FCP CMD IU was received. The op field in the 802 * structure shall indicate the operation for the LLDD to perform 803 * relative to the io. 804 * NVMET_FCOP_READDATA operation: the LLDD is to send the 805 * payload data (described by sglist) to the host in 1 or 806 * more FC sequences (preferrably 1). Note: the fc-nvme layer 807 * may call the READDATA operation multiple times for longer 808 * payloads. 809 * NVMET_FCOP_WRITEDATA operation: the LLDD is to receive the 810 * payload data (described by sglist) from the host via 1 or 811 * more FC sequences (preferrably 1). The LLDD is to generate 812 * the XFER_RDY IU(s) corresponding to the data being requested. 813 * Note: the FC-NVME layer may call the WRITEDATA operation 814 * multiple times for longer payloads. 815 * NVMET_FCOP_READDATA_RSP operation: the LLDD is to send the 816 * payload data (described by sglist) to the host in 1 or 817 * more FC sequences (preferrably 1). If an error occurs during 818 * payload data transmission, the LLDD is to set the 819 * nvmefc_tgt_fcp_req fcp_error and transferred_length field, then 820 * consider the operation complete. On error, the LLDD is to not 821 * transmit the FCP_RSP iu. If all payload data is transferred 822 * successfully, the LLDD is to update the nvmefc_tgt_fcp_req 823 * transferred_length field and may subsequently transmit the 824 * FCP_RSP iu payload (described by rspbuf, rspdma, rsplen). 825 * If FCP_CONF is supported, the LLDD is to await FCP_CONF 826 * reception to confirm the RSP reception by the host. The LLDD 827 * may retramsit the FCP_RSP iu if necessary per FC-NVME. Upon 828 * transmission of the FCP_RSP iu if FCP_CONF is not supported, 829 * or upon success/failure of FCP_CONF if it is supported, the 830 * LLDD is to set the nvmefc_tgt_fcp_req fcp_error field and 831 * consider the operation complete. 832 * NVMET_FCOP_RSP: the LLDD is to transmit the FCP_RSP iu payload 833 * (described by rspbuf, rspdma, rsplen). If FCP_CONF is 834 * supported, the LLDD is to await FCP_CONF reception to confirm 835 * the RSP reception by the host. The LLDD may retramsit the 836 * FCP_RSP iu if FCP_CONF is not received per FC-NVME. Upon 837 * transmission of the FCP_RSP iu if FCP_CONF is not supported, 838 * or upon success/failure of FCP_CONF if it is supported, the 839 * LLDD is to set the nvmefc_tgt_fcp_req fcp_error field and 840 * consider the operation complete. 841 * Upon completing the indicated operation, the LLDD is to set the 842 * status fields for the operation (tranferred_length and fcp_error 843 * status) in the request, then call the "done" routine 844 * indicated in the fcp request. After the operation completes, 845 * regardless of whether the FCP_RSP iu was successfully transmit, 846 * the LLDD-supplied exchange structure must remain valid until the 847 * transport calls the fcp_req_release() callback to return ownership 848 * of the exchange structure back to the LLDD so that it may be used 849 * for another fcp command. 850 * Note: when calling the done routine for READDATA or WRITEDATA 851 * operations, the fc-nvme layer may immediate convert, in the same 852 * thread and before returning to the LLDD, the fcp operation to 853 * the next operation for the fcp io and call the LLDDs fcp_op 854 * call again. If fields in the fcp request are to be accessed post 855 * the done call, the LLDD should save their values prior to calling 856 * the done routine, and inspect the save values after the done 857 * routine. 858 * Returns 0 on success, -<errno> on failure (Ex: -EIO) 859 * Entrypoint is Mandatory. 860 * 861 * @fcp_abort: Called by the transport to abort an active command. 862 * The command may be in-between operations (nothing active in LLDD) 863 * or may have an active WRITEDATA operation pending. The LLDD is to 864 * initiate the ABTS process for the command and return from the 865 * callback. The ABTS does not need to be complete on the command. 866 * The fcp_abort callback inherently cannot fail. After the 867 * fcp_abort() callback completes, the transport will wait for any 868 * outstanding operation (if there was one) to complete, then will 869 * call the fcp_req_release() callback to return the command's 870 * exchange context back to the LLDD. 871 * Entrypoint is Mandatory. 872 * 873 * @fcp_req_release: Called by the transport to return a nvmefc_tgt_fcp_req 874 * to the LLDD after all operations on the fcp operation are complete. 875 * This may be due to the command completing or upon completion of 876 * abort cleanup. 877 * Entrypoint is Mandatory. 878 * 879 * @defer_rcv: Called by the transport to signal the LLLD that it has 880 * begun processing of a previously received NVME CMD IU. The LLDD 881 * is now free to re-use the rcv buffer associated with the 882 * nvmefc_tgt_fcp_req. 883 * Entrypoint is Optional. 884 * 885 * @discovery_event: Called by the transport to generate an RSCN 886 * change notifications to NVME initiators. The RSCN notifications 887 * should cause the initiator to rescan the discovery controller 888 * on the targetport. 889 * 890 * @ls_req: Called to issue a FC-NVME FC-4 LS service request. 891 * The nvme_fc_ls_req structure will fully describe the buffers for 892 * the request payload and where to place the response payload. 893 * The targetport that is to issue the LS request is identified by 894 * the targetport argument. The remote port that is to receive the 895 * LS request is identified by the hosthandle argument. The nvmet-fc 896 * transport is only allowed to issue FC-NVME LS's on behalf of an 897 * association that was created prior by a Create Association LS. 898 * The hosthandle will originate from the LLDD in the struct 899 * nvmefc_ls_rsp structure for the Create Association LS that 900 * was delivered to the transport. The transport will save the 901 * hosthandle as an attribute of the association. If the LLDD 902 * loses connectivity with the remote port, it must call the 903 * nvmet_fc_invalidate_host() routine to remove any references to 904 * the remote port in the transport. 905 * The LLDD is to allocate an exchange, issue the LS request, obtain 906 * the LS response, and call the "done" routine specified in the 907 * request structure (argument to done is the ls request structure 908 * itself). 909 * Entrypoint is Optional - but highly recommended. 910 * 911 * @ls_abort: called to request the LLDD to abort the indicated ls request. 912 * The call may return before the abort has completed. After aborting 913 * the request, the LLDD must still call the ls request done routine 914 * indicating an FC transport Aborted status. 915 * Entrypoint is Mandatory if the ls_req entry point is specified. 916 * 917 * @host_release: called to inform the LLDD that the request to invalidate 918 * the host port indicated by the hosthandle has been fully completed. 919 * No associations exist with the host port and there will be no 920 * further references to hosthandle. 921 * Entrypoint is Mandatory if the lldd calls nvmet_fc_invalidate_host(). 922 * 923 * @max_hw_queues: indicates the maximum number of hw queues the LLDD 924 * supports for cpu affinitization. 925 * Value is Mandatory. Must be at least 1. 926 * 927 * @max_sgl_segments: indicates the maximum number of sgl segments supported 928 * by the LLDD 929 * Value is Mandatory. Must be at least 1. Recommend at least 256. 930 * 931 * @max_dif_sgl_segments: indicates the maximum number of sgl segments 932 * supported by the LLDD for DIF operations. 933 * Value is Mandatory. Must be at least 1. Recommend at least 256. 934 * 935 * @dma_boundary: indicates the dma address boundary where dma mappings 936 * will be split across. 937 * Value is Mandatory. Typical value is 0xFFFFFFFF to split across 938 * 4Gig address boundarys 939 * 940 * @target_features: The LLDD sets bits in this field to correspond to 941 * optional features that are supported by the LLDD. 942 * Refer to the NVMET_FCTGTFEAT_xxx values. 943 * Value is Mandatory. Allowed to be zero. 944 * 945 * @target_priv_sz: The LLDD sets this field to the amount of additional 946 * memory that it would like fc nvme layer to allocate on the LLDD's 947 * behalf whenever a targetport is allocated. The additional memory 948 * area solely for the of the LLDD and its location is specified by 949 * the targetport->private pointer. 950 * Value is Mandatory. Allowed to be zero. 951 * 952 * @lsrqst_priv_sz: The LLDD sets this field to the amount of additional 953 * memory that it would like nvmet-fc layer to allocate on the LLDD's 954 * behalf whenever a ls request structure is allocated. The additional 955 * memory area is solely for use by the LLDD and its location is 956 * specified by the ls_request->private pointer. 957 * Value is Mandatory. Allowed to be zero. 958 * 959 */ 960 struct nvmet_fc_target_template { 961 void (*targetport_delete)(struct nvmet_fc_target_port *tgtport); 962 int (*xmt_ls_rsp)(struct nvmet_fc_target_port *tgtport, 963 struct nvmefc_ls_rsp *ls_rsp); 964 int (*fcp_op)(struct nvmet_fc_target_port *tgtport, 965 struct nvmefc_tgt_fcp_req *fcpreq); 966 void (*fcp_abort)(struct nvmet_fc_target_port *tgtport, 967 struct nvmefc_tgt_fcp_req *fcpreq); 968 void (*fcp_req_release)(struct nvmet_fc_target_port *tgtport, 969 struct nvmefc_tgt_fcp_req *fcpreq); 970 void (*defer_rcv)(struct nvmet_fc_target_port *tgtport, 971 struct nvmefc_tgt_fcp_req *fcpreq); 972 void (*discovery_event)(struct nvmet_fc_target_port *tgtport); 973 int (*ls_req)(struct nvmet_fc_target_port *targetport, 974 void *hosthandle, struct nvmefc_ls_req *lsreq); 975 void (*ls_abort)(struct nvmet_fc_target_port *targetport, 976 void *hosthandle, struct nvmefc_ls_req *lsreq); 977 void (*host_release)(void *hosthandle); 978 979 u32 max_hw_queues; 980 u16 max_sgl_segments; 981 u16 max_dif_sgl_segments; 982 u64 dma_boundary; 983 984 u32 target_features; 985 986 /* sizes of additional private data for data structures */ 987 u32 target_priv_sz; 988 u32 lsrqst_priv_sz; 989 }; 990 991 992 int nvmet_fc_register_targetport(struct nvmet_fc_port_info *portinfo, 993 struct nvmet_fc_target_template *template, 994 struct device *dev, 995 struct nvmet_fc_target_port **tgtport_p); 996 997 int nvmet_fc_unregister_targetport(struct nvmet_fc_target_port *tgtport); 998 999 /* 1000 * Routine called to pass a NVME-FC LS request, received by the lldd, 1001 * to the nvmet-fc transport. 1002 * 1003 * If the return value is zero: the LS was successfully accepted by the 1004 * transport. 1005 * If the return value is non-zero: the transport has not accepted the 1006 * LS. The lldd should ABTS-LS the LS. 1007 * 1008 * Note: if the LLDD receives and ABTS for the LS prior to the transport 1009 * calling the ops->xmt_ls_rsp() routine to transmit a response, the LLDD 1010 * shall mark the LS as aborted, and when the xmt_ls_rsp() is called: the 1011 * response shall not be transmit and the struct nvmefc_ls_rsp() done 1012 * routine shall be called. The LLDD may transmit the ABTS response as 1013 * soon as the LS was marked or can delay until the xmt_ls_rsp() call is 1014 * made. 1015 * Note: if an RCV LS was successfully posted to the transport and the 1016 * targetport is then unregistered before xmt_ls_rsp() was called for 1017 * the lsrsp structure, the transport will still call xmt_ls_rsp() 1018 * afterward to cleanup the outstanding lsrsp structure. The LLDD should 1019 * noop the transmission of the rsp and call the lsrsp->done() routine 1020 * to allow the lsrsp structure to be released. 1021 */ 1022 int nvmet_fc_rcv_ls_req(struct nvmet_fc_target_port *tgtport, 1023 void *hosthandle, 1024 struct nvmefc_ls_rsp *rsp, 1025 void *lsreqbuf, u32 lsreqbuf_len); 1026 1027 /* 1028 * Routine called by the LLDD whenever it has a logout or loss of 1029 * connectivity to a NVME-FC host port which there had been active 1030 * NVMe controllers for. The host port is indicated by the 1031 * hosthandle. The hosthandle is given to the nvmet-fc transport 1032 * when a NVME LS was received, typically to create a new association. 1033 * The nvmet-fc transport will cache the hostport value with the 1034 * association for use in LS requests for the association. 1035 * When the LLDD calls this routine, the nvmet-fc transport will 1036 * immediately terminate all associations that were created with 1037 * the hosthandle host port. 1038 * The LLDD, after calling this routine and having control returned, 1039 * must assume the transport may subsequently utilize hosthandle as 1040 * part of sending LS's to terminate the association. The LLDD 1041 * should reject the LS's if they are attempted. 1042 * Once the last association has terminated for the hosthandle host 1043 * port, the nvmet-fc transport will call the ops->host_release() 1044 * callback. As of the callback, the nvmet-fc transport will no 1045 * longer reference hosthandle. 1046 */ 1047 void nvmet_fc_invalidate_host(struct nvmet_fc_target_port *tgtport, 1048 void *hosthandle); 1049 1050 /* 1051 * If nvmet_fc_rcv_fcp_req returns non-zero, the transport has not accepted 1052 * the FCP cmd. The lldd should ABTS-LS the cmd. 1053 */ 1054 int nvmet_fc_rcv_fcp_req(struct nvmet_fc_target_port *tgtport, 1055 struct nvmefc_tgt_fcp_req *fcpreq, 1056 void *cmdiubuf, u32 cmdiubuf_len); 1057 1058 void nvmet_fc_rcv_fcp_abort(struct nvmet_fc_target_port *tgtport, 1059 struct nvmefc_tgt_fcp_req *fcpreq); 1060 /* 1061 * add a define, visible to the compiler, that indicates support 1062 * for feature. Allows for conditional compilation in LLDDs. 1063 */ 1064 #define NVME_FC_FEAT_UUID 0x0001 1065 1066 #endif /* _NVME_FC_DRIVER_H */ 1067