docs/system/nvme.rst

   1 ==============
   2 NVMe Emulation
   3 ==============
   4
   5 QEMU provides NVMe emulation through the ``nvme``, ``nvme-ns`` and
   6 ``nvme-subsys`` devices.
   7
   8 See the following sections for specific information on
   9
  10   * `Adding NVMe Devices`_, `additional namespaces`_ and `NVM subsystems`_.
  11   * Configuration of `Optional Features`_ such as `Controller Memory Buffer`_,
  12     `Simple Copy`_, `Zoned Namespaces`_, `metadata`_ and `End-to-End Data
  13     Protection`_,
  14
  15 Adding NVMe Devices
  16 ===================
  17
  18 Controller Emulation
  19 --------------------
  20
  21 The QEMU emulated NVMe controller implements version 1.4 of the NVM Express
  22 specification. All mandatory features are implement with a couple of exceptions
  23 and limitations:
  24
  25   * Accounting numbers in the SMART/Health log page are reset when the device
  26     is power cycled.
  27   * Interrupt Coalescing is not supported and is disabled by default.
  28
  29 The simplest way to attach an NVMe controller on the QEMU PCI bus is to add the
  30 following parameters:
  31
  32 .. code-block:: console
  33
  34     -drive file=nvm.img,if=none,id=nvm
  35     -device nvme,serial=deadbeef,drive=nvm
  36
  37 There are a number of optional general parameters for the ``nvme`` device. Some
  38 are mentioned here, but see ``-device nvme,help`` to list all possible
  39 parameters.
  40
  41 ``max_ioqpairs=UINT32`` (default: ``64``)
  42   Set the maximum number of allowed I/O queue pairs. This replaces the
  43   deprecated ``num_queues`` parameter.
  44
  45 ``msix_qsize=UINT16`` (default: ``65``)
  46   The number of MSI-X vectors that the device should support.
  47
  48 ``mdts=UINT8`` (default: ``7``)
  49   Set the Maximum Data Transfer Size of the device.
  50
  51 ``use-intel-id`` (default: ``off``)
  52   Since QEMU 5.2, the device uses a QEMU allocated "Red Hat" PCI Device and
  53   Vendor ID. Set this to ``on`` to revert to the unallocated Intel ID
  54   previously used.
  55
  56 Additional Namespaces
  57 ---------------------
  58
  59 In the simplest possible invocation sketched above, the device only support a
  60 single namespace with the namespace identifier ``1``. To support multiple
  61 namespaces and additional features, the ``nvme-ns`` device must be used.
  62
  63 .. code-block:: console
  64
  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
  70
  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
  73 identifers are allocated automatically, starting from ``1``.
  74
  75 There are a number of parameters available:
  76
  77 ``nsid`` (default: ``0``)
  78   Explicitly set the namespace identifier.
  79
  80 ``uuid`` (default: *autogenerated*)
  81   Set the UUID of the namespace. This will be reported as a "Namespace UUID"
  82   descriptor in the Namespace Identification Descriptor List.
  83
  84 ``bus``
  85   If there are more ``nvme`` devices defined, this parameter may be used to
  86   attach the namespace to a specific ``nvme`` device (identified by an ``id``
  87   parameter on the controller device).
  88
  89 NVM Subsystems
  90 --------------
  91
  92 Additional features becomes available if the controller device (``nvme``) is
  93 linked to an NVM Subsystem device (``nvme-subsys``).
  94
  95 The NVM Subsystem emulation allows features such as shared namespaces and
  96 multipath I/O.
  97
  98 .. code-block:: console
  99
 100    -device nvme-subsys,id=nvme-subsys-0,nqn=subsys0
 101    -device nvme,serial=a,subsys=nvme-subsys-0
 102    -device nvme,serial=b,subsys=nvme-subsys-0
 103
 104 This will create an NVM subsystem with two controllers. Having controllers
 105 linked to an ``nvme-subsys`` device allows additional ``nvme-ns`` parameters:
 106
 107 ``shared`` (default: ``off``)
 108   Specifies that the namespace will be attached to all controllers in the
 109   subsystem. If set to ``off`` (the default), the namespace will remain a
 110   private namespace and may only be attached to a single controller at a time.
 111
 112 ``detached`` (default: ``off``)
 113   If set to ``on``, the namespace will be be available in the subsystem, but
 114   not attached to any controllers initially.
 115
 116 Thus, adding
 117
 118 .. code-block:: console
 119
 120    -drive file=nvm-1.img,if=none,id=nvm-1
 121    -device nvme-ns,drive=nvm-1,nsid=1,shared=on
 122    -drive file=nvm-2.img,if=none,id=nvm-2
 123    -device nvme-ns,drive=nvm-2,nsid=3,detached=on
 124
 125 will cause NSID 1 will be a shared namespace (due to ``shared=on``) that is
 126 initially attached to both controllers. NSID 3 will be a private namespace
 127 (i.e. only attachable to a single controller at a time) and will not be
 128 attached to any controller initially (due to ``detached=on``).
 129
 130 Optional Features
 131 =================
 132
 133 Controller Memory Buffer
 134 ------------------------
 135
 136 ``nvme`` device parameters related to the Controller Memory Buffer support:
 137
 138 ``cmb_size_mb=UINT32`` (default: ``0``)
 139   This adds a Controller Memory Buffer of the given size at offset zero in BAR
 140   2.
 141
 142 ``legacy-cmb`` (default: ``off``)
 143   By default, the device uses the "v1.4 scheme" for the Controller Memory
 144   Buffer support (i.e, the CMB is initially disabled and must be explicitly
 145   enabled by the host). Set this to ``on`` to behave as a v1.3 device wrt. the
 146   CMB.
 147
 148 Simple Copy
 149 -----------
 150
 151 The device includes support for TP 4065 ("Simple Copy Command"). A number of
 152 additional ``nvme-ns`` device parameters may be used to control the Copy
 153 command limits:
 154
 155 ``mssrl=UINT16`` (default: ``128``)
 156   Set the Maximum Single Source Range Length (``MSSRL``). This is the maximum
 157   number of logical blocks that may be specified in each source range.
 158
 159 ``mcl=UINT32`` (default: ``128``)
 160   Set the Maximum Copy Length (``MCL``). This is the maximum number of logical
 161   blocks that may be specified in a Copy command (the total for all source
 162   ranges).
 163
 164 ``msrc=UINT8`` (default: ``127``)
 165   Set the Maximum Source Range Count (``MSRC``). This is the maximum number of
 166   source ranges that may be used in a Copy command. This is a 0's based value.
 167
 168 Zoned Namespaces
 169 ----------------
 170
 171 A namespaces may be "Zoned" as defined by TP 4053 ("Zoned Namespaces"). Set
 172 ``zoned=on`` on an ``nvme-ns`` device to configure it as a zoned namespace.
 173
 174 The namespace may be configured with additional parameters
 175
 176 ``zoned.zone_size=SIZE`` (default: ``128MiB``)
 177   Define the zone size (``ZSZE``).
 178
 179 ``zoned.zone_capacity=SIZE`` (default: ``0``)
 180   Define the zone capacity (``ZCAP``). If left at the default (``0``), the zone
 181   capacity will equal the zone size.
 182
 183 ``zoned.descr_ext_size=UINT32`` (default: ``0``)
 184   Set the Zone Descriptor Extension Size (``ZDES``). Must be a multiple of 64
 185   bytes.
 186
 187 ``zoned.cross_read=BOOL`` (default: ``off``)
 188   Set to ``on`` to allow reads to cross zone boundaries.
 189
 190 ``zoned.max_active=UINT32`` (default: ``0``)
 191   Set the maximum number of active resources (``MAR``). The default (``0``)
 192   allows all zones to be active.
 193
 194 ``zoned.max_open=UINT32`` (default: ``0``)
 195   Set the maximum number of open resources (``MOR``). The default (``0``)
 196   allows all zones to be open. If ``zoned.max_active`` is specified, this value
 197   must be less than or equal to that.
 198
 199 Metadata
 200 --------
 201
 202 The virtual namespace device supports LBA metadata in the form separate
 203 metadata (``MPTR``-based) and extended LBAs.
 204
 205 ``ms=UINT16`` (default: ``0``)
 206   Defines the number of metadata bytes per LBA.
 207
 208 ``mset=UINT8`` (default: ``0``)
 209   Set to ``1`` to enable extended LBAs.
 210
 211 End-to-End Data Protection
 212 --------------------------
 213
 214 The virtual namespace device supports DIF- and DIX-based protection information
 215 (depending on ``mset``).
 216
 217 ``pi=UINT8`` (default: ``0``)
 218   Enable protection information of the specified type (type ``1``, ``2`` or
 219   ``3``).
 220
 221 ``pil=UINT8`` (default: ``0``)
 222   Controls the location of the protection information within the metadata. Set
 223   to ``1`` to transfer protection information as the first eight bytes of
 224   metadata. Otherwise, the protection information is transferred as the last
 225   eight bytes.