QEMU provides NVMe emulation through the
See the following sections for specific information on
Adding NVMe Devices¶
The QEMU emulated NVMe controller implements version 1.4 of the NVM Express specification. All mandatory features are implement with a couple of exceptions and limitations:
- Accounting numbers in the SMART/Health log page are reset when the device is power cycled.
- Interrupt Coalescing is not supported and is disabled by default.
The simplest way to attach an NVMe controller on the QEMU PCI bus is to add the following parameters:
-drive file=nvm.img,if=none,id=nvm -device nvme,serial=deadbeef,drive=nvm
There are a number of optional general parameters for the
nvme device. Some
are mentioned here, but see
-device nvme,help to list all possible
- Set the maximum number of allowed I/O queue pairs. This replaces the
- The number of MSI-X vectors that the device should support.
- Set the Maximum Data Transfer Size of the device.
- Since QEMU 5.2, the device uses a QEMU allocated “Red Hat” PCI Device and
Vendor ID. Set this to
onto revert to the unallocated Intel ID previously used.
In the simplest possible invocation sketched above, the device only support a
single namespace with the namespace identifier
1. To support multiple
namespaces and additional features, the
nvme-ns device must be used.
-device nvme,id=nvme-ctrl-0,serial=deadbeef -drive file=nvm-1.img,if=none,id=nvm-1 -device nvme-ns,drive=nvm-1 -drive file=nvm-2.img,if=none,id=nvm-2 -device nvme-ns,drive=nvm-2
The namespaces defined by the
nvme-ns device will attach to the most
nvme-bus that is created by the
nvme device. Namespace
identifiers are allocated automatically, starting from
There are a number of parameters available:
- Explicitly set the namespace identifier.
- Set the UUID of the namespace. This will be reported as a “Namespace UUID” descriptor in the Namespace Identification Descriptor List.
- Set the EUI-64 of the namespace. This will be reported as a “IEEE Extended Unique Identifier” descriptor in the Namespace Identification Descriptor List. Since machine type 6.1 a non-zero default value is used if the parameter is not provided. For earlier machine types the field defaults to 0.
- If there are more
nvmedevices defined, this parameter may be used to attach the namespace to a specific
nvmedevice (identified by an
idparameter on the controller device).
Additional features becomes available if the controller device (
linked to an NVM Subsystem device (
The NVM Subsystem emulation allows features such as shared namespaces and multipath I/O.
-device nvme-subsys,id=nvme-subsys-0,nqn=subsys0 -device nvme,serial=a,subsys=nvme-subsys-0 -device nvme,serial=b,subsys=nvme-subsys-0
This will create an NVM subsystem with two controllers. Having controllers
linked to an
nvme-subsys device allows additional
- Specifies that the namespace will be attached to all controllers in the
subsystem. If set to
off, the namespace will remain a private namespace and may only be attached to a single controller at a time. Shared namespaces are always automatically attached to all controllers (also when controllers are hotplugged).
- If set to
on, the namespace will be be available in the subsystem, but not attached to any controllers initially. A shared namespace with this set to
onwill never be automatically attached to controllers.
-drive file=nvm-1.img,if=none,id=nvm-1 -device nvme-ns,drive=nvm-1,nsid=1 -drive file=nvm-2.img,if=none,id=nvm-2 -device nvme-ns,drive=nvm-2,nsid=3,shared=off,detached=on
will cause NSID 1 will be a shared namespace that is initially attached to both
controllers. NSID 3 will be a private namespace due to
shared=off and only
attachable to a single controller at a time. Additionally it will not be
attached to any controller initially (due to
detached=on) or to hotplugged
Controller Memory Buffer¶
nvme device parameters related to the Controller Memory Buffer support:
- This adds a Controller Memory Buffer of the given size at offset zero in BAR 2.
- By default, the device uses the “v1.4 scheme” for the Controller Memory
Buffer support (i.e, the CMB is initially disabled and must be explicitly
enabled by the host). Set this to
onto behave as a v1.3 device wrt. the CMB.
The device includes support for TP 4065 (“Simple Copy Command”). A number of
nvme-ns device parameters may be used to control the Copy
- Set the Maximum Single Source Range Length (
MSSRL). This is the maximum number of logical blocks that may be specified in each source range.
- Set the Maximum Copy Length (
MCL). This is the maximum number of logical blocks that may be specified in a Copy command (the total for all source ranges).
- Set the Maximum Source Range Count (
MSRC). This is the maximum number of source ranges that may be used in a Copy command. This is a 0’s based value.
A namespaces may be “Zoned” as defined by TP 4053 (“Zoned Namespaces”). Set
zoned=on on an
nvme-ns device to configure it as a zoned namespace.
The namespace may be configured with additional parameters
- Define the zone size (
- Define the zone capacity (
ZCAP). If left at the default (
0), the zone capacity will equal the zone size.
- Set the Zone Descriptor Extension Size (
ZDES). Must be a multiple of 64 bytes.
- Set to
onto allow reads to cross zone boundaries.
- Set the maximum number of active resources (
MAR). The default (
0) allows all zones to be active.
- Set the maximum number of open resources (
MOR). The default (
0) allows all zones to be open. If
zoned.max_activeis specified, this value must be less than or equal to that.
- Set the maximum data transfer size for the Zone Append command. Like
mdts, the value is specified as a power of two (2^n) and is in units of the minimum memory page size (CAP.MPSMIN). The default value (
0) has this property inherit the
The virtual namespace device supports LBA metadata in the form separate
MPTR-based) and extended LBAs.
- Defines the number of metadata bytes per LBA.
- Set to
1to enable extended LBAs.
End-to-End Data Protection¶
The virtual namespace device supports DIF- and DIX-based protection information
- Enable protection information of the specified type (type
- Controls the location of the protection information within the metadata. Set
1to transfer protection information as the first eight bytes of metadata. Otherwise, the protection information is transferred as the last eight bytes.