system/devices/nvme.rst

5 QEMU provides NVMe emulation through the ``nvme``, ``nvme-ns`` and
6 ``nvme-subsys`` devices.
8 See the following sections for specific information on
12     `Simple Copy`_, `Zoned Namespaces`_, `metadata`_ and `End-to-End Data
19 --------------------
27   * Interrupt Coalescing is not supported and is disabled by default.
29 The simplest way to attach an NVMe controller on the QEMU PCI bus is to add the
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
41 ``max_ioqpairs=UINT32`` (default: ``64``)
45 ``msix_qsize=UINT16`` (default: ``65``)
46   The number of MSI-X vectors that the device should support.
48 ``mdts=UINT8`` (default: ``7``)
51 ``use-intel-id`` (default: ``off``)
53   Vendor ID. Set this to ``on`` to revert to the unallocated Intel ID
56 ``ocp`` (default: ``off``)
58   sits on top of NVMe. It describes additional commands and NVMe behaviors
59   specific for the Datacenter. When this option is ``on`` OCP features such as
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
84 ``nsid`` (default: ``0``)
87 ``uuid`` (default: *autogenerated*)
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
107   parameter on the controller device).
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:
127 ``shared`` (default: ``on`` since 6.2)
134 ``detached`` (default: ``off``)
135   If set to ``on``, the namespace will be be available in the subsystem, but
137   to ``on`` will never be automatically attached to controllers.
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
151 attached to any controller initially (due to ``detached=on``) or to hotplugged
158 ------------------------
162 ``cmb_size_mb=UINT32`` (default: ``0``)
166 ``legacy-cmb`` (default: ``off``)
167   By default, the device uses the "v1.4 scheme" for the Controller Memory
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
179 ``mssrl=UINT16`` (default: ``128``)
183 ``mcl=UINT32`` (default: ``128``)
188 ``msrc=UINT8`` (default: ``127``)
193 ----------------
196 ``zoned=on`` on an ``nvme-ns`` device to configure it as a zoned namespace.
200 ``zoned.zone_size=SIZE`` (default: ``128MiB``)
203 ``zoned.zone_capacity=SIZE`` (default: ``0``)
204   Define the zone capacity (``ZCAP``). If left at the default (``0``), the zone
207 ``zoned.descr_ext_size=UINT32`` (default: ``0``)
211 ``zoned.cross_read=BOOL`` (default: ``off``)
212   Set to ``on`` to allow reads to cross zone boundaries.
214 ``zoned.max_active=UINT32`` (default: ``0``)
215   Set the maximum number of active resources (``MAR``). The default (``0``)
218 ``zoned.max_open=UINT32`` (default: ``0``)
219   Set the maximum number of open resources (``MOR``). The default (``0``)
223 ``zoned.zasl=UINT8`` (default: ``0``)
226   the minimum memory page size (CAP.MPSMIN). The default value (``0``)
230 -----------------------
233 configuring it (``fdp=on``) on the subsystem::
235     -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0,fdp=on,fdp.nruh=16
237 The subsystem emulates a single Endurance Group, on which Flexible Data
239 slightly from the specification, by always enabling the "FDP Mode" feature on
242 Enabling Flexible Data Placement on the subsyste enables the following
245 ``fdp.nrg`` (default: ``1``)
248 ``fdp.nruh`` (default: ``0``)
250   must be non-zero.
252 ``fdp.runs`` (default: ``96M``)
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.
270 ``ms=UINT16`` (default: ``0``)
273 ``mset=UINT8`` (default: ``0``)
276 End-to-End Data Protection
277 --------------------------
279 The virtual namespace device supports DIF- and DIX-based protection information
280 (depending on ``mset``).
282 ``pi=UINT8`` (default: ``0``)
286 ``pil=UINT8`` (default: ``0``)
292 ``pif=UINT8`` (default: ``0``)
293   By default, the namespace device uses 16 bit guard protection information
298 Virtualization Enhancements and SR-IOV (Experimental Support)
299 -------------------------------------------------------------
303 an NVM Subsystem device (``nvme-subsys``) for use with SR-IOV.
308 ``sriov_max_vfs`` (default: ``0``)
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)``.
324 ``sriov_max_vi_per_vf`` (default: ``0``)
326   to a secondary controller. The default ``0`` resolves to
329 ``sriov_max_vq_per_vf`` (default: ``0``)
331   a secondary controller. The default ``0`` resolves to
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
353   * perform a Function Level Reset on the primary controller to actually
356 .. code-block:: console
362 .. code-block:: console
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