1.. _disk_nvme:
2
3NVMe
4####
5
6NVMe is a standardized logical device interface on PCIe bus exposing storage devices.
7
8NVMe controllers and disks are supported. Disks can be accessed via the :ref:`Disk Access API <disk_access_api>` they expose
9and thus be used through the :ref:`File System API <file_system_api>`.
10
11Driver design
12*************
13
14The driver is sliced up in 3 main parts:
15
16- NVMe controller: :zephyr_file:`drivers/disk/nvme/nvme_controller.c`
17- NVMe commands: :zephyr_file:`drivers/disk/nvme/nvme_cmd.c`
18- NVMe namespace: :zephyr_file:`drivers/disk/nvme/nvme_namespace.c`
19
20Where the NVMe controller is the root of the device driver. This is the one that will get device driver instances.
21Note that this is only what DTS describes: the NVMe controller, and none of its namespaces (disks).
22The NVMe command is the generic logic used to communicate with the controller and the namespaces it exposes.
23Finally the NVMe namespace is the dedicated part to deal with an actual namespace which, in turn, enables applications
24accessing each ones through the Disk Access API :zephyr_file:`drivers/disk/nvme/nvme_disk.c`.
25
26If a controller exposes more than 1 namespace (disk), it will be possible to raise the amount of built-in namespace support
27by tweaking the configuration option CONFIG_NVME_MAX_NAMESPACES (see below).
28
29Each exposed disk, via it's related disk_info structure, will be distinguished by its name which is inherited from
30it's related namespace. As such, the disk name follows NVMe naming which is nvme<k>n<n> where k is the controller number
31and n the namespame number. Most of the time, if only one NVMe disk is plugged into the system, one will see 'nvme0n0' as
32an exposed disk.
33
34NVMe configuration
35******************
36
37DTS
38===
39
40Any board exposing an NVMe disk should provide a DTS overlay to enable its use within Zephyr
41
42.. code-block:: devicetree
43
44    #include <zephyr/dt-bindings/pcie/pcie.h>
45    / {
46        pcie0 {
47            nvme0: nvme0 {
48                compatible = "nvme-controller";
49                vendor-id = <VENDOR_ID>;
50                device-id = <DEVICE_ID>;
51                status = "okay";
52            };
53        };
54    };
55
56Where VENDOR_ID and DEVICE_ID are the ones from the exposed NVMe controller.
57
58Options
59=======
60
61* :kconfig:option:`CONFIG_NVME`
62
63Note that NVME requires the target to support PCIe multi-vector MSI-X in order to function.
64
65* :kconfig:option:`CONFIG_NVME_MAX_NAMESPACES`
66
67Important note for users
68************************
69
70NVMe specifications mandate the data buffer to be placed in a dword (4 bytes) aligned address.
71While this is not a problem for advanced OS managing virtual memory and dynamic allocations
72below the user processes, this can become an issue in Zephyr as soon as buffer addresses
73map directly to physical memory.
74
75At this stage then, it is up to the user to make sure the buffer address being provided to
76:c:func:`disk_access_read` and :c:func:`disk_access_write` are dword aligned.
77