Repository files navigation

NVM-Express user space tooling for Linux.

To install, run:

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

Or find a short summary with:

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

$ sudo dnf install nvme-cli

nvme-cli is supported in the Universe package sources for Xenial formany 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 aUbuntu PPA. Right now there is support for Trusty, Vivid and Wiley. Toinstall nvme-cli using this approach please perform the followingsteps:

1. Add the sbates PPA to your sources. One way to do this is to run

sudo add-apt-repository ppa:sbates

2. Perform an update of your repository list:

sudo apt-get update

3. Get nvme-cli!

sudo apt-get install nvme-cli

4. 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 installedin the system.

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

# akp update && apk add nvme-cli nvme-cli-docif 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:ffffffffcritical_warning : 0temperature : 49 Cavailable_spare : 100%```

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

$ sudo zypper install nvme-cli

Install from AUR, e.g.:

$ yaourt -S nvme-cli-git

TBD

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

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

The first thing to do is define a new command entry in the commandlist. This is declared in nvme-builtin.h. Simply append a new "ENTRY" intothe list. The ENTRY takes three arguments: the "name" of the subcommand(this is what the user will type at the command line to invoke yourcommand), a short help description of what your command does, and thename of the function callback that you're going to write.

After the ENTRY is defined, you need to implement the callback. It takesfour arguments: argc, argv, the command structure associated with thecallback, and the plug-in structure that contains that command. Theprototype 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 startafter 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 specificoptions then do some command specific action in your callback.

The nvme-cli provides macros to make define a new plug-in simpler. Youcan certainly do all this by hand if you want, but it should be easierto get going using the macros. To start, first create a header fileto 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 followingis 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 xmacroexpansion, you need to include this header in your source file, withpre-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 eachENTRY, then append the object file name to the Makefile's "OBJS".