summaryrefslogtreecommitdiffstats
path: root/doc/rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2023-06-30 22:36:10 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-06-30 22:36:10 +0000
commit61d0a8bdffbbb7229776d2f4f2e79ed22d21551f (patch)
tree2e249969fedce45eb37ae6314ad167595900fe38 /doc/rst
parentReleasing debian version 1.4-4. (diff)
downloadlibnvme-61d0a8bdffbbb7229776d2f4f2e79ed22d21551f.tar.xz
libnvme-61d0a8bdffbbb7229776d2f4f2e79ed22d21551f.zip
Merging upstream version 1.5.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/rst')
-rw-r--r--doc/rst/ioctl.rst5
-rw-r--r--doc/rst/meson.build6
-rw-r--r--doc/rst/mi.rst26
-rw-r--r--doc/rst/nbft.rst1870
-rw-r--r--doc/rst/tree.rst77
-rw-r--r--doc/rst/types.rst133
-rw-r--r--doc/rst/util.rst23
7 files changed, 2136 insertions, 4 deletions
diff --git a/doc/rst/ioctl.rst b/doc/rst/ioctl.rst
index d0a5173..a2f3b86 100644
--- a/doc/rst/ioctl.rst
+++ b/doc/rst/ioctl.rst
@@ -3883,7 +3883,7 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
-.. c:function:: int nvme_ns_mgmt_create (int fd, struct nvme_id_ns *ns, __u32 *nsid, __u32 timeout, __u8 csi)
+.. c:function:: int nvme_ns_mgmt_create (int fd, struct nvme_id_ns *ns, __u32 *nsid, __u32 timeout, __u8 csi, struct nvme_ns_mgmt_host_sw_specified *data)
Create a non attached namespace
@@ -3905,6 +3905,9 @@ The nvme command status if a response was received (see
``__u8 csi``
Command Set Identifier
+``struct nvme_ns_mgmt_host_sw_specified *data``
+ Host Software Specified Fields that defines ns creation parameters
+
**Description**
On successful creation, the namespace exists in the subsystem, but is not
diff --git a/doc/rst/meson.build b/doc/rst/meson.build
index ea79115..e54c381 100644
--- a/doc/rst/meson.build
+++ b/doc/rst/meson.build
@@ -1,17 +1,19 @@
+top_source_dir = meson.current_source_dir() + '/../../'
+
want_docs = get_option('docs')
if want_docs != 'false'
want_docs_build = get_option('docs-build')
rstdir = get_option('rstdir')
if want_docs_build
- kernel_doc = find_program('../kernel-doc')
+ kernel_doc = find_program(top_source_dir + 'scripts/kernel-doc')
conf = configuration_data()
conf.set('SYSCONFDIR', sysconfdir)
if want_docs == 'all' or want_docs == 'rst' or want_docs == 'html'
foreach apif : api_files
- afile = files('../../src/nvme/' + apif)
+ afile = files(top_source_dir + 'src/nvme/' + apif)
subst = configure_file(
input: afile,
output: '@BASENAME@.subst',
diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst
index d43e3c6..ba0f29a 100644
--- a/doc/rst/mi.rst
+++ b/doc/rst/mi.rst
@@ -1029,6 +1029,27 @@ New controller object, or NULL on failure.
controller to free
+.. c:function:: __u16 nvme_mi_ctrl_id (nvme_mi_ctrl_t ctrl)
+
+ get the ID of a controller
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+ controller to query
+
+**Description**
+
+Retrieve the ID of the controller, as defined by hardware, and available
+in the Identify (Controller List) data. This is the value passed to
+**nvme_mi_init_ctrl**, but may have been created internally via
+**nvme_mi_scan_ep**.
+
+**Return**
+
+the (locally-stored) ID of this controller.
+
+
.. c:function:: char * nvme_mi_endpoint_desc (nvme_mi_ep_t ep)
Get a string describing a MI endpoint.
@@ -2969,7 +2990,7 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
-.. c:function:: int nvme_mi_admin_ns_mgmt_create (nvme_mi_ctrl_t ctrl, struct nvme_id_ns *ns, __u8 csi, __u32 *nsid)
+.. c:function:: int nvme_mi_admin_ns_mgmt_create (nvme_mi_ctrl_t ctrl, struct nvme_id_ns *ns, __u8 csi, __u32 *nsid, struct nvme_ns_mgmt_host_sw_specified *data)
Helper for Namespace Management Create command
@@ -2987,6 +3008,9 @@ The nvme command status if a response was received (see
``__u32 *nsid``
Set to new namespace ID on create
+``struct nvme_ns_mgmt_host_sw_specified *data``
+ Host Software Specified Fields that defines ns creation parameters
+
**Description**
Issues a Namespace Management (Create) command to **ctrl**, to create a
diff --git a/doc/rst/nbft.rst b/doc/rst/nbft.rst
new file mode 100644
index 0000000..93a3642
--- /dev/null
+++ b/doc/rst/nbft.rst
@@ -0,0 +1,1870 @@
+
+
+.. c:enum:: nbft_desc_type
+
+ NBFT Elements - Descriptor Types (Figure 5)
+
+**Constants**
+
+``NBFT_DESC_HEADER``
+ Header: an ACPI structure header with some additional
+ NBFT specific info.
+
+``NBFT_DESC_CONTROL``
+ Control Descriptor: indicates the location of host,
+ HFI, SSNS, security, and discovery descriptors.
+
+``NBFT_DESC_HOST``
+ Host Descriptor: host information.
+
+``NBFT_DESC_HFI``
+ HFI Descriptor: an indexable table of HFI Descriptors,
+ one for each fabric interface on the host.
+
+``NBFT_DESC_SSNS``
+ Subsystem Namespace Descriptor: an indexable table
+ of SSNS Descriptors.
+
+``NBFT_DESC_SECURITY``
+ Security Descriptor: an indexable table of Security
+ descriptors.
+
+``NBFT_DESC_DISCOVERY``
+ Discovery Descriptor: an indexable table of Discovery
+ Descriptors.
+
+``NBFT_DESC_HFI_TRINFO``
+ HFI Transport Descriptor: indicated by an HFI Descriptor,
+ corresponds to a specific transport for a single HFI.
+
+``NBFT_DESC_RESERVED_8``
+ Reserved.
+
+``NBFT_DESC_SSNS_EXT_INFO``
+ SSNS Extended Info Descriptor: indicated by an SSNS
+ Descriptor if required.
+
+
+
+
+.. c:enum:: nbft_trtype
+
+ NBFT Interface Transport Types (Figure 7)
+
+**Constants**
+
+``NBFT_TRTYPE_TCP``
+ NVMe/TCP (802.3 + TCP/IP). String Designator "tcp".
+
+
+
+
+.. c:struct:: nbft_heap_obj
+
+ NBFT Header Driver Signature
+
+**Definition**
+
+::
+
+ struct nbft_heap_obj {
+ __le32 offset;
+ __le16 length;
+ };
+
+**Members**
+
+``offset``
+ Offset in bytes of the heap object, if any, from byte offset 0h
+ of the NBFT Table Header.
+
+``length``
+ Length in bytes of the heap object, if any.
+
+
+
+
+
+.. c:struct:: nbft_header
+
+ NBFT Table - Header (Figure 8)
+
+**Definition**
+
+::
+
+ struct nbft_header {
+ char signature[4];
+ __le32 length;
+ __u8 major_revision;
+ __u8 checksum;
+ char oem_id[6];
+ char oem_table_id[8];
+ __le32 oem_revision;
+ __le32 creator_id;
+ __le32 creator_revision;
+ __le32 heap_offset;
+ __le32 heap_length;
+ struct nbft_heap_obj driver_dev_path_sig;
+ __u8 minor_revision;
+ __u8 reserved[13];
+ };
+
+**Members**
+
+``signature``
+ Signature: An ASCII string representation of the table
+ identifier. This field shall be set to the value 4E424654h
+ (i.e. "NBFT", see #NBFT_HEADER_SIG).
+
+``length``
+ Length: The length of the table, in bytes, including the
+ header, starting from offset 0h. This field is used to record
+ the size of the entire table.
+
+``major_revision``
+ Major Revision: The major revision of the structure
+ corresponding to the Signature field. Larger major revision
+ numbers should not be assumed backward compatible to lower
+ major revision numbers with the same signature.
+
+``checksum``
+ Checksum: The entire table, including the Checksum field,
+ shall sum to 0h to be considered valid.
+
+``oem_id``
+ OEMID shall be populated by the NBFT driver writer by
+ an OEM-supplied string that identifies the OEM. All
+ trailing bytes shall be NULL.
+
+``oem_table_id``
+ OEM Table ID: This field shall be populated by the NBFT
+ driver writer with an OEM-supplied string that the OEM
+ uses to identify the particular data table. This field is
+ particularly useful when defining a definition block to
+ distinguish definition block functions. The OEM assigns
+ each dissimilar table a new OEM Table ID.
+
+``oem_revision``
+ OEM Revision: An OEM-supplied revision number. Larger
+ numbers are assumed to be newer revisions.
+
+``creator_id``
+ Creator ID: Vendor ID of utility that created the table.
+ For instance, this may be the ID for the ASL Compiler.
+
+``creator_revision``
+ Creator Revision: Revision of utility that created the
+ table. For instance, this may be the ID for the ASL Compiler.
+
+``heap_offset``
+ Heap Offset (HO): This field indicates the offset in bytes
+ of the heap, if any, from byte offset 0h of the NBFT
+ Table Header.
+
+``heap_length``
+ Heap Length (HL): The length of the heap, if any.
+
+``driver_dev_path_sig``
+ Driver Signature Heap Object Reference: This field indicates
+ the offset in bytes of a heap object containing the Driver
+ Signature, if any, from byte offset 0h of the NBFT Table
+ Header.
+
+``minor_revision``
+ Minor Revision: The minor revision of the structure
+ corresponding to the Signature field. If the major revision
+ numbers are the same, any minor revision number differences
+ shall be backwards compatible with the same signature.
+
+``reserved``
+ Reserved.
+
+
+
+
+
+.. c:struct:: nbft_control
+
+ NBFT Table - Control Descriptor (Figure 8)
+
+**Definition**
+
+::
+
+ struct nbft_control {
+ __u8 structure_id;
+ __u8 major_revision;
+ __u8 minor_revision;
+ __u8 reserved1;
+ __le16 csl;
+ __u8 flags;
+ __u8 reserved2;
+ struct nbft_heap_obj hdesc;
+ __u8 hsv;
+ __u8 reserved3;
+ __le32 hfio;
+ __le16 hfil;
+ __u8 hfiv;
+ __u8 num_hfi;
+ __le32 ssnso;
+ __le16 ssnsl;
+ __u8 ssnsv;
+ __u8 num_ssns;
+ __le32 seco;
+ __le16 secl;
+ __u8 secv;
+ __u8 num_sec;
+ __le32 disco;
+ __le16 discl;
+ __u8 discv;
+ __u8 num_disc;
+ __u8 reserved4[16];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field specifies the element (refer to
+ :c:type:`enum nbft_desc_type <nbft_desc_type>`). This field shall be set to 1h (i.e.,
+ Control, #NBFT_DESC_CONTROL).
+
+``major_revision``
+ Major Revision: The major revision of the structure corresponding
+ to the Signature field. Larger major revision numbers should
+ not be assumed backward compatible to lower major revision
+ numbers with the same signature.
+
+``minor_revision``
+ Minor Revision: The minor revision of the structure corresponding
+ to the signature field. If the major revision numbers are
+ the same, any minor revision number differences shall be backwards
+ compatible with the same signature.
+
+``reserved1``
+ Reserved.
+
+``csl``
+ Control Structure Length (CSL): This field indicates the length
+ in bytes of the Control Descriptor.
+
+``flags``
+ Flags, see :c:type:`enum nbft_control_flags <nbft_control_flags>`.
+
+``reserved2``
+ Reserved.
+
+``hdesc``
+ Host Descriptor (HDESC): This field indicates the location
+ and length of the Host Descriptor (see :c:type:`struct nbft_host <nbft_host>`).
+
+``hsv``
+ Host Descriptor Version (HSV): This field indicates the version
+ of the Host Descriptor.
+
+``reserved3``
+ Reserved.
+
+``hfio``
+ HFI Descriptor List Offset (HFIO): If this field is set to
+ a non-zero value, then this field indicates the offset in bytes
+ of the HFI Descriptor List, if any, from byte offset 0h of the
+ NBFT Table Header. If the **num_hfi** field is cleared to 0h,
+ then this field is reserved.
+
+``hfil``
+ HFI Descriptor Length (HFIL): This field indicates the length
+ in bytes of each HFI Descriptor, if any. If the **num_hfi** field
+ is cleared to 0h, then this field is reserved.
+
+``hfiv``
+ HFI Descriptor Version (HFIV): This field indicates the version
+ of each HFI Descriptor.
+
+``num_hfi``
+ Number of Host Fabric Interface Descriptors (NumHFI): This field
+ indicates the number of HFI Descriptors (see :c:type:`struct nbft_hfi <nbft_hfi>`)
+ in the HFI Descriptor List, if any. If no interfaces have been
+ configured, then this field shall be cleared to 0h.
+
+``ssnso``
+ SSNS Descriptor List Offset (SSNSO):: This field indicates
+ the offset in bytes of the SSNS Descriptor List, if any, from
+ byte offset 0h of the NBFT Table Header. If the **num_ssns** field
+ is cleared to 0h, then this field is reserved.
+
+``ssnsl``
+ SSNS Descriptor Length (SSNSL): This field indicates the length
+ in bytes of each SSNS Descriptor, if any. If the **num_ssns**
+ field is cleared to 0h, then this field is reserved.
+
+``ssnsv``
+ SSNS Descriptor Version (SSNSV): This field indicates the version
+ of the SSNS Descriptor.
+
+``num_ssns``
+ Number of Subsystem and Namespace Descriptors (NumSSNS): This
+ field indicates the number of Subsystem Namespace (SSNS)
+ Descriptors (see :c:type:`struct nbft_ssns <nbft_ssns>`) in the SSNS Descriptor List,
+ if any.
+
+``seco``
+ Security Profile Descriptor List Offset (SECO): This field
+ indicates the offset in bytes of the Security Profile Descriptor
+ List, if any, from byte offset 0h of the NBFT Table Header.
+ If the **num_sec** field is cleared to 0h, then this field
+ is reserved.
+
+``secl``
+ Security Profile Descriptor Length (SECL): This field indicates
+ the length in bytes of each Security Profile Descriptor, if any.
+ If the **num_sec** field is cleared to 0h, then this field
+ is reserved.
+
+``secv``
+ Security Profile Descriptor Version (SECV): This field indicates
+ the version of the Security Profile Descriptor.
+
+``num_sec``
+ Number of Security Profile Descriptors (NumSec): This field
+ indicates the number of Security Profile Descriptors
+ (see :c:type:`struct nbft_security <nbft_security>`), if any, in the Security Profile
+ Descriptor List.
+
+``disco``
+ Discovery Descriptor Offset (DISCO): This field indicates
+ the offset in bytes of the Discovery Descriptor List, if any,
+ from byte offset 0h of the NBFT Table Header. If the **num_disc**
+ field is cleared to 0h, then this field is reserved.
+
+``discl``
+ Discovery Descriptor Length (DISCL): This field indicates
+ the length in bytes of each Discovery Descriptor, if any.
+ If the **num_disc** field is cleared to 0h, then this field
+ is reserved.
+
+``discv``
+ Discovery Descriptor Version (DISCV): This field indicates
+ the version of the Discovery Descriptor.
+
+``num_disc``
+ Number of Discovery Descriptors (NumDisc): This field indicates
+ the number of Discovery Descriptors (see :c:type:`struct nbft_discovery <nbft_discovery>`),
+ if any, in the Discovery Descriptor List, if any.
+
+``reserved4``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_control_flags
+
+ Control Descriptor Flags
+
+**Constants**
+
+``NBFT_CONTROL_VALID``
+ Block Valid: indicates that the structure is valid.
+
+
+
+
+.. c:struct:: nbft_host
+
+ Host Descriptor (Figure 9)
+
+**Definition**
+
+::
+
+ struct nbft_host {
+ __u8 structure_id;
+ __u8 flags;
+ __u8 host_id[16];
+ struct nbft_heap_obj host_nqn_obj;
+ __u8 reserved[8];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 2h (i.e.,
+ Host Descriptor; #NBFT_DESC_HOST).
+
+``flags``
+ Host Flags, see :c:type:`enum nbft_host_flags <nbft_host_flags>`.
+
+``host_id``
+ Host ID: This field shall be set to the Host Identifier. This
+ field shall not be empty if the NBFT and NVMe Boot are supported
+ by the Platform.
+
+``host_nqn_obj``
+ Host NQN Heap Object Reference: this field indicates a heap
+ object containing a Host NQN. This object shall not be empty
+ if the NBFT and NVMe Boot are supported by the Platform.
+
+``reserved``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_host_flags
+
+ Host Flags
+
+**Constants**
+
+``NBFT_HOST_VALID``
+ Descriptor Valid: If set to 1h, then this
+ descriptor is valid. If cleared to 0h, then
+ this descriptor is reserved.
+
+``NBFT_HOST_HOSTID_CONFIGURED``
+ HostID Configured: If set to 1h, then the
+ Host ID field contains an administratively-configured
+ value. If cleared to 0h, then the Host ID
+ field contains a driver default value.
+
+``NBFT_HOST_HOSTNQN_CONFIGURED``
+ Host NQN Configured: If set to 1h, then the
+ Host NQN indicated by the Host NQN Heap Object
+ Reference field (:c:type:`struct nbft_host <nbft_host>`.host_nqn)
+ contains an administratively-configured value.
+ If cleared to 0h, then the Host NQN indicated
+ by the Host NQN Offset field contains a driver
+ default value.
+
+``NBFT_HOST_PRIMARY_ADMIN_MASK``
+ Mask to get Primary Administrative Host Descriptor:
+ indicates whether the Host Descriptor in this
+ NBFT was selected as the primary NBFT for
+ administrative purposes of platform identity
+ as a hint to the OS. If multiple NBFT tables
+ are present, only one NBFT should be administratively
+ selected. There is no enforcement mechanism
+ for this to be coordinated between multiple NBFT
+ tables, but this field should be set to Selected
+ (#NBFT_HOST_PRIMARY_ADMIN_SELECTED) if
+ more than one NBFT is present.
+
+``NBFT_HOST_PRIMARY_ADMIN_NOT_INDICATED``
+ Not Indicated by Driver: The driver that created
+ this NBFT provided no administrative priority
+ hint for this NBFT.
+
+``NBFT_HOST_PRIMARY_ADMIN_UNSELECTED``
+ Unselected: The driver that created this NBFT
+ explicitly indicated that this NBFT should
+ not be prioritized over any other NBFT.
+
+``NBFT_HOST_PRIMARY_ADMIN_SELECTED``
+ Selected: The driver that created this NBFT
+ explicitly indicated that this NBFT should
+ be prioritized over any other NBFT.
+
+
+
+
+.. c:struct:: nbft_hfi
+
+ Host Fabric Interface (HFI) Descriptor (Figure 11)
+
+**Definition**
+
+::
+
+ struct nbft_hfi {
+ __u8 structure_id;
+ __u8 index;
+ __u8 flags;
+ __u8 trtype;
+ __u8 reserved1[12];
+ struct nbft_heap_obj trinfo_obj;
+ __u8 reserved2[10];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 3h (i.e., Host Fabric
+ Interface Descriptor; #NBFT_DESC_HFI).
+
+``index``
+ HFI Descriptor Index: This field indicates the number of this
+ HFI Descriptor in the Host Fabric Interface Descriptor List.
+
+``flags``
+ HFI Descriptor Flags, see :c:type:`enum nbft_hfi_flags <nbft_hfi_flags>`.
+
+``trtype``
+ HFI Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`.
+
+``reserved1``
+ Reserved.
+
+``trinfo_obj``
+ HFI Transport Info Descriptor Heap Object Reference: If this
+ field is set to a non-zero value, then this field indicates
+ the location and size of a heap object containing
+ a HFI Transport Info.
+
+``reserved2``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_hfi_flags
+
+ HFI Descriptor Flags
+
+**Constants**
+
+``NBFT_HFI_VALID``
+ Descriptor Valid: If set to 1h, then this descriptor is valid.
+ If cleared to 0h, then this descriptor is reserved.
+
+
+
+
+.. c:struct:: nbft_hfi_info_tcp
+
+ HFI Transport Info Descriptor - NVMe/TCP (Figure 13)
+
+**Definition**
+
+::
+
+ struct nbft_hfi_info_tcp {
+ __u8 structure_id;
+ __u8 version;
+ __u8 trtype;
+ __u8 trinfo_version;
+ __le16 hfi_index;
+ __u8 flags;
+ __le32 pci_sbdf;
+ __u8 mac_addr[6];
+ __le16 vlan;
+ __u8 ip_origin;
+ __u8 ip_address[16];
+ __u8 subnet_mask_prefix;
+ __u8 ip_gateway[16];
+ __u8 reserved1;
+ __le16 route_metric;
+ __u8 primary_dns[16];
+ __u8 secondary_dns[16];
+ __u8 dhcp_server[16];
+ struct nbft_heap_obj host_name_obj;
+ __u8 reserved2[18];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 7h (i.e.,
+ HFI Transport Info; #NBFT_DESC_HFI_TRINFO).
+
+``version``
+ Version: This field shall be set to 1h.
+
+``trtype``
+ HFI Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`: This field
+ shall be set to 03h (i.e., NVMe/TCP; #NBFT_TRTYPE_TCP).
+
+``trinfo_version``
+ Transport Info Version: Implementations compliant to this
+ specification shall set this field to 1h.
+
+``hfi_index``
+ HFI Descriptor Index: The value of the HFI Descriptor Index
+ field of the HFI Descriptor (see :c:type:`struct nbft_hfi <nbft_hfi>`.index)
+ whose HFI Transport Info Descriptor Heap Object Reference
+ field indicates this HFI Transport Info Descriptor.
+
+``flags``
+ HFI Transport Flags, see :c:type:`enum nbft_hfi_info_tcp_flags <nbft_hfi_info_tcp_flags>`.
+
+``pci_sbdf``
+ PCI Express Routing ID for the HFI Transport Function:
+ This field indicates the PCI Express Routing ID as specified
+ in the PCI Express Base Specification.
+
+``mac_addr``
+ MAC Address: The MAC address of this HFI, in EUI-48TM format,
+ as defined in the IEEE Guidelines for Use of Extended Unique
+ Identifiers. This field shall be set to a non-zero value.
+
+``vlan``
+ VLAN: If this field is set to a non-zero value, then this
+ field contains the VLAN identifier if the VLAN associated
+ with this HFI, as defined in IEEE 802.1q-2018. If no VLAN
+ is associated with this HFI, then this field shall be cleared
+ to 0h.
+
+``ip_origin``
+ IP Origin: If this field is set to a non-zero value, then
+ this field indicates the source of Ethernet L3 configuration
+ information used by the driver for this interface. Valid
+ values are defined in the Win 32 API: NL_PREFIX_ORIGIN
+ enumeration specification. This field should be cleared
+ to 0h if the IP Origin field is unused by driver.
+
+``ip_address``
+ IP Address: This field indicates the IPv4 or IPv6 address
+ of this HFI. This field shall be set to a non-zero value.
+
+``subnet_mask_prefix``
+ Subnet Mask Prefix: This field indicates the IPv4 or IPv6
+ subnet mask in CIDR routing prefix notation.
+
+``ip_gateway``
+ IP Gateway: If this field is set to a non-zero value, this
+ field indicates the IPv4 or IPv6 address of the IP gateway
+ for this HFI. If this field is cleared to 0h, then
+ no IP gateway is specified.
+
+``reserved1``
+ Reserved.
+
+``route_metric``
+ Route Metric: If this field is set to a non-zero value,
+ this field indicates the cost value for the route indicated
+ by this HF. This field contains the value utilized by the
+ pre-OS driver when chosing among all available routes. Lower
+ values relate to higher priority. Refer to IETF RFC 4249.
+ If the pre-OS driver supports routing and did not configure
+ a specific route metric for this interface, then the pre-OS
+ driver should set this value to 500. If the pre-OS driver
+ does not support routing, then this field should be cleared
+ to 0h.
+
+``primary_dns``
+ Primary DNS: If this field is set to a non-zero value,
+ this field indicates the IPv4 or IPv6 address of the
+ Primary DNS server for this HFI, if any, from byte offset
+ 0h of the NBFT Table Header. If this field is cleared to 0h,
+ then no Primary DNS is specified.
+
+``secondary_dns``
+ Secondary DNS: If this field is set to a non-zero value,
+ this field indicates the IPv4 or IPv6 address of
+ the Secondary DNS server for this HFI, if any, from byte
+ offset 0h of the NBFT Table Header. If this field is
+ cleared to 0h, then no Secondary DNS is specified.
+
+``dhcp_server``
+ DHCP Server: If the DHCP Override bit is set to 1h, then
+ this field indicates the IPv4 or IPv6 address of the DHCP
+ server used to assign this HFI address. If that bit is
+ cleared to 0h, then this field is reserved.
+
+``host_name_obj``
+ Host Name Heap Object Reference: If this field is set
+ to a non-zero value, then this field indicates the location
+ and size of a heap object containing a Host Name string.
+
+``reserved2``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_hfi_info_tcp_flags
+
+ HFI Transport Flags
+
+**Constants**
+
+``NBFT_HFI_INFO_TCP_VALID``
+ Descriptor Valid: if set to 1h, then this
+ descriptor is valid. If cleared to 0h, then
+ this descriptor is reserved.
+
+``NBFT_HFI_INFO_TCP_GLOBAL_ROUTE``
+ Global Route vs. Link Local Override Flag:
+ if set to 1h, then the BIOS utilized this
+ interface described by HFI to be the default
+ route with highest priority. If cleared to 0h,
+ then routes are local to their own scope.
+
+``NBFT_HFI_INFO_TCP_DHCP_OVERRIDE``
+ DHCP Override: if set to 1, then HFI information
+ was populated by consuming the DHCP on this
+ interface. If cleared to 0h, then the HFI
+ information was set administratively by
+ a configuration interface to the driver and
+ pre-OS envrionment.
+
+
+
+
+.. c:struct:: nbft_ssns
+
+ Subsystem Namespace (SSNS) Descriptor (Figure 15)
+
+**Definition**
+
+::
+
+ struct nbft_ssns {
+ __u8 structure_id;
+ __le16 index;
+ __le16 flags;
+ __u8 trtype;
+ __le16 trflags;
+ __u8 primary_discovery_ctrl_index;
+ __u8 reserved1;
+ struct nbft_heap_obj subsys_traddr_obj;
+ struct nbft_heap_obj subsys_trsvcid_obj;
+ __le16 subsys_port_id;
+ __le32 nsid;
+ __u8 nidt;
+ __u8 nid[16];
+ __u8 security_desc_index;
+ __u8 primary_hfi_desc_index;
+ __u8 reserved2;
+ struct nbft_heap_obj secondary_hfi_assoc_obj;
+ struct nbft_heap_obj subsys_ns_nqn_obj;
+ struct nbft_heap_obj ssns_extended_info_desc_obj;
+ __u8 reserved3[62];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 4h
+ (i.e., SSNS; #NBFT_DESC_SSNS).
+
+``index``
+ SSNS Descriptor Index: This field indicates the number
+ of this Subsystem Namespace Descriptor in the
+ Subsystem Namespace Descriptor List.
+
+``flags``
+ SSNS Flags, see :c:type:`enum nbft_ssns_flags <nbft_ssns_flags>`.
+
+``trtype``
+ Transport Type, see :c:type:`enum nbft_trtype <nbft_trtype>`.
+
+``trflags``
+ Transport Specific Flags, see :c:type:`enum nbft_ssns_trflags <nbft_ssns_trflags>`.
+
+``primary_discovery_ctrl_index``
+ Primary Discovery Controller Index: The Discovery
+ Descriptor Index field of the Discovery Descriptor
+ (see :c:type:`struct nbft_discovery <nbft_discovery>`) that is associated with
+ this SSNS Descriptor. If a Discovery controller was
+ used to establish this record this value shall
+ be set to a non-zero value. If this namespace was
+ associated with multiple Discovery controllers,
+ those Discovery controllers shall have records
+ in the Discovery Descriptor to facilitate multi-path
+ rediscovery as required. If no Discovery controller
+ was utilized to inform this namespace record,
+ this field shall be cleared to 0h.
+
+``reserved1``
+ Reserved.
+
+``subsys_traddr_obj``
+ Subsystem Transport Address Heap Object Reference:
+ This field indicates the location and size of a heap
+ object containing the Subsystem Transport Address.
+ For IP based transports types, shall be an IP Address.
+
+``subsys_trsvcid_obj``
+ Subsystem Transport Service Identifier Heap Object Reference:
+ This field indicates the location and size of a heap
+ object containing an array of bytes indicating
+ the Subsystem Transport Service Identifier.
+ See :c:type:`enum nbft_trtype <nbft_trtype>`.
+
+``subsys_port_id``
+ Subsystem Port ID: Port in the NVM subsystem
+ associated with this transport address used by
+ the pre-OS driver.
+
+``nsid``
+ Namespace ID: This field indicates the namespace
+ identifier (NSID) of the namespace indicated by
+ this descriptor. This field shall be cleared to 0h
+ if not specified by the user. If this value is cleared
+ to 0h, then consumers of the NBFT shall rely
+ on the NID.
+
+``nidt``
+ Namespace Identifier Type (NIDT): This field
+ contains the value of the Namespace Identifier Type (NIDT)
+ field in the Namespace Identification Descriptor
+ for the namespace indicated by this descriptor.
+ If a namespace supports multiple NIDT entries
+ for uniqueness, the order of preference is NIDT field
+ value of 3h (i.e., UUID) before 2h (i.e., NSGUID),
+ and 2h before 1h (i.e., EUI-64).
+
+``nid``
+ Namespace Identifier (NID): This field contains
+ the value of the Namespace Identifier (NID) field
+ in the Namespace Identification Descriptor for
+ the namespace indicated by this descriptor.
+
+``security_desc_index``
+ Security Profile Descriptor Index: If the Use Security
+ Flag bit in the SSNS Flags field is set to 1h, then
+ this field indicates the value of the Security Profile
+ Descriptor Index field of the Security Profile
+ Descriptor (see :c:type:`struct nbft_security <nbft_security>`) associated
+ with this namespace. If the Use Security Flag bit
+ is cleared to 0h, then no Security Profile Descriptor
+ is associated with this namespace and this field
+ is reserved.
+
+``primary_hfi_desc_index``
+ Primary HFI Descriptor Index: This field indicates
+ the value of the HFI Descriptor Index field of the
+ HFI Descriptor (see :c:type:`struct nbft_hfi <nbft_hfi>`) for the
+ interface associated with this namespace. If multiple
+ HFIs are associated with this record, subsequent
+ interfaces should be populated in the Secondary
+ HFI Associations field.
+
+``reserved2``
+ Reserved.
+
+``secondary_hfi_assoc_obj``
+ Secondary HFI Associations Heap Object Reference:
+ If this field is set to a non-zero value, then
+ this field indicates an array of bytes, in which
+ each byte contains the value of the HFI Descriptor
+ Index field of an HFI Descriptor in the HFI Descriptor
+ List. If this field is cleared to 0h, then no
+ secondary HFI associations are specified.
+
+``subsys_ns_nqn_obj``
+ Subsystem and Namespace NQN Heap Object Reference:
+ This field indicates the location and size of
+ a heap object containing the Subsystem and Namespace NQN.
+
+``ssns_extended_info_desc_obj``
+ SSNS Extended Information Descriptor Heap Object
+ Reference: If the SSNS Extended Info In-use Flag
+ bit is set to 1h, then this field indicates the
+ offset in bytes of a heap object containing an
+ SSNS Extended Information Descriptor
+ (see :c:type:`struct nbft_ssns_ext_info <nbft_ssns_ext_info>`) heap object
+ from byte offset 0h of the NBFT Table Header.
+ If the SSNS Extended Info In-use Flag bit is cleared
+ to 0h, then this field is reserved.
+
+``reserved3``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_ssns_flags
+
+ Subsystem and Namespace Specific Flags Field (Figure 16)
+
+**Constants**
+
+``NBFT_SSNS_VALID``
+ Descriptor Valid: If set to 1h, then this descriptor
+ is valid. If cleared to 0h, then this descriptor
+ is not valid. A host that supports NVMe-oF Boot,
+ but does not currently have a remote Subsystem
+ and Namespace assigned may clear this bit to 0h.
+
+``NBFT_SSNS_NON_BOOTABLE_ENTRY``
+ Non-bootable Entry Flag: If set to 1h, this flag
+ indicates that this SSNS Descriptor contains
+ a namespace of administrative purpose to the boot
+ process, but the pre-OS may not have established
+ connectivity to or evaluated the contents of this
+ Descriptor. Such namespaces may contain supplemental
+ data deemed relevant by the Administrator as part
+ of the pre-OS to OS hand off. This may include
+ properties such as a UEFI device path that may
+ not have been created for this namespace. This means
+ an OS runtime may still require the contents
+ of such a namespace to complete later stages
+ of boot. If cleared to 0h, then this namespace did
+ not have any special administrative intent.
+
+``NBFT_SSNS_USE_SECURITY_FIELD``
+ Use Security Flag: If set to 1h, then there is
+ a Security Profile Descriptor associated with this
+ SSNS record and the Security Profile Descriptor Index
+ field is valid. If cleared to 0h, then there is
+ no Security Profile Descriptor associated with this
+ SSNS record and the Security Profile Descriptor Index
+ field is not valid.
+
+``NBFT_SSNS_DHCP_ROOT_PATH_OVERRIDE``
+ DHCP Root-Path Override Flag: If set to 1h, then
+ this SSNS descriptor was populated by consuming
+ the DHCP Root-Path on this interface. If cleared
+ to 0h, then the DHCP Root-Path was not used
+ in populating the SSNS descriptor.
+
+``NBFT_SSNS_EXTENDED_INFO_IN_USE``
+ SSNS Extended Info In-use Flag: If set to 1h,
+ then the SSNS Extended Information Offset field
+ and the SSNS Extended Information Length field
+ are valid. This flag, if set to 1h, indicates
+ that a Subsystem and Namespace Extended Information
+ Descriptor corresponding to this descriptor is present.
+
+``NBFT_SSNS_SEPARATE_DISCOVERY_CTRL``
+ Separate Discovery Controller Flag: If set to 1h,
+ then the Discovery controller associated with
+ this volume is on a different transport address
+ than the specified in the Subsystem Transport
+ Address Heap Object Reference. If cleared to 0h,
+ then the Discovery controller is the same as the
+ Subsystem Transport Address Heap Object Reference.
+
+``NBFT_SSNS_DISCOVERED_NAMESPACE``
+ Discovered Namespace Flag: If set to 1h, then
+ this namespace was acquired through discovery.
+ If cleared to 0h, then this namespace was
+ explicitly configured in the system.
+
+``NBFT_SSNS_UNAVAIL_NAMESPACE_MASK``
+ Mask to get Unavailable Namespace Flag: This
+ field indicates the availability of the namespace
+ at a specific point in time. Such use is only
+ a hint and its use does not guarantee the availability
+ of that referenced namespace at any future point in time.
+
+``NBFT_SSNS_UNAVAIL_NAMESPACE_NOTIND``
+ Not Indicated by Driver: No information is provided.
+
+``NBFT_SSNS_UNAVAIL_NAMESPACE_AVAIL``
+ Available: A referenced namespace described by this
+ flag was previously accessible by the pre-OS driver.
+
+``NBFT_SSNS_UNAVAIL_NAMESPACE_UNAVAIL``
+ Unavailable: This namespace was administratively
+ configured but unattempted, unavailable or
+ inaccessible when establishing connectivity
+ by the pre-OS driver.
+
+
+
+
+.. c:enum:: nbft_ssns_trflags
+
+ SSNS Transport Specific Flags Field (Figure 17)
+
+**Constants**
+
+``NBFT_SSNS_TRFLAG_VALID``
+ Transport Specific Flags in Use: If set to 1h, then
+ this descriptor is valid. If cleared to 0h, then
+ this descriptor is not valid.
+
+``NBFT_SSNS_PDU_HEADER_DIGEST``
+ PDU Header Digest (HDGST) Flag: If set to 1h, then
+ the host or administrator required the connection
+ described by this Subsystem and Namespace Descriptor
+ to use the NVM Header Digest Enabled. A consumer
+ of this information should attempt to use NVM Header
+ Digest when recreating this connection if enabled.
+ If cleared to 0h, then the host or administrator
+ did not require the connection described by this
+ Subsystem and Namespace Descriptor to use the
+ NVM Header Digest Enabled.
+
+``NBFT_SSNS_DATA_DIGEST``
+ Data Digest (DDGST) Flag: If set to 1h, then
+ the host or administrator required the connection
+ described by this Subsystem and Namespace Descriptor
+ to use the NVM Data Digest Enabled. If cleared
+ to 0h, then the host or administrator did not
+ require the connection described by this Subsystem
+ and Namespace Descriptor to use the NVM Data Digest
+ Enabled. A consumer of this field should attempt
+ to use NVM Data Digest when recreating this
+ connection if enabled.
+
+
+
+
+.. c:struct:: nbft_ssns_ext_info
+
+ Subsystem and Namespace Extended Information Descriptor (Figure 19)
+
+**Definition**
+
+::
+
+ struct nbft_ssns_ext_info {
+ __u8 structure_id;
+ __u8 version;
+ __le16 ssns_index;
+ __le32 flags;
+ __le16 cntlid;
+ __le16 asqsz;
+ struct nbft_heap_obj dhcp_root_path_str_obj;
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 9h
+ (i.e., SSNS Extended Info; #NBFT_DESC_SSNS_EXT_INFO).
+
+``version``
+ Version: This field shall be set to 1h.
+
+``ssns_index``
+ SSNS Descriptor Index: This field indicates the value
+ of the SSNS Descriptor Index field of the Subsystem
+ and Namespace Descriptor (see :c:type:`struct nbft_ssns <nbft_ssns>`) whose
+ SSNS Extended Information Descriptor Heap Object
+ Reference field indicates this descriptor.
+
+``flags``
+ Flags, see :c:type:`enum nbft_ssns_ext_info_flags <nbft_ssns_ext_info_flags>`.
+
+``cntlid``
+ Controller ID: The controller identifier of the first
+ controller associated with the Admin Queue by the driver.
+ If a controller identifier is not administratively
+ specified or direct configuration is not supported
+ by the driver, then this field shall be cleared to 0h.
+
+``asqsz``
+ Admin Submission Queue Size (ASQSZ): The Admin Submission
+ Queue Size utilized for the respective SSNS by the driver.
+
+``dhcp_root_path_str_obj``
+ DHCP Root Path String Heap Object Reference: If the
+ SSNS DHCP Root Path Override (#NBFT_SSNS_DHCP_ROOT_PATH_OVERRIDE)
+ flag bit is set to 1h, then this field indicates
+ the offset in bytes of a heap object containing
+ an DHCP Root Path String used by the driver. If the
+ SNSS DHCP Root Path Override flag bit is cleared to 0h,
+ then this field is reserved.
+
+
+
+
+
+.. c:enum:: nbft_ssns_ext_info_flags
+
+ Subsystem and Namespace Extended Information Descriptor Flags
+
+**Constants**
+
+``NBFT_SSNS_EXT_INFO_VALID``
+ Descriptor Valid: If set to 1h, then this descriptor
+ is valid. If cleared to 0h, then this descriptor
+ is reserved.
+
+``NBFT_SSNS_EXT_INFO_ADMIN_ASQSZ``
+ Administrative ASQSZ: If set to 1h, then the value
+ of the ASQSZ field was provided by administrative
+ configuration for this SSNS record. If cleared
+ to 0h, then the value of the ASQSZ field was
+ either obtained by discovery or assumed
+ by the driver.
+
+
+
+
+.. c:struct:: nbft_security
+
+ Security Profile Descriptor (Figure 21)
+
+**Definition**
+
+::
+
+ struct nbft_security {
+ __u8 structure_id;
+ __u8 index;
+ __le16 flags;
+ __u8 secret_type;
+ __u8 reserved1;
+ struct nbft_heap_obj sec_chan_alg_obj;
+ struct nbft_heap_obj auth_proto_obj;
+ struct nbft_heap_obj cipher_suite_obj;
+ struct nbft_heap_obj dh_grp_obj;
+ struct nbft_heap_obj sec_hash_func_obj;
+ struct nbft_heap_obj sec_keypath_obj;
+ __u8 reserved2[22];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 5h
+ (i.e., Security; #NBFT_DESC_SECURITY).
+
+``index``
+ Security Profile Descriptor Index: This field indicates
+ the number of this Security Profile Descriptor in the
+ Security Profile Descriptor List.
+
+``flags``
+ Security Profile Descriptor Flags, see :c:type:`enum nbft_security_flags <nbft_security_flags>`.
+
+``secret_type``
+ Secret Type, see :c:type:`enum nbft_security_secret_type <nbft_security_secret_type>`.
+
+``reserved1``
+ Reserved.
+
+``sec_chan_alg_obj``
+ Secure Channel Algorithm Heap Object Reference: If the
+ Security Policy List field is set to 1h, then this field
+ indicates the location and size of a heap object containing
+ a list of secure channel algorithms. The list is an array
+ of bytes and the values are defined in the Security Type
+ (SECTYPE) field in the Transport Specific Address Subtype
+ Definition in the NVMe TCP Transport Specification.
+ If the Security Policy List field is cleared to 0h, then
+ this field is reserved.
+
+``auth_proto_obj``
+ Authentication Protocols Heap Object Reference: If the
+ Authentication Policy List field is set to 1h, then this
+ field indicates the location and size of a heap object
+ containing a list of authentication protocol identifiers.
+ If the Authentication Policy List field is cleared to 0h,
+ then this field is reserved.
+
+``cipher_suite_obj``
+ Cipher Suite Offset Heap Object Reference: If the Cipher
+ Suites Restricted by Policy bit is set to 1h, then this
+ field indicates the location and size of a heap object
+ containing a list of cipher suite identifiers. The list,
+ if any, is an array of bytes and the values are defined
+ in the IANA TLS Parameters Registry. If the Cipher Suites
+ Restricted by Policy bit is cleared to 0h, then this field
+ is reserved.
+
+``dh_grp_obj``
+ DH Groups Heap Object Reference: If the Authentication DH Groups
+ Restricted by Policy List bit is set to 1h, then this field
+ indicates the location and size of a heap object containing
+ a list of DH-HMAC-CHAP Diffie-Hellman (DH) group identifiers.
+ If the Authentication DH Groups Restricted by Policy List
+ bit is cleared to 0h, then this field is reserved.
+
+``sec_hash_func_obj``
+ Secure Hash Functions Offset Heap Object Reference: If the
+ Secure Hash Functions Policy List bit is set to 1h, then
+ this field indicates the offset in bytes of a heap object
+ containing a list of DH-HMAC-CHAP hash function identifiers.
+ The list is an array of bytes and the values are defined
+ in the NVM Express Base Specification. If the Secure Hash
+ Functions Policy List bit is cleared to 0h, then this
+ field is reserved.
+
+``sec_keypath_obj``
+ Secret Keypath Offset Heap Object Reference: if this field
+ is set to a non-zero value, then this field indicates
+ the location and size of a heap object containing a URI.
+ The type of the URI is specified in the Secret Type field.
+ If this field is cleared to 0h, then this field is reserved.
+
+``reserved2``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_security_flags
+
+ Security Profile Descriptor Flags (Figure 22)
+
+**Constants**
+
+``NBFT_SECURITY_VALID``
+ Descriptor Valid: If set to 1h, then
+ this descriptor is valid. If cleared
+ to 0h, then this descriptor is not valid.
+
+``NBFT_SECURITY_IN_BAND_AUTH_MASK``
+ Mask to get the In-Band Authentication
+ Required field.
+
+``NBFT_SECURITY_IN_BAND_AUTH_NOT_SUPPORTED``
+ In-band authentication is not supported
+ by the NVM subsystem.
+
+``NBFT_SECURITY_IN_BAND_AUTH_NOT_REQUIRED``
+ In-band authentication is supported by
+ the NVM subsystem and is not required.
+
+``NBFT_SECURITY_IN_BAND_AUTH_REQUIRED``
+ In-band authentication is supported by
+ the NVM subsystem and is required.
+
+``NBFT_SECURITY_AUTH_POLICY_LIST_MASK``
+ Mask to get the Authentication Policy List
+ flag: This field indicates whether
+ authentication protocols were indicated
+ by policy from driver defaults or
+ administrative configuration.
+
+``NBFT_SECURITY_AUTH_POLICY_LIST_NOT_SUPPORTED``
+ Authentication Protocols Heap Object Reference
+ field Offset and Length are reserved.
+
+``NBFT_SECURITY_AUTH_POLICY_LIST_DRIVER``
+ Authentication Protocols Offset field and
+ the Authentication Protocols Length field
+ indicate a list of authentication protocols
+ used by the driver.
+
+``NBFT_SECURITY_AUTH_POLICY_LIST_ADMIN``
+ Authentication Protocols Offset field and
+ the Authentication Protocols Length field
+ indicate a list of authentication protocols
+ that were administratively set and used
+ by the driver.
+
+``NBFT_SECURITY_SEC_CHAN_NEG_MASK``
+ Mask to get the Secure Channel Negotiation
+ Required flag: This field indicates whether
+ secure channel negotiation (e.g. TLS)
+ is required.
+
+``NBFT_SECURITY_SEC_CHAN_NEG_NOT_SUPPORTED``
+ Secure channel negotiation is not supported
+ by the NVM subsystem.
+
+``NBFT_SECURITY_SEC_CHAN_NEG_NOT_REQUIRED``
+ Secure channel negotiation is supported
+ by the NVM subsystem and is not required.
+
+``NBFT_SECURITY_SEC_CHAN_NEG_REQUIRED``
+ Secure channel negotiation is supported
+ by the NVM subsystem and is required.
+
+``NBFT_SECURITY_SEC_POLICY_LIST_MASK``
+ Mask to get the Security Policy List flag:
+ This field indicates whether secure channel
+ protocols were indicated by policy from driver
+ defaults or administrative configuration.
+
+``NBFT_SECURITY_SEC_POLICY_LIST_NOT_SUPPORTED``
+ The Offset field and Length field in the
+ Secure Channel Algorithm Heap Object Reference
+ field are reserved.
+
+``NBFT_SECURITY_SEC_POLICY_LIST_DRIVER``
+ The Heap Object specified by the Secure Channel
+ Algorithm Heap Object Reference field indicates
+ a list of authentication protocols used
+ by the driver.
+
+``NBFT_SECURITY_SEC_POLICY_LIST_ADMIN``
+ The Heap Object specified by the Secure Channel
+ Algorithm Heap Object Reference field indicates
+ a list of authentication protocols that were
+ administratively set and used by the driver.
+
+``NBFT_SECURITY_CIPHER_RESTRICTED``
+ Cipher Suites Restricted by Policy: If set to 1h,
+ then the Cipher Suite Offset field and the
+ Ciper Suite Length field indicate a list
+ of supported cipher suites by the driver.
+ If cleared to 0h, then the Cipher Suite Offset
+ field and the Cipher Suite Length field
+ are reserved.
+
+``NBFT_SECURITY_AUTH_DH_GROUPS_RESTRICTED``
+ Authentication DH Groups Restricted
+ by Policy List: If set to 1h, then connections
+ shall use one of the authentication DH groups
+ in the Authentication DH Groups List is required.
+ If cleared to 0h, then no Authentication DH Groups
+ List is indicated and use of an authentication
+ DH Group is not required.
+
+``NBFT_SECURITY_SEC_HASH_FUNC_POLICY_LIST``
+ Secure Hash Functions Policy List: If set to 1h,
+ then connections shall use one of the secure
+ hash functions in the Secure Hash Functions
+ Policy List is required. If cleared to 0h,
+ then no Secure Hash Functions Policy
+ List is indicated and use of a secure
+ hash function is not required.
+
+
+
+
+.. c:enum:: nbft_security_secret_type
+
+ Security Profile Descriptor Secret Type
+
+**Constants**
+
+``NBFT_SECURITY_SECRET_REDFISH_HOST_IFACE_URI``
+ Redfish Host Interface URI:
+ If set to 1h, then the Secret Keypath
+ Object Reference is a URI pointing
+ to a Redfish Key Collection Object
+ that contains the PSK.
+
+
+
+
+.. c:struct:: nbft_discovery
+
+ Discovery Descriptor (Figure 24)
+
+**Definition**
+
+::
+
+ struct nbft_discovery {
+ __u8 structure_id;
+ __u8 flags;
+ __u8 index;
+ __u8 hfi_index;
+ __u8 sec_index;
+ __u8 reserved1;
+ struct nbft_heap_obj discovery_ctrl_addr_obj;
+ struct nbft_heap_obj discovery_ctrl_nqn_obj;
+ __u8 reserved2[14];
+ };
+
+**Members**
+
+``structure_id``
+ Structure ID: This field shall be set to 6h
+ (i.e., Discovery Descriptor; #NBFT_DESC_DISCOVERY).
+
+``flags``
+ Discovery Descriptor Flags, see :c:type:`enum nbft_discovery_flags <nbft_discovery_flags>`.
+
+``index``
+ Discovery Descriptor Index: This field indicates
+ the number of this Discovery Descriptor in
+ the Discovery Descriptor List.
+
+``hfi_index``
+ HFI Descriptor Index: This field indicates the value
+ of the HFI Descriptor Index field of the HFI Descriptor
+ associated with this Discovery Descriptor. If multiple
+ HFIs share a common Discovery controller, there shall
+ be multiple Discovery Descriptor entries with one per HFI.
+
+``sec_index``
+ Security Profile Descriptor Index: This field indicates
+ the value of the Security Profile Descriptor Index
+ field of the Security Descriptor associated with
+ this Discovery Descriptor.
+
+``reserved1``
+ Reserved.
+
+``discovery_ctrl_addr_obj``
+ Discovery Controller Address Heap Object Reference:
+ This field indicates the location and size of a heap
+ object containing a URI which indicates an NVMe Discovery
+ controller associated with this Discovery Descriptor.
+ If this field is cleared to 0h, then no URI is specified.
+
+``discovery_ctrl_nqn_obj``
+ Discovery Controller NQN Heap Object Reference:
+ If set to a non-zero value, this field indicates
+ the location and size of a heap object containing
+ an NVMe Discovery controller NQN. If the NVMe Discovery
+ controller referenced by this record requires secure
+ authentication with a well known Subsystem NQN, this
+ field indicates the unique NQN for that NVMe Discovery
+ controller. This record is involved formatted as an NQN
+ string. If this field is cleared to 0h, then this
+ field is reserved and the OS shall use the well
+ known discovery NQN for this record.
+
+``reserved2``
+ Reserved.
+
+
+
+
+
+.. c:enum:: nbft_discovery_flags
+
+ Discovery Descriptor Flags
+
+**Constants**
+
+``NBFT_DISCOVERY_VALID``
+ Descriptor Valid: if set to 1h, then this descriptor
+ is valid. If cleared to 0h, then this descriptor
+ is reserved.
+
+
+
+
+.. c:enum:: nbft_info_primary_admin_host_flag
+
+ Primary Administrative Host Descriptor Flags
+
+**Constants**
+
+``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_NOT_INDICATED``
+ Not Indicated by Driver: The driver
+ that created this NBFT provided no
+ administrative priority hint for
+ this NBFT.
+
+``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_UNSELECTED``
+ Unselected: The driver that created
+ this NBFT explicitly indicated that
+ this NBFT should not be prioritized
+ over any other NBFT.
+
+``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_SELECTED``
+ Selected: The driver that created
+ this NBFT explicitly indicated that
+ this NBFT should be prioritized over
+ any other NBFT.
+
+``NBFT_INFO_PRIMARY_ADMIN_HOST_FLAG_RESERVED``
+ Reserved.
+
+
+
+
+.. c:struct:: nbft_info_host
+
+ Host Descriptor
+
+**Definition**
+
+::
+
+ struct nbft_info_host {
+ unsigned char *id;
+ char *nqn;
+ bool host_id_configured;
+ bool host_nqn_configured;
+ enum nbft_info_primary_admin_host_flag primary;
+ };
+
+**Members**
+
+``id``
+ Host ID (raw UUID, length = 16 bytes).
+
+``nqn``
+ Host NQN.
+
+``host_id_configured``
+ HostID Configured Flag: value of True indicates that **id**
+ contains administratively-configured value, or driver
+ default value if False.
+
+``host_nqn_configured``
+ Host NQN Configured Flag: value of True indicates that
+ **nqn** contains administratively-configured value,
+ or driver default value if False.
+
+``primary``
+ Primary Administrative Host Descriptor, see
+ :c:type:`enum nbft_info_primary_admin_host_flag <nbft_info_primary_admin_host_flag>`.
+
+
+
+
+
+.. c:struct:: nbft_info_hfi_info_tcp
+
+ HFI Transport Info Descriptor - NVMe/TCP
+
+**Definition**
+
+::
+
+ struct nbft_info_hfi_info_tcp {
+ __u32 pci_sbdf;
+ __u8 mac_addr[6];
+ __u16 vlan;
+ __u8 ip_origin;
+ char ipaddr[40];
+ __u8 subnet_mask_prefix;
+ char gateway_ipaddr[40];
+ __u16 route_metric;
+ char primary_dns_ipaddr[40];
+ char secondary_dns_ipaddr[40];
+ char dhcp_server_ipaddr[40];
+ char *host_name;
+ bool this_hfi_is_default_route;
+ bool dhcp_override;
+ };
+
+**Members**
+
+``pci_sbdf``
+ PCI Express Routing ID for the HFI Transport Function.
+
+``mac_addr``
+ MAC Address: The MAC address of this HFI,
+ in EUI-48TM format.
+
+``vlan``
+ The VLAN identifier if the VLAN is associated with
+ this HFI, as defined in IEEE 802.1q-2018 or zeroes
+ if no VLAN is associated with this HFI.
+
+``ip_origin``
+ The source of Ethernet L3 configuration information
+ used by the driver or 0 if not used.
+
+``ipaddr``
+ The IPv4 or IPv6 address of this HFI.
+
+``subnet_mask_prefix``
+ The IPv4 or IPv6 subnet mask in CIDR routing prefix
+ notation.
+
+``gateway_ipaddr``
+ The IPv4 or IPv6 address of the IP gateway for this
+ HFI or zeroes if no IP gateway is specified.
+
+``route_metric``
+ The cost value for the route indicated by this HFI.
+
+``primary_dns_ipaddr``
+ The IPv4 or IPv6 address of the Primary DNS server
+ for this HFI.
+
+``secondary_dns_ipaddr``
+ The IPv4 or IPv6 address of the Secondary DNS server
+ for this HFI.
+
+``dhcp_server_ipaddr``
+ The IPv4 or IPv6 address of the DHCP server used
+ to assign this HFI address.
+
+``host_name``
+ The Host Name string.
+
+``this_hfi_is_default_route``
+ If True, then the BIOS utilized this interface
+ described by HFI to be the default route with highest
+ priority. If False, then routes are local to their
+ own scope.
+
+``dhcp_override``
+ If True, then HFI information was populated
+ by consuming the DHCP on this interface. If False,
+ then the HFI information was set administratively
+ by a configuration interface to the driver and
+ pre-OS envrionment.
+
+
+
+
+
+.. c:struct:: nbft_info_hfi
+
+ Host Fabric Interface (HFI) Descriptor
+
+**Definition**
+
+::
+
+ struct nbft_info_hfi {
+ int index;
+ char transport[8];
+ struct nbft_info_hfi_info_tcp tcp_info;
+ };
+
+**Members**
+
+``index``
+ HFI Descriptor Index: indicates the number of this HFI Descriptor
+ in the Host Fabric Interface Descriptor List.
+
+``transport``
+ Transport Type string (e.g. 'tcp').
+
+``tcp_info``
+ The HFI Transport Info Descriptor, see :c:type:`struct nbft_info_hfi_info_tcp <nbft_info_hfi_info_tcp>`.
+
+
+
+
+
+.. c:struct:: nbft_info_discovery
+
+ Discovery Descriptor
+
+**Definition**
+
+::
+
+ struct nbft_info_discovery {
+ int index;
+ struct nbft_info_security *security;
+ struct nbft_info_hfi *hfi;
+ char *uri;
+ char *nqn;
+ };
+
+**Members**
+
+``index``
+ The number of this Discovery Descriptor in the Discovery
+ Descriptor List.
+
+``security``
+ The Security Profile Descriptor, see :c:type:`struct nbft_info_security <nbft_info_security>`.
+
+``hfi``
+ The HFI Descriptor associated with this Discovery Descriptor.
+ See :c:type:`struct nbft_info_hfi <nbft_info_hfi>`.
+
+``uri``
+ A URI which indicates an NVMe Discovery controller associated
+ with this Discovery Descriptor.
+
+``nqn``
+ An NVMe Discovery controller NQN.
+
+
+
+
+
+.. c:struct:: nbft_info_security
+
+ Security Profile Descriptor
+
+**Definition**
+
+::
+
+ struct nbft_info_security {
+ int index;
+ };
+
+**Members**
+
+``index``
+ The number of this Security Profile Descriptor in the Security
+ Profile Descriptor List.
+
+
+
+
+
+.. c:enum:: nbft_info_nid_type
+
+ Namespace Identifier Type (NIDT)
+
+**Constants**
+
+``NBFT_INFO_NID_TYPE_NONE``
+ No identifier available.
+
+``NBFT_INFO_NID_TYPE_EUI64``
+ The EUI-64 identifier.
+
+``NBFT_INFO_NID_TYPE_NGUID``
+ The NSGUID identifier.
+
+``NBFT_INFO_NID_TYPE_NS_UUID``
+ The UUID identifier.
+
+
+
+
+.. c:struct:: nbft_info_subsystem_ns
+
+ Subsystem Namespace (SSNS) info
+
+**Definition**
+
+::
+
+ struct nbft_info_subsystem_ns {
+ int index;
+ struct nbft_info_discovery *discovery;
+ struct nbft_info_security *security;
+ int num_hfis;
+ struct nbft_info_hfi **hfis;
+ char transport[8];
+ char traddr[40];
+ char *trsvcid;
+ __u16 subsys_port_id;
+ __u32 nsid;
+ enum nbft_info_nid_type nid_type;
+ __u8 *nid;
+ char *subsys_nqn;
+ bool pdu_header_digest_required;
+ bool data_digest_required;
+ int controller_id;
+ int asqsz;
+ char *dhcp_root_path_string;
+ };
+
+**Members**
+
+``index``
+ SSNS Descriptor Index in the descriptor list.
+
+``discovery``
+ Primary Discovery Controller associated with
+ this SSNS Descriptor.
+
+``security``
+ Security Profile Descriptor associated with
+ this namespace.
+
+``num_hfis``
+ Number of HFIs.
+
+``hfis``
+ List of HFIs associated with this namespace.
+ Includes the primary HFI at the first position
+ and all secondary HFIs. This array is null-terminated.
+
+``transport``
+ Transport Type string (e.g. 'tcp').
+
+``traddr``
+ Subsystem Transport Address.
+
+``trsvcid``
+ Subsystem Transport Service Identifier.
+
+``subsys_port_id``
+ The Subsystem Port ID.
+
+``nsid``
+ The Namespace ID of this descriptor or when **nid**
+ should be used instead.
+
+``nid_type``
+ Namespace Identifier Type, see :c:type:`enum nbft_info_nid_type <nbft_info_nid_type>`.
+
+``nid``
+ The Namespace Identifier value.
+
+``subsys_nqn``
+ Subsystem and Namespace NQN.
+
+``pdu_header_digest_required``
+ PDU Header Digest (HDGST) Flag: the use of NVM Header
+ Digest Enabled is required.
+
+``data_digest_required``
+ Data Digest (DDGST) Flag: the use of NVM Data Digest
+ Enabled is required.
+
+``controller_id``
+ Controller ID (SSNS Extended Information Descriptor):
+ The controller ID associated with the Admin Queue
+ or 0 if not supported.
+
+``asqsz``
+ Admin Submission Queue Size (SSNS Extended Information
+ Descriptor) or 0 if not supported.
+
+``dhcp_root_path_string``
+ DHCP Root Path Override string (SSNS Extended
+ Information Descriptor).
+
+
+
+
+
+.. c:struct:: nbft_info
+
+ The parsed NBFT table data.
+
+**Definition**
+
+::
+
+ struct nbft_info {
+ char *filename;
+ __u8 *raw_nbft;
+ ssize_t raw_nbft_size;
+ struct nbft_info_host host;
+ struct nbft_info_hfi **hfi_list;
+ struct nbft_info_security **security_list;
+ struct nbft_info_discovery **discovery_list;
+ struct nbft_info_subsystem_ns **subsystem_ns_list;
+ };
+
+**Members**
+
+``filename``
+ Path to the NBFT table.
+
+``raw_nbft``
+ The original NBFT table contents.
+
+``raw_nbft_size``
+ Size of **raw_nbft**.
+
+``host``
+ The Host Descriptor (should match other NBFTs).
+
+``hfi_list``
+ The HFI Descriptor List (null-terminated array).
+
+``security_list``
+ The Security Profile Descriptor List (null-terminated array).
+
+``discovery_list``
+ The Discovery Descriptor List (null-terminated array).
+
+``subsystem_ns_list``
+ The SSNS Descriptor List (null-terminated array).
+
+
+
+.. c:function:: int nvme_nbft_read (struct nbft_info **nbft, const char *filename)
+
+ Read and parse contents of an ACPI NBFT table
+
+**Parameters**
+
+``struct nbft_info **nbft``
+ Parsed NBFT table data.
+
+``const char *filename``
+ Filename of the raw NBFT table to read.
+
+**Description**
+
+Read and parse the specified NBFT file into a struct nbft_info.
+Free with nvme_nbft_free().
+
+**Return**
+
+0 on success, errno otherwise.
+
+
+.. c:function:: void nvme_nbft_free (struct nbft_info *nbft)
+
+ Free the struct nbft_info and its contents
+
+**Parameters**
+
+``struct nbft_info *nbft``
+ Parsed NBFT table data.
+
+
diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst
index 9a8bb3f..f964ec6 100644
--- a/doc/rst/tree.rst
+++ b/doc/rst/tree.rst
@@ -22,6 +22,37 @@ libnvme tree object interface
Initialized :c:type:`nvme_root_t` object
+.. c:function:: void nvme_root_set_application (nvme_root_t r, const char *a)
+
+ Specify managing application
+
+**Parameters**
+
+``nvme_root_t r``
+ :c:type:`nvme_root_t` object
+
+``const char *a``
+ Application string
+
+**Description**
+
+Sets the managing application string for **r**.
+
+
+.. c:function:: const char * nvme_root_get_application (nvme_root_t r)
+
+ Get managing application
+
+**Parameters**
+
+``nvme_root_t r``
+ :c:type:`nvme_root_t` object
+
+**Description**
+
+Returns the managing application string for **r** or NULL if not set.
+
+
.. c:function:: void nvme_free_tree (nvme_root_t r)
Free root object
@@ -1319,6 +1350,21 @@ NVMe-over-Fabrics address string of **c** or empty string
of no address is present.
+.. c:function:: const char * nvme_ctrl_get_phy_slot (nvme_ctrl_t c)
+
+ PCI physical slot number of a controller
+
+**Parameters**
+
+``nvme_ctrl_t c``
+ Controller instance
+
+**Return**
+
+PCI physical slot number of **c** or empty string if slot
+number is not present.
+
+
.. c:function:: const char * nvme_ctrl_get_firmware (nvme_ctrl_t c)
Firmware string of a controller
@@ -1885,6 +1931,37 @@ Returns the subsystem type of **s**.
'nvm' or 'discovery'
+.. c:function:: const char * nvme_subsystem_get_application (nvme_subsystem_t s)
+
+ Return the application string
+
+**Parameters**
+
+``nvme_subsystem_t s``
+ nvme_subsystem_t object
+
+**Return**
+
+Managing application string or NULL if not set.
+
+
+.. c:function:: void nvme_subsystem_set_application (nvme_subsystem_t s, const char *a)
+
+ Set the application string
+
+**Parameters**
+
+``nvme_subsystem_t s``
+ nvme_subsystem_t object
+
+``const char *a``
+ application string
+
+**Description**
+
+Sets the managing application string for **s**.
+
+
.. c:function:: int nvme_scan_topology (nvme_root_t r, nvme_scan_filter_t f, void *f_args)
Scan NVMe topology and apply filter
diff --git a/doc/rst/types.rst b/doc/rst/types.rst
index 5262202..3c9725a 100644
--- a/doc/rst/types.rst
+++ b/doc/rst/types.rst
@@ -9625,6 +9625,17 @@ entries are of a variable lengths (TEL), TEL is always a multiple of
command requires access to media and
the media is not ready.
+``NVME_SC_FDP_DISABLED``
+ Command is not allowed when
+ Flexible Data Placement is disabled.
+
+``NVME_SC_INVALID_PLACEMENT_HANDLE_LIST``
+ The Placement Handle List is invalid
+ due to invalid Reclaim Unit Handle Identifier or
+ valid Reclaim Unit Handle Identifier but restricted or
+ the Placement Handle List number of entries exceeded the
+ maximum number allowed.
+
``NVME_SC_LBA_RANGE``
LBA Out of Range: The command references
an LBA that exceeds the size of the namespace.
@@ -11752,3 +11763,125 @@ true if **status** is of the specified type and value
Reclaim Unit Handle Update
+
+
+.. c:struct:: nvme_ns_mgmt_host_sw_specified
+
+ Namespace management Host Software Specified Fields.
+
+**Definition**
+
+::
+
+ struct nvme_ns_mgmt_host_sw_specified {
+ __le64 nsze;
+ __le64 ncap;
+ __u8 rsvd16[10];
+ __u8 flbas;
+ __u8 rsvd27[2];
+ __u8 dps;
+ __u8 nmic;
+ __u8 rsvd31[61];
+ __le32 anagrpid;
+ __u8 rsvd96[4];
+ __le16 nvmsetid;
+ __le16 endgid;
+ __u8 rsvd104[280];
+ __le64 lbstm;
+ __le16 nphndls;
+ __u8 rsvd394[105];
+ union {
+ __u8 rsvd499[13];
+ struct {
+ __u8 znsco;
+ __le32 rar;
+ __le32 ror;
+ __le32 rnumzrwa;
+ } zns;
+ };
+ __le16 phndl[128];
+ __u8 rsvd768[3328];
+ };
+
+**Members**
+
+``nsze``
+ Namespace Size indicates the total size of the namespace in
+ logical blocks. The number of logical blocks is based on the
+ formatted LBA size.
+
+``ncap``
+ Namespace Capacity indicates the maximum number of logical blocks
+ that may be allocated in the namespace at any point in time. The
+ number of logical blocks is based on the formatted LBA size.
+
+``rsvd16``
+ Reserved
+
+``flbas``
+ Formatted LBA Size, see :c:type:`enum nvme_id_ns_flbas <nvme_id_ns_flbas>`.
+
+``rsvd27``
+ Reserved
+
+``dps``
+ End-to-end Data Protection Type Settings, see
+ :c:type:`enum nvme_id_ns_dps <nvme_id_ns_dps>`.
+
+``nmic``
+ Namespace Multi-path I/O and Namespace Sharing Capabilities, see
+ :c:type:`enum nvme_id_ns_nmic <nvme_id_ns_nmic>`.
+
+``rsvd31``
+ Reserved
+
+``anagrpid``
+ ANA Group Identifier indicates the ANA Group Identifier of the
+ ANA group of which the namespace is a member.
+
+``rsvd96``
+ Reserved
+
+``nvmsetid``
+ NVM Set Identifier indicates the NVM Set with which this
+ namespace is associated.
+
+``endgid``
+ Endurance Group Identifier indicates the Endurance Group with
+ which this namespace is associated.
+
+``rsvd104``
+ Reserved
+
+``lbstm``
+ Logical Block Storage Tag Mask Identifies the mask for the
+ Storage Tag field for the protection information
+
+``nphndls``
+ Number of Placement Handles specifies the number of Placement
+ Handles included in the Placement Handle List
+
+``rsvd394``
+ Reserved
+
+``{unnamed_union}``
+ anonymous
+
+``rsvd499``
+ Reserved for I/O Command Sets that extend this specification.
+
+``zns``
+ rsvd499( Zoned Namespace Command Set specific field )
+
+``phndl``
+ Placement Handle Associated RUH : This field specifies the Reclaim
+ Unit Handle Identifier to be associated with the Placement Handle
+ value. If the Flexible Data Placement capability is not supported or
+ not enabled in specified Endurance Group, then the controller shall
+ ignore this field.
+
+``rsvd768``
+ Reserved
+
+
+
diff --git a/doc/rst/util.rst b/doc/rst/util.rst
index 4b85492..6f7974e 100644
--- a/doc/rst/util.rst
+++ b/doc/rst/util.rst
@@ -67,6 +67,12 @@ libnvme utility functions
``ENVME_CONNECT_CONNREFUSED``
connection refused
+``ENVME_CONNECT_ADDRNOTAVAIL``
+ cannot assign requested address
+
+``ENVME_CONNECT_IGNORED``
+ connect attempt is ignored due to configuration
+
.. c:function:: __u8 nvme_status_to_errno (int status, bool fabrics)
@@ -575,3 +581,20 @@ https://www.rfc-editor.org/rfc/rfc4122#section-4.4
Returns error code if generating of random number fails.
+.. c:function:: bool nvme_ipaddrs_eq (const char *addr1, const char *addr2)
+
+ Check if 2 IP addresses are equal.
+
+**Parameters**
+
+``const char *addr1``
+ IP address (can be IPv4 or IPv6)
+
+``const char *addr2``
+ IP address (can be IPv4 or IPv6)
+
+**Return**
+
+true if addr1 == addr2. false otherwise.
+
+