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