Quick Start

Assuming that you have met the Prerequisites, and running Ubuntu Linux (16.04/xenial), then build and install liblightnvm for source:

git clone https://github.com/OpenChannelSSD/liblightnvm.git
cd liblightnvm
make dev

Or, install from deb-packages:

echo "deb https://dl.bintray.com/openchannelssd/debs xenial main" | sudo tee -a /etc/apt/sources.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 379CE192D401AB61
sudo apt-get update
sudo apt-get install liblightnvm-dev liblightnvm-lib liblightnvm-cli

With the library installed, 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 -llightnvm -o hello

Tip

liblightnvm is also available as a static library. So you can add /usr/lib/liblightnvm.a to your compiler target instead of linking dynamically.

Run it

chmod +x hello
./hello
dev:
  verid: 0x02
  be_id: 0x02
  name: 'nvme0n1'
  path: '/dev/nvme0n1'
  fd: 3
  ssw: 12
  pmode: 'DUAL'
  erase_naddrs_max: 64
  read_naddrs_max: 64
  write_naddrs_max: 64
  meta_mode: 0
  bbts_cached: 0
dev_geo:
  nchannels: 16
  nluns: 8
  nplanes: 2
  nblocks: 1020
  npages: 512
  nsectors: 4
  page_nbytes: 16384
  sector_nbytes: 4096
  meta_nbytes: 16
  tbytes: 2190433320960
  tmbytes: 2088960
dev_ppaf:
  ch_off: 25
  ch_len: 04
  lun_off: 22
  lun_len: 03
  pl_off: 02
  pl_len: 01
  blk_off: 12
  blk_len: 10
  pg_off: 03
  pg_len: 09
  sec_off: 00
  sec_len: 02
dev_ppaf_mask:
  ch:  '0000000000000000000000000000000000011110000000000000000000000000'
  lun: '0000000000000000000000000000000000000001110000000000000000000000'
  pl:  '0000000000000000000000000000000000000000000000000000000000000100'
  blk: '0000000000000000000000000000000000000000001111111111000000000000'
  pg:  '0000000000000000000000000000000000000000000000000000111111111000'
  sec: '0000000000000000000000000000000000000000000000000000000000000011'

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:
  verid: 0x02
  be_id: 0x02
  name: 'nvme0n1'
  path: '/dev/nvme0n1'
  fd: 3
  ssw: 12
  pmode: 'DUAL'
  erase_naddrs_max: 64
  read_naddrs_max: 64
  write_naddrs_max: 64
  meta_mode: 0
  bbts_cached: 0
dev_geo:
  nchannels: 16
  nluns: 8
  nplanes: 2
  nblocks: 1020
  npages: 512
  nsectors: 4
  page_nbytes: 16384
  sector_nbytes: 4096
  meta_nbytes: 16
  tbytes: 2190433320960
  tmbytes: 2088960
dev_ppaf:
  ch_off: 25
  ch_len: 04
  lun_off: 22
  lun_len: 03
  pl_off: 02
  pl_len: 01
  blk_off: 12
  blk_len: 10
  pg_off: 03
  pg_len: 09
  sec_off: 00
  sec_len: 02
dev_ppaf_mask:
  ch:  '0000000000000000000000000000000000011110000000000000000000000000'
  lun: '0000000000000000000000000000000000000001110000000000000000000000'
  pl:  '0000000000000000000000000000000000000000000000000000000000000100'
  blk: '0000000000000000000000000000000000000000001111111111000000000000'
  pg:  '0000000000000000000000000000000000000000000000000000111111111000'
  sec: '0000000000000000000000000000000000000000000000000000000000000011'

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.