From: Klaus Jensen <its@irrelevant.dk>
To: qemu-devel@nongnu.org
Cc: "Fam Zheng" <fam@euphon.net>, "Kevin Wolf" <kwolf@redhat.com>,
"Daniel P. Berrangé" <berrange@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>,
qemu-block@nongnu.org,
"Philippe Mathieu-Daudé" <philmd@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Klaus Jensen" <its@irrelevant.dk>,
"Hanna Reitz" <hreitz@redhat.com>,
"Hannes Reinecke" <hare@suse.de>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
"Klaus Jensen" <k.jensen@samsung.com>,
"Keith Busch" <kbusch@kernel.org>,
"Paolo Bonzini" <pbonzini@redhat.com>,
"Eric Blake" <eblake@redhat.com>
Subject: [PATCH RFC v2 16/16] docs: add documentation for experimental nvme emulation
Date: Mon, 27 Sep 2021 07:17:59 +0200 [thread overview]
Message-ID: <20210927051759.447305-17-its@irrelevant.dk> (raw)
In-Reply-To: <20210927051759.447305-1-its@irrelevant.dk>
From: Klaus Jensen <k.jensen@samsung.com>
Signed-off-by: Klaus Jensen <k.jensen@samsung.com>
---
docs/system/device-emulation.rst | 1 +
docs/system/devices/nvme-experimental.rst | 107 ++++++++++++++++++++++
2 files changed, 108 insertions(+)
create mode 100644 docs/system/devices/nvme-experimental.rst
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 7afcfd8064ae..9a4e08e4ea44 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -85,6 +85,7 @@ Emulated Devices
devices/ivshmem.rst
devices/net.rst
devices/nvme.rst
+ devices/nvme-experimental.rst
devices/usb.rst
devices/vhost-user.rst
devices/virtio-pmem.rst
diff --git a/docs/system/devices/nvme-experimental.rst b/docs/system/devices/nvme-experimental.rst
new file mode 100644
index 000000000000..d3b94dc3ef59
--- /dev/null
+++ b/docs/system/devices/nvme-experimental.rst
@@ -0,0 +1,107 @@
+===========================
+Experimental NVMe Emulation
+===========================
+
+QEMU offers experimental NVMe emulation through the ``x-nvme-ctrl`` device and
+the ``x-nvme-subsystem`` and ``x-nvme-ns-{nvm,zoned}`` objects.
+
+
+Adding NVMe Devices
+===================
+
+Controller Emulation
+--------------------
+
+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:
+
+.. code-block:: console
+
+ -object x-nvme-subsystem,id=nvme-subsys-0
+ -device x-nvme-ctrl,subsys=nvme-subsys-0
+
+There are a number of optional general parameters for the ``x-nvme-ctrl``
+device. Some are mentioned here, but see ``-device x-nvme-ctrl,help`` to list
+all possible parameters.
+
+``max-ioqpairs=UINT32`` (default: ``64``)
+ Set the maximum number of allowed I/O queue pairs.
+
+``msix-vectors=UINT16`` (default: ``65``)
+ The number of MSI-X vectors that the device should support.
+
+``mdts=UINT8`` (default: ``7``)
+ Set the Maximum Data Transfer Size of the device.
+
+
+Additional Namespaces
+---------------------
+
+The invocation sketched above does not add any namespaces to the subsystem. To
+add these, add ``x-nvme-ns-NSTYPE`` (where ``NSTYPE`` is either ``nvm`` or
+``zoned``) objects with attached blockdevs and a reference to the subsystem:
+
+.. code-block:: console
+
+ -blockdev file,node-name=blk-file-nvm-1,filename=nvm-1.img
+ -blockdev raw,node-name=blk-nvm-1,file=blk-file-nvm-1
+ -object x-nvme-ns-nvm,id=nvm-1,blockdev=blk-nvm-1,subsys=nvme-subsys-0
+
+There are a number of optional parameters available (common to both the ``nvm``
+and ``zoned`` namespace types):
+
+``nsid`` (default: ``"auto"``)
+ Explicitly set the namespace identifier. If left at the default, the
+ subsystem will allocate the next available identifier.
+
+``uuid`` (default: ``"auto"``)
+ Set the UUID of the namespace. This will be reported as a "Namespace UUID"
+ descriptor in the Namespace Identification Descriptor List. If left at the
+ default, a UUID will be generated.
+
+``eui64`` (default: ``"auto"``)
+ Set the EUI-64 of the namespace. This will be reported as a "IEEE Extended
+ Unique Identifier" descriptor in the Namespace Identification Descriptor
+ List. If left at the default, an identifier prefixed with the QEMU IEEE OUI
+ (``52:54:00``) will be generated.
+
+``lba-size`` (default: ``4096``)
+ Set the logical block size.
+
+Namespaces support LBA metadata in the form separate metadata (``MPTR``-based)
+and extended LBAs.
+
+``metadata-size`` (default: ``0``)
+ Defines the number of metadata bytes per LBA.
+
+``extended-lba`` (default: ``off/false``)
+ Set to ``on/true`` to enable extended LBAs.
+
+With metadata configured, namespaces support DIF- and DIX-based protection
+information (depending on ``extended-lba``).
+
+``pi-type`` (default: ``"none"``)
+ Enable protection information of the specified type (type ``"type1"``,
+ ``"type2"`` or ``"type3"``).
+
+``pi-first`` (default: ``off/false``)
+ Controls the location of the protection information within the metadata. Set
+ to ``on/true`` to transfer protection information as the first eight bytes of
+ metadata. Otherwise, the protection information is transferred as the last
+ eight bytes.
+
+The ``zoned`` namespace type has additional parameters:
+
+``zone-size`` (default: ``4096``)
+ The number of LBAs in a zone.
+
+``zone-capacity`` (default: ``4096``)
+ The number of writable LBAs in a zone.
--
2.33.0
prev parent reply other threads:[~2021-09-27 5:45 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-27 5:17 [PATCH RFC v2 00/16] hw/nvme: experimental user-creatable objects Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 01/16] hw/nvme: reattach subsystem namespaces on hotplug Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 02/16] hw/nvme: change nvme-ns 'shared' default Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 03/16] hw/nvme: move dif/pi prototypes into dif.h Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 04/16] hw/nvme: move zns helpers and types into zns.h Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 05/16] hw/nvme: move zoned namespace members to separate struct Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 06/16] hw/nvme: move nvm " Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 07/16] hw/nvme: move BlockBackend to NvmeNamespaceNvm Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 08/16] hw/nvme: hoist qdev state from namespace Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 09/16] hw/nvme: hoist qdev state from subsystem Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 10/16] hw/nvme: hoist qdev state from controller Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 11/16] hw/nvme: add experimental object x-nvme-subsystem Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 12/16] nvme: add structured type for nguid Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 13/16] hw/nvme: add experimental abstract object x-nvme-ns Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 14/16] hw/nvme: add experimental objects x-nvme-ns-{nvm, zoned} Klaus Jensen
2021-09-27 5:17 ` [PATCH RFC v2 15/16] hw/nvme: add experimental device x-nvme-ctrl Klaus Jensen
2021-09-27 5:17 ` Klaus Jensen [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210927051759.447305-17-its@irrelevant.dk \
--to=its@irrelevant.dk \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=eblake@redhat.com \
--cc=ehabkost@redhat.com \
--cc=fam@euphon.net \
--cc=hare@suse.de \
--cc=hreitz@redhat.com \
--cc=k.jensen@samsung.com \
--cc=kbusch@kernel.org \
--cc=kwolf@redhat.com \
--cc=pbonzini@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).