Debian Codegraph @

doc/rst/fabrics.rst

raw
1 .. _fabrics.h:
2
3 **fabrics.h**
4
5
6 Fabrics-specific definitions.
7
8
9
10 .. c:type:: struct nvme_fabrics_config
11
12 Defines all linux nvme fabrics initiator options
13
14 **Definition**
15
16 ::
17
18 struct nvme_fabrics_config {
19 char *host_traddr;
20 char *host_iface;
21 int queue_size;
22 int nr_io_queues;
23 int reconnect_delay;
24 int ctrl_loss_tmo;
25 int fast_io_fail_tmo;
26 int keep_alive_tmo;
27 int nr_write_queues;
28 int nr_poll_queues;
29 int tos;
30 long keyring;
31 long tls_key;
32 long tls_configured_key;
33 bool duplicate_connect;
34 bool disable_sqflow;
35 bool hdr_digest;
36 bool data_digest;
37 bool tls;
38 bool concat;
39 };
40
41 **Members**
42
43 ``host_traddr``
44 Host transport address
45
46 ``host_iface``
47 Host interface name
48
49 ``queue_size``
50 Number of IO queue entries
51
52 ``nr_io_queues``
53 Number of controller IO queues to establish
54
55 ``reconnect_delay``
56 Time between two consecutive reconnect attempts.
57
58 ``ctrl_loss_tmo``
59 Override the default controller reconnect attempt timeout in seconds
60
61 ``fast_io_fail_tmo``
62 Set the fast I/O fail timeout in seconds.
63
64 ``keep_alive_tmo``
65 Override the default keep-alive-timeout to this value in seconds
66
67 ``nr_write_queues``
68 Number of queues to use for exclusively for writing
69
70 ``nr_poll_queues``
71 Number of queues to reserve for polling completions
72
73 ``tos``
74 Type of service
75
76 ``keyring``
77 Keyring to store and lookup keys
78
79 ``tls_key``
80 TLS PSK for the connection
81
82 ``tls_configured_key``
83 TLS PSK for connect command for the connection
84
85 ``duplicate_connect``
86 Allow multiple connections to the same target
87
88 ``disable_sqflow``
89 Disable controller sq flow control
90
91 ``hdr_digest``
92 Generate/verify header digest (TCP)
93
94 ``data_digest``
95 Generate/verify data digest (TCP)
96
97 ``tls``
98 Start TLS on the connection (TCP)
99
100 ``concat``
101 Enable secure concatenation (TCP)
102
103
104
105
106
107 .. c:type:: struct nvme_fabrics_uri
108
109 Parsed URI structure
110
111 **Definition**
112
113 ::
114
115 struct nvme_fabrics_uri {
116 char *scheme;
117 char *protocol;
118 char *userinfo;
119 char *host;
120 int port;
121 char **path_segments;
122 char *query;
123 char *fragment;
124 };
125
126 **Members**
127
128 ``scheme``
129 Scheme name (typically 'nvme')
130
131 ``protocol``
132 Optional protocol/transport (e.g. 'tcp')
133
134 ``userinfo``
135 Optional user information component of the URI authority
136
137 ``host``
138 Host transport address
139
140 ``port``
141 The port subcomponent or 0 if not specified
142
143 ``path_segments``
144 NULL-terminated array of path segments
145
146 ``query``
147 Optional query string component (separated by '?')
148
149 ``fragment``
150 Optional fragment identifier component (separated by '#')
151
152
153
154 .. c:function:: const char * nvmf_trtype_str (__u8 trtype)
155
156 Decode TRTYPE field
157
158 **Parameters**
159
160 ``__u8 trtype``
161 value to be decoded
162
163 **Description**
164
165 Decode the transport type field in the discovery
166 log page entry.
167
168 **Return**
169
170 decoded string
171
172
173 .. c:function:: const char * nvmf_adrfam_str (__u8 adrfam)
174
175 Decode ADRFAM field
176
177 **Parameters**
178
179 ``__u8 adrfam``
180 value to be decoded
181
182 **Description**
183
184 Decode the address family field in the discovery
185 log page entry.
186
187 **Return**
188
189 decoded string
190
191
192 .. c:function:: const char * nvmf_subtype_str (__u8 subtype)
193
194 Decode SUBTYPE field
195
196 **Parameters**
197
198 ``__u8 subtype``
199 value to be decoded
200
201 **Description**
202
203 Decode the subsystem type field in the discovery
204 log page entry.
205
206 **Return**
207
208 decoded string
209
210
211 .. c:function:: const char * nvmf_treq_str (__u8 treq)
212
213 Decode TREQ field
214
215 **Parameters**
216
217 ``__u8 treq``
218 value to be decoded
219
220 **Description**
221
222 Decode the transport requirements field in the
223 discovery log page entry.
224
225 **Return**
226
227 decoded string
228
229
230 .. c:function:: const char * nvmf_eflags_str (__u16 eflags)
231
232 Decode EFLAGS field
233
234 **Parameters**
235
236 ``__u16 eflags``
237 value to be decoded
238
239 **Description**
240
241 Decode the EFLAGS field in the discovery log page
242 entry.
243
244 **Return**
245
246 decoded string
247
248
249 .. c:function:: const char * nvmf_sectype_str (__u8 sectype)
250
251 Decode SECTYPE field
252
253 **Parameters**
254
255 ``__u8 sectype``
256 value to be decoded
257
258 **Description**
259
260 Decode the SECTYPE field in the discovery log page
261 entry.
262
263 **Return**
264
265 decoded string
266
267
268 .. c:function:: const char * nvmf_prtype_str (__u8 prtype)
269
270 Decode RDMA Provider type field
271
272 **Parameters**
273
274 ``__u8 prtype``
275 value to be decoded
276
277 **Description**
278
279 Decode the RDMA Provider type field in the discovery
280 log page entry.
281
282 **Return**
283
284 decoded string
285
286
287 .. c:function:: const char * nvmf_qptype_str (__u8 qptype)
288
289 Decode RDMA QP Service type field
290
291 **Parameters**
292
293 ``__u8 qptype``
294 value to be decoded
295
296 **Description**
297
298 Decode the RDMA QP Service type field in the discovery log page
299 entry.
300
301 **Return**
302
303 decoded string
304
305
306 .. c:function:: const char * nvmf_cms_str (__u8 cms)
307
308 Decode RDMA connection management service field
309
310 **Parameters**
311
312 ``__u8 cms``
313 value to be decoded
314
315 **Description**
316
317 Decode the RDMA connection management service field in the discovery
318 log page entry.
319
320 **Return**
321
322 decoded string
323
324
325 .. c:function:: void nvmf_default_config (struct nvme_fabrics_config *cfg)
326
327 Default values for fabrics configuration
328
329 **Parameters**
330
331 ``struct nvme_fabrics_config *cfg``
332 config values to set
333
334 **Description**
335
336 Initializes **cfg** with default values.
337
338
339 .. c:function:: void nvmf_update_config (nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)
340
341 Update fabrics configuration values
342
343 **Parameters**
344
345 ``nvme_ctrl_t c``
346 Controller to be modified
347
348 ``const struct nvme_fabrics_config *cfg``
349 Updated configuration values
350
351 **Description**
352
353 Updates the values from **c** with the configuration values from **cfg**;
354 all non-default values from **cfg** will overwrite the values in **c**.
355
356
357 .. c:function:: int nvmf_add_ctrl (nvme_host_t h, nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)
358
359 Connect a controller and update topology
360
361 **Parameters**
362
363 ``nvme_host_t h``
364 Host to which the controller should be attached
365
366 ``nvme_ctrl_t c``
367 Controller to be connected
368
369 ``const struct nvme_fabrics_config *cfg``
370 Default configuration for the controller
371
372 **Description**
373
374 Issues a 'connect' command to the NVMe-oF controller and inserts **c**
375 into the topology using **h** as parent.
376 **c** must be initialized and not connected to the topology.
377
378 **Return**
379
380 0 on success; on failure errno is set and -1 is returned.
381
382
383 .. c:function:: int nvmf_connect_ctrl (nvme_ctrl_t c)
384
385 Connect a controller
386
387 **Parameters**
388
389 ``nvme_ctrl_t c``
390 Controller to be connected
391
392 **Description**
393
394 Issues a 'connect' command to the NVMe-oF controller.
395 **c** must be initialized and not connected to the topology.
396
397 **Return**
398
399 0 on success; on failure errno is set and -1 is returned.
400
401
402 .. c:function:: int nvmf_get_discovery_log (nvme_ctrl_t c, struct nvmf_discovery_log **logp, int max_retries)
403
404 Return the discovery log page
405
406 **Parameters**
407
408 ``nvme_ctrl_t c``
409 Discovery controller to use
410
411 ``struct nvmf_discovery_log **logp``
412 Pointer to the log page to be returned
413
414 ``int max_retries``
415 Number of retries in case of failure
416
417 **Description**
418
419 The memory allocated for the log page and returned in **logp**
420 must be freed by the caller using free().
421
422 **Note**
423
424 Consider using nvmf_get_discovery_wargs() instead.
425
426 **Return**
427
428 0 on success; on failure -1 is returned and errno is set
429
430
431
432
433 .. c:type:: struct nvme_get_discovery_args
434
435 Arguments for nvmf_get_discovery_wargs()
436
437 **Definition**
438
439 ::
440
441 struct nvme_get_discovery_args {
442 nvme_ctrl_t c;
443 int args_size;
444 int max_retries;
445 __u32 *result;
446 __u32 timeout;
447 __u8 lsp;
448 };
449
450 **Members**
451
452 ``c``
453 Discovery controller
454
455 ``args_size``
456 Length of the structure
457
458 ``max_retries``
459 Number of retries in case of failure
460
461 ``result``
462 The command completion result from CQE dword0
463
464 ``timeout``
465 Timeout in ms (default: NVME_DEFAULT_IOCTL_TIMEOUT)
466
467 ``lsp``
468 Log specific field (See enum nvmf_log_discovery_lsp)
469
470
471
472 .. c:function:: struct nvmf_discovery_log * nvmf_get_discovery_wargs (struct nvme_get_discovery_args *args)
473
474 Get the discovery log page with args
475
476 **Parameters**
477
478 ``struct nvme_get_discovery_args *args``
479 Argument structure
480
481 **Description**
482
483 This function is similar to nvmf_get_discovery_log(), but
484 takes an extensible **args** parameter. **args** provides more
485 options than nvmf_get_discovery_log().
486
487 This function performs a get discovery log page (DLP) command
488 and returns the DLP. The memory allocated for the returned
489 DLP must be freed by the caller using free().
490
491 **Return**
492
493 Pointer to the discovery log page (to be freed). NULL
494 on failure and errno is set.
495
496
497 .. c:function:: char * nvmf_hostnqn_generate ()
498
499 Generate a machine specific host nqn
500
501 **Parameters**
502
503 **Return**
504
505 An nvm namespace qualified name string based on the machine
506 identifier, or NULL if not successful.
507
508
509 .. c:function:: char * nvmf_hostnqn_generate_from_hostid (char *hostid)
510
511 Generate a host nqn from host identifier
512
513 **Parameters**
514
515 ``char *hostid``
516 Host identifier
517
518 **Description**
519
520 If **hostid** is NULL, the function generates it based on the machine
521 identifier.
522
523 **Return**
524
525 On success, an NVMe Qualified Name for host identification. This
526 name is based on the given host identifier. On failure, NULL.
527
528
529 .. c:function:: char * nvmf_hostid_generate ()
530
531 Generate a machine specific host identifier
532
533 **Parameters**
534
535 **Return**
536
537 On success, an identifier string based on the machine identifier to
538 be used as NVMe Host Identifier, or NULL on failure.
539
540
541 .. c:function:: char * nvmf_hostnqn_from_file ()
542
543 Reads the host nvm qualified name from the config default location
544
545 **Parameters**
546
547 **Description**
548
549
550 Retrieve the qualified name from the config file located in $SYSCONFIDR/nvme.
551 $SYSCONFDIR is usually /etc.
552
553 **Return**
554
555 The host nqn, or NULL if unsuccessful. If found, the caller
556 is responsible to free the string.
557
558
559 .. c:function:: char * nvmf_hostid_from_file ()
560
561 Reads the host identifier from the config default location
562
563 **Parameters**
564
565 **Description**
566
567
568 Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/.
569 $SYSCONFDIR is usually /etc.
570
571 **Return**
572
573 The host identifier, or NULL if unsuccessful. If found, the caller
574 is responsible to free the string.
575
576
577 .. c:function:: nvme_ctrl_t nvmf_connect_disc_entry (nvme_host_t h, struct nvmf_disc_log_entry *e, const struct nvme_fabrics_config *defcfg, bool *discover)
578
579 Connect controller based on the discovery log page entry
580
581 **Parameters**
582
583 ``nvme_host_t h``
584 Host to which the controller should be connected
585
586 ``struct nvmf_disc_log_entry *e``
587 Discovery log page entry
588
589 ``const struct nvme_fabrics_config *defcfg``
590 Default configuration to be used for the new controller
591
592 ``bool *discover``
593 Set to 'true' if the new controller is a discovery controller
594
595 **Return**
596
597 Pointer to the new controller
598
599
600 .. c:function:: bool nvmf_is_registration_supported (nvme_ctrl_t c)
601
602 check whether registration can be performed.
603
604 **Parameters**
605
606 ``nvme_ctrl_t c``
607 Controller instance
608
609 **Description**
610
611 Only discovery controllers (DC) that comply with TP8010 support
612 explicit registration with the DIM PDU. These can be identified by
613 looking at the value of a dctype in the Identify command
614 response. A value of 1 (DDC) or 2 (CDC) indicates that the DC
615 supports explicit registration.
616
617 **Return**
618
619 true if controller supports explicit registration. false
620 otherwise.
621
622
623 .. c:function:: int nvmf_register_ctrl (nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result)
624
625 Perform registration task with a DC
626
627 **Parameters**
628
629 ``nvme_ctrl_t c``
630 Controller instance
631
632 ``enum nvmf_dim_tas tas``
633 Task field of the Command Dword 10 (cdw10). Indicates whether to
634 perform a Registration, Deregistration, or Registration-update.
635
636 ``__u32 *result``
637 The command-specific result returned by the DC upon command
638 completion.
639
640 **Description**
641
642 Perform registration task with a Discovery Controller (DC). Three
643 tasks are supported: register, deregister, and registration update.
644
645 **Return**
646
647 0 on success; on failure -1 is returned and errno is set
648
649
650 .. c:function:: struct nvme_fabrics_uri * nvme_parse_uri (const char *str)
651
652 Parse the URI string
653
654 **Parameters**
655
656 ``const char *str``
657 URI string
658
659 **Description**
660
661 Parse the URI string as defined in the NVM Express Boot Specification.
662 Supported URI elements looks as follows:
663
664 nvme+tcp://user**host**:port/subsys_nqn/nid?query=val#fragment
665
666 **Return**
667
668 :c:type:`nvme_fabrics_uri` structure on success; NULL on failure with errno
669 set.
670
671
672 .. c:function:: void nvme_free_uri (struct nvme_fabrics_uri *uri)
673
674 Free the URI structure
675
676 **Parameters**
677
678 ``struct nvme_fabrics_uri *uri``
679 :c:type:`nvme_fabrics_uri` structure
680
681 **Description**
682
683 Free an :c:type:`nvme_fabrics_uri` structure.
684
685