Quick Start

Assuming that you have met the Prerequisites, and running Ubuntu Linux (16.04/xenial), then retrieve the source code, configure, build, and install it:

# Retrieve liblightnvm
git clone https://github.com/OpenChannelSSD/liblightnvm.git
cd liblightnvm

# Default configuration, build and install
make configure
make
sudo make install

The above will configure liblightnvm, with default options, and install it by copying headers, libraries and binaries into system paths.

BUILD: Changing configuration options

The configuration options are named option_{on,off}, consult the Makefile to see available options. Apply an option by typing it before the configure target. For example:

# Change configuration, build and install
make spdk_on debug_on configure
make
sudo make install

This will enable debugging and the SPDK backend.

In case you enable build of Debian packages via deb_on, then you can modify the make install step to install/uninstall using the Debian package:

# Change configuration, build and install via package
make spdk_on debug_on deb_on configure
make
sudo make install-deb

# Conveniently remove liblightnvm by uninstalling the Debian package
sudo make uninstall-deb

BUILD: Cross-compiling for ARM on x86

liblightnvm compiles on ARM machines, however, in case you do not have the build-tools available on your ARM target, then you can cross-compile liblightnvm by setting the CC environment variable to your cross-compiler, e.g.:

CC=aarch64-linux-gnu-gcc-7 make tests_off configure
make

Then transfer the following files:

$BUILD_DIR/liblightnvm.a
$BUILD_DIR/liblightnvm_cli.a
$BUILD_DIR/cli/nvm_addr
$BUILD_DIR/cli/nvm_bbt
$BUILD_DIR/cli/nvm_cmd
$BUILD_DIR/cli/nvm_dev
$BUILD_DIR/cli/nvm_vblk

To your ARM target.

Note

The tests, the binaries named nvm_test_*, are not cross-compiled as they depend on libcunit.

With liblightnvm built and installed as you see fit, try the following examples of the C API and Command-Line Interface.

API: Hello Open-Channel SSD

This “hello-world” example prints out device information of an Open-Channel SSD. Include the liblightnvm header in your C/C++ source:

#include <stdio.h>
#include <liblightnvm.h>

int main(int argc, char **argv)
{
	struct nvm_dev *dev = nvm_dev_open("/dev/nvme0n1");
	if (!dev) {
		perror("nvm_dev_open");
		return 1;
	}
	nvm_dev_pr(dev);
	nvm_dev_close(dev);

	return 0;
}

Compile it

gcc hello.c -fopenmp -llightnvm -o hello

Tip

If you compiled liblightnvm with SPDK, then add SPDK to the command above as well. Have a look in the SPDK backend section for information on installing and linking with SPDK.

Run it

chmod +x hello
./hello

dev_attr:
  verid: 0x02
  be_id: 0x01
  be_name: 'NVM_BE_IOCTL'
  name: 'nvme0n1'
  path: '/dev/nvme0n1'
  fd: 3
  ssw: 12
  mccap: '00000000000000000000000000000001'
  bbts_cached: 0
  quirks: '00000000'
dev_geo:
  verid: 0x02
  npugrp: 8
  npunit: 4
  nchunk: 1474
  nsectr: 6144
  nbytes: 4096
  nbytes_oob: 16
  tbytes: 1187021586432
  tmbytes: 1132032
dev_cmd_opts:
  mask: '00000000000000000000000011001000'
  iomd: 'SYNC'
  addr: 'VECTOR'
  plod: 'PRP'
dev_vblk_opts:
  pmode: 'SNGL'
  erase_naddrs_max: 64
  read_naddrs_max: 64
  write_naddrs_max: 64
  meta_mode: 0
dev_ppaf: ~
dev_ppaf_mask: ~
dev_lbaf:
  pugrp: 3
  punit: 2
  chunk: 11
  sectr: 13
dev_lbaz:
  pugrp: 26
  punit: 24
  chunk: 13
  sectr: 0
dev_lbam:
  pugrp:  '0000000000000000000000000000000000011100000000000000000000000000'
  punit:  '0000000000000000000000000000000000000011000000000000000000000000'
  chunk:  '0000000000000000000000000000000000000000111111111110000000000000'
  sectr:  '0000000000000000000000000000000000000000000000000001111111111111'

CLI: Hello Open-Channel SSD

Most of the C API is wrapped in a suite of command-line interface (CLI) tools. The equivalent of the above example is readily available from the nvm_dev command:

nvm_dev info /dev/nvme0n1

Which should output information similar to:

# Device information -- nvm_dev_pr
dev_attr:
  verid: 0x02
  be_id: 0x01
  be_name: 'NVM_BE_IOCTL'
  name: 'nvme0n1'
  path: '/dev/nvme0n1'
  fd: 3
  ssw: 12
  mccap: '00000000000000000000000000000001'
  bbts_cached: 0
  quirks: '00000000'
dev_geo:
  verid: 0x02
  npugrp: 8
  npunit: 4
  nchunk: 1474
  nsectr: 6144
  nbytes: 4096
  nbytes_oob: 16
  tbytes: 1187021586432
  tmbytes: 1132032
dev_cmd_opts:
  mask: '00000000000000000000000011001000'
  iomd: 'SYNC'
  addr: 'VECTOR'
  plod: 'PRP'
dev_vblk_opts:
  pmode: 'SNGL'
  erase_naddrs_max: 64
  read_naddrs_max: 64
  write_naddrs_max: 64
  meta_mode: 0
dev_ppaf: ~
dev_ppaf_mask: ~
dev_lbaf:
  pugrp: 3
  punit: 2
  chunk: 11
  sectr: 13
dev_lbaz:
  pugrp: 26
  punit: 24
  chunk: 13
  sectr: 0
dev_lbam:
  pugrp:  '0000000000000000000000000000000000011100000000000000000000000000'
  punit:  '0000000000000000000000000000000000000011000000000000000000000000'
  chunk:  '0000000000000000000000000000000000000000111111111110000000000000'
  sectr:  '0000000000000000000000000000000000000000000000000001111111111111'

Tip

If the above does not suffice to get you started then have a look at the Prerequisites for detailed information about what you need to setup an environment.

With the basics in place, have a look at the Background section on working with NAND media, follow the Tutorial Introduction to see the background information put into practice, and dive deeper into C API and experiment with Command-Line Interface.