NVMe management command line interface.
Clone or download
keithbusch Regen documentation
Signed-off-by: Keith Busch <keith.busch@intel.com>
Latest commit d9a1281 Sep 6, 2018
Permalink
Failed to load latest commit information.
Documentation Regen documentation Sep 6, 2018
completions nvme: Introduce new 'list-subsys' command Dec 13, 2017
linux Fix nvme id namespace struct Aug 20, 2018
scripts latency script fixup Sep 30, 2016
tests Use tnvmcap register for creating namespace Jul 12, 2018
.gitignore Ignore cscope files Feb 18, 2018
CONTRIBUTING.md Add "CONTRIBUTING" file. Feb 4, 2016
LICENSE Reverted to GPL licensing Jun 2, 2015
Makefile Initial checkin for Seagate Plugin Jun 10, 2018
NVME-VERSION-GEN Release 1.6 Jul 18, 2018
README.md Update subcommand alias description in README.md Jan 10, 2018
argconfig.c nvme-cli: make malloc error handling uniform Sep 5, 2018
argconfig.h Show help when no or an invalid device is given Jun 15, 2017
cmd.h Make building plug-ins easier Jun 9, 2016
cmd_handler.h nvme-cli: add support alias command with Firmware Activate Dec 19, 2017
common.h nvme-cli: Fix build on aarch64-linux-android-4.9 Apr 24, 2017
define_cmd.h Move program execution to plugin handler Jun 8, 2016
fabrics.c fabrics: add disconnect-all command Sep 6, 2018
fabrics.h fabrics: add disconnect-all command Sep 6, 2018
huawei-nvme.c nvme-vendor: fixup c99 declaration in huawei plugin Aug 17, 2018
huawei-nvme.h nvme-cli: add id-ctrl for nvme-huawei plug-in. Jun 16, 2017
intel-nvme.c Remove trailing "\n" so that the output is valid json Jul 25, 2018
intel-nvme.h nvme-cli: Fix typo in Intel plugin and improve generic help text Jun 26, 2017
json.c Fix json output of 128-bit numbers Jun 15, 2018
json.h nvme-cli: Add support of unsigned long long to json routines Jan 20, 2018
lnvm-nvme.c nvme-cli: don't use unsigned for fd in lnvm-nvme.c Aug 20, 2018
lnvm-nvme.h Use simpler plugin definition Jun 9, 2016
memblaze-nvme.c Add support for decoding IO Determinism features Feb 18, 2018
memblaze-nvme.h Add memblaze get/set feature support Jul 7, 2016
micron-nvme.c Add support for Micron plugin May 9, 2018
micron-nvme.h Add support for Micron plugin May 9, 2018
netapp-nvme.c nvme-cli: netapp plugin handle empty strings Aug 23, 2018
netapp-nvme.h nvme-cli: add NetApp plugin Feb 12, 2018
nvme-builtin.h fabrics: add disconnect-all command Sep 6, 2018
nvme-ioctl.c nvme-cli: make malloc error handling uniform Sep 5, 2018
nvme-ioctl.h nvme-cli: add minimal ana-log page support Aug 13, 2018
nvme-lightnvm.c lightnvm: fix type coercion Jul 17, 2018
nvme-lightnvm.h lightnvm: fix type coercion Jul 17, 2018
nvme-models.c nvme-cli: make malloc error handling uniform Sep 5, 2018
nvme-models.h nvme: add options for write command directives Dec 10, 2017
nvme-print.c nvme-cli: fix indentation Aug 29, 2018
nvme-print.h nvme-cli: add minimal ana-log page support Aug 13, 2018
nvme.c fabrics: add disconnect-all command Sep 6, 2018
nvme.control.in Debian package fixes Oct 20, 2015
nvme.h nvme: commonize subsystems info in a helper Sep 6, 2018
nvme.spec.in fabrics: add hostid option to connect command Jun 20, 2017
parser.c Adds parser library Jun 7, 2016
parser.h Adds parser library Jun 7, 2016
plugin.c nvme-cli: handle long commands in help message by adjusting minimal p… Jan 24, 2018
plugin.h nvme-cli: add support alias command with Firmware Activate Dec 19, 2017
regress Updated license on bash scripts Sep 28, 2015
seagate-diag.h Updating version to 1.1 Jun 15, 2018
seagate-nvme.c Adding ppc big endian support Jun 14, 2018
seagate-nvme.h Removed Duplicate commands. Jun 10, 2018
suffix.c Use fixed-width integer types for long suffixed parameters Mar 30, 2018
suffix.h Use fixed-width integer types for long suffixed parameters Mar 30, 2018
toshiba-nvme.c Fixes for log page access. Apr 13, 2018
toshiba-nvme.h Add toshiba plugin code and command documentation. Mar 28, 2018
wdc-nvme.c nvme-cli: make wdc plug-in functions static Aug 29, 2018
wdc-nvme.h NVMe-CLI WDC-Plugin Add clear-pcie-corr command Jan 19, 2018
wdc-utils.c NVMe-CLI WDC-Plugin Add drive-essentials command Jan 19, 2018
wdc-utils.h NVMe-CLI WDC-Plugin Add drive-essentials command Jan 19, 2018

