Debian Codegraph @

doc/rst/nbft.rst

raw
1 .. _nbft.h:
2
3 **nbft.h**
4
5
6 NVM Express Boot Specification, Revision 1.0
7
8 Note: this API is currently unstable, subject to further additions.
9
10
11
12 .. c:type:: enum nbft_desc_type
13
14 NBFT Elements - Descriptor Types (Figure 5)
15
16 **Constants**
17
18 ``NBFT_DESC_HEADER``
19 Header: an ACPI structure header with some additional
20 NBFT specific info.
21
22 ``NBFT_DESC_CONTROL``
23 Control Descriptor: indicates the location of host,
24 HFI, SSNS, security, and discovery descriptors.
25
26 ``NBFT_DESC_HOST``
27 Host Descriptor: host information.
28
29 ``NBFT_DESC_HFI``
30 HFI Descriptor: an indexable table of HFI Descriptors,
31 one for each fabric interface on the host.
32
33 ``NBFT_DESC_SSNS``
34 Subsystem Namespace Descriptor: an indexable table
35 of SSNS Descriptors.
36
37 ``NBFT_DESC_SECURITY``
38 Security Descriptor: an indexable table of Security
39 descriptors.
40
41 ``NBFT_DESC_DISCOVERY``
42 Discovery Descriptor: an indexable table of Discovery
43 Descriptors.
44
45 ``NBFT_DESC_HFI_TRINFO``
46 HFI Transport Descriptor: indicated by an HFI Descriptor,
47 corresponds to a specific transport for a single HFI.
48
49 ``NBFT_DESC_RESERVED_8``
50 Reserved.
51
52 ``NBFT_DESC_SSNS_EXT_INFO``
53 SSNS Extended Info Descriptor: indicated by an SSNS
54 Descriptor if required.
55
56
57
58
59 .. c:type:: enum nbft_trtype
60
61 NBFT Interface Transport Types (Figure 7)
62
63 **Constants**
64
65 ``NBFT_TRTYPE_TCP``
66 NVMe/TCP (802.3 + TCP/IP). String Designator "tcp".
67
68
69
70
71 .. c:type:: struct nbft_heap_obj
72
73 NBFT Header Driver Signature
74
75 **Definition**
76
77 ::
78
79 struct nbft_heap_obj {
80 __le32 offset;
81 __le16 length;
82 };
83
84 **Members**
85
86 ``offset``
87 Offset in bytes of the heap object, if any, from byte offset 0h
88 of the NBFT Table Header.
89
90 ``length``
91 Length in bytes of the heap object, if any.
92
93
94
95
96
97 .. c:type:: struct nbft_header
98
99 NBFT Table - Header (Figure 8)
100
101 **Definition**
102
103 ::
104
105 struct nbft_header {
106 char signature[4];
107 __le32 length;
108 __u8 major_revision;
109 __u8 checksum;
110 char oem_id[6];
111 char oem_table_id[8];
112 __le32 oem_revision;
113 __le32 creator_id;
114 __le32 creator_revision;
115 __le32 heap_offset;
116 __le32 heap_length;
117 struct nbft_heap_obj driver_dev_path_sig;
118 __u8 minor_revision;
119 __u8 reserved[13];
120 };
121
122 **Members**
123
124 ``signature``
125 Signature: An ASCII string representation of the table
126 identifier. This field shall be set to the value 4E424654h
127 (i.e. "NBFT", see #NBFT_HEADER_SIG).
128
129 ``length``
130 Length: The length of the table, in bytes, including the
131 header, starting from offset 0h. This field is used to record
132 the size of the entire table.
133
134 ``major_revision``
135 Major Revision: The major revision of the structure
136 corresponding to the Signature field. Larger major revision
137 numbers should not be assumed backward compatible to lower
138 major revision numbers with the same signature.
139
140 ``checksum``
141 Checksum: The entire table, including the Checksum field,
142 shall sum to 0h to be considered valid.
143
144 ``oem_id``
145 OEMID shall be populated by the NBFT driver writer by
146 an OEM-supplied string that identifies the OEM. All
147 trailing bytes shall be NULL.
148
149 ``oem_table_id``
150 OEM Table ID: This field shall be populated by the NBFT
151 driver writer with an OEM-supplied string that the OEM
152 uses to identify the particular data table. This field is
153 particularly useful when defining a definition block to
154 distinguish definition block functions. The OEM assigns
155 each dissimilar table a new OEM Table ID.
156
157 ``oem_revision``
158 OEM Revision: An OEM-supplied revision number. Larger
159 numbers are assumed to be newer revisions.
160
161 ``creator_id``
162 Creator ID: Vendor ID of utility that created the table.
163 For instance, this may be the ID for the ASL Compiler.
164
165 ``creator_revision``
166 Creator Revision: Revision of utility that created the
167 table. For instance, this may be the ID for the ASL Compiler.
168
169 ``heap_offset``
170 Heap Offset (HO): This field indicates the offset in bytes
171 of the heap, if any, from byte offset 0h of the NBFT
172 Table Header.
173
174 ``heap_length``
175 Heap Length (HL): The length of the heap, if any.
176
177 ``driver_dev_path_sig``
178 Driver Signature Heap Object Reference: This field indicates
179 the offset in bytes of a heap object containing the Driver
180 Signature, if any, from byte offset 0h of the NBFT Table
181 Header.
182
183 ``minor_revision``
184 Minor Revision: The minor revision of the structure
185 corresponding to the Signature field. If the major revision
186 numbers are the same, any minor revision number differences
187 shall be backwards compatible with the same signature.
188
189 ``reserved``
190 Reserved.
191
192
193
194
195
196 .. c:type:: struct nbft_control
197
198 NBFT Table - Control Descriptor (Figure 8)
199
200 **Definition**
201
202 ::
203
204 struct nbft_control {
205 __u8 structure_id;
206 __u8 major_revision;
207 __u8 minor_revision;
208 __u8 reserved1;
209 __le16 csl;
210 __u8 flags;
211 __u8 reserved2;
212 struct nbft_heap_obj hdesc;
213 __u8 hsv;
214 __u8 reserved3;
215 __le32 hfio;
216 __le16 hfil;
217 __u8 hfiv;
218 __u8 num_hfi;
219 __le32 ssnso;
220 __le16 ssnsl;
221 __u8 ssnsv;
222 __u8 num_ssns;
223 __le32 seco;
224 __le16 secl;
225 __u8 secv;
226 __u8 num_sec;
227 __le32 disco;
228 __le16 discl;
229 __u8 discv;
230 __u8 num_disc;
231 __u8 reserved4[16];
232 };
233
234 **Members**
235
236 ``structure_id``
237 Structure ID: This field specifies the element (refer to
238 :c:type:`enum nbft_desc_type <nbft_desc_type>`). This field shall be set to 1h (i.e.,
239 Control, #NBFT_DESC_CONTROL).
240
241 ``major_revision``
242 Major Revision: The major revision of the structure corresponding
243 to the Signature field. Larger major revision numbers should
244 not be assumed backward compatible to lower major revision
245 numbers with the same signature.
246
247 ``minor_revision``
248 Minor Revision: The minor revision of the structure corresponding
249 to the signature field. If the major revision numbers are
250 the same, any minor revision number differences shall be backwards
251 compatible with the same signature.
252
253 ``reserved1``
254 Reserved.
255
256 ``csl``
257 Control Structure Length (CSL): This field indicates the length
258 in bytes of the Control Descriptor.
259
260 ``flags``
261 Flags, see :c:type:`enum nbft_control_flags <nbft_control_flags>`.
262
263 ``reserved2``
264 Reserved.
265
266 ``hdesc``
267 Host Descriptor (HDESC): This field indicates the location
268 and length of the Host Descriptor (see :c:type:`struct nbft_host <nbft_host>`).
269
270 ``hsv``
271 Host Descriptor Version (HSV): This field indicates the version
272 of the Host Descriptor.
273
274 ``reserved3``
275 Reserved.
276
277 ``hfio``
278 HFI Descriptor List Offset (HFIO): If this field is set to
279 a non-zero value, then this field indicates the offset in bytes
280 of the HFI Descriptor List, if any, from byte offset 0h of the
281 NBFT Table Header. If the **num_hfi** field is cleared to 0h,
282 then this field is reserved.
283
284 ``hfil``
285 HFI Descriptor Length (HFIL): This field indicates the length
286 in bytes of each HFI Descriptor, if any. If the **num_hfi** field
287 is cleared to 0h, then this field is reserved.
288
289 ``hfiv``
290 HFI Descriptor Version (HFIV): This field indicates the version
291 of each HFI Descriptor.
292
293 ``num_hfi``
294 Number of Host Fabric Interface Descriptors (NumHFI): This field
295 indicates the number of HFI Descriptors (see :c:type:`struct nbft_hfi <nbft_hfi>`)
296 in the HFI Descriptor List, if any. If no interfaces have been
297 configured, then this field shall be cleared to 0h.
298
299 ``ssnso``
300 SSNS Descriptor List Offset (SSNSO):: This field indicates
301 the offset in bytes of the SSNS Descriptor List, if any, from
302 byte offset 0h of the NBFT Table Header. If the **num_ssns** field
303 is cleared to 0h, then this field is reserved.
304
305 ``ssnsl``
306 SSNS Descriptor Length (SSNSL): This field indicates the length
307 in bytes of each SSNS Descriptor, if any. If the **num_ssns**
308 field is cleared to 0h, then this field is reserved.
309
310 ``ssnsv``
311 SSNS Descriptor Version (SSNSV): This field indicates the version
312 of the SSNS Descriptor.
313
314 ``num_ssns``
315 Number of Subsystem and Namespace Descriptors (NumSSNS): This
316 field indicates the number of Subsystem Namespace (SSNS)
317 Descriptors (see :c:type:`struct nbft_ssns <nbft_ssns>`) in the SSNS Descriptor List,
318 if any.
319
320 ``seco``
321 Security Profile Descriptor List Offset (SECO): This field
322 indicates the offset in bytes of the Security Profile Descriptor
323 List, if any, from byte offset 0h of the NBFT Table Header.
324 If the **num_sec** field is cleared to 0h, then this field
325 is reserved.
326
327 ``secl``
328 Security Profile Descriptor Length (SECL): This field indicates
329 the length in bytes of each Security Profile Descriptor, if any.
330 If the **num_sec** field is cleared to 0h, then this field
331 is reserved.
332
333 ``secv``
334 Security Profile Descriptor Version (SECV): This field indicates
335 the version of the Security Profile Descriptor.
336
337 ``num_sec``
338 Number of Security Profile Descriptors (NumSec): This field
339 indicates the number of Security Profile Descriptors
340 (see :c:type:`struct nbft_security <nbft_security>`), if any, in the Security Profile
341 Descriptor List.
342
343 ``disco``
344 Discovery Descriptor Offset (DISCO): This field indicates
345 the offset in bytes of the Discovery Descriptor List, if any,
346 from byte offset 0h of the NBFT Table Header. If the **num_disc**
347 field is cleared to 0h, then this field is reserved.
348
349 ``discl``
350 Discovery Descriptor Length (DISCL): This field indicates
351 the length in bytes of each Discovery Descriptor, if any.
352 If the **num_disc** field is cleared to 0h, then this field
353 is reserved.
354
355 ``discv``
356 Discovery Descriptor Version (DISCV): This field indicates
357 the version of the Discovery Descriptor.
358
359 ``num_disc``
360 Number of Discovery Descriptors (NumDisc): This field indicates
361 the number of Discovery Descriptors (see :c:type:`struct nbft_discovery <nbft_discovery>`),
362 if any, in the Discovery Descriptor List, if any.
363
364 ``reserved4``
365 Reserved.
366
367
368
369
370
371 .. c:type:: enum nbft_control_flags
372
373 Control Descriptor Flags
374
375 **Constants**
376
377 ``NBFT_CONTROL_VALID``
378 Block Valid: indicates that the structure is valid.
379
380
381
382
383 .. c:type:: struct nbft_host
384
385 Host Descriptor (Figure 9)
386
387 **Definition**
388
389 ::
390
391 struct nbft_host {
392 __u8 structure_id;
393 __u8 flags;
394 __u8 host_id[16];
395 struct nbft_heap_obj host_nqn_obj;
396 __u8 reserved[8];
397 };
398
399 **Members**
400
401 ``structure_id``
402 Structure ID: This field shall be set to 2h (i.e.,
403 Host Descriptor; #NBFT_DESC_HOST).
404
405 ``flags``
406 Host Flags, see :c:type:`enum nbft_host_flags <nbft_host_flags>`.
407
408 ``host_id``
409 Host ID: This field shall be set to the Host Identifier. This
410 field shall not be empty if the NBFT and NVMe Boot are supported
411 by the Platform.
412
413 ``host_nqn_obj``
414 Host NQN Heap Object Reference: this field indicates a heap
415 object containing a Host NQN. This object shall not be empty
416 if the NBFT and NVMe Boot are supported by the Platform.
417
418 ``reserved``
419 Reserved.
420
421
422
423
424
425 .. c:type:: enum nbft_host_flags
426
427 Host Flags
428
429 **Constants**
430
431 ``NBFT_HOST_VALID``
432 Descriptor Valid: If set to 1h, then this
433 descriptor is valid. If cleared to 0h, then
434 this descriptor is reserved.
435
436 ``NBFT_HOST_HOSTID_CONFIGURED``
437 HostID Configured: If set to 1h, then the
438 Host ID field contains an administratively-configured
439 value. If cleared to 0h, then the Host ID
440 field contains a driver default value.
441
442 ``NBFT_HOST_HOSTNQN_CONFIGURED``
443 Host NQN Configured: If set to 1h, then the
444 Host NQN indicated by the Host NQN Heap Object
445 Reference field (:c:type:`struct nbft_host <nbft_host>`.host_nqn)
446 contains an administratively-configured value.
447 If cleared to 0h, then the Host NQN indicated
448 by the Host NQN Offset field contains a driver
449 default value.
450
451 ``NBFT_HOST_PRIMARY_ADMIN_MASK``
452 Mask to get Primary Administrative Host Descriptor:
453 indicates whether the Host Descriptor in this
454 NBFT was selected as the primary NBFT for
455 administrative purposes of platform identity
456 as a hint to the OS. If multiple NBFT tables
457 are present, only one NBFT should be administratively
458 selected. There is no enforcement mechanism
459 for this to be coordinated between multiple NBFT
460 tables, but this field should be set to Selected
461 (#NBFT_HOST_PRIMARY_ADMIN_SELECTED) if
462 more than one NBFT is present.
463
464 ``NBFT_HOST_PRIMARY_ADMIN_NOT_INDICATED``
465 Not Indicated by Driver: The driver that created
466 this NBFT provided no administrative priority
467 hint for this NBFT.
468
469 ``NBFT_HOST_PRIMARY_ADMIN_UNSELECTED``
470 Unselected: The driver that created this NBFT
471 explicitly indicated that this NBFT should
472 not be prioritized over any other NBFT.
473
474 ``NBFT_HOST_PRIMARY_ADMIN_SELECTED``
475 Selected: The driver that created this NBFT
476 explicitly indicated that this NBFT should
477 be prioritized over any other NBFT.
478
479
480
481
482 .. c:type:: struct nbft_hfi
483
484 Host Fabric Interface (HFI) Descriptor (Figure 11)
485
486 **Definition**
487
488 ::
489
490 struct nbft_hfi {
491 __u8 structure_id;
492 __u8 index;
493 __u8 flags;
494 __u8 trtype;
495 __u8 reserved1[12];
496 struct nbft_heap_obj trinfo_obj;
497 __u8 reserved2[10];
498 };
499
500 **Members**
501
502 ``structure_id``
503 Structure ID: This field shall be set to 3h (i.e., Host Fabric
504 Interface Descriptor; #NBFT_DESC_HFI).
505
506 ``index``
507 HFI Descriptor Index: This field indicates the number of this
508 HFI Descriptor in the Host Fabric Interface Descriptor List.
509
510 ``flags``
511 HFI Descriptor Flags, see :c:type:`enum nbft_hfi_flags <nbft_hfi_flags>`.
512
513 ``trtype``
514 HFI Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`.
515
516 ``reserved1``
517 Reserved.
518
519 ``trinfo_obj``
520 HFI Transport Info Descriptor Heap Object Reference: If this
521 field is set to a non-zero value, then this field indicates
522 the location and size of a heap object containing
523 a HFI Transport Info.
524
525 ``reserved2``
526 Reserved.
527
528
529
530
531
532 .. c:type:: enum nbft_hfi_flags
533
534 HFI Descriptor Flags
535
536 **Constants**
537
538 ``NBFT_HFI_VALID``
539 Descriptor Valid: If set to 1h, then this descriptor is valid.
540 If cleared to 0h, then this descriptor is reserved.
541
542
543
544
545 .. c:type:: struct nbft_hfi_info_tcp
546
547 HFI Transport Info Descriptor - NVMe/TCP (Figure 13)
548
549 **Definition**
550
551 ::
552
553 struct nbft_hfi_info_tcp {
554 __u8 structure_id;
555 __u8 version;
556 __u8 trtype;
557 __u8 trinfo_version;
558 __le16 hfi_index;
559 __u8 flags;
560 __le32 pci_sbdf;
561 __u8 mac_addr[6];
562 __le16 vlan;
563 __u8 ip_origin;
564 __u8 ip_address[16];
565 __u8 subnet_mask_prefix;
566 __u8 ip_gateway[16];
567 __u8 reserved1;
568 __le16 route_metric;
569 __u8 primary_dns[16];
570 __u8 secondary_dns[16];
571 __u8 dhcp_server[16];
572 struct nbft_heap_obj host_name_obj;
573 __u8 reserved2[18];
574 };
575
576 **Members**
577
578 ``structure_id``
579 Structure ID: This field shall be set to 7h (i.e.,
580 HFI Transport Info; #NBFT_DESC_HFI_TRINFO).
581
582 ``version``
583 Version: This field shall be set to 1h.
584
585 ``trtype``
586 HFI Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`: This field
587 shall be set to 03h (i.e., NVMe/TCP; #NBFT_TRTYPE_TCP).
588
589 ``trinfo_version``
590 Transport Info Version: Implementations compliant to this
591 specification shall set this field to 1h.
592
593 ``hfi_index``
594 HFI Descriptor Index: The value of the HFI Descriptor Index
595 field of the HFI Descriptor (see :c:type:`struct nbft_hfi <nbft_hfi>`.index)
596 whose HFI Transport Info Descriptor Heap Object Reference
597 field indicates this HFI Transport Info Descriptor.
598
599 ``flags``
600 HFI Transport Flags, see :c:type:`enum nbft_hfi_info_tcp_flags <nbft_hfi_info_tcp_flags>`.
601
602 ``pci_sbdf``
603 PCI Express Routing ID for the HFI Transport Function:
604 This field indicates the PCI Express Routing ID as specified
605 in the PCI Express Base Specification.
606
607 ``mac_addr``
608 MAC Address: The MAC address of this HFI, in EUI-48TM format,
609 as defined in the IEEE Guidelines for Use of Extended Unique
610 Identifiers. This field shall be set to a non-zero value.
611
612 ``vlan``
613 VLAN: If this field is set to a non-zero value, then this
614 field contains the VLAN identifier if the VLAN associated
615 with this HFI, as defined in IEEE 802.1q-2018. If no VLAN
616 is associated with this HFI, then this field shall be cleared
617 to 0h.
618
619 ``ip_origin``
620 IP Origin: If this field is set to a non-zero value, then
621 this field indicates the source of Ethernet L3 configuration
622 information used by the driver for this interface. Valid
623 values are defined in the Win 32 API: NL_PREFIX_ORIGIN
624 enumeration specification. This field should be cleared
625 to 0h if the IP Origin field is unused by driver.
626
627 ``ip_address``
628 IP Address: This field indicates the IPv4 or IPv6 address
629 of this HFI. This field shall be set to a non-zero value.
630
631 ``subnet_mask_prefix``
632 Subnet Mask Prefix: This field indicates the IPv4 or IPv6
633 subnet mask in CIDR routing prefix notation.
634
635 ``ip_gateway``
636 IP Gateway: If this field is set to a non-zero value, this
637 field indicates the IPv4 or IPv6 address of the IP gateway
638 for this HFI. If this field is cleared to 0h, then
639 no IP gateway is specified.
640
641 ``reserved1``
642 Reserved.
643
644 ``route_metric``
645 Route Metric: If this field is set to a non-zero value,
646 this field indicates the cost value for the route indicated
647 by this HF. This field contains the value utilized by the
648 pre-OS driver when chosing among all available routes. Lower
649 values relate to higher priority. Refer to IETF RFC 4249.
650 If the pre-OS driver supports routing and did not configure
651 a specific route metric for this interface, then the pre-OS
652 driver should set this value to 500. If the pre-OS driver
653 does not support routing, then this field should be cleared
654 to 0h.
655
656 ``primary_dns``
657 Primary DNS: If this field is set to a non-zero value,
658 this field indicates the IPv4 or IPv6 address of the
659 Primary DNS server for this HFI, if any, from byte offset
660 0h of the NBFT Table Header. If this field is cleared to 0h,
661 then no Primary DNS is specified.
662
663 ``secondary_dns``
664 Secondary DNS: If this field is set to a non-zero value,
665 this field indicates the IPv4 or IPv6 address of
666 the Secondary DNS server for this HFI, if any, from byte
667 offset 0h of the NBFT Table Header. If this field is
668 cleared to 0h, then no Secondary DNS is specified.
669
670 ``dhcp_server``
671 DHCP Server: If the DHCP Override bit is set to 1h, then
672 this field indicates the IPv4 or IPv6 address of the DHCP
673 server used to assign this HFI address. If that bit is
674 cleared to 0h, then this field is reserved.
675
676 ``host_name_obj``
677 Host Name Heap Object Reference: If this field is set
678 to a non-zero value, then this field indicates the location
679 and size of a heap object containing a Host Name string.
680
681 ``reserved2``
682 Reserved.
683
684
685
686
687
688 .. c:type:: enum nbft_hfi_info_tcp_flags
689
690 HFI Transport Flags
691
692 **Constants**
693
694 ``NBFT_HFI_INFO_TCP_VALID``
695 Descriptor Valid: if set to 1h, then this
696 descriptor is valid. If cleared to 0h, then
697 this descriptor is reserved.
698
699 ``NBFT_HFI_INFO_TCP_GLOBAL_ROUTE``
700 Global Route vs. Link Local Override Flag:
701 if set to 1h, then the BIOS utilized this
702 interface described by HFI to be the default
703 route with highest priority. If cleared to 0h,
704 then routes are local to their own scope.
705
706 ``NBFT_HFI_INFO_TCP_DHCP_OVERRIDE``
707 DHCP Override: if set to 1, then HFI information
708 was populated by consuming the DHCP on this
709 interface. If cleared to 0h, then the HFI
710 information was set administratively by
711 a configuration interface to the driver and
712 pre-OS envrionment.
713
714
715
716
717 .. c:type:: struct nbft_ssns
718
719 Subsystem Namespace (SSNS) Descriptor (Figure 15)
720
721 **Definition**
722
723 ::
724
725 struct nbft_ssns {
726 __u8 structure_id;
727 __le16 index;
728 __le16 flags;
729 __u8 trtype;
730 __le16 trflags;
731 __u8 primary_discovery_ctrl_index;
732 __u8 reserved1;
733 struct nbft_heap_obj subsys_traddr_obj;
734 struct nbft_heap_obj subsys_trsvcid_obj;
735 __le16 subsys_port_id;
736 __le32 nsid;
737 __u8 nidt;
738 __u8 nid[16];
739 __u8 security_desc_index;
740 __u8 primary_hfi_desc_index;
741 __u8 reserved2;
742 struct nbft_heap_obj secondary_hfi_assoc_obj;
743 struct nbft_heap_obj subsys_ns_nqn_obj;
744 struct nbft_heap_obj ssns_extended_info_desc_obj;
745 __u8 reserved3[62];
746 };
747
748 **Members**
749
750 ``structure_id``
751 Structure ID: This field shall be set to 4h
752 (i.e., SSNS; #NBFT_DESC_SSNS).
753
754 ``index``
755 SSNS Descriptor Index: This field indicates the number
756 of this Subsystem Namespace Descriptor in the
757 Subsystem Namespace Descriptor List.
758
759 ``flags``
760 SSNS Flags, see :c:type:`enum nbft_ssns_flags <nbft_ssns_flags>`.
761
762 ``trtype``
763 Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`.
764
765 ``trflags``
766 Transport Specific Flags, see :c:type:`enum nbft_ssns_trflags <nbft_ssns_trflags>`.
767
768 ``primary_discovery_ctrl_index``
769 Primary Discovery Controller Index: The Discovery
770 Descriptor Index field of the Discovery Descriptor
771 (see :c:type:`struct nbft_discovery <nbft_discovery>`) that is associated with
772 this SSNS Descriptor. If a Discovery controller was
773 used to establish this record this value shall
774 be set to a non-zero value. If this namespace was
775 associated with multiple Discovery controllers,
776 those Discovery controllers shall have records
777 in the Discovery Descriptor to facilitate multi-path
778 rediscovery as required. If no Discovery controller
779 was utilized to inform this namespace record,
780 this field shall be cleared to 0h.
781
782 ``reserved1``
783 Reserved.
784
785 ``subsys_traddr_obj``
786 Subsystem Transport Address Heap Object Reference:
787 This field indicates the location and size of a heap
788 object containing the Subsystem Transport Address.
789 For IP based transports types, shall be an IP Address.
790
791 ``subsys_trsvcid_obj``
792 Subsystem Transport Service Identifier Heap Object Reference:
793 This field indicates the location and size of a heap
794 object containing an array of bytes indicating
795 the Subsystem Transport Service Identifier.
796 See :c:type:`enum nbft_trtype <nbft_trtype>`.
797
798 ``subsys_port_id``
799 Subsystem Port ID: Port in the NVM subsystem
800 associated with this transport address used by
801 the pre-OS driver.
802
803 ``nsid``
804 Namespace ID: This field indicates the namespace
805 identifier (NSID) of the namespace indicated by
806 this descriptor. This field shall be cleared to 0h
807 if not specified by the user. If this value is cleared
808 to 0h, then consumers of the NBFT shall rely
809 on the NID.
810
811 ``nidt``
812 Namespace Identifier Type (NIDT): This field
813 contains the value of the Namespace Identifier Type (NIDT)
814 field in the Namespace Identification Descriptor
815 for the namespace indicated by this descriptor.
816 If a namespace supports multiple NIDT entries
817 for uniqueness, the order of preference is NIDT field
818 value of 3h (i.e., UUID) before 2h (i.e., NSGUID),
819 and 2h before 1h (i.e., EUI-64).
820
821 ``nid``
822 Namespace Identifier (NID): This field contains
823 the value of the Namespace Identifier (NID) field
824 in the Namespace Identification Descriptor for
825 the namespace indicated by this descriptor.
826
827 ``security_desc_index``
828 Security Profile Descriptor Index: If the Use Security
829 Flag bit in the SSNS Flags field is set to 1h, then
830 this field indicates the value of the Security Profile
831 Descriptor Index field of the Security Profile
832 Descriptor (see :c:type:`struct nbft_security <nbft_security>`) associated
833 with this namespace. If the Use Security Flag bit
834 is cleared to 0h, then no Security Profile Descriptor
835 is associated with this namespace and this field
836 is reserved.
837
838 ``primary_hfi_desc_index``
839 Primary HFI Descriptor Index: This field indicates
840 the value of the HFI Descriptor Index field of the
841 HFI Descriptor (see :c:type:`struct nbft_hfi <nbft_hfi>`) for the
842 interface associated with this namespace. If multiple
843 HFIs are associated with this record, subsequent
844 interfaces should be populated in the Secondary
845 HFI Associations field.
846
847 ``reserved2``
848 Reserved.
849
850 ``secondary_hfi_assoc_obj``
851 Secondary HFI Associations Heap Object Reference:
852 If this field is set to a non-zero value, then
853 this field indicates an array of bytes, in which
854 each byte contains the value of the HFI Descriptor
855 Index field of an HFI Descriptor in the HFI Descriptor
856 List. If this field is cleared to 0h, then no
857 secondary HFI associations are specified.
858
859 ``subsys_ns_nqn_obj``
860 Subsystem and Namespace NQN Heap Object Reference:
861 This field indicates the location and size of
862 a heap object containing the Subsystem and Namespace NQN.
863
864 ``ssns_extended_info_desc_obj``
865 SSNS Extended Information Descriptor Heap Object
866 Reference: If the SSNS Extended Info In-use Flag
867 bit is set to 1h, then this field indicates the
868 offset in bytes of a heap object containing an
869 SSNS Extended Information Descriptor
870 (see :c:type:`struct nbft_ssns_ext_info <nbft_ssns_ext_info>`) heap object
871 from byte offset 0h of the NBFT Table Header.
872 If the SSNS Extended Info In-use Flag bit is cleared
873 to 0h, then this field is reserved.
874
875 ``reserved3``
876 Reserved.
877
878
879
880
881
882 .. c:type:: enum nbft_ssns_flags
883
884 Subsystem and Namespace Specific Flags Field (Figure 16)
885
886 **Constants**
887
888 ``NBFT_SSNS_VALID``
889 Descriptor Valid: If set to 1h, then this descriptor
890 is valid. If cleared to 0h, then this descriptor
891 is not valid. A host that supports NVMe-oF Boot,
892 but does not currently have a remote Subsystem
893 and Namespace assigned may clear this bit to 0h.
894
895 ``NBFT_SSNS_NON_BOOTABLE_ENTRY``
896 Non-bootable Entry Flag: If set to 1h, this flag
897 indicates that this SSNS Descriptor contains
898 a namespace of administrative purpose to the boot
899 process, but the pre-OS may not have established
900 connectivity to or evaluated the contents of this
901 Descriptor. Such namespaces may contain supplemental
902 data deemed relevant by the Administrator as part
903 of the pre-OS to OS hand off. This may include
904 properties such as a UEFI device path that may
905 not have been created for this namespace. This means
906 an OS runtime may still require the contents
907 of such a namespace to complete later stages
908 of boot. If cleared to 0h, then this namespace did
909 not have any special administrative intent.
910
911 ``NBFT_SSNS_USE_SECURITY_FIELD``
912 Use Security Flag: If set to 1h, then there is
913 a Security Profile Descriptor associated with this
914 SSNS record and the Security Profile Descriptor Index
915 field is valid. If cleared to 0h, then there is
916 no Security Profile Descriptor associated with this
917 SSNS record and the Security Profile Descriptor Index
918 field is not valid.
919
920 ``NBFT_SSNS_DHCP_ROOT_PATH_OVERRIDE``
921 DHCP Root-Path Override Flag: If set to 1h, then
922 this SSNS descriptor was populated by consuming
923 the DHCP Root-Path on this interface. If cleared
924 to 0h, then the DHCP Root-Path was not used
925 in populating the SSNS descriptor.
926
927 ``NBFT_SSNS_EXTENDED_INFO_IN_USE``
928 SSNS Extended Info In-use Flag: If set to 1h,
929 then the SSNS Extended Information Offset field
930 and the SSNS Extended Information Length field
931 are valid. This flag, if set to 1h, indicates
932 that a Subsystem and Namespace Extended Information
933 Descriptor corresponding to this descriptor is present.
934
935 ``NBFT_SSNS_SEPARATE_DISCOVERY_CTRL``
936 Separate Discovery Controller Flag: If set to 1h,
937 then the Discovery controller associated with
938 this volume is on a different transport address
939 than the specified in the Subsystem Transport
940 Address Heap Object Reference. If cleared to 0h,
941 then the Discovery controller is the same as the
942 Subsystem Transport Address Heap Object Reference.
943
944 ``NBFT_SSNS_DISCOVERED_NAMESPACE``
945 Discovered Namespace Flag: If set to 1h, then
946 this namespace was acquired through discovery.
947 If cleared to 0h, then this namespace was
948 explicitly configured in the system.
949
950 ``NBFT_SSNS_UNAVAIL_NAMESPACE_MASK``
951 Mask to get Unavailable Namespace Flag: This
952 field indicates the availability of the namespace
953 at a specific point in time. Such use is only
954 a hint and its use does not guarantee the availability
955 of that referenced namespace at any future point in time.
956
957 ``NBFT_SSNS_UNAVAIL_NAMESPACE_NOTIND``
958 Not Indicated by Driver: No information is provided.
959
960 ``NBFT_SSNS_UNAVAIL_NAMESPACE_AVAIL``
961 Available: A referenced namespace described by this
962 flag was previously accessible by the pre-OS driver.
963
964 ``NBFT_SSNS_UNAVAIL_NAMESPACE_UNAVAIL``
965 Unavailable: This namespace was administratively
966 configured but unattempted, unavailable or
967 inaccessible when establishing connectivity
968 by the pre-OS driver.
969
970
971
972
973 .. c:type:: enum nbft_ssns_trflags
974
975 SSNS Transport Specific Flags Field (Figure 17)
976
977 **Constants**
978
979 ``NBFT_SSNS_TRFLAG_VALID``
980 Transport Specific Flags in Use: If set to 1h, then
981 this descriptor is valid. If cleared to 0h, then
982 this descriptor is not valid.
983
984 ``NBFT_SSNS_PDU_HEADER_DIGEST``
985 PDU Header Digest (HDGST) Flag: If set to 1h, then
986 the host or administrator required the connection
987 described by this Subsystem and Namespace Descriptor
988 to use the NVM Header Digest Enabled. A consumer
989 of this information should attempt to use NVM Header
990 Digest when recreating this connection if enabled.
991 If cleared to 0h, then the host or administrator
992 did not require the connection described by this
993 Subsystem and Namespace Descriptor to use the
994 NVM Header Digest Enabled.
995
996 ``NBFT_SSNS_DATA_DIGEST``
997 Data Digest (DDGST) Flag: If set to 1h, then
998 the host or administrator required the connection
999 described by this Subsystem and Namespace Descriptor
1000 to use the NVM Data Digest Enabled. If cleared
1001 to 0h, then the host or administrator did not
1002 require the connection described by this Subsystem
1003 and Namespace Descriptor to use the NVM Data Digest
1004 Enabled. A consumer of this field should attempt
1005 to use NVM Data Digest when recreating this
1006 connection if enabled.
1007
1008
1009
1010
1011 .. c:type:: struct nbft_ssns_ext_info
1012
1013 Subsystem and Namespace Extended Information Descriptor (Figure 19)
1014
1015 **Definition**
1016
1017 ::
1018
1019 struct nbft_ssns_ext_info {
1020 __u8 structure_id;
1021 __u8 version;
1022 __le16 ssns_index;
1023 __le32 flags;
1024 __le16 cntlid;
1025 __le16 asqsz;
1026 struct nbft_heap_obj dhcp_root_path_str_obj;
1027 };
1028
1029 **Members**
1030
1031 ``structure_id``
1032 Structure ID: This field shall be set to 9h
1033 (i.e., SSNS Extended Info; #NBFT_DESC_SSNS_EXT_INFO).
1034
1035 ``version``
1036 Version: This field shall be set to 1h.
1037
1038 ``ssns_index``
1039 SSNS Descriptor Index: This field indicates the value
1040 of the SSNS Descriptor Index field of the Subsystem
1041 and Namespace Descriptor (see :c:type:`struct nbft_ssns <nbft_ssns>`) whose
1042 SSNS Extended Information Descriptor Heap Object
1043 Reference field indicates this descriptor.
1044
1045 ``flags``
1046 Flags, see :c:type:`enum nbft_ssns_ext_info_flags <nbft_ssns_ext_info_flags>`.
1047
1048 ``cntlid``
1049 Controller ID: The controller identifier of the first
1050 controller associated with the Admin Queue by the driver.
1051 If a controller identifier is not administratively
1052 specified or direct configuration is not supported
1053 by the driver, then this field shall be cleared to 0h.
1054
1055 ``asqsz``
1056 Admin Submission Queue Size (ASQSZ): The Admin Submission
1057 Queue Size utilized for the respective SSNS by the driver.
1058
1059 ``dhcp_root_path_str_obj``
1060 DHCP Root Path String Heap Object Reference: If the
1061 SSNS DHCP Root Path Override (#NBFT_SSNS_DHCP_ROOT_PATH_OVERRIDE)
1062 flag bit is set to 1h, then this field indicates
1063 the offset in bytes of a heap object containing
1064 an DHCP Root Path String used by the driver. If the
1065 SNSS DHCP Root Path Override flag bit is cleared to 0h,
1066 then this field is reserved.
1067
1068
1069
1070
1071
1072 .. c:type:: enum nbft_ssns_ext_info_flags
1073
1074 Subsystem and Namespace Extended Information Descriptor Flags
1075
1076 **Constants**
1077
1078 ``NBFT_SSNS_EXT_INFO_VALID``
1079 Descriptor Valid: If set to 1h, then this descriptor
1080 is valid. If cleared to 0h, then this descriptor
1081 is reserved.
1082
1083 ``NBFT_SSNS_EXT_INFO_ADMIN_ASQSZ``
1084 Administrative ASQSZ: If set to 1h, then the value
1085 of the ASQSZ field was provided by administrative
1086 configuration for this SSNS record. If cleared
1087 to 0h, then the value of the ASQSZ field was
1088 either obtained by discovery or assumed
1089 by the driver.
1090
1091
1092
1093
1094 .. c:type:: struct nbft_security
1095
1096 Security Profile Descriptor (Figure 21)
1097
1098 **Definition**
1099
1100 ::
1101
1102 struct nbft_security {
1103 __u8 structure_id;
1104 __u8 index;
1105 __le16 flags;
1106 __u8 secret_type;
1107 __u8 reserved1;
1108 struct nbft_heap_obj sec_chan_alg_obj;
1109 struct nbft_heap_obj auth_proto_obj;
1110 struct nbft_heap_obj cipher_suite_obj;
1111 struct nbft_heap_obj dh_grp_obj;
1112 struct nbft_heap_obj sec_hash_func_obj;
1113 struct nbft_heap_obj sec_keypath_obj;
1114 __u8 reserved2[22];
1115 };
1116
1117 **Members**
1118
1119 ``structure_id``
1120 Structure ID: This field shall be set to 5h
1121 (i.e., Security; #NBFT_DESC_SECURITY).
1122
1123 ``index``
1124 Security Profile Descriptor Index: This field indicates
1125 the number of this Security Profile Descriptor in the
1126 Security Profile Descriptor List.
1127
1128 ``flags``
1129 Security Profile Descriptor Flags, see :c:type:`enum nbft_security_flags <nbft_security_flags>`.
1130
1131 ``secret_type``
1132 Secret Type, see :c:type:`enum nbft_security_secret_type <nbft_security_secret_type>`.
1133
1134 ``reserved1``
1135 Reserved.
1136
1137 ``sec_chan_alg_obj``
1138 Secure Channel Algorithm Heap Object Reference: If the
1139 Security Policy List field is set to 1h, then this field
1140 indicates the location and size of a heap object containing
1141 a list of secure channel algorithms. The list is an array
1142 of bytes and the values are defined in the Security Type
1143 (SECTYPE) field in the Transport Specific Address Subtype
1144 Definition in the NVMe TCP Transport Specification.
1145 If the Security Policy List field is cleared to 0h, then
1146 this field is reserved.
1147
1148 ``auth_proto_obj``
1149 Authentication Protocols Heap Object Reference: If the
1150 Authentication Policy List field is set to 1h, then this
1151 field indicates the location and size of a heap object
1152 containing a list of authentication protocol identifiers.
1153 If the Authentication Policy List field is cleared to 0h,
1154 then this field is reserved.
1155
1156 ``cipher_suite_obj``
1157 Cipher Suite Offset Heap Object Reference: If the Cipher
1158 Suites Restricted by Policy bit is set to 1h, then this
1159 field indicates the location and size of a heap object
1160 containing a list of cipher suite identifiers. The list,
1161 if any, is an array of bytes and the values are defined
1162 in the IANA TLS Parameters Registry. If the Cipher Suites
1163 Restricted by Policy bit is cleared to 0h, then this field
1164 is reserved.
1165
1166 ``dh_grp_obj``
1167 DH Groups Heap Object Reference: If the Authentication DH Groups
1168 Restricted by Policy List bit is set to 1h, then this field
1169 indicates the location and size of a heap object containing
1170 a list of DH-HMAC-CHAP Diffie-Hellman (DH) group identifiers.
1171 If the Authentication DH Groups Restricted by Policy List
1172 bit is cleared to 0h, then this field is reserved.
1173
1174 ``sec_hash_func_obj``
1175 Secure Hash Functions Offset Heap Object Reference: If the
1176 Secure Hash Functions Policy List bit is set to 1h, then
1177 this field indicates the offset in bytes of a heap object
1178 containing a list of DH-HMAC-CHAP hash function identifiers.
1179 The list is an array of bytes and the values are defined
1180 in the NVM Express Base Specification. If the Secure Hash
1181 Functions Policy List bit is cleared to 0h, then this
1182 field is reserved.
1183
1184 ``sec_keypath_obj``
1185 Secret Keypath Offset Heap Object Reference: if this field
1186 is set to a non-zero value, then this field indicates
1187 the location and size of a heap object containing a URI.
1188 The type of the URI is specified in the Secret Type field.
1189 If this field is cleared to 0h, then this field is reserved.
1190
1191 ``reserved2``
1192 Reserved.
1193
1194
1195
1196
1197
1198 .. c:type:: enum nbft_security_flags
1199
1200 Security Profile Descriptor Flags (Figure 22)
1201
1202 **Constants**
1203
1204 ``NBFT_SECURITY_VALID``
1205 Descriptor Valid: If set to 1h, then
1206 this descriptor is valid. If cleared
1207 to 0h, then this descriptor is not valid.
1208
1209 ``NBFT_SECURITY_IN_BAND_AUTH_MASK``
1210 Mask to get the In-Band Authentication
1211 Required field.
1212
1213 ``NBFT_SECURITY_IN_BAND_AUTH_NOT_SUPPORTED``
1214 In-band authentication is not supported
1215 by the NVM subsystem.
1216
1217 ``NBFT_SECURITY_IN_BAND_AUTH_NOT_REQUIRED``
1218 In-band authentication is supported by
1219 the NVM subsystem and is not required.
1220
1221 ``NBFT_SECURITY_IN_BAND_AUTH_REQUIRED``
1222 In-band authentication is supported by
1223 the NVM subsystem and is required.
1224
1225 ``NBFT_SECURITY_AUTH_POLICY_LIST_MASK``
1226 Mask to get the Authentication Policy List
1227 flag: This field indicates whether
1228 authentication protocols were indicated
1229 by policy from driver defaults or
1230 administrative configuration.
1231
1232 ``NBFT_SECURITY_AUTH_POLICY_LIST_NOT_SUPPORTED``
1233 Authentication Protocols Heap Object Reference
1234 field Offset and Length are reserved.
1235
1236 ``NBFT_SECURITY_AUTH_POLICY_LIST_DRIVER``
1237 Authentication Protocols Offset field and
1238 the Authentication Protocols Length field
1239 indicate a list of authentication protocols
1240 used by the driver.
1241
1242 ``NBFT_SECURITY_AUTH_POLICY_LIST_ADMIN``
1243 Authentication Protocols Offset field and
1244 the Authentication Protocols Length field
1245 indicate a list of authentication protocols
1246 that were administratively set and used
1247 by the driver.
1248
1249 ``NBFT_SECURITY_SEC_CHAN_NEG_MASK``
1250 Mask to get the Secure Channel Negotiation
1251 Required flag: This field indicates whether
1252 secure channel negotiation (e.g. TLS)
1253 is required.
1254
1255 ``NBFT_SECURITY_SEC_CHAN_NEG_NOT_SUPPORTED``
1256 Secure channel negotiation is not supported
1257 by the NVM subsystem.
1258
1259 ``NBFT_SECURITY_SEC_CHAN_NEG_NOT_REQUIRED``
1260 Secure channel negotiation is supported
1261 by the NVM subsystem and is not required.
1262
1263 ``NBFT_SECURITY_SEC_CHAN_NEG_REQUIRED``
1264 Secure channel negotiation is supported
1265 by the NVM subsystem and is required.
1266
1267 ``NBFT_SECURITY_SEC_POLICY_LIST_MASK``
1268 Mask to get the Security Policy List flag:
1269 This field indicates whether secure channel
1270 protocols were indicated by policy from driver
1271 defaults or administrative configuration.
1272
1273 ``NBFT_SECURITY_SEC_POLICY_LIST_NOT_SUPPORTED``
1274 The Offset field and Length field in the
1275 Secure Channel Algorithm Heap Object Reference
1276 field are reserved.
1277
1278 ``NBFT_SECURITY_SEC_POLICY_LIST_DRIVER``
1279 The Heap Object specified by the Secure Channel
1280 Algorithm Heap Object Reference field indicates
1281 a list of authentication protocols used
1282 by the driver.
1283
1284 ``NBFT_SECURITY_SEC_POLICY_LIST_ADMIN``
1285 The Heap Object specified by the Secure Channel
1286 Algorithm Heap Object Reference field indicates
1287 a list of authentication protocols that were
1288 administratively set and used by the driver.
1289
1290 ``NBFT_SECURITY_CIPHER_RESTRICTED``
1291 Cipher Suites Restricted by Policy: If set to 1h,
1292 then the Cipher Suite Offset field and the
1293 Ciper Suite Length field indicate a list
1294 of supported cipher suites by the driver.
1295 If cleared to 0h, then the Cipher Suite Offset
1296 field and the Cipher Suite Length field
1297 are reserved.
1298
1299 ``NBFT_SECURITY_AUTH_DH_GROUPS_RESTRICTED``
1300 Authentication DH Groups Restricted
1301 by Policy List: If set to 1h, then connections
1302 shall use one of the authentication DH groups
1303 in the Authentication DH Groups List is required.
1304 If cleared to 0h, then no Authentication DH Groups
1305 List is indicated and use of an authentication
1306 DH Group is not required.
1307
1308 ``NBFT_SECURITY_SEC_HASH_FUNC_POLICY_LIST``
1309 Secure Hash Functions Policy List: If set to 1h,
1310 then connections shall use one of the secure
1311 hash functions in the Secure Hash Functions
1312 Policy List is required. If cleared to 0h,
1313 then no Secure Hash Functions Policy
1314 List is indicated and use of a secure
1315 hash function is not required.
1316
1317
1318
1319
1320 .. c:type:: enum nbft_security_secret_type
1321
1322 Security Profile Descriptor Secret Type
1323
1324 **Constants**
1325
1326 ``NBFT_SECURITY_SECRET_REDFISH_HOST_IFACE_URI``
1327 Redfish Host Interface URI:
1328 If set to 1h, then the Secret Keypath
1329 Object Reference is a URI pointing
1330 to a Redfish Key Collection Object
1331 that contains the PSK.
1332
1333
1334
1335
1336 .. c:type:: struct nbft_discovery
1337
1338 Discovery Descriptor (Figure 24)
1339
1340 **Definition**
1341
1342 ::
1343
1344 struct nbft_discovery {
1345 __u8 structure_id;
1346 __u8 flags;
1347 __u8 index;
1348 __u8 hfi_index;
1349 __u8 sec_index;
1350 __u8 reserved1;
1351 struct nbft_heap_obj discovery_ctrl_addr_obj;
1352 struct nbft_heap_obj discovery_ctrl_nqn_obj;
1353 __u8 reserved2[14];
1354 };
1355
1356 **Members**
1357
1358 ``structure_id``
1359 Structure ID: This field shall be set to 6h
1360 (i.e., Discovery Descriptor; #NBFT_DESC_DISCOVERY).
1361
1362 ``flags``
1363 Discovery Descriptor Flags, see :c:type:`enum nbft_discovery_flags <nbft_discovery_flags>`.
1364
1365 ``index``
1366 Discovery Descriptor Index: This field indicates
1367 the number of this Discovery Descriptor in
1368 the Discovery Descriptor List.
1369
1370 ``hfi_index``
1371 HFI Descriptor Index: This field indicates the value
1372 of the HFI Descriptor Index field of the HFI Descriptor
1373 associated with this Discovery Descriptor. If multiple
1374 HFIs share a common Discovery controller, there shall
1375 be multiple Discovery Descriptor entries with one per HFI.
1376
1377 ``sec_index``
1378 Security Profile Descriptor Index: This field indicates
1379 the value of the Security Profile Descriptor Index
1380 field of the Security Descriptor associated with
1381 this Discovery Descriptor.
1382
1383 ``reserved1``
1384 Reserved.
1385
1386 ``discovery_ctrl_addr_obj``
1387 Discovery Controller Address Heap Object Reference:
1388 This field indicates the location and size of a heap
1389 object containing a URI which indicates an NVMe Discovery
1390 controller associated with this Discovery Descriptor.
1391 If this field is cleared to 0h, then no URI is specified.
1392
1393 ``discovery_ctrl_nqn_obj``
1394 Discovery Controller NQN Heap Object Reference:
1395 If set to a non-zero value, this field indicates
1396 the location and size of a heap object containing
1397 an NVMe Discovery controller NQN. If the NVMe Discovery
1398 controller referenced by this record requires secure
1399 authentication with a well known Subsystem NQN, this
1400 field indicates the unique NQN for that NVMe Discovery
1401 controller. This record is involved formatted as an NQN
1402 string. If this field is cleared to 0h, then this
1403 field is reserved and the OS shall use the well
1404 known discovery NQN for this record.
1405
1406 ``reserved2``
1407 Reserved.
1408
1409
1410
1411
1412
1413 .. c:type:: enum nbft_discovery_flags
1414
1415 Discovery Descriptor Flags
1416
1417 **Constants**
1418
1419 ``NBFT_DISCOVERY_VALID``
1420 Descriptor Valid: if set to 1h, then this descriptor
1421 is valid. If cleared to 0h, then this descriptor
1422 is reserved.
1423
1424
1425
1426
1427 .. c:type:: enum nbft_info_primary_admin_host_flag
1428
1429 Primary Administrative Host Descriptor Flags
1430
1431 **Constants**
1432
1433 ``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_NOT_INDICATED``
1434 Not Indicated by Driver: The driver
1435 that created this NBFT provided no
1436 administrative priority hint for
1437 this NBFT.
1438
1439 ``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_UNSELECTED``
1440 Unselected: The driver that created
1441 this NBFT explicitly indicated that
1442 this NBFT should not be prioritized
1443 over any other NBFT.
1444
1445 ``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_SELECTED``
1446 Selected: The driver that created
1447 this NBFT explicitly indicated that
1448 this NBFT should be prioritized over
1449 any other NBFT.
1450
1451 ``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_RESERVED``
1452 Reserved.
1453
1454
1455
1456
1457 .. c:type:: struct nbft_info_host
1458
1459 Host Descriptor
1460
1461 **Definition**
1462
1463 ::
1464
1465 struct nbft_info_host {
1466 unsigned char *id;
1467 char *nqn;
1468 bool host_id_configured;
1469 bool host_nqn_configured;
1470 enum nbft_info_primary_admin_host_flag primary;
1471 };
1472
1473 **Members**
1474
1475 ``id``
1476 Host ID (raw UUID, length = 16 bytes).
1477
1478 ``nqn``
1479 Host NQN.
1480
1481 ``host_id_configured``
1482 HostID Configured Flag: value of True indicates that **id**
1483 contains administratively-configured value, or driver
1484 default value if False.
1485
1486 ``host_nqn_configured``
1487 Host NQN Configured Flag: value of True indicates that
1488 **nqn** contains administratively-configured value,
1489 or driver default value if False.
1490
1491 ``primary``
1492 Primary Administrative Host Descriptor, see
1493 :c:type:`enum nbft_info_primary_admin_host_flag <nbft_info_primary_admin_host_flag>`.
1494
1495
1496
1497
1498
1499 .. c:type:: struct nbft_info_hfi_info_tcp
1500
1501 HFI Transport Info Descriptor - NVMe/TCP
1502
1503 **Definition**
1504
1505 ::
1506
1507 struct nbft_info_hfi_info_tcp {
1508 __u32 pci_sbdf;
1509 __u8 mac_addr[6];
1510 __u16 vlan;
1511 __u8 ip_origin;
1512 char ipaddr[40];
1513 __u8 subnet_mask_prefix;
1514 char gateway_ipaddr[40];
1515 __u16 route_metric;
1516 char primary_dns_ipaddr[40];
1517 char secondary_dns_ipaddr[40];
1518 char dhcp_server_ipaddr[40];
1519 char *host_name;
1520 bool this_hfi_is_default_route;
1521 bool dhcp_override;
1522 };
1523
1524 **Members**
1525
1526 ``pci_sbdf``
1527 PCI Express Routing ID for the HFI Transport Function.
1528
1529 ``mac_addr``
1530 MAC Address: The MAC address of this HFI,
1531 in EUI-48TM format.
1532
1533 ``vlan``
1534 The VLAN identifier if the VLAN is associated with
1535 this HFI, as defined in IEEE 802.1q-2018 or zeroes
1536 if no VLAN is associated with this HFI.
1537
1538 ``ip_origin``
1539 The source of Ethernet L3 configuration information
1540 used by the driver or 0 if not used.
1541
1542 ``ipaddr``
1543 The IPv4 or IPv6 address of this HFI.
1544
1545 ``subnet_mask_prefix``
1546 The IPv4 or IPv6 subnet mask in CIDR routing prefix
1547 notation.
1548
1549 ``gateway_ipaddr``
1550 The IPv4 or IPv6 address of the IP gateway for this
1551 HFI or zeroes if no IP gateway is specified.
1552
1553 ``route_metric``
1554 The cost value for the route indicated by this HFI.
1555
1556 ``primary_dns_ipaddr``
1557 The IPv4 or IPv6 address of the Primary DNS server
1558 for this HFI.
1559
1560 ``secondary_dns_ipaddr``
1561 The IPv4 or IPv6 address of the Secondary DNS server
1562 for this HFI.
1563
1564 ``dhcp_server_ipaddr``
1565 The IPv4 or IPv6 address of the DHCP server used
1566 to assign this HFI address.
1567
1568 ``host_name``
1569 The Host Name string.
1570
1571 ``this_hfi_is_default_route``
1572 If True, then the BIOS utilized this interface
1573 described by HFI to be the default route with highest
1574 priority. If False, then routes are local to their
1575 own scope.
1576
1577 ``dhcp_override``
1578 If True, then HFI information was populated
1579 by consuming the DHCP on this interface. If False,
1580 then the HFI information was set administratively
1581 by a configuration interface to the driver and
1582 pre-OS envrionment.
1583
1584
1585
1586
1587
1588 .. c:type:: struct nbft_info_hfi
1589
1590 Host Fabric Interface (HFI) Descriptor
1591
1592 **Definition**
1593
1594 ::
1595
1596 struct nbft_info_hfi {
1597 int index;
1598 char transport[8];
1599 struct nbft_info_hfi_info_tcp tcp_info;
1600 };
1601
1602 **Members**
1603
1604 ``index``
1605 HFI Descriptor Index: indicates the number of this HFI Descriptor
1606 in the Host Fabric Interface Descriptor List.
1607
1608 ``transport``
1609 Transport Type string (e.g. 'tcp').
1610
1611 ``tcp_info``
1612 The HFI Transport Info Descriptor, see :c:type:`struct nbft_info_hfi_info_tcp <nbft_info_hfi_info_tcp>`.
1613
1614
1615
1616
1617
1618 .. c:type:: struct nbft_info_discovery
1619
1620 Discovery Descriptor
1621
1622 **Definition**
1623
1624 ::
1625
1626 struct nbft_info_discovery {
1627 int index;
1628 struct nbft_info_security *security;
1629 struct nbft_info_hfi *hfi;
1630 char *uri;
1631 char *nqn;
1632 };
1633
1634 **Members**
1635
1636 ``index``
1637 The number of this Discovery Descriptor in the Discovery
1638 Descriptor List.
1639
1640 ``security``
1641 The Security Profile Descriptor, see :c:type:`struct nbft_info_security <nbft_info_security>`.
1642
1643 ``hfi``
1644 The HFI Descriptor associated with this Discovery Descriptor.
1645 See :c:type:`struct nbft_info_hfi <nbft_info_hfi>`.
1646
1647 ``uri``
1648 A URI which indicates an NVMe Discovery controller associated
1649 with this Discovery Descriptor.
1650
1651 ``nqn``
1652 An NVMe Discovery controller NQN.
1653
1654
1655
1656
1657
1658 .. c:type:: struct nbft_info_security
1659
1660 Security Profile Descriptor
1661
1662 **Definition**
1663
1664 ::
1665
1666 struct nbft_info_security {
1667 int index;
1668 };
1669
1670 **Members**
1671
1672 ``index``
1673 The number of this Security Profile Descriptor in the Security
1674 Profile Descriptor List.
1675
1676
1677
1678
1679
1680 .. c:type:: enum nbft_info_nid_type
1681
1682 Namespace Identifier Type (NIDT)
1683
1684 **Constants**
1685
1686 ``NBFT_INFO_NID_TYPE_NONE``
1687 No identifier available.
1688
1689 ``NBFT_INFO_NID_TYPE_EUI64``
1690 The EUI-64 identifier.
1691
1692 ``NBFT_INFO_NID_TYPE_NGUID``
1693 The NSGUID identifier.
1694
1695 ``NBFT_INFO_NID_TYPE_NS_UUID``
1696 The UUID identifier.
1697
1698
1699
1700
1701 .. c:type:: struct nbft_info_subsystem_ns
1702
1703 Subsystem Namespace (SSNS) info
1704
1705 **Definition**
1706
1707 ::
1708
1709 struct nbft_info_subsystem_ns {
1710 int index;
1711 struct nbft_info_discovery *discovery;
1712 struct nbft_info_security *security;
1713 int num_hfis;
1714 struct nbft_info_hfi **hfis;
1715 char transport[8];
1716 char traddr[40];
1717 char *trsvcid;
1718 __u16 subsys_port_id;
1719 __u32 nsid;
1720 enum nbft_info_nid_type nid_type;
1721 __u8 *nid;
1722 char *subsys_nqn;
1723 bool pdu_header_digest_required;
1724 bool data_digest_required;
1725 int controller_id;
1726 int asqsz;
1727 char *dhcp_root_path_string;
1728 bool discovered;
1729 bool unavailable;
1730 };
1731
1732 **Members**
1733
1734 ``index``
1735 SSNS Descriptor Index in the descriptor list.
1736
1737 ``discovery``
1738 Primary Discovery Controller associated with
1739 this SSNS Descriptor.
1740
1741 ``security``
1742 Security Profile Descriptor associated with
1743 this namespace.
1744
1745 ``num_hfis``
1746 Number of HFIs.
1747
1748 ``hfis``
1749 List of HFIs associated with this namespace.
1750 Includes the primary HFI at the first position
1751 and all secondary HFIs. This array is null-terminated.
1752
1753 ``transport``
1754 Transport Type string (e.g. 'tcp').
1755
1756 ``traddr``
1757 Subsystem Transport Address.
1758
1759 ``trsvcid``
1760 Subsystem Transport Service Identifier.
1761
1762 ``subsys_port_id``
1763 The Subsystem Port ID.
1764
1765 ``nsid``
1766 The Namespace ID of this descriptor or when **nid**
1767 should be used instead.
1768
1769 ``nid_type``
1770 Namespace Identifier Type, see :c:type:`enum nbft_info_nid_type <nbft_info_nid_type>`.
1771
1772 ``nid``
1773 The Namespace Identifier value.
1774
1775 ``subsys_nqn``
1776 Subsystem and Namespace NQN.
1777
1778 ``pdu_header_digest_required``
1779 PDU Header Digest (HDGST) Flag: the use of NVM Header
1780 Digest Enabled is required.
1781
1782 ``data_digest_required``
1783 Data Digest (DDGST) Flag: the use of NVM Data Digest
1784 Enabled is required.
1785
1786 ``controller_id``
1787 Controller ID (SSNS Extended Information Descriptor):
1788 The controller ID associated with the Admin Queue
1789 or 0 if not supported.
1790
1791 ``asqsz``
1792 Admin Submission Queue Size (SSNS Extended Information
1793 Descriptor) or 0 if not supported.
1794
1795 ``dhcp_root_path_string``
1796 DHCP Root Path Override string (SSNS Extended
1797 Information Descriptor).
1798
1799 ``discovered``
1800 Indicates that this namespace was acquired
1801 through discovery.
1802
1803 ``unavailable``
1804 Namespace is unavailable as indicated by
1805 the pre-OS driver.
1806
1807
1808
1809
1810
1811 .. c:type:: struct nbft_info
1812
1813 The parsed NBFT table data.
1814
1815 **Definition**
1816
1817 ::
1818
1819 struct nbft_info {
1820 char *filename;
1821 __u8 *raw_nbft;
1822 ssize_t raw_nbft_size;
1823 struct nbft_info_host host;
1824 struct nbft_info_hfi **hfi_list;
1825 struct nbft_info_security **security_list;
1826 struct nbft_info_discovery **discovery_list;
1827 struct nbft_info_subsystem_ns **subsystem_ns_list;
1828 };
1829
1830 **Members**
1831
1832 ``filename``
1833 Path to the NBFT table.
1834
1835 ``raw_nbft``
1836 The original NBFT table contents.
1837
1838 ``raw_nbft_size``
1839 Size of **raw_nbft**.
1840
1841 ``host``
1842 The Host Descriptor (should match other NBFTs).
1843
1844 ``hfi_list``
1845 The HFI Descriptor List (null-terminated array).
1846
1847 ``security_list``
1848 The Security Profile Descriptor List (null-terminated array).
1849
1850 ``discovery_list``
1851 The Discovery Descriptor List (null-terminated array).
1852
1853 ``subsystem_ns_list``
1854 The SSNS Descriptor List (null-terminated array).
1855
1856
1857
1858 .. c:function:: int nvme_nbft_read (struct nbft_info **nbft, const char *filename)
1859
1860 Read and parse contents of an ACPI NBFT table
1861
1862 **Parameters**
1863
1864 ``struct nbft_info **nbft``
1865 Parsed NBFT table data.
1866
1867 ``const char *filename``
1868 Filename of the raw NBFT table to read.
1869
1870 **Description**
1871
1872 Read and parse the specified NBFT file into a struct nbft_info.
1873 Free with nvme_nbft_free().
1874
1875 **Return**
1876
1877 0 on success, errno otherwise.
1878
1879
1880 .. c:function:: void nvme_nbft_free (struct nbft_info *nbft)
1881
1882 Free the struct nbft_info and its contents
1883
1884 **Parameters**
1885
1886 ``struct nbft_info *nbft``
1887 Parsed NBFT table data.
1888
1889