libnvme API review

[Nilay Shroff]

On 3/16/26 3:57 PM, Daniel Wagner wrote:
> Hi,
> 
> For the upcoming v3.0 release of nvme-cli and libnvme, I would like to
> get some feedback on the naming scheme used in the libnvme function API.
> 
> The goal is to improve consistency across the library. Below is a table
> comparing the current names with the suggested new names.
> 
> Functions are grouped by common prefixes:
> 
> - Generic top-level functions use the nvme_ prefix.
> - Object-specific functions use the object type as a
>    prefix (e.g., nvme_ns_).
> 
> The prefix is typically followed by a verb, such as nvme_create_ctrl.
> 
Following the verb after the prefix looks good to me, as it aligns well
with the kernel naming style. While aligning fully with the NVMe spec
API would likely require a significant amount of cleanup, improving
consistency within libnvme is definitely a step in the right direction.

Since we are already considering API changes for the 3.0 release, I’d
also like to raise another point regarding non-cached variants of some
APIs (perhaps only for a subset where it makes sense).

Currently, most libnvme APIs return cached values for attributes. While
this is efficient, there are cases where a real-time view (for instance,
nvme-top) is required. For example, retrieving the current ANA state or
I/O policy may not be accurate if we rely solely on cached data (e.g.,
nvme_path_get_ana_state() or nvme_subsystem_get_iopolicy()).

To address this, I’d like to propose introducing non-cached variants of
selected APIs, for example:

nvme_path_get_current_<attribute>
nvme_ctrl_get_current_<attribute>
nvme_ns_get_current_<attribute>
nvme_subsystem_get_current_<attibute>

where <attribute> could be path ana_state, iopolicy, or other
attributes where fetching the latest value from the device or kernel is
important.

Does this approach (naming) make sense?

One another approach would be to always return the current/non-cached
value using existing API and then we don't need new API. I think this
could be reasonable considering the existing nvme-cli commands are
typically oneshot, and so it doesn't matter whether we return cached
or non-cached value.

Alternatively, are there better naming or design approaches for
distinguishing cached vs real-time queries?

Thanks,
--Nilay