|
| 1 | +# nvme-cli |
| 2 | +NVM-Express user space tooling for Linux. |
| 3 | + |
| 4 | +To install, run: |
| 5 | + |
| 6 | + # make && make install |
| 7 | + |
| 8 | +If not sure how to use, find the top-level documentation with: |
| 9 | + |
| 10 | + # man nvme |
| 11 | + |
| 12 | +Or find a short summary with: |
| 13 | + |
| 14 | + # nvme help |
| 15 | + |
| 16 | +## Distro Support |
| 17 | + |
| 18 | +### Fedora |
| 19 | + |
| 20 | +nvme-cli is available in Fedora 23 and up. Install it with your favorite |
| 21 | +package manager. For example: |
| 22 | + |
| 23 | + $ sudo dnf install nvme-cli |
| 24 | + |
| 25 | +### Ubuntu |
| 26 | + |
| 27 | +nvme-cli is supported in the Universe package sources for Xenial for |
| 28 | +many architectures. For a complete list try running: |
| 29 | + ``` |
| 30 | + rmadison nvme-cli |
| 31 | + nvme-cli | 0.3-1 | xenial/universe | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x |
| 32 | + ``` |
| 33 | +A Debian based package for nvme-cli is currently maintained as a |
| 34 | +Ubuntu PPA. Right now there is support for Trusty, Vivid and Wiley. To |
| 35 | +install nvme-cli using this approach please perform the following |
| 36 | +steps: |
| 37 | + 1. Add the sbates PPA to your sources. One way to do this is to run |
| 38 | + ``` |
| 39 | + sudo add-apt-repository ppa:sbates |
| 40 | + ``` |
| 41 | + 2. Perform an update of your repository list: |
| 42 | + ``` |
| 43 | + sudo apt-get update |
| 44 | + ``` |
| 45 | + 3. Get nvme-cli! |
| 46 | + ``` |
| 47 | + sudo apt-get install nvme-cli |
| 48 | + ``` |
| 49 | + 4. Test the code. |
| 50 | + ``` |
| 51 | + sudo nvme list |
| 52 | + ``` |
| 53 | + In the case of no NVMe devices you will see |
| 54 | + ``` |
| 55 | + No NVMe devices detected. |
| 56 | + ``` |
| 57 | + otherwise you will see information about each NVMe device installed |
| 58 | + in the system. |
| 59 | + |
| 60 | +### Alpine Linux |
| 61 | + |
| 62 | +nvme-cli is tested on Alpine Linux 3.3. Install it using: |
| 63 | + |
| 64 | + # akp update && apk add nvme-cli nvme-cli-doc |
| 65 | + |
| 66 | +if you just use the device you're after, it will work flawless. |
| 67 | +``` |
| 68 | +# nvme smart-log /dev/nvme0 |
| 69 | +Smart Log for NVME device:/dev/nvme0 namespace-id:ffffffff |
| 70 | +critical_warning : 0 |
| 71 | +temperature : 49 C |
| 72 | +available_spare : 100% |
| 73 | +``` |
| 74 | + |
| 75 | +### openSUSE Tumbleweed |
| 76 | + |
| 77 | +nvme-cli is available in openSUSE Tumbleweed. You can install it using zypper. |
| 78 | +For example: |
| 79 | + |
| 80 | + $ sudo zypper install nvme-cli |
| 81 | + |
| 82 | +### Arch Linux |
| 83 | + |
| 84 | +Install from AUR, e.g.: |
| 85 | +``` |
| 86 | +$ yaourt -S nvme-cli-git |
| 87 | +``` |
| 88 | + |
| 89 | +### Nix(OS) |
| 90 | + |
| 91 | +The attribute is named `nvme-cli` and can e.g. be installed with: |
| 92 | +``` |
| 93 | +$ nix-env -f '<nixpkgs>' -iA nvme-cli |
| 94 | +``` |
| 95 | + |
| 96 | +### Other Distros |
| 97 | + |
| 98 | +TBD |
| 99 | + |
| 100 | +## Developers |
| 101 | + |
| 102 | +You may wish to add a new command or possibly an entirely new plug-in |
| 103 | +for some special extension outside the spec. |
| 104 | + |
| 105 | +This project provides macros that help generate the code for you. If |
| 106 | +you're interested in how that works, it is very similar to how trace |
| 107 | +events are created by Linux kernel's 'ftrace' component. |
| 108 | + |
| 109 | +### Add command to existing built-in |
| 110 | + |
| 111 | +The first thing to do is define a new command entry in the command |
| 112 | +list. This is declared in nvme-builtin.h. Simply append a new "ENTRY" into |
| 113 | +the list. The ENTRY normally takes three arguments: the "name" of the |
| 114 | +subcommand (this is what the user will type at the command line to invoke |
| 115 | +your command), a short help description of what your command does, and the |
| 116 | +name of the function callback that you're going to write. Additionally, |
| 117 | +You can declare an alias name of subcommand with fourth argument, if needed. |
| 118 | + |
| 119 | +After the ENTRY is defined, you need to implement the callback. It takes |
| 120 | +four arguments: argc, argv, the command structure associated with the |
| 121 | +callback, and the plug-in structure that contains that command. The |
| 122 | +prototype looks like this: |
| 123 | + |
| 124 | + ``` |
| 125 | + int f(int argc, char **argv, struct command *cmd, struct plugin *plugin); |
| 126 | + ``` |
| 127 | + |
| 128 | +The argc and argv are adjusted from the command line arguments to start |
| 129 | +after the sub-command. So if the command line is "nvme foo --option=bar", |
| 130 | +the argc is 1 and argv starts at "--option". |
| 131 | + |
| 132 | +You can then define argument parsing for your sub-command's specific |
| 133 | +options then do some command specific action in your callback. |
| 134 | + |
| 135 | +### Add a new plugin |
| 136 | + |
| 137 | +The nvme-cli provides macros to make define a new plug-in simpler. You |
| 138 | +can certainly do all this by hand if you want, but it should be easier |
| 139 | +to get going using the macros. To start, first create a header file |
| 140 | +to define your plugin. This is where you will give your plugin a name, |
| 141 | +description, and define all the sub-commands your plugin implements. |
| 142 | + |
| 143 | +There is a very important order on how to define the plugin. The following |
| 144 | +is a basic example on how to start this: |
| 145 | + |
| 146 | +File: foo-plugin.h |
| 147 | +``` |
| 148 | +#undef CMD_INC_FILE |
| 149 | +#define CMD_INC_FILE foo-plugin |
| 150 | +
|
| 151 | +#if !defined(FOO) || defined(CMD_HEADER_MULTI_READ) |
| 152 | +#define FOO |
| 153 | +
|
| 154 | +#include "cmd.h" |
| 155 | +
|
| 156 | +PLUGIN(NAME("foo", "Foo plugin"), |
| 157 | + COMMAND_LIST( |
| 158 | + ENTRY("bar", "foo bar", bar) |
| 159 | + ENTRY("baz", "foo baz", baz) |
| 160 | + ENTRY("qux", "foo quz", qux) |
| 161 | + ) |
| 162 | +); |
| 163 | +
|
| 164 | +#endif |
| 165 | +
|
| 166 | +#include "define_cmd.h" |
| 167 | +``` |
| 168 | + |
| 169 | +In order to have the compiler generate the plugin through the xmacro |
| 170 | +expansion, you need to include this header in your source file, with |
| 171 | +pre-defining macro directive to create the commands. |
| 172 | + |
| 173 | +To get started from the above example, we just need to define "CREATE_CMD" |
| 174 | +and include the header: |
| 175 | + |
| 176 | +File: foo-plugin.c |
| 177 | +``` |
| 178 | +#define CREATE_CMD |
| 179 | +#include "foo-plugin.h" |
| 180 | +``` |
| 181 | + |
| 182 | +After that, you just need to implement the functions you defined in each |
| 183 | +ENTRY, then append the object file name to the Makefile's "OBJS". |
0 commit comments