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