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
42   Set the maximum number of allowed I/O queue pairs. This replaces the
46   The number of MSI-X vectors that the device should support.
49   Set the Maximum Data Transfer Size of the device.
51 ``use-intel-id`` (default: ``off``)
53   Vendor ID. Set this to ``on`` to revert to the unallocated Intel ID
64 ---------------------
68 namespaces and additional features, the ``nvme-ns`` device must be used.
70 .. code-block:: console
72    -device nvme,id=nvme-ctrl-0,serial=deadbeef
73    -drive file=nvm-1.img,if=none,id=nvm-1
74    -device nvme-ns,drive=nvm-1
75    -drive file=nvm-2.img,if=none,id=nvm-2
76    -device nvme-ns,drive=nvm-2
78 The namespaces defined by the ``nvme-ns`` device will attach to the most
79 recently defined ``nvme-bus`` that is created by the ``nvme`` device. Namespace
85   Explicitly set the namespace identifier.
88   Set the UUID of the namespace. This will be reported as a "Namespace UUID"
92   Set the NGUID of the namespace. This will be reported as a "Namespace Globally
95   or "auto" for a random value. An optional '-' separator could be used to group
99   Set the EUI-64 of the namespace. This will be reported as a "IEEE Extended
101   Since machine type 6.1 a non-zero default value is used if the parameter
110 --------------
113 linked to an NVM Subsystem device (``nvme-subsys``).
118 .. code-block:: console
120    -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0
121    -device nvme,serial=deadbeef,subsys=nvme-subsys-0
122    -device nvme,serial=deadbeef,subsys=nvme-subsys-0
125 linked to an ``nvme-subsys`` device allows additional ``nvme-ns`` parameters:
129   subsystem. If set to ``off``, the namespace will remain a private namespace
135   If set to ``on``, the namespace will be be available in the subsystem, but
136   not attached to any controllers initially. A shared namespace with this set
141 .. code-block:: console
143    -drive file=nvm-1.img,if=none,id=nvm-1
144    -device nvme-ns,drive=nvm-1,nsid=1
145    -drive file=nvm-2.img,if=none,id=nvm-2
146    -device nvme-ns,drive=nvm-2,nsid=3,shared=off,detached=on
158 ------------------------
166 ``legacy-cmb`` (default: ``off``)
169   enabled by the host). Set this to ``on`` to behave as a v1.3 device wrt. the
173 -----------
176 additional ``nvme-ns`` device parameters may be used to control the Copy
180   Set the Maximum Single Source Range Length (``MSSRL``). This is the maximum
184   Set the Maximum Copy Length (``MCL``). This is the maximum number of logical
189   Set the Maximum Source Range Count (``MSRC``). This is the maximum number of
193 ----------------
195 A namespaces may be "Zoned" as defined by TP 4053 ("Zoned Namespaces"). Set
196 ``zoned=on`` on an ``nvme-ns`` device to configure it as a zoned namespace.
208   Set the Zone Descriptor Extension Size (``ZDES``). Must be a multiple of 64
212   Set to ``on`` to allow reads to cross zone boundaries.
215   Set the maximum number of active resources (``MAR``). The default (``0``)
219   Set the maximum number of open resources (``MOR``). The default (``0``)
224   Set the maximum data transfer size for the Zone Append command. Like
230 -----------------------
235     -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0,fdp=on,fdp.nruh=16
246   Set the number of Reclaim Groups.
249   Set the number of Reclaim Unit Handles. This is a mandatory parameter and
250   must be non-zero.
253   Set the Reclaim Unit Nominal Size. Defaults to 96 MiB.
257     -device nvme-ns,drive=nvm-1,fdp.ruhs=RUHLIST
260 include ranges (i.e. ``0;8-15``). If no reclaim unit handle list is specified,
261 the controller will assign the controller-specified reclaim unit handle to
265 --------
268 metadata (``MPTR``-based) and extended LBAs.
274   Set to ``1`` to enable extended LBAs.
276 End-to-End Data Protection
277 --------------------------
279 The virtual namespace device supports DIF- and DIX-based protection information
287   Controls the location of the protection information within the metadata. Set
294   format (``pif=0``). Set to ``2`` to enable 64 bit guard protection
298 Virtualization Enhancements and SR-IOV (Experimental Support)
299 -------------------------------------------------------------
303 an NVM Subsystem device (``nvme-subsys``) for use with SR-IOV.
310   by the controller. Specifying a non-zero value enables reporting of both
311   SR-IOV and ARI (Alternative Routing-ID Interpretation) capabilities
312   by the NVMe device. Virtual function controllers will not report SR-IOV.
317   controller's private resources to ``(max_ioqpairs - sriov_vq_flexible)``.
322   controller's private resources to ``(msix_qsize - sriov_vi_flexible)``.
334 The simplest possible invocation enables the capability to set up one VF
335 controller and assign an admin queue, an IO queue, and a MSI-X interrupt.
337 .. code-block:: console
339    -device nvme-subsys,id=subsys0
340    -device nvme,serial=deadbeef,subsys=subsys0,sriov_max_vfs=1,
348 .. code-block:: console
350    nvme virt-mgmt /dev/nvme0 -c 0 -r 1 -a 1 -n 0
351    nvme virt-mgmt /dev/nvme0 -c 0 -r 0 -a 1 -n 0
356 .. code-block:: console
362 .. code-block:: console
366   * assign the flexible resources to the VF and set it ONLINE
368 .. code-block:: console
370    nvme virt-mgmt /dev/nvme0 -c 1 -r 1 -a 8 -n 1
371    nvme virt-mgmt /dev/nvme0 -c 1 -r 0 -a 8 -n 2
372    nvme virt-mgmt /dev/nvme0 -c 1 -r 0 -a 9 -n 0
376 .. code-block:: console