Re: [PATCH 1/3] nvme: add ABI documentation for host sysfs interfaces
Guixin Liu <[email protected]>
| Newsgroups | org.infradead.lists.linux-nvme |
|---|---|
| Message-ID | <[email protected]> |
在 2026/7/2 14:31, Hannes Reinecke 写道: > On 7/2/26 5:48 AM, Guixin Liu wrote: >> 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. >> >> Signed-off-by: Guixin Liu <[email protected]> >> --- >> Documentation/ABI/testing/sysfs-nvme | 444 ++++++++++++++++++++++++++- >> 1 file changed, 434 insertions(+), 10 deletions(-) >> >> diff --git a/Documentation/ABI/testing/sysfs-nvme >> b/Documentation/ABI/testing/sysfs-nvme >> index 499d5f843cd4..079561601acd 100644 >> --- a/Documentation/ABI/testing/sysfs-nvme >> +++ b/Documentation/ABI/testing/sysfs-nvme >> @@ -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). >> + > > 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 > >> +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. > > Otherwise looks good. > > Cheers, > > Hannes