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