Merging upstream version 2.5.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 89 insertions, 115 deletions

diff --git a/README.md b/README.md
index da3a7de..d969769 100644
--- a/README.md
+++ b/README.md
@@ -5,157 +5,82 @@
 
 NVM-Express user space tooling for Linux.
 
-nvme-cli uses meson as build system. In order to build nvme-cli
-run following commands
+## Build from source
 
-	$ meson .build
-	$ ninja -C .build
+nvme-cli uses meson as build system.
 
-nvme-cli depends on json-c
+### nvme-cli dependencies:
 
-To install, run:
+ | Library | Dependency | Notes |
+ |---------|------------|-------|
+ | libnvme, libnvme-mi| yes | be either installed or included into the build via meson fallback feature |
+ | json-c | optional | recommended, without all plugins are disabled and json-c output format is disabled |
+ | libhugetblfs | optional | adds support for hugetblfs |
 
-	# meson install -C .build
-
-There is a Makefile wrapper for meson for backwards compatiblily
-
-    $ make
-    # make install
-
-RPM build support via Makefile that uses meson
-
-    $ make rpm
-
-If not sure how to use, find the top-level documentation with:
-
-    $ man nvme
 
-Or find a short summary with:
-
-    $ nvme help
-
-## Distro Support
-
-### Alpine Linux
+### Configuring
 
-nvme-cli is tested on Alpine Linux 3.3.  Install it using:
-
-    # apk update && apk add nvme-cli nvme-cli-doc
-
-if you just use the device you're after, it will work flawless.
-```
-# nvme smart-log /dev/nvme0
-Smart Log for NVME device:/dev/nvme0 namespace-id:ffffffff
-critical_warning                    : 0
-temperature                         : 49 C
-available_spare                     : 100%
-```
+In case libnvme is not installed on the system, it possible to use meson's
+fallback feature to resolve the dependency.
 
-### Arch Linux
+	$ meson setup --force-fallback-for=libnvme .build
 
-nvme-cli is available in the `[community]` repository. It can be installed with:
+If the libnvme is already installed on the system meson is using pkg-config to
+find the dependency. In this case a plain setup call is enough:
 
-    # pacman -S nvme-cli
+	$ meson setup .build
 
-The development version can be installed from AUR, e.g.:
+With meson's --wrap-mode argument it's possible to control if the additional
+dependencies should also resolved or not. The options are
 
-    $ yay -S nvme-cli-git
+	--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}
 
-### Debian
+Note for nvme-cli the 'default' is set to nofallback.
 
-nvme-cli is available in Debian 9 and up.  Install it with your favorite
-package manager.  For example:
+### Building
 
-    $ sudo apt install nvme-cli
+	$ meson compile -C .build
 
-### Fedora
+### Installing
 
-nvme-cli is available in Fedora 23 and up.  Install it with your favorite
-package manager.  For example:
+	# meson install -C .build
 
-    $ sudo dnf install nvme-cli
+### Makefile wrapper
 
-### FreeBSD
+There is a Makefile wrapper for meson for backwards compatibility
 
-`nvme-cli` is available in the FreeBSD Ports Collection.  A prebuilt binary
-package can be installed with:
+	$ make
+	# make install
 
-```console
-# pkg install nvme-cli
-```
+Note in this case libnvme needs to be installed by hand first.
 
-### Gentoo
+RPM build support via Makefile that uses meson
 
-nvme-cli is available and tested in portage:
-```
-$ emerge -av nvme-cli
-```
+	$ make rpm
 
-### Nix(OS)
+If not sure how to use, find the top-level documentation with:
 
-The attribute is named `nvme-cli` and can e.g. be installed with:
-```
-$ nix-env -f '<nixpkgs>' -iA nvme-cli
-```
+	$ man nvme
 
-### openSUSE
+Or find a short summary with:
 
-nvme-cli is available in openSUSE Leap 42.2 or later and Tumbleweed. You can
-install it using zypper. For example:
+	$ nvme help
 
-    $ sudo zypper install nvme-cli
+## Distro Support
 
-### Ubuntu
+Many popular distributions (Alpine, Arch, Debian, Fedora, FreeBSD, Gentoo,
+Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is nvme-cli.
 
-nvme-cli is supported in the Universe package sources for
-many architectures. For a complete list try running:
-  ```
-  rmadison nvme-cli
-   nvme-cli | 0.5-1          | xenial/universe         | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x
-   nvme-cli | 0.5-1ubuntu0.2 | xenial-updates/universe | source, amd64, arm64,       armhf, i386, powerpc, ppc64el, s390x
-   nvme-cli | 1.5-1          | bionic/universe         | source, amd64, arm64,       armhf, i386, ppc64el, s390x
-   nvme-cli | 1.5-1ubuntu1.2 | bionic-updates          | source, amd64, arm64,       armhf, i386, ppc64el, s390x
-   nvme-cli | 1.9-1          | focal/universe          | source, amd64, arm64,       armhf, ppc64el, riscv64, s390x
-   nvme-cli | 1.9-1ubuntu0.1 | focal-updates           | source, amd64, arm64,       armhf, ppc64el, riscv64, s390x
-   nvme-cli | 1.14-1         | impish                  | source, amd64, arm64,       armhf, ppc64el, riscv64, s390x
-   nvme-cli | 1.16-3         | jammy                   | source, amd64, arm64,       armhf, ppc64el, riscv64, s390x
-  ```
-A Debian based package for nvme-cli is currently maintained as a
-Ubuntu PPA. To install nvme-cli using this approach please perform the following
-steps:
-   1. Perform an update of your repository list:
-   ```
-   sudo apt-get update
-   ```
-   2. Get nvme-cli!
-   ```
-   sudo apt-get install nvme-cli
-   ```
-   3. Test the code.
-   ```
-   sudo nvme list
-   ```
-   In the case of no NVMe devices you will see
-   ```
-   No NVMe devices detected.
-   ```
-   otherwise you will see information about each NVMe device installed
-   in the system.
-
-### OpenEmbedded/Yocto
+#### OpenEmbedded/Yocto
 
 An [nvme-cli recipe](https://layers.openembedded.org/layerindex/recipe/88631/)
 is available as part of the `meta-openembeded` layer collection.
 
-### Buildroot
+#### Buildroot
 
 `nvme-cli` is available as [buildroot](https://buildroot.org) package. The
 package is named `nvme`.
 
-### Other Distros
-
-TBD
-
 ## Developers
 
 You may wish to add a new command or possibly an entirely new plug-in
@@ -254,7 +179,7 @@ means if the current branch is updated via git, the subprojects/libnvme
 branch will not updated accordingly.  To update it, either use the 
 normal git operations or the command: 
 
-    $ meson subprojects update
+	$ meson subprojects update
 
 ## Dependency
 
@@ -309,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.