summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md204
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.