NVMe/nvme-cli

nvme-cli

nvme-cli - NVMe management command line interface.

GitHub - linux-nvme/nvme-cli: NVMe management command line interface. - https://github.com/linux-nvme/nvme-cli

Build and Install

NOTE: As of version 2.0, Meson (and submodule libnvme) are included, and build became much more complicated. Version 1.16 was the last pre-Meson build.

# Ubuntu:
apt-get install gcc make libudev-dev git pkg-config libsystemd-dev

mkdir ~/.src ; cd ~/.src

git clone https://github.com/linux-nvme/nvme-cli nvme-cli

cd nvme-cli
#git checkout v1.8.1
#git checkout v1.10.1
#git checkout v1.12
git checkout v1.16   # <--- recommended version!
make clean
make

If you want to install to an alternative path:

# which will end up with the binary in /otherdir/usr/sbin/
make install DESTDIR=/otherdir
or
# which will end up with the binary in /otherdir/sbin/
make install PREFIX=/otherdir

Remove old, and install new:

rm -f `which nvme`  # remove previous version, as 1.8.1 installed in a different location
sudo make install

nvme --version

nvme --help
nvme list

Build and Install v2

NOTE: As of version 2.0, Meson (and submodule libnvme) are included, and build became much more complicated. Version 1.16 was the last pre-Meson build.

# Ubuntu:
 ## apt-get install gcc make libudev-dev git pkg-config libsystemd-dev
 sudo apt-get -y -qq install build-essential
 sudo apt-get -y -qq install git-all git-daemon-sysvinit
 sudo apt-get -y -qq install pkg-config
 sudo apt-get -y -qq install cmake    
 sudo apt-get -y -qq install uuid uuid-dev
 sudo apt-get -y -qq install libjson-c-dev
 sudo apt-get -y -qq install python3-pip
 sudo apt-get -y -qq install libpam-dev
 sudo apt-get -y -qq install libcap-ng-dev
 sudo apt-get -y -qq install libssl-dev
 sudo dpkg --purge meson
 pip3 install meson

 # compact:
 sudo apt-get -y -qq install build-essential git-all git-daemon-sysvinit pkg-config cmake uuid uuid-dev libjson-c-dev python3-pip libpam-dev libcap-ng-dev libssl-dev
 sudo dpkg --purge meson
 pip3 install meson

# Redhat:
 sudo yum group install -y -q "Development Tools"
 # sudo yum install -y -q python3-pip libuuid libuuid-devel json-c-devel pam-devel libcap-ng-devel
 sudo yum install -y -q python3-pip
 sudo yum install -y -q libuuid libuuid-devel
 sudo yum install -y -q json-c-devel
 sudo yum install -y -q pam-devel
 sudo yum install -y -q libcap-ng-devel
 sudo pip3 install meson
 sudo pip3 install ninja==1.8.2

mkdir ~/.src ; cd ~/.src

git clone https://github.com/linux-nvme/libnvme libnvme

cd libnvme
# git master
# git checkout v1.6
# ### Note: subprojects/libnvme.wrap in nvme-cli specifies which version to checkout:
# git checkout b25dc6102bc000ff4c8061e6448cfb4c034eaed6    # (a 1.6 version)
checkout 80c5cf2aa45f4afc7571dc48850fae3fd62828af  # (for nvme-cli v2.9 and v2.9.1)

# To build:
meson .build
ninja -C .build

# To Install: (watch for install /path/lib64, may need it below)
meson install -C .build

NOTE: There is a Makefile wrapper for meson for backwards compatiblily:

make clean
make
make install

Verify library found:

ldconfig -p | grep libnvme

If not may need to fix ldconfig: (use /path/lib64 from above)

echo "/usr/local/lib64" > /etc/ld.so.conf.d/local.conf
ldconfig
ldconfig -p | grep libnvme

-

git clone https://github.com/linux-nvme/nvme-cli nvme-cli

cd nvme-cli
  # git master
  # git checkout v2.2   # <--- recommended version!
# git checkout v2.9.1
git checkout tags/v2.9.1

# Build dependency subprojects
rm -rf .build
  # meson setup .build
  # meson subprojects update
  # meson setup --prefix=/usr --force-fallback-for=libnvme,json-c .build
meson setup --force-fallback-for=libnvme,json-c .build
ninja -C .build

# install:
meson install -C .build

# Rebuild ldconfig, if libnvme were copied over
ldconfig
ldconfig -p | grep nvme  # print to verify

Or:

make clean
make

Note: if it couldn't find libnvme

ERROR: Dependency 'libnvme' is required but not found.
vim meson.build
 # incdir = include_directories(['ccan'])
 incdir = include_directories(['ccan','/usr/local/include'])

If you want to install to an alternative path:

# which will end up with the binary in /otherdir/usr/sbin/
make install DESTDIR=/otherdir
or
# which will end up with the binary in /otherdir/sbin/
make install PREFIX=/otherdir

Remove old, and install new:

rm -f `which nvme`  # remove previous version, as 1.8.1 installed in a different location
sudo make install

nvme --version

nvme --help
nvme list

Build and install with additional WDC vendor specific functionality

git clone https://github.com/wdc-tools/nvme-cli.git wdc-nvme-cli
cd wdc-nvme-cli
make clean
make
sudo make install

Useful Commands

List NVME devices:

sudo nvme list

Capture WDC E6 Log

Retrieve WDC device's internal firmware log and save to file.

