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