Skip to contentSkip to conversation

nvme: add ABI documentation for sysfs and configfs interfaces

PATCH Superseded Guixin Liu 3 participants 11 messages Jul 2 – Jul 3 NVMe

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Guixin Liu

author
#0 lore raw

cover nvme: add ABI documentation for sysfs and configfs interfaces

The NVMe host sysfs interfaces and target configfs interfaces lack ABI documentation under Documentation/ABI/. This series adds the missing documentation and updates MAINTAINERS accordingly.

Each attribute entry has been traced back to its original introducing commit via git archaeology to provide accurate Date, KernelVersion, and Contact information.

This documentation was created with the assistance of AI (Claude) for git history tracing and document formatting.

Patch 1 adds Documentation/ABI/testing/sysfs-nvme for host sysfs. Patch 2 adds Documentation/ABI/testing/configfs-nvmet for target configfs. Patch 3 adds missing F: entries in MAINTAINERS for NVMe documentation.

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 | 347 ++++++++++++++++++
 Documentation/ABI/testing/sysfs-nvme     | 444 ++++++++++++++++++++++-
 MAINTAINERS                              |   4 +
 3 files changed, 785 insertions(+), 10 deletions(-)
 create mode 100644 Documentation/ABI/testing/configfs-nvmet
Signature · 1 line
2.43.7
author
#1 lore raw

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

---
 Documentation/ABI/testing/sysfs-nvme | 444 ++++++++++++++++++++++++++-
 1 file changed, 434 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-nvme +434 -10
index 499d5f843cd4..079561601acd 100644
@@ -1,13 +1,437 @@
-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/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/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/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/block/nvmeXnY/wwid
+Date:		February 2016
+KernelVersion:	4.6
+Contact:	Keith Busch <[email protected]>
+Description:
+		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/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/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/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/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/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/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.
+
+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-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/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/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/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-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".
+
+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/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/passthru_err_log_enabled
+What:		/sys/block/nvmeXnY/passthru_err_log_enabled
+Date:		January 2024
+KernelVersion:	6.8
+Contact:	Alan Adamson <[email protected]>
+Description:
+		Shows or sets whether passthrough error logging is enabled.
+		Reading returns "on" or "off". Writing accepts a boolean
+		value. The controller-level attribute controls admin
+		passthrough logging; the namespace-level attribute controls
+		I/O passthrough logging.
+
+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/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/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/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/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:
-		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 active quirk names for this controller, one per
+		line. Shows "none" if no quirks are active.
+
+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/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/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.
 
-		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.
+		All counters can be reset by writing a value.
Signature · 1 line
2.43.7
#2 lore raw

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

Quoted 288 lines · Guixin Liu

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.

---
  Documentation/ABI/testing/sysfs-nvme | 444 ++++++++++++++++++++++++++-
  1 file changed, 434 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-nvme +268 -1
index 499d5f843cd4..079561601acd 100644
@@ -1,13 +1,437 @@
-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/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/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/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/block/nvmeXnY/wwid
+Date:		February 2016
+KernelVersion:	4.6
+Contact:	Keith Busch <[email protected]>
+Description:
+		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/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/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/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/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/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/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.
+
+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-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/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/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/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-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".
+
+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/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.
+

Documentation/ABI/testing/sysfs-nvme line 278

Quoted 10 lines
Documentation/ABI/testing/sysfs-nvme +10 -0
+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).
+

Can you keep the TLS attributes together?
That way it's easier to figure out which attributes one need to look at when checking the TLS status.

Quoted 158 lines
Documentation/ABI/testing/sysfs-nvme +151 -5
+What:		/sys/class/nvme/nvmeX/passthru_err_log_enabled
+What:		/sys/block/nvmeXnY/passthru_err_log_enabled
+Date:		January 2024
+KernelVersion:	6.8
+Contact:	Alan Adamson <[email protected]>
+Description:
+		Shows or sets whether passthrough error logging is enabled.
+		Reading returns "on" or "off". Writing accepts a boolean
+		value. The controller-level attribute controls admin
+		passthrough logging; the namespace-level attribute controls
+		I/O passthrough logging.
+
+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/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/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/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/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:
-		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 active quirk names for this controller, one per
+		line. Shows "none" if no quirks are active.
+
+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/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/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.

