libnvmf: NVMe Controller Ownership Registry (V2)

Documentation/meson.build

@@ -114,6 +114,10 @@ adoc_sources = [
     'nvme-predictable-lat-log',
     'nvme-primary-ctrl-caps',
     'nvme-read',
+    'nvme-registry-delete',
+    'nvme-registry-list',
+    'nvme-registry-retrieve',
+    'nvme-registry-update',
     'nvme-reset',
     'nvme-resv-acquire',
     'nvme-resv-notif-log',

Documentation/nvme-disconnect-all.txt

@@ -9,30 +9,70 @@ SYNOPSIS
 --------
 [verse]
 'nvme' [<global-options>] 'disconnect-all'
+			[--transport=<STR> | -r <STR>]
+			[--owner=<NAME> | -O <NAME>]
+			[--force]
 
 DESCRIPTION
 -----------
-Disconnects and removes all existing NVMe over Fabrics controllers.
+Disconnects and removes NVMe over Fabrics controllers.  The default
+behavior is ownership-aware: only controllers with no entry in the
+ownership registry are disconnected.  Controllers registered to an
+orchestrator (e.g. nvme-stas, nbft) are left untouched.
+
+Use --owner to target a specific orchestrator's controllers, or --force
+to disconnect all controllers regardless of ownership.  --force and
+--owner are mutually exclusive.  When --force is used interactively a
+confirmation prompt is shown.
+
+PCIe and apple-nvme controllers are never disconnected regardless of
+the options used.
 
 See the documentation for the nvme-disconnect(1) command for further
 background.
 
 OPTIONS
 -------
+-r <STR>::
+--transport=<STR>::
+	Limit disconnection to controllers using the specified transport
+	(e.g. tcp, rdma, fc).
+
+-O <NAME>::
+--owner=<NAME>::
+	Disconnect only controllers owned by NAME in the registry.
+
+--force::
+	Disconnect all controllers regardless of ownership.  Requires
+	interactive confirmation when stdin is a terminal.
 
 include::global-options.txt[]
 
 EXAMPLES
 --------
-* Disconnect all existing nvme controllers:
+* Disconnect all unowned controllers (safe default):
 +
 ------------
 # nvme disconnect-all
 ------------
 
+* Disconnect all controllers owned by nvme-stas:
++
+------------
+# nvme disconnect-all --owner stas
+------------
+
+* Disconnect all controllers regardless of ownership:
++
+------------
+# nvme disconnect-all --force
+------------
+
 SEE ALSO
 --------
 nvme-disconnect(1)
+nvme-registry-list(1)
+nvme-registry-delete(1)
 
 NVME
 ----

Documentation/nvme-registry-delete.txt

@@ -0,0 +1,50 @@
+nvme-registry-delete(1)
+=======================
+
+NAME
+----
+nvme-registry-delete - Remove a controller's ownership registry entry
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry delete'
+			--device=<DEV> | -d <DEV>
+
+DESCRIPTION
+-----------
+Remove the ownership registry entry for an NVMe-oF controller.  The
+registry entry is the directory /run/nvme/registry/<device>/ and all
+attribute files it contains.
+
+Under normal operation registry entries are removed automatically: a
+udev rule fires on the kernel REMOVE event and deletes the entry.  This
+command is provided for manual cleanup or for orchestrators that want to
+explicitly release ownership before disconnecting.
+
+OPTIONS
+-------
+-d <DEV>::
+--device=<DEV>::
+	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Remove the registry entry for nvme3:
++
+------------
+# nvme registry delete --device nvme3
+------------
+
+SEE ALSO
+--------
+nvme-registry-list(1)
+nvme-registry-retrieve(1)
+nvme-registry-update(1)
+nvme-disconnect-all(1)
+
+NVME
+----
+Part of the nvme-user suite

Documentation/nvme-registry-list.txt

@@ -0,0 +1,52 @@
+nvme-registry-list(1)
+=====================
+
+NAME
+----
+nvme-registry-list - List NVMe-oF controller ownership registry entries
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry list'
+
+DESCRIPTION
+-----------
+List all live entries in the NVMe-oF controller ownership registry.  The
+registry records which orchestrator (e.g. nvme-stas, nbft) owns each
+connected NVMe-oF controller.  It is stored under /run/nvme/registry/ as
+one directory per live controller containing one plain-text file per
+attribute (e.g. /run/nvme/registry/nvme3/owner).
+
+One entry is printed per live registered controller.  Controllers with no
+registry entry (unowned) and PCIe/apple-nvme controllers (which are never
+registered) are not shown.  Stale entries whose corresponding /dev/nvmeN
+device node no longer exists are silently skipped.
+
+OPTIONS
+-------
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* List all owned controllers:
++
+------------
+# nvme registry list
+nvme1
+  owner        stas
+nvme3
+  owner        nbft
+------------
+
+SEE ALSO
+--------
+nvme-registry-retrieve(1)
+nvme-registry-update(1)
+nvme-registry-delete(1)
+nvme-disconnect-all(1)
+
+NVME
+----
+Part of the nvme-user suite

Documentation/nvme-registry-retrieve.txt

@@ -0,0 +1,60 @@
+nvme-registry-retrieve(1)
+=========================
+
+NAME
+----
+nvme-registry-retrieve - Read an attribute from a controller's registry entry
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry retrieve'
+			--device=<DEV> | -d <DEV>
+			[--attr=<ATTR> | -a <ATTR>]
+
+DESCRIPTION
+-----------
+Read a single attribute from the ownership registry entry for an NVMe-oF
+controller.  The registry is stored under /run/nvme/registry/ as one
+directory per live controller, with one plain-text file per attribute
+(e.g. /run/nvme/registry/nvme3/owner).
+
+If --attr is omitted the 'owner' attribute is retrieved.
+
+OPTIONS
+-------
+-d <DEV>::
+--device=<DEV>::
+	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
+
+-a <ATTR>::
+--attr=<ATTR>::
+	Attribute name to retrieve.  Defaults to 'owner'.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Retrieve the owner of nvme3 (default attribute):
++
+------------
+# nvme registry retrieve --device nvme3
+stas
+------------
+
+* Retrieve a specific attribute:
++
+------------
+# nvme registry retrieve --device nvme3 --attr owner
+stas
+------------
+
+SEE ALSO
+--------
+nvme-registry-list(1)
+nvme-registry-update(1)
+nvme-registry-delete(1)
+
+NVME
+----
+Part of the nvme-user suite

Documentation/nvme-registry-update.txt

@@ -0,0 +1,70 @@
+nvme-registry-update(1)
+=======================
+
+NAME
+----
+nvme-registry-update - Write an attribute to a controller's registry entry
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry update'
+			--device=<DEV> | -d <DEV>
+			--attr=<ATTR> | -a <ATTR>
+			--value=<VAL> | -V <VAL>
+
+DESCRIPTION
+-----------
+Write an attribute to the ownership registry entry for an NVMe-oF
+controller.  The registry is stored under /run/nvme/registry/ as one
+directory per live controller, with one plain-text file per attribute.
+The entry directory is created if it does not already exist.
+
+This command is primarily used by orchestrators to claim or transfer
+ownership of an existing connection.  An orchestrator with greater
+management authority (e.g. nvme-stas with CDC/fabric-zoning knowledge)
+may call this command to take ownership from one that connected first.
+
+Writes are atomic: a temporary file is written and synced, then renamed
+into place, preventing corruption under concurrent access.
+
+OPTIONS
+-------
+-d <DEV>::
+--device=<DEV>::
+	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
+
+-a <ATTR>::
+--attr=<ATTR>::
+	Attribute name to write (e.g. owner).
+
+-V <VAL>::
+--value=<VAL>::
+	New attribute value.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Claim ownership of nvme3:
++
+------------
+# nvme registry update --device nvme3 --attr owner --value stas
+------------
+
+* Transfer ownership to a different orchestrator:
++
+------------
+# nvme registry update --device nvme3 --attr owner --value nbft
+------------
+
+SEE ALSO
+--------
+nvme-registry-list(1)
+nvme-registry-retrieve(1)
+nvme-registry-delete(1)
+nvme-disconnect-all(1)
+
+NVME
+----
+Part of the nvme-user suite