README.md

nvme-cli

NVM-Express user space tooling for Linux.

To install, run:

make && make install

If not sure how to use, find the top-level documentation with:

man nvme

Or find a short summary with:

nvme help

Distro Support

Fedora

nvme-cli is available in Fedora 23 and up. Install it with your favorite package manager. For example:

$ sudo dnf install nvme-cli

Ubuntu

nvme-cli is supported in the Universe package sources for Xenial for many architectures. For a complete list try running:

rmadison nvme-cli
 nvme-cli | 0.3-1 | xenial/universe | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x

A Debian based package for nvme-cli is currently maintained as a Ubuntu PPA. Right now there is support for Trusty, Vivid and Wiley. To install nvme-cli using this approach please perform the following steps:

  1. Add the sbates PPA to your sources. One way to do this is to run
sudo add-apt-repository ppa:sbates
  1. Perform an update of your repository list:
sudo apt-get update
  1. Get nvme-cli!
sudo apt-get install nvme-cli
  1. 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.

Alpine Linux

nvme-cli is tested on Alpine Linux 3.3. Install it using:

# akp 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%

openSUSE Tumbleweed

nvme-cli is available in openSUSE Tumbleweed. You can install it using zypper. For example:

$ sudo zypper install nvme-cli

Arch Linux

Install from AUR, e.g.:

$ yaourt -S nvme-cli-git

Nix(OS)

The attribute is named nvme-cli and can e.g. be installed with:

$ nix-env -f '<nixpkgs>' -iA nvme-cli

Other Distros

TBD

Developers

You may wish to add a new command or possibly an entirely new plug-in for some special extension outside the spec.

This project provides macros that help generate the code for you. If you're interested in how that works, it is very similar to how trace events are created by Linux kernel's 'ftrace' component.

Add command to existing built-in

The first thing to do is define a new command entry in the command list. This is declared in nvme-builtin.h. Simply append a new "ENTRY" into the list. The ENTRY normally takes three arguments: the "name" of the subcommand (this is what the user will type at the command line to invoke your command), a short help description of what your command does, and the name of the function callback that you're going to write. Additionally, You can declare an alias name of subcommand with fourth argument, if needed.

After the ENTRY is defined, you need to implement the callback. It takes four arguments: argc, argv, the command structure associated with the callback, and the plug-in structure that contains that command. The prototype looks like this:

int f(int argc, char **argv, struct command *cmd, struct plugin *plugin);

The argc and argv are adjusted from the command line arguments to start after the sub-command. So if the command line is "nvme foo --option=bar", the argc is 1 and argv starts at "--option".

You can then define argument parsing for your sub-command's specific options then do some command specific action in your callback.

Add a new plugin

The nvme-cli provides macros to make define a new plug-in simpler. You can certainly do all this by hand if you want, but it should be easier to get going using the macros. To start, first create a header file to define your plugin. This is where you will give your plugin a name, description, and define all the sub-commands your plugin implements.

There is a very important order on how to define the plugin. The following is a basic example on how to start this:

File: foo-plugin.h

#undef CMD_INC_FILE
#define CMD_INC_FILE foo-plugin

#if !defined(FOO) || defined(CMD_HEADER_MULTI_READ)
#define FOO

#include "cmd.h"

PLUGIN(NAME("foo", "Foo plugin"),
	COMMAND_LIST(
		ENTRY("bar", "foo bar", bar)
		ENTRY("baz", "foo baz", baz)
		ENTRY("qux", "foo quz", qux)
	)
);

#endif

#include "define_cmd.h"

In order to have the compiler generate the plugin through the xmacro expansion, you need to include this header in your source file, with pre-defining macro directive to create the commands.

To get started from the above example, we just need to define "CREATE_CMD" and include the header:

File: foo-plugin.c

#define CREATE_CMD
#include "foo-plugin.h"

After that, you just need to implement the functions you defined in each ENTRY, then append the object file name to the Makefile's "OBJS".