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