API¶

This part of the documentation lists the full API reference of all public classes and functions.

ioctl.h

Linux NVMe ioctl interface functions

struct nvme_passthru_cmd¶: nvme passthrough command structure

Definition

struct nvme_passthru_cmd {
  __u8 opcode;
  __u8 flags;
  __u16 rsvd1;
  __u32 nsid;
  __u32 cdw2;
  __u32 cdw3;
  __u64 metadata;
  __u64 addr;
  __u32 metadata_len;
  __u32 data_len;
  __u32 cdw10;
  __u32 cdw11;
  __u32 cdw12;
  __u32 cdw13;
  __u32 cdw14;
  __u32 cdw15;
  __u32 timeout_ms;
  __u32 result;
};

Members

opcode: Operation code, see enum nvme_io_opcodes and enum nvme_admin_opcodes
flags: Not supported: intended for command flags (eg: SGL, FUSE)
rsvd1: Reserved for future use
nsid: Namespace Identifier, or Fabrics type
cdw2: Command Dword 2 (no spec defined use)
cdw3: Command Dword 3 (no spec defined use)
metadata: User space address to metadata buffer (NULL if not used)
addr: User space address to data buffer (NULL if not used)
metadata_len: Metadata buffer transfer length
data_len: Data buffer transfer length
cdw10: Command Dword 10 (command specific)
cdw11: Command Dword 11 (command specific)
cdw12: Command Dword 12 (command specific)
cdw13: Command Dword 13 (command specific)
cdw14: Command Dword 14 (command specific)
cdw15: Command Dword 15 (command specific)
timeout_ms: If non-zero, overrides system default timeout in milliseconds
result: Set on completion to the command’s CQE DWORD 0 controller response

struct nvme_passthru_cmd64¶: 64-bit nvme passthrough command structure

Definition

struct nvme_passthru_cmd64 {
  __u8 opcode;
  __u8 flags;
  __u16 rsvd1;
  __u32 nsid;
  __u32 cdw2;
  __u32 cdw3;
  __u64 metadata;
  __u64 addr;
  __u32 metadata_len;
  __u32 data_len;
  __u32 cdw10;
  __u32 cdw11;
  __u32 cdw12;
  __u32 cdw13;
  __u32 cdw14;
  __u32 cdw15;
  __u32 timeout_ms;
  __u32 rsvd2;
  __u64 result;
};

Members

