From: Daniel Wagner <dwagner@suse.de>
Date: Fri, 16 Jun 2023 11:13:08 +0000 (+0200)
Subject: doc: Add information on --context
X-Git-Tag: v2.5~14
X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=a1d59599178a962241380b6cd62eeefd5a316816;p=users%2Fsagi%2Fnvme-cli.git

doc: Add information on --context

Document the newly added --context argument and how to use it.

Signed-off-by: Daniel Wagner <dwagner@suse.de>
---

diff --git a/Documentation/nvme-connect-all.txt b/Documentation/nvme-connect-all.txt
index cbb7ca6c..46b09116 100644
--- a/Documentation/nvme-connect-all.txt
+++ b/Documentation/nvme-connect-all.txt
@@ -38,6 +38,7 @@ SYNOPSIS
                 [--nbft]
                 [--no-nbft]
                 [--nbft-path=<STR>]
+                [--context=<STR>]
 
 DESCRIPTION
 -----------
@@ -210,7 +211,9 @@ OPTIONS
 --nbft-path=<STR>::
         Use a user-defined path to the NBFT tables
 
-
+--context <STR>::
+	Set the execution context to <STR>. This allows to coordinate
+	the management of the global resources.
 
 EXAMPLES
 --------
diff --git a/Documentation/nvme-connect.txt b/Documentation/nvme-connect.txt
index 0e8856c7..a6effafb 100644
--- a/Documentation/nvme-connect.txt
+++ b/Documentation/nvme-connect.txt
@@ -37,6 +37,7 @@ SYNOPSIS
 		[--tls                        ]
 		[--dump-config            | -O]
 		[--output-format=<fmt>    | -o <fmt>]
+		[--application=<id>                 ]
 
 DESCRIPTION
 -----------
@@ -195,6 +196,10 @@ OPTIONS
 	be used at a time. When this option is specified, the device associated with
 	the connection will be printed. Nothing is printed otherwise.
 
+--context <STR>::
+	Set the execution context to <STR>. This allows to coordinate
+	the management of the global resources.
+
 EXAMPLES
 --------
 * Connect to a subsystem named nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432
diff --git a/Documentation/nvme-discover.txt b/Documentation/nvme-discover.txt
index b040c688..a0ffb362 100644
--- a/Documentation/nvme-discover.txt
+++ b/Documentation/nvme-discover.txt
@@ -40,6 +40,7 @@ SYNOPSIS
                 [--nbft]
                 [--no-nbft]
                 [--nbft-path=<STR>]
+		[--context=<STR>]
 
 DESCRIPTION
 -----------
@@ -241,6 +242,9 @@ OPTIONS
 --nbft-path=<STR>::
         Use a user-defined path to the NBFT tables
 
+--context <STR>::
+	Set the execution context to <STR>. This allows to coordinate
+	the management of the global resources.
 
 EXAMPLES
 --------
diff --git a/README.md b/README.md
index 9afbc520..d969769e 100644
--- a/README.md
+++ b/README.md
@@ -234,3 +234,52 @@ $ git rebase master
 # Push your changes to github and trigger a PR
 $ git push -u origin fix-something
 ```
+
+## Persistent, volatile configuration
+
+Persistent configurations can be stored in two different locations: either in
+the file `/etc/nvme/discovery.conf` using the old style, or in the file
+`/etc/nvme/config.json` using the new style.
+
+On the other hand, volatile configurations, such as those obtained from
+third-party tools like `nvme-stats` or `blktests'` can be stored in the
+`/run/nvme` directory. When using the `nvme-cli` tool, all these configurations
+are combined into a single configuration that is used as input.
+
+The volatile configuration is particularly useful for coordinating access to the
+global resources among various components. For example, when executing
+`blktests` for the FC transport, the `nvme-cli` udev rules can be triggered. To
+prevent interference with a test, `blktests` can create a JSON configuration
+file in `/run/nvme` to inform `nvme-cli` that it should not perform any actions
+trigged from the udev context. This behavior can be controlled using the
+`--context` argument.
+
+For example a `blktests` volatile configuration could look like:
+
+```json
+[
+  {
+    "hostnqn": "nqn.2014-08.org.nvmexpress:uuid:242d4a24-2484-4a80-8234-d0169409c5e8",
+    "hostid": "242d4a24-2484-4a80-8234-d0169409c5e8",
+    "subsystems": [
+      {
+	"application": "blktests",
+        "nqn": "blktests-subsystem-1",
+        "ports": [
+          {
+            "transport": "fc",
+	    "traddr": "nn-0x10001100aa000001:pn-0x20001100aa000001",
+	    "host_traddr": "nn-0x10001100aa000002:pn-0x20001100aa000002"
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+Note when updating the volatile configuration during runtime, it should done in
+a an atomic way. For example create a temporary file without the `.json` file
+extension in `/run/nvme` and write the contents to this file. When finished use
+`rename` to add the `'.json'` file name extension. This ensures nvme-cli only
+sees the complete file.