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

[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.

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.

And yes thanks for documenting all this!

--Nilay