1071 lines · c
1/* SPDX-License-Identifier: GPL-2.0 */2/*3 * Copyright (c) 2016, Avago Technologies4 */5 6#ifndef _NVME_FC_DRIVER_H7#define _NVME_FC_DRIVER_H 18 9#include <linux/scatterlist.h>10#include <linux/blk-mq.h>11 12 13/*14 * ********************** FC-NVME LS API ********************15 *16 * Data structures used by both FC-NVME hosts and FC-NVME17 * targets to perform FC-NVME LS requests or transmit18 * responses.19 *20 * ***********************************************************21 */22 23/**24 * struct nvmefc_ls_req - Request structure passed from the transport25 * to the LLDD to perform a NVME-FC LS request and obtain26 * a response.27 * Used by nvme-fc transport (host) to send LS's such as28 * Create Association, Create Connection and Disconnect29 * Association.30 * Used by the nvmet-fc transport (controller) to send31 * LS's such as Disconnect Association.32 *33 * Values set by the requestor prior to calling the LLDD ls_req entrypoint:34 * @rqstaddr: pointer to request buffer35 * @rqstdma: PCI DMA address of request buffer36 * @rqstlen: Length, in bytes, of request buffer37 * @rspaddr: pointer to response buffer38 * @rspdma: PCI DMA address of response buffer39 * @rsplen: Length, in bytes, of response buffer40 * @timeout: Maximum amount of time, in seconds, to wait for the LS response.41 * If timeout exceeded, LLDD to abort LS exchange and complete42 * LS request with error status.43 * @private: pointer to memory allocated alongside the ls request structure44 * that is specifically for the LLDD to use while processing the45 * request. The length of the buffer corresponds to the46 * lsrqst_priv_sz value specified in the xxx_template supplied47 * by the LLDD.48 * @done: The callback routine the LLDD is to invoke upon completion of49 * the LS request. req argument is the pointer to the original LS50 * request structure. Status argument must be 0 upon success, a51 * negative errno on failure (example: -ENXIO).52 */53struct nvmefc_ls_req {54 void *rqstaddr;55 dma_addr_t rqstdma;56 u32 rqstlen;57 void *rspaddr;58 dma_addr_t rspdma;59 u32 rsplen;60 u32 timeout;61 62 void *private;63 64 void (*done)(struct nvmefc_ls_req *req, int status);65 66} __aligned(sizeof(u64)); /* alignment for other things alloc'd with */67 68 69/**70 * struct nvmefc_ls_rsp - Structure passed from the transport to the LLDD71 * to request the transmit the NVME-FC LS response to a72 * NVME-FC LS request. The structure originates in the LLDD73 * and is given to the transport via the xxx_rcv_ls_req()74 * transport routine. As such, the structure represents the75 * FC exchange context for the NVME-FC LS request that was76 * received and which the response is to be sent for.77 * Used by the LLDD to pass the nvmet-fc transport (controller)78 * received LS's such as Create Association, Create Connection79 * and Disconnect Association.80 * Used by the LLDD to pass the nvme-fc transport (host)81 * received LS's such as Disconnect Association or Disconnect82 * Connection.83 *84 * The structure is allocated by the LLDD whenever a LS Request is received85 * from the FC link. The address of the structure is passed to the nvmet-fc86 * or nvme-fc layer via the xxx_rcv_ls_req() transport routines.87 *88 * The address of the structure is to be passed back to the LLDD89 * when the response is to be transmit. The LLDD will use the address to90 * map back to the LLDD exchange structure which maintains information such91 * the remote N_Port that sent the LS as well as any FC exchange context.92 * Upon completion of the LS response transmit, the LLDD will pass the93 * address of the structure back to the transport LS rsp done() routine,94 * allowing the transport release dma resources. Upon completion of95 * the done() routine, no further access to the structure will be made by96 * the transport and the LLDD can de-allocate the structure.97 *98 * Field initialization:99 * At the time of the xxx_rcv_ls_req() call, there is no content that100 * is valid in the structure.101 *102 * When the structure is used for the LLDD->xmt_ls_rsp() call, the103 * transport layer will fully set the fields in order to specify the104 * response payload buffer and its length as well as the done routine105 * to be called upon completion of the transmit. The transport layer106 * will also set a private pointer for its own use in the done routine.107 *108 * Values set by the transport layer prior to calling the LLDD xmt_ls_rsp109 * entrypoint:110 * @rspbuf: pointer to the LS response buffer111 * @rspdma: PCI DMA address of the LS response buffer112 * @rsplen: Length, in bytes, of the LS response buffer113 * @done: The callback routine the LLDD is to invoke upon completion of114 * transmitting the LS response. req argument is the pointer to115 * the original ls request.116 * @nvme_fc_private: pointer to an internal transport-specific structure117 * used as part of the transport done() processing. The LLDD is118 * not to access this pointer.119 */120struct nvmefc_ls_rsp {121 void *rspbuf;122 dma_addr_t rspdma;123 u16 rsplen;124 125 void (*done)(struct nvmefc_ls_rsp *rsp);126 void *nvme_fc_private; /* LLDD is not to access !! */127};128 129 130 131/*132 * ********************** LLDD FC-NVME Host API ********************133 *134 * For FC LLDD's that are the NVME Host role.135 *136 * ******************************************************************137 */138 139 140/**141 * struct nvme_fc_port_info - port-specific ids and FC connection-specific142 * data element used during NVME Host role143 * registrations144 *145 * Static fields describing the port being registered:146 * @node_name: FC WWNN for the port147 * @port_name: FC WWPN for the port148 * @port_role: What NVME roles are supported (see FC_PORT_ROLE_xxx)149 * @dev_loss_tmo: maximum delay for reconnects to an association on150 * this device. Used only on a remoteport.151 *152 * Initialization values for dynamic port fields:153 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must154 * be set to 0.155 */156struct nvme_fc_port_info {157 u64 node_name;158 u64 port_name;159 u32 port_role;160 u32 port_id;161 u32 dev_loss_tmo;162};163 164enum nvmefc_fcp_datadir {165 NVMEFC_FCP_NODATA, /* payload_length and sg_cnt will be zero */166 NVMEFC_FCP_WRITE,167 NVMEFC_FCP_READ,168};169 170 171/**172 * struct nvmefc_fcp_req - Request structure passed from NVME-FC transport173 * to LLDD in order to perform a NVME FCP IO operation.174 *175 * Values set by the NVME-FC layer prior to calling the LLDD fcp_io176 * entrypoint.177 * @cmdaddr: pointer to the FCP CMD IU buffer178 * @rspaddr: pointer to the FCP RSP IU buffer179 * @cmddma: PCI DMA address of the FCP CMD IU buffer180 * @rspdma: PCI DMA address of the FCP RSP IU buffer181 * @cmdlen: Length, in bytes, of the FCP CMD IU buffer182 * @rsplen: Length, in bytes, of the FCP RSP IU buffer183 * @payload_length: Length of DATA_IN or DATA_OUT payload data to transfer184 * @sg_table: scatter/gather structure for payload data185 * @first_sgl: memory for 1st scatter/gather list segment for payload data186 * @sg_cnt: number of elements in the scatter/gather list187 * @io_dir: direction of the FCP request (see NVMEFC_FCP_xxx)188 * @done: The callback routine the LLDD is to invoke upon completion of189 * the FCP operation. req argument is the pointer to the original190 * FCP IO operation.191 * @private: pointer to memory allocated alongside the FCP operation192 * request structure that is specifically for the LLDD to use193 * while processing the operation. The length of the buffer194 * corresponds to the fcprqst_priv_sz value specified in the195 * nvme_fc_port_template supplied by the LLDD.196 * @sqid: The nvme SQID the command is being issued on197 *198 * Values set by the LLDD indicating completion status of the FCP operation.199 * Must be set prior to calling the done() callback.200 * @rcv_rsplen: length, in bytes, of the FCP RSP IU received.201 * @transferred_length: amount of payload data, in bytes, that were202 * transferred. Should equal payload_length on success.203 * @status: Completion status of the FCP operation. must be 0 upon success,204 * negative errno value upon failure (ex: -EIO). Note: this is205 * NOT a reflection of the NVME CQE completion status. Only the206 * status of the FCP operation at the NVME-FC level.207 */208struct nvmefc_fcp_req {209 void *cmdaddr;210 void *rspaddr;211 dma_addr_t cmddma;212 dma_addr_t rspdma;213 u16 cmdlen;214 u16 rsplen;215 216 u32 payload_length;217 struct sg_table sg_table;218 struct scatterlist *first_sgl;219 int sg_cnt;220 enum nvmefc_fcp_datadir io_dir;221 222 void (*done)(struct nvmefc_fcp_req *req);223 224 void *private;225 226 __le16 sqid;227 228 u16 rcv_rsplen;229 u32 transferred_length;230 u32 status;231} __aligned(sizeof(u64)); /* alignment for other things alloc'd with */232 233 234/*235 * Direct copy of fc_port_state enum. For later merging236 */237enum nvme_fc_obj_state {238 FC_OBJSTATE_UNKNOWN,239 FC_OBJSTATE_NOTPRESENT,240 FC_OBJSTATE_ONLINE,241 FC_OBJSTATE_OFFLINE, /* User has taken Port Offline */242 FC_OBJSTATE_BLOCKED,243 FC_OBJSTATE_BYPASSED,244 FC_OBJSTATE_DIAGNOSTICS,245 FC_OBJSTATE_LINKDOWN,246 FC_OBJSTATE_ERROR,247 FC_OBJSTATE_LOOPBACK,248 FC_OBJSTATE_DELETED,249};250 251 252/**253 * struct nvme_fc_local_port - structure used between NVME-FC transport and254 * a LLDD to reference a local NVME host port.255 * Allocated/created by the nvme_fc_register_localport()256 * transport interface.257 *258 * Fields with static values for the port. Initialized by the259 * port_info struct supplied to the registration call.260 * @port_num: NVME-FC transport host port number261 * @port_role: NVME roles are supported on the port (see FC_PORT_ROLE_xxx)262 * @node_name: FC WWNN for the port263 * @port_name: FC WWPN for the port264 * @private: pointer to memory allocated alongside the local port265 * structure that is specifically for the LLDD to use.266 * The length of the buffer corresponds to the local_priv_sz267 * value specified in the nvme_fc_port_template supplied by268 * the LLDD.269 * @dev_loss_tmo: maximum delay for reconnects to an association on270 * this device. To modify, lldd must call271 * nvme_fc_set_remoteport_devloss().272 *273 * Fields with dynamic values. Values may change base on link state. LLDD274 * may reference fields directly to change them. Initialized by the275 * port_info struct supplied to the registration call.276 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must277 * be set to 0.278 * @port_state: Operational state of the port.279 */280struct nvme_fc_local_port {281 /* static/read-only fields */282 u32 port_num;283 u32 port_role;284 u64 node_name;285 u64 port_name;286 287 void *private;288 289 /* dynamic fields */290 u32 port_id;291 enum nvme_fc_obj_state port_state;292} __aligned(sizeof(u64)); /* alignment for other things alloc'd with */293 294 295/**296 * struct nvme_fc_remote_port - structure used between NVME-FC transport and297 * a LLDD to reference a remote NVME subsystem port.298 * Allocated/created by the nvme_fc_register_remoteport()299 * transport interface.300 *301 * Fields with static values for the port. Initialized by the302 * port_info struct supplied to the registration call.303 * @port_num: NVME-FC transport remote subsystem port number304 * @port_role: NVME roles are supported on the port (see FC_PORT_ROLE_xxx)305 * @node_name: FC WWNN for the port306 * @port_name: FC WWPN for the port307 * @localport: pointer to the NVME-FC local host port the subsystem is308 * connected to.309 * @private: pointer to memory allocated alongside the remote port310 * structure that is specifically for the LLDD to use.311 * The length of the buffer corresponds to the remote_priv_sz312 * value specified in the nvme_fc_port_template supplied by313 * the LLDD.314 *315 * Fields with dynamic values. Values may change base on link or login316 * state. LLDD may reference fields directly to change them. Initialized by317 * the port_info struct supplied to the registration call.318 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must319 * be set to 0.320 * @port_state: Operational state of the remote port. Valid values are321 * ONLINE or UNKNOWN.322 */323struct nvme_fc_remote_port {324 /* static fields */325 u32 port_num;326 u32 port_role;327 u64 node_name;328 u64 port_name;329 struct nvme_fc_local_port *localport;330 void *private;331 u32 dev_loss_tmo;332 333 /* dynamic fields */334 u32 port_id;335 enum nvme_fc_obj_state port_state;336} __aligned(sizeof(u64)); /* alignment for other things alloc'd with */337 338 339/**340 * struct nvme_fc_port_template - structure containing static entrypoints and341 * operational parameters for an LLDD that supports NVME host342 * behavior. Passed by reference in port registrations.343 * NVME-FC transport remembers template reference and may344 * access it during runtime operation.345 *346 * Host/Initiator Transport Entrypoints/Parameters:347 *348 * @localport_delete: The LLDD initiates deletion of a localport via349 * nvme_fc_deregister_localport(). However, the teardown is350 * asynchronous. This routine is called upon the completion of the351 * teardown to inform the LLDD that the localport has been deleted.352 * Entrypoint is Mandatory.353 *354 * @remoteport_delete: The LLDD initiates deletion of a remoteport via355 * nvme_fc_deregister_remoteport(). However, the teardown is356 * asynchronous. This routine is called upon the completion of the357 * teardown to inform the LLDD that the remoteport has been deleted.358 * Entrypoint is Mandatory.359 *360 * @create_queue: Upon creating a host<->controller association, queues are361 * created such that they can be affinitized to cpus/cores. This362 * callback into the LLDD to notify that a controller queue is being363 * created. The LLDD may choose to allocate an associated hw queue364 * or map it onto a shared hw queue. Upon return from the call, the365 * LLDD specifies a handle that will be given back to it for any366 * command that is posted to the controller queue. The handle can367 * be used by the LLDD to map quickly to the proper hw queue for368 * command execution. The mask of cpu's that will map to this queue369 * at the block-level is also passed in. The LLDD should use the370 * queue id and/or cpu masks to ensure proper affinitization of the371 * controller queue to the hw queue.372 * Entrypoint is Optional.373 *374 * @delete_queue: This is the inverse of the crete_queue. During375 * host<->controller association teardown, this routine is called376 * when a controller queue is being terminated. Any association with377 * a hw queue should be termined. If there is a unique hw queue, the378 * hw queue should be torn down.379 * Entrypoint is Optional.380 *381 * @poll_queue: Called to poll for the completion of an io on a blk queue.382 * Entrypoint is Optional.383 *384 * @ls_req: Called to issue a FC-NVME FC-4 LS service request.385 * The nvme_fc_ls_req structure will fully describe the buffers for386 * the request payload and where to place the response payload. The387 * LLDD is to allocate an exchange, issue the LS request, obtain the388 * LS response, and call the "done" routine specified in the request389 * structure (argument to done is the ls request structure itself).390 * Entrypoint is Mandatory.391 *392 * @fcp_io: called to issue a FC-NVME I/O request. The I/O may be for393 * an admin queue or an i/o queue. The nvmefc_fcp_req structure will394 * fully describe the io: the buffer containing the FC-NVME CMD IU395 * (which contains the SQE), the sg list for the payload if applicable,396 * and the buffer to place the FC-NVME RSP IU into. The LLDD will397 * complete the i/o, indicating the amount of data transferred or398 * any transport error, and call the "done" routine specified in the399 * request structure (argument to done is the fcp request structure400 * itself).401 * Entrypoint is Mandatory.402 *403 * @ls_abort: called to request the LLDD to abort the indicated ls request.404 * The call may return before the abort has completed. After aborting405 * the request, the LLDD must still call the ls request done routine406 * indicating an FC transport Aborted status.407 * Entrypoint is Mandatory.408 *409 * @fcp_abort: called to request the LLDD to abort the indicated fcp request.410 * The call may return before the abort has completed. After aborting411 * the request, the LLDD must still call the fcp request done routine412 * indicating an FC transport Aborted status.413 * Entrypoint is Mandatory.414 *415 * @xmt_ls_rsp: Called to transmit the response to a FC-NVME FC-4 LS service.416 * The nvmefc_ls_rsp structure is the same LLDD-supplied exchange417 * structure specified in the nvme_fc_rcv_ls_req() call made when418 * the LS request was received. The structure will fully describe419 * the buffers for the response payload and the dma address of the420 * payload. The LLDD is to transmit the response (or return a421 * non-zero errno status), and upon completion of the transmit, call422 * the "done" routine specified in the nvmefc_ls_rsp structure423 * (argument to done is the address of the nvmefc_ls_rsp structure424 * itself). Upon the completion of the done routine, the LLDD shall425 * consider the LS handling complete and the nvmefc_ls_rsp structure426 * may be freed/released.427 * Entrypoint is mandatory if the LLDD calls the nvme_fc_rcv_ls_req()428 * entrypoint.429 *430 * @max_hw_queues: indicates the maximum number of hw queues the LLDD431 * supports for cpu affinitization.432 * Value is Mandatory. Must be at least 1.433 *434 * @max_sgl_segments: indicates the maximum number of sgl segments supported435 * by the LLDD436 * Value is Mandatory. Must be at least 1. Recommend at least 256.437 *438 * @max_dif_sgl_segments: indicates the maximum number of sgl segments439 * supported by the LLDD for DIF operations.440 * Value is Mandatory. Must be at least 1. Recommend at least 256.441 *442 * @dma_boundary: indicates the dma address boundary where dma mappings443 * will be split across.444 * Value is Mandatory. Typical value is 0xFFFFFFFF to split across445 * 4Gig address boundarys446 *447 * @local_priv_sz: The LLDD sets this field to the amount of additional448 * memory that it would like fc nvme layer to allocate on the LLDD's449 * behalf whenever a localport is allocated. The additional memory450 * area solely for the of the LLDD and its location is specified by451 * the localport->private pointer.452 * Value is Mandatory. Allowed to be zero.453 *454 * @remote_priv_sz: The LLDD sets this field to the amount of additional455 * memory that it would like fc nvme layer to allocate on the LLDD's456 * behalf whenever a remoteport is allocated. The additional memory457 * area solely for the of the LLDD and its location is specified by458 * the remoteport->private pointer.459 * Value is Mandatory. Allowed to be zero.460 *461 * @lsrqst_priv_sz: The LLDD sets this field to the amount of additional462 * memory that it would like fc nvme layer to allocate on the LLDD's463 * behalf whenever a ls request structure is allocated. The additional464 * memory area is solely for use by the LLDD and its location is465 * specified by the ls_request->private pointer.466 * Value is Mandatory. Allowed to be zero.467 *468 * @fcprqst_priv_sz: The LLDD sets this field to the amount of additional469 * memory that it would like fc nvme layer to allocate on the LLDD's470 * behalf whenever a fcp request structure is allocated. The additional471 * memory area solely for the of the LLDD and its location is472 * specified by the fcp_request->private pointer.473 * Value is Mandatory. Allowed to be zero.474 */475struct nvme_fc_port_template {476 /* initiator-based functions */477 void (*localport_delete)(struct nvme_fc_local_port *);478 void (*remoteport_delete)(struct nvme_fc_remote_port *);479 int (*create_queue)(struct nvme_fc_local_port *,480 unsigned int qidx, u16 qsize,481 void **handle);482 void (*delete_queue)(struct nvme_fc_local_port *,483 unsigned int qidx, void *handle);484 int (*ls_req)(struct nvme_fc_local_port *,485 struct nvme_fc_remote_port *,486 struct nvmefc_ls_req *);487 int (*fcp_io)(struct nvme_fc_local_port *,488 struct nvme_fc_remote_port *,489 void *hw_queue_handle,490 struct nvmefc_fcp_req *);491 void (*ls_abort)(struct nvme_fc_local_port *,492 struct nvme_fc_remote_port *,493 struct nvmefc_ls_req *);494 void (*fcp_abort)(struct nvme_fc_local_port *,495 struct nvme_fc_remote_port *,496 void *hw_queue_handle,497 struct nvmefc_fcp_req *);498 int (*xmt_ls_rsp)(struct nvme_fc_local_port *localport,499 struct nvme_fc_remote_port *rport,500 struct nvmefc_ls_rsp *ls_rsp);501 void (*map_queues)(struct nvme_fc_local_port *localport,502 struct blk_mq_queue_map *map);503 504 u32 max_hw_queues;505 u16 max_sgl_segments;506 u16 max_dif_sgl_segments;507 u64 dma_boundary;508 509 /* sizes of additional private data for data structures */510 u32 local_priv_sz;511 u32 remote_priv_sz;512 u32 lsrqst_priv_sz;513 u32 fcprqst_priv_sz;514};515 516 517/*518 * Initiator/Host functions519 */520 521int nvme_fc_register_localport(struct nvme_fc_port_info *pinfo,522 struct nvme_fc_port_template *template,523 struct device *dev,524 struct nvme_fc_local_port **lport_p);525 526int nvme_fc_unregister_localport(struct nvme_fc_local_port *localport);527 528int nvme_fc_register_remoteport(struct nvme_fc_local_port *localport,529 struct nvme_fc_port_info *pinfo,530 struct nvme_fc_remote_port **rport_p);531 532int nvme_fc_unregister_remoteport(struct nvme_fc_remote_port *remoteport);533 534void nvme_fc_rescan_remoteport(struct nvme_fc_remote_port *remoteport);535 536int nvme_fc_set_remoteport_devloss(struct nvme_fc_remote_port *remoteport,537 u32 dev_loss_tmo);538 539/*540 * Routine called to pass a NVME-FC LS request, received by the lldd,541 * to the nvme-fc transport.542 *543 * If the return value is zero: the LS was successfully accepted by the544 * transport.545 * If the return value is non-zero: the transport has not accepted the546 * LS. The lldd should ABTS-LS the LS.547 *548 * Note: if the LLDD receives and ABTS for the LS prior to the transport549 * calling the ops->xmt_ls_rsp() routine to transmit a response, the LLDD550 * shall mark the LS as aborted, and when the xmt_ls_rsp() is called: the551 * response shall not be transmit and the struct nvmefc_ls_rsp() done552 * routine shall be called. The LLDD may transmit the ABTS response as553 * soon as the LS was marked or can delay until the xmt_ls_rsp() call is554 * made.555 * Note: if an RCV LS was successfully posted to the transport and the556 * remoteport is then unregistered before xmt_ls_rsp() was called for557 * the lsrsp structure, the transport will still call xmt_ls_rsp()558 * afterward to cleanup the outstanding lsrsp structure. The LLDD should559 * noop the transmission of the rsp and call the lsrsp->done() routine560 * to allow the lsrsp structure to be released.561 */562int nvme_fc_rcv_ls_req(struct nvme_fc_remote_port *remoteport,563 struct nvmefc_ls_rsp *lsrsp,564 void *lsreqbuf, u32 lsreqbuf_len);565 566 567/*568 * Routine called to get the appid field associated with request by the lldd569 *570 * If the return value is NULL : the user/libvirt has not set the appid to VM571 * If the return value is non-zero: Returns the appid associated with VM572 *573 * @req: IO request from nvme fc to driver574 */575char *nvme_fc_io_getuuid(struct nvmefc_fcp_req *req);576 577/*578 * *************** LLDD FC-NVME Target/Subsystem API ***************579 *580 * For FC LLDD's that are the NVME Subsystem role581 *582 * ******************************************************************583 */584 585/**586 * struct nvmet_fc_port_info - port-specific ids and FC connection-specific587 * data element used during NVME Subsystem role588 * registrations589 *590 * Static fields describing the port being registered:591 * @node_name: FC WWNN for the port592 * @port_name: FC WWPN for the port593 *594 * Initialization values for dynamic port fields:595 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must596 * be set to 0.597 */598struct nvmet_fc_port_info {599 u64 node_name;600 u64 port_name;601 u32 port_id;602};603 604 605/* Operations that NVME-FC layer may request the LLDD to perform for FCP */606enum {607 NVMET_FCOP_READDATA = 1, /* xmt data to initiator */608 NVMET_FCOP_WRITEDATA = 2, /* xmt data from initiator */609 NVMET_FCOP_READDATA_RSP = 3, /* xmt data to initiator and send610 * rsp as well611 */612 NVMET_FCOP_RSP = 4, /* send rsp frame */613};614 615/**616 * struct nvmefc_tgt_fcp_req - Structure used between LLDD and NVMET-FC617 * layer to represent the exchange context and618 * the specific FC-NVME IU operation(s) to perform619 * for a FC-NVME FCP IO.620 *621 * Structure used between LLDD and nvmet-fc layer to represent the exchange622 * context for a FC-NVME FCP I/O operation (e.g. a nvme sqe, the sqe-related623 * memory transfers, and its associated cqe transfer).624 *625 * The structure is allocated by the LLDD whenever a FCP CMD IU is received626 * from the FC link. The address of the structure is passed to the nvmet-fc627 * layer via the nvmet_fc_rcv_fcp_req() call. The address of the structure628 * will be passed back to the LLDD for the data operations and transmit of629 * the response. The LLDD is to use the address to map back to the LLDD630 * exchange structure which maintains information such as the targetport631 * the FCP I/O was received on, the remote FC NVME initiator that sent the632 * FCP I/O, and any FC exchange context. Upon completion of the FCP target633 * operation, the address of the structure will be passed back to the FCP634 * op done() routine, allowing the nvmet-fc layer to release dma resources.635 * Upon completion of the done() routine for either RSP or ABORT ops, no636 * further access will be made by the nvmet-fc layer and the LLDD can637 * de-allocate the structure.638 *639 * Field initialization:640 * At the time of the nvmet_fc_rcv_fcp_req() call, there is no content that641 * is valid in the structure.642 *643 * When the structure is used for an FCP target operation, the nvmet-fc644 * layer will fully set the fields in order to specify the scattergather645 * list, the transfer length, as well as the done routine to be called646 * upon compeletion of the operation. The nvmet-fc layer will also set a647 * private pointer for its own use in the done routine.648 *649 * Values set by the NVMET-FC layer prior to calling the LLDD fcp_op650 * entrypoint.651 * @op: Indicates the FCP IU operation to perform (see NVMET_FCOP_xxx)652 * @hwqid: Specifies the hw queue index (0..N-1, where N is the653 * max_hw_queues value from the LLD's nvmet_fc_target_template)654 * that the operation is to use.655 * @offset: Indicates the DATA_OUT/DATA_IN payload offset to be tranferred.656 * Field is only valid on WRITEDATA, READDATA, or READDATA_RSP ops.657 * @timeout: amount of time, in seconds, to wait for a response from the NVME658 * host. A value of 0 is an infinite wait.659 * Valid only for the following ops:660 * WRITEDATA: caps the wait for data reception661 * READDATA_RSP & RSP: caps wait for FCP_CONF reception (if used)662 * @transfer_length: the length, in bytes, of the DATA_OUT or DATA_IN payload663 * that is to be transferred.664 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops.665 * @ba_rjt: Contains the BA_RJT payload that is to be transferred.666 * Valid only for the NVMET_FCOP_BA_RJT op.667 * @sg: Scatter/gather list for the DATA_OUT/DATA_IN payload data.668 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops.669 * @sg_cnt: Number of valid entries in the scatter/gather list.670 * Valid only for the WRITEDATA, READDATA, or READDATA_RSP ops.671 * @rspaddr: pointer to the FCP RSP IU buffer to be transmit672 * Used by RSP and READDATA_RSP ops673 * @rspdma: PCI DMA address of the FCP RSP IU buffer674 * Used by RSP and READDATA_RSP ops675 * @rsplen: Length, in bytes, of the FCP RSP IU buffer676 * Used by RSP and READDATA_RSP ops677 * @done: The callback routine the LLDD is to invoke upon completion of678 * the operation. req argument is the pointer to the original679 * FCP subsystem op request.680 * @nvmet_fc_private: pointer to an internal NVMET-FC layer structure used681 * as part of the NVMET-FC processing. The LLDD is not to682 * reference this field.683 *684 * Values set by the LLDD indicating completion status of the FCP operation.685 * Must be set prior to calling the done() callback.686 * @transferred_length: amount of DATA_OUT payload data received by a687 * WRITEDATA operation. If not a WRITEDATA operation, value must688 * be set to 0. Should equal transfer_length on success.689 * @fcp_error: status of the FCP operation. Must be 0 on success; on failure690 * must be a NVME_SC_FC_xxxx value.691 */692struct nvmefc_tgt_fcp_req {693 u8 op;694 u16 hwqid;695 u32 offset;696 u32 timeout;697 u32 transfer_length;698 struct fc_ba_rjt ba_rjt;699 struct scatterlist *sg;700 int sg_cnt;701 void *rspaddr;702 dma_addr_t rspdma;703 u16 rsplen;704 705 void (*done)(struct nvmefc_tgt_fcp_req *);706 707 void *nvmet_fc_private; /* LLDD is not to access !! */708 709 u32 transferred_length;710 int fcp_error;711};712 713 714/* Target Features (Bit fields) LLDD supports */715enum {716 NVMET_FCTGTFEAT_READDATA_RSP = (1 << 0),717 /* Bit 0: supports the NVMET_FCPOP_READDATA_RSP op, which718 * sends (the last) Read Data sequence followed by the RSP719 * sequence in one LLDD operation. Errors during Data720 * sequence transmit must not allow RSP sequence to be sent.721 */722};723 724 725/**726 * struct nvmet_fc_target_port - structure used between NVME-FC transport and727 * a LLDD to reference a local NVME subsystem port.728 * Allocated/created by the nvme_fc_register_targetport()729 * transport interface.730 *731 * Fields with static values for the port. Initialized by the732 * port_info struct supplied to the registration call.733 * @port_num: NVME-FC transport subsystem port number734 * @node_name: FC WWNN for the port735 * @port_name: FC WWPN for the port736 * @private: pointer to memory allocated alongside the local port737 * structure that is specifically for the LLDD to use.738 * The length of the buffer corresponds to the target_priv_sz739 * value specified in the nvme_fc_target_template supplied by740 * the LLDD.741 *742 * Fields with dynamic values. Values may change base on link state. LLDD743 * may reference fields directly to change them. Initialized by the744 * port_info struct supplied to the registration call.745 * @port_id: FC N_Port_ID currently assigned the port. Upper 8 bits must746 * be set to 0.747 * @port_state: Operational state of the port.748 */749struct nvmet_fc_target_port {750 /* static/read-only fields */751 u32 port_num;752 u64 node_name;753 u64 port_name;754 755 void *private;756 757 /* dynamic fields */758 u32 port_id;759 enum nvme_fc_obj_state port_state;760} __aligned(sizeof(u64)); /* alignment for other things alloc'd with */761 762 763/**764 * struct nvmet_fc_target_template - structure containing static entrypoints765 * and operational parameters for an LLDD that supports NVME766 * subsystem behavior. Passed by reference in port767 * registrations. NVME-FC transport remembers template768 * reference and may access it during runtime operation.769 *770 * Subsystem/Target Transport Entrypoints/Parameters:771 *772 * @targetport_delete: The LLDD initiates deletion of a targetport via773 * nvmet_fc_unregister_targetport(). However, the teardown is774 * asynchronous. This routine is called upon the completion of the775 * teardown to inform the LLDD that the targetport has been deleted.776 * Entrypoint is Mandatory.777 *778 * @xmt_ls_rsp: Called to transmit the response to a FC-NVME FC-4 LS service.779 * The nvmefc_ls_rsp structure is the same LLDD-supplied exchange780 * structure specified in the nvmet_fc_rcv_ls_req() call made when781 * the LS request was received. The structure will fully describe782 * the buffers for the response payload and the dma address of the783 * payload. The LLDD is to transmit the response (or return a784 * non-zero errno status), and upon completion of the transmit, call785 * the "done" routine specified in the nvmefc_ls_rsp structure786 * (argument to done is the address of the nvmefc_ls_rsp structure787 * itself). Upon the completion of the done() routine, the LLDD shall788 * consider the LS handling complete and the nvmefc_ls_rsp structure789 * may be freed/released.790 * The transport will always call the xmt_ls_rsp() routine for any791 * LS received.792 * Entrypoint is Mandatory.793 *794 * @map_queues: This functions lets the driver expose the queue mapping795 * to the block layer.796 * Entrypoint is Optional.797 *798 * @fcp_op: Called to perform a data transfer or transmit a response.799 * The nvmefc_tgt_fcp_req structure is the same LLDD-supplied800 * exchange structure specified in the nvmet_fc_rcv_fcp_req() call801 * made when the FCP CMD IU was received. The op field in the802 * structure shall indicate the operation for the LLDD to perform803 * relative to the io.804 * NVMET_FCOP_READDATA operation: the LLDD is to send the805 * payload data (described by sglist) to the host in 1 or806 * more FC sequences (preferrably 1). Note: the fc-nvme layer807 * may call the READDATA operation multiple times for longer808 * payloads.809 * NVMET_FCOP_WRITEDATA operation: the LLDD is to receive the810 * payload data (described by sglist) from the host via 1 or811 * more FC sequences (preferrably 1). The LLDD is to generate812 * the XFER_RDY IU(s) corresponding to the data being requested.813 * Note: the FC-NVME layer may call the WRITEDATA operation814 * multiple times for longer payloads.815 * NVMET_FCOP_READDATA_RSP operation: the LLDD is to send the816 * payload data (described by sglist) to the host in 1 or817 * more FC sequences (preferrably 1). If an error occurs during818 * payload data transmission, the LLDD is to set the819 * nvmefc_tgt_fcp_req fcp_error and transferred_length field, then820 * consider the operation complete. On error, the LLDD is to not821 * transmit the FCP_RSP iu. If all payload data is transferred822 * successfully, the LLDD is to update the nvmefc_tgt_fcp_req823 * transferred_length field and may subsequently transmit the824 * FCP_RSP iu payload (described by rspbuf, rspdma, rsplen).825 * If FCP_CONF is supported, the LLDD is to await FCP_CONF826 * reception to confirm the RSP reception by the host. The LLDD827 * may retramsit the FCP_RSP iu if necessary per FC-NVME. Upon828 * transmission of the FCP_RSP iu if FCP_CONF is not supported,829 * or upon success/failure of FCP_CONF if it is supported, the830 * LLDD is to set the nvmefc_tgt_fcp_req fcp_error field and831 * consider the operation complete.832 * NVMET_FCOP_RSP: the LLDD is to transmit the FCP_RSP iu payload833 * (described by rspbuf, rspdma, rsplen). If FCP_CONF is834 * supported, the LLDD is to await FCP_CONF reception to confirm835 * the RSP reception by the host. The LLDD may retramsit the836 * FCP_RSP iu if FCP_CONF is not received per FC-NVME. Upon837 * transmission of the FCP_RSP iu if FCP_CONF is not supported,838 * or upon success/failure of FCP_CONF if it is supported, the839 * LLDD is to set the nvmefc_tgt_fcp_req fcp_error field and840 * consider the operation complete.841 * Upon completing the indicated operation, the LLDD is to set the842 * status fields for the operation (tranferred_length and fcp_error843 * status) in the request, then call the "done" routine844 * indicated in the fcp request. After the operation completes,845 * regardless of whether the FCP_RSP iu was successfully transmit,846 * the LLDD-supplied exchange structure must remain valid until the847 * transport calls the fcp_req_release() callback to return ownership848 * of the exchange structure back to the LLDD so that it may be used849 * for another fcp command.850 * Note: when calling the done routine for READDATA or WRITEDATA851 * operations, the fc-nvme layer may immediate convert, in the same852 * thread and before returning to the LLDD, the fcp operation to853 * the next operation for the fcp io and call the LLDDs fcp_op854 * call again. If fields in the fcp request are to be accessed post855 * the done call, the LLDD should save their values prior to calling856 * the done routine, and inspect the save values after the done857 * routine.858 * Returns 0 on success, -<errno> on failure (Ex: -EIO)859 * Entrypoint is Mandatory.860 *861 * @fcp_abort: Called by the transport to abort an active command.862 * The command may be in-between operations (nothing active in LLDD)863 * or may have an active WRITEDATA operation pending. The LLDD is to864 * initiate the ABTS process for the command and return from the865 * callback. The ABTS does not need to be complete on the command.866 * The fcp_abort callback inherently cannot fail. After the867 * fcp_abort() callback completes, the transport will wait for any868 * outstanding operation (if there was one) to complete, then will869 * call the fcp_req_release() callback to return the command's870 * exchange context back to the LLDD.871 * Entrypoint is Mandatory.872 *873 * @fcp_req_release: Called by the transport to return a nvmefc_tgt_fcp_req874 * to the LLDD after all operations on the fcp operation are complete.875 * This may be due to the command completing or upon completion of876 * abort cleanup.877 * Entrypoint is Mandatory.878 *879 * @defer_rcv: Called by the transport to signal the LLLD that it has880 * begun processing of a previously received NVME CMD IU. The LLDD881 * is now free to re-use the rcv buffer associated with the882 * nvmefc_tgt_fcp_req.883 * Entrypoint is Optional.884 *885 * @discovery_event: Called by the transport to generate an RSCN886 * change notifications to NVME initiators. The RSCN notifications887 * should cause the initiator to rescan the discovery controller888 * on the targetport.889 *890 * @ls_req: Called to issue a FC-NVME FC-4 LS service request.891 * The nvme_fc_ls_req structure will fully describe the buffers for892 * the request payload and where to place the response payload.893 * The targetport that is to issue the LS request is identified by894 * the targetport argument. The remote port that is to receive the895 * LS request is identified by the hosthandle argument. The nvmet-fc896 * transport is only allowed to issue FC-NVME LS's on behalf of an897 * association that was created prior by a Create Association LS.898 * The hosthandle will originate from the LLDD in the struct899 * nvmefc_ls_rsp structure for the Create Association LS that900 * was delivered to the transport. The transport will save the901 * hosthandle as an attribute of the association. If the LLDD902 * loses connectivity with the remote port, it must call the903 * nvmet_fc_invalidate_host() routine to remove any references to904 * the remote port in the transport.905 * The LLDD is to allocate an exchange, issue the LS request, obtain906 * the LS response, and call the "done" routine specified in the907 * request structure (argument to done is the ls request structure908 * itself).909 * Entrypoint is Optional - but highly recommended.910 *911 * @ls_abort: called to request the LLDD to abort the indicated ls request.912 * The call may return before the abort has completed. After aborting913 * the request, the LLDD must still call the ls request done routine914 * indicating an FC transport Aborted status.915 * Entrypoint is Mandatory if the ls_req entry point is specified.916 *917 * @host_release: called to inform the LLDD that the request to invalidate918 * the host port indicated by the hosthandle has been fully completed.919 * No associations exist with the host port and there will be no920 * further references to hosthandle.921 * Entrypoint is Mandatory if the lldd calls nvmet_fc_invalidate_host().922 *923 * @host_traddr: called by the transport to retrieve the node name and924 * port name of the host port address.925 *926 * @max_hw_queues: indicates the maximum number of hw queues the LLDD927 * supports for cpu affinitization.928 * Value is Mandatory. Must be at least 1.929 *930 * @max_sgl_segments: indicates the maximum number of sgl segments supported931 * by the LLDD932 * Value is Mandatory. Must be at least 1. Recommend at least 256.933 *934 * @max_dif_sgl_segments: indicates the maximum number of sgl segments935 * supported by the LLDD for DIF operations.936 * Value is Mandatory. Must be at least 1. Recommend at least 256.937 *938 * @dma_boundary: indicates the dma address boundary where dma mappings939 * will be split across.940 * Value is Mandatory. Typical value is 0xFFFFFFFF to split across941 * 4Gig address boundarys942 *943 * @target_features: The LLDD sets bits in this field to correspond to944 * optional features that are supported by the LLDD.945 * Refer to the NVMET_FCTGTFEAT_xxx values.946 * Value is Mandatory. Allowed to be zero.947 *948 * @target_priv_sz: The LLDD sets this field to the amount of additional949 * memory that it would like fc nvme layer to allocate on the LLDD's950 * behalf whenever a targetport is allocated. The additional memory951 * area solely for the of the LLDD and its location is specified by952 * the targetport->private pointer.953 * Value is Mandatory. Allowed to be zero.954 *955 * @lsrqst_priv_sz: The LLDD sets this field to the amount of additional956 * memory that it would like nvmet-fc layer to allocate on the LLDD's957 * behalf whenever a ls request structure is allocated. The additional958 * memory area is solely for use by the LLDD and its location is959 * specified by the ls_request->private pointer.960 * Value is Mandatory. Allowed to be zero.961 *962 */963struct nvmet_fc_target_template {964 void (*targetport_delete)(struct nvmet_fc_target_port *tgtport);965 int (*xmt_ls_rsp)(struct nvmet_fc_target_port *tgtport,966 struct nvmefc_ls_rsp *ls_rsp);967 int (*fcp_op)(struct nvmet_fc_target_port *tgtport,968 struct nvmefc_tgt_fcp_req *fcpreq);969 void (*fcp_abort)(struct nvmet_fc_target_port *tgtport,970 struct nvmefc_tgt_fcp_req *fcpreq);971 void (*fcp_req_release)(struct nvmet_fc_target_port *tgtport,972 struct nvmefc_tgt_fcp_req *fcpreq);973 void (*defer_rcv)(struct nvmet_fc_target_port *tgtport,974 struct nvmefc_tgt_fcp_req *fcpreq);975 void (*discovery_event)(struct nvmet_fc_target_port *tgtport);976 int (*ls_req)(struct nvmet_fc_target_port *targetport,977 void *hosthandle, struct nvmefc_ls_req *lsreq);978 void (*ls_abort)(struct nvmet_fc_target_port *targetport,979 void *hosthandle, struct nvmefc_ls_req *lsreq);980 void (*host_release)(void *hosthandle);981 int (*host_traddr)(void *hosthandle, u64 *wwnn, u64 *wwpn);982 983 u32 max_hw_queues;984 u16 max_sgl_segments;985 u16 max_dif_sgl_segments;986 u64 dma_boundary;987 988 u32 target_features;989 990 /* sizes of additional private data for data structures */991 u32 target_priv_sz;992 u32 lsrqst_priv_sz;993};994 995 996int nvmet_fc_register_targetport(struct nvmet_fc_port_info *portinfo,997 struct nvmet_fc_target_template *template,998 struct device *dev,999 struct nvmet_fc_target_port **tgtport_p);1000 1001int nvmet_fc_unregister_targetport(struct nvmet_fc_target_port *tgtport);1002 1003/*1004 * Routine called to pass a NVME-FC LS request, received by the lldd,1005 * to the nvmet-fc transport.1006 *1007 * If the return value is zero: the LS was successfully accepted by the1008 * transport.1009 * If the return value is non-zero: the transport has not accepted the1010 * LS. The lldd should ABTS-LS the LS.1011 *1012 * Note: if the LLDD receives and ABTS for the LS prior to the transport1013 * calling the ops->xmt_ls_rsp() routine to transmit a response, the LLDD1014 * shall mark the LS as aborted, and when the xmt_ls_rsp() is called: the1015 * response shall not be transmit and the struct nvmefc_ls_rsp() done1016 * routine shall be called. The LLDD may transmit the ABTS response as1017 * soon as the LS was marked or can delay until the xmt_ls_rsp() call is1018 * made.1019 * Note: if an RCV LS was successfully posted to the transport and the1020 * targetport is then unregistered before xmt_ls_rsp() was called for1021 * the lsrsp structure, the transport will still call xmt_ls_rsp()1022 * afterward to cleanup the outstanding lsrsp structure. The LLDD should1023 * noop the transmission of the rsp and call the lsrsp->done() routine1024 * to allow the lsrsp structure to be released.1025 */1026int nvmet_fc_rcv_ls_req(struct nvmet_fc_target_port *tgtport,1027 void *hosthandle,1028 struct nvmefc_ls_rsp *rsp,1029 void *lsreqbuf, u32 lsreqbuf_len);1030 1031/*1032 * Routine called by the LLDD whenever it has a logout or loss of1033 * connectivity to a NVME-FC host port which there had been active1034 * NVMe controllers for. The host port is indicated by the1035 * hosthandle. The hosthandle is given to the nvmet-fc transport1036 * when a NVME LS was received, typically to create a new association.1037 * The nvmet-fc transport will cache the hostport value with the1038 * association for use in LS requests for the association.1039 * When the LLDD calls this routine, the nvmet-fc transport will1040 * immediately terminate all associations that were created with1041 * the hosthandle host port.1042 * The LLDD, after calling this routine and having control returned,1043 * must assume the transport may subsequently utilize hosthandle as1044 * part of sending LS's to terminate the association. The LLDD1045 * should reject the LS's if they are attempted.1046 * Once the last association has terminated for the hosthandle host1047 * port, the nvmet-fc transport will call the ops->host_release()1048 * callback. As of the callback, the nvmet-fc transport will no1049 * longer reference hosthandle.1050 */1051void nvmet_fc_invalidate_host(struct nvmet_fc_target_port *tgtport,1052 void *hosthandle);1053 1054/*1055 * If nvmet_fc_rcv_fcp_req returns non-zero, the transport has not accepted1056 * the FCP cmd. The lldd should ABTS-LS the cmd.1057 */1058int nvmet_fc_rcv_fcp_req(struct nvmet_fc_target_port *tgtport,1059 struct nvmefc_tgt_fcp_req *fcpreq,1060 void *cmdiubuf, u32 cmdiubuf_len);1061 1062void nvmet_fc_rcv_fcp_abort(struct nvmet_fc_target_port *tgtport,1063 struct nvmefc_tgt_fcp_req *fcpreq);1064/*1065 * add a define, visible to the compiler, that indicates support1066 * for feature. Allows for conditional compilation in LLDDs.1067 */1068#define NVME_FC_FEAT_UUID 0x00011069 1070#endif /* _NVME_FC_DRIVER_H */1071