libnvme: NVMe-oF controller ownership registry

Documentation/nvme-disconnect-all.txt

@@ -9,30 +9,67 @@ SYNOPSIS
 --------
 [verse]
 'nvme' [<global-options>] 'disconnect-all'
+			[--transport=<STR> | -r <STR>]
+			[--owner=<NAME> | -O <NAME>]
+			[--force | -f]
 
 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.
 
 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.
+
+-f::
+--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
 ----

Documentation/nvme-registry-delete.txt

@@ -0,0 +1,49 @@
+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 stored at /run/nvme/registry/<device>.json.
+
+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).
+
+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,49 @@
+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 JSON file per live controller.
+
+One line is printed per live registered controller.  Controllers with no
+registry entry (unowned) and PCIe/apple-nvme controllers (which are never
+registered) are not shown.
+
+OPTIONS
+-------
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* List all owned controllers:
++
+------------
+# nvme registry-list
+DEVICE           OWNER
+nvme1            stas
+nvme3            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,59 @@
+nvme-registry-retrieve(1)
+=========================
+
+NAME
+----
+nvme-registry-retrieve - Retrieve a field from a controller's registry entry
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry-retrieve'
+			[--device=<DEV> | -d <DEV>]
+			[--key=<KEY> | -k <KEY>]
+
+DESCRIPTION
+-----------
+Read a single field from the ownership registry entry for an NVMe-oF
+controller.  The registry is stored under /run/nvme/registry/ as one JSON
+file per live controller (e.g. nvme3.json).
+
+If --key is omitted the 'owner' field is retrieved.
+
+OPTIONS
+-------
+-d <DEV>::
+--device=<DEV>::
+	NVMe device name (e.g. nvme3).
+
+-k <KEY>::
+--key=<KEY>::
+	Registry field name to retrieve.  Defaults to 'owner'.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Retrieve the owner of nvme3 (default key):
++
+------------
+# nvme registry-retrieve --device nvme3
+stas
+------------
++
+* Retrieve a specific field by key:
++
+------------
+# nvme registry-retrieve --device nvme3 --key device
+nvme3
+------------
+
+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,59 @@
+nvme-registry-update(1)
+=======================
+
+NAME
+----
+nvme-registry-update - Update a field in a controller's registry entry
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'registry-update'
+			--device=<DEV> | -d <DEV>
+			--key=<KEY> | -k <KEY>
+			--value=<VAL> | -V <VAL>
+
+DESCRIPTION
+-----------
+Write a key/value pair to the ownership registry entry for an NVMe-oF
+controller.  If the entry does not exist it is created.  The write is
+atomic: a temporary file is created, synced, and renamed over the
+destination.
+
+This command is the primary mechanism for an orchestrator to claim or
+steal ownership of an existing connection.  All orchestrators are
+assumed to be cooperative; there is no OS-level enforcement of ownership.
+
+OPTIONS
+-------
+-d <DEV>::
+--device=<DEV>::
+	NVMe device name (e.g. nvme3).
+
+-k <KEY>::
+--key=<KEY>::
+	Registry field name to update (e.g. owner).
+
+-V <VAL>::
+--value=<VAL>::
+	New value for the field.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Claim ownership of nvme3:
++
+------------
+# nvme registry-update --device nvme3 --key owner --value stas
+------------
+
+SEE ALSO
+--------
+nvme-registry-list(1)
+nvme-registry-retrieve(1)
+nvme-registry-delete(1)
+
+NVME
+----
+Part of the nvme-user suite