system/devices/nvme.rst

5 QEMU provides NVMe emulation through the ``nvme``, ``nvme-ns`` and
6 ``nvme-subsys`` devices.
12     `Simple Copy`_, `Zoned Namespaces`_, `metadata`_ and `End-to-End Data
19 --------------------
32 .. code-block:: console
34     -drive file=nvm.img,if=none,id=nvm
35     -device nvme,serial=deadbeef,drive=nvm
38 are mentioned here, but see ``-device nvme,help`` to list all possible
46   The number of MSI-X vectors that the device should support.
51 ``use-intel-id`` (default: ``off``)
57 ---------------------
61 namespaces and additional features, the ``nvme-ns`` device must be used.
63 .. code-block:: console
65    -device nvme,id=nvme-ctrl-0,serial=deadbeef
66    -drive file=nvm-1.img,if=none,id=nvm-1
67    -device nvme-ns,drive=nvm-1
68    -drive file=nvm-2.img,if=none,id=nvm-2
69    -device nvme-ns,drive=nvm-2
71 The namespaces defined by the ``nvme-ns`` device will attach to the most
72 recently defined ``nvme-bus`` that is created by the ``nvme`` device. Namespace
88   or "auto" for a random value. An optional '-' separator could be used to group
92   Set the EUI-64 of the namespace. This will be reported as a "IEEE Extended
94   Since machine type 6.1 a non-zero default value is used if the parameter
103 --------------
106 linked to an NVM Subsystem device (``nvme-subsys``).
111 .. code-block:: console
113    -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0
114    -device nvme,serial=deadbeef,subsys=nvme-subsys-0
115    -device nvme,serial=deadbeef,subsys=nvme-subsys-0
118 linked to an ``nvme-subsys`` device allows additional ``nvme-ns`` parameters:
134 .. code-block:: console
136    -drive file=nvm-1.img,if=none,id=nvm-1
137    -device nvme-ns,drive=nvm-1,nsid=1
138    -drive file=nvm-2.img,if=none,id=nvm-2
139    -device nvme-ns,drive=nvm-2,nsid=3,shared=off,detached=on
151 ------------------------
159 ``legacy-cmb`` (default: ``off``)
166 -----------
169 additional ``nvme-ns`` device parameters may be used to control the Copy
173   Set the Maximum Single Source Range Length (``MSSRL``). This is the maximum
174   number of logical blocks that may be specified in each source range.
178   blocks that may be specified in a Copy command (the total for all source
182   Set the Maximum Source Range Count (``MSRC``). This is the maximum number of
183   source ranges that may be used in a Copy command. This is a 0's based value.
186 ----------------
189 ``zoned=on`` on an ``nvme-ns`` device to configure it as a zoned namespace.
212   Set the maximum number of open resources (``MOR``). The default (``0``)
213   allows all zones to be open. If ``zoned.max_active`` is specified, this value
223 -----------------------
228     -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0,fdp=on,fdp.nruh=16
243   must be non-zero.
250     -device nvme-ns,drive=nvm-1,fdp.ruhs=RUHLIST
253 include ranges (i.e. ``0;8-15``). If no reclaim unit handle list is specified,
254 the controller will assign the controller-specified reclaim unit handle to
258 --------
261 metadata (``MPTR``-based) and extended LBAs.
269 End-to-End Data Protection
270 --------------------------
272 The virtual namespace device supports DIF- and DIX-based protection information
291 Virtualization Enhancements and SR-IOV (Experimental Support)
292 -------------------------------------------------------------
296 an NVM Subsystem device (``nvme-subsys``) for use with SR-IOV.
303   by the controller. Specifying a non-zero value enables reporting of both
304   SR-IOV and ARI (Alternative Routing-ID Interpretation) capabilities
305   by the NVMe device. Virtual function controllers will not report SR-IOV.
310   controller's private resources to ``(max_ioqpairs - sriov_vq_flexible)``.
315   controller's private resources to ``(msix_qsize - sriov_vi_flexible)``.
328 controller and assign an admin queue, an IO queue, and a MSI-X interrupt.
330 .. code-block:: console
332    -device nvme-subsys,id=subsys0
333    -device nvme,serial=deadbeef,subsys=subsys0,sriov_max_vfs=1,
341 .. code-block:: console
343    nvme virt-mgmt /dev/nvme0 -c 0 -r 1 -a 1 -n 0
344    nvme virt-mgmt /dev/nvme0 -c 0 -r 0 -a 1 -n 0
349 .. code-block:: console
355 .. code-block:: console
361 .. code-block:: console
363    nvme virt-mgmt /dev/nvme0 -c 1 -r 1 -a 8 -n 1
364    nvme virt-mgmt /dev/nvme0 -c 1 -r 0 -a 8 -n 2
365    nvme virt-mgmt /dev/nvme0 -c 1 -r 0 -a 9 -n 0
369 .. code-block:: console