libnvme API review

[Daniel Wagner]

Hi Curtis,

On Mon, Mar 16, 2026 at 03:34:39PM +0000, Ballard, Curtis C (HPE Storage) wrote:
> It looks like these proposed changes are intended to align better with the terms
> in common use or in the NVMe specifications.

I think I should provide some background here first.

The libnvme headers previously mixed NVMe spec APIs with library APIs.
This has been mostly resolved (though some further cleanups are
necessary, we are almost there).

types.h contains all the "payload" definitions for a command, while
cmds.h contains helper functions to set up a command structure. While
cmds.h is fairly clean and closely follows the spec, types.h uses
different styles. Cleaning this part up will be a major task, and I
don't have the time or the patience to do it myself. If anyone wants to
work on this, be my guest.

linux.h, lib.h, ioctl.h, filters.h, and util.h constitute the library
interface used to set up and submit commands to a controller.

fabrics.h (I just realized the table is missing entries) contains the
interface for Fabrics commands, such as connect and disconnect.

The tree.h API defines a data structure that connects various
"resources" such as subsystems, namespaces, and controllers—together.
The tree is populated by reading from the kernel's sysfs interface.
Consequently, while this data structure uses the same names as the
specification, it is not the same thing.

> That may be a side effect of the
> library authors generally using that to create names rather than being the goal
> since you refer to library consistency as the goal.
> 
> With spec and common use in mind, one proposed changed jumped out at me:
> | `nvme_subsystem_reset`       | `nvme_reset_subsystem` |

This is from ioctl.h, which provides the interface for interacting with
the kernel via ioctls. As outlined in the email, the proposal is to
adopt the nvme_VERB_RESOURCE pattern, which more closely follows the
kernel's naming scheme (at least within the NVMe subsystem). In this
specific case, the NVME_IOCTL_SUBSYS_RESET ioctl is issued, which maps
to

    static inline int nvme_reset_subsystem(struct nvme_ctrl *ctrl)
    {
        if (!ctrl->subsystem || !ctrl->ops->subsystem_reset)
		   return -ENOTTY;
        return ctrl->ops->subsystem_reset(ctrl);
    }

inside the kernel.

> The term in the NVMe specifications is "subsystem reset" and that term is used
> many times but I don't see any use of "reset subsystem". Most common use by
> those well versed in the technology also is "subsystem reset" though I have
> seen "reset subsystem" used pretty frequently by people who aren't deep in
> the NVMe specs.

I see. The problem is that mixing NVMe spec terminology with library
API terminology could cause confusion.

> I don't know whether there is a 'best' for this term. General software developers
> might prefer "reset subsystem" but mapping to the specs will be easier with
> "subsystem reset".

The only way I currently see to resolve this is by using a different
prefix for the library APIs (e.g., libnvme_) and reserving the nvme_
prefix exclusively for NVMe spec APIs. However, I am unsure if this
approach will reach a consensus here.

Thanks,
Daniel