[PATCH v2 1/3] nvme: add ABI documentation for host sysfs interfaces

[Guixin Liu]

在 2026/7/2 21:49, Nilay Shroff 写道:
> On 7/2/26 3:25 PM, Guixin Liu wrote:
>> +What: /sys/block/nvmeXnY/diag/command_retries_count
>> +What:        /sys/block/nvmeXnY/diag/command_error_count
>> +What:        /sys/block/nvmeXnY/diag/multipath_failover_count
>> +What: /sys/block/nvmeXnY/diag/io_requeue_no_usable_path_count
>> +What: /sys/block/nvmeXnY/diag/io_fail_no_available_path_count
>> +Date:        May 2026
>> +KernelVersion:    7.2
>> +Contact:    Nilay Shroff<nilay at linux.ibm.com>
>> +Description:
>> +        Namespace diagnostic counters.
>> +
>> +        command_retries_count: I/O command retry counter. Only
>> +        visible on per-path devices.
>> +
>> +        command_error_count: I/O command error counter. Only
>> +        visible on per-path devices.
>> +
>> +        multipath_failover_count: Multipath failover counter.
>> +        Only visible on per-path devices. Requires
>> +        CONFIG_NVME_MULTIPATH.
>> +
>> +        io_requeue_no_usable_path_count: Counter of I/Os requeued
>> +        because no usable path was available. Only visible on
>> +        multipath head devices. Requires CONFIG_NVME_MULTIPATH.
>> +
>> +        io_fail_no_available_path_count: Counter of I/Os failed
>> +        because no available path existed. Only visible on
>> +        multipath head devices. Requires CONFIG_NVME_MULTIPATH.
>> +
>> +        All counters can be reset by writing a value.
>> +
>
> How about splitting the above diagnostic counters into two sections 
> instead? Since the sysfs
> layout differs depending on whether multipath is enabled, I think 
> documenting them separately
> may make the interface clearer.
>
> For instance, how about documenting it as follows:
>
> One block covering non-multipath configurations:
>
> What:           /sys/block/nvmeXnY/diag/command_retries_count
> What:           /sys/block/nvmeXnY/diag/command_error_count
>
> Description:
>         Namespace diagnostic counters for non-multipath
>         configurations (when CONFIG_NVME_MULTIPATH is
>         not configured).
>
>         command_retries_count: I/O command retry counter.
>
>         command_error_count: I/O command error counter.
>
>         All counters can be reset by writing any value.
>
> For multipath configurations:
>
> What:           /sys/block/nvmeXcYnZ/diag/command_retries_count
> What:           /sys/block/nvmeXcYnZ/diag/command_error_count
> What: /sys/block/nvmeXcYnZ/diag/multipath_failover_count
> What: /sys/block/nvmeXnY/diag/io_requeue_no_usable_path_count
> What: /sys/block/nvmeXnY/diag/io_fail_no_available_path_count
>
> Description:
>         Namespace diagnostic counters for multipath
>         configurations (when CONFIG_NVME_MULTIPATH is
>         configured).
>
>         command_retries_count: I/O command retry counter.
>
>         command_error_count: I/O command error counter.
>
>         multipath_failover_count: Multipath failover counter.
>
>         io_requeue_no_usable_path_count: Counter of I/Os
>         requeued because no usable path was available.
>
>         io_fail_no_available_path_count: Counter of I/Os
>         failed because no available path existed.
>
>         All counters can be reset by writing any value.
>
> I think this better reflects the actual sysfs interface and makes it 
> immediately obvious where each
> attribute is exposed, without having to describe the differences 
> between per-path and multipath head
> devices in the individual attribute descriptions.
>
Sure, changed in v3 thanks.
> One other suggestion: could we keep all of the diagnostic counters 
> grouped together in the ABI
> documentation? I noticed that in your first revision they were all 
> documented together, but in
> this revision they're separated. I'm referring to the controller 
> diagnostic counters under:
> /sys/class/nvme/nvmeX/diag/*
>
> IMO, keeping all of the diagnostic counters adjacent would make the 
> documentation easier to
> browse.
My bad, changed in v3 thanks.

Best Regards,
Guixin Liu
>
> And yes thanks for documenting all this!
>
> --Nilay