1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright (C) 2017 NXP Semiconductors
3.. Copyright (C) 2017 Bin Meng <bmeng.cn@gmail.com>
4
5NVMe Support
6============
7
8What is NVMe
9------------
10
11NVM Express (NVMe) is a register level interface that allows host software to
12communicate with a non-volatile memory subsystem. This interface is optimized
13for enterprise and client solid state drives, typically attached to the PCI
14express interface. It is a scalable host controller interface designed to
15address the needs of enterprise and client systems that utilize PCI express
16based solid state drives (SSD). The interface provides optimized command
17submission and completion paths. It includes support for parallel operation by
18supporting up to 64K I/O queues with up to 64K commands per I/O queue.
19
20The device is comprised of some number of controllers, where each controller
21is comprised of some number of namespaces, where each namespace is comprised
22of some number of logical blocks. A namespace is a quantity of non-volatile
23memory that is formatted into logical blocks. An NVMe namespace is equivalent
24to a SCSI LUN. Each namespace is operated as an independent "device".
25
26How it works
27------------
28There is an NVMe uclass driver (driver name "nvme"), an NVMe host controller
29driver (driver name "nvme") and an NVMe namespace block driver (driver name
30"nvme_blk"). The host controller driver is supposed to probe the hardware and
31do necessary initialization to put the controller into a ready state at which
32it is able to scan all available namespaces attached to it. Scanning namespace
33is triggered by the NVMe uclass driver and the actual work is done in the NVMe
34namespace block driver.
35
36Status
37------
38It only support basic block read/write functions in the NVMe driver.
39
40Config options
41--------------
42CONFIG_NVME	Enable NVMe device support
43CONFIG_NVME_PCI	Enable PCIe NVMe device support
44CONFIG_CMD_NVME	Enable basic NVMe commands
45
46Usage in U-Boot
47---------------
48To use an NVMe hard disk from U-Boot shell, a 'nvme scan' command needs to
49be executed for all NVMe hard disks attached to the NVMe controller to be
50identified.
51
52To list all of the NVMe hard disks, try:
53
54.. code-block:: none
55
56  => nvme info
57  Device 0: Vendor: 0x8086 Rev: 8DV10131 Prod: CVFT535600LS400BGN
58	    Type: Hard Disk
59	    Capacity: 381554.0 MB = 372.6 GB (781422768 x 512)
60
61and print out detailed information for controller and namespaces via:
62
63.. code-block:: none
64
65  => nvme detail
66
67Raw block read/write to can be done via the 'nvme read/write' commands:
68
69.. code-block:: none
70
71  => nvme read a0000000 0 11000
72
73  => tftp 80000000 /tftpboot/kernel.itb
74  => nvme write 80000000 0 11000
75
76Of course, file system command can be used on the NVMe hard disk as well:
77
78.. code-block:: none
79
80  => fatls nvme 0:1
81	32376967   kernel.itb
82	22929408   100m
83
84	2 file(s), 0 dir(s)
85
86  => fatload nvme 0:1 a0000000 /kernel.itb
87  => bootm a0000000
88
89Testing NVMe with QEMU x86
90--------------------------
91QEMU supports NVMe emulation and we can test NVMe driver with QEMU x86 running
92U-Boot. Please see README.x86 for how to build u-boot.rom image for QEMU x86.
93
94Example command line to call QEMU x86 below with emulated NVMe device:
95
96.. code-block:: bash
97
98  $ ./qemu-system-i386 -drive file=nvme.img,if=none,id=drv0 -device nvme,drive=drv0,serial=QEMUNVME0001 -bios u-boot.rom
99