Documentation/ABI/testing/sysfs-nvme line 437

Quoted 10 lines
Documentation/ABI/testing/sysfs-nvme +5 -4
+
+		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.
 
-		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.
+		All counters can be reset by writing a value.

Otherwise looks good.

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
author
#3 lore raw

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

Quoted 295 lines · Hannes Reinecke
Quoted 294 lines · Guixin Liu

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.

---
  Documentation/ABI/testing/sysfs-nvme | 444 ++++++++++++++++++++++++++-

  1 file changed, 434 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-nvme +274 -1
index 499d5f843cd4..079561601acd 100644
@@ -1,13 +1,437 @@
-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/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/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/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/block/nvmeXnY/wwid
+Date:        February 2016
+KernelVersion:    4.6
+Contact:    Keith Busch <[email protected]>
+Description:
+        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/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/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/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/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/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/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.
+
+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-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/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/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/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-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".
+
+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/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.
Quoted 8 lines

Documentation/ABI/testing/sysfs-nvme line 278

Quoted 4 lines
Documentation/ABI/testing/sysfs-nvme +4 -0
+        Returns empty if no TLS key is active. Only available for
+        TCP controllers with TLS or secure concatenation enabled
+        (CONFIG_NVME_TCP_TLS).
+

Can you keep the TLS attributes together?
That way it's easier to figure out which attributes one need to look at when checking the TLS status.

OK, I just sort them by date, changed in v2, thanks.

Best Regards,
Guixin Liu

Quoted 174 lines
Quoted 163 lines
Documentation/ABI/testing/sysfs-nvme +78 -0
+What: /sys/class/nvme/nvmeX/passthru_err_log_enabled
+What:        /sys/block/nvmeXnY/passthru_err_log_enabled
+Date:        January 2024
+KernelVersion:    6.8
+Contact:    Alan Adamson <[email protected]>
+Description:
+        Shows or sets whether passthrough error logging is enabled.
+        Reading returns "on" or "off". Writing accepts a boolean
+        value. The controller-level attribute controls admin
+        passthrough logging; the namespace-level attribute controls
+        I/O passthrough logging.
+
+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/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/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/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/class/nvme/nvmeX/quirks

  Date:        November 2025

Documentation/ABI/testing/sysfs-nvme +2 -2
-KernelVersion:    6.19
-Contact:    Linux NVMe mailing list <[email protected]>
+KernelVersion:    7.0
+Contact:    Maurizio Lombardi <[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 active quirk names for this controller, one per +        line. Shows "none" if no quirks are active.

Documentation/ABI/testing/sysfs-nvme +73 -0
+
+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/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/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.
Quoted 5 lines

  -        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.
+        All counters can be reset by writing a value.

Otherwise looks good.

Cheers,

Hannes

author
#4 lore raw

PATCH 2/3 nvmet: add ABI documentation for target configfs interfaces

In reply to Guixin Liu

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

---
 Documentation/ABI/testing/configfs-nvmet | 347 +++++++++++++++++++++++
 1 file changed, 347 insertions(+)
 create mode 100644 Documentation/ABI/testing/configfs-nvmet
Documentation/ABI/testing/configfs-nvmet new file +347 -0
new file mode 100644
index 000000000000..728c905310c5
@@ -0,0 +1,347 @@
+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/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/ports/N/ana_groups/ID/ana_state
+What:		/config/nvmet/subsystems/NAME/namespaces/NSID/ana_grpid
+Date:		June 2018
+KernelVersion:	4.19
+Contact:	Christoph Hellwig <[email protected]>
+Description:
+		ANA (Asymmetric Namespace Access) attributes.
+
+		ana_state: Shows or sets the ANA state for this group on
+		this port. Accepted values: "optimized", "non-optimized",
+		"inaccessible", "persistent-loss", "change". Changes
+		trigger an ANA change event.
+
+		ana_grpid: Shows or sets the ANA Group ID for this
+		namespace. Must be between 1 and 128. Changing triggers
+		an ANA event notification.
+
+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/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
+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. Accepts boolean value. Only available
+		when CONFIG_BLK_DEV_INTEGRITY is enabled. The port-level
+		attribute requires the port to be disabled before
+		modification.
+
+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/hosts/HOSTNQN/dhchap_key
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_ctrl_key
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_hash
+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)".
+
+		Only available when CONFIG_NVME_TARGET_AUTH is enabled.
+
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_dhgroup
+Date:		June 2022
+KernelVersion:	6.0
+Contact:	Hannes Reinecke <[email protected]>
+Description:
+		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/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/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/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.
+
+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/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.
Signature · 1 line
2.43.7
#5 lore raw

