libnvme API review

[Hannes Reinecke]

On 3/18/26 09:01, Nilay Shroff wrote:
> 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?
> 
This is actually part of a wider-ranging challenge: lifetime
of structure elements.
While we do have abstractions like 'nvme_ctrl', 'nvme_subsys',
and the like, most of the settings in these objects are typically
read-only, and can only be set when the object is instantiated
(ie read from sysfs).
So we either need to find a way to set the scope of individual
settings (via __attribute__ or something), or we split the
structures into one structure used for _creating_ an object,
and declare the object itself readonly once created.

I've raised in issue in github
(https://github.com/linux-nvme/nvme-cli/issues/3192)
to discuss it there.

Cheers,

Hannes
-- 
Dr. Hannes Reinecke                  Kernel Storage Architect
hare at suse.de                                +49 911 74053 688
SUSE Software Solutions GmbH, Frankenstr. 146, 90461 Nürnberg
HRB 36809 (AG Nürnberg), GF: I. Totev, A. McDonald, W. Knoblich