~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/nvme-fc-driver.h

Version: ~ [ linux-5.4-rc3 ] ~ [ linux-5.3.6 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.79 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.149 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.196 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.196 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.75 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-3.9.11 ] ~ [ linux-3.8.13 ] ~ [ linux-3.7.10 ] ~ [ linux-3.6.11 ] ~ [ linux-3.5.7 ] ~ [ linux-3.4.113 ] ~ [ linux-3.3.8 ] ~ [ linux-3.2.102 ] ~ [ linux-3.1.10 ] ~ [ linux-3.0.101 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp