include/linux/nvme-fc-driver.h

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