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