Re: [PATCH 2/3] nvmet: add ABI documentation for target configfs interfaces
Hannes Reinecke <[email protected]>
| Newsgroups | org.infradead.lists.linux-nvme |
|---|---|
| Message-ID | <[email protected]> |
On 7/2/26 5:48 AM, Guixin Liu wrote: > 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. > > Signed-off-by: Guixin Liu <[email protected]> > --- > Documentation/ABI/testing/configfs-nvmet | 347 +++++++++++++++++++++++ > 1 file changed, 347 insertions(+) > create mode 100644 Documentation/ABI/testing/configfs-nvmet > > diff --git a/Documentation/ABI/testing/configfs-nvmet b/Documentation/ABI/testing/configfs-nvmet > new file mode 100644 > index 000000000000..728c905310c5 > --- /dev/null > +++ b/Documentation/ABI/testing/configfs-nvmet > @@ -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. > + 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. > +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. Otherwise looks good. Cheers, Hannes -- 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