Re: [PATCH 2/3] nvmet: add ABI documentation for target configfs interfaces

Quoted 271 lines · Guixin Liu

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

---
  Documentation/ABI/testing/configfs-nvmet | 347 +++++++++++++++++++++++
  1 file changed, 347 insertions(+)

create mode 100644 Documentation/ABI/testing/configfs-nvmet

Documentation/ABI/testing/configfs-nvmet new file +251 -0
new file mode 100644
index 000000000000..728c905310c5
@@ -0,0 +1,347 @@
+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/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/ports/N/ana_groups/ID/ana_state
+What:		/config/nvmet/subsystems/NAME/namespaces/NSID/ana_grpid
+Date:		June 2018
+KernelVersion:	4.19
+Contact:	Christoph Hellwig <[email protected]>
+Description:
+		ANA (Asymmetric Namespace Access) attributes.
+
+		ana_state: Shows or sets the ANA state for this group on
+		this port. Accepted values: "optimized", "non-optimized",
+		"inaccessible", "persistent-loss", "change". Changes
+		trigger an ANA change event.
+
+		ana_grpid: Shows or sets the ANA Group ID for this
+		namespace. Must be between 1 and 128. Changing triggers
+		an ANA event notification.
+
+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/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
+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. Accepts boolean value. Only available
+		when CONFIG_BLK_DEV_INTEGRITY is enabled. The port-level
+		attribute requires the port to be disabled before
+		modification.
+
+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/hosts/HOSTNQN/dhchap_key
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_ctrl_key
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_hash
+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)".
+
+		Only available when CONFIG_NVME_TARGET_AUTH is enabled.
+
+What:		/config/nvmet/hosts/HOSTNQN/dhchap_dhgroup
+Date:		June 2022

Documentation/ABI/testing/configfs-nvmet line 261

Quoted 10 lines
Documentation/ABI/testing/configfs-nvmet new file +10 -0
+KernelVersion:	6.0
+Contact:	Hannes Reinecke <[email protected]>
+Description:
+		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.
+

Why is this a separate entry, and not grouped with the other dhchap entries?

And these are 'host' settings. Please keep settings for 'host', 'subsystem', and 'ports' together.

Quoted 76 lines
Documentation/ABI/testing/configfs-nvmet new file +76 -0
+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/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/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.
+
+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

Documentation/ABI/testing/configfs-nvmet line 347

Quoted 10 lines
Documentation/ABI/testing/configfs-nvmet new file +10 -0
+		vendor ID. Displayed in "0x%x" format.
+
+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.

Otherwise looks good.

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
author
#6 lore raw

Re: [PATCH 2/3] nvmet: add ABI documentation for target configfs interfaces

Quoted 286 lines · Hannes Reinecke
Quoted 271 lines · Guixin Liu

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

---
  Documentation/ABI/testing/configfs-nvmet | 347 +++++++++++++++++++++++

  1 file changed, 347 insertions(+)

  create mode 100644 Documentation/ABI/testing/configfs-nvmet