opcode: Operation code, see enum nvme_io_opcodes and enum nvme_admin_opcodes
flags: Not supported: intended for command flags (eg: SGL, FUSE)
rsvd1: Reserved for future use
nsid: Namespace Identifier, or Fabrics type
cdw2: Command Dword 2 (no spec defined use)
cdw3: Command Dword 3 (no spec defined use)
metadata: User space address to metadata buffer (NULL if not used)
addr: User space address to data buffer (NULL if not used)
metadata_len: Metadata buffer transfer length
data_len: Data buffer transfer length
cdw10: Command Dword 10 (command specific)
cdw11: Command Dword 11 (command specific)
cdw12: Command Dword 12 (command specific)
cdw13: Command Dword 13 (command specific)
cdw14: Command Dword 14 (command specific)
cdw15: Command Dword 15 (command specific)
timeout_ms: If non-zero, overrides system default timeout in milliseconds
rsvd2: Reserved for future use (and fills an implicit struct pad
result: Set on completion to the command’s CQE DWORD 0-1 controller response

struct nvme_uring_cmd¶: nvme uring command structure

Definition

struct nvme_uring_cmd {
  __u8 opcode;
  __u8 flags;
  __u16 rsvd1;
  __u32 nsid;
  __u32 cdw2;
  __u32 cdw3;
  __u64 metadata;
  __u64 addr;
  __u32 metadata_len;
  __u32 data_len;
  __u32 cdw10;
  __u32 cdw11;
  __u32 cdw12;
  __u32 cdw13;
  __u32 cdw14;
  __u32 cdw15;
  __u32 timeout_ms;
  __u32 rsvd2;
};

Members

opcode: Operation code, see enum nvme_io_opcodes and enum nvme_admin_opcodes
flags: Not supported: intended for command flags (eg: SGL, FUSE)
rsvd1: Reserved for future use
nsid: Namespace Identifier, or Fabrics type
cdw2: Command Dword 2 (no spec defined use)
cdw3: Command Dword 3 (no spec defined use)
metadata: User space address to metadata buffer (NULL if not used)
addr: User space address to data buffer (NULL if not used)
metadata_len: Metadata buffer transfer length
data_len: Data buffer transfer length
cdw10: Command Dword 10 (command specific)
cdw11: Command Dword 11 (command specific)
cdw12: Command Dword 12 (command specific)
cdw13: Command Dword 13 (command specific)
cdw14: Command Dword 14 (command specific)
cdw15: Command Dword 15 (command specific)
timeout_ms: If non-zero, overrides system default timeout in milliseconds
rsvd2: Reserved for future use (and fills an implicit struct pad

sizeof_args¶

sizeof_args (type, member, align)

Helper function used to determine structure sizes

Parameters

type: Argument structure type
member: Member inside the type
align: Alignment information

int nvme_submit_admin_passthru64(int fd, struct nvme_passthru_cmd64 *cmd, __u64 *result)¶: Submit a 64-bit nvme passthrough admin command

Parameters

int fd: File descriptor of nvme device
struct nvme_passthru_cmd64 *cmd: The nvme admin command to send
__u64 *result: Optional field to return the result from the CQE DW0-1

Description

Uses NVME_IOCTL_ADMIN64_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_admin_passthru64(int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u64 *result)¶: Submit a 64-bit nvme passthrough command

Parameters

int fd: File descriptor of nvme device
__u8 opcode: The nvme io command to send
__u8 flags: NVMe command flags (not used)
__u16 rsvd: Reserved for future use
__u32 nsid: Namespace identifier
__u32 cdw2: Command dword 2
__u32 cdw3: Command dword 3
__u32 cdw10: Command dword 10
__u32 cdw11: Command dword 11
__u32 cdw12: Command dword 12
__u32 cdw13: Command dword 13
__u32 cdw14: Command dword 14
__u32 cdw15: Command dword 15
__u32 data_len: Length of the data transferred in this command in bytes
void *data: Pointer to user address of the data buffer
__u32 metadata_len: Length of metadata transferred in this command
void *metadata: Pointer to user address of the metadata buffer
__u32 timeout_ms: How long the kernel waits for the command to complete
__u64 *result: Optional field to return the result from the CQE dword 0

Description

Parameterized form of nvme_submit_admin_passthru64(). This sets up and submits a struct nvme_passthru_cmd64.

Known values for opcode are defined in enum nvme_admin_opcode.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_submit_admin_passthru(int fd, struct nvme_passthru_cmd *cmd, __u32 *result)¶: Submit an nvme passthrough admin command

Parameters

int fd: File descriptor of nvme device
struct nvme_passthru_cmd *cmd: The nvme admin command to send
__u32 *result: Optional field to return the result from the CQE DW0

Description

Uses NVME_IOCTL_ADMIN_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_admin_passthru(int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u32 *result)¶: Submit an nvme passthrough command

Parameters

int fd: File descriptor of nvme device
__u8 opcode: The nvme io command to send
__u8 flags: NVMe command flags (not used)
__u16 rsvd: Reserved for future use
__u32 nsid: Namespace identifier
__u32 cdw2: Command dword 2
__u32 cdw3: Command dword 3
__u32 cdw10: Command dword 10
__u32 cdw11: Command dword 11
__u32 cdw12: Command dword 12
__u32 cdw13: Command dword 13
__u32 cdw14: Command dword 14
__u32 cdw15: Command dword 15
__u32 data_len: Length of the data transferred in this command in bytes
void *data: Pointer to user address of the data buffer
__u32 metadata_len: Length of metadata transferred in this command
void *metadata: Pointer to user address of the metadata buffer
__u32 timeout_ms: How long the kernel waits for the command to complete
__u32 *result: Optional field to return the result from the CQE dword 0

Description

Parameterized form of nvme_submit_admin_passthru(). This sets up and submits a struct nvme_passthru_cmd.

Known values for opcode are defined in enum nvme_admin_opcode.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_submit_io_passthru64(int fd, struct nvme_passthru_cmd64 *cmd, __u64 *result)¶: Submit a 64-bit nvme passthrough command

Parameters

int fd: File descriptor of nvme device
struct nvme_passthru_cmd64 *cmd: The nvme io command to send
__u64 *result: Optional field to return the result from the CQE DW0-1

Description

Uses NVME_IOCTL_IO64_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_io_passthru64(int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u64 *result)¶: Submit an nvme io passthrough command

Parameters

int fd: File descriptor of nvme device
__u8 opcode: The nvme io command to send
__u8 flags: NVMe command flags (not used)
__u16 rsvd: Reserved for future use
__u32 nsid: Namespace identifier
__u32 cdw2: Command dword 2
__u32 cdw3: Command dword 3
__u32 cdw10: Command dword 10
__u32 cdw11: Command dword 11
__u32 cdw12: Command dword 12
__u32 cdw13: Command dword 13
__u32 cdw14: Command dword 14
__u32 cdw15: Command dword 15
__u32 data_len: Length of the data transferred in this command in bytes
void *data: Pointer to user address of the data buffer
__u32 metadata_len: Length of metadata transferred in this command
void *metadata: Pointer to user address of the metadata buffer
__u32 timeout_ms: How long the kernel waits for the command to complete
__u64 *result: Optional field to return the result from the CQE dword 0

Description

Parameterized form of nvme_submit_io_passthru64(). This sets up and submits a struct nvme_passthru_cmd64.

Known values for opcode are defined in enum nvme_io_opcode.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_submit_io_passthru(int fd, struct nvme_passthru_cmd *cmd, __u32 *result)¶: Submit an nvme passthrough command

Parameters

int fd: File descriptor of nvme device
struct nvme_passthru_cmd *cmd: The nvme io command to send
__u32 *result: Optional field to return the result from the CQE DW0

Description

Uses NVME_IOCTL_IO_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_io_passthru(int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u32 *result)¶: Submit an nvme io passthrough command

Parameters

int fd: File descriptor of nvme device
__u8 opcode: The nvme io command to send
__u8 flags: NVMe command flags (not used)
__u16 rsvd: Reserved for future use
__u32 nsid: Namespace identifier
__u32 cdw2: Command dword 2
__u32 cdw3: Command dword 3
__u32 cdw10: Command dword 10
__u32 cdw11: Command dword 11
__u32 cdw12: Command dword 12
__u32 cdw13: Command dword 13
__u32 cdw14: Command dword 14
__u32 cdw15: Command dword 15
__u32 data_len: Length of the data transferred in this command in bytes
void *data: Pointer to user address of the data buffer
__u32 metadata_len: Length of metadata transferred in this command
void *metadata: Pointer to user address of the metadata buffer
__u32 timeout_ms: How long the kernel waits for the command to complete
__u32 *result: Optional field to return the result from the CQE dword 0

Description

Parameterized form of nvme_submit_io_passthru(). This sets up and submits a struct nvme_passthru_cmd.

Known values for opcode are defined in enum nvme_io_opcode.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_subsystem_reset(int fd)¶: Initiate a subsystem reset

Parameters

int fd: File descriptor of nvme device

Description

This should only be sent to controller handles, not to namespaces.

Return

Zero if a subsystem reset was initiated or -1 with errno set otherwise.

int nvme_ctrl_reset(int fd)¶: Initiate a controller reset

Parameters

int fd: File descriptor of nvme device

Description

This should only be sent to controller handles, not to namespaces.

Return

0 if a reset was initiated or -1 with errno set otherwise.

int nvme_ns_rescan(int fd)¶: Initiate a controller rescan

Parameters

int fd: File descriptor of nvme device

Description

This should only be sent to controller handles, not to namespaces.

Return

0 if a rescan was initiated or -1 with errno set otherwise.

int nvme_get_nsid(int fd, __u32 *nsid)¶: Retrieve the NSID from a namespace file descriptor

Parameters

int fd: File descriptor of nvme namespace
__u32 *nsid: User pointer to namespace id

Description

This should only be sent to namespace handles, not to controllers. The kernel’s interface returns the nsid as the return value. This is unfortunate for many architectures that are incapable of allowing distinguishing a namespace id > 0x80000000 from a negative error number.

Return

0 if nsid was set successfully or -1 with errno set otherwise.

int nvme_identify(struct nvme_identify_args *args)¶: Send the NVMe Identify command

Parameters

struct nvme_identify_args *args: struct nvme_identify_args argument structure

Description

The Identify command returns a data buffer that describes information about the NVM subsystem, the controller or the namespace(s).

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ctrl(int fd, struct nvme_id_ctrl *id)¶: Retrieves nvme identify controller

Parameters

int fd: File descriptor of nvme device
struct nvme_id_ctrl *id: User space destination address to transfer the data,

Description

Sends nvme identify with CNS value NVME_IDENTIFY_CNS_CTRL.

See struct nvme_id_ctrl for details on the data returned.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ns(int fd, __u32 nsid, struct nvme_id_ns *ns)¶: Retrieves nvme identify namespace

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace to identify
struct nvme_id_ns *ns: User space destination address to transfer the data

Description

If the Namespace Identifier (NSID) field specifies an active NSID, then the Identify Namespace data structure is returned to the host for that specified namespace.

If the controller supports the Namespace Management capability and the NSID field is set to NVME_NSID_ALL, then the controller returns an Identify Namespace data structure that specifies capabilities that are common across namespaces for this controller.

See struct nvme_id_ns for details on the structure returned.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_allocated_ns(int fd, __u32 nsid, struct nvme_id_ns *ns)¶: Same as nvme_identify_ns, but only for allocated namespaces

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace to identify
struct nvme_id_ns *ns: User space destination address to transfer the data

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_active_ns_list(int fd, __u32 nsid, struct nvme_ns_list *list)¶: Retrieves active namespaces id list

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return namespaces greater than this identifier
struct nvme_ns_list *list: User space destination address to transfer the data

Description

A list of 1024 namespace IDs is returned to the host containing NSIDs in increasing order that are greater than the value specified in the Namespace Identifier (nsid) field of the command.

See struct nvme_ns_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_allocated_ns_list(int fd, __u32 nsid, struct nvme_ns_list *list)¶: Retrieves allocated namespace id list

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return namespaces greater than this identifier
struct nvme_ns_list *list: User space destination address to transfer the data

Description

A list of 1024 namespace IDs is returned to the host containing NSIDs in increasing order that are greater than the value specified in the Namespace Identifier (nsid) field of the command.

See struct nvme_ns_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ctrl_list(int fd, __u16 cntid, struct nvme_ctrl_list *cntlist)¶: Retrieves identify controller list

Parameters

int fd: File descriptor of nvme device
__u16 cntid: Starting CNTLID to return in the list
struct nvme_ctrl_list *cntlist: User space destination address to transfer the data

Description

Up to 2047 controller identifiers is returned containing a controller identifier greater than or equal to the controller identifier specified in cntid.

See struct nvme_ctrl_list for a definition of the structure returned.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_nsid_ctrl_list(int fd, __u32 nsid, __u16 cntid, struct nvme_ctrl_list *cntlist)¶: Retrieves controller list attached to an nsid

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return controllers that are attached to this nsid
__u16 cntid: Starting CNTLID to return in the list
struct nvme_ctrl_list *cntlist: User space destination address to transfer the data

Description

Up to 2047 controller identifiers are returned containing a controller identifier greater than or equal to the controller identifier specified in cntid attached to nsid.

See struct nvme_ctrl_list for a definition of the structure returned.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1

int nvme_identify_ns_descs(int fd, __u32 nsid, struct nvme_ns_id_desc *descs)¶: Retrieves namespace descriptor list

Parameters

int fd: File descriptor of nvme device
__u32 nsid: The namespace id to retrieve descriptors
struct nvme_ns_id_desc *descs: User space destination address to transfer the data

Description

A list of Namespace Identification Descriptor structures is returned to the host for the namespace specified in the Namespace Identifier (NSID) field if it is an active NSID.

The data returned is in the form of an array of ‘struct nvme_ns_id_desc’.

See struct nvme_ns_id_desc for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_nvmset_list(int fd, __u16 nvmsetid, struct nvme_id_nvmset_list *nvmset)¶: Retrieves NVM Set List

Parameters

int fd: File descriptor of nvme device
__u16 nvmsetid: NVM Set Identifier
struct nvme_id_nvmset_list *nvmset: User space destination address to transfer the data

Description

Retrieves an NVM Set List, struct nvme_id_nvmset_list. The data structure is an ordered list by NVM Set Identifier, starting with the first NVM Set Identifier supported by the NVM subsystem that is equal to or greater than the NVM Set Identifier.

See struct nvme_id_nvmset_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_primary_ctrl(int fd, __u16 cntid, struct nvme_primary_ctrl_cap *cap)¶: Retrieve NVMe Primary Controller identification

Parameters

int fd: File descriptor of nvme device
__u16 cntid: Return controllers starting at this identifier
struct nvme_primary_ctrl_cap *cap: User space destination buffer address to transfer the data

Description

See struct nvme_primary_ctrl_cap for the definition of the returned structure, cap.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_secondary_ctrl_list(int fd, __u16 cntid, struct nvme_secondary_ctrl_list *sc_list)¶: Retrieves secondary controller list

Parameters

int fd: File descriptor of nvme device
__u16 cntid: Return controllers starting at this identifier
struct nvme_secondary_ctrl_list *sc_list: User space destination address to transfer the data

Description

A Secondary Controller List is returned to the host for up to 127 secondary controllers associated with the primary controller processing this command. The list contains entries for controller identifiers greater than or equal to the value specified in the Controller Identifier (cntid).

See struct nvme_secondary_ctrls_list for a definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ns_granularity(int fd, struct nvme_id_ns_granularity_list *gr_list)¶: Retrieves namespace granularity identification

Parameters

int fd: File descriptor of nvme device
struct nvme_id_ns_granularity_list *gr_list: User space destination address to transfer the data

Description

If the controller supports reporting of Namespace Granularity, then a Namespace Granularity List is returned to the host for up to sixteen namespace granularity descriptors

See struct nvme_id_ns_granularity_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_uuid(int fd, struct nvme_id_uuid_list *uuid_list)¶: Retrieves device’s UUIDs

Parameters

int fd: File descriptor of nvme device
struct nvme_id_uuid_list *uuid_list: User space destination address to transfer the data

Description

Each UUID List entry is either 0h, the NVMe Invalid UUID, or a valid UUID. Valid UUIDs are those which are non-zero and are not the NVMe Invalid UUID.

See struct nvme_id_uuid_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ns_csi(int fd, __u32 nsid, __u8 uuidx, enum nvme_csi csi, void *data)¶: I/O command set specific identify namespace data

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace to identify
__u8 uuidx: UUID Index for differentiating vendor specific encoding
enum nvme_csi csi: Command Set Identifier
void *data: User space destination address to transfer the data

Description

An I/O Command Set specific Identify Namespace data structure is returned for the namespace specified in nsid.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ctrl_csi(int fd, enum nvme_csi csi, void *data)¶: I/O command set specific Identify Controller data

Parameters

int fd: File descriptor of nvme device
enum nvme_csi csi: Command Set Identifier
void *data: User space destination address to transfer the data

Description

An I/O Command Set specific Identify Controller data structure is returned to the host for the controller processing the command. The specific Identify Controller data structure to be returned is specified by csi.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_active_ns_list_csi(int fd, __u32 nsid, enum nvme_csi csi, struct nvme_ns_list *ns_list)¶: Active namespace ID list associated with a specified I/O command set

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return namespaces greater than this identifier
enum nvme_csi csi: Command Set Identifier
struct nvme_ns_list *ns_list: User space destination address to transfer the data

Description

A list of 1024 namespace IDs is returned to the host containing active NSIDs in increasing order that are greater than the value specified in the Namespace Identifier (nsid) field of the command and matching the I/O Command Set specified in the csi argument.

See struct nvme_ns_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_allocated_ns_list_csi(int fd, __u32 nsid, enum nvme_csi csi, struct nvme_ns_list *ns_list)¶: Allocated namespace ID list associated with a specified I/O command set

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return namespaces greater than this identifier
enum nvme_csi csi: Command Set Identifier
struct nvme_ns_list *ns_list: User space destination address to transfer the data

Description

A list of 1024 namespace IDs is returned to the host containing allocated NSIDs in increasing order that are greater than the value specified in the nsid field of the command and matching the I/O Command Set specified in the csi argument.

See struct nvme_ns_list for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_independent_identify_ns(int fd, __u32 nsid, struct nvme_id_independent_id_ns *ns)¶: I/O command set independent Identify namespace data

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Return namespaces greater than this identifier
struct nvme_id_independent_id_ns *ns: I/O Command Set Independent Identify Namespace data structure

Description

The I/O command set independent Identify namespace data structure for the namespace identified with ns is returned to the host.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_ns_csi_user_data_format(int fd, __u16 user_data_format, __u8 uuidx, enum nvme_csi csi, void *data)¶: Identify namespace user data format

Parameters

int fd: File descriptor of nvme device
__u16 user_data_format: Return namespaces capability of identifier
__u8 uuidx: UUID selection, if supported
enum nvme_csi csi: Command Set Identifier
void *data: User space destination address to transfer the data

Description

Identify Namespace data structure for the specified User Data Format index containing the namespace capabilities for the NVM Command Set.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_iocs_ns_csi_user_data_format(int fd, __u16 user_data_format, __u8 uuidx, enum nvme_csi csi, void *data)¶: Identify I/O command set namespace data structure

Parameters

int fd: File descriptor of nvme device
__u16 user_data_format: Return namespaces capability of identifier
__u8 uuidx: UUID selection, if supported
enum nvme_csi csi: Command Set Identifier
void *data: User space destination address to transfer the data

Description

I/O Command Set specific Identify Namespace data structure for the specified User Data Format index containing the namespace capabilities for the I/O Command Set specified in the CSI field.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_nvm_identify_ctrl(int fd, struct nvme_id_ctrl_nvm *id)¶: Identify controller data

Parameters

int fd: File descriptor of nvme device
struct nvme_id_ctrl_nvm *id: User space destination address to transfer the data

Description

Return an identify controller data structure to the host of processing controller.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_domain_list(int fd, __u16 domid, struct nvme_id_domain_list *list)¶: Domain list data

Parameters

int fd: File descriptor of nvme device
__u16 domid: Domain ID
struct nvme_id_domain_list *list: User space destination address to transfer data

Description

A list of 31 domain IDs is returned to the host containing domain attributes in increasing order that are greater than the value specified in the domid field.

See struct nvme_identify_domain_attr for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_endurance_group_list(int fd, __u16 endgrp_id, struct nvme_id_endurance_group_list *list)¶: Endurance group list data

Parameters

int fd: File descriptor of nvme device
__u16 endgrp_id: Endurance group identifier
struct nvme_id_endurance_group_list *list: Array of endurance group identifiers

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_identify_iocs(int fd, __u16 cntlid, struct nvme_id_iocs *iocs)¶: I/O command set data structure

Parameters

int fd: File descriptor of nvme device
__u16 cntlid: Controller ID
struct nvme_id_iocs *iocs: User space destination address to transfer the data

Description

Retrieves list of the controller’s supported io command set vectors. See struct nvme_id_iocs.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_identify_ns(int fd, __u32 nsid, struct nvme_zns_id_ns *data)¶: ZNS identify namespace data

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace to identify
struct nvme_zns_id_ns *data: User space destination address to transfer the data

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_identify_ctrl(int fd, struct nvme_zns_id_ctrl *id)¶: ZNS identify controller data

Parameters

int fd: File descriptor of nvme device
struct nvme_zns_id_ctrl *id: User space destination address to transfer the data

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log(struct nvme_get_log_args *args)¶: NVMe Admin Get Log command

Parameters

struct nvme_get_log_args *args: struct nvme_get_log_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_page(int fd, __u32 xfer_len, struct nvme_get_log_args *args)¶: Get log page data

Parameters

int fd: File descriptor of nvme device
__u32 xfer_len: Max log transfer size per request to split the total.
struct nvme_get_log_args *args: struct nvme_get_log_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_supported_log_pages(int fd, bool rae, struct nvme_supported_log_pages *log)¶: Retrieve nmve supported log pages

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_supported_log_pages *log: Array of LID supported and Effects data structures

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_error(int fd, unsigned int nr_entries, bool rae, struct nvme_error_log_page *err_log)¶: Retrieve nvme error log

Parameters

int fd: File descriptor of nvme device
unsigned int nr_entries: Number of error log entries allocated
bool rae: Retain asynchronous events
struct nvme_error_log_page *err_log: Array of error logs of size ‘entries’

Description

This log page describes extended error information for a command that completed with error, or may report an error that is not specific to a particular command.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_smart(int fd, __u32 nsid, bool rae, struct nvme_smart_log *smart_log)¶: Retrieve nvme smart log

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Optional namespace identifier
bool rae: Retain asynchronous events
struct nvme_smart_log *smart_log: User address to store the smart log

Description

This log page provides SMART and general health information. The information provided is over the life of the controller and is retained across power cycles. To request the controller log page, the namespace identifier specified is FFFFFFFFh. The controller may also support requesting the log page on a per namespace basis, as indicated by bit 0 of the LPA field in the Identify Controller data structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_fw_slot(int fd, bool rae, struct nvme_firmware_slot *fw_log)¶: Retrieves the controller firmware log

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_firmware_slot *fw_log: User address to store the log page

Description

This log page describes the firmware revision stored in each firmware slot supported. The firmware revision is indicated as an ASCII string. The log page also indicates the active slot number.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_changed_ns_list(int fd, bool rae, struct nvme_ns_list *ns_log)¶: Retrieve namespace changed list

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_ns_list *ns_log: User address to store the log page

Description

This log page describes namespaces attached to this controller that have changed since the last time the namespace was identified, been added, or deleted.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_cmd_effects(int fd, enum nvme_csi csi, struct nvme_cmd_effects_log *effects_log)¶: Retrieve nvme command effects log

Parameters

int fd: File descriptor of nvme device
enum nvme_csi csi: Command Set Identifier
struct nvme_cmd_effects_log *effects_log: User address to store the effects log

Description

This log page describes the commands that the controller supports and the effects of those commands on the state of the NVM subsystem.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_device_self_test(int fd, struct nvme_self_test_log *log)¶: Retrieve the device self test log

Parameters

int fd: File descriptor of nvme device
struct nvme_self_test_log *log: Userspace address of the log payload

Description

The log page indicates the status of an in progress self test and the percent complete of that operation, and the results of the previous 20 self-test operations.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_create_telemetry_host_mcda(int fd, enum nvme_telemetry_da mcda, struct nvme_telemetry_log *log)¶: Create host telemetry log

Parameters

int fd: File descriptor of nvme device
enum nvme_telemetry_da mcda: Maximum Created Data Area
struct nvme_telemetry_log *log: Userspace address of the log payload

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_create_telemetry_host(int fd, struct nvme_telemetry_log *log)¶: Create host telemetry log

Parameters

int fd: File descriptor of nvme device
struct nvme_telemetry_log *log: Userspace address of the log payload

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_telemetry_host(int fd, __u64 offset, __u32 len, void *log)¶: Get Telemetry Host-Initiated log page

Parameters

int fd: File descriptor of nvme device
__u64 offset: Offset into the telemetry data
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Description

Retrieves the Telemetry Host-Initiated log page at the requested offset using the previously existing capture.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_telemetry_ctrl(int fd, bool rae, __u64 offset, __u32 len, void *log)¶: Get Telemetry Controller-Initiated log page

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u64 offset: Offset into the telemetry data
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Description

Retrieves the Telemetry Controller-Initiated log page at the requested offset using the previously existing capture.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_endurance_group(int fd, __u16 endgid, struct nvme_endurance_group_log *log)¶: Get Endurance Group log

Parameters

int fd: File descriptor of nvme device
__u16 endgid: Starting group identifier to return in the list
struct nvme_endurance_group_log *log: User address to store the endurance log

Description

This log page indicates if an Endurance Group Event has occurred for a particular Endurance Group. If an Endurance Group Event has occurred, the details of the particular event are included in the Endurance Group Information log page for that Endurance Group. An asynchronous event is generated when an entry for an Endurance Group is newly added to this log page.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_predictable_lat_nvmset(int fd, __u16 nvmsetid, struct nvme_nvmset_predictable_lat_log *log)¶: Predictable Latency Per NVM Set

Parameters

int fd: File descriptor of nvme device
__u16 nvmsetid: NVM set id
struct nvme_nvmset_predictable_lat_log *log: User address to store the predictable latency log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_predictable_lat_event(int fd, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Predictable Latency Event Aggregate Log Page

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 offset: Offset into the predictable latency event
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_fdp_configurations(int fd, __u16 egid, __u32 offset, __u32 len, void *log)¶: Get list of Flexible Data Placement configurations

Parameters

int fd: File descriptor of nvme device
__u16 egid: Endurance group identifier
__u32 offset: Offset into log page
__u32 len: Length (in bytes) of provided user buffer to hold the log data
void *log: Log page data buffer

int nvme_get_log_reclaim_unit_handle_usage(int fd, __u16 egid, __u32 offset, __u32 len, void *log)¶: Get reclaim unit handle usage

Parameters

int fd: File descriptor of nvme device
__u16 egid: Endurance group identifier
__u32 offset: Offset into log page
__u32 len: Length (in bytes) of provided user buffer to hold the log data
void *log: Log page data buffer

int nvme_get_log_fdp_stats(int fd, __u16 egid, __u32 offset, __u32 len, void *log)¶: Get Flexible Data Placement statistics

Parameters

int fd: File descriptor of nvme device
__u16 egid: Endurance group identifier
__u32 offset: Offset into log page
__u32 len: Length (in bytes) of provided user buffer to hold the log data
void *log: Log page data buffer

int nvme_get_log_fdp_events(int fd, __u16 egid, bool host_events, __u32 offset, __u32 len, void *log)¶: Get Flexible Data Placement events

Parameters

int fd: File descriptor of nvme device
__u16 egid: Endurance group identifier
bool host_events: Whether to report host or controller events
__u32 offset: Offset into log page
__u32 len: Length (in bytes) of provided user buffer to hold the log data
void *log: Log page data buffer

int nvme_get_log_ana(int fd, enum nvme_log_ana_lsp lsp, bool rae, __u64 offset, __u32 len, void *log)¶: Retrieve Asymmetric Namespace Access log page

Parameters

int fd: File descriptor of nvme device
enum nvme_log_ana_lsp lsp: Log specific, see enum nvme_get_log_ana_lsp
bool rae: Retain asynchronous events
__u64 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the ana log

Description

This log consists of a header describing the log and descriptors containing the asymmetric namespace access information for ANA Groups that contain namespaces that are attached to the controller processing the command.

See struct nvme_ana_log for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_ana_groups(int fd, bool rae, __u32 len, struct nvme_ana_log *log)¶: Retrieve Asymmetric Namespace Access groups only log page

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ana_log *log: User address to store the ana group log

Description

See struct nvme_ana_log for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_ana_log_atomic(int fd, bool rgo, bool rae, unsigned int retries, struct nvme_ana_log *log, __u32 *len)¶: Retrieve Asymmetric Namespace Access log page atomically

Parameters

int fd: File descriptor of nvme device
bool rgo: Whether to retrieve ANA groups only (no NSIDs)
bool rae: Whether to retain asynchronous events
unsigned int retries: The maximum number of times to retry on log page changes
struct nvme_ana_log *log: Pointer to a buffer to receive the ANA log page
__u32 *len: Input: the length of the log page buffer. Output: the actual length of the ANA log page.

Description

See struct nvme_ana_log for the definition of the returned structure.

Return

If successful, returns 0 and sets *len to the actual log page length. If unsuccessful, returns the nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise. Sets errno = EINVAL if retries == 0. Sets errno = EAGAIN if unable to read the log page atomically because chgcnt changed during each of the retries attempts. Sets errno = ENOSPC if the full log page does not fit in the provided buffer.

int nvme_get_log_lba_status(int fd, bool rae, __u64 offset, __u32 len, void *log)¶: Retrieve LBA Status

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u64 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_endurance_grp_evt(int fd, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Endurance Group Event Aggregate

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_fid_supported_effects(int fd, bool rae, struct nvme_fid_supported_effects_log *log)¶: Retrieve Feature Identifiers Supported and Effects

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_fid_supported_effects_log *log: FID Supported and Effects data structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_mi_cmd_supported_effects(int fd, bool rae, struct nvme_mi_cmd_supported_effects_log *log)¶: displays the MI Commands Supported by the controller

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_mi_cmd_supported_effects_log *log: MI Command Supported and Effects data structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_boot_partition(int fd, bool rae, __u8 lsp, __u32 len, struct nvme_boot_partition *part)¶: Retrieve Boot Partition

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u8 lsp: The log specified field of LID
__u32 len: The allocated size, minimum struct nvme_boot_partition
struct nvme_boot_partition *part: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_rotational_media_info(int fd, __u16 endgid, __u32 len, struct nvme_rotational_media_info_log *log)¶: Retrieve Rotational Media Information Log

Parameters

int fd: File descriptor of nvme device
__u16 endgid: Endurance Group Identifier
__u32 len: The allocated length of the log page
struct nvme_rotational_media_info_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_dispersed_ns_participating_nss(int fd, __u32 nsid, __u32 len, struct nvme_dispersed_ns_participating_nss_log *log)¶: Retrieve Dispersed Namespace Participating NVM Subsystems Log

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace Identifier
__u32 len: The allocated length of the log page
struct nvme_dispersed_ns_participating_nss_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_mgmt_addr_list(int fd, __u32 len, struct nvme_mgmt_addr_list_log *log)¶: Retrieve Management Address List Log

Parameters

int fd: File descriptor of nvme device
__u32 len: The allocated length of the log page
struct nvme_mgmt_addr_list_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_phy_rx_eom(int fd, __u8 lsp, __u16 controller, __u32 len, struct nvme_phy_rx_eom_log *log)¶: Retrieve Physical Interface Receiver Eye Opening Measurement Log

Parameters

int fd: File descriptor of nvme device
__u8 lsp: Log specific, controls action and measurement quality
__u16 controller: Target controller ID
__u32 len: The allocated size, minimum struct nvme_phy_rx_eom_log
struct nvme_phy_rx_eom_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_reachability_groups(int fd, bool rgo, bool rae, __u32 len, struct nvme_reachability_groups_log *log)¶: Retrieve Reachability Groups Log

Parameters

int fd: File descriptor of nvme device
bool rgo: Return groups only
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_reachability_groups_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_reachability_associations(int fd, bool rao, bool rae, __u32 len, struct nvme_reachability_associations_log *log)¶: Retrieve Reachability Associations Log

Parameters

int fd: File descriptor of nvme device
bool rao: Return associations only
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_reachability_associations_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_changed_alloc_ns_list(int fd, bool rae, __u32 len, struct nvme_ns_list *log)¶: Retrieve Changed Allocated Namespace List Log

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ns_list *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_discovery(int fd, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Discovery log page

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 offset: Offset of this log to retrieve
__u32 len: The allocated size for this portion of the log
void *log: User address to store the discovery log

Description

Supported only by fabrics discovery controllers, returning discovery records.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_host_discover(int fd, bool allhoste, bool rae, __u32 len, struct nvme_host_discover_log *log)¶: Retrieve Host Discovery Log

Parameters

int fd: File descriptor of nvme device
bool allhoste: All host entries
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_host_discover_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_ave_discover(int fd, bool rae, __u32 len, struct nvme_ave_discover_log *log)¶: Retrieve AVE Discovery Log

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ave_discover_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_pull_model_ddc_req(int fd, bool rae, __u32 len, struct nvme_pull_model_ddc_req_log *log)¶: Retrieve Pull Model DDC Request Log

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_pull_model_ddc_req_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_media_unit_stat(int fd, __u16 domid, struct nvme_media_unit_stat_log *mus)¶: Retrieve Media Unit Status

Parameters

int fd: File descriptor of nvme device
__u16 domid: Domain Identifier selection, if supported
struct nvme_media_unit_stat_log *mus: User address to store the Media Unit statistics log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_support_cap_config_list(int fd, __u16 domid, struct nvme_supported_cap_config_list_log *cap)¶: Retrieve Supported Capacity Configuration List

Parameters

int fd: File descriptor of nvme device
__u16 domid: Domain Identifier selection, if supported
struct nvme_supported_cap_config_list_log *cap: User address to store supported capabilities config list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_reservation(int fd, bool rae, struct nvme_resv_notification_log *log)¶: Retrieve Reservation Notification

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_resv_notification_log *log: User address to store the reservation log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_get_log_sanitize(int fd, bool rae, struct nvme_sanitize_log_page *log)¶: Retrieve Sanitize Status

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_sanitize_log_page *log: User address to store the sanitize log

Description

The Sanitize Status log page reports sanitize operation time estimates and information about the most recent sanitize operation.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_zns_changed_zones(int fd, __u32 nsid, bool rae, struct nvme_zns_changed_zone_log *log)¶: Retrieve list of zones that have changed

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
bool rae: Retain asynchronous events
struct nvme_zns_changed_zone_log *log: User address to store the changed zone log

Description

The list of zones that have changed state due to an exceptional event.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_persistent_event(int fd, enum nvme_pevent_log_action action, __u32 size, void *pevent_log)¶: Retrieve Persistent Event Log

Parameters

int fd: File descriptor of nvme device
enum nvme_pevent_log_action action: Action the controller should take during processing this command
__u32 size: Size of pevent_log
void *pevent_log: User address to store the persistent event log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_log_lockdown(int fd, __u8 cnscp, struct nvme_lockdown_log *lockdown_log)¶: Retrieve lockdown Log

Parameters

int fd: File descriptor of nvme device
__u8 cnscp: Contents and Scope of Command and Feature Identifier Lists
struct nvme_lockdown_log *lockdown_log: Buffer to store the lockdown log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features(struct nvme_set_features_args *args)¶: Set a feature attribute

Parameters

struct nvme_set_features_args *args: struct nvme_set_features_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_data(int fd, __u8 fid, __u32 nsid, __u32 cdw11, bool save, __u32 data_len, void *data, __u32 *result)¶: Helper function for nvme_set_features()

Parameters

int fd: File descriptor of nvme device
__u8 fid: Feature identifier
__u32 nsid: Namespace ID, if applicable
__u32 cdw11: Value to set the feature to
bool save: Save value across power states
__u32 data_len: Length of feature data, if applicable, in bytes
void *data: User address of feature data, if applicable
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_simple(int fd, __u8 fid, __u32 nsid, __u32 cdw11, bool save, __u32 *result)¶: Helper function for nvme_set_features()

Parameters

int fd: File descriptor of nvme device
__u8 fid: Feature identifier
__u32 nsid: Namespace ID, if applicable
__u32 cdw11: Value to set the feature to
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_arbitration(int fd, __u8 ab, __u8 lpw, __u8 mpw, __u8 hpw, bool save, __u32 *result)¶: Set arbitration features

Parameters

int fd: File descriptor of nvme device
__u8 ab: Arbitration Burst
__u8 lpw: Low Priority Weight
__u8 mpw: Medium Priority Weight
__u8 hpw: High Priority Weight
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_power_mgmt(int fd, __u8 ps, __u8 wh, bool save, __u32 *result)¶: Set power management feature

Parameters

int fd: File descriptor of nvme device
__u8 ps: Power State
__u8 wh: Workload Hint
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_lba_range(int fd, __u32 nsid, __u8 nr_ranges, bool save, struct nvme_lba_range_type *data, __u32 *result)¶: Set LBA range feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u8 nr_ranges: Number of ranges in data
bool save: Save value across power states
struct nvme_lba_range_type *data: User address of feature data
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_temp_thresh(int fd, __u16 tmpth, __u8 tmpsel, enum nvme_feat_tmpthresh_thsel thsel, bool save, __u32 *result)¶: Set temperature threshold feature

Parameters

int fd: File descriptor of nvme device
__u16 tmpth: Temperature Threshold
__u8 tmpsel: Threshold Temperature Select
enum nvme_feat_tmpthresh_thsel thsel: Threshold Type Select
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_temp_thresh2(int fd, __u16 tmpth, __u8 tmpsel, enum nvme_feat_tmpthresh_thsel thsel, __u8 tmpthh, bool save, __u32 *result)¶: Set temperature threshold feature

Parameters

int fd: File descriptor of nvme device
__u16 tmpth: Temperature Threshold
__u8 tmpsel: Threshold Temperature Select
enum nvme_feat_tmpthresh_thsel thsel: Threshold Type Select
__u8 tmpthh: Temperature Threshold Hysteresis
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_err_recovery(int fd, __u32 nsid, __u16 tler, bool dulbe, bool save, __u32 *result)¶: Set error recovery feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u16 tler: Time-limited error recovery value
bool dulbe: Deallocated or Unwritten Logical Block Error Enable
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_volatile_wc(int fd, bool wce, bool save, __u32 *result)¶: Set volatile write cache feature

Parameters

int fd: File descriptor of nvme device
bool wce: Write cache enable
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_irq_coalesce(int fd, __u8 thr, __u8 time, bool save, __u32 *result)¶: Set IRQ coalesce feature

Parameters

int fd: File descriptor of nvme device
__u8 thr: Aggregation Threshold
__u8 time: Aggregation Time
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_irq_config(int fd, __u16 iv, bool cd, bool save, __u32 *result)¶: Set IRQ config feature

Parameters

int fd: File descriptor of nvme device
__u16 iv: Interrupt Vector
bool cd: Coalescing Disable
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_write_atomic(int fd, bool dn, bool save, __u32 *result)¶: Set write atomic feature

Parameters

int fd: File descriptor of nvme device
bool dn: Disable Normal
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_async_event(int fd, __u32 events, bool save, __u32 *result)¶: Set asynchronous event feature

Parameters

int fd: File descriptor of nvme device
__u32 events: Events to enable
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_auto_pst(int fd, bool apste, bool save, struct nvme_feat_auto_pst *apst, __u32 *result)¶: Set autonomous power state feature

Parameters

int fd: File descriptor of nvme device
bool apste: Autonomous Power State Transition Enable
bool save: Save value across power states
struct nvme_feat_auto_pst *apst: Autonomous Power State Transition
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_timestamp(int fd, bool save, __u64 timestamp)¶: Set timestamp feature

Parameters

int fd: File descriptor of nvme device
bool save: Save value across power states
__u64 timestamp: The current timestamp value to assign to this feature

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_hctm(int fd, __u16 tmt2, __u16 tmt1, bool save, __u32 *result)¶: Set thermal management feature

Parameters

int fd: File descriptor of nvme device
__u16 tmt2: Thermal Management Temperature 2
__u16 tmt1: Thermal Management Temperature 1
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_nopsc(int fd, bool noppme, bool save, __u32 *result)¶: Set non-operational power state feature

Parameters

int fd: File descriptor of nvme device
bool noppme: Non-Operational Power State Permissive Mode Enable
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_rrl(int fd, __u8 rrl, __u16 nvmsetid, bool save, __u32 *result)¶: Set read recovery level feature

Parameters

int fd: File descriptor of nvme device
__u8 rrl: Read recovery level setting
__u16 nvmsetid: NVM set id
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_plm_config(int fd, bool enable, __u16 nvmsetid, bool save, struct nvme_plm_config *data, __u32 *result)¶: Set predictable latency feature

Parameters

int fd: File descriptor of nvme device
bool enable: Predictable Latency Enable
__u16 nvmsetid: NVM Set Identifier
bool save: Save value across power states
struct nvme_plm_config *data: Pointer to structure nvme_plm_config
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_plm_window(int fd, enum nvme_feat_plm_window_select sel, __u16 nvmsetid, bool save, __u32 *result)¶: Set window select feature

Parameters

int fd: File descriptor of nvme device
enum nvme_feat_plm_window_select sel: Window Select
__u16 nvmsetid: NVM Set Identifier
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_lba_sts_interval(int fd, __u16 lsiri, __u16 lsipi, bool save, __u32 *result)¶: Set LBA status information feature

Parameters

int fd: File descriptor of nvme device
__u16 lsiri: LBA Status Information Report Interval
__u16 lsipi: LBA Status Information Poll Interval
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_host_behavior(int fd, bool save, struct nvme_feat_host_behavior *data)¶: Set host behavior feature

Parameters

int fd: File descriptor of nvme device
bool save: Save value across power states
struct nvme_feat_host_behavior *data: Pointer to structure nvme_feat_host_behavior

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_sanitize(int fd, bool nodrm, bool save, __u32 *result)¶: Set sanitize feature

Parameters

int fd: File descriptor of nvme device
bool nodrm: No-Deallocate Response Mode
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_endurance_evt_cfg(int fd, __u16 endgid, __u8 egwarn, bool save, __u32 *result)¶: Set endurance event config feature

Parameters

int fd: File descriptor of nvme device
__u16 endgid: Endurance Group Identifier
__u8 egwarn: Flags to enable warning, see enum nvme_eg_critical_warning_flags
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_sw_progress(int fd, __u8 pbslc, bool save, __u32 *result)¶: Set pre-boot software load count feature

Parameters

int fd: File descriptor of nvme device
__u8 pbslc: Pre-boot Software Load Count
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_host_id(int fd, bool exhid, bool save, __u8 *hostid)¶: Set enable extended host identifiers feature

Parameters

int fd: File descriptor of nvme device
bool exhid: Enable Extended Host Identifier
bool save: Save value across power states
__u8 *hostid: Host ID to set

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_resv_mask(int fd, __u32 mask, bool save, __u32 *result)¶: Set reservation notification mask feature

Parameters

int fd: File descriptor of nvme device
__u32 mask: Reservation Notification Mask Field
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_set_features_resv_mask2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_resv_mask2(int fd, __u32 nsid, __u32 mask, bool save, __u32 *result)¶: Set reservation notification mask feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u32 mask: Reservation Notification Mask Field
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_resv_persist(int fd, bool ptpl, bool save, __u32 *result)¶: Set persist through power loss feature

Parameters

int fd: File descriptor of nvme device
bool ptpl: Persist Through Power Loss
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_set_features_resv_persist2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_resv_persist2(int fd, __u32 nsid, bool ptpl, bool save, __u32 *result)¶: Set persist through power loss feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
bool ptpl: Persist Through Power Loss
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_write_protect(int fd, enum nvme_feat_nswpcfg_state state, bool save, __u32 *result)¶: Set write protect feature

Parameters

int fd: File descriptor of nvme device
enum nvme_feat_nswpcfg_state state: Write Protection State
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_set_features_write_protect2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_write_protect2(int fd, __u32 nsid, enum nvme_feat_nswpcfg_state state, bool save, __u32 *result)¶: Set write protect feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
enum nvme_feat_nswpcfg_state state: Write Protection State
bool save: Save value across power states
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_features_iocs_profile(int fd, __u16 iocsi, bool save)¶: Set I/O command set profile feature

Parameters

int fd: File descriptor of nvme device
__u16 iocsi: I/O Command Set Combination Index
bool save: Save value across power states

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features(struct nvme_get_features_args *args)¶: Retrieve a feature attribute

Parameters

struct nvme_get_features_args *args: struct nvme_get_features_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_data(int fd, enum nvme_features_id fid, __u32 nsid, __u32 data_len, void *data, __u32 *result)¶: Helper function for nvme_get_features()

Parameters

int fd: File descriptor of nvme device
enum nvme_features_id fid: Feature identifier
__u32 nsid: Namespace ID, if applicable
__u32 data_len: Length of feature data, if applicable, in bytes
void *data: User address of feature data, if applicable
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_simple(int fd, enum nvme_features_id fid, __u32 nsid, __u32 *result)¶: Helper function for nvme_get_features()

Parameters

int fd: File descriptor of nvme device
enum nvme_features_id fid: Feature identifier
__u32 nsid: Namespace ID, if applicable
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_arbitration(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get arbitration feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_power_mgmt(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get power management feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_lba_range(int fd, enum nvme_get_features_sel sel, struct nvme_lba_range_type *data, __u32 *result)¶: Get LBA range feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
struct nvme_lba_range_type *data: User address of feature data, if applicable
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_get_features_lba_range2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_lba_range2(int fd, enum nvme_get_features_sel sel, __u32 nsid, struct nvme_lba_range_type *data, __u32 *result)¶: Get LBA range feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 nsid: Namespace ID
struct nvme_lba_range_type *data: Buffer to receive LBA Range Type data structure
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_temp_thresh(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get temperature threshold feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_temp_thresh2(int fd, enum nvme_get_features_sel sel, __u8 tmpsel, enum nvme_feat_tmpthresh_thsel thsel, __u32 *result)¶: Get temperature threshold feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u8 tmpsel: Threshold Temperature Select
enum nvme_feat_tmpthresh_thsel thsel: Threshold Type Select
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_err_recovery(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get error recovery feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_get_features_err_recovery2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_err_recovery2(int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)¶: Get error recovery feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 nsid: Namespace ID
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_volatile_wc(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get volatile write cache feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_num_queues(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get number of queues feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_irq_coalesce(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get IRQ coalesce feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_irq_config(int fd, enum nvme_get_features_sel sel, __u16 iv, __u32 *result)¶: Get IRQ config feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel

__u16 iv

__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_write_atomic(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get write atomic feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_async_event(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get asynchronous event feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_auto_pst(int fd, enum nvme_get_features_sel sel, struct nvme_feat_auto_pst *apst, __u32 *result)¶: Get autonomous power state feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel

struct nvme_feat_auto_pst *apst

__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_host_mem_buf(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get host memory buffer feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t fetch the Host Memory Buffer Attributes data structure. Use nvme_get_features_host_mem_buf2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_host_mem_buf2(int fd, enum nvme_get_features_sel sel, struct nvme_host_mem_buf_attrs *attrs, __u32 *result)¶: Get host memory buffer feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
struct nvme_host_mem_buf_attrs *attrs: Buffer for returned Host Memory Buffer Attributes
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_timestamp(int fd, enum nvme_get_features_sel sel, struct nvme_timestamp *ts)¶: Get timestamp feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
struct nvme_timestamp *ts: Current timestamp

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_kato(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get keep alive timeout feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_hctm(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get thermal management feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_nopsc(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get non-operational power state feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_rrl(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get read recovery level feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_plm_config(int fd, enum nvme_get_features_sel sel, __u16 nvmsetid, struct nvme_plm_config *data, __u32 *result)¶: Get predictable latency feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u16 nvmsetid: NVM set id

struct nvme_plm_config *data

__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_plm_window(int fd, enum nvme_get_features_sel sel, __u16 nvmsetid, __u32 *result)¶: Get window select feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u16 nvmsetid: NVM set id
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_lba_sts_interval(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get LBA status information feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_host_behavior(int fd, enum nvme_get_features_sel sel, struct nvme_feat_host_behavior *data, __u32 *result)¶: Get host behavior feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
struct nvme_feat_host_behavior *data: Pointer to structure nvme_feat_host_behavior
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_sanitize(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get sanitize feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_endurance_event_cfg(int fd, enum nvme_get_features_sel sel, __u16 endgid, __u32 *result)¶: Get endurance event config feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u16 endgid: Endurance Group Identifier
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_sw_progress(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get software progress feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_host_id(int fd, enum nvme_get_features_sel sel, bool exhid, __u32 len, __u8 *hostid)¶: Get host id feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
bool exhid: Enable Extended Host Identifier
__u32 len: Length of hostid
__u8 *hostid: Buffer for returned host ID

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_resv_mask(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get reservation mask feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_get_features_resv_mask2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_resv_mask2(int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)¶: Get reservation mask feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 nsid: Namespace ID
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_resv_persist(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get reservation persist feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Description

Deprecated: doesn’t support specifying a NSID. Use nvme_get_features_resv_persist2() instead.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_resv_persist2(int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)¶: Get reservation persist feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 nsid: Namespace ID
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_write_protect(int fd, __u32 nsid, enum nvme_get_features_sel sel, __u32 *result)¶: Get write protect feature

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_features_iocs_profile(int fd, enum nvme_get_features_sel sel, __u32 *result)¶: Get IOCS profile feature

Parameters

int fd: File descriptor of nvme device
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_format_nvm(struct nvme_format_nvm_args *args)¶: Format nvme namespace(s)

Parameters

struct nvme_format_nvm_args *args: struct nvme_format_nvme_args argument structure

Description

The Format NVM command low level formats the NVM media. This command is used by the host to change the LBA data size and/or metadata size. A low level format may destroy all data and metadata associated with all namespaces or only the specific namespace associated with the command

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_mgmt(struct nvme_ns_mgmt_args *args)¶: Issue a Namespace management command

Parameters

struct nvme_ns_mgmt_args *args: struct nvme_ns_mgmt_args Argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

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

Parameters

int fd: File descriptor of nvme device
struct nvme_id_ns *ns: Namespace identification that defines ns creation parameters
__u32 *nsid: On success, set to the namespace id that was created
__u32 timeout: Override the default timeout to this value in milliseconds; set to 0 to use the system default.
__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 attached to any controller. Use the nvme_ns_attach_ctrls() to assign the namespace to one or more controllers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_mgmt_delete_timeout(int fd, __u32 nsid, __u32 timeout)¶: Delete a non attached namespace with timeout

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace identifier to delete
__u32 timeout: Override the default timeout to this value in milliseconds; set to 0 to use the system default.

Description

It is recommended that a namespace being deleted is not attached to any controller. Use the nvme_ns_detach_ctrls() first if the namespace is still attached.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_mgmt_delete(int fd, __u32 nsid)¶: Delete a non attached namespace

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace identifier to delete

Description

It is recommended that a namespace being deleted is not attached to any controller. Use the nvme_ns_detach_ctrls() first if the namespace is still attached.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_attach(struct nvme_ns_attach_args *args)¶: Attach or detach namespace to controller(s)

Parameters

struct nvme_ns_attach_args *args: struct nvme_ns_attach_args Argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_attach_ctrls(int fd, __u32 nsid, struct nvme_ctrl_list *ctrlist)¶: Attach namespace to controllers

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID to attach
struct nvme_ctrl_list *ctrlist: Controller list to modify attachment state of nsid

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_ns_detach_ctrls(int fd, __u32 nsid, struct nvme_ctrl_list *ctrlist)¶: Detach namespace from controllers

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID to detach
struct nvme_ctrl_list *ctrlist: Controller list to modify attachment state of nsid

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_fw_download(struct nvme_fw_download_args *args)¶: Download part or all of a firmware image to the controller

Parameters

struct nvme_fw_download_args *args: struct nvme_fw_download_args argument structure

Description

The Firmware Image Download command downloads all or a portion of an image for a future update to the controller. The Firmware Image Download command downloads a new image (in whole or in part) to the controller.

The image may be constructed of multiple pieces that are individually downloaded with separate Firmware Image Download commands. Each Firmware Image Download command includes a Dword Offset and Number of Dwords that specify a dword range.

The new firmware image is not activated as part of the Firmware Image Download command. Use the nvme_fw_commit() to activate a newly downloaded image.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_fw_commit(struct nvme_fw_commit_args *args)¶: Commit firmware using the specified action

Parameters

struct nvme_fw_commit_args *args: struct nvme_fw_commit_args argument structure

Description

The Firmware Commit command modifies the firmware image or Boot Partitions.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise. The command status response may specify additional reset actions required to complete the commit process.

int nvme_security_send(struct nvme_security_send_args *args)¶: Security Send command

Parameters

struct nvme_security_send_args *args: struct nvme_security_send argument structure

Description

The Security Send command transfers security protocol data to the controller. The data structure transferred to the controller as part of this command contains security protocol specific commands to be performed by the controller. The data structure transferred may also contain data or parameters associated with the security protocol commands.

The security data is protocol specific and is not defined by the NVMe specification.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_security_receive(struct nvme_security_receive_args *args)¶: Security Receive command

Parameters

struct nvme_security_receive_args *args: struct nvme_security_receive argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_lba_status(struct nvme_get_lba_status_args *args)¶: Retrieve information on possibly unrecoverable LBAs

Parameters

struct nvme_get_lba_status_args *args: struct nvme_get_lba_status_args argument structure

Description

The Get LBA Status command requests information about Potentially Unrecoverable LBAs. Refer to the specification for action type descriptions.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_send(struct nvme_directive_send_args *args)¶: Send directive command

Parameters

struct nvme_directive_send_args *args: struct nvme_directive_send_args argument structure

Description

Directives is a mechanism to enable host and NVM subsystem or controller information exchange. The Directive Send command transfers data related to a specific Directive Type from the host to the controller.

See the NVMe specification for more information.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_send_id_endir(int fd, __u32 nsid, bool endir, enum nvme_directive_dtype dtype, struct nvme_id_directives *id)¶: Directive Send Enable Directive

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace Identifier
bool endir: Enable Directive
enum nvme_directive_dtype dtype: Directive Type
struct nvme_id_directives *id: Pointer to structure nvme_id_directives

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_send_stream_release_identifier(int fd, __u32 nsid, __u16 stream_id)¶: Directive Send Stream release

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u16 stream_id: Stream identifier

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_send_stream_release_resource(int fd, __u32 nsid)¶: Directive Send Stream release resources

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_recv(struct nvme_directive_recv_args *args)¶: Receive directive specific data

Parameters

struct nvme_directive_recv_args *args: struct nvme_directive_recv_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_recv_identify_parameters(int fd, __u32 nsid, struct nvme_id_directives *id)¶: Directive receive identifier parameters

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
struct nvme_id_directives *id: Identify parameters buffer

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_recv_stream_parameters(int fd, __u32 nsid, struct nvme_streams_directive_params *parms)¶: Directive receive stream parameters

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
struct nvme_streams_directive_params *parms: Streams directive parameters buffer

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_recv_stream_status(int fd, __u32 nsid, unsigned int nr_entries, struct nvme_streams_directive_status *id)¶: Directive receive stream status

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
unsigned int nr_entries: Number of streams to receive
struct nvme_streams_directive_status *id: Stream status buffer

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_directive_recv_stream_allocate(int fd, __u32 nsid, __u16 nsr, __u32 *result)¶: Directive receive stream allocate

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u16 nsr: Namespace Streams Requested
__u32 *result: If successful, the CQE dword0 value

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_capacity_mgmt(struct nvme_capacity_mgmt_args *args)¶: Capacity management command

Parameters

struct nvme_capacity_mgmt_args *args: struct nvme_capacity_mgmt_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lockdown(struct nvme_lockdown_args *args)¶: Issue lockdown command

Parameters

struct nvme_lockdown_args *args: struct nvme_lockdown_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_property(struct nvme_set_property_args *args)¶: Set controller property

Parameters

struct nvme_set_property_args *args: struct nvme_set_property_args argument structure

Description

This is an NVMe-over-Fabrics specific command, not applicable to PCIe. These properties align to the PCI MMIO controller registers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_property(struct nvme_get_property_args *args)¶: Get a controller property

Parameters

struct nvme_get_property_args *args: struct nvme_get_propert_args argument structure

Description

This is an NVMe-over-Fabrics specific command, not applicable to PCIe. These properties align to the PCI MMIO controller registers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_sanitize_nvm(struct nvme_sanitize_nvm_args *args)¶: Start a sanitize operation

Parameters

struct nvme_sanitize_nvm_args *args: struct nvme_sanitize_nvm_args argument structure

Description

A sanitize operation alters all user data in the NVM subsystem such that recovery of any previous user data from any cache, the non-volatile media, or any Controller Memory Buffer is not possible.

The Sanitize command starts a sanitize operation or to recover from a previously failed sanitize operation. The sanitize operation types that may be supported are Block Erase, Crypto Erase, and Overwrite. All sanitize operations are processed in the background, i.e., completion of the sanitize command does not indicate completion of the sanitize operation.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_dev_self_test(struct nvme_dev_self_test_args *args)¶: Start or abort a self test

Parameters

struct nvme_dev_self_test_args *args: struct nvme_dev_self_test argument structure

Description

The Device Self-test command starts a device self-test operation or abort a device self-test operation. A device self-test operation is a diagnostic testing sequence that tests the integrity and functionality of the controller and may include testing of the media associated with namespaces. The controller may return a response to this command immediately while running the self-test in the background.

Set the ‘nsid’ field to 0 to not include namespaces in the test. Set to 0xffffffff to test all namespaces. All other values tests a specific namespace, if present.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_virtual_mgmt(struct nvme_virtual_mgmt_args *args)¶: Virtualization resource management

Parameters

struct nvme_virtual_mgmt_args *args: struct nvme_virtual_mgmt_args argument structure

Description

The Virtualization Management command is supported by primary controllers that support the Virtualization Enhancements capability. This command is used for several functions:

Modifying Flexible Resource allocation for the primary controller

Assigning Flexible Resources for secondary controllers

Setting the Online and Offline state for secondary controllers

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_flush(int fd, __u32 nsid)¶: Send an nvme flush command

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace identifier

Description

The Flush command requests that the contents of volatile write cache be made non-volatile.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_io(struct nvme_io_args *args, __u8 opcode)¶: Submit an nvme user I/O command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure
__u8 opcode: Opcode to execute

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_read(struct nvme_io_args *args)¶: Submit an nvme user read command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_write(struct nvme_io_args *args)¶: Submit an nvme user write command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_compare(struct nvme_io_args *args)¶: Submit an nvme user compare command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_write_zeros(struct nvme_io_args *args)¶: Submit an nvme write zeroes command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Description

The Write Zeroes command sets a range of logical blocks to zero. After successful completion of this command, the value returned by subsequent reads of logical blocks in this range shall be all bytes cleared to 0h until a write occurs to this LBA range.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_write_uncorrectable(struct nvme_io_args *args)¶: Submit an nvme write uncorrectable command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Description

The Write Uncorrectable command marks a range of logical blocks as invalid. When the specified logical block(s) are read after this operation, a failure is returned with Unrecovered Read Error status. To clear the invalid logical block status, a write operation on those logical blocks is required.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_verify(struct nvme_io_args *args)¶: Send an nvme verify command

Parameters

struct nvme_io_args *args: struct nvme_io_args argument structure

Description

The Verify command verifies integrity of stored information by reading data and metadata, if applicable, for the LBAs indicated without transferring any data or metadata to the host.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_dsm(struct nvme_dsm_args *args)¶: Send an nvme data set management command

Parameters

struct nvme_dsm_args *args: struct nvme_dsm_args argument structure

Description

The Dataset Management command is used by the host to indicate attributes for ranges of logical blocks. This includes attributes like frequency that data is read or written, access size, and other information that may be used to optimize performance and reliability, and may be used to deallocate/unmap/trim those logical blocks.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_copy(struct nvme_copy_args *args)¶: Copy command

Parameters

struct nvme_copy_args *args: struct nvme_copy_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_resv_acquire(struct nvme_resv_acquire_args *args)¶: Send an nvme reservation acquire

Parameters

struct nvme_resv_acquire_args *args: struct nvme_resv_acquire argument structure

Description

The Reservation Acquire command acquires a reservation on a namespace, preempt a reservation held on a namespace, and abort a reservation held on a namespace.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_resv_register(struct nvme_resv_register_args *args)¶: Send an nvme reservation register

Parameters

struct nvme_resv_register_args *args: struct nvme_resv_register_args argument structure

Description

The Reservation Register command registers, unregisters, or replaces a reservation key.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_resv_release(struct nvme_resv_release_args *args)¶: Send an nvme reservation release

Parameters

struct nvme_resv_release_args *args: struct nvme_resv_release_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_resv_report(struct nvme_resv_report_args *args)¶: Send an nvme reservation report

Parameters

struct nvme_resv_report_args *args: struct nvme_resv_report_args argument structure

Description

Returns a Reservation Status data structure to memory that describes the registration and reservation status of a namespace. See the definition for the returned structure, struct nvme_reservation_status, for more details.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_io_mgmt_recv(struct nvme_io_mgmt_recv_args *args)¶: I/O Management Receive command

Parameters

struct nvme_io_mgmt_recv_args *args: struct nvme_io_mgmt_recv_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_fdp_reclaim_unit_handle_status(int fd, __u32 nsid, __u32 data_len, void *data)¶: Get reclaim unit handle status

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace identifier
__u32 data_len: Length of response buffer
void *data: Response buffer

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_io_mgmt_send(struct nvme_io_mgmt_send_args *args)¶: I/O Management Send command

Parameters

struct nvme_io_mgmt_send_args *args: struct nvme_io_mgmt_send_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_fdp_reclaim_unit_handle_update(int fd, __u32 nsid, unsigned int npids, __u16 *pids)¶: Update a list of reclaim unit handles

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace identifier
unsigned int npids: Number of placement identifiers
__u16 *pids: List of placement identifiers

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_mgmt_send(struct nvme_zns_mgmt_send_args *args)¶: ZNS management send command

Parameters

struct nvme_zns_mgmt_send_args *args: struct nvme_zns_mgmt_send_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_mgmt_recv(struct nvme_zns_mgmt_recv_args *args)¶: ZNS management receive command

Parameters

struct nvme_zns_mgmt_recv_args *args: struct nvme_zns_mgmt_recv_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_report_zones(int fd, __u32 nsid, __u64 slba, enum nvme_zns_report_options opts, bool extended, bool partial, __u32 data_len, void *data, __u32 timeout, __u32 *result)¶: Return the list of zones

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID
__u64 slba: Starting LBA
enum nvme_zns_report_options opts: Reporting options
bool extended: Extended report
bool partial: Partial report requested
__u32 data_len: Length of the data buffer
void *data: Userspace address of the report zones data
__u32 timeout: timeout in ms
__u32 *result: The command completion result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_zns_append(struct nvme_zns_append_args *args)¶: Append data to a zone

Parameters

struct nvme_zns_append_args *args: struct nvme_zns_append_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_dim_send(struct nvme_dim_args *args)¶: Send a Discovery Information Management (DIM) command

Parameters

struct nvme_dim_args *args: struct nvme_dim_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lm_cdq(struct nvme_lm_cdq_args *args)¶: Controller Data Queue - Controller Data Queue command

Parameters

struct nvme_lm_cdq_args *args: struct nvme_lm_cdq_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.)

int nvme_lm_track_send(struct nvme_lm_track_send_args *args)¶: Track Send command

Parameters

struct nvme_lm_track_send_args *args: struct nvme_lm_track_send_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lm_migration_send(struct nvme_lm_migration_send_args *args)¶: Migration Send command

Parameters

struct nvme_lm_migration_send_args *args: struct nvme_lm_migration_send_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lm_migration_recv(struct nvme_lm_migration_recv_args *args)¶: Migration Receive command

Parameters

struct nvme_lm_migration_recv_args *args: struct nvme_lm_migration_rev_args argument structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lm_set_features_ctrl_data_queue(int fd, __u16 cdqid, __u32 hp, __u32 tpt, bool etpt, __u32 *result)¶: Set Controller Datea Queue feature

Parameters

int fd: File descriptor of nvme device
__u16 cdqid: Controller Data Queue ID (CDQID)
__u32 hp: Head Pointer
__u32 tpt: Tail Pointer Trigger
bool etpt: Enable Tail Pointer Trigger
__u32 *result: The command completions result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_lm_get_features_ctrl_data_queue(int fd, __u16 cdqid, struct nvme_lm_ctrl_data_queue_fid_data *data, __u32 *result)¶: Get Controller Data Queue feature

Parameters

int fd: File descriptor of nvme device
__u16 cdqid: Controller Data Queue ID (CDQID)
struct nvme_lm_ctrl_data_queue_fid_data *data: Get Controller Data Queue feature data
__u32 *result: The command completions result from CQE dword0

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

fabrics.h

Fabrics-specific definitions.

struct nvme_fabrics_config¶: Defines all linux nvme fabrics initiator options

Definition

struct nvme_fabrics_config {
  char *host_traddr;
  char *host_iface;
  int queue_size;
  int nr_io_queues;
  int reconnect_delay;
  int ctrl_loss_tmo;
  int fast_io_fail_tmo;
  int keep_alive_tmo;
  int nr_write_queues;
  int nr_poll_queues;
  int tos;
  long keyring;
  long tls_key;
  long tls_configured_key;
  bool duplicate_connect;
  bool disable_sqflow;
  bool hdr_digest;
  bool data_digest;
  bool tls;
  bool concat;
};

Members

host_traddr: Host transport address
host_iface: Host interface name
queue_size: Number of IO queue entries
nr_io_queues: Number of controller IO queues to establish
reconnect_delay: Time between two consecutive reconnect attempts.
ctrl_loss_tmo: Override the default controller reconnect attempt timeout in seconds
fast_io_fail_tmo: Set the fast I/O fail timeout in seconds.
keep_alive_tmo: Override the default keep-alive-timeout to this value in seconds
nr_write_queues: Number of queues to use for exclusively for writing
nr_poll_queues: Number of queues to reserve for polling completions
tos: Type of service
keyring: Keyring to store and lookup keys
tls_key: TLS PSK for the connection
tls_configured_key: TLS PSK for connect command for the connection
duplicate_connect: Allow multiple connections to the same target
disable_sqflow: Disable controller sq flow control
hdr_digest: Generate/verify header digest (TCP)
data_digest: Generate/verify data digest (TCP)
tls: Start TLS on the connection (TCP)
concat: Enable secure concatenation (TCP)

struct nvme_fabrics_uri¶: Parsed URI structure

Definition

struct nvme_fabrics_uri {
  char *scheme;
  char *protocol;
  char *userinfo;
  char *host;
  int port;
  char **path_segments;
  char *query;
  char *fragment;
};

Members

scheme: Scheme name (typically ‘nvme’)
protocol: Optional protocol/transport (e.g. ‘tcp’)
userinfo: Optional user information component of the URI authority
host: Host transport address
port: The port subcomponent or 0 if not specified
path_segments: NULL-terminated array of path segments
query: Optional query string component (separated by ‘?’)
fragment: Optional fragment identifier component (separated by ‘#’)

const char *nvmf_trtype_str(__u8 trtype)¶: Decode TRTYPE field

Parameters

__u8 trtype: value to be decoded

Description

Decode the transport type field in the discovery log page entry.

Return

decoded string

const char *nvmf_adrfam_str(__u8 adrfam)¶: Decode ADRFAM field

Parameters

__u8 adrfam: value to be decoded

Description

Decode the address family field in the discovery log page entry.

Return

decoded string

const char *nvmf_subtype_str(__u8 subtype)¶: Decode SUBTYPE field

Parameters

__u8 subtype: value to be decoded

Description

Decode the subsystem type field in the discovery log page entry.

Return

decoded string

const char *nvmf_treq_str(__u8 treq)¶: Decode TREQ field

Parameters

__u8 treq: value to be decoded

Description

Decode the transport requirements field in the discovery log page entry.

Return

decoded string

const char *nvmf_eflags_str(__u16 eflags)¶: Decode EFLAGS field

Parameters

__u16 eflags: value to be decoded

Description

Decode the EFLAGS field in the discovery log page entry.

Return

decoded string

const char *nvmf_sectype_str(__u8 sectype)¶: Decode SECTYPE field

Parameters

__u8 sectype: value to be decoded

Description

Decode the SECTYPE field in the discovery log page entry.

Return

decoded string

const char *nvmf_prtype_str(__u8 prtype)¶: Decode RDMA Provider type field

Parameters

__u8 prtype: value to be decoded

Description

Decode the RDMA Provider type field in the discovery log page entry.

Return

decoded string

const char *nvmf_qptype_str(__u8 qptype)¶: Decode RDMA QP Service type field

Parameters

__u8 qptype: value to be decoded

Description

Decode the RDMA QP Service type field in the discovery log page entry.

Return

decoded string

const char *nvmf_cms_str(__u8 cms)¶: Decode RDMA connection management service field

Parameters

__u8 cms: value to be decoded

Description

Decode the RDMA connection management service field in the discovery log page entry.

Return

decoded string

void nvmf_default_config(struct nvme_fabrics_config *cfg)¶: Default values for fabrics configuration

Parameters

struct nvme_fabrics_config *cfg: config values to set

Description

Initializes cfg with default values.

void nvmf_update_config(nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)¶: Update fabrics configuration values

Parameters

nvme_ctrl_t c: Controller to be modified
const struct nvme_fabrics_config *cfg: Updated configuration values

Description

Updates the values from c with the configuration values from cfg; all non-default values from cfg will overwrite the values in c.

int nvmf_add_ctrl(nvme_host_t h, nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)¶: Connect a controller and update topology

Parameters

nvme_host_t h: Host to which the controller should be attached
nvme_ctrl_t c: Controller to be connected
const struct nvme_fabrics_config *cfg: Default configuration for the controller

Description

Issues a ‘connect’ command to the NVMe-oF controller and inserts c into the topology using h as parent. c must be initialized and not connected to the topology.

Return

0 on success; on failure errno is set and -1 is returned.

int nvmf_connect_ctrl(nvme_ctrl_t c)¶: Connect a controller

Parameters

nvme_ctrl_t c: Controller to be connected

Description

Issues a ‘connect’ command to the NVMe-oF controller. c must be initialized and not connected to the topology.

Return

0 on success; on failure errno is set and -1 is returned.

int nvmf_get_discovery_log(nvme_ctrl_t c, struct nvmf_discovery_log **logp, int max_retries)¶: Return the discovery log page

Parameters

nvme_ctrl_t c: Discovery controller to use
struct nvmf_discovery_log **logp: Pointer to the log page to be returned
int max_retries: Number of retries in case of failure

Description

The memory allocated for the log page and returned in logp must be freed by the caller using free().

Note

Consider using nvmf_get_discovery_wargs() instead.

Return

0 on success; on failure -1 is returned and errno is set

struct nvme_get_discovery_args¶: Arguments for nvmf_get_discovery_wargs()

Definition

struct nvme_get_discovery_args {
  nvme_ctrl_t c;
  int args_size;
  int max_retries;
  __u32 *result;
  __u32 timeout;
  __u8 lsp;
};

Members

c: Discovery controller
args_size: Length of the structure
max_retries: Number of retries in case of failure
result: The command completion result from CQE dword0
timeout: Timeout in ms (default: NVME_DEFAULT_IOCTL_TIMEOUT)
lsp: Log specific field (See enum nvmf_log_discovery_lsp)

struct nvmf_discovery_log *nvmf_get_discovery_wargs(struct nvme_get_discovery_args *args)¶: Get the discovery log page with args

Parameters

struct nvme_get_discovery_args *args: Argument structure

Description

This function is similar to nvmf_get_discovery_log(), but takes an extensible args parameter. args provides more options than nvmf_get_discovery_log().

This function performs a get discovery log page (DLP) command and returns the DLP. The memory allocated for the returned DLP must be freed by the caller using free().

Return

Pointer to the discovery log page (to be freed). NULL on failure and errno is set.

char *nvmf_hostnqn_generate()¶: Generate a machine specific host nqn

Parameters

Return

An nvm namespace qualified name string based on the machine identifier, or NULL if not successful.

char *nvmf_hostnqn_generate_from_hostid(char *hostid)¶: Generate a host nqn from host identifier

Parameters

char *hostid: Host identifier

Description

If hostid is NULL, the function generates it based on the machine identifier.

Return

On success, an NVMe Qualified Name for host identification. This name is based on the given host identifier. On failure, NULL.

char *nvmf_hostid_generate()¶: Generate a machine specific host identifier

Parameters

Return

On success, an identifier string based on the machine identifier to be used as NVMe Host Identifier, or NULL on failure.

char *nvmf_hostnqn_from_file()¶: Reads the host nvm qualified name from the config default location

Parameters

Description

Retrieve the qualified name from the config file located in $SYSCONFIDR/nvme. $SYSCONFDIR is usually /etc.

Return

The host nqn, or NULL if unsuccessful. If found, the caller is responsible to free the string.

char *nvmf_hostid_from_file()¶: Reads the host identifier from the config default location

Parameters

Description

Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/. $SYSCONFDIR is usually /etc.

Return

The host identifier, or NULL if unsuccessful. If found, the caller: is responsible to free the string.

nvme_ctrl_t nvmf_connect_disc_entry(nvme_host_t h, struct nvmf_disc_log_entry *e, const struct nvme_fabrics_config *defcfg, bool *discover)¶: Connect controller based on the discovery log page entry

Parameters

nvme_host_t h: Host to which the controller should be connected
struct nvmf_disc_log_entry *e: Discovery log page entry
const struct nvme_fabrics_config *defcfg: Default configuration to be used for the new controller
bool *discover: Set to ‘true’ if the new controller is a discovery controller

Return

Pointer to the new controller

bool nvmf_is_registration_supported(nvme_ctrl_t c)¶: check whether registration can be performed.

Parameters

nvme_ctrl_t c: Controller instance

Description

Only discovery controllers (DC) that comply with TP8010 support explicit registration with the DIM PDU. These can be identified by looking at the value of a dctype in the Identify command response. A value of 1 (DDC) or 2 (CDC) indicates that the DC supports explicit registration.

Return

true if controller supports explicit registration. false otherwise.

int nvmf_register_ctrl(nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result)¶: Perform registration task with a DC

Parameters

nvme_ctrl_t c: Controller instance
enum nvmf_dim_tas tas: Task field of the Command Dword 10 (cdw10). Indicates whether to perform a Registration, Deregistration, or Registration-update.
__u32 *result: The command-specific result returned by the DC upon command completion.

Description

Perform registration task with a Discovery Controller (DC). Three tasks are supported: register, deregister, and registration update.

Return

0 on success; on failure -1 is returned and errno is set

struct nvme_fabrics_uri *nvme_parse_uri(const char *str)¶: Parse the URI string

Parameters

const char *str: URI string

Description

Parse the URI string as defined in the NVM Express Boot Specification. Supported URI elements looks as follows:

nvme+tcp://user**host**:port/subsys_nqn/nid?query=val#fragment

Return

nvme_fabrics_uri structure on success; NULL on failure with errno set.

void nvme_free_uri(struct nvme_fabrics_uri *uri)¶: Free the URI structure

Parameters

struct nvme_fabrics_uri *uri: nvme_fabrics_uri structure

Description

Free an nvme_fabrics_uri structure.

linux.h

linux-specific utility functions

int nvme_fw_download_seq(int fd, __u32 size, __u32 xfer, __u32 offset, void *buf)¶: Firmware download sequence

Parameters

int fd: File descriptor of nvme device
__u32 size: Total size of the firmware image to transfer
__u32 xfer: Maximum size to send with each partial transfer
__u32 offset: Starting offset to send with this firmware download
void *buf: Address of buffer containing all or part of the firmware image.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_set_etdas(int fd, bool *changed)¶: Set the Extended Telemetry Data Area 4 Supported bit

Parameters

int fd: File descriptor of nvme device
bool *changed: boolean to indicate whether or not the host behavior support feature had been changed

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_clear_etdas(int fd, bool *changed)¶: Clear the Extended Telemetry Data Area 4 Supported bit

Parameters

int fd: File descriptor of nvme device
bool *changed: boolean to indicate whether or not the host behavior support feature had been changed

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_uuid_list(int fd, struct nvme_id_uuid_list *uuid_list)¶: Returns the uuid list (if supported)

Parameters

int fd: File descriptor of nvme device
struct nvme_id_uuid_list *uuid_list: UUID list returned by identify UUID

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_telemetry_max(int fd, enum nvme_telemetry_da *da, size_t *max_data_tx)¶: Get telemetry limits

Parameters

int fd: File descriptor of nvme device
enum nvme_telemetry_da *da: On success return max supported data area
size_t *max_data_tx: On success set to max transfer chunk supported by the controller

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_telemetry_log(int fd, bool create, bool ctrl, bool rae, size_t max_data_tx, enum nvme_telemetry_da da, struct nvme_telemetry_log **log, size_t *size)¶: Get specified telemetry log

Parameters

int fd: File descriptor of nvme device
bool create: Generate new host initated telemetry capture
bool ctrl: Get controller Initiated log
bool rae: Retain asynchronous events
size_t max_data_tx: Set the max data transfer size to be used retrieving telemetry.
enum nvme_telemetry_da da: Log page data area, valid values: enum nvme_telemetry_da.
struct nvme_telemetry_log **log: On success, set to the value of the allocated and retrieved log.
size_t *size: Ptr to the telemetry log size, so it can be returned

Description

The total size allocated can be calculated as:: (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_ctrl_telemetry(int fd, bool rae, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)¶: Get controller telemetry log

Parameters

int fd: File descriptor of nvme device
bool rae: Retain asynchronous events
struct nvme_telemetry_log **log: On success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da da: Log page data area, valid values: enum nvme_telemetry_da
size_t *size: Ptr to the telemetry log size, so it can be returned

Description

The total size allocated can be calculated as:: (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_host_telemetry(int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)¶: Get host telemetry log

Parameters

int fd: File descriptor of nvme device
struct nvme_telemetry_log **log: On success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da da: Log page data area, valid values: enum nvme_telemetry_da
size_t *size: Ptr to the telemetry log size, so it can be returned

Description

The total size allocated can be calculated as:: (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_new_host_telemetry(int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)¶: Get new host telemetry log

Parameters

int fd: File descriptor of nvme device
struct nvme_telemetry_log **log: On success, set to the value of the allocated and retrieved log.
enum nvme_telemetry_da da: Log page data area, valid values: enum nvme_telemetry_da
size_t *size: Ptr to the telemetry log size, so it can be returned

Description

The total size allocated can be calculated as:: (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

size_t nvme_get_ana_log_len_from_id_ctrl(const struct nvme_id_ctrl *id_ctrl, bool rgo)¶: Retrieve maximum possible ANA log size

Parameters

const struct nvme_id_ctrl *id_ctrl: Controller identify data
bool rgo: If true, return maximum log page size without NSIDs

Return

A byte limit on the size of the controller’s ANA log page

int nvme_get_ana_log_len(int fd, size_t *analen)¶: Retrieve size of the current ANA log

Parameters

int fd: File descriptor of nvme device
size_t *analen: Pointer to where the length will be set on success

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_logical_block_size(int fd, __u32 nsid, int *blksize)¶: Retrieve block size

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace id
int *blksize: Pointer to where the block size will be set on success

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_get_lba_status_log(int fd, bool rae, struct nvme_lba_status_log **log)¶: Retrieve the LBA Status log page

Parameters

int fd: File descriptor of the nvme device
bool rae: Retain asynchronous events
struct nvme_lba_status_log **log: On success, set to the value of the allocated and retrieved log.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_namespace_attach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist)¶: Attach namespace to controller(s)

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID to attach
__u16 num_ctrls: Number of controllers in ctrlist
__u16 *ctrlist: List of controller IDs to perform the attach action

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_namespace_detach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist)¶: Detach namespace from controller(s)

Parameters

int fd: File descriptor of nvme device
__u32 nsid: Namespace ID to detach
__u16 num_ctrls: Number of controllers in ctrlist
__u16 *ctrlist: List of controller IDs to perform the detach action

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_open(const char *name)¶: Open an nvme controller or namespace device

Parameters

const char *name: The basename of the device to open

Description

This will look for the handle in /dev/ and validate the name and filetype match linux conventions.

Return

A file descriptor for the device on a successful open, or -1 with errno set otherwise.

enum nvme_hmac_alg¶: HMAC algorithm

Constants

NVME_HMAC_ALG_NONE: No HMAC algorithm
NVME_HMAC_ALG_SHA2_256: SHA2-256
NVME_HMAC_ALG_SHA2_384: SHA2-384
NVME_HMAC_ALG_SHA2_512: SHA2-512

int nvme_gen_dhchap_key(char *hostnqn, enum nvme_hmac_alg hmac, unsigned int key_len, unsigned char *secret, unsigned char *key)¶: DH-HMAC-CHAP key generation

Parameters

char *hostnqn: Host NVMe Qualified Name
enum nvme_hmac_alg hmac: HMAC algorithm
unsigned int key_len: Output key length
unsigned char *secret: Secret to used for digest
unsigned char *key: Generated DH-HMAC-CHAP key

Return

If key generation was successful the function returns 0 or -1 with errno set otherwise.

long nvme_lookup_keyring(const char *keyring)¶: Lookup keyring serial number

Parameters

const char *keyring: Keyring name

Description

Looks up the serial number of the keyring keyring.

Return

The key serial number of the keyring or 0 with errno set otherwise.

char *nvme_describe_key_serial(long key_id)¶: Return key description

Parameters

long key_id: Key serial number

Description

Fetches the description of the key or keyring identified by the serial number key_id.

Return

The description of key_id or NULL on failure. The returned string needs to be freed by the caller.

long nvme_lookup_key(const char *type, const char *identity)¶: Lookup key serial number

Parameters

const char *type: Key type
const char *identity: Key description

Description

Looks up the serial number of the key identity with type type in the current session keyring.

Return

The key serial number of the key or 0 with errno set otherwise.

int nvme_set_keyring(long keyring_id)¶: Link keyring for lookup

Parameters

long keyring_id: Keyring id

Description

Links keyring_id into the session keyring such that its keys are available for further key lookups.

Return

0 on success, a negative number on error with errno set.

unsigned char *nvme_read_key(long keyring_id, long key_id, int *len)¶: Read key raw data

Parameters

long keyring_id: Id of the keyring holding key_id
long key_id: Key id
int *len: Length of the returned data

Description

Links the keyring specified by keyring_id into the session keyring and reads the payload of the key specified by key_id. len holds the size of the returned buffer. If keyring is 0 the default keyring ‘.nvme’ is used.

Return

Pointer to the payload on success, or NULL with errno set otherwise.

long nvme_update_key(long keyring_id, const char *key_type, const char *identity, unsigned char *key_data, int key_len)¶: Update key raw data

Parameters

long keyring_id: Id of the keyring holding key_id
const char *key_type: Type of the key to insert
const char *identity: Key identity string
unsigned char *key_data: Raw data of the key
int key_len: Length of key_data

Description

Links the keyring specified by keyring_id into the session keyring and updates the key reference by identity with key_data. The old key with identity identity will be revoked to make it inaccessible.

Return

Key id of the new key or 0 with errno set otherwise.

nvme_scan_tls_keys_cb_t¶: Typedef: Callback for iterating TLS keys

Syntax

void nvme_scan_tls_keys_cb_t (long keyring, long key, char *desc, int desc_len, void *data)

Parameters

long keyring: Keyring which has been iterated
long key: Key for which the callback has been invoked
char *desc: Description of the key
int desc_len: Length of desc
void *data: Pointer for caller data

Description

Called for each TLS PSK in the keyring.

int nvme_scan_tls_keys(const char *keyring, nvme_scan_tls_keys_cb_t cb, void *data)¶: Iterate over TLS keys in a keyring

Parameters

const char *keyring: Keyring holding TLS keys
nvme_scan_tls_keys_cb_t cb: Callback function
void *data: Pointer for data to be passed to cb

Description

Iterates keyring and call cb for each TLS key. When keyring is NULL the default ‘.nvme’ keyring is used. A TLS key must be of type ‘psk’ and the description must be of the form ‘NVMe<0|1><R|G>0<1|2> <identity>’, otherwise it will be skipped during iteration.

Return

Number of keys for which cb was called, or -1 with errno set on error.

long nvme_insert_tls_key(const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len)¶: Derive and insert TLS key

Parameters

const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a and stores it as type key_type in the keyring specified by keyring.

Return

The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.

long nvme_insert_tls_key_versioned(const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)¶: Derive and insert TLS key

Parameters

const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring.

Return

The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.

long nvme_insert_tls_key_compat(const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)¶: Derive and insert TLS key

Parameters

const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring. This version differs from nvme_insert_tls_key_versioned() in that it uses the original implementation for HKDF Expand-Label which does not prefix the ‘info’ and ‘label’ strings with the length.

Return

The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.

char *nvme_generate_tls_key_identity(const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)¶: Generate the TLS key identity

Parameters

const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity.

Return

The string containing the TLS identity. It is the responsibility of the caller to free the returned string. On error NULL is returned with errno set.

char *nvme_generate_tls_key_identity_compat(const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)¶: Generate the TLS key identity

Parameters

const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity. This version differs from nvme_generate_tls_key_identity() in that it uses the original implementation for HKDF-Expand-Label which does not prefix the ‘info’ and ‘label’ string with the length.

Return

The string containing the TLS identity. It is the responsibility of the caller to free the returned string.

long nvme_revoke_tls_key(const char *keyring, const char *key_type, const char *identity)¶: Revoke TLS key from keyring

Parameters

const char *keyring: Keyring to use
const char *key_type: Type of the key to revoke
const char *identity: Key identity string

Return

0 on success or on failure -1 with errno set.

char *nvme_export_tls_key(const unsigned char *key_data, int key_len)¶: Export a TLS key

Parameters

const unsigned char *key_data: Raw data of the key
int key_len: Length of key_data

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

Return

The string containing the TLS identity or NULL with errno set on error. It is the responsibility of the caller to free the returned string.

char *nvme_export_tls_key_versioned(unsigned char version, unsigned char hmac, const unsigned char *key_data, size_t key_len)¶: Export a TLS pre-shared key

Parameters

unsigned char version: Indicated the representation of the TLS PSK
unsigned char hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
const unsigned char *key_data: Raw data of the key
size_t key_len: Length of key_data

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

Return

The string containing the TLS identity or NULL with errno set on error. It is the responsibility of the caller to free the returned string.

unsigned char *nvme_import_tls_key(const char *encoded_key, int *key_len, unsigned int *hmac)¶: Import a TLS key

Parameters

const char *encoded_key: TLS key in PSK interchange format
int *key_len: Length of the resulting key data
unsigned int *hmac: HMAC algorithm

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

Return

The raw data of the PSK or NULL with errno set on error. It is the responsibility of the caller to free the returned string.

unsigned char *nvme_import_tls_key_versioned(const char *encoded_key, unsigned char *version, unsigned char *hmac, size_t *key_len)¶: Import a TLS key

Parameters

const char *encoded_key: TLS key in PSK interchange format
unsigned char *version: Indicated the representation of the TLS PSK
unsigned char *hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
size_t *key_len: Length of the resulting key data

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

Return

The raw data of the PSK or NULL with errno set on error. It is the responsibility of the caller to free the returned string.

int nvme_submit_passthru(int fd, unsigned long ioctl_cmd, struct nvme_passthru_cmd *cmd, __u32 *result)¶: Low level ioctl wrapper for passthru commands

Parameters

int fd: File descriptor of the nvme device
unsigned long ioctl_cmd: IOCTL command id
struct nvme_passthru_cmd *cmd: Passhtru command
__u32 *result: Optional field to return the result

Description

This is a low level library function which should not be used directly. It is exposed as weak symbol so that the user application is able to provide their own implementation of this function with additional debugging or logging code.

Return

The value from the ioctl system call (see ioctl documentation)

int nvme_submit_passthru64(int fd, unsigned long ioctl_cmd, struct nvme_passthru_cmd64 *cmd, __u64 *result)¶: Low level ioctl wrapper for passthru commands

Parameters

int fd: File descriptor of the nvme device
unsigned long ioctl_cmd: IOCTL command id
struct nvme_passthru_cmd64 *cmd: Passhtru command
__u64 *result: Optional field to return the result

Description

This is a low level library function which should not be used directly. It is exposed as weak symbol so that the user application is able to provide their own implementation of this function with additional debugging or logging code.

Return

The value from the ioctl system call (see ioctl documentation)

mi.h - NVMe Management Interface library (libnvme-mi) definitions.

These provide an abstraction for the MI messaging between controllers and a host, typically over an MCTP-over-i2c link to a NVMe device, used as part of the out-of-band management of a system.

We have a few data structures define here to reflect the topology of a MI connection with an NVMe subsystem:

nvme_mi_ep_t: an MI endpoint - our mechanism of communication with a NVMe subsystem. For MCTP, an endpoint will be the component that holds the MCTP address (EID), and receives our request message.

endpoints are defined in the NVMe-MI spec, and are specific to the MI interface.

Each endpoint will provide access to one or more of:

nvme_mi_ctrl_t: a NVMe controller, as defined by the NVMe base spec. The controllers are responsible for processing any NVMe standard commands (eg, the Admin command set). An endpoint (nvme_mi_ep_t) may provide access to multiple controllers - so each of the controller- type commands will require a nvme_mi_ctrl_t to be specified, rather than an endpoint

A couple of conventions with the libnvme-mi API:

All types and functions have the nvme_mi prefix, to distinguish from the libnvme core.

We currently support either MI commands and Admin commands. The former adds a _mi prefix, the latter an _admin prefix. [This does result in the MI functions having a double _mi, like nvme_mi_mi_subsystem_health_status_poll, which is apparently amusing for our German-speaking readers]

For return values: unless specified in the per-function documentation, all functions:

return 0 on success

return -1, with errno set, for errors communicating with the MI device, either in request or response data

return >1 on MI status errors. This value is the 8-bit MI status value, represented by enum nvme_mi_resp_status. Note that the status values may be vendor-defined above 0xe0.

For the second case, we have a few conventions for errno values:

EPROTO: response data violated the MI protocol, and libnvme cannot validly interpret the response

EIO: Other I/O error communicating with device (eg., valid but unexpected response data)

EINVAL: invalid input arguments for a command

In line with the core NVMe API, the Admin command functions take an _args structure to provide the command-specific parameters. However, for the MI interface, the fd and timeout members of these _args structs are ignored.

References to the specifications here will either to be the NVM Express Management Interface (“NVMe-MI”) or the NVM Express Base specification (“NVMe”). At the time of writing, the versions we’re referencing here are:

NVMe-MI 1.2b

NVMe 2.0b

with a couple of accommodations for older spec types, particularly NVMe-MI 1.1, where possible.

NVME_MI_MSGTYPE_NVME¶

NVME_MI_MSGTYPE_NVME ()

MCTP message type for NVMe-MI messages.

Parameters

Description

This is defined by MCTP, but is referenced as part of the NVMe-MI message spec. This is the MCTP NVMe message type (0x4), with the message-integrity bit (0x80) set.

enum nvme_mi_message_type¶: NVMe-MI message type field.

Constants

NVME_MI_MT_CONTROL: NVME-MI Control Primitive
NVME_MI_MT_MI: NVMe-MI command
NVME_MI_MT_ADMIN: NVMe Admin command
NVME_MI_MT_PCIE: PCIe command
NVME_MI_MT_AE: Asynchronous Event

Description

Used as byte 1 of both request and response messages (NMIMT bits of NMP byte). Not to be confused with the MCTP message type in byte 0.

enum nvme_mi_ror¶: Request or response field.

Constants

NVME_MI_ROR_REQ: request message
NVME_MI_ROR_RSP: response message

enum nvme_mi_resp_status¶: values for the response status field

Constants

NVME_MI_RESP_SUCCESS: success
NVME_MI_RESP_MPR: More Processing Required
NVME_MI_RESP_INTERNAL_ERR: Internal Error
NVME_MI_RESP_INVALID_OPCODE: Invalid command opcode
NVME_MI_RESP_INVALID_PARAM: Invalid command parameter
NVME_MI_RESP_INVALID_CMD_SIZE: Invalid command size
NVME_MI_RESP_INVALID_INPUT_SIZE: Invalid command input data size
NVME_MI_RESP_ACCESS_DENIED: Access Denied
NVME_MI_RESP_VPD_UPDATES_EXCEEDED: More VPD updates than allowed
NVME_MI_RESP_PCIE_INACCESSIBLE: PCIe functionality currently unavailable
NVME_MI_RESP_MEB_SANITIZED: MEB has been cleared due to sanitize
NVME_MI_RESP_ENC_SERV_FAILURE: Enclosure services process failed
NVME_MI_RESP_ENC_SERV_XFER_FAILURE: Transfer with enclosure services failed
NVME_MI_RESP_ENC_FAILURE: Unreoverable enclosure failure
NVME_MI_RESP_ENC_XFER_REFUSED: Enclosure services transfer refused
NVME_MI_RESP_ENC_FUNC_UNSUP: Unsupported enclosure services function
NVME_MI_RESP_ENC_SERV_UNAVAIL: Enclosure services unavailable
NVME_MI_RESP_ENC_DEGRADED: Noncritical failure detected by enc. services
NVME_MI_RESP_SANITIZE_IN_PROGRESS: Command prohibited during sanitize

struct nvme_mi_msg_hdr¶: General MI message header.

Definition

struct nvme_mi_msg_hdr {
  __u8 type;
  __u8 nmp;
  __u8 meb;
  __u8 rsvd0;
};

Members

type: MCTP message type, will always be NVME_MI_MSGTYPE_NVME
nmp: NVMe-MI message parameters (including MI message type)
meb: Management Endpoint Buffer flag; unused for libnvme-mi implementation
rsvd0: currently reserved

Description

Wire format shared by both request and response messages, per NVMe-MI section 3.1. This is used for all message types, MI and Admin.

struct nvme_mi_msg_resp¶: Generic response type.

Definition

struct nvme_mi_msg_resp {
  struct nvme_mi_msg_hdr hdr;
  __u8 status;
  __u8 rsvd0[3];
};

Members

hdr: the general request/response message header
status: response status value (see enum nvme_mi_resp_status)
rsvd0: reserved data, may be defined by specific response

Description

Every response will start with one of these; command-specific responses will define parts of the reserved data, and may add further fields.

enum nvme_mi_mi_opcode¶: Operation code for supported NVMe-MI commands.

Constants

nvme_mi_mi_opcode_mi_data_read: Read NVMe-MI Data Structure
nvme_mi_mi_opcode_subsys_health_status_poll: Subsystem Health Status Poll
nvme_mi_mi_opcode_configuration_set: MI Configuration Set
nvme_mi_mi_opcode_configuration_get: MI Configuration Get

struct nvme_mi_mi_req_hdr¶: MI request message header.

Definition

struct nvme_mi_mi_req_hdr {
  struct nvme_mi_msg_hdr hdr;
  __u8 opcode;
  __u8 rsvd0[3];
  __le32 cdw0, cdw1;
};

Members

hdr: generic MI message header
opcode: opcode (OPC) for the specific MI command
rsvd0: reserved bytes
cdw0: Management Request Doubleword 0 - command specific usage
cdw1: Management Request Doubleword 1 - command specific usage

Description

Wire format for MI request message headers, defined in section 5 of NVMe-MI.

struct nvme_mi_mi_resp_hdr¶: MI response message header.

Definition

struct nvme_mi_mi_resp_hdr {
  struct nvme_mi_msg_hdr hdr;
  __u8 status;
  __u8 nmresp[3];
};

Members

hdr: generic MI message header
status: generic response status from command; non-zero on failure.
nmresp: NVMe Management Response: command-type-specific response data

Description

Wire format for MI response message header, defined in section 5 of NVMe-MI.

enum nvme_mi_dtyp¶: Data Structure Type field.

Constants

nvme_mi_dtyp_subsys_info: NVM Subsystem Information
nvme_mi_dtyp_port_info: Port information
nvme_mi_dtyp_ctrl_list: Controller List
nvme_mi_dtyp_ctrl_info: Controller Information
nvme_mi_dtyp_opt_cmd_support: Optionally Supported Command List
nvme_mi_dtyp_meb_support: Management Endpoint Buffer Command Support List

Description

Data Structure Type field for Read NVMe-MI Data Structure command, used to indicate the particular structure to query from the endpoint.

enum nvme_mi_config_id¶: NVMe-MI Configuration identifier.

Constants

NVME_MI_CONFIG_SMBUS_FREQ: Current SMBus/I2C frequency
NVME_MI_CONFIG_HEALTH_STATUS_CHANGE: Health Status change - used to clear health status bits in CCS bits of status poll. Only for Set ops.
NVME_MI_CONFIG_MCTP_MTU: MCTP maximum transmission unit size of port specified in dw 0
NVME_MI_CONFIG_AE: Asynchronous Events configuration Configuration parameters for the MI Get/Set Configuration commands.

Description

See :c:type:`nvme_mi_mi_config_get`() and :c:type:`nvme_mi_config_set`().

enum nvme_mi_config_smbus_freq¶: SMBus/I2C frequency values

Constants

NVME_MI_CONFIG_SMBUS_FREQ_100kHz: 100kHz
NVME_MI_CONFIG_SMBUS_FREQ_400kHz: 400kHz
NVME_MI_CONFIG_SMBUS_FREQ_1MHz: 1MHz

Description

Values used in the SMBus Frequency device configuration. See :c:type:`nvme_mi_mi_config_get_smbus_freq`() and :c:type:`nvme_mi_mi_config_set_smbus_freq`().

struct nvme_mi_aem_supported_list_header¶: Asynchronous Event Supported List Header.

Definition

struct nvme_mi_aem_supported_list_header {
  __u8 numaes;
  __u8 aeslver;
  __le16 aest;
  __u8 aeslhl;
};

Members

numaes: Number of AE supported data structures that follow the header
aeslver: AE Supported List Version
aest: AE Supported list length (including this header)
aeslhl: AE Supported list header length

Description

This header preceeds a number, (numaes), of AE supported data structures

struct nvme_mi_aem_supported_item¶: AE Supported List Item

Definition

struct nvme_mi_aem_supported_item {
  __u8 aesl;
  __le16 aesi;
};

Members

aesl: AE supported list item length
aesi: AE supported info

Description

Following this header should be hdr.numaes entries of nvme_mi_aem_supported_item structures

bool nvme_mi_aem_aesi_get_aese(__le16 aesi)¶: return aese from aesi field

Parameters

__le16 aesi: aesi field from nvme_mi_aem_supported_item

Return

A bool representing the aese value

__u8 nvme_mi_aem_aesi_get_aesid(__le16 aesi)¶: return aesid from aesi field

Parameters

__le16 aesi: aesi field from nvme_mi_aem_supported_item

Return

aesid value

void nvme_mi_aem_aesi_set_aesid(struct nvme_mi_aem_supported_item *item, __u8 aesid)¶: set aesid in the aesi field

Parameters

struct nvme_mi_aem_supported_item *item: Pointer to nvme_mi_aem_supported_item to update the aesi field
__u8 aesid: aesid value to use

void nvme_mi_aem_aesi_set_aee(struct nvme_mi_aem_supported_item *item, bool enabled)¶: set aee in the aesi field

Parameters

struct nvme_mi_aem_supported_item *item: Pointer to nvme_mi_aem_supported_item to update the aesi field
bool enabled: aee value to use

struct nvme_mi_aem_supported_list¶: AE Supported List received with GET CONFIG Asynchronous Event

Definition

struct nvme_mi_aem_supported_list {
  struct nvme_mi_aem_supported_list_header hdr;
};

Members

hdr: AE supported list header

Description

Following this header should be hdr.numaes entries of nvme_mi_aem_supported_item structures

struct nvme_mi_aem_enable_item¶: AE Enabled item entry

Definition

struct nvme_mi_aem_enable_item {
  __u8 aeel;
  __le16 aeei;
};

Members

aeel: AE Enable Length (length of this structure which is 3)
aeei: AE Enable Info

bool nvme_mi_aem_aeei_get_aee(__le16 aeei)¶: return aee from aeei field

Parameters

__le16 aeei: aeei field from nvme_mi_aem_enable_item

Return

aee value

__u8 nvme_mi_aem_aeei_get_aeeid(__le16 aeei)¶: return aeeid from aeei field

Parameters

__le16 aeei: aeei field from nvme_mi_aem_enable_item

Return

aeeid value

void nvme_mi_aem_aeei_set_aeeid(struct nvme_mi_aem_enable_item *item, __u8 aeeid)¶: set aeeid in the aeei field

Parameters

struct nvme_mi_aem_enable_item *item: Pointer to nvme_mi_aem_enable_item to update the aeei field
__u8 aeeid: aeeid value to use

void nvme_mi_aem_aeei_set_aee(struct nvme_mi_aem_enable_item *item, bool enabled)¶: set aee in the aeei field

Parameters

struct nvme_mi_aem_enable_item *item: Pointer to nvme_mi_aem_enable_item to update the aee field
bool enabled: aee value to use

struct nvme_mi_aem_enable_list_header¶: AE Enable list header

Definition

struct nvme_mi_aem_enable_list_header {
  __u8 numaee;
  __u8 aeelver;
  __le16 aeetl;
  __u8 aeelhl;
};

Members

numaee: Number of AE enable items following the header
aeelver: Version of the AE enable list (zero)
aeetl: Total length of the AE enable list including header and items
aeelhl: Header length of this header (5)

struct nvme_mi_aem_enable_list¶: AE enable list sent with SET CONFIG Asyncronous Event

Definition

struct nvme_mi_aem_enable_list {
  struct nvme_mi_aem_enable_list_header hdr;
};

Members

hdr: AE enable list header

Description

Following this header should be hdr.numaee entries of nvme_mi_aem_enable_item structures

struct nvme_mi_aem_occ_data¶: AEM Message definition.

Definition

struct nvme_mi_aem_occ_data {
  __u8 aelhlen;
  __u8 aeosil;
  __u8 aeovsil;
  struct {
    __u8 aeoi;
    __le32 aeocidi;
    __u8 aessi;
  } aeoui;
};

Members

aelhlen: AE Occurrence Header Length
aeosil: AE Occurrence Specific Info Length
aeovsil: AE Occurrence Vendor Specific Info Length
aeoui: AE Occurrence Unique ID made up of other subfields

Description

A single entry of ae occurrence data that comes with an nvme_aem_msg. Following this structure is variable length AEOSI (occurrence specific info) and variable length AEVSI (vendor specific info). The length of AEOSI is specified by aeosil and the length of AEVSI is specified by AEVSI. Neither field is mandatory and shall be omitted if their length parameter is set to zero.

struct nvme_mi_aem_occ_list_hdr¶: AE occurrence list header

Definition

struct nvme_mi_aem_occ_list_hdr {
  __u8 numaeo;
  __u8 aelver;
  __u8 aeolli[3];
  __u8 aeolhl;
  __u8 aemti;
};

Members

numaeo: Number of AE Occurrence Data Structures
aelver: AE Occurrence List Version Number
aeolli: AE Occurrence List Length Info (AEOLLI)
aeolhl: AE Occurrence List Header Length (shall be set to 7)
aemti: AEM Transmission Info

Description

The header for the occurrence list. numaeo defines how many nvme_mi_aem_occ_data structures (including variable payaloads) are included. Following this header is each of the numaeo occurrence data structures.

__u8 nvme_mi_aem_aemti_get_aemgn(__u8 aemti)¶: return aemgn from aemti field

Parameters

__u8 aemti: aemti field from nvme_mi_aem_occ_list_hdr

Return

aemgn value

__u32 nvme_mi_aem_aeolli_get_aeoltl(__u8 *aeolli)¶: return aeoltl from aeolli field

Parameters

__u8 *aeolli: Pointer to 3 byte aeolli field from nvme_mi_aem_occ_list_hdr

Return

aeoltl value

void nvme_mi_aem_aeolli_set_aeoltl(struct nvme_mi_aem_occ_list_hdr *hdr, __u32 aeoltl)¶: set aeoltl in the aeolli field

Parameters

struct nvme_mi_aem_occ_list_hdr *hdr: Pointer to nvme_mi_aem_occ_list_hdr to set the aeolli field
__u32 aeoltl: aeoltl value to use

struct nvme_mi_aem_msg¶: AEM Message definition.

Definition

struct nvme_mi_aem_msg {
  struct nvme_mi_msg_hdr hdr;
  struct nvme_mi_aem_occ_list_hdr occ_list_hdr;
};

Members

hdr: the general response message header
occ_list_hdr: ae occurrence list header.

Description

Every ae message will start with one of these. The occ_list_hder wil define information about how many ae occ data entries are included. Each entry is defined by the nvme_mi_aem_occ_data structure which will follow the occ_list_hdr. Each nvme_mi_aem_occ_data structure has a fixed length header but a variable length payload ude to occurrence specific and vendor specific info. For this reason, do not index the nvme_mi_ae_occ data structures by array or fixed offset.

struct nvme_mi_admin_req_hdr¶: Admin command request header.

Definition

struct nvme_mi_admin_req_hdr {
  struct nvme_mi_msg_hdr hdr;
  __u8 opcode;
  __u8 flags;
  __le16 ctrl_id;
  __le32 cdw1, cdw2, cdw3, cdw4, cdw5;
  __le32 doff;
  __le32 dlen;
  __le32 rsvd0, rsvd1;
  __le32 cdw10, cdw11, cdw12, cdw13, cdw14, cdw15;
};

Members

hdr: Generic MI message header
opcode: Admin command opcode (using enum nvme_admin_opcode)
flags: Command Flags, indicating dlen and doff validity; Only defined in NVMe-MI version 1.1, no fields defined in 1.2 (where the dlen/doff are always considered valid).
ctrl_id: Controller ID target of command
cdw1: Submission Queue Entry doubleword 1
cdw2: Submission Queue Entry doubleword 2
cdw3: Submission Queue Entry doubleword 3
cdw4: Submission Queue Entry doubleword 4
cdw5: Submission Queue Entry doubleword 5
doff: Offset of data to return from command
dlen: Length of sent/returned data
rsvd0: Reserved
rsvd1: Reserved
cdw10: Submission Queue Entry doubleword 10
cdw11: Submission Queue Entry doubleword 11
cdw12: Submission Queue Entry doubleword 12
cdw13: Submission Queue Entry doubleword 13
cdw14: Submission Queue Entry doubleword 14
cdw15: Submission Queue Entry doubleword 15

Description

Wire format for Admin command message headers, defined in section 6 of NVMe-MI.

struct nvme_mi_admin_resp_hdr¶: Admin command response header.

Definition

struct nvme_mi_admin_resp_hdr {
  struct nvme_mi_msg_hdr hdr;
  __u8 status;
  __u8 rsvd0[3];
  __le32 cdw0, cdw1, cdw3;
};

Members

hdr: Generic MI message header
status: Generic response code, non-zero on failure
rsvd0: Reserved
cdw0: Completion Queue Entry doubleword 0
cdw1: Completion Queue Entry doubleword 1
cdw3: Completion Queue Entry doubleword 3

Description

This is the generic response format with the three doublewords of completion queue data, plus optional response data.

enum nvme_mi_control_opcode¶: Operation code for Control Primitives.

Constants

nvme_mi_control_opcode_pause: Suspend response transmission/timeout
nvme_mi_control_opcode_resume: Resume from a paused condition
nvme_mi_control_opcode_abort: Re-initialize a Command Slot to the Idle state
nvme_mi_control_opcode_get_state: Get the state of a Command Slot
nvme_mi_control_opcode_replay: Retransmit the Response Message

struct nvme_mi_control_req¶: The Control Primitive request.

Definition

struct nvme_mi_control_req {
  struct nvme_mi_msg_hdr hdr;
  __u8 opcode;
  __u8 tag;
  __le16 cpsp;
};

Members

hdr: Generic MI message header
opcode: Control Primitive Opcodes (using enum nvme_mi_control_opcode)
tag: flag - Opaque value passed from request to response
cpsp: Control Primitive Specific Parameter

const char *nvme_mi_status_to_string(int status)¶: return a string representation of the MI status.

Parameters

int status: MI response status

Description

Gives a string description of status, as per section 4.1.2 of the NVMe-MI spec. The status value should be of type NVME_STATUS_MI, and extracted from the return value using nvme_status_get_value().

Returned string is const, and should not be free()ed.

Return

A string representing the status value

nvme_root_t nvme_mi_create_root(FILE *fp, int log_level)¶: Create top-level MI (root) handle.

Parameters

FILE *fp: File descriptor for logging messages
int log_level: Logging level to use

Description

Create the top-level (library) handle for creating subsequent endpoint objects. Similar to nvme_create_root(), but we provide this to allow linking without the core libnvme.

See nvme_create_root.

Return

new root object, or NULL on failure.

void nvme_mi_free_root(nvme_root_t root)¶: Free root object.

Parameters

nvme_root_t root: root to free

void nvme_mi_set_probe_enabled(nvme_root_t root, bool enabled)¶: enable/disable the probe for new endpoints

Parameters

nvme_root_t root: nvme_root_t object
bool enabled: whether to probe new endpoints

Description

Controls whether newly-created endpoints are probed for quirks on creation. Defaults to enabled, which results in some initial messaging with the endpoint to determine model-specific details.

type nvme_mi_ep_t¶: MI Endpoint object.

Description

Represents our communication endpoint on the remote MI-capable device. To be used for direct MI commands for the endpoint (through the nvme_mi_mi_* functions(), or to communicate with individual controllers (see nvme_mi_init_ctrl).

Endpoints are created through a transport-specific constructor; currently only MCTP-connected endpoints are supported, through nvme_mi_open_mctp. Subsequent operations on the endpoint (and related controllers) are transport-independent.

int nvme_mi_set_csi(nvme_mi_ep_t ep, uint8_t csi)¶: Assign a CSI to an endpoint.

Parameters

nvme_mi_ep_t ep: Endpoint
uint8_t csi: value to use for CSI bit in NMP (0 or 1) for this endpoint

Return

0 if successful, -1 otherwise (some endpoints may not support)

nvme_mi_ep_t nvme_mi_first_endpoint(nvme_root_t m)¶: Start endpoint iterator

Parameters

nvme_root_t m: nvme_root_t object

Return

first MI endpoint object under this root, or NULL if no endpoints: are present.

Description

See: nvme_mi_next_endpoint, nvme_mi_for_each_endpoint

nvme_mi_ep_t nvme_mi_next_endpoint(nvme_root_t m, nvme_mi_ep_t e)¶: Continue endpoint iterator

Parameters

nvme_root_t m: nvme_root_t object
nvme_mi_ep_t e: nvme_mi_ep_t current position of iterator

Return

next endpoint MI endpoint object after e under this root, or NULL: if no further endpoints are present.

Description

See: nvme_mi_first_endpoint, nvme_mi_for_each_endpoint

nvme_mi_for_each_endpoint¶

nvme_mi_for_each_endpoint (m, e)

Iterator for NVMe-MI endpoints.

Parameters

m: nvme_root_t containing endpoints
e: nvme_mi_ep_t object, set on each iteration

nvme_mi_for_each_endpoint_safe¶

nvme_mi_for_each_endpoint_safe (m, e, _e)

Iterator for NVMe-MI endpoints, allowing deletion during traversal

Parameters

m: nvme_root_t containing endpoints
e: nvme_mi_ep_t object, set on each iteration
_e: nvme_mi_ep_t object used as temporary storage

int nvme_mi_ep_set_timeout(nvme_mi_ep_t ep, unsigned int timeout_ms)¶: set a timeout for NVMe-MI responses

Parameters

nvme_mi_ep_t ep: MI endpoint object
unsigned int timeout_ms: Timeout for MI responses, given in milliseconds

void nvme_mi_ep_set_mprt_max(nvme_mi_ep_t ep, unsigned int mprt_max_ms)¶: set the maximum wait time for a More Processing Required response

Parameters

nvme_mi_ep_t ep: MI endpoint object
unsigned int mprt_max_ms: Maximum more processing required wait time

Description

NVMe-MI endpoints may respond to a request with a “More Processing Required” response; this also includes a hint on the worst-case processing time for the eventual response data, with a specification-defined maximum of 65.535 seconds.

This function provides a way to limit the maximum time we’re prepared to wait for the final response. Specify zero in mprt_max_ms for no limit. This should be larger than the command/response timeout set in :c:type:`nvme_mi_ep_set_timeout`().

unsigned int nvme_mi_ep_get_timeout(nvme_mi_ep_t ep)¶: get the current timeout value for NVMe-MI responses

Parameters

nvme_mi_ep_t ep: MI endpoint object

Description

Returns the current timeout value, in milliseconds, for this endpoint.

type nvme_mi_ctrl_t¶: NVMe-MI Controller object.

Description

Provides NVMe command functionality, through the MI interface.

nvme_mi_ctrl_t nvme_mi_first_ctrl(nvme_mi_ep_t ep)¶: Start controller iterator

Parameters

nvme_mi_ep_t ep: nvme_mi_ep_t object

Return

first MI controller object under this root, or NULL if no controllers: are present.

Description

See: nvme_mi_next_ctrl, nvme_mi_for_each_ctrl

nvme_mi_ctrl_t nvme_mi_next_ctrl(nvme_mi_ep_t ep, nvme_mi_ctrl_t c)¶: Continue ctrl iterator

Parameters

nvme_mi_ep_t ep: nvme_mi_ep_t object
nvme_mi_ctrl_t c: nvme_mi_ctrl_t current position of iterator

Return

next MI controller object after c under this endpoint, or NULL: if no further controllers are present.

Description

See: nvme_mi_first_ctrl, nvme_mi_for_each_ctrl

nvme_mi_for_each_ctrl¶

nvme_mi_for_each_ctrl (ep, c)

Iterator for NVMe-MI controllers.

Parameters

ep: nvme_mi_ep_t containing endpoints
c: nvme_mi_ctrl_t object, set on each iteration

Description

Allows iteration of the list of controllers behind an endpoint. Unless the controllers have already been created explicitly, you’ll probably want to call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first.

See: :c:type:`nvme_mi_scan_ep`()

nvme_mi_for_each_ctrl_safe¶

nvme_mi_for_each_ctrl_safe (ep, c, _c)

Iterator for NVMe-MI controllers, allowing deletion during traversal

Parameters

ep: nvme_mi_ep_t containing controllers
c: nvme_mi_ctrl_t object, set on each iteration
_c: nvme_mi_ctrl_t object used as temporary storage

Description

Allows iteration of the list of controllers behind an endpoint, safe against deletion during iteration. Unless the controllers have already been created explicitly (or you’re just iterating to destroy controllers) you’ll probably want to call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first.

See: :c:type:`nvme_mi_scan_ep`()

nvme_mi_ep_t nvme_mi_open_mctp(nvme_root_t root, unsigned int netid, uint8_t eid)¶: Create an endpoint using a MCTP connection.

Parameters

nvme_root_t root: root object to create under
unsigned int netid: MCTP network ID on this system
uint8_t eid: MCTP endpoint ID

Description

Transport-specific endpoint initialization for MI-connected endpoints. Once an endpoint is created, the rest of the API is transport-independent.

See nvme_mi_close

Return

New endpoint object for netid & eid, or NULL on failure.

int nvme_mi_aem_open(nvme_mi_ep_t ep)¶: Prepare an existing endpoint to receive AEMs

Parameters

nvme_mi_ep_t ep: Endpoint to configure for AEMs

Return

0 if success, -1 otherwise

void nvme_mi_close(nvme_mi_ep_t ep)¶: Close an endpoint connection and release resources, including controller objects.

Parameters

nvme_mi_ep_t ep: Endpoint object to close

nvme_root_t nvme_mi_scan_mctp(void)¶: look for MCTP-connected NVMe-MI endpoints.

Parameters

void: no arguments

Description

This function queries the system MCTP daemon (“mctpd”) over D-Bus, to find MCTP endpoints that report support for NVMe-MI over MCTP.

This requires libvnme-mi to be compiled with D-Bus support; if not, this will return NULL.

Return

A nvme_root_t populated with a set of MCTP-connected endpoints,: or NULL on failure

int nvme_mi_scan_ep(nvme_mi_ep_t ep, bool force_rescan)¶: query an endpoint for its NVMe controllers.

Parameters

nvme_mi_ep_t ep: Endpoint to scan
bool force_rescan: close existing controllers and rescan

Description

This function queries an MI endpoint for the controllers available, by performing an MI Read MI Data Structure command (requesting the controller list). The controllers are stored in the endpoint’s internal list, and can be iterated with nvme_mi_for_each_ctrl.

This will only scan the endpoint once, unless force_rescan is set. If so, all existing controller objects will be freed - the caller must not hold a reference to those across this call.

See: nvme_mi_for_each_ctrl

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

nvme_mi_ctrl_t nvme_mi_init_ctrl(nvme_mi_ep_t ep, __u16 ctrl_id)¶: initialise a NVMe controller.

Parameters

nvme_mi_ep_t ep: Endpoint to create under
__u16 ctrl_id: ID of controller to initialize.

Description

Create a connection to a controller behind the endpoint specified in ep. Controller IDs may be queried from the endpoint through nvme_mi_mi_read_mi_data_ctrl_list.

See nvme_mi_close_ctrl

Return

New controller object, or NULL on failure.

void nvme_mi_close_ctrl(nvme_mi_ctrl_t ctrl)¶: free a controller

Parameters

nvme_mi_ctrl_t ctrl: controller to free

__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.

char *nvme_mi_endpoint_desc(nvme_mi_ep_t ep)¶: Get a string describing a MI endpoint.

Parameters

nvme_mi_ep_t ep: endpoint to describe

Description

Generates a human-readable string describing the endpoint, with possibly transport-specific data. The string is allocated during the call, and the caller is responsible for free()-ing the string.

Return

a newly-allocated string containing the endpoint description, or: NULL on failure.

int nvme_mi_mi_xfer(nvme_mi_ep_t ep, struct nvme_mi_mi_req_hdr *mi_req, size_t req_data_size, struct nvme_mi_mi_resp_hdr *mi_resp, size_t *resp_data_size)¶: Raw mi transfer interface.

Parameters

nvme_mi_ep_t ep: endpoint to send the MI command to
struct nvme_mi_mi_req_hdr *mi_req: request data
size_t req_data_size: size of request data payload
struct nvme_mi_mi_resp_hdr *mi_resp: buffer for response data
size_t *resp_data_size: size of response data buffer, updated to received size

Description

Performs an arbitrary NVMe MI command, using the provided request data, in mi_req. The size of the request data payload is specified in req_data_size - this does not include the standard header length (so a header-only request would have a size of 0). Note that the Management Request Doublewords are considered part of the header data.

On success, response data is stored in mi_resp, which has an optional appended payload buffer of resp_data_size bytes. The actual payload size transferred will be stored in resp_data_size. This size does not include the MI response header, so 0 represents no payload.

See: struct nvme_mi_mi_req_hdr and struct nvme_mi_mi_resp_hdr.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_read_mi_data_subsys(nvme_mi_ep_t ep, struct nvme_mi_read_nvm_ss_info *s)¶: Perform a Read MI Data Structure command, retrieving subsystem data.

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
struct nvme_mi_read_nvm_ss_info *s: subsystem information to populate

Description

Retrieves the Subsystem information - number of external ports and NVMe version information. See struct nvme_mi_read_nvm_ss_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_read_mi_data_port(nvme_mi_ep_t ep, __u8 portid, struct nvme_mi_read_port_info *p)¶: Perform a Read MI Data Structure command, retrieving port data.

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 portid: id of port data to retrieve
struct nvme_mi_read_port_info *p: port information to populate

Description

Retrieves the Port information, for the specified port ID. The subsystem data (from nvme_mi_mi_read_mi_data_subsys) nmp field contains the allowed range of port IDs.

See struct nvme_mi_read_port_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_read_mi_data_ctrl_list(nvme_mi_ep_t ep, __u8 start_ctrlid, struct nvme_ctrl_list *list)¶: Perform a Read MI Data Structure command, retrieving the list of attached controllers.

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 start_ctrlid: starting controller ID
struct nvme_ctrl_list *list: controller list to populate

Description

Retrieves the list of attached controllers, with IDs greater than or equal to start_ctrlid.

See struct nvme_ctrl_list.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_read_mi_data_ctrl(nvme_mi_ep_t ep, __u16 ctrl_id, struct nvme_mi_read_ctrl_info *ctrl)¶: Perform a Read MI Data Structure command, retrieving controller information

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u16 ctrl_id: ID of controller to query
struct nvme_mi_read_ctrl_info *ctrl: controller data to populate

Description

Retrieves the Controller Information Data Structure for the attached controller with ID ctrlid.

See struct nvme_mi_read_ctrl_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_subsystem_health_status_poll(nvme_mi_ep_t ep, bool clear, struct nvme_mi_nvm_ss_health_status *nshds)¶: Read the Subsystem Health Data Structure from the NVM subsystem

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
bool clear: flag to clear the Composite Controller Status state
struct nvme_mi_nvm_ss_health_status *nshds: subsystem health status data to populate

Description

Retrieves the Subsystem Health Data Structure into nshds. If clear is set, requests that the Composite Controller Status bits are cleared after the read. See NVMe-MI section 5.6 for details on the CCS bits.

See struct nvme_mi_nvm_ss_health_status.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_get(nvme_mi_ep_t ep, __u32 dw0, __u32 dw1, __u32 *nmresp)¶: query a configuration parameter

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u32 dw0: management doubleword 0, containing configuration identifier, plus config-specific fields
__u32 dw1: management doubleword 0, config-specific.
__u32 *nmresp: set to queried configuration data in NMRESP field of response.

Description

Performs a MI Configuration Get command, with the configuration identifier as the LSB of dw0. Other dw0 and dw1 data is configuration-identifier specific.

On a successful Configuration Get, the nmresp pointer will be populated with the bytes from the 3-byte NMRESP field, converted to native endian.

See enum nvme_mi_config_id for identifiers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_set(nvme_mi_ep_t ep, __u32 dw0, __u32 dw1)¶: set a configuration parameter

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u32 dw0: management doubleword 0, containing configuration identifier, plus config-specific fields
__u32 dw1: management doubleword 0, config-specific.

Description

Performs a MI Configuration Set command, with the command as the LSB of dw0. Other dw0 and dw1 data is configuration-identifier specific.

See enum nvme_mi_config_id for identifiers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_get_smbus_freq(nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq *freq)¶: get configuration: SMBus port frequency

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to query
enum nvme_mi_config_smbus_freq *freq: output value for current frequency configuration

Description

Performs a MI Configuration Get, to query the current SMBus frequency of the port specified in port. On success, populates freq with the port frequency

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_set_smbus_freq(nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq freq)¶: set configuration: SMBus port frequency

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to set
enum nvme_mi_config_smbus_freq freq: new frequency configuration

Description

Performs a MI Configuration Set, to update the current SMBus frequency of the port specified in port.

See struct nvme_mi_read_port_info for the maximum supported SMBus frequency for the port.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_set_health_status_change(nvme_mi_ep_t ep, __u32 mask)¶: clear CCS bits in health status

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u32 mask: bitmask to clear

Description

Performs a MI Configuration Set, to update the current health status poll values of the Composite Controller Status bits. Bits set in mask will be cleared from future health status poll data, and may be re-triggered by a future health change event.

See nvme_mi_mi_subsystem_health_status_poll`(), :c:type:`enum nvme_mi_ccs for values in mask.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_get_mctp_mtu(nvme_mi_ep_t ep, __u8 port, __u16 *mtu)¶: get configuration: MCTP MTU

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to query
__u16 *mtu: output value for current MCTP MTU configuration

Description

Performs a MI Configuration Get, to query the current MCTP Maximum Transmission Unit size (MTU) of the port specified in port. On success, populates mtu with the MTU.

The default reset value is 64, corresponding to the MCTP baseline MTU.

Some controllers may also use this as the maximum receive unit size, and may not accept MCTP messages larger than the configured MTU.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_set_mctp_mtu(nvme_mi_ep_t ep, __u8 port, __u16 mtu)¶: set configuration: MCTP MTU

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to set
__u16 mtu: new MTU configuration

Description

Performs a MI Configuration Set, to update the current MCTP MTU value for the port specified in port.

Some controllers may also use this as the maximum receive unit size, and may not accept MCTP messages larger than the configured MTU. When setting this value, you will likely need to change the MTU of the local MCTP interface(s) to match.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_get_async_event(nvme_mi_ep_t ep, __u8 *aeelver, struct nvme_mi_aem_supported_list *list, size_t *list_num_bytes)¶: get configuration: Asynchronous Event

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 *aeelver: Asynchronous Event Enable List Version Number
struct nvme_mi_aem_supported_list *list: AE Supported list header and list contents
size_t *list_num_bytes: number of bytes in the list header and contents buffer. This will be populated with returned size of list and contents if successful.

Description

Performs a MI Configuration Get, to query the current enable Asynchronous Events. On success, populates aeelver and the list with current info,

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_mi_config_set_async_event(nvme_mi_ep_t ep, bool envfa, bool empfa, bool encfa, __u8 aemd, __u8 aerd, struct nvme_mi_aem_enable_list *enable_list, size_t enable_list_size, struct nvme_mi_aem_occ_list_hdr *occ_list, size_t *occ_list_size)¶: set configuration: Asynchronous Event

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
bool envfa: Enable SR-IOV Virtual Functions AE
bool empfa: Enable SR-IOV Physical Functions AE
bool encfa: Enable PCI Functions AE.
__u8 aemd: AEM Delay Interval (for Sync only)
__u8 aerd: AEM Retry Delay (for Sync only; time in 100s of ms)
struct nvme_mi_aem_enable_list *enable_list: nvme_mi_aem_enable_listucture containing header and items of events to be enabled or disabled. This is taken as a delta change from the current configuration.
size_t enable_list_size: Size of the enable_list including header and data. Meant to catch overrun issues.
struct nvme_mi_aem_occ_list_hdr *occ_list: Pointer to populate with the occurrence list (header and data)
size_t *occ_list_size: Total size of provided occ_list buffer. Will be updated with received size if successful

Description

Performs a MI Configuration Set, to ACK (sent after an AEM) or Sync (at anytime to enable or disable Asynchronous Events).

On success, populates occ_list. See TP6035a for details on how occ_list is populated in ACK versus Sync conditions

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_admin_xfer(nvme_mi_ctrl_t ctrl, struct nvme_mi_admin_req_hdr *admin_req, size_t req_data_size, struct nvme_mi_admin_resp_hdr *admin_resp, off_t resp_data_offset, size_t *resp_data_size)¶: Raw admin transfer interface.

Parameters

nvme_mi_ctrl_t ctrl: controller to send the admin command to
struct nvme_mi_admin_req_hdr *admin_req: request data
size_t req_data_size: size of request data payload
struct nvme_mi_admin_resp_hdr *admin_resp: buffer for response data
off_t resp_data_offset: offset into request data to retrieve from controller
size_t *resp_data_size: size of response data buffer, updated to received size

Description

Performs an arbitrary NVMe Admin command, using the provided request data, in admin_req. The size of the request data payload is specified in req_data_size - this does not include the standard header length (so a header-only request would have a size of 0).

On success, response data is stored in admin_resp, which has an optional appended payload buffer of resp_data_size bytes. The actual payload transferred will be stored in resp_data_size. These sizes do not include the Admin request header, so 0 represents no payload.

As with all Admin commands, we can request partial data from the Admin Response payload, offset by resp_data_offset.

See: struct nvme_mi_admin_req_hdr and struct nvme_mi_admin_resp_hdr.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise..

int nvme_mi_admin_admin_passthru(nvme_mi_ctrl_t ctrl, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u32 *result)¶: Submit an nvme admin passthrough command

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
__u8 opcode: The nvme admin command to send
__u8 flags: NVMe command flags (not used)
__u16 rsvd: Reserved for future use
__u32 nsid: Namespace identifier
__u32 cdw2: Command dword 2
__u32 cdw3: Command dword 3
__u32 cdw10: Command dword 10
__u32 cdw11: Command dword 11
__u32 cdw12: Command dword 12
__u32 cdw13: Command dword 13
__u32 cdw14: Command dword 14
__u32 cdw15: Command dword 15
__u32 data_len: Length of the data transferred in this command in bytes
void *data: Pointer to user address of the data buffer
__u32 metadata_len: Length of metadata transferred in this command(not used)
void *metadata: Pointer to user address of the metadata buffer(not used)
__u32 timeout_ms: How long to wait for the command to complete
__u32 *result: Optional field to return the result from the CQE dword 0

Description

Send a customized NVMe Admin command request message and get the corresponding response message.

This interface supports no data, host to controller and controller to host but it doesn’t support bidirectional data transfer. Also this interface only supports data transfer size range [0, 4096] (bytes) so the & data_len parameter must be less than 4097.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_partial(nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args, off_t offset, size_t size)¶: Perform an Admin identify command, and retrieve partial response data.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
struct nvme_identify_args *args: Identify command arguments
off_t offset: offset of identify data to retrieve from response
size_t size: size of identify data to return

Description

Perform an Identify command, using the Identify command parameters in args. The offset and size arguments allow the caller to retrieve part of the identify response. See NVMe-MI section 6.2 for the semantics (and some handy diagrams) of the offset & size parameters.

Will return an error if the length of the response data (from the controller) did not match size.

Unless you’re performing a vendor-unique identify command, You’ll probably want to use one of the identify helpers (nvme_mi_admin_identify, nvme_mi_admin_identify_cns_nsid, or nvme_mi_admin_identify_<type>) instead of this. If the type of your identify command is standardized but not yet supported by libnvme-mi, please contact the maintainers.

See: struct nvme_identify_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify(nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args)¶: Perform an Admin identify command.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
struct nvme_identify_args *args: Identify command arguments

Description

Perform an Identify command, using the Identify command parameters in args. Stores the identify data in ->data, and (if set) the result from cdw0 into args->result.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE.

See: struct nvme_identify_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_control(nvme_mi_ep_t ep, __u8 opcode, __u16 cpsp, __u16 *result_cpsr)¶: Perform a Control Primitive command

Parameters

nvme_mi_ep_t ep: endpoint for MI communication
__u8 opcode: Control Primitive opcode (using enum nvme_mi_control_opcode)
__u16 cpsp: Control Primitive Specific Parameter
__u16 *result_cpsr: Optional field to return the result from the CPSR field

Description

Perform a Control Primitive command, using the opcode specified in opcode Stores the result from the CPSR field in result_cpsr if set.

See: enum nvme_mi_control_opcode

Return

0 on success, non-zero on failure

int nvme_mi_admin_identify_cns_nsid(nvme_mi_ctrl_t ctrl, enum nvme_identify_cns cns, __u32 nsid, void *data)¶: Perform an Admin identify command using specific CNS/NSID parameters.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
enum nvme_identify_cns cns: Controller or Namespace Structure, specifying identified object
__u32 nsid: namespace ID
void *data: buffer for identify data response

Description

Perform an Identify command, using the CNS specifier cns, and the namespace ID nsid if required by the CNS type.

Stores the identify data in data, which is expected to be a buffer of NVME_IDENTIFY_DATA_SIZE bytes.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_ns(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_id_ns *ns)¶: Perform an Admin identify command for a namespace

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: namespace ID
struct nvme_id_ns *ns: Namespace identification to populate

Description

Perform an Identify (namespace) command, setting the namespace id data in ns. The namespace is expected to active and allocated.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_ns_descs(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_id_desc *descs)¶: Perform an Admin identify Namespace Identification Descriptor list command for a namespace

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: Namespace ID
struct nvme_ns_id_desc *descs: Namespace Identification Descriptor list to populate

Description

Perform an Identify namespace identification description list command, setting the namespace identification description list in descs

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_allocated_ns(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_id_ns *ns)¶: Perform an Admin identify command for an allocated namespace

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: namespace ID
struct nvme_id_ns *ns: Namespace identification to populate

Description

Perform an Identify (namespace) command, setting the namespace id data in ns.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_ctrl(nvme_mi_ctrl_t ctrl, struct nvme_id_ctrl *id)¶: Perform an Admin identify for a controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
struct nvme_id_ctrl *id: Controller identify data to populate

Description

Perform an Identify command, for the controller specified by ctrl, writing identify data to id.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so id will be fully populated on success.

See: struct nvme_id_ctrl

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_ctrl_list(nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_ctrl_list *list)¶: Perform an Admin identify for a controller list.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u16 cntid: Controller ID to specify list start
struct nvme_ctrl_list *list: List data to populate

Description

Perform an Identify command, for the controller list starting with IDs greater than or equal to cntid.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so id will be fully populated on success.

See: struct nvme_ctrl_list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_nsid_ctrl_list(nvme_mi_ctrl_t ctrl, __u32 nsid, __u16 cntid, struct nvme_ctrl_list *list)¶: Perform an Admin identify for a controller list with specific namespace ID

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: Namespace identifier
__u16 cntid: Controller ID to specify list start
struct nvme_ctrl_list *list: List data to populate

Description

Perform an Identify command, for the controller list for nsid, starting with IDs greater than or equal to cntid.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so id will be fully populated on success.

See: struct nvme_ctrl_list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_allocated_ns_list(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_list *list)¶: Perform an Admin identify for an allocated namespace list

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: Namespace ID to specify list start
struct nvme_ns_list *list: List data to populate

Description

Perform an Identify command, for the allocated namespace list starting with IDs greater than or equal to nsid. Specify NVME_NSID_NONE for the start of the list.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so list will be be fully populated on success.

See: struct nvme_ns_list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_active_ns_list(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_list *list)¶: Perform an Admin identify for an active namespace list

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u32 nsid: Namespace ID to specify list start
struct nvme_ns_list *list: List data to populate

Description

Perform an Identify command, for the active namespace list starting with IDs greater than or equal to nsid. Specify NVME_NSID_NONE for the start of the list.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so list will be be fully populated on success.

See: struct nvme_ns_list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_identify_primary_ctrl(nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_primary_ctrl_cap *cap)¶: Perform an Admin identify for primary controller capabilities data structure.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u16 cntid: Controller ID to specify
struct nvme_primary_ctrl_cap *cap: Primary Controller Capabilities data structure to populate

Description

Perform an Identify command to get the Primary Controller Capabilities data for the controller specified by cntid

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so cap will be be fully populated on success.

See: struct nvme_primary_ctrl_cap

Return

0 on success, non-zero on failure

int nvme_mi_admin_identify_secondary_ctrl_list(nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_secondary_ctrl_list *list)¶: Perform an Admin identify for a secondary controller list.

Parameters

nvme_mi_ctrl_t ctrl: Controller to process identify command
__u16 cntid: Controller ID to specify list start
struct nvme_secondary_ctrl_list *list: List data to populate

Description

Perform an Identify command, for the secondary controllers associated with the current primary controller. Only entries with IDs greater than or equal to cntid are returned.

Will return an error if the length of the response data (from the controller) is not a full NVME_IDENTIFY_DATA_SIZE, so list will be be fully populated on success.

See: struct nvme_secondary_ctrl_list

Return

0 on success, non-zero on failure

int nvme_mi_admin_get_log_page(nvme_mi_ctrl_t ctrl, __u32 xfer_len, struct nvme_get_log_args *args)¶: Retrieve log page data from controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u32 xfer_len: The chunk size of the read
struct nvme_get_log_args *args: Get Log Page command arguments

Description

Performs a Get Log Page Admin command as specified by args. Response data is stored in args->data, which should be a buffer of args->data_len bytes. Resulting data length is stored in args->data_len on successful command completion.

This request may be implemented as multiple log page commands, in order to fit within MI message-size limits.

See: struct nvme_get_log_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log(nvme_mi_ctrl_t ctrl, struct nvme_get_log_args *args)¶: Retrieve log page data from controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
struct nvme_get_log_args *args: Get Log Page command arguments

Description

Performs a Get Log Page Admin command as specified by args. Response data is stored in args->data, which should be a buffer of args->data_len bytes. Resulting data length is stored in args->data_len on successful command completion.

This request may be implemented as multiple log page commands, in order to fit within MI message-size limits.

See: struct nvme_get_log_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_nsid_log(nvme_mi_ctrl_t ctrl, bool rae, enum nvme_cmd_get_log_lid lid, __u32 nsid, __u32 len, void *log)¶: Helper for Get Log Page functions

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain Asynchronous Events
enum nvme_cmd_get_log_lid lid: Log identifier
__u32 nsid: Namespace ID
__u32 len: length of log buffer
void *log: pointer for resulting log data

Description

Performs a Get Log Page Admin command for a specific log ID lid and namespace ID nsid. Log data is expected to be len bytes, and is stored in log on success. The rae flag is passed as-is to the Get Log Page command, and is specific to the Log Page requested.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_endgid_log(nvme_mi_ctrl_t ctrl, bool rae, enum nvme_cmd_get_log_lid lid, __u16 endgid, __u32 len, void *log)¶: Helper for Get Endurance Group ID Log Page functions

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain Asynchronous Events
enum nvme_cmd_get_log_lid lid: Log identifier
__u16 endgid: Endurance Group ID
__u32 len: length of log buffer
void *log: pointer for resulting log data

Description

Performs a Get Log Page Admin command for a specific log ID lid and endurance group ID endgid. Log data is expected to be len bytes, and is stored in log on success. The rae flag is passed as-is to the Get Log Page command, and is specific to the Log Page requested.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_simple(nvme_mi_ctrl_t ctrl, enum nvme_cmd_get_log_lid lid, __u32 len, void *log)¶: Helper for Get Log Page functions with no NSID or RAE requirements

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
enum nvme_cmd_get_log_lid lid: Log identifier
__u32 len: length of log buffer
void *log: pointer for resulting log data

Description

Performs a Get Log Page Admin command for a specific log ID lid, using NVME_NSID_ALL for the namespace identifier, and rae set to false.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_supported_log_pages(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_supported_log_pages *log)¶: Retrieve nmve supported log pages

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_supported_log_pages *log: Array of LID supported and Effects data structures

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_error(nvme_mi_ctrl_t ctrl, unsigned int nr_entries, bool rae, struct nvme_error_log_page *err_log)¶: Retrieve nvme error log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
unsigned int nr_entries: Number of error log entries allocated
bool rae: Retain asynchronous events
struct nvme_error_log_page *err_log: Array of error logs of size ‘entries’

Description

This log page describes extended error information for a command that completed with error, or may report an error that is not specific to a particular command.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_smart(nvme_mi_ctrl_t ctrl, __u32 nsid, bool rae, struct nvme_smart_log *smart_log)¶: Retrieve nvme smart log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u32 nsid: Optional namespace identifier
bool rae: Retain asynchronous events
struct nvme_smart_log *smart_log: User address to store the smart log

Description

This log page provides SMART and general health information. The information provided is over the life of the controller and is retained across power cycles. To request the controller log page, the namespace identifier specified is FFFFFFFFh. The controller may also support requesting the log page on a per namespace basis, as indicated by bit 0 of the LPA field in the Identify Controller data structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_fw_slot(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_firmware_slot *fw_log)¶: Retrieves the controller firmware log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_firmware_slot *fw_log: User address to store the log page

Description

This log page describes the firmware revision stored in each firmware slot supported. The firmware revision is indicated as an ASCII string. The log page also indicates the active slot number.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_changed_ns_list(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_ns_list *ns_log)¶: Retrieve namespace changed list

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_ns_list *ns_log: User address to store the log page

Description

This log page describes namespaces attached to this controller that have changed since the last time the namespace was identified, been added, or deleted.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_cmd_effects(nvme_mi_ctrl_t ctrl, enum nvme_csi csi, struct nvme_cmd_effects_log *effects_log)¶: Retrieve nvme command effects log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
enum nvme_csi csi: Command Set Identifier
struct nvme_cmd_effects_log *effects_log: User address to store the effects log

Description

This log page describes the commands that the controller supports and the effects of those commands on the state of the NVM subsystem.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_device_self_test(nvme_mi_ctrl_t ctrl, struct nvme_self_test_log *log)¶: Retrieve the device self test log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
struct nvme_self_test_log *log: Userspace address of the log payload

Description

The log page indicates the status of an in progress self test and the percent complete of that operation, and the results of the previous 20 self-test operations.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_create_telemetry_host_mcda(nvme_mi_ctrl_t ctrl, enum nvme_telemetry_da mcda, struct nvme_telemetry_log *log)¶: Create host telemetry log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
enum nvme_telemetry_da mcda: Maximum Created Data Area
struct nvme_telemetry_log *log: Userspace address of the log payload

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_create_telemetry_host(nvme_mi_ctrl_t ctrl, struct nvme_telemetry_log *log)¶: Create host telemetry log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
struct nvme_telemetry_log *log: Userspace address of the log payload

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_telemetry_host(nvme_mi_ctrl_t ctrl, __u64 offset, __u32 len, void *log)¶: Get Telemetry Host-Initiated log page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u64 offset: Offset into the telemetry data
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Description

Retrieves the Telemetry Host-Initiated log page at the requested offset using the previously existing capture.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_telemetry_ctrl(nvme_mi_ctrl_t ctrl, bool rae, __u64 offset, __u32 len, void *log)¶: Get Telemetry Controller-Initiated log page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u64 offset: Offset into the telemetry data
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Description

Retrieves the Telemetry Controller-Initiated log page at the requested offset using the previously existing capture.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_endurance_group(nvme_mi_ctrl_t ctrl, __u16 endgid, struct nvme_endurance_group_log *log)¶: Get Endurance Group log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u16 endgid: Starting group identifier to return in the list
struct nvme_endurance_group_log *log: User address to store the endurance log

Description

This log page indicates if an Endurance Group Event has occurred for a particular Endurance Group. If an Endurance Group Event has occurred, the details of the particular event are included in the Endurance Group Information log page for that Endurance Group. An asynchronous event is generated when an entry for an Endurance Group is newly added to this log page.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_predictable_lat_nvmset(nvme_mi_ctrl_t ctrl, __u16 nvmsetid, struct nvme_nvmset_predictable_lat_log *log)¶: Predictable Latency Per NVM Set

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u16 nvmsetid: NVM set id
struct nvme_nvmset_predictable_lat_log *log: User address to store the predictable latency log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_predictable_lat_event(nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Predictable Latency Event Aggregate Log Page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 offset: Offset into the predictable latency event
__u32 len: Length of provided user buffer to hold the log data in bytes
void *log: User address for log page data

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_ana(nvme_mi_ctrl_t ctrl, enum nvme_log_ana_lsp lsp, bool rae, __u64 offset, __u32 len, void *log)¶: Retrieve Asymmetric Namespace Access log page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
enum nvme_log_ana_lsp lsp: Log specific, see enum nvme_get_log_ana_lsp
bool rae: Retain asynchronous events
__u64 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the ana log

Description

This log consists of a header describing the log and descriptors containing the asymmetric namespace access information for ANA Groups that contain namespaces that are attached to the controller processing the command.

See struct nvme_ana_log for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_ana_groups(nvme_mi_ctrl_t ctrl, bool rae, __u32 len, struct nvme_ana_group_desc *log)¶: Retrieve Asymmetric Namespace Access groups only log page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ana_group_desc *log: User address to store the ana group log

Description

See struct nvme_ana_group_desc for the definition of the returned structure.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_ana_log_atomic(nvme_mi_ctrl_t ctrl, bool rgo, bool rae, unsigned int retries, struct nvme_ana_log *log, __u32 *len)¶: Retrieve Asymmetric Namespace Access log page atomically

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rgo: Whether to retrieve ANA groups only (no NSIDs)
bool rae: Whether to retain asynchronous events
unsigned int retries: The maximum number of times to retry on log page changes
struct nvme_ana_log *log: Pointer to a buffer to receive the ANA log page
__u32 *len: Input: the length of the log page buffer. Output: the actual length of the ANA log page.

Description

See struct nvme_ana_log for the definition of the returned structure.

Return

If successful, returns 0 and sets *len to the actual log page length. If unsuccessful, returns the nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise. Sets errno = EINVAL if retries == 0. Sets errno = EAGAIN if unable to read the log page atomically because chgcnt changed during each of the retries attempts. Sets errno = ENOSPC if the full log page does not fit in the provided buffer.

int nvme_mi_admin_get_log_lba_status(nvme_mi_ctrl_t ctrl, bool rae, __u64 offset, __u32 len, void *log)¶: Retrieve LBA Status

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u64 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_endurance_grp_evt(nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Rotational Media Information

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 offset: Offset to the start of the log page
__u32 len: The allocated length of the log page
void *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_fid_supported_effects(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_fid_supported_effects_log *log)¶: Retrieve Feature Identifiers Supported and Effects

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_fid_supported_effects_log *log: FID Supported and Effects data structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_mi_cmd_supported_effects(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_mi_cmd_supported_effects_log *log)¶: displays the MI Commands Supported by the controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_mi_cmd_supported_effects_log *log: MI Command Supported and Effects data structure

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_boot_partition(nvme_mi_ctrl_t ctrl, bool rae, __u8 lsp, __u32 len, struct nvme_boot_partition *part)¶: Retrieve Boot Partition

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u8 lsp: The log specified field of LID
__u32 len: The allocated size, minimum struct nvme_boot_partition
struct nvme_boot_partition *part: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_rotational_media_info(nvme_mi_ctrl_t ctrl, __u16 endgid, __u32 len, struct nvme_rotational_media_info_log *log)¶: Retrieve Rotational Media Information Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u16 endgid: Endurance Group Identifier
__u32 len: The allocated length of the log page
struct nvme_rotational_media_info_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_dispersed_ns_participating_nss(nvme_mi_ctrl_t ctrl, __u32 nsid, __u32 len, struct nvme_dispersed_ns_participating_nss_log *log)¶: Retrieve Dispersed Namespace Participating NVM Subsystems Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u32 nsid: Namespace Identifier
__u32 len: The allocated length of the log page
struct nvme_dispersed_ns_participating_nss_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_mgmt_addr_list(nvme_mi_ctrl_t ctrl, __u32 len, struct nvme_mgmt_addr_list_log *log)¶: Retrieve Management Address List Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u32 len: The allocated length of the log page
struct nvme_mgmt_addr_list_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_phy_rx_eom(nvme_mi_ctrl_t ctrl, __u8 lsp, __u16 controller, __u32 len, struct nvme_phy_rx_eom_log *log)¶: Retrieve Physical Interface Receiver Eye Opening Measurement Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u8 lsp: Log specific, controls action and measurement quality
__u16 controller: Target controller ID
__u32 len: The allocated size, minimum struct nvme_phy_rx_eom_log
struct nvme_phy_rx_eom_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_reachability_groups(nvme_mi_ctrl_t ctrl, bool rgo, bool rae, __u32 len, struct nvme_reachability_groups_log *log)¶: Retrieve Reachability Groups Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rgo: Return groups only
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_reachability_groups_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_reachability_associations(nvme_mi_ctrl_t ctrl, bool rao, bool rae, __u32 len, struct nvme_reachability_associations_log *log)¶: Retrieve Reachability Associations Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rao: Return associations only
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_reachability_associations_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_changed_alloc_ns_list(nvme_mi_ctrl_t ctrl, bool rae, __u32 len, struct nvme_ns_list *log)¶: Retrieve Changed Allocated Namespace List Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ns_list *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_discovery(nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log)¶: Retrieve Discovery log page

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 offset: Offset of this log to retrieve
__u32 len: The allocated size for this portion of the log
void *log: User address to store the discovery log

Description

Supported only by fabrics discovery controllers, returning discovery records.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_host_discover(nvme_mi_ctrl_t ctrl, bool allhoste, bool rae, __u32 len, struct nvme_host_discover_log *log)¶: Retrieve Host Discovery Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool allhoste: All host entries
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_host_discover_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_ave_discover(nvme_mi_ctrl_t ctrl, bool rae, __u32 len, struct nvme_ave_discover_log *log)¶: Retrieve AVE Discovery Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_ave_discover_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_pull_model_ddc_req(nvme_mi_ctrl_t ctrl, bool rae, __u32 len, struct nvme_pull_model_ddc_req_log *log)¶: Retrieve Pull Model DDC Request Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
__u32 len: The allocated length of the log page
struct nvme_pull_model_ddc_req_log *log: User address to store the log page

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise

int nvme_mi_admin_get_log_media_unit_stat(nvme_mi_ctrl_t ctrl, __u16 domid, struct nvme_media_unit_stat_log *mus)¶: Retrieve Media Unit Status

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u16 domid: Domain Identifier selection, if supported
struct nvme_media_unit_stat_log *mus: User address to store the Media Unit statistics log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_support_cap_config_list(nvme_mi_ctrl_t ctrl, __u16 domid, struct nvme_supported_cap_config_list_log *cap)¶: Retrieve Supported Capacity Configuration List

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u16 domid: Domain Identifier selection, if supported
struct nvme_supported_cap_config_list_log *cap: User address to store supported capabilities config list

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_reservation(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_resv_notification_log *log)¶: Retrieve Reservation Notification

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_resv_notification_log *log: User address to store the reservation log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_sanitize(nvme_mi_ctrl_t ctrl, bool rae, struct nvme_sanitize_log_page *log)¶: Retrieve Sanitize Status

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
bool rae: Retain asynchronous events
struct nvme_sanitize_log_page *log: User address to store the sanitize log

Description

The Sanitize Status log page reports sanitize operation time estimates and information about the most recent sanitize operation.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_zns_changed_zones(nvme_mi_ctrl_t ctrl, __u32 nsid, bool rae, struct nvme_zns_changed_zone_log *log)¶: Retrieve list of zones that have changed

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u32 nsid: Namespace ID
bool rae: Retain asynchronous events
struct nvme_zns_changed_zone_log *log: User address to store the changed zone log

Description

The list of zones that have changed state due to an exceptional event.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_persistent_event(nvme_mi_ctrl_t ctrl, enum nvme_pevent_log_action action, __u32 size, void *pevent_log)¶: Retrieve Persistent Event Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
enum nvme_pevent_log_action action: Action the controller should take during processing this command
__u32 size: Size of pevent_log
void *pevent_log: User address to store the persistent event log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_log_lockdown(nvme_mi_ctrl_t ctrl, __u8 cnscp, struct nvme_lockdown_log *lockdown_log)¶: Retrieve lockdown Log

Parameters

nvme_mi_ctrl_t ctrl: Controller to query
__u8 cnscp: Contents and Scope of Command and Feature Identifier Lists
struct nvme_lockdown_log *lockdown_log: Buffer to store the lockdown log

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_security_send(nvme_mi_ctrl_t ctrl, struct nvme_security_send_args *args)¶: Perform a Security Send command on a controller.

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_security_send_args *args: Security Send command arguments

Description

Performs a Security Send Admin command as specified by args. Response data is stored in args->data, which should be a buffer of args->data_len bytes. Resulting data length is stored in args->data_len on successful command completion.

Security Send data length should not be greater than 4096 bytes to comply with specification limits.

See: struct nvme_get_log_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_security_recv(nvme_mi_ctrl_t ctrl, struct nvme_security_receive_args *args)¶: Perform a Security Receive command on a controller.

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_security_receive_args *args: Security Receive command arguments

Description

Performs a Security Receive Admin command as specified by args. Response data is stored in args->data, which should be a buffer of args->data_len bytes. Resulting data length is stored in args->data_len on successful command completion.

Security Receive data length should not be greater than 4096 bytes to comply with specification limits.

See: struct nvme_get_log_args

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_features(nvme_mi_ctrl_t ctrl, struct nvme_get_features_args *args)¶: Perform a Get Feature command on a controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_get_features_args *args: Get Features command arguments

Description

Performs a Get Features Admin command as specified by args. Returned feature data will be stored in args->result and args->data, depending on the specification of the feature itself; most features do not return additional data. See section 5.27.1 of the NVMe spec (v2.0b) for feature-specific information.

On success, args->data_len will be updated with the actual data length received.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_features_arbitration(nvme_mi_ctrl_t ctrl, enum nvme_get_features_sel sel, __u32 *result)¶: Get arbitration feature

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The feature data is returned in this argument

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_features_power_mgmt(nvme_mi_ctrl_t ctrl, enum nvme_get_features_sel sel, __u32 *result)¶: Get power management feature

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
enum nvme_get_features_sel sel: Select which type of attribute to return, see enum nvme_get_features_sel
__u32 *result: The feature data is returned in this argument

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_features_data(nvme_mi_ctrl_t ctrl, enum nvme_features_id fid, __u32 nsid, __u32 data_len, void *data, __u32 *result)¶: Helper function for :c:type:`nvme_mi_admin_get_features`()

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
enum nvme_features_id fid: Feature identifier
__u32 nsid: Namespace ID, if applicable for fid
__u32 data_len: Length of feature data, if applicable for fid, in bytes
void *data: User address of feature data, if applicable
__u32 *result: The command completion result from CQE dword0

Description

Helper for optionally features that optionally return data, using the SEL_CURRENT selector value.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_get_features_simple(nvme_mi_ctrl_t ctrl, enum nvme_features_id fid, __u32 nsid, __u32 *result)¶: Get a simple feature value with no data

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
enum nvme_features_id fid: Feature identifier
__u32 nsid: Namespace id, if required by fid
__u32 *result: output feature data

int nvme_mi_admin_set_features(nvme_mi_ctrl_t ctrl, struct nvme_set_features_args *args)¶: Perform a Set Features command on a controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_set_features_args *args: Set Features command arguments

Description

Performs a Set Features Admin command as specified by args. Result data will be stored in args->result. on the specification of the feature itself; most features do not return additional data. See section 5.27.1 of the NVMe spec (v2.0b) for feature-specific information.

On success, args->data_len will be updated with the actual data length received.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_set_features_power_mgmt(nvme_mi_ctrl_t ctrl, __u8 ps, __u8 wh, bool save, __u32 *result)¶: Set power management feature

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
__u8 ps: Power State
__u8 wh: Workload Hint
bool save: Save value across power states
__u32 *result: The feature data is returned in this argument

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_ns_mgmt(nvme_mi_ctrl_t ctrl, struct nvme_ns_mgmt_args *args)¶: Issue a Namespace Management command

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_ns_mgmt_args *args: Namespace management command arguments

Description

Issues a Namespace Management command to ctrl, with arguments specified from args.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

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

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_id_ns *ns: New namespace parameters
__u8 csi: Command Set Identifier for new NS
__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 new namespace specified by ns, using command set csi. On success, the new namespace ID will be written to nsid.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_ns_mgmt_delete(nvme_mi_ctrl_t ctrl, __u32 nsid)¶: Helper for Namespace Management Delete command

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
__u32 nsid: Namespace ID to delete

Description

Issues a Namespace Management (Delete) command to ctrl, to delete the namespace with id nsid.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_ns_attach(nvme_mi_ctrl_t ctrl, struct nvme_ns_attach_args *args)¶: Attach or detach namespace to controller(s)

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_ns_attach_args *args: Namespace Attach command arguments

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_ns_attach_ctrls(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ctrl_list *ctrlist)¶: Attach namespace to controllers

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
__u32 nsid: Namespace ID to attach
struct nvme_ctrl_list *ctrlist: Controller list to modify attachment state of nsid

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_ns_detach_ctrls(nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ctrl_list *ctrlist)¶: Detach namespace from controllers

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
__u32 nsid: Namespace ID to detach
struct nvme_ctrl_list *ctrlist: Controller list to modify attachment state of nsid

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_fw_download(nvme_mi_ctrl_t ctrl, struct nvme_fw_download_args *args)¶: Download part or all of a firmware image to the controller

Parameters

nvme_mi_ctrl_t ctrl: Controller to send firmware data to
struct nvme_fw_download_args *args: struct nvme_fw_download_args argument structure

Description

The Firmware Image Download command downloads all or a portion of an image for a future update to the controller. The Firmware Image Download command downloads a new image (in whole or in part) to the controller.

The image may be constructed of multiple pieces that are individually downloaded with separate Firmware Image Download commands. Each Firmware Image Download command includes a Dword Offset and Number of Dwords that specify a dword range.

The new firmware image is not activated as part of the Firmware Image Download command. Use the nvme_mi_admin_fw_commit() to activate a newly downloaded image.

Return

0 on success, non-zero on failure

int nvme_mi_admin_fw_commit(nvme_mi_ctrl_t ctrl, struct nvme_fw_commit_args *args)¶: Commit firmware using the specified action

Parameters

nvme_mi_ctrl_t ctrl: Controller to send firmware data to
struct nvme_fw_commit_args *args: struct nvme_fw_download_args argument structure

Description

The Firmware Commit command modifies the firmware image or Boot Partitions.

Return

0 on success, non-zero on failure

int nvme_mi_admin_format_nvm(nvme_mi_ctrl_t ctrl, struct nvme_format_nvm_args *args)¶: Format NVMe namespace

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_format_nvm_args *args: Format NVM command arguments

Description

Perform a low-level format to set the LBA data & metadata size. May destroy data & metadata on the specified namespaces

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

int nvme_mi_admin_sanitize_nvm(nvme_mi_ctrl_t ctrl, struct nvme_sanitize_nvm_args *args)¶: Start a subsystem Sanitize operation

Parameters

nvme_mi_ctrl_t ctrl: Controller to send command to
struct nvme_sanitize_nvm_args *args: Sanitize command arguments

Description

A sanitize operation alters all user data in the NVM subsystem such that recovery of any previous user data from any cache, the non-volatile media, or any Controller Memory Buffer is not possible.

The Sanitize command starts a sanitize operation or to recover from a previously failed sanitize operation. The sanitize operation types that may be supported are Block Erase, Crypto Erase, and Overwrite. All sanitize operations are processed in the background, i.e., completion of the sanitize command does not indicate completion of the sanitize operation.

Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

enum nvme_mi_aem_handler_next_action¶: Next action for the AEM state machine handler

Constants

NVME_MI_AEM_HNA_ACK: Send an ack for the AEM
NVME_MI_AEM_HNA_NONE: No further action

Description

Used as return value for the AE callback generated when calling nvme_mi_aem_process

struct nvme_mi_event¶: AE event information structure

Definition

struct nvme_mi_event {
  uint8_t aeoi;
  uint8_t aessi;
  uint32_t aeocidi;
  void *spec_info;
  size_t spec_info_len;
  void *vend_spec_info;
  size_t vend_spec_info_len;
};

Members

aeoi: Event identifier
aessi: Event occurrence scope info
aeocidi: Event occurrence scope ID info
spec_info: Specific info buffer
spec_info_len: Length of specific info buffer
vend_spec_info: Vendor specific info buffer
vend_spec_info_len: Length of vendor specific info buffer

Description

Application callbacks for nvme_mi_aem_process will be able to call nvme_mi_aem_get_next_event which will return a pointer to such an identifier for the next event the application should parse

struct nvme_mi_event *nvme_mi_aem_get_next_event(nvme_mi_ep_t ep)¶: Get details for the next event to parse

Parameters

nvme_mi_ep_t ep: The endpoint with the event

Description

When inside a aem_handler, call this and a returned struct pointer will provide details of event information. Will return NULL when end of parsing is occurred. spec_info and vend_spec_info must be copied to persist as they will not be valid after the handler_next_action has returned.

Return

Pointer no next nvme_mi_event or NULL if this is the last one

struct nvme_mi_aem_config¶: Provided for nvme_mi_aem_enable

Definition

struct nvme_mi_aem_config {
  enum nvme_mi_aem_handler_next_action (*aem_handler)(nvme_mi_ep_t ep,size_t num_events, void *userdata);
  struct nvme_mi_aem_enabled_map enabled_map;
  bool envfa;
  bool empfa;
  bool encfa;
  __u8 aemd;
  __u8 aerd;
};

Members

aem_handler: Callback function for application processing of events
enabled_map: Map indicating which AE should be enabled on the endpoint
envfa: Enable SR-IOV virtual functions AE
empfa: Enable SR-IOV physical functions AE
encfa: Enable PCIe functions AE
aemd: AEM Delay (time in seconds from when event happens to AEM being batched and sent)
aerd: AEM Retry Delay (time in 100s of ms between AEM retries from the endpoint)

Description

Application callbacks for nvme_mi_aem_process will be able to call nvme_mi_aem_get_next_event which will return a pointer to such an identifier for the next event the application should parse

int nvme_mi_aem_get_fd(nvme_mi_ep_t ep)¶: Returns the pollable fd for AEM data available

Parameters

nvme_mi_ep_t ep: The endpoint being monitored for asynchronous data

Description

This populated structure can be polled from the application to understand if a call to nvme_mi_aem_process() is required (when a poll returns > 0).

Return

The fd value or -1 if error

int nvme_mi_aem_enable(nvme_mi_ep_t ep, struct nvme_mi_aem_config *config, void *userdata)¶: Enable AE on the provided endpoint

Parameters

nvme_mi_ep_t ep: Endpoint to enable AEs
struct nvme_mi_aem_config *config: AE configuraiton including which events are enabled and the callback function
void *userdata: Application provided context pointer for callback function

Description

This function is called to enable AE on the endpoint. Endpoint will provide initial state (if any) of enabled AEs and application can parse those via the aem_handler fn pointer in callbacks. Thes can be obtained in the callback by calling nvme_mi_aem_get_next_event().

Application should poll the fd that can be obtained from nvme_mi_aem_get_fd and then call nvme_mi_aem_process() when poll() indicates data available.

A call to nvme_mi_aem_process() will grab AEM data and call the aem_handler fn pointer. At this point the application can call nvme_mi_aem_get_next_event() to get information for each triggered event.

Return

0 is a success, nonzero is an error and errno may be read for further details

int nvme_mi_aem_get_enabled(nvme_mi_ep_t ep, struct nvme_mi_aem_enabled_map *enabled)¶: Return information on which AEs are enabled

Parameters

nvme_mi_ep_t ep: Endpoint to check enabled status
struct nvme_mi_aem_enabled_map *enabled: nvme_mi_aem_enabled_map indexed by AE event ID of enabled state

Return

0 is a success, nonzero is an error and errno may be read for further details

int nvme_mi_aem_disable(nvme_mi_ep_t ep)¶: Disable AE on the provided endpoint

Parameters

nvme_mi_ep_t ep: Endpoint to disable AEs

Return

0 is a success, nonzero is an error and errno may be read for further details

int nvme_mi_aem_process(nvme_mi_ep_t ep, void *userdata)¶: Process AEM on the provided endpoint

Parameters

nvme_mi_ep_t ep: Endpoint to process
void *userdata: Application provided context pointer for callback function

Description

Call this if poll() indicates data is available on the fd provided by nvme_mi_aem_get_fd()

This will call the fn pointer, aem_handler, provided with nvme_mi_aem_config and the application can call nvme_mi_aem_get_next_event() from within this callback to get aem event data. The callback function should return NVME_MI_AEM_HNA_ACK for normal operation.

Return

0 is a success, nonzero is an error and errno may be read for further details

tree.h

libnvme tree object interface

nvme_root_t nvme_create_root(FILE *fp, int log_level)¶: Initialize root object

Parameters

FILE *fp: File descriptor for logging messages
int log_level: Logging level to use

Return

Initialized nvme_root_t object

void nvme_root_set_application(nvme_root_t r, const char *a)¶: Specify managing application

Parameters

nvme_root_t r: nvme_root_t object
const char *a: Application string

Description

Sets the managing application string for r.

const char *nvme_root_get_application(nvme_root_t r)¶: Get managing application

Parameters

nvme_root_t r: nvme_root_t object

Description

Returns the managing application string for r or NULL if not set.

void nvme_root_skip_namespaces(nvme_root_t r)¶: Skip namespace scanning

Parameters

nvme_root_t r: nvme_root_t object

Description

Sets a flag to skip namespaces during scanning.

void nvme_root_release_fds(nvme_root_t r)¶: Close all opened file descriptors in the tree

Parameters

nvme_root_t r: nvme_root_t object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds in the tree.

void nvme_free_tree(nvme_root_t r)¶: Free root object

Parameters

nvme_root_t r: nvme_root_t object

Description

Free an nvme_root_t object and all attached objects

nvme_host_t nvme_first_host(nvme_root_t r)¶: Start host iterator

Parameters

nvme_root_t r: nvme_root_t object

Return

First nvme_host_t object in an iterator

nvme_host_t nvme_next_host(nvme_root_t r, nvme_host_t h)¶: Next host iterator

Parameters

nvme_root_t r: nvme_root_t object
nvme_host_t h: Previous nvme_host_t iterator

Return

Next nvme_host_t object in an iterator

nvme_root_t nvme_host_get_root(nvme_host_t h)¶: Returns nvme_root_t object

Parameters

nvme_host_t h: nvme_host_t object

Return

nvme_root_t object from h

nvme_host_t nvme_lookup_host(nvme_root_t r, const char *hostnqn, const char *hostid)¶: Lookup nvme_host_t object

Parameters

nvme_root_t r: nvme_root_t object
const char *hostnqn: Host NQN
const char *hostid: Host ID

Description

Lookup a nvme_host_t object based on hostnqn and hostid or create one if not found.

Return

nvme_host_t object

const char *nvme_host_get_dhchap_key(nvme_host_t h)¶: Return host key

Parameters

nvme_host_t h: Host for which the key should be returned

Return

DH-HMAC-CHAP host key or NULL if not set

void nvme_host_set_dhchap_key(nvme_host_t h, const char *key)¶: set host key

Parameters

nvme_host_t h: Host for which the key should be set
const char *key: DH-HMAC-CHAP Key to set or NULL to clear existing key

void nvme_host_set_pdc_enabled(nvme_host_t h, bool enabled)¶: Set Persistent Discovery Controller flag

Parameters

nvme_host_t h: Host for which the falg should be set
bool enabled: The bool to set the enabled flag

Description

When nvme_host_set_pdc_enabled() is not used to set the PDC flag, nvme_host_is_pdc_enabled() will return the default value which was passed into the function and not the undefined flag value.

bool nvme_host_is_pdc_enabled(nvme_host_t h, bool fallback)¶: Is Persistenct Discovery Controller enabled

Parameters

nvme_host_t h: Host which to check if PDC is enabled
bool fallback: The fallback default value of the flag when nvme_host_set_pdc_enabled has not be used to set the flag.

Return

true if PDC is enabled for h, else false

nvme_host_t nvme_default_host(nvme_root_t r)¶: Initializes the default host

Parameters

nvme_root_t r: nvme_root_t object

Description

Initializes the default host object based on the hostnqn/hostid values returned by nvme_host_get_ids() and attaches it to r.

Return

nvme_host_t object

int nvme_host_get_ids(nvme_root_t r, char *hostnqn_arg, char *hostid_arg, char **hostnqn, char **hostid)¶: Retrieve host ids from various sources

Parameters

nvme_root_t r: nvme_root_t object
char *hostnqn_arg: Input hostnqn (command line) argument
char *hostid_arg: Input hostid (command line) argument
char **hostnqn: Output hostnqn
char **hostid: Output hostid

Description

nvme_host_get_ids figures out which hostnqn/hostid is to be used. There are several sources where this information can be retrieved.

The order is:

Start with informartion from DMI or device-tree

Override hostnqn and hostid from /etc/nvme files

Override hostnqn or hostid with values from JSON configuration file. The first host entry in the file is considered the default host.

Override hostnqn or hostid with values from the command line (hostnqn_arg, hostid_arg).

If the IDs are still NULL after the lookup algorithm, the function will generate random IDs.

The function also verifies that hostnqn and hostid matches. The Linux NVMe implementation expects a 1:1 matching between the IDs.

Return

0 on success (hostnqn and hostid contain valid strings: which the caller needs to free), -1 otherwise and errno is set.

nvme_subsystem_t nvme_first_subsystem(nvme_host_t h)¶: Start subsystem iterator

Parameters

nvme_host_t h: nvme_host_t object

Return

first nvme_subsystem_t object in an iterator

nvme_subsystem_t nvme_next_subsystem(nvme_host_t h, nvme_subsystem_t s)¶: Next subsystem iterator

Parameters

nvme_host_t h: nvme_host_t object
nvme_subsystem_t s: Previous nvme_subsystem_t iterator

Return

next nvme_subsystem_t object in an iterator

nvme_subsystem_t nvme_lookup_subsystem(struct nvme_host *h, const char *name, const char *subsysnqn)¶: Lookup nvme_subsystem_t object

Parameters

struct nvme_host *h: nvme_host_t object
const char *name: Name of the subsystem (may be NULL)
const char *subsysnqn: Subsystem NQN

Description

Lookup a nvme_subsystem_t object in h base on name (if present) and subsysnqn or create one if not found.

Return

nvme_subsystem_t object

void nvme_free_subsystem(struct nvme_subsystem *s)¶: Free a subsystem

Parameters

struct nvme_subsystem *s: subsystem

Description

Frees s and all related objects.

nvme_host_t nvme_subsystem_get_host(nvme_subsystem_t s)¶: Returns nvme_host_t object

Parameters

nvme_subsystem_t s: subsystem

Return

nvme_host_t object from s

nvme_ns_t nvme_ctrl_first_ns(nvme_ctrl_t c)¶: Start namespace iterator

Parameters

nvme_ctrl_t c: Controller instance

Return

First nvme_ns_t object of an c iterator

nvme_ns_t nvme_ctrl_next_ns(nvme_ctrl_t c, nvme_ns_t n)¶: Next namespace iterator

Parameters

nvme_ctrl_t c: Controller instance
nvme_ns_t n: Previous nvme_ns_t iterator

Return

Next nvme_ns_t object of an c iterator

nvme_path_t nvme_ctrl_first_path(nvme_ctrl_t c)¶: Start path iterator

Parameters

nvme_ctrl_t c: Controller instance

Return

First nvme_path_t object of an c iterator

nvme_path_t nvme_ctrl_next_path(nvme_ctrl_t c, nvme_path_t p)¶: Next path iterator

Parameters

nvme_ctrl_t c: Controller instance
nvme_path_t p: Previous nvme_path_t object of an c iterator

Return

Next nvme_path_t object of an c iterator

nvme_ctrl_t nvme_subsystem_first_ctrl(nvme_subsystem_t s)¶: First ctrl iterator

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

First controller of an s iterator

nvme_ctrl_t nvme_subsystem_next_ctrl(nvme_subsystem_t s, nvme_ctrl_t c)¶: Next ctrl iterator

Parameters

nvme_subsystem_t s: nvme_subsystem_t object
nvme_ctrl_t c: Previous controller instance of an s iterator

Return

Next controller of an s iterator

nvme_path_t nvme_namespace_first_path(nvme_ns_t ns)¶: Start path iterator

Parameters

nvme_ns_t ns: Namespace instance

Return

First nvme_path_t object of an ns iterator

nvme_path_t nvme_namespace_next_path(nvme_ns_t ns, nvme_path_t p)¶: Next path iterator

Parameters

nvme_ns_t ns: Namespace instance
nvme_path_t p: Previous nvme_path_t object of an ns iterator

Return

Next nvme_path_t object of an ns iterator

nvme_ctrl_t nvme_lookup_ctrl(nvme_subsystem_t s, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid, nvme_ctrl_t p)¶: Lookup nvme_ctrl_t object

Parameters

nvme_subsystem_t s: nvme_subsystem_t object
const char *transport: Transport name
const char *traddr: Transport address
const char *host_traddr: Host transport address
const char *host_iface: Host interface name
const char *trsvcid: Transport service identifier
nvme_ctrl_t p: Previous controller instance

Description

Lookup a controller in s based on transport, traddr, host_traddr, host_iface, and trsvcid. transport must be specified, other fields may be required depending on the transport. A new object is created if none is found. If p is specified the lookup will start at p instead of the first controller.

Return

Controller instance

nvme_ctrl_t nvme_ctrl_find(nvme_subsystem_t s, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)¶: Locate an existing controller

Parameters

nvme_subsystem_t s: nvme_subsystem_t object
const char *transport: Transport name
const char *traddr: Transport address
const char *trsvcid: Transport service identifier
const char *subsysnqn: Subsystem NQN
const char *host_traddr: Host transport address
const char *host_iface: Host interface name

Description

Lookup a controller in s based on transport, traddr, trsvcid, subsysnqn, host_traddr, and host_iface. transport must be specified, other fields may be required depending on the transport. Parameters set to NULL will be ignored.

Unlike nvme_lookup_ctrl(), this function does not create a new object if an existing controller cannot be found.

Return

Controller instance on success, NULL otherwise.

bool nvme_ctrl_config_match(struct nvme_ctrl *c, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)¶: Check if ctrl c matches config params

Parameters

struct nvme_ctrl *c: An existing controller instance
const char *transport: Transport name
const char *traddr: Transport address
const char *trsvcid: Transport service identifier
const char *subsysnqn: Subsystem NQN
const char *host_traddr: Host transport address
const char *host_iface: Host interface name

Description

Check that controller c matches parameters: transport, traddr, trsvcid, subsysnqn, host_traddr, and host_iface. Parameters set to NULL will be ignored.

Return

true if there’s a match, false otherwise.

nvme_ctrl_t nvme_create_ctrl(nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid)¶: Allocate an unconnected NVMe controller

Parameters

nvme_root_t r: NVMe root element
const char *subsysnqn: Subsystem NQN
const char *transport: Transport type
const char *traddr: Transport address
const char *host_traddr: Host transport address
const char *host_iface: Host interface name
const char *trsvcid: Transport service ID

Description

Creates an unconnected controller to be used for nvme_add_ctrl().

Return

Controller instance

nvme_ns_t nvme_subsystem_first_ns(nvme_subsystem_t s)¶: Start namespace iterator

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

First nvme_ns_t object of an s iterator

nvme_ns_t nvme_subsystem_next_ns(nvme_subsystem_t s, nvme_ns_t n)¶: Next namespace iterator

Parameters

nvme_subsystem_t s: nvme_subsystem_t object
nvme_ns_t n: Previous nvme_ns_t iterator

Return

Next nvme_ns_t object of an s iterator

nvme_for_each_host_safe¶

nvme_for_each_host_safe (r, h, _h)

Traverse host list

Parameters

r: nvme_root_t object
h: nvme_host_t object
_h: Temporary nvme_host_t object

nvme_for_each_host¶

nvme_for_each_host (r, h)

Traverse host list

Parameters

r: nvme_root_t object
h: nvme_host_t object

nvme_for_each_subsystem_safe¶

nvme_for_each_subsystem_safe (h, s, _s)

Traverse subsystems

Parameters

h: nvme_host_t object
s: nvme_subsystem_t object
_s: Temporary nvme_subsystem_t object

nvme_for_each_subsystem¶

nvme_for_each_subsystem (h, s)

Traverse subsystems

Parameters

h: nvme_host_t object
s: nvme_subsystem_t object

nvme_subsystem_for_each_ctrl_safe¶

nvme_subsystem_for_each_ctrl_safe (s, c, _c)

Traverse controllers

Parameters

s: nvme_subsystem_t object
c: Controller instance
_c: A nvme_ctrl_t_node to use as temporary storage

nvme_subsystem_for_each_ctrl¶

nvme_subsystem_for_each_ctrl (s, c)

Traverse controllers

Parameters

s: nvme_subsystem_t object
c: Controller instance

nvme_ctrl_for_each_ns_safe¶

nvme_ctrl_for_each_ns_safe (c, n, _n)

Traverse namespaces

Parameters

c: Controller instance
n: nvme_ns_t object
_n: A nvme_ns_t_node to use as temporary storage

nvme_ctrl_for_each_ns¶

nvme_ctrl_for_each_ns (c, n)

Traverse namespaces

Parameters

c: Controller instance
n: nvme_ns_t object

nvme_ctrl_for_each_path_safe¶

nvme_ctrl_for_each_path_safe (c, p, _p)

Traverse paths

Parameters

c: Controller instance
p: nvme_path_t object
_p: A nvme_path_t_node to use as temporary storage

nvme_ctrl_for_each_path¶

nvme_ctrl_for_each_path (c, p)

Traverse paths

Parameters

c: Controller instance
p: nvme_path_t object

nvme_subsystem_for_each_ns_safe¶

nvme_subsystem_for_each_ns_safe (s, n, _n)

Traverse namespaces

Parameters

s: nvme_subsystem_t object
n: nvme_ns_t object
_n: A nvme_ns_t_node to use as temporary storage

nvme_subsystem_for_each_ns¶

nvme_subsystem_for_each_ns (s, n)

Traverse namespaces

Parameters

s: nvme_subsystem_t object
n: nvme_ns_t object

nvme_namespace_for_each_path_safe¶

nvme_namespace_for_each_path_safe (n, p, _p)

Traverse paths

Parameters

n: Namespace instance
p: nvme_path_t object
_p: A nvme_path_t_node to use as temporary storage

nvme_namespace_for_each_path¶

nvme_namespace_for_each_path (n, p)

Traverse paths

Parameters

n: Namespace instance
p: nvme_path_t object

int nvme_ns_get_fd(nvme_ns_t n)¶: Get associated file descriptor

Parameters

nvme_ns_t n: Namespace instance

Description

libnvme will open() the file (if not already opened) and keep an internal copy of the file descriptor. Following calls to this API retrieve the internal cached copy of the file descriptor. The file will remain opened and the fd will remain cached until the ns object is deleted or nvme_ns_release_fd() is called.

Return

File descriptor associated with n or -1

void nvme_ns_release_fd(nvme_ns_t n)¶: Close fd and clear fd from ns object

Parameters

nvme_ns_t n: Namespace instance

int nvme_ns_get_nsid(nvme_ns_t n)¶: NSID of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

NSID of n

int nvme_ns_get_lba_size(nvme_ns_t n)¶: LBA size of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

LBA size of n

int nvme_ns_get_meta_size(nvme_ns_t n)¶: Metadata size of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

Metadata size of n

uint64_t nvme_ns_get_lba_count(nvme_ns_t n)¶: LBA count of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

LBA count of n

uint64_t nvme_ns_get_lba_util(nvme_ns_t n)¶: LBA utilization of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

LBA utilization of n

enum nvme_csi nvme_ns_get_csi(nvme_ns_t n)¶: Command set identifier of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

The namespace’s command set identifier in use

const uint8_t *nvme_ns_get_eui64(nvme_ns_t n)¶: 64-bit eui of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

A pointer to the 64-bit eui

const uint8_t *nvme_ns_get_nguid(nvme_ns_t n)¶: 128-bit nguid of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

A pointer to the 128-bit nguid

void nvme_ns_get_uuid(nvme_ns_t n, unsigned char out[NVME_UUID_LEN])¶: UUID of a namespace

Parameters

nvme_ns_t n: Namespace instance
unsigned char out[NVME_UUID_LEN]: buffer for the UUID

Description

Copies the namespace’s uuid into out

const char *nvme_ns_get_sysfs_dir(nvme_ns_t n)¶: sysfs directory of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

sysfs directory name of n

const char *nvme_ns_get_name(nvme_ns_t n)¶: sysfs name of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

sysfs name of n

const char *nvme_ns_get_generic_name(nvme_ns_t n)¶: Returns name of generic namespace chardev.

Parameters

nvme_ns_t n: Namespace instance

Return

Name of generic namespace chardev

const char *nvme_ns_get_firmware(nvme_ns_t n)¶: Firmware string of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

Firmware string of n

const char *nvme_ns_get_serial(nvme_ns_t n)¶: Serial number of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

Serial number string of n

const char *nvme_ns_get_model(nvme_ns_t n)¶: Model of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

Model string of n

nvme_subsystem_t nvme_ns_get_subsystem(nvme_ns_t n)¶: nvme_subsystem_t of a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

nvme_subsystem_t object of n

nvme_ctrl_t nvme_ns_get_ctrl(nvme_ns_t n)¶: nvme_ctrl_t of a namespace

Parameters

nvme_ns_t n: Namespace instance

Description

nvme_ctrl_t object may be NULL for a multipathed namespace

Return

nvme_ctrl_t object of n if present

void nvme_free_ns(struct nvme_ns *n)¶: Free a namespace object

Parameters

struct nvme_ns *n: Namespace instance

int nvme_ns_read(nvme_ns_t n, void *buf, off_t offset, size_t count)¶: Read from a namespace

Parameters

nvme_ns_t n: Namespace instance
void *buf: Buffer into which the data will be transferred
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors read or -1 on error.

int nvme_ns_write(nvme_ns_t n, void *buf, off_t offset, size_t count)¶: Write to a namespace

Parameters

nvme_ns_t n: Namespace instance
void *buf: Buffer with data to be written
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors written or -1 on error

int nvme_ns_verify(nvme_ns_t n, off_t offset, size_t count)¶: Verify data on a namespace

Parameters

nvme_ns_t n: Namespace instance
off_t offset: LBA offset of n
size_t count: Number of sectors to be verified

Return

Number of sectors verified

int nvme_ns_compare(nvme_ns_t n, void *buf, off_t offset, size_t count)¶: Compare data on a namespace

Parameters

nvme_ns_t n: Namespace instance
void *buf: Buffer with data to be compared
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors compared

int nvme_ns_write_zeros(nvme_ns_t n, off_t offset, size_t count)¶: Write zeros to a namespace

Parameters

nvme_ns_t n: Namespace instance
off_t offset: LBA offset in n
size_t count: Number of sectors to be written

Return

Number of sectors written

int nvme_ns_write_uncorrectable(nvme_ns_t n, off_t offset, size_t count)¶: Issus a ‘write uncorrectable’ command

Parameters

nvme_ns_t n: Namespace instance
off_t offset: LBA offset in n
size_t count: Number of sectors to be written

Return

Number of sectors written

int nvme_ns_flush(nvme_ns_t n)¶: Flush data to a namespace

Parameters

nvme_ns_t n: Namespace instance

Return

0 on success, -1 on error.

int nvme_ns_identify(nvme_ns_t n, struct nvme_id_ns *ns)¶: Issue an ‘identify namespace’ command

Parameters

nvme_ns_t n: Namespace instance
struct nvme_id_ns *ns: nvme_id_ns buffer

Description

Writes the data returned by the ‘identify namespace’ command into ns.

Return

0 on success, -1 on error.

int nvme_ns_identify_descs(nvme_ns_t n, struct nvme_ns_id_desc *descs)¶: Issue an ‘identify descriptors’ command

Parameters

nvme_ns_t n: Namespace instance
struct nvme_ns_id_desc *descs: List of identify descriptors

Description

Writes the data returned by the ‘identify descriptors’ command into descs.

Return

0 on success, -1 on error.

const char *nvme_path_get_name(nvme_path_t p)¶: sysfs name of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

sysfs name of p

const char *nvme_path_get_sysfs_dir(nvme_path_t p)¶: sysfs directory of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

sysfs directory of p

const char *nvme_path_get_ana_state(nvme_path_t p)¶: ANA state of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

ANA (Asynchronous Namespace Access) state of p

const char *nvme_path_get_numa_nodes(nvme_path_t p)¶: NUMA nodes of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

NUMA nodes associated to p

int nvme_path_get_queue_depth(nvme_path_t p)¶: Queue depth of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

Queue depth of p

nvme_ctrl_t nvme_path_get_ctrl(nvme_path_t p)¶: Parent controller of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

Parent controller if present

nvme_ns_t nvme_path_get_ns(nvme_path_t p)¶: Parent namespace of an nvme_path_t object

Parameters

nvme_path_t p: nvme_path_t object

Return

Parent namespace if present

int nvme_ctrl_get_fd(nvme_ctrl_t c)¶: Get associated file descriptor

Parameters

nvme_ctrl_t c: Controller instance

Description

libnvme will open() the file (if not already opened) and keep an internal copy of the file descriptor. Following calls to this API retrieve the internal cached copy of the file descriptor. The file will remain opened and the fd will remain cached until the controller object is deleted or nvme_ctrl_release_fd() is called.

Return

File descriptor associated with c or -1

void nvme_ctrl_release_fd(nvme_ctrl_t c)¶: Close fd and clear fd from controller object

Parameters

nvme_ctrl_t c: Controller instance

const char *nvme_ctrl_get_name(nvme_ctrl_t c)¶: sysfs name of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

sysfs name of c

const char *nvme_ctrl_get_sysfs_dir(nvme_ctrl_t c)¶: sysfs directory of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

sysfs directory name of c

const char *nvme_ctrl_get_address(nvme_ctrl_t c)¶: Address string of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

NVMe-over-Fabrics address string of c or empty string of no address is present.

char *nvme_ctrl_get_src_addr(nvme_ctrl_t c, char *src_addr, size_t src_addr_len)¶: Extract src_addr from the c->address string

Parameters

nvme_ctrl_t c: Controller instance
char *src_addr: Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.
size_t src_addr_len: Length of the buffer src_addr.

Return

Pointer to src_addr on success. NULL on failure to extract the src_addr.

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.

const char *nvme_ctrl_get_firmware(nvme_ctrl_t c)¶: Firmware string of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Firmware string of c

const char *nvme_ctrl_get_model(nvme_ctrl_t c)¶: Model of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Model string of c

const char *nvme_ctrl_get_state(nvme_ctrl_t c)¶: Running state of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

String indicating the running state of c

const char *nvme_ctrl_get_numa_node(nvme_ctrl_t c)¶: NUMA node of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

String indicating the NUMA node

const char *nvme_ctrl_get_queue_count(nvme_ctrl_t c)¶: Queue count of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Queue count of c

const char *nvme_ctrl_get_serial(nvme_ctrl_t c)¶: Serial number of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Serial number string of c

const char *nvme_ctrl_get_sqsize(nvme_ctrl_t c)¶: SQ size of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

SQ size (as string) of c

const char *nvme_ctrl_get_transport(nvme_ctrl_t c)¶: Transport type of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Transport type of c

const char *nvme_ctrl_get_subsysnqn(nvme_ctrl_t c)¶: Subsystem NQN of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Subsystem NQN of c

nvme_subsystem_t nvme_ctrl_get_subsystem(nvme_ctrl_t c)¶: Parent subsystem of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Parent nvme_subsystem_t object

const char *nvme_ctrl_get_traddr(nvme_ctrl_t c)¶: Transport address of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Transport address of c

const char *nvme_ctrl_get_trsvcid(nvme_ctrl_t c)¶: Transport service identifier of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Transport service identifier of c (if present)

const char *nvme_ctrl_get_host_traddr(nvme_ctrl_t c)¶: Host transport address of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Host transport address of c (if present)

const char *nvme_ctrl_get_host_iface(nvme_ctrl_t c)¶: Host interface name of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Host interface name of c (if present)

const char *nvme_ctrl_get_dhchap_host_key(nvme_ctrl_t c)¶: Return host key

Parameters

nvme_ctrl_t c: Controller to be checked

Return

DH-HMAC-CHAP host key or NULL if not set

const char *nvme_ctrl_get_cntlid(nvme_ctrl_t c)¶: Controller id

Parameters

nvme_ctrl_t c: Controller to be checked

Return

Controller id of c

void nvme_ctrl_set_dhchap_host_key(nvme_ctrl_t c, const char *key)¶: Set host key

Parameters

nvme_ctrl_t c: Host for which the key should be set
const char *key: DH-HMAC-CHAP Key to set or NULL to clear existing key

const char *nvme_ctrl_get_dhchap_key(nvme_ctrl_t c)¶: Return controller key

Parameters

nvme_ctrl_t c: Controller for which the key should be set

Return

DH-HMAC-CHAP controller key or NULL if not set

const char *nvme_ns_head_get_sysfs_dir(nvme_ns_head_t head)¶: sysfs dir of namespave head

Parameters

nvme_ns_head_t head: namespace head instance

Return

sysfs directory name of head

void nvme_ctrl_set_dhchap_key(nvme_ctrl_t c, const char *key)¶: Set controller key

Parameters

nvme_ctrl_t c: Controller for which the key should be set
const char *key: DH-HMAC-CHAP Key to set or NULL to clear existing key

const char *nvme_ctrl_get_keyring(nvme_ctrl_t c)¶: Return keyring

Parameters

nvme_ctrl_t c: Controller to be used for the lookup

Return

Keyring or NULL if not set

void nvme_ctrl_set_keyring(nvme_ctrl_t c, const char *keyring)¶: Set keyring

Parameters

nvme_ctrl_t c: Controller for which the keyring should be set
const char *keyring: Keyring name

const char *nvme_ctrl_get_tls_key_identity(nvme_ctrl_t c)¶: Return Derive TLS Identity

Parameters

nvme_ctrl_t c: Controller to be used for the lookup

Return

Derive TLS Identity or NULL if not set

void nvme_ctrl_set_tls_key_identity(nvme_ctrl_t c, const char *identity)¶: Set Derive TLS Identity

Parameters

nvme_ctrl_t c: Controller for which the key should be set
const char *identity: Derive TLS identity or NULL to clear existing key

const char *nvme_ctrl_get_tls_key(nvme_ctrl_t c)¶: Return Derive TLS PSK

Parameters

nvme_ctrl_t c: Controller to be used for the lookup

Return

Key in PSK interchange format or NULL if not set

void nvme_ctrl_set_tls_key(nvme_ctrl_t c, const char *key)¶: Set Derive TLS PSK

Parameters

nvme_ctrl_t c: Controller for which the key should be set
const char *key: Key in interchange format or NULL to clear existing key

struct nvme_fabrics_config *nvme_ctrl_get_config(nvme_ctrl_t c)¶: Fabrics configuration of a controller

Parameters

nvme_ctrl_t c: Controller instance

Return

Fabrics configuration of c

void nvme_ctrl_set_discovered(nvme_ctrl_t c, bool discovered)¶: Set the ‘discovered’ flag

Parameters

nvme_ctrl_t c: nvme_ctrl_t object
bool discovered: Value of the ‘discovered’ flag

Description

Set the ‘discovered’ flag of c to discovered

bool nvme_ctrl_is_discovered(nvme_ctrl_t c)¶: Returns the value of the ‘discovered’ flag

Parameters

nvme_ctrl_t c: Controller instance

Return

Value of the ‘discovered’ flag of c

void nvme_ctrl_set_persistent(nvme_ctrl_t c, bool persistent)¶: Set the ‘persistent’ flag

Parameters

nvme_ctrl_t c: Controller instance
bool persistent: value of the ‘persistent’ flag

Description

Set the ‘persistent’ flag of c to persistent

bool nvme_ctrl_is_persistent(nvme_ctrl_t c)¶: Returns the value of the ‘persistent’ flag

Parameters

nvme_ctrl_t c: Controller instance

Return

Value of the ‘persistent’ flag of c

void nvme_ctrl_set_discovery_ctrl(nvme_ctrl_t c, bool discovery)¶: Set the ‘discovery_ctrl’ flag

Parameters

nvme_ctrl_t c: Controller to be modified
bool discovery: value of the discovery_ctrl flag

Description

Sets the ‘discovery_ctrl’ flag in c to specify whether c connects to a discovery subsystem.

bool nvme_ctrl_is_discovery_ctrl(nvme_ctrl_t c)¶: Check the ‘discovery_ctrl’ flag

Parameters

nvme_ctrl_t c: Controller to be checked

Description

Returns the value of the ‘discovery_ctrl’ flag which specifies whether c connects to a discovery subsystem.

Return

Value of the ‘discover_ctrl’ flag

void nvme_ctrl_set_unique_discovery_ctrl(nvme_ctrl_t c, bool unique)¶: Set the ‘unique_discovery_ctrl’ flag

Parameters

nvme_ctrl_t c: Controller to be modified
bool unique: value of the unique_disc_ctrl flag

Description

Sets the ‘unique_discovery_ctrl’ flag in c to specify wheter c is a unique discovery controller

bool nvme_ctrl_is_unique_discovery_ctrl(nvme_ctrl_t c)¶: Check the ‘unique_discovery_ctrl’ flag

Parameters

nvme_ctrl_t c: Controller to be checked

Return

Value of the ‘unique_discovery_ctrl’ flag

int nvme_ctrl_identify(nvme_ctrl_t c, struct nvme_id_ctrl *id)¶: Issues an ‘identify controller’ command

Parameters

nvme_ctrl_t c: Controller instance
struct nvme_id_ctrl *id: Identify controller data structure

Description

Issues an ‘identify controller’ command to c and copies the data into id.

Return

0 on success or -1 on failure.

int nvme_disconnect_ctrl(nvme_ctrl_t c)¶: Disconnect a controller

Parameters

nvme_ctrl_t c: Controller instance

Description

Issues a ‘disconnect’ fabrics command to c

Return

0 on success, -1 on failure.

nvme_ctrl_t nvme_scan_ctrl(nvme_root_t r, const char *name)¶: Scan on a controller

Parameters

nvme_root_t r: nvme_root_t object
const char *name: Name of the controller

Description

Scans a controller with sysfs name name and add it to r.

Return

nvme_ctrl_t object

void nvme_rescan_ctrl(nvme_ctrl_t c)¶: Rescan an existing controller

Parameters

nvme_ctrl_t c: Controller instance

int nvme_init_ctrl(nvme_host_t h, nvme_ctrl_t c, int instance)¶: Initialize nvme_ctrl_t object for an existing controller.

Parameters

nvme_host_t h: nvme_host_t object
nvme_ctrl_t c: nvme_ctrl_t object
int instance: Instance number (e.g. 1 for nvme1)

Return

The ioctl() return code. Typically 0 on success.

void nvme_free_ctrl(struct nvme_ctrl *c)¶: Free controller

Parameters

struct nvme_ctrl *c: Controller instance

void nvme_unlink_ctrl(struct nvme_ctrl *c)¶: Unlink controller

Parameters

struct nvme_ctrl *c: Controller instance

const char *nvme_subsystem_get_nqn(nvme_subsystem_t s)¶: Retrieve NQN from subsystem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

NQN of subsystem

const char *nvme_subsystem_get_sysfs_dir(nvme_subsystem_t s)¶: sysfs directory of an nvme_subsystem_t object

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

sysfs directory name of s

const char *nvme_subsystem_get_name(nvme_subsystem_t s)¶: sysfs name of an nvme_subsystem_t object

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

sysfs name of s

const char *nvme_subsystem_get_type(nvme_subsystem_t s)¶: Returns the type of a subsystem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Description

Returns the subsystem type of s.

Return

‘nvm’ or ‘discovery’

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.

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.

const char *nvme_subsystem_get_iopolicy(nvme_subsystem_t s)¶: Return the IO policy of subsytem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

IO policy used by current subsystem

const char *nvme_subsystem_get_model(nvme_subsystem_t s)¶: Return the model of subsystem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

Model of the current subsystem

const char *nvme_subsystem_get_serial(nvme_subsystem_t s)¶: Return the serial number of subsystem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

Serial number of the current subsystem

const char *nvme_subsystem_get_fw_rev(nvme_subsystem_t s)¶: Return the firmware rev of subsystem

Parameters

nvme_subsystem_t s: nvme_subsystem_t object

Return

Firmware revision of the current subsystem

int nvme_scan_topology(nvme_root_t r, nvme_scan_filter_t f, void *f_args)¶: Scan NVMe topology and apply filter

Parameters

nvme_root_t r: nvme_root_t object
nvme_scan_filter_t f: filter to apply
void *f_args: user-specified argument to f

Description

Scans the NVMe topology and filters out the resulting elements by applying f.

Return

0 on success, -1 on failure with errno set.

const char *nvme_host_get_hostnqn(nvme_host_t h)¶: Host NQN of an nvme_host_t object

Parameters

nvme_host_t h: nvme_host_t object

Return

Host NQN of h

const char *nvme_host_get_hostid(nvme_host_t h)¶: Host ID of an nvme_host_t object

Parameters

nvme_host_t h: nvme_host_t object

Return

Host ID of h

void nvme_host_release_fds(struct nvme_host *h)¶: Close all opened file descriptors under host

Parameters

struct nvme_host *h: nvme_host_t object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds under this host.

void nvme_free_host(nvme_host_t h)¶: Free nvme_host_t object

Parameters

nvme_host_t h: nvme_host_t object

nvme_root_t nvme_scan(const char *config_file)¶: Scan NVMe topology

Parameters

const char *config_file: Configuration file

Return

nvme_root_t object of found elements

int nvme_read_config(nvme_root_t r, const char *config_file)¶: Read NVMe JSON configuration file

Parameters

nvme_root_t r: nvme_root_t object
const char *config_file: JSON configuration file

Description

Read in the contents of config_file and merge them with the elements in r.

Return

0 on success, -1 on failure with errno set.

void nvme_refresh_topology(nvme_root_t r)¶: Refresh nvme_root_t object contents

Parameters

nvme_root_t r: nvme_root_t object

Description

Removes all elements in r and rescans the existing topology.

int nvme_update_config(nvme_root_t r)¶: Update JSON configuration

Parameters

nvme_root_t r: nvme_root_t object

Description

Updates the JSON configuration file with the contents of r.

Return

0 on success, -1 on failure.

int nvme_dump_config(nvme_root_t r)¶: Print the JSON configuration

Parameters

nvme_root_t r: nvme_root_t object

Description

Prints the current contents of the JSON configuration file to stdout.

Return

0 on success, -1 on failure.

int nvme_dump_tree(nvme_root_t r)¶: Dump internal object tree

Parameters

nvme_root_t r: nvme_root_t object

Description

Prints the internal object tree in JSON format to stdout.

Return

0 on success, -1 on failure.

char *nvme_get_attr(const char *d, const char *attr)¶: Read sysfs attribute

Parameters

const char *d: sysfs directory
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error (indicated by non-zero errno code).

char *nvme_get_subsys_attr(nvme_subsystem_t s, const char *attr)¶: Read subsystem sysfs attribute

Parameters

nvme_subsystem_t s: nvme_subsystem_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error (indicated by non-zero errno code).

char *nvme_get_ctrl_attr(nvme_ctrl_t c, const char *attr)¶: Read controller sysfs attribute

Parameters

nvme_ctrl_t c: Controller instance
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error (indicated by non-zero errno code).

char *nvme_get_ns_attr(nvme_ns_t n, const char *attr)¶: Read namespace sysfs attribute

Parameters

nvme_ns_t n: nvme_ns_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error (indicated by non-zero errno code).

nvme_ns_t nvme_subsystem_lookup_namespace(struct nvme_subsystem *s, __u32 nsid)¶: lookup namespace by NSID

Parameters

struct nvme_subsystem *s: nvme_subsystem_t object
__u32 nsid: Namespace id

Return

nvme_ns_t of the namespace with id nsid in subsystem s

void nvme_subsystem_release_fds(struct nvme_subsystem *s)¶: Close all opened fds under subsystem

Parameters

struct nvme_subsystem *s: nvme_subsystem_t object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds under this subsystem.

char *nvme_get_path_attr(nvme_path_t p, const char *attr)¶: Read path sysfs attribute

Parameters

nvme_path_t p: nvme_path_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error (indicated by non-zero errno code).

nvme_ns_t nvme_scan_namespace(const char *name)¶: scan namespace based on sysfs name

Parameters

const char *name: sysfs name of the namespace to scan

Return

nvme_ns_t object or NULL if not found.

const char *nvme_host_get_hostsymname(nvme_host_t h)¶: Get the host’s symbolic name

Parameters

nvme_host_t h: Host for which the symbolic name should be returned.

Return

The symbolic name or NULL if a symbolic name hasn’t been configure.

void nvme_host_set_hostsymname(nvme_host_t h, const char *hostsymname)¶: Set the host’s symbolic name

Parameters

nvme_host_t h: Host for which the symbolic name should be set.
const char *hostsymname: Symbolic name

filters.h

libnvme directory filter

int nvme_namespace_filter(const struct dirent *d)¶: Filter for namespaces

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int nvme_paths_filter(const struct dirent *d)¶: Filter for paths

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int nvme_ctrls_filter(const struct dirent *d)¶: Filter for controllers

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int nvme_subsys_filter(const struct dirent *d)¶: Filter for subsystems

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int nvme_scan_subsystems(struct dirent ***subsys)¶: Scan for subsystems

Parameters

struct dirent ***subsys: Pointer to array of dirents

Return

number of entries in subsys

int nvme_scan_subsystem_namespaces(nvme_subsystem_t s, struct dirent ***ns)¶: Scan for namespaces in a subsystem

Parameters

nvme_subsystem_t s: Subsystem to scan
struct dirent ***ns: Pointer to array of dirents

Return

number of entries in ns

int nvme_scan_ctrls(struct dirent ***ctrls)¶: Scan for controllers

Parameters

struct dirent ***ctrls: Pointer to array of dirents

Return

number of entries in ctrls

int nvme_scan_ctrl_namespace_paths(nvme_ctrl_t c, struct dirent ***paths)¶: Scan for namespace paths in a controller

Parameters

nvme_ctrl_t c: Controller to scan
struct dirent ***paths: Pointer to array of dirents

Return

number of entries in paths

int nvme_scan_ctrl_namespaces(nvme_ctrl_t c, struct dirent ***ns)¶: Scan for namespaces in a controller

Parameters

nvme_ctrl_t c: Controller to scan
struct dirent ***ns: Pointer to array of dirents

Return

number of entries in ns

int nvme_scan_ns_head_paths(nvme_ns_head_t head, struct dirent ***paths)¶: Scan for namespace paths

Parameters

nvme_ns_head_t head: Namespace head node to scan
struct dirent ***paths: Pointer to array of dirents

Return

number of entries in ents

util.h

libnvme utility functions

enum nvme_connect_err¶: nvme connect error codes

Constants

ENVME_CONNECT_RESOLVE: failed to resolve host
ENVME_CONNECT_ADDRFAM: unrecognized address family
ENVME_CONNECT_TRADDR: failed to get traddr
ENVME_CONNECT_TARG: need a transport (-t) argument
ENVME_CONNECT_AARG: need a address (-a) argument
ENVME_CONNECT_OPEN: failed to open nvme-fabrics device
ENVME_CONNECT_WRITE: failed to write to nvme-fabrics device
ENVME_CONNECT_READ: failed to read from nvme-fabrics device
ENVME_CONNECT_PARSE: failed to parse ctrl info
ENVME_CONNECT_INVAL_TR: invalid transport type
ENVME_CONNECT_LOOKUP_SUBSYS_NAME: failed to lookup subsystem name
ENVME_CONNECT_LOOKUP_SUBSYS: failed to lookup subsystem
ENVME_CONNECT_ALREADY: the connect attempt failed, already connected
ENVME_CONNECT_INVAL: invalid arguments/configuration
ENVME_CONNECT_ADDRINUSE: hostnqn already in use
ENVME_CONNECT_NODEV: invalid interface
ENVME_CONNECT_OPNOTSUPP: not supported
ENVME_CONNECT_CONNREFUSED: connection refused
ENVME_CONNECT_ADDRNOTAVAIL: cannot assign requested address
ENVME_CONNECT_IGNORED: connect attempt is ignored due to configuration
ENVME_CONNECT_NOKEY: the TLS key is missing

__u8 nvme_status_to_errno(int status, bool fabrics)¶: Converts nvme return status to errno

Parameters

int status: Return status from an nvme passthrough command
bool fabrics: Set to true if status is to a fabrics target.

Return

An errno representing the nvme status if it is an nvme status field, or unchanged status is < 0 since errno is already set.

const char *nvme_status_to_string(int status, bool fabrics)¶: Returns string describing nvme return status.

Parameters

int status: Return status from an nvme passthrough command
bool fabrics: Set to true if status is to a fabrics target.

Return

String representation of the nvme status if it is an nvme status field, or a standard errno string if status is < 0.

const char *nvme_errno_to_string(int err)¶: Returns string describing nvme connect failures

Parameters

int err: Returned error code from nvme_add_ctrl()

Return

String representation of the nvme connect error codes

void nvme_init_ctrl_list(struct nvme_ctrl_list *cntlist, __u16 num_ctrls, __u16 *ctrlist)¶: Initialize an nvme_ctrl_list structure from an array.

Parameters

struct nvme_ctrl_list *cntlist: The controller list structure to initialize
__u16 num_ctrls: The number of controllers in the array, ctrlist.
__u16 *ctrlist: An array of controller identifiers in CPU native endian.

Description

This is intended to be used with any command that takes a controller list argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().

void nvme_init_dsm_range(struct nvme_dsm_range *dsm, __u32 *ctx_attrs, __u32 *llbas, __u64 *slbas, __u16 nr_ranges)¶: Constructs a data set range structure

Parameters

struct nvme_dsm_range *dsm: DSM range array
__u32 *ctx_attrs: Array of context attributes
__u32 *llbas: Array of length in logical blocks
__u64 *slbas: Array of starting logical blocks
__u16 nr_ranges: The size of the dsm arrays

Description

Each array must be the same size of size ‘nr_ranges’. This is intended to be used with constructing a payload for nvme_dsm().

Return

The nvme command status if a response was received or -errno otherwise.

void nvme_init_copy_range(struct nvme_copy_range *copy, __u16 *nlbs, __u64 *slbas, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)¶: Constructs a copy range structure

Parameters

struct nvme_copy_range *copy: Copy range array
__u16 *nlbs: Number of logical blocks
__u64 *slbas: Starting LBA
__u32 *eilbrts: Expected initial logical block reference tag
__u32 *elbatms: Expected logical block application tag mask
__u32 *elbats: Expected logical block application tag
__u16 nr: Number of descriptors to construct

void nvme_init_copy_range_f1(struct nvme_copy_range_f1 *copy, __u16 *nlbs, __u64 *slbas, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)¶: Constructs a copy range f1 structure

Parameters

struct nvme_copy_range_f1 *copy: Copy range array
__u16 *nlbs: Number of logical blocks
__u64 *slbas: Starting LBA
__u64 *eilbrts: Expected initial logical block reference tag
__u32 *elbatms: Expected logical block application tag mask
__u32 *elbats: Expected logical block application tag
__u16 nr: Number of descriptors to construct

void nvme_init_copy_range_f2(struct nvme_copy_range_f2 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)¶: Constructs a copy range f2 structure

Parameters

struct nvme_copy_range_f2 *copy: Copy range array
__u32 *snsids: Source namespace identifier
__u16 *nlbs: Number of logical blocks
__u64 *slbas: Starting LBA
__u16 *sopts: Source options
__u32 *eilbrts: Expected initial logical block reference tag
__u32 *elbatms: Expected logical block application tag mask
__u32 *elbats: Expected logical block application tag
__u16 nr: Number of descriptors to construct

void nvme_init_copy_range_f3(struct nvme_copy_range_f3 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)¶: Constructs a copy range f3 structure

Parameters

struct nvme_copy_range_f3 *copy: Copy range array
__u32 *snsids: Source namespace identifier
__u16 *nlbs: Number of logical blocks
__u64 *slbas: Starting LBA
__u16 *sopts: Source options
__u64 *eilbrts: Expected initial logical block reference tag
__u32 *elbatms: Expected logical block application tag mask
__u32 *elbats: Expected logical block application tag
__u16 nr: Number of descriptors to construct

int nvme_get_feature_length(int fid, __u32 cdw11, __u32 *len)¶: Retreive the command payload length for a specific feature identifier

Parameters

int fid: Feature identifier, see enum nvme_features_id.
__u32 cdw11: The cdw11 value may affect the transfer (only known fid is NVME_FEAT_FID_HOST_ID)
__u32 *len: On success, set to this features payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize fid.

int nvme_get_feature_length2(int fid, __u32 cdw11, enum nvme_data_tfr dir, __u32 *len)¶: Retreive the command payload length for a specific feature identifier

Parameters

int fid: Feature identifier, see enum nvme_features_id.
__u32 cdw11: The cdw11 value may affect the transfer (only known fid is NVME_FEAT_FID_HOST_ID)
enum nvme_data_tfr dir: Data transfer direction: false - host to controller, true - controller to host may affect the transfer (only known fid is NVME_FEAT_FID_HOST_MEM_BUF).
__u32 *len: On success, set to this features payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize fid.

int nvme_get_directive_receive_length(enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len)¶: Get directive receive length

Parameters

enum nvme_directive_dtype dtype: Directive type, see enum nvme_directive_dtype
enum nvme_directive_receive_doper doper: Directive receive operation, see enum nvme_directive_receive_doper
__u32 *len: On success, set to this directives payload length in bytes.

Return

0 on success, -1 with errno set to EINVAL if the function did not recognize dtype or doper.

size_t get_entity_name(char *buffer, size_t bufsz)¶: Get Entity Name (ENAME).

Parameters

char *buffer: The buffer where the ENAME will be saved as an ASCII string.
size_t bufsz: The size of buffer.

Description

Per TP8010, ENAME is defined as the name associated with the host (i.e. hostname).

Return

Number of characters copied to buffer.

size_t get_entity_version(char *buffer, size_t bufsz)¶: Get Entity Version (EVER).

Parameters

char *buffer: The buffer where the EVER will be saved as an ASCII string.
size_t bufsz: The size of buffer.

Description

EVER is defined as the operating system name and version as an ASCII string. This function reads different files from the file system and builds a string as follows: [os type] [os release] [distro release]

E.g. “Linux 5.17.0-rc1 SLES 15.4”

Return

Number of characters copied to buffer.

char *kv_strip(char *kv)¶: Strip blanks from key value string

Parameters

char *kv: The key-value string to strip

Description

Strip leading/trailing blanks as well as trailing comments from the Key=Value string pointed to by kv.

Return

A pointer to the stripped string. Note that the original string, kv, gets modified.

char *kv_keymatch(const char *kv, const char *key)¶: Look for key in key value string

Parameters

const char *kv: The key=value string to search for the presence of key
const char *key: The key to look for

Description

Look for key in the Key=Value pair pointed to by k and return a pointer to the Value if key is found.

Check if kv starts with key. If it does then make sure that we have a whole-word match on the key, and if we do, return a pointer to the first character of value (i.e. skip leading spaces, tabs, and equal sign)

Return

A pointer to the first character of “value” if a match is found. NULL otherwise.

char *startswith(const char *s, const char *prefix)¶: Checks that a string starts with a given prefix.

Parameters

const char *s: The string to check
const char *prefix: A string that s could be starting with

Return

If s starts with prefix, then return a pointer within s at the first character after the matched prefix. NULL otherwise.

round_up¶

round_up (val, mult)

Round a value val to the next multiple specified by mult.

Parameters

val: Value to round
mult: Multiple to round to.

Description

usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16

__u16 nvmf_exat_len(size_t val_len)¶: Return length rounded up by 4

Parameters

size_t val_len: Value length

Description

Return the size in bytes, rounded to a multiple of 4 (e.g., size of __u32), of the buffer needed to hold the exat value of size val_len.

Return

Length rounded up by 4

__u16 nvmf_exat_size(size_t val_len)¶: Return min aligned size to hold value

Parameters

size_t val_len: This is the length of the data to be copied to the “exatval” field of a “struct nvmf_ext_attr”.

Description

Return the size of the “struct nvmf_ext_attr” needed to hold a value of size val_len.

Return

The size in bytes, rounded to a multiple of 4 (i.e. size of __u32), of the “struct nvmf_ext_attr” required to hold a string of length val_len.

struct nvmf_ext_attr *nvmf_exat_ptr_next(struct nvmf_ext_attr *p)¶: Increment p to the next element in the array.

Parameters

struct nvmf_ext_attr *p: Pointer to an element of an array of “struct nvmf_ext_attr”.

Description

Extended attributes are saved to an array of “struct nvmf_ext_attr” where each element of the array is of variable size. In order to move to the next element in the array one must increment the pointer to the current element (p) by the size of the current element.

Return

Pointer to the next element in the array.

enum nvme_version¶: Selector for version to be returned by nvme_get_version

Constants

NVME_VERSION_PROJECT: Project release version
NVME_VERSION_GIT: Git reference

const char *nvme_get_version(enum nvme_version type)¶: Return version libnvme string

Parameters

enum nvme_version type: Selects which version type (see struct nvme_version)

Return

Returns version string for known types or else “n/a”

int nvme_uuid_to_string(unsigned char uuid[NVME_UUID_LEN], char *str)¶: Return string represenation of encoded UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID
char *str: Output string represenation of UUID

Return

Returns error code if type conversion fails.

int nvme_uuid_from_string(const char *str, unsigned char uuid[NVME_UUID_LEN])¶: Return encoded UUID represenation of string UUID

Parameters

const char *str: Output string represenation of UUID
unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID

Return

Returns error code if type conversion fails.

int nvme_uuid_random(unsigned char uuid[NVME_UUID_LEN])¶: Generate random UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]: Generated random UUID

Description

Generate random number according https://www.rfc-editor.org/rfc/rfc4122#section-4.4

Return

Returns error code if generating of random number fails.

int nvme_uuid_find(struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN])¶: Find UUID position on UUID list

Parameters

struct nvme_id_uuid_list *uuid_list: UUID list returned by identify UUID
const unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID

Return

The array position where given UUID is present, or -1 on failure with errno set.

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.

const char *nvme_iface_matching_addr(const struct ifaddrs *iface_list, const char *addr)¶: Get interface matching addr

Parameters

const struct ifaddrs *iface_list: Interface list returned by getifaddrs()
const char *addr: Address to match

Description

Parse the interface list pointed to by iface_list looking for the interface that has addr as one of its assigned addresses.

Return

The name of the interface that owns addr or NULL.

bool nvme_iface_primary_addr_matches(const struct ifaddrs *iface_list, const char *iface, const char *addr)¶: Check that interface’s primary address matches

Parameters

const struct ifaddrs *iface_list: Interface list returned by getifaddrs()
const char *iface: Interface to match
const char *addr: Address to match

Description

Parse the interface list pointed to by iface_list and looking for interface iface. The get its primary address and check if it matches addr.

Return

true if a match is found, false otherwise.

log.h

logging functions

void nvme_init_logging(nvme_root_t r, int lvl, bool log_pid, bool log_tstamp)¶: Initialize logging

Parameters

nvme_root_t r: nvme_root_t context
int lvl: Logging level to set
bool log_pid: Boolean to enable logging of the PID
bool log_tstamp: Boolean to enable logging of the timestamp

Description

Sets the default logging variables for the library.

void nvme_init_default_logging(FILE *fp, int lvl, bool log_pid, bool log_tstamp)¶: Initialize default (fallback) logging

Parameters

FILE *fp: File descriptor for logging messages
int lvl: Logging level to set
bool log_pid: Boolean to enable logging of the PID
bool log_tstamp: Boolean to enable logging of the timestamp

Description

Sets the default logging settings for the library in case the root object is absent.

int nvme_get_logging_level(nvme_root_t r, bool *log_pid, bool *log_tstamp)¶: Get current logging level

Parameters

nvme_root_t r: nvme_root_t context
bool *log_pid: Pointer to store a current value of logging of the PID flag at (optional).
bool *log_tstamp: Pointer to store a current value of logging of the timestamp flag at (optional).

Description

Retrieves current values of logging variables.

Return

current log level value or DEFAULT_LOGLEVEL if not initialized.

void nvme_set_root(nvme_root_t r)¶: Set nvme_root_t context

Parameters

nvme_root_t r: nvme_root_t context

Description

In order to be able to log from code paths where no root object is passed in via the arguments use the the default one which can be set via this call. When creating a new root object with nvme_create_root the global root object will be set as well. This means the global root object is always pointing to the latest created root object. Note the first nvme_free_tree call will reset the global root object.

This function is deprecated. Use nvme_init_default_logging or/and nvme_init_logging instead.

void nvme_set_debug(bool debug)¶: Set NVMe command debugging output

Parameters

bool debug: true to enable or false to disable

Description

This function is deprecated. Use nvme_init_default_logging instead.

bool nvme_get_debug(void)¶: Get NVMe command debugging output

Parameters

void: no arguments

Description

This function is deprecated. Use nvme_get_logging_level instead.

Return

false if disabled or true if enabled.

nbft.h

NVM Express Boot Specification, Revision 1.0

Note: this API is currently unstable, subject to further additions.

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.

enum nbft_trtype¶: NBFT Interface Transport Types (Figure 7)

Constants

NBFT_TRTYPE_TCP: NVMe/TCP (802.3 + TCP/IP). String Designator “tcp”.

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.

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.

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 enum 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 enum nbft_control_flags.
reserved2: Reserved.
hdesc: Host Descriptor (HDESC): This field indicates the location and length of the Host Descriptor (see struct 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 struct 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 struct 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 struct 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 struct nbft_discovery), if any, in the Discovery Descriptor List, if any.
reserved4: Reserved.

enum nbft_control_flags¶: Control Descriptor Flags

Constants

NBFT_CONTROL_VALID: Block Valid: indicates that the structure is valid.

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 enum 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.

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 (struct 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.

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 enum nbft_hfi_flags.
trtype: HFI Transport Type, see enum 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.

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.

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 enum 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 struct nbft_hfi.index) whose HFI Transport Info Descriptor Heap Object Reference field indicates this HFI Transport Info Descriptor.
flags: HFI Transport Flags, see enum 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.

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.

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 enum nbft_ssns_flags.
trtype: Transport Type, see enum nbft_trtype.
trflags: Transport Specific Flags, see enum nbft_ssns_trflags.
primary_discovery_ctrl_index: Primary Discovery Controller Index: The Discovery Descriptor Index field of the Discovery Descriptor (see struct 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 enum 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 struct 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 struct 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 struct 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.

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.

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.

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 struct nbft_ssns) whose SSNS Extended Information Descriptor Heap Object Reference field indicates this descriptor.
flags: Flags, see enum 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.

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.

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 enum nbft_security_flags.
secret_type: Secret Type, see enum 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.

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.

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.

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 enum 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.

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.

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.

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 enum nbft_info_primary_admin_host_flag.

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.

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 struct nbft_info_hfi_info_tcp.

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 struct nbft_info_security.
hfi: The HFI Descriptor associated with this Discovery Descriptor. See struct nbft_info_hfi.
uri: A URI which indicates an NVMe Discovery controller associated with this Discovery Descriptor.
nqn: An NVMe Discovery controller NQN.

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.

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.

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;
  bool discovered;
  bool unavailable;
};

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 enum 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).
discovered: Indicates that this namespace was acquired through discovery.
unavailable: Namespace is unavailable as indicated by the pre-OS driver.

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).

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.

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.

API¶

libnvme

Navigation

Related Topics