mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-08-30 14:33:24 -04:00
Code Issues Packages Projects Releases Wiki Activity

nvme: add ABI documentation for host sysfs interfaces

Browse Source 
Add Documentation/ABI/stable/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.

Reviewed-by: Hannes Reinecke <hare@kernel.org>
Reviewed-by: Nilay Shroff <nilay@linux.ibm.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Reviewed-by: Daniel Wagner <dwagner@suse.de>
Signed-off-by: Guixin Liu <kanie@linux.alibaba.com>
Signed-off-by: Keith Busch <kbusch@kernel.org>
This commit is contained in:
Guixin Liu
2026-07-07 20:12:25 +08:00
committed by Keith Busch
parent 1511516478
commit 1c4635cf4d
2 changed files with 453 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
Documentation/ABI/stable/sysfs-nvme Normal file
View File

@@ -0,0 +1,453 @@
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 <kbusch@kernel.org>
Description:
Shows the model, serial number, or firmware revision string
of the NVMe controller, as reported in the Identify
Controller data structure.
What: /sys/class/nvme/nvmeX/cntlid
Date: February 2016
KernelVersion: 4.6
Contact: Ming Lin <ming.l@ssi.samsung.com>
Description:
Shows the controller identifier assigned by the NVMe
subsystem.
What: /sys/class/nvme/nvmeX/cntrltype
What: /sys/class/nvme/nvmeX/dctype
Date: February 2022
KernelVersion: 5.18
Contact: Martin Belanger <martin.belanger@dell.com>
Description:
cntrltype: Shows the controller type. Possible values: "io",
"discovery", "admin", "reserved".
dctype: Shows the discovery controller type. Possible values:
"none", "ddc", "cdc", "reserved".
What: /sys/class/nvme/nvmeX/reset_controller
Date: November 2015
KernelVersion: 4.5
Contact: Christoph Hellwig <hch@lst.de>
Description:
Write-only. Writing any value triggers a synchronous
controller reset.
What: /sys/class/nvme/nvmeX/rescan_controller
Date: April 2016
KernelVersion: 4.7
Contact: Keith Busch <kbusch@kernel.org>
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 <ming.l@ssi.samsung.com>
Description:
Fabrics controller attributes added with NVMe-oF support.
transport: Shows the transport type string. Possible values:
"pcie", "tcp", "rdma", "fc", "loop".
subsysnqn: Shows the NVMe Qualified Name (NQN) of the
subsystem this controller belongs to.
address: Shows the transport-specific address string. Only
available for fabrics controllers.
delete_controller: Write-only. Triggers deletion of this
fabrics controller.
reconnect_delay: Shows or sets the reconnect delay in
seconds. Reading returns the delay value, or "off" if
disabled.
ctrl_loss_tmo: Shows or sets the controller loss timeout in
seconds. Reading returns the timeout value, or "off" if
infinite reconnects are allowed. Writing a negative value
disables the timeout.
What: /sys/class/nvme/nvmeX/hostnqn
What: /sys/class/nvme/nvmeX/hostid
Date: February 2020
KernelVersion: 5.7
Contact: Sagi Grimberg <sagi@grimberg.me>
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 <Victor.Gladkov@kioxia.com>
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 <hare@suse.de>
Description:
Shows the Keep Alive Timeout value in milliseconds for
this controller.
What: /sys/class/nvme/nvmeX/cmb
Date: October 2016
KernelVersion: 4.9
Contact: Stephen Bates <sbates@raithlin.com>
Description:
Shows the Controller Memory Buffer (CMB) register values
in format "cmbloc : 0x%08x\ncmbsz : 0x%08x\n". Only
visible when the controller has a CMB (cmbsz != 0).
PCI transport only.
What: /sys/class/nvme/nvmeX/cmbloc
What: /sys/class/nvme/nvmeX/cmbsz
What: /sys/class/nvme/nvmeX/hmb
Date: July 2021
KernelVersion: 5.15
Contact: Keith Busch <kbusch@kernel.org>
Description:
cmbloc: Shows the CMBLOC register value.
cmbsz: Shows the CMBSZ register value.
cmbloc and cmbsz are only visible when the controller has
a CMB. PCI transport only.
hmb: Shows or sets whether the Host Memory Buffer (HMB) is
enabled. Reading returns 1 (enabled) or 0 (disabled).
Writing 1 enables HMB; writing 0 disables it. Only
visible when the controller supports HMB (hmpre != 0).
PCI transport only.
What: /sys/class/nvme/nvmeX/state
Date: November 2016
KernelVersion: 4.11
Contact: Sagi Grimberg <sagi@grimberg.me>
Description:
Shows the current state of the controller. Possible values:
"new", "live", "resetting", "connecting", "deleting",
"deleting (no IO)", "dead".
What: /sys/class/nvme/nvmeX/numa_node
Date: November 2018
KernelVersion: 5.0
Contact: Hannes Reinecke <hare@suse.de>
Description:
Shows the NUMA node the controller is attached to.
What: /sys/class/nvme/nvmeX/queue_count
What: /sys/class/nvme/nvmeX/sqsize
Date: September 2019
KernelVersion: 5.4
Contact: James Smart <jsmart2021@gmail.com>
Description:
queue_count: Shows the total number of queues (admin + I/O)
for this controller.
sqsize: Shows the submission queue size for this controller.
What: /sys/class/nvme/nvmeX/dhchap_secret
What: /sys/class/nvme/nvmeX/dhchap_ctrl_secret
Date: June 2022
KernelVersion: 6.0
Contact: Hannes Reinecke <hare@suse.de>
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 <hare@suse.de>
Description:
Shows the serial of the currently active TLS PSK as hex.
Returns empty if no TLS key is active. Only available for
TCP controllers with TLS or secure concatenation enabled
(CONFIG_NVME_TCP_TLS).
What: /sys/class/nvme/nvmeX/tls_configured_key
Date: July 2024
KernelVersion: 6.12
Contact: Hannes Reinecke <hare@kernel.org>
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 <hare@kernel.org>
Description:
Shows the TLS keyring description. Only available for TCP
controllers with a keyring configured (CONFIG_NVME_TCP_TLS).
What: /sys/class/nvme/nvmeX/tls_mode
Date: April 2026
KernelVersion: 7.1
Contact: Daniel Wagner <wagi@kernel.org>
Description:
Shows the TLS mode: "tls" for direct TLS or "concat" for
secure concatenation. Only available for TCP controllers
with TLS or secure concatenation enabled
(CONFIG_NVME_TCP_TLS).
What: /sys/class/nvme/nvmeX/passthru_err_log_enabled
Date: January 2024
KernelVersion: 6.8
Contact: Alan Adamson <alan.adamson@oracle.com>
Description:
Shows or sets whether admin passthrough error logging is
enabled for this controller. Reading returns "on" or "off".
Writing accepts a boolean value.
What: /sys/class/nvme/nvmeX/quirks
Date: November 2025
KernelVersion: 7.0
Contact: Maurizio Lombardi <mlombard@redhat.com>
Description:
Shows the active quirk names for this controller, one per
line. Shows "none" if no quirks are active.
What: /sys/class/nvme/nvmeX/admin_timeout
What: /sys/class/nvme/nvmeX/io_timeout
Date: May 2026
KernelVersion: 7.2
Contact: Maurizio Lombardi <mlombard@redhat.com>
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/block/nvmeXnY/uuid
What: /sys/block/nvmeXnY/eui
What: /sys/block/nvmeXnY/nsid
Date: December 2015
KernelVersion: 4.5
Contact: Keith Busch <kbusch@kernel.org>
Description:
Namespace identification attributes.
uuid: Shows the UUID for this namespace. Falls back to
showing the NGUID for backward compatibility. Hidden if
both are all zeros.
eui: Shows the IEEE Extended Unique Identifier (EUI-64).
Hidden if all zeros.
nsid: Shows the namespace identifier (NSID).
What: /sys/block/nvmeXnY/wwid
Date: February 2016
KernelVersion: 4.6
Contact: Keith Busch <kbusch@kernel.org>
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/block/nvmeXnY/nguid
Date: June 2017
KernelVersion: 4.13
Contact: Johannes Thumshirn <jthumshirn@suse.de>
Description:
Shows the Namespace Globally Unique Identifier (NGUID).
Hidden if the NGUID is all zeros.
What: /sys/block/nvmeXcYnZ/ana_grpid
What: /sys/block/nvmeXcYnZ/ana_state
Date: May 2018
KernelVersion: 4.19
Contact: Christoph Hellwig <hch@lst.de>
Description:
ana_grpid: Shows the ANA Group ID for this namespace
path device.
ana_state: Shows the ANA state. Possible values:
"optimized", "non-optimized", "inaccessible",
"persistent-loss", "change".
Only visible when the controller supports ANA.
Requires CONFIG_NVME_MULTIPATH.
What: /sys/block/nvmeXcYnZ/queue_depth
Date: June 2024
KernelVersion: 6.11
Contact: Thomas Song <tsong@purestorage.com>
Description:
Shows the current active I/O count on this path's
controller. Returns empty if iopolicy is not "queue-depth".
Requires CONFIG_NVME_MULTIPATH.
What: /sys/block/nvmeXcYnZ/numa_nodes
Date: January 2025
KernelVersion: 6.15
Contact: Nilay Shroff <nilay@linux.ibm.com>
Description:
Shows the NUMA node mask for which this path is the
currently selected path. Returns empty if iopolicy is not
"numa". Requires CONFIG_NVME_MULTIPATH.
What: /sys/block/nvmeXnY/delayed_removal_secs
Date: May 2025
KernelVersion: 6.16
Contact: Nilay Shroff <nilay@linux.ibm.com>
Description:
Shows or sets the delayed removal timeout in seconds for
the multipath head device. When nonzero, I/O is queued
instead of failed when all paths are gone, and head removal
is deferred. Only visible on multipath head devices.
Requires CONFIG_NVME_MULTIPATH.
What: /sys/block/nvmeXnY/csi
What: /sys/block/nvmeXnY/metadata_bytes
What: /sys/block/nvmeXnY/nuse
Date: December 2023
KernelVersion: 6.8
Contact: Daniel Wagner <dwagner@suse.de>
Description:
csi: Shows the Command Set Identifier for this namespace.
metadata_bytes: Shows the metadata size in bytes.
nuse: Shows the Namespace Utilization (NUSE) value. Reading
triggers an Identify Namespace command to refresh the
value (rate-limited to avoid excessive commands).
What: /sys/block/nvmeXnY/passthru_err_log_enabled
Date: January 2024
KernelVersion: 6.8
Contact: Alan Adamson <alan.adamson@oracle.com>
Description:
Shows or sets whether I/O passthrough error logging is
enabled for this namespace. Reading returns "on" or "off".
Writing accepts a boolean value.
What: /sys/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 <nilay@linux.ibm.com>
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
Date: May 2026
KernelVersion: 7.2
Contact: Nilay Shroff <nilay@linux.ibm.com>
Description:
Namespace diagnostic counters for non-multipath
configurations (when CONFIG_NVME_MULTIPATH is not
configured).
command_retries_count: I/O command retry counter.
command_error_count: I/O command error counter.
All counters can be reset by writing any value.
What: /sys/block/nvmeXcYnZ/diag/command_retries_count
What: /sys/block/nvmeXcYnZ/diag/command_error_count
What: /sys/block/nvmeXcYnZ/diag/multipath_failover_count
What: /sys/block/nvmeXnY/diag/io_requeue_no_usable_path_count
What: /sys/block/nvmeXnY/diag/io_fail_no_available_path_count
Date: May 2026
KernelVersion: 7.2
Contact: Nilay Shroff <nilay@linux.ibm.com>
Description:
Namespace diagnostic counters for multipath
configurations (when CONFIG_NVME_MULTIPATH is
configured).
command_retries_count: I/O command retry counter.
command_error_count: I/O command error counter.
multipath_failover_count: Multipath failover counter.
io_requeue_no_usable_path_count: Counter of I/Os
requeued because no usable path was available.
io_fail_no_available_path_count: Counter of I/Os
failed because no available path existed.
All counters can be reset by writing any value.
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 <hare@suse.de>
Description:
Shows the model, serial number, firmware revision, or NQN
of the NVMe subsystem.
What: /sys/class/nvme-subsystem/nvme-subsysX/iopolicy
Date: February 2019
KernelVersion: 5.1
Contact: Hannes Reinecke <hare@suse.de>
Description:
Shows or sets the multipath I/O path selection policy for
this subsystem. Accepted values: "numa", "round-robin",
"queue-depth". Changing the policy clears all current path
selections. Only available when CONFIG_NVME_MULTIPATH is
enabled.
What: /sys/class/nvme-subsystem/nvme-subsysX/subsystype
Date: September 2021
KernelVersion: 5.16
Contact: Hannes Reinecke <hare@suse.de>
Description:
Shows the subsystem type. Possible values: "discovery",
"nvm", "reserved".

13
Documentation/ABI/testing/sysfs-nvme
View File

@@ -1,13 +0,0 @@
What: /sys/devices/virtual/nvme-fabrics/ctl/.../tls_configured_key
Date: November 2025
KernelVersion: 6.19
Contact: Linux NVMe mailing list <linux-nvme@lists.infradead.org>
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.
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.