include/linux/nvme-fc-driver.h

   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        0x11
  31 #define FC_PORT_ROLE_NVME_DISCOVERY     0x12
  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  *             NVME_SC_FC_xxx value upon failure. Note: this is NOT a
 141  *             reflection of the NVME CQE completion status. Only the status
 142  *             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  * @max_hw_queues:  indicates the maximum number of hw queues the LLDD
 350  *       supports for cpu affinitization.
 351  *       Value is Mandatory. Must be at least 1.
 352  *
 353  * @max_sgl_segments:  indicates the maximum number of sgl segments supported
 354  *       by the LLDD
 355  *       Value is Mandatory. Must be at least 1. Recommend at least 256.
 356  *
 357  * @max_dif_sgl_segments:  indicates the maximum number of sgl segments
 358  *       supported by the LLDD for DIF operations.
 359  *       Value is Mandatory. Must be at least 1. Recommend at least 256.
 360  *
 361  * @dma_boundary:  indicates the dma address boundary where dma mappings
 362  *       will be split across.
 363  *       Value is Mandatory. Typical value is 0xFFFFFFFF to split across
 364  *       4Gig address boundarys
 365  *
 366  * @local_priv_sz: The LLDD sets this field to the amount of additional
 367  *       memory that it would like fc nvme layer to allocate on the LLDD's
 368  *       behalf whenever a localport is allocated.  The additional memory
 369  *       area solely for the of the LLDD and its location is specified by
 370  *       the localport->private pointer.
 371  *       Value is Mandatory. Allowed to be zero.
 372  *
 373  * @remote_priv_sz: The LLDD sets this field to the amount of additional
 374  *       memory that it would like fc nvme layer to allocate on the LLDD's
 375  *       behalf whenever a remoteport is allocated.  The additional memory
 376  *       area solely for the of the LLDD and its location is specified by
 377  *       the remoteport->private pointer.
 378  *       Value is Mandatory. Allowed to be zero.
 379  *
 380  * @lsrqst_priv_sz: The LLDD sets this field to the amount of additional
 381  *       memory that it would like fc nvme layer to allocate on the LLDD's
 382  *       behalf whenever a ls request structure is allocated. The additional
 383  *       memory area solely for the of the LLDD and its location is
 384  *       specified by the ls_request->private pointer.
 385  *       Value is Mandatory. Allowed to be zero.
 386  *
 387  * @fcprqst_priv_sz: The LLDD sets this field to the amount of additional
 388  *       memory that it would like fc nvme layer to allocate on the LLDD's
 389  *       behalf whenever a fcp request structure is allocated. The additional
 390  *       memory area solely for the of the LLDD and its location is
 391  *       specified by the fcp_request->private pointer.
 392  *       Value is Mandatory. Allowed to be zero.
 393  */
 394 struct nvme_fc_port_template {
 395         /* initiator-based functions */
 396         void    (*localport_delete)(struct nvme_fc_local_port *);
 397         void    (*remoteport_delete)(struct nvme_fc_remote_port *);
 398         int     (*create_queue)(struct nvme_fc_local_port *,
 399                                 unsigned int qidx, u16 qsize,
 400                                 void **handle);
 401         void    (*delete_queue)(struct nvme_fc_local_port *,
 402                                 unsigned int qidx, void *handle);
 403         void    (*poll_queue)(struct nvme_fc_local_port *, void *handle);
 404         int     (*ls_req)(struct nvme_fc_local_port *,
 405                                 struct nvme_fc_remote_port *,
 406                                 struct nvmefc_ls_req *);
 407         int     (*fcp_io)(struct nvme_fc_local_port *,
 408                                 struct nvme_fc_remote_port *,
 409                                 void *hw_queue_handle,
 410                                 struct nvmefc_fcp_req *);
 411         void    (*ls_abort)(struct nvme_fc_local_port *,
 412                                 struct nvme_fc_remote_port *,
 413                                 struct nvmefc_ls_req *);
 414         void    (*fcp_abort)(struct nvme_fc_local_port *,
 415                                 struct nvme_fc_remote_port *,
 416                                 void *hw_queue_handle,
 417                                 struct nvmefc_fcp_req *);
 418
 419         u32     max_hw_queues;
 420         u16     max_sgl_segments;
 421         u16     max_dif_sgl_segments;
 422         u64     dma_boundary;
 423
 424         /* sizes of additional private data for data structures */
 425         u32     local_priv_sz;
 426         u32     remote_priv_sz;
 427         u32     lsrqst_priv_sz;
 428         u32     fcprqst_priv_sz;
 429 };
 430
 431
 432 /*
 433  * Initiator/Host functions
 434  */
 435
 436 int nvme_fc_register_localport(struct nvme_fc_port_info *pinfo,
 437                         struct nvme_fc_port_template *template,
 438                         struct device *dev,
 439                         struct nvme_fc_local_port **lport_p);
 440
 441 int nvme_fc_unregister_localport(struct nvme_fc_local_port *localport);
 442
 443 int nvme_fc_register_remoteport(struct nvme_fc_local_port *localport,
 444                         struct nvme_fc_port_info *pinfo,
 445                         struct nvme_fc_remote_port **rport_p);
 446
 447 int nvme_fc_unregister_remoteport(struct nvme_fc_remote_port *remoteport);
 448
 449
 450
 451 /*
 452  * ***************  LLDD FC-NVME Target/Subsystem API ***************
 453  *
 454  *  For FC LLDD's that are the NVME Subsystem role
 455  *
 456  * ******************************************************************
 457  */
 458
 459 /**
 460  * struct nvmet_fc_port_info - port-specific ids and FC connection-specific
 461  *                             data element used during NVME Subsystem role
 462  *                             registrations
 463  *
 464  * Static fields describing the port being registered:
 465  * @node_name: FC WWNN for the port
 466  * @port_name: FC WWPN for the port
 467  *
 468  * Initialization values for dynamic port fields:
 469  * @port_id:      FC N_Port_ID currently assigned the port. Upper 8 bits must
 470  *                be set to 0.
 471  */
 472 struct nvmet_fc_port_info {
 473         u64                     node_name;
 474         u64                     port_name;
 475         u32                     port_id;
 476 };
 477
 478
 479 /**
 480  * struct nvmefc_tgt_ls_req - Structure used between LLDD and NVMET-FC
 481  *                            layer to represent the exchange context for
 482  *                            a FC-NVME Link Service (LS).
 483  *
 484  * The structure is allocated by the LLDD whenever a LS Request is received
 485  * from the FC link. The address of the structure is passed to the nvmet-fc
 486  * layer via the nvmet_fc_rcv_ls_req() call. The address of the structure
 487  * will be passed back to the LLDD when the response is to be transmit.
 488  * The LLDD is to use the address to map back to the LLDD exchange structure
 489  * which maintains information such as the targetport the LS was received
 490  * on, the remote FC NVME initiator that sent the LS, and any FC exchange
 491  * context.  Upon completion of the LS response transmit, the address of the
 492  * structure will be passed back to the LS rsp done() routine, allowing the
 493  * nvmet-fc layer to release dma resources. Upon completion of the done()
 494  * routine, no further access will be made by the nvmet-fc layer and the
 495  * LLDD can de-allocate the structure.
 496  *
 497  * Field initialization:
 498  *   At the time of the nvmet_fc_rcv_ls_req() call, there is no content that
 499  *     is valid in the structure.
 500  *
 501  *   When the structure is used for the LLDD->xmt_ls_rsp() call, the nvmet-fc
 502  *     layer will fully set the fields in order to specify the response
 503  *     payload buffer and its length as well as the done routine to be called
 504  *     upon compeletion of the transmit.  The nvmet-fc layer will also set a
 505  *     private pointer for its own use in the done routine.
 506  *
 507  * Values set by the NVMET-FC layer prior to calling the LLDD xmt_ls_rsp
 508  * entrypoint.
 509  * @rspbuf:   pointer to the LS response buffer
 510  * @rspdma:   PCI DMA address of the LS response buffer
 511  * @rsplen:   Length, in bytes, of the LS response buffer
 512  * @done:     The callback routine the LLDD is to invoke upon completion of
 513  *            transmitting the LS response. req argument is the pointer to
 514  *            the original ls request.
 515  * @nvmet_fc_private:  pointer to an internal NVMET-FC layer structure used
 516  *            as part of the NVMET-FC processing. The LLDD is not to access
 517  *            this pointer.
 518  */
 519 struct nvmefc_tgt_ls_req {
 520         void            *rspbuf;
 521         dma_addr_t      rspdma;
 522         u16             rsplen;
 523
 524         void (*done)(struct nvmefc_tgt_ls_req *req);
 525         void *nvmet_fc_private;         /* LLDD is not to access !! */
 526 };
 527
 528 /* Operations that NVME-FC layer may request the LLDD to perform for FCP */
 529 enum {
 530         NVMET_FCOP_READDATA     = 1,    /* xmt data to initiator */
 531         NVMET_FCOP_WRITEDATA    = 2,    /* xmt data from initiator */
 532         NVMET_FCOP_READDATA_RSP = 3,    /* xmt data to initiator and send
 533                                          * rsp as well
 534                                          */
 535         NVMET_FCOP_RSP          = 4,    /* send rsp frame */
 536         NVMET_FCOP_ABORT        = 5,    /* abort exchange via ABTS */
 537         NVMET_FCOP_BA_ACC       = 6,    /* send BA_ACC */
 538         NVMET_FCOP_BA_RJT       = 7,    /* send BA_RJT */
 539 };
 540
 541 /**
 542  * struct nvmefc_tgt_fcp_req - Structure used between LLDD and NVMET-FC
 543  *                            layer to represent the exchange context and
 544  *                            the specific FC-NVME IU operation(s) to perform
 545  *                            for a FC-NVME FCP IO.
 546  *
 547  * Structure used between LLDD and nvmet-fc layer to represent the exchange
 548  * context for a FC-NVME FCP I/O operation (e.g. a nvme sqe, the sqe-related
 549  * memory transfers, and its assocated cqe transfer).
 550  *
 551  * The structure is allocated by the LLDD whenever a FCP CMD IU is received
 552  * from the FC link. The address of the structure is passed to the nvmet-fc
 553  * layer via the nvmet_fc_rcv_fcp_req() call. The address of the structure
 554  * will be passed back to the LLDD for the data operations and transmit of
 555  * the response. The LLDD is to use the address to map back to the LLDD
 556  * exchange structure which maintains information such as the targetport
 557  * the FCP I/O was received on, the remote FC NVME initiator that sent the
 558  * FCP I/O, and any FC exchange context.  Upon completion of the FCP target
 559  * operation, the address of the structure will be passed back to the FCP
 560  * op done() routine, allowing the nvmet-fc layer to release dma resources.
 561  * Upon completion of the done() routine for either RSP or ABORT ops, no
 562  * further access will be made by the nvmet-fc layer and the LLDD can
 563  * de-allocate the structure.
 564  *
 565  * Field initialization:
 566  *   At the time of the nvmet_fc_rcv_fcp_req() call, there is no content that
 567  *     is valid in the structure.
 568  *
 569  *   When the structure is used for an FCP target operation, the nvmet-fc
 570  *     layer will fully set the fields in order to specify the scattergather
 571  *     list, the transfer length, as well as the done routine to be called
 572  *     upon compeletion of the operation.  The nvmet-fc layer will also set a
 573  *     private pointer for its own use in the done routine.
 574  *
 575  * Note: the LLDD must never fail a NVMET_FCOP_ABORT request !!
 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[NVME_FC_MAX_SEGMENTS];
 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_NEEDS_CMD_CPUSCHED = (1 << 1),
 651                 /* Bit 1: When 0, the LLDD will deliver FCP CMD
 652                  * on the CPU it should be affinitized to. Thus work will
 653                  * be scheduled on the cpu received on. When 1, the LLDD
 654                  * may not deliver the CMD on the CPU it should be worked
 655                  * on. The transport should pick a cpu to schedule the work
 656                  * on.
 657                  */
 658 };
 659
 660
 661 /**
 662  * struct nvmet_fc_target_port - structure used between NVME-FC transport and
 663  *                 a LLDD to reference a local NVME subsystem port.
 664  *                 Allocated/created by the nvme_fc_register_targetport()
 665  *                 transport interface.
 666  *
 667  * Fields with static values for the port. Initialized by the
 668  * port_info struct supplied to the registration call.
 669  * @port_num:  NVME-FC transport subsytem port number
 670  * @node_name: FC WWNN for the port
 671  * @port_name: FC WWPN for the port
 672  * @private:   pointer to memory allocated alongside the local port
 673  *             structure that is specifically for the LLDD to use.
 674  *             The length of the buffer corresponds to the target_priv_sz
 675  *             value specified in the nvme_fc_target_template supplied by
 676  *             the LLDD.
 677  *
 678  * Fields with dynamic values. Values may change base on link state. LLDD
 679  * may reference fields directly to change them. Initialized by the
 680  * port_info struct supplied to the registration call.
 681  * @port_id:      FC N_Port_ID currently assigned the port. Upper 8 bits must
 682  *                be set to 0.
 683  * @port_state:   Operational state of the port.
 684  */
 685 struct nvmet_fc_target_port {
 686         /* static/read-only fields */
 687         u32 port_num;
 688         u64 node_name;
 689         u64 port_name;
 690
 691         void *private;
 692
 693         /* dynamic fields */
 694         u32 port_id;
 695         enum nvme_fc_obj_state port_state;
 696 } __aligned(sizeof(u64));       /* alignment for other things alloc'd with */
 697
 698
 699 /**
 700  * struct nvmet_fc_target_template - structure containing static entrypoints
 701  *                 and operational parameters for an LLDD that supports NVME
 702  *                 subsystem behavior. Passed by reference in port
 703  *                 registrations. NVME-FC transport remembers template
 704  *                 reference and may access it during runtime operation.
 705  *
 706  * Subsystem/Target Transport Entrypoints/Parameters:
 707  *
 708  * @targetport_delete:  The LLDD initiates deletion of a targetport via
 709  *       nvmet_fc_unregister_targetport(). However, the teardown is
 710  *       asynchronous. This routine is called upon the completion of the
 711  *       teardown to inform the LLDD that the targetport has been deleted.
 712  *       Entrypoint is Mandatory.
 713  *
 714  * @xmt_ls_rsp:  Called to transmit the response to a FC-NVME FC-4 LS service.
 715  *       The nvmefc_tgt_ls_req structure is the same LLDD-supplied exchange
 716  *       structure specified in the nvmet_fc_rcv_ls_req() call made when
 717  *       the LS request was received.  The structure will fully describe
 718  *       the buffers for the response payload and the dma address of the
 719  *       payload. The LLDD is to transmit the response (or return a non-zero
 720  *       errno status), and upon completion of the transmit, call the
 721  *       "done" routine specified in the nvmefc_tgt_ls_req structure
 722  *       (argument to done is the ls reqwuest structure itself).
 723  *       After calling the done routine, the LLDD shall consider the
 724  *       LS handling complete and the nvmefc_tgt_ls_req structure may
 725  *       be freed/released.
 726  *       Entrypoint is Mandatory.
 727  *
 728  * @fcp_op:  Called to perform a data transfer, transmit a response, or
 729  *       abort an FCP opertion. The nvmefc_tgt_fcp_req structure is the same
 730  *       LLDD-supplied exchange structure specified in the
 731  *       nvmet_fc_rcv_fcp_req() call made when the FCP CMD IU was received.
 732  *       The op field in the structure shall indicate the operation for
 733  *       the LLDD to perform relative to the io.
 734  *         NVMET_FCOP_READDATA operation: the LLDD is to send the
 735  *           payload data (described by sglist) to the host in 1 or
 736  *           more FC sequences (preferrably 1).  Note: the fc-nvme layer
 737  *           may call the READDATA operation multiple times for longer
 738  *           payloads.
 739  *         NVMET_FCOP_WRITEDATA operation: the LLDD is to receive the
 740  *           payload data (described by sglist) from the host via 1 or
 741  *           more FC sequences (preferrably 1). The LLDD is to generate
 742  *           the XFER_RDY IU(s) corresponding to the data being requested.
 743  *           Note: the FC-NVME layer may call the WRITEDATA operation
 744  *           multiple times for longer payloads.
 745  *         NVMET_FCOP_READDATA_RSP operation: the LLDD is to send the
 746  *           payload data (described by sglist) to the host in 1 or
 747  *           more FC sequences (preferrably 1). If an error occurs during
 748  *           payload data transmission, the LLDD is to set the
 749  *           nvmefc_tgt_fcp_req fcp_error and transferred_length field, then
 750  *           consider the operation complete. On error, the LLDD is to not
 751  *           transmit the FCP_RSP iu. If all payload data is transferred
 752  *           successfully, the LLDD is to update the nvmefc_tgt_fcp_req
 753  *           transferred_length field and may subsequently transmit the
 754  *           FCP_RSP iu payload (described by rspbuf, rspdma, rsplen).
 755  *           The LLDD is to await FCP_CONF reception to confirm the RSP
 756  *           reception by the host. The LLDD may retramsit the FCP_RSP iu
 757  *           if necessary per FC-NVME. Upon reception of FCP_CONF, or upon
 758  *           FCP_CONF failure, the LLDD is to set the nvmefc_tgt_fcp_req
 759  *           fcp_error field and consider the operation complete..
 760  *         NVMET_FCOP_RSP: the LLDD is to transmit the FCP_RSP iu payload
 761  *           (described by rspbuf, rspdma, rsplen).  The LLDD is to await
 762  *           FCP_CONF reception to confirm the RSP reception by the host.
 763  *           The LLDD may retramsit the FCP_RSP iu if necessary per FC-NVME.
 764  *           Upon reception of FCP_CONF, or upon FCP_CONF failure, the
 765  *           LLDD is to set the nvmefc_tgt_fcp_req fcp_error field and
 766  *           consider the operation complete..
 767  *         NVMET_FCOP_ABORT: the LLDD is to terminate the exchange
 768  *           corresponding to the fcp operation. The LLDD shall send
 769  *           ABTS and follow FC exchange abort-multi rules, including
 770  *           ABTS retries and possible logout.
 771  *       Upon completing the indicated operation, the LLDD is to set the
 772  *       status fields for the operation (tranferred_length and fcp_error
 773  *       status) in the request, then all the "done" routine
 774  *       indicated in the fcp request.  Upon return from the "done"
 775  *       routine for either a NVMET_FCOP_RSP or NVMET_FCOP_ABORT operation
 776  *       the fc-nvme layer will not longer reference the fcp request,
 777  *       allowing the LLDD to free/release the fcp request.
 778  *       Note: when calling the done routine for READDATA or WRITEDATA
 779  *       operations, the fc-nvme layer may immediate convert, in the same
 780  *       thread and before returning to the LLDD, the fcp operation to
 781  *       the next operation for the fcp io and call the LLDDs fcp_op
 782  *       call again. If fields in the fcp request are to be accessed post
 783  *       the done call, the LLDD should save their values prior to calling
 784  *       the done routine, and inspect the save values after the done
 785  *       routine.
 786  *       Returns 0 on success, -<errno> on failure (Ex: -EIO)
 787  *       Entrypoint is Mandatory.
 788  *
 789  * @max_hw_queues:  indicates the maximum number of hw queues the LLDD
 790  *       supports for cpu affinitization.
 791  *       Value is Mandatory. Must be at least 1.
 792  *
 793  * @max_sgl_segments:  indicates the maximum number of sgl segments supported
 794  *       by the LLDD
 795  *       Value is Mandatory. Must be at least 1. Recommend at least 256.
 796  *
 797  * @max_dif_sgl_segments:  indicates the maximum number of sgl segments
 798  *       supported by the LLDD for DIF operations.
 799  *       Value is Mandatory. Must be at least 1. Recommend at least 256.
 800  *
 801  * @dma_boundary:  indicates the dma address boundary where dma mappings
 802  *       will be split across.
 803  *       Value is Mandatory. Typical value is 0xFFFFFFFF to split across
 804  *       4Gig address boundarys
 805  *
 806  * @target_features: The LLDD sets bits in this field to correspond to
 807  *       optional features that are supported by the LLDD.
 808  *       Refer to the NVMET_FCTGTFEAT_xxx values.
 809  *       Value is Mandatory. Allowed to be zero.
 810  *
 811  * @target_priv_sz: The LLDD sets this field to the amount of additional
 812  *       memory that it would like fc nvme layer to allocate on the LLDD's
 813  *       behalf whenever a targetport is allocated.  The additional memory
 814  *       area solely for the of the LLDD and its location is specified by
 815  *       the targetport->private pointer.
 816  *       Value is Mandatory. Allowed to be zero.
 817  */
 818 struct nvmet_fc_target_template {
 819         void (*targetport_delete)(struct nvmet_fc_target_port *tgtport);
 820         int (*xmt_ls_rsp)(struct nvmet_fc_target_port *tgtport,
 821                                 struct nvmefc_tgt_ls_req *tls_req);
 822         int (*fcp_op)(struct nvmet_fc_target_port *tgtport,
 823                                 struct nvmefc_tgt_fcp_req *);
 824
 825         u32     max_hw_queues;
 826         u16     max_sgl_segments;
 827         u16     max_dif_sgl_segments;
 828         u64     dma_boundary;
 829
 830         u32     target_features;
 831
 832         u32     target_priv_sz;
 833 };
 834
 835
 836 int nvmet_fc_register_targetport(struct nvmet_fc_port_info *portinfo,
 837                         struct nvmet_fc_target_template *template,
 838                         struct device *dev,
 839                         struct nvmet_fc_target_port **tgtport_p);
 840
 841 int nvmet_fc_unregister_targetport(struct nvmet_fc_target_port *tgtport);
 842
 843 int nvmet_fc_rcv_ls_req(struct nvmet_fc_target_port *tgtport,
 844                         struct nvmefc_tgt_ls_req *lsreq,
 845                         void *lsreqbuf, u32 lsreqbuf_len);
 846
 847 int nvmet_fc_rcv_fcp_req(struct nvmet_fc_target_port *tgtport,
 848                         struct nvmefc_tgt_fcp_req *fcpreq,
 849                         void *cmdiubuf, u32 cmdiubuf_len);
 850
 851 #endif /* _NVME_FC_DRIVER_H */