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 cbb7ca6cbfbdd25023bf2fd5944be88e9a185254..46b09116e6f29582fb5cca78a14e07bdf7f3b838 100644 (file)
--- 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 0e8856c706ded7abe63f9b41398f6945bc1b8d45..a6effafbd3d09dba77a476d90ce43f818223ef16 100644 (file)
--- 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 b040c688ca9dbaaabc5dca2d0573dbd19d972c0a..a0ffb3623042a9438e07b0680699d6f5496f3104 100644 (file)
--- 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 9afbc5209f8cbceb0f3629b6291605c32016bd5f..d969769e8bac4505d9c952eb2ffa9b621d9ec06a 100644 (file)
--- 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.