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