nvme: add ABI documentation for sysfs and configfs interfaces
v2 cover nvme: add ABI documentation for sysfs and configfs interfaces
This series adds ABI documentation for the NVMe host sysfs interfaces and the NVMe target configfs interfaces, and updates MAINTAINERS to route patches touching these files to the NVMe list.
Each documented entry has been traced to its original introducing commit to provide accurate Date, KernelVersion, and Contact fields.
v1->v2:
- sysfs: group all TLS attributes together and reorganize the file by device class (controller, namespace, subsystem), keeping related attributes grouped within each class; split the combined passthru_err_log_enabled entry into controller and namespace entries.
- configfs: group attributes by object type (ports, subsystems, hosts), merge dhchap_dhgroup into the DH-HMAC-CHAP host authentication entry, and split the combined ANA and PI-enable entries into separate port and subsystem entries.
Guixin Liu (3):
nvme: add ABI documentation for host sysfs interfaces
nvmet: add ABI documentation for target configfs interfaces
MAINTAINERS: add missing NVMe documentation files
Documentation/ABI/testing/configfs-nvmet | 352 ++++++++++++++++++ Documentation/ABI/testing/sysfs-nvme | 450 ++++++++++++++++++++++- MAINTAINERS | 4 + 3 files changed, 796 insertions(+), 10 deletions(-) create mode 100644 Documentation/ABI/testing/configfs-nvmet
Signature · 1 line
2.43.7
PATCH v2 1/3 nvme: add ABI documentation for host sysfs interfaces
Add Documentation/ABI/testing/sysfs-nvme documenting all NVMe host sysfs attributes, covering controller attributes under /sys/class/nvme/nvmeX/, namespace attributes under /sys/block/nvmeXnY/, and subsystem attributes under /sys/class/nvme-subsystem/nvme-subsysX/.
Each entry has been traced to its original introducing commit to provide accurate Date, KernelVersion, and Contact information.
---v1->v2:
- Group all TLS attributes together (move tls_key and tls_mode next to tls_configured_key and tls_keyring).
- Reorganize the file by device class (controller, namespace, subsystem), keeping related attributes grouped within each class.
- Split the combined passthru_err_log_enabled entry into separate controller and namespace entries.
Documentation/ABI/testing/sysfs-nvme | 450 ++++++++++++++++++++++++++- 1 file changed, 440 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-nvme +440 -10
@@ -1,13 +1,443 @@ -What: /sys/devices/virtual/nvme-fabrics/ctl/.../tls_configured_key +What: /sys/class/nvme/nvmeX/model +What: /sys/class/nvme/nvmeX/serial +What: /sys/class/nvme/nvmeX/firmware_rev +Date: January 2016 +KernelVersion: 4.5 +Contact: Keith Busch <[email protected]> +Description: + Shows the model, serial number, or firmware revision string + of the NVMe controller, as reported in the Identify + Controller data structure. + +What: /sys/class/nvme/nvmeX/cntlid +Date: February 2016 +KernelVersion: 4.6 +Contact: Ming Lin <[email protected]> +Description: + Shows the controller identifier assigned by the NVMe + subsystem. + +What: /sys/class/nvme/nvmeX/cntrltype +What: /sys/class/nvme/nvmeX/dctype +Date: February 2022 +KernelVersion: 5.18 +Contact: Martin Belanger <[email protected]> +Description: + cntrltype: Shows the controller type. Possible values: "io", + "discovery", "admin", "reserved". + + dctype: Shows the discovery controller type. Possible values: + "none", "ddc", "cdc", "reserved". + +What: /sys/class/nvme/nvmeX/reset_controller +Date: November 2015 +KernelVersion: 4.5 +Contact: Christoph Hellwig <[email protected]> +Description: + Write-only. Writing any value triggers a synchronous + controller reset. + +What: /sys/class/nvme/nvmeX/rescan_controller +Date: April 2016 +KernelVersion: 4.7 +Contact: Keith Busch <[email protected]> +Description: + Write-only. Writing any value triggers a namespace rescan + on this controller. + +What: /sys/class/nvme/nvmeX/transport +What: /sys/class/nvme/nvmeX/subsysnqn +What: /sys/class/nvme/nvmeX/address +What: /sys/class/nvme/nvmeX/delete_controller +What: /sys/class/nvme/nvmeX/reconnect_delay +What: /sys/class/nvme/nvmeX/ctrl_loss_tmo +Date: June 2016 +KernelVersion: 4.8 +Contact: Ming Lin <[email protected]> +Description: + Fabrics controller attributes added with NVMe-oF support. + + transport: Shows the transport type string. Possible values: + "pcie", "tcp", "rdma", "fc", "loop". + + subsysnqn: Shows the NVMe Qualified Name (NQN) of the + subsystem this controller belongs to. + + address: Shows the transport-specific address string. Only + available for fabrics controllers. + + delete_controller: Write-only. Triggers deletion of this + fabrics controller. + + reconnect_delay: Shows or sets the reconnect delay in + seconds. Reading returns the delay value, or "off" if + disabled. + + ctrl_loss_tmo: Shows or sets the controller loss timeout in + seconds. Reading returns the timeout value, or "off" if + infinite reconnects are allowed. Writing a negative value + disables the timeout. + +What: /sys/class/nvme/nvmeX/hostnqn +What: /sys/class/nvme/nvmeX/hostid +Date: February 2020 +KernelVersion: 5.7 +Contact: Sagi Grimberg <[email protected]> +Description: + hostnqn: Shows the host NQN used by this fabrics controller. + + hostid: Shows the host identifier (UUID format) used by this + fabrics controller. + + Only available for fabrics controllers. + +What: /sys/class/nvme/nvmeX/fast_io_fail_tmo +Date: November 2020 +KernelVersion: 5.11 +Contact: Victor Gladkov <[email protected]> +Description: + Shows or sets the fast I/O fail timeout in seconds. Reading + returns the timeout value, or "off" if disabled. Writing a + negative value disables the fast I/O fail. Only available + for fabrics controllers. + +What: /sys/class/nvme/nvmeX/kato +Date: April 2021 +KernelVersion: 5.13 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the Keep Alive Timeout value in milliseconds for + this controller. + +What: /sys/class/nvme/nvmeX/cmb +Date: October 2016 +KernelVersion: 4.9 +Contact: Stephen Bates <[email protected]> +Description: + Shows the Controller Memory Buffer (CMB) register values + in format "cmbloc : 0x%08x\ncmbsz : 0x%08x\n". Only + visible when the controller has a CMB (cmbsz != 0). + PCI transport only. + +What: /sys/class/nvme/nvmeX/cmbloc +What: /sys/class/nvme/nvmeX/cmbsz +What: /sys/class/nvme/nvmeX/hmb +Date: July 2021 +KernelVersion: 5.15 +Contact: Keith Busch <[email protected]> +Description: + cmbloc: Shows the CMBLOC register value. + + cmbsz: Shows the CMBSZ register value. + + cmbloc and cmbsz are only visible when the controller has + a CMB. PCI transport only. + + hmb: Shows or sets whether the Host Memory Buffer (HMB) is + enabled. Reading returns 1 (enabled) or 0 (disabled). + Writing 1 enables HMB; writing 0 disables it. Only + visible when the controller supports HMB (hmpre != 0). + PCI transport only. + +What: /sys/class/nvme/nvmeX/state +Date: November 2016 +KernelVersion: 4.11 +Contact: Sagi Grimberg <[email protected]> +Description: + Shows the current state of the controller. Possible values: + "new", "live", "resetting", "connecting", "deleting", + "deleting (no IO)", "dead". + +What: /sys/class/nvme/nvmeX/numa_node +Date: November 2018 +KernelVersion: 5.0 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the NUMA node the controller is attached to. + +What: /sys/class/nvme/nvmeX/queue_count +What: /sys/class/nvme/nvmeX/sqsize +Date: September 2019 +KernelVersion: 5.4 +Contact: James Smart <[email protected]> +Description: + queue_count: Shows the total number of queues (admin + I/O) + for this controller. + + sqsize: Shows the submission queue size for this controller. + +What: /sys/class/nvme/nvmeX/dhchap_secret +What: /sys/class/nvme/nvmeX/dhchap_ctrl_secret +Date: June 2022 +KernelVersion: 6.0 +Contact: Hannes Reinecke <[email protected]> +Description: + dhchap_secret: Shows or sets the host DH-HMAC-CHAP secret + for this controller. Reading returns "none" if not set. + Writing must use the "DHHC-1:" key format and triggers + re-authentication. + + dhchap_ctrl_secret: Shows or sets the controller + DH-HMAC-CHAP secret for bidirectional authentication. + Same format as dhchap_secret. + + Only available when CONFIG_NVME_HOST_AUTH is enabled and + for fabrics controllers. + +What: /sys/class/nvme/nvmeX/tls_key +Date: August 2023 +KernelVersion: 6.7 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the serial of the currently active TLS PSK as hex. + Returns empty if no TLS key is active. Only available for + TCP controllers with TLS or secure concatenation enabled + (CONFIG_NVME_TCP_TLS). + +What: /sys/class/nvme/nvmeX/tls_configured_key +Date: July 2024 +KernelVersion: 6.12 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the serial of the configured TLS key. Writing 0 + triggers a PSK reauthentication (REPLACETLSPSK) with + the target. After reauthentication the returned serial + will be the new key. Only available for TCP controllers + with secure concatenation enabled (CONFIG_NVME_TCP_TLS). + +What: /sys/class/nvme/nvmeX/tls_keyring +Date: July 2024 +KernelVersion: 6.12 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the TLS keyring description. Only available for TCP + controllers with a keyring configured (CONFIG_NVME_TCP_TLS). + +What: /sys/class/nvme/nvmeX/tls_mode +Date: April 2026 +KernelVersion: 7.1 +Contact: Daniel Wagner <[email protected]> +Description: + Shows the TLS mode: "tls" for direct TLS or "concat" for + secure concatenation. Only available for TCP controllers + with TLS or secure concatenation enabled + (CONFIG_NVME_TCP_TLS). + +What: /sys/class/nvme/nvmeX/passthru_err_log_enabled +Date: January 2024 +KernelVersion: 6.8 +Contact: Alan Adamson <[email protected]> +Description: + Shows or sets whether admin passthrough error logging is + enabled for this controller. Reading returns "on" or "off". + Writing accepts a boolean value. + +What: /sys/class/nvme/nvmeX/quirks Date: November 2025 -KernelVersion: 6.19 -Contact: Linux NVMe mailing list <[email protected]> +KernelVersion: 7.0 +Contact: Maurizio Lombardi <[email protected]> +Description: + Shows the active quirk names for this controller, one per + line. Shows "none" if no quirks are active. + +What: /sys/class/nvme/nvmeX/admin_timeout +What: /sys/class/nvme/nvmeX/io_timeout +Date: May 2026 +KernelVersion: 7.2 +Contact: Maurizio Lombardi <[email protected]> +Description: + admin_timeout: Shows or sets the admin command timeout in + milliseconds. + + io_timeout: Shows or sets the I/O command timeout in + milliseconds. Changes are propagated to all namespace + request queues. + + The value must be nonzero. Only writable after the + controller has been started at least once. + +What: /sys/class/nvme/nvmeX/diag/command_error_count +What: /sys/class/nvme/nvmeX/diag/reset_count +What: /sys/class/nvme/nvmeX/diag/reconnect_count +Date: May 2026 +KernelVersion: 7.2 +Contact: Nilay Shroff <[email protected]> +Description: + Controller diagnostic counters. + + command_error_count: Admin command error counter. + + reset_count: Controller reset counter. + + reconnect_count: Accumulated reconnect counter. Only + available for fabrics controllers. + + All counters can be reset by writing a value. + +What: /sys/block/nvmeXnY/uuid +What: /sys/block/nvmeXnY/eui +What: /sys/block/nvmeXnY/nsid +Date: December 2015 +KernelVersion: 4.5 +Contact: Keith Busch <[email protected]> +Description: + Namespace identification attributes. + + uuid: Shows the UUID for this namespace. Falls back to + showing the NGUID for backward compatibility. Hidden if + both are all zeros. + + eui: Shows the IEEE Extended Unique Identifier (EUI-64). + Hidden if all zeros. + + nsid: Shows the namespace identifier (NSID). + +What: /sys/block/nvmeXnY/wwid +Date: February 2016 +KernelVersion: 4.6 +Contact: Keith Busch <[email protected]> Description: - The file is avaliable when using a secure concatanation - connection to a NVMe target. Reading the file will return - the serial of the currently negotiated key. + Shows the World Wide Identifier for this namespace. The + format depends on available identifiers (in priority + order): "uuid.{UUID}", "eui.{NGUID}", "eui.{EUI64}", or + "nvme.{VID}-{SERIAL}-{MODEL}-{NSID}". + +What: /sys/block/nvmeXnY/nguid +Date: June 2017 +KernelVersion: 4.13 +Contact: Johannes Thumshirn <[email protected]> +Description: + Shows the Namespace Globally Unique Identifier (NGUID). + Hidden if the NGUID is all zeros. + +What: /sys/block/nvmeXnY/ana_grpid +What: /sys/block/nvmeXnY/ana_state +Date: May 2018 +KernelVersion: 4.19 +Contact: Christoph Hellwig <[email protected]> +Description: + ana_grpid: Shows the ANA Group ID for this per-path + namespace device. + + ana_state: Shows the ANA state. Possible values: + "optimized", "non-optimized", "inaccessible", + "persistent-loss", "change". + + Only visible on per-path devices (not multipath head) when + the controller supports ANA. Requires CONFIG_NVME_MULTIPATH. - Writing 0 to the file will trigger a PSK reauthentication - (REPLACETLSPSK) with the target. After a reauthentication - the value returned by tls_configured_key will be the new - serial. +What: /sys/block/nvmeXnY/queue_depth +Date: June 2024 +KernelVersion: 6.11 +Contact: Thomas Song <[email protected]> +Description: + Shows the current active I/O count on this path's + controller. Returns empty if iopolicy is not "queue-depth". + Only visible on per-path devices. + Requires CONFIG_NVME_MULTIPATH. + +What: /sys/block/nvmeXnY/numa_nodes +Date: January 2025 +KernelVersion: 6.15 +Contact: Nilay Shroff <[email protected]> +Description: + Shows the NUMA node mask for which this path is the + currently selected path. Returns empty if iopolicy is not + "numa". Only visible on per-path devices. + Requires CONFIG_NVME_MULTIPATH. + +What: /sys/block/nvmeXnY/delayed_removal_secs +Date: May 2025 +KernelVersion: 6.16 +Contact: Nilay Shroff <[email protected]> +Description: + Shows or sets the delayed removal timeout in seconds for + the multipath head device. When nonzero, I/O is queued + instead of failed when all paths are gone, and head removal + is deferred. Only visible on multipath head devices. + Requires CONFIG_NVME_MULTIPATH. + +What: /sys/block/nvmeXnY/csi +What: /sys/block/nvmeXnY/metadata_bytes +What: /sys/block/nvmeXnY/nuse +Date: December 2023 +KernelVersion: 6.8 +Contact: Daniel Wagner <[email protected]> +Description: + csi: Shows the Command Set Identifier for this namespace. + + metadata_bytes: Shows the metadata size in bytes. + + nuse: Shows the Namespace Utilization (NUSE) value. Reading + triggers an Identify Namespace command to refresh the + value (rate-limited to avoid excessive commands). + +What: /sys/block/nvmeXnY/passthru_err_log_enabled +Date: January 2024 +KernelVersion: 6.8 +Contact: Alan Adamson <[email protected]> +Description: + Shows or sets whether I/O passthrough error logging is + enabled for this namespace. Reading returns "on" or "off". + Writing accepts a boolean value. + +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 <[email protected]> +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. + +What: /sys/class/nvme-subsystem/nvme-subsysX/model +What: /sys/class/nvme-subsystem/nvme-subsysX/serial +What: /sys/class/nvme-subsystem/nvme-subsysX/firmware_rev +What: /sys/class/nvme-subsystem/nvme-subsysX/subsysnqn +Date: November 2017 +KernelVersion: 4.15 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the model, serial number, firmware revision, or NQN + of the NVMe subsystem. + +What: /sys/class/nvme-subsystem/nvme-subsysX/iopolicy +Date: February 2019 +KernelVersion: 5.1 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows or sets the multipath I/O path selection policy for + this subsystem. Accepted values: "numa", "round-robin", + "queue-depth". Changing the policy clears all current path + selections. Only available when CONFIG_NVME_MULTIPATH is + enabled. + +What: /sys/class/nvme-subsystem/nvme-subsysX/subsystype +Date: September 2021 +KernelVersion: 5.16 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows the subsystem type. Possible values: "discovery", + "nvm", "reserved".
Signature · 1 line
2.43.7
Re: [PATCH v2 1/3] nvme: add ABI documentation for host sysfs interfaces
Quoted 21 lines · Guixin Liu
Documentation/ABI/testing/sysfs-nvme +21
-0+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<[email protected]> +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. +
Documentation/ABI/testing/sysfs-nvme line 414
Quoted 10 lines
Documentation/ABI/testing/sysfs-nvme +10
-0+ 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
Re: [PATCH v2 1/3] nvme: add ABI documentation for host sysfs interfaces
Quoted 77 lines · Nilay Shroff
Quoted 21 lines · Guixin Liu
Documentation/ABI/testing/sysfs-nvme +21
-0+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<[email protected]> +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. +Documentation/ABI/testing/sysfs-nvme line 414
Quoted 10 lines
Documentation/ABI/testing/sysfs-nvme +10
-0+ 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_countWhat:/sys/block/nvmeXnY/diag/command_error_countDescription:
Namespace diagnostic counters for non-multipath configurations (whenCONFIG_NVME_MULTIPATHis 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_countWhat:/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_countDescription:
Namespace diagnostic counters for multipath configurations (whenCONFIG_NVME_MULTIPATHis 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.
Quoted 9 lines
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.
Quoted 7 lines
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
Quoted 4 lines
And yes thanks for documenting all this!
--Nilay
Re: [PATCH v2 1/3] nvme: add ABI documentation for host sysfs interfaces
In reply to Guixin LiuQuoted 19 lines · Guixin Liu
Add
Documentation/ABI/testing/sysfs-nvmedocumenting all NVMe host sysfs attributes, covering controller attributes under/sys/class/nvme/nvmeX/, namespace attributes under/sys/block/nvmeXnY/, and subsystem attributes under/sys/class/nvme-subsystem/nvme-subsysX/.Each entry has been traced to its original introducing commit to provide accurate Date, KernelVersion, and Contact information.
Signed-off-by Guixin Liu <[email protected]>---
v1->v2:
- Group all TLS attributes together (movetls_keyandtls_modenext totls_configured_keyandtls_keyring).
- Reorganize the file by device class (controller, namespace, subsystem), keeping related attributes grouped within each class.
- Split the combinedpassthru_err_log_enabledentry into separate controller and namespace entries.
Quoted 3 lines
Documentation/ABI/testing/sysfs-nvme | 450 ++++++++++++++++++++++++++- 1 file changed, 440 insertions(+), 10 deletions(-)
Cheers,
Hannes
Signature · 4 lines
Dr. Hannes Reinecke Kernel Storage Architect [email protected] +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
PATCH v2 2/3 nvmet: add ABI documentation for target configfs interfaces
In reply to Guixin LiuAdd Documentation/ABI/testing/configfs-nvmet documenting all NVMe target configfs attributes, covering port attributes, subsystem attributes, namespace attributes, host authentication, passthrough mode, and ANA configuration.
Each entry has been traced to its original introducing commit to provide accurate Date, KernelVersion, and Contact information.
---v1->v2:
- Group attributes by object type (ports, subsystems, hosts).
- Merge dhchap_dhgroup into the DH-HMAC-CHAP host authentication entry.
- Split the combined ANA and PI-enable entries into separate port and subsystem entries.
Documentation/ABI/testing/configfs-nvmet | 352 +++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 Documentation/ABI/testing/configfs-nvmet
Documentation/ABI/testing/configfs-nvmet new file +352 -0
@@ -0,0 +1,352 @@ +What: /config/nvmet/ports/N/addr_adrfam +What: /config/nvmet/ports/N/addr_portid +What: /config/nvmet/ports/N/addr_traddr +What: /config/nvmet/ports/N/addr_trsvcid +What: /config/nvmet/ports/N/addr_trtype +What: /config/nvmet/ports/N/addr_treq +Date: June 2016 +KernelVersion: 4.8 +Contact: Christoph Hellwig <[email protected]> +Description: + Address attributes for an NVMe-oF target port. + + addr_adrfam: Shows or sets the address family. Accepted + values: "pcie", "ipv4", "ipv6", "ib", "fc", "pci", "loop". + + addr_portid: Shows or sets the port identifier (u16). + + addr_traddr: Shows or sets the transport address string. + + addr_trsvcid: Shows or sets the transport service identifier. + + addr_trtype: Shows or sets the transport type. Accepted + values: "rdma", "fc", "tcp", "pci", "loop". Also + initializes default TSAS values. + + addr_treq: Shows or sets the transport security requirements. + Accepted values: "not specified", "required", + "not required". For TCP with TLS1.3, "not specified" is + rejected. + + All attributes require the port to be disabled before + modification. + +What: /config/nvmet/ports/N/referrals/NAME/addr_adrfam +What: /config/nvmet/ports/N/referrals/NAME/addr_portid +What: /config/nvmet/ports/N/referrals/NAME/addr_traddr +What: /config/nvmet/ports/N/referrals/NAME/addr_trsvcid +What: /config/nvmet/ports/N/referrals/NAME/addr_trtype +What: /config/nvmet/ports/N/referrals/NAME/addr_treq +What: /config/nvmet/ports/N/referrals/NAME/enable +Date: June 2016 +KernelVersion: 4.8 +Contact: Christoph Hellwig <[email protected]> +Description: + Address attributes and enable control for a referral entry + under a port. The addr_* attributes have the same semantics + as the corresponding port-level attributes. The enable + attribute shows or sets whether this referral is enabled + (boolean). + +What: /config/nvmet/ports/N/param_inline_data_size +Date: June 2018 +KernelVersion: 4.19 +Contact: Steve Wise <[email protected]> +Description: + Shows or sets the inline data size for this port. Default + is -1 which lets the transport choose. The port must be + disabled before modification. + +What: /config/nvmet/ports/N/ana_groups/ID/ana_state +Date: June 2018 +KernelVersion: 4.19 +Contact: Christoph Hellwig <[email protected]> +Description: + Shows or sets the ANA (Asymmetric Namespace Access) state + for this group on this port. Accepted values: "optimized", + "non-optimized", "inaccessible", "persistent-loss", + "change". Changes trigger an ANA change event. + +What: /config/nvmet/ports/N/param_pi_enable +Date: May 2020 +KernelVersion: 5.8 +Contact: Israel Rukshin <[email protected]> +Description: + Shows or sets whether protection information (PI) is + enabled/supported for this port. Accepts boolean value. + Only available when CONFIG_BLK_DEV_INTEGRITY is enabled. + The port must be disabled before modification. + +What: /config/nvmet/ports/N/addr_tsas +Date: August 2023 +KernelVersion: 6.7 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows or sets the transport-specific address subtype. For + TCP transport, accepted values: "none", "tls1.3" (requires + CONFIG_NVME_TARGET_TCP_TLS). For RDMA transport, shows the + QP type: "connected" or "datagram". The port must be + disabled before modification. + +What: /config/nvmet/ports/N/param_max_queue_size +Date: January 2024 +KernelVersion: 6.9 +Contact: Max Gurtovoy <[email protected]> +Description: + Shows or sets the maximum queue size for this port. Default + is -1 which lets the transport choose. The port must be + disabled before modification. + +What: /config/nvmet/ports/N/param_mdts +Date: April 2026 +KernelVersion: 7.1 +Contact: Aurelien Aptel <[email protected]> +Description: + Shows or sets the maximum data transfer size for this port. + Default is -1 which lets the transport choose. The port + must be disabled before modification. + +What: /config/nvmet/subsystems/NAME/attr_allow_any_host +Date: June 2016 +KernelVersion: 4.8 +Contact: Christoph Hellwig <[email protected]> +Description: + Shows or sets whether any host is allowed to connect. + Accepts boolean value. Cannot be set to 1 if explicit + hosts are linked in the allowed_hosts/ directory. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/device_path +What: /config/nvmet/subsystems/NAME/namespaces/NSID/device_nguid +What: /config/nvmet/subsystems/NAME/namespaces/NSID/enable +Date: June 2016 +KernelVersion: 4.8 +Contact: Christoph Hellwig <[email protected]> +Description: + Namespace attributes added with the initial NVMe target. + + device_path: Shows or sets the backend block device path. + The namespace must be disabled before modification. + + device_nguid: Shows or sets the NGUID (128-bit identifier). + Accepts 32 hex digits with optional "-" or ":" separators. + The namespace must be disabled before modification. + + enable: Shows or sets whether this namespace is enabled + (boolean). + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/device_uuid +Date: June 2017 +KernelVersion: 4.13 +Contact: Johannes Thumshirn <[email protected]> +Description: + Shows or sets the UUID for this namespace. The namespace + must be disabled before modification. + +What: /config/nvmet/subsystems/NAME/attr_version +What: /config/nvmet/subsystems/NAME/attr_serial +Date: July 2017 +KernelVersion: 4.13 +Contact: Johannes Thumshirn <[email protected]> +Description: + attr_version: Shows or sets the NVMe version reported by + this subsystem. Format: "major.minor" or + "major.minor.tertiary". Cannot be changed after the + subsystem has been discovered. + + attr_serial: Shows or sets the serial number. Must be a + 1-20 byte ASCII string (characters 0x20-0x7e). Cannot be + changed after the subsystem has been discovered. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/ana_grpid +Date: June 2018 +KernelVersion: 4.19 +Contact: Christoph Hellwig <[email protected]> +Description: + Shows or sets the ANA (Asymmetric Namespace Access) Group + ID for this namespace. Must be between 1 and 128. Changing + triggers an ANA event notification. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/buffered_io +Date: June 2018 +KernelVersion: 4.19 +Contact: Chaitanya Kulkarni <[email protected]> +Description: + Shows or sets whether buffered I/O is used for this + namespace. Accepts boolean value. The namespace must be + disabled before modification. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/p2pmem +Date: October 2018 +KernelVersion: 4.20 +Contact: Logan Gunthorpe <[email protected]> +Description: + Shows or sets the P2P DMA memory device for this namespace. + Accepts a PCI device BDF, "auto", or "none". The namespace + must be disabled before modification. Only available when + CONFIG_PCI_P2PDMA is enabled. + +What: /config/nvmet/subsystems/NAME/attr_cntlid_min +What: /config/nvmet/subsystems/NAME/attr_cntlid_max +Date: January 2020 +KernelVersion: 5.7 +Contact: Chaitanya Kulkarni <[email protected]> +Description: + attr_cntlid_min: Shows or sets the minimum controller ID + (u16). Must be nonzero and not greater than attr_cntlid_max. + + attr_cntlid_max: Shows or sets the maximum controller ID + (u16). Must be nonzero and not less than attr_cntlid_min. + +What: /config/nvmet/subsystems/NAME/attr_model +Date: January 2020 +KernelVersion: 5.7 +Contact: Mark Ruijter <[email protected]> +Description: + Shows or sets the model number for this subsystem. Must + be a 1-40 byte ASCII string (characters 0x20-0x7e). + Cannot be changed after the subsystem has been discovered. + +What: /config/nvmet/subsystems/NAME/attr_pi_enable +Date: May 2020 +KernelVersion: 5.8 +Contact: Israel Rukshin <[email protected]> +Description: + Shows or sets whether protection information (PI) is + enabled/supported for this subsystem. Accepts boolean + value. Only available when CONFIG_BLK_DEV_INTEGRITY is + enabled. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/revalidate_size +Date: May 2020 +KernelVersion: 5.8 +Contact: Chaitanya Kulkarni <[email protected]> +Description: + Write-only. Writing 1 triggers namespace size revalidation. + If the size has changed, a namespace changed AEN is sent. + The namespace must be enabled. + +What: /config/nvmet/subsystems/NAME/passthru/device_path +What: /config/nvmet/subsystems/NAME/passthru/enable +Date: July 2020 +KernelVersion: 5.9 +Contact: Logan Gunthorpe <[email protected]> +Description: + Passthrough mode attributes. + + device_path: Shows or sets the NVMe controller character + device path (e.g., /dev/nvme0). Cannot be changed while + the passthrough controller is active. + + enable: Shows or sets whether passthrough mode is enabled + (boolean). + + Only available when CONFIG_NVME_TARGET_PASSTHRU is enabled. + +What: /config/nvmet/subsystems/NAME/passthru/admin_timeout +What: /config/nvmet/subsystems/NAME/passthru/io_timeout +Date: November 2020 +KernelVersion: 5.11 +Contact: Chaitanya Kulkarni <[email protected]> +Description: + admin_timeout: Shows or sets the admin command timeout for + passthrough mode, in jiffies. + + io_timeout: Shows or sets the I/O command timeout for + passthrough mode, in jiffies. + + Only available when CONFIG_NVME_TARGET_PASSTHRU is enabled. + +What: /config/nvmet/subsystems/NAME/passthru/clear_ids +Date: June 2022 +KernelVersion: 5.19 +Contact: Alan Adamson <[email protected]> +Description: + Shows or sets whether to clear identify data IDs in + passthrough mode. Only available when + CONFIG_NVME_TARGET_PASSTHRU is enabled. + +What: /config/nvmet/subsystems/NAME/attr_qid_max +Date: August 2022 +KernelVersion: 6.1 +Contact: Daniel Wagner <[email protected]> +Description: + Shows or sets the maximum queue ID (number of I/O queues, + u16). Must be between 1 and 128. Changing this value + forces reconnection of all connected controllers. + +What: /config/nvmet/subsystems/NAME/attr_ieee_oui +Date: November 2022 +KernelVersion: 6.2 +Contact: Aleksandr Miloserdov <[email protected]> +Description: + Shows or sets the IEEE OUI for this subsystem. Displayed + in "0x%06x" format. Must be a 24-bit value. Cannot be + changed after the subsystem has been discovered. + +What: /config/nvmet/subsystems/NAME/attr_firmware +Date: November 2022 +KernelVersion: 6.2 +Contact: Aleksandr Miloserdov <[email protected]> +Description: + Shows or sets the firmware revision string for this + subsystem. Must be a 1-8 byte ASCII string (characters + 0x20-0x7e). Cannot be changed after the subsystem has + been discovered. + +What: /config/nvmet/subsystems/NAME/namespaces/NSID/resv_enable +Date: November 2024 +KernelVersion: 6.13 +Contact: Guixin Liu <[email protected]> +Description: + Shows or sets whether persistent reservation support is + enabled for this namespace. Accepts boolean value. The + namespace must be disabled before modification. + +What: /config/nvmet/subsystems/NAME/attr_vendor_id +What: /config/nvmet/subsystems/NAME/attr_subsys_vendor_id +Date: January 2025 +KernelVersion: 6.14 +Contact: Damien Le Moal <[email protected]> +Description: + attr_vendor_id: Shows or sets the PCI vendor ID reported + by this subsystem. Displayed in "0x%x" format. + + attr_subsys_vendor_id: Shows or sets the PCI subsystem + vendor ID. Displayed in "0x%x" format. + +What: /config/nvmet/hosts/HOSTNQN/dhchap_key +What: /config/nvmet/hosts/HOSTNQN/dhchap_ctrl_key +What: /config/nvmet/hosts/HOSTNQN/dhchap_hash +What: /config/nvmet/hosts/HOSTNQN/dhchap_dhgroup +Date: June 2022 +KernelVersion: 6.0 +Contact: Hannes Reinecke <[email protected]> +Description: + DH-HMAC-CHAP authentication attributes. + + dhchap_key: Shows or sets the host secret key. Accepts a + key string in "DHHC-1:" format. + + dhchap_ctrl_key: Shows or sets the controller secret key + for bidirectional authentication. Same format as dhchap_key. + + dhchap_hash: Shows or sets the HMAC hash algorithm. + Accepted values: "hmac(sha256)", "hmac(sha384)", + "hmac(sha512)". + + dhchap_dhgroup: Shows or sets the Diffie-Hellman group for + DH-HMAC-CHAP key exchange. Accepted values: "null", + "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144". + Non-null groups require the corresponding KPP crypto + algorithm to be available. + + Only available when CONFIG_NVME_TARGET_AUTH is enabled. + +What: /config/nvmet/discovery_nqn +Date: April 2024 +KernelVersion: 6.9 +Contact: Hannes Reinecke <[email protected]> +Description: + Shows or sets the NQN of the discovery subsystem. The + value must be unique and not duplicate any existing + subsystem name.
Signature · 1 line
2.43.7
Re: [PATCH v2 2/3] nvmet: add ABI documentation for target configfs interfaces
Quoted 16 lines · Guixin Liu
Add
Documentation/ABI/testing/configfs-nvmetdocumenting all NVMe target configfs attributes, covering port attributes, subsystem attributes, namespace attributes, host authentication, passthrough mode, and ANA configuration.Each entry has been traced to its original introducing commit to provide accurate Date, KernelVersion, and Contact information.
Signed-off-by Guixin Liu <[email protected]>---
v1->v2:
- Group attributes by object type (ports, subsystems, hosts).
- Mergedhchap_dhgroupinto the DH-HMAC-CHAP host authentication entry.
- Split the combined ANA and PI-enable entries into separate port and subsystem entries.
Quoted 4 lines
Documentation/ABI/testing/configfs-nvmet | 352 +++++++++++++++++++++++ 1 file changed, 352 insertions(+)create mode 100644
Documentation/ABI/testing/configfs-nvmet
Cheers,
Hannes
Signature · 4 lines
Dr. Hannes Reinecke Kernel Storage Architect [email protected] +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
PATCH v2 3/3 MAINTAINERS: add missing NVMe documentation files
In reply to Guixin LiuAdd documentation file entries that were missing from the NVM EXPRESS DRIVER and NVM EXPRESS TARGET DRIVER sections, so patches touching these files are properly routed to the NVMe mailing list and maintainers.
---v1->v2: Add Reviewed-by tag from Hannes Reinecke, thanks.
MAINTAINERS | 4 ++++ 1 file changed, 4 insertions(+)
MAINTAINERS +4 -0
@@ -19367,6 +19367,9 @@ L: [email protected] S: Supported W: http://git.infradead.org/nvme.git T: git git://git.infradead.org/nvme.git +F: Documentation/ABI/testing/sysfs-nvme +F: Documentation/admin-guide/nvme-multipath.rst +F: Documentation/fault-injection/nvme-fault-injection.rst F: Documentation/nvme/ F: drivers/nvme/common/ F: drivers/nvme/host/
@@ -19409,6 +19412,7 @@ L: [email protected] S: Supported W: http://git.infradead.org/nvme.git T: git git://git.infradead.org/nvme.git +F: Documentation/ABI/testing/configfs-nvmet F: drivers/nvme/target/ NVMEM FRAMEWORK
Signature · 1 line
2.43.7