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

source code of linux/include/linux/nvme-fc-driver.h