nvme wdc cap-diag /dev/nvme0 -o e6.bin
nvme wdc vs-internal-log /dev/nvme0 -o e6.bin

The E6 log dump file would then be submitted to support for analysis.

Read Example

nvme read:

--start-block=<NUM>, -s <NUM>
--block-count=<NUM>, -c <NUM>
--data-size=<NUM>, -z <NUM>
--data=<FILE>, -d <FILE>

Pass or fail result:

# read lba 1 -> lba 2
sudo nvme read /dev/nvme0n1 -s 1 -c 0 -z 4096
    read: Success

Read to file:

# read lba 1 -> lba 2
sudo nvme read /dev/nvme0n1 -s 1 -c 0 -z 4096 -d read.img
    read: Success

Write Example

nvme write:

--start-block=<NUM>, -s <NUM>
--block-count=<NUM>, -c <NUM>
--data-size=<NUM>, -z <NUM>
--data=<FILE>, -d <FILE>

Write data:

# write lba 1 -> lba 2
sudo nvme write /dev/nvme0n1 -s 1 -c 0 -z 4096 -d write.img
    read: Success

Read Write Example

# write 4k random data file
dd if=/dev/urandom of=write_data.img bs=4k count=1

# write 4k random data file to nvme device at first block
sudo nvme write /dev/nvme0n1 -s 1 -c 0 -z 4096 -d write_data.img

# read 4k random data file from nvme device at first block
sudo nvme read /dev/nvme0n1 -s 1 -c 0 -z 4096 -d read_data.img

# checksum both (should match)
md5sum write_data.img read_data.img

Format

4k or 512 format may or may not be the default, so check the LBA Format options first:

List LBA Format Options:

$ sudo nvme id-ns -H /dev/nvme0n1
...
LBA Format  0 : Metadata Size: 0   bytes - Data Size: 4096 bytes - Relative Performance
: 0 Best (in use)
LBA Format  1 : Metadata Size: 0   bytes - Data Size: 512 bytes - Relative Performance:
 0 Best

Format with chosen LBA Format option:

# default LBA format
$ sudo nvme format /dev/nvme0n1
$ sudo nvme format /dev/nvme0n1 --lbaf=0

# LBA format option 1
$ sudo nvme format /dev/nvme0n1 --lbaf=1

--

$ sudo nvme id-ns /dev/nvme0n1
lbaf  0 : ms:0   lbads:12 rp:0 (in use)
lbaf  1 : ms:0   lbads:9  rp:0

ms:0 = metadata size is 2^0 = 0
lbads 12 = LBA size = 2^12 = 4096
lbads 12 = LBA size = 2^9 = 512

Activate Firmware

$ sudo nvme fw-download /dev/nvme0 -f firmware_image.vpkg
$ sudo nvme fw-activate /dev/nvme0 --action 1 --slot 1
$ sudo nvme reset /dev/nvme0

SMART Log

nvme smart-log /dev/nvme0

additional smart log:

nvme smart-log-add /dev/nvme0

Temperature

nvme smart-log /dev/nvme0 | grep "^temperature"

Unmap

There is a Dataset Management Deallocate command (UNMAP) in nvme-cli:

sudo nvme dsm /dev/nvme0n1 -d -s 0x1bf0ea00 -b 0xff

nvme dsm /dev/nvme0n1 -d -s 0x100000 -b 0x80000
0x80000 blocks, starting at 0x100000.
-s and -b can be , separated lists to do multiple ranges

Name Spaces

List Name Spaces

nvme list-ns /dev/nvme0

Delete Name Space

nvme delete-ns /dev/nvme0 -n 0

Create Name Space

nvme create-ns /dev/nvme0 ...

Attach Name Space

nvme attach-ns /dev/nvme0 -n 0 -c 0

Sample

# ls /dev/nvme*
/dev/nvme0  /dev/nvme0n1  /dev/nvme1

root@lmt-ci-8049:~# nvme list
Node             SN                   Model                                    Namespace Usage                      Format           FW Rev
---------------- -------------------- ---------------------------------------- --------- -------------------------- ---------------- --------
/dev/nvme0n1     203351900009         SomeDriveXXX                             1           0.00   B /   1.92  TB      4 KiB +  0 B   0000780

root@lmt-ci-8049:~# nvme delete-ns /dev/nvme0 -n 1
delete-ns: Success, deleted nsid:1

root@lmt-ci-8049:~# nvme create-ns /dev/nvme0 -s 0x1024 -c 0x1024 -f 0 -d 0 -m 1
create-ns: Success, created nsid:1

root@lmt-ci-8049:~# nvme create-ns /dev/nvme1 -s 0x1024 -c 0x1024 -f 0 -d 0 -m 1
create-ns: Success, created nsid:2

root@lmt-ci-8049:~# nvme attach-ns /dev/nvme0 -n 1 -c 0
attach-ns: Success, nsid:1

root@lmt-ci-8049:~# nvme attach-ns /dev/nvme1 -n 2 -c 1
attach-ns: Success, nsid:2

root@lmt-ci-8049:~# nvme list
Node             SN                   Model                                    Namespace Usage                      Format           FW Rev
---------------- -------------------- ---------------------------------------- --------- -------------------------- ---------------- --------
/dev/nvme0n1     20335190000X         SomeDriveXXX                             1           0.00   B /  16.92  MB      4 KiB +  0 B   0000780
/dev/nvme0n2     20335190000X         SomeDriveXXX                             2           0.00   B /  16.92  MB      4 KiB +  0 B   0000780

keywords

nvme nvme-cli NVME CLI