Documentation/ABI/testing/configfs-nvmet new file +251 -0
new file mode 100644
index 000000000000..728c905310c5
@@ -0,0 +1,347 @@
+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/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/ports/N/ana_groups/ID/ana_state
+What: /config/nvmet/subsystems/NAME/namespaces/NSID/ana_grpid
+Date:        June 2018
+KernelVersion:    4.19
+Contact:    Christoph Hellwig <[email protected]>
+Description:
+        ANA (Asymmetric Namespace Access) attributes.
+
+        ana_state: Shows or sets the ANA state for this group on
+        this port. Accepted values: "optimized", "non-optimized",
+        "inaccessible", "persistent-loss", "change". Changes
+        trigger an ANA change event.
+
+        ana_grpid: Shows or sets the ANA Group ID for this
+        namespace. Must be between 1 and 128. Changing triggers
+        an ANA event notification.
+
+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/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
+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. Accepts boolean value. Only available
+        when CONFIG_BLK_DEV_INTEGRITY is enabled. The port-level
+        attribute requires the port to be disabled before
+        modification.
+
+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/hosts/HOSTNQN/dhchap_key
+What:        /config/nvmet/hosts/HOSTNQN/dhchap_ctrl_key
+What:        /config/nvmet/hosts/HOSTNQN/dhchap_hash
+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)".
+
+        Only available when CONFIG_NVME_TARGET_AUTH is enabled.
+
+What:        /config/nvmet/hosts/HOSTNQN/dhchap_dhgroup
+Date:        June 2022

Documentation/ABI/testing/configfs-nvmet line 261

Quoted 10 lines
Documentation/ABI/testing/configfs-nvmet new file +10 -0
+KernelVersion:    6.0
+Contact:    Hannes Reinecke <[email protected]>
+Description:
+        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.
+

Why is this a separate entry, and not grouped with the other dhchap entries?

Quoted 2 lines

And these are 'host' settings. Please keep settings for 'host', 'subsystem', and 'ports' together.

Changed in v2, thanks.

Best Regards,
Guixin Liu

Quoted 92 lines
Quoted 76 lines
Documentation/ABI/testing/configfs-nvmet new file +76 -0
+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/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/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.
+
+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

Documentation/ABI/testing/configfs-nvmet line 347

Quoted 10 lines
Documentation/ABI/testing/configfs-nvmet new file +10 -0
+        vendor ID. Displayed in "0x%x" format.
+
+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.

Otherwise looks good.

Cheers,

Hannes

#7 lore raw

Re: [PATCH 2/3] nvmet: add ABI documentation for target configfs interfaces

In reply to Guixin Liu
Quoted 1 line · Guixin Liu

Add Documentation/ABI/testing/configfs-nvmet documenting all NVMe

As far I am aware, nvmet is actually also used in production systems. Thus it's not just an testing API I think.

Thanks for doing this!

BTW, I agree with Hannes, grouping them together makes it easier to consume. Obviously they can still be sorted by time withing a group if this makes sense.

Cheers,
Daniel

author
#8 lore raw

Re: [PATCH 2/3] nvmet: add ABI documentation for target configfs interfaces

Quoted 5 lines · Daniel Wagner
Quoted 1 line · Guixin Liu

Add Documentation/ABI/testing/configfs-nvmet documenting all NVMe

As far I am aware, nvmet is actually also used in production systems. Thus it's not just an testing API I think.

Quoted 8 lines

Thanks for doing this!

BTW, I agree with Hannes, grouping them together makes it easier to consume. Obviously they can still be sorted by time withing a group if this makes sense.

Cheers,
Daniel

Yes, please see the v2 patch set.

Best Regards,
Guixin Liu

author
#9 lore raw

PATCH 3/3 MAINTAINERS: add missing NVMe documentation files

In reply to Guixin Liu

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

---
 MAINTAINERS | 4 ++++
 1 file changed, 4 insertions(+)
MAINTAINERS +4 -0
index 15011f5752a9..7f8d52f8aab1 100644
@@ -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
Reviewed-by on v1 3/3
#10 lore raw

Re: [PATCH 3/3] MAINTAINERS: add missing NVMe documentation files

Quoted 25 lines · Guixin Liu

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

---
  MAINTAINERS | 4 ++++
  1 file changed, 4 insertions(+)
MAINTAINERS +3 -0
index 15011f5752a9..7f8d52f8aab1 100644
@@ -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/

MAINTAINERS L: [email protected] · line 19418

Quoted 7 lines
MAINTAINERS +1 -0
@@ -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

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