From nobody Sat Apr 20 00:46:21 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1617885317; cv=none; d=zohomail.com; s=zohoarc; b=F9j6DEGMsKjPHaswMkkKlaJm/jzf53tkKdIhN+xpKm5cwwuZZ9e4eY7YBNgzdP1qW+GSjaAH5ZWjA2HHuh5S1pKyjCF3y6klQ8rNkIQC6Hp8sKAOWgu6BMn2B5B4mhpg2f7hJN78Ls9iG4mnI+f/ngMAn/rqQMklqiHgQNoURGw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1617885317; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=N2JTTBQ42sYV9TreRFXcZGkdkLulzG1uVq1TbAkqx2w=; b=RlIBtLIHooqoc5Snviu2shKExaiPg77raV9vjMVYRgkhpnHt2CUsaBemUeevtBjKlNVTOB0hh4hsbKCZtRD0VD2GuomxMyF/TFu87D3AWQw+eyDVu46SvKSfW7LvGGqhxd1859OqJNGA4es3i7xfOHynj80MAuDgDYUH0AUbeno= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1617885317051314.68617026529876; Thu, 8 Apr 2021 05:35:17 -0700 (PDT) Received: from localhost ([::1]:39166 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lUTsR-00050i-NB for importer@patchew.org; Thu, 08 Apr 2021 08:35:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:44200) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lUTnw-0003LN-16; Thu, 08 Apr 2021 08:30:36 -0400 Received: from out5-smtp.messagingengine.com ([66.111.4.29]:40983) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lUTns-0005x0-ID; Thu, 08 Apr 2021 08:30:35 -0400 Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id 7D0055C00B1; Thu, 8 Apr 2021 08:30:30 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute4.internal (MEProxy); Thu, 08 Apr 2021 08:30:30 -0400 Received: from apples.local (80-167-98-190-cable.dk.customer.tdc.net [80.167.98.190]) by mail.messagingengine.com (Postfix) with ESMTPA id 96CB1108005C; Thu, 8 Apr 2021 08:30:28 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=irrelevant.dk; h=from:to:cc:subject:date:message-id:mime-version:content-type :content-transfer-encoding; s=fm2; bh=N2JTTBQ42sYV9TreRFXcZGkdkL ulzG1uVq1TbAkqx2w=; b=MAcn5ZbYGhHGaJKFYlkyGUqofbQNAkyX9B4q2DSQ3O XQUhdh0yv/V253UC7IklWTc8xwzbHAC3W/W5uSO+VCked1LloxOnsVTinPGvGPvZ CLlOlSvdqAnrdOIeCRbJkLhZ1O9IVUMvFxz8jsFgRQWwWf9rOggRStQBl3589Os/ IRtO1+qAQzcSsFLoIzxBUOzgMinPyPfuRHGvMxhMvLGYt5fJXEFc2838Y/wEwIzH 3mzVSlgbOgw3PhF1XrdRIcNBLE1tnjFVjIOvPew0x6ZdXj8ghNnxLoqto0Lb+EE/ zVLzHYkEqRPnS/xs7CeT2kumR1YX1cbJlqfU54u6Imqg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:message-id:mime-version:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; bh=N2JTTB Q42sYV9TreRFXcZGkdkLulzG1uVq1TbAkqx2w=; b=AiN35M93YlQxWrsja1lAj4 JOTByG88MDgpv9jPEsKgmKbvD/EGtlXZFoCl0ZXwbhe9HOupY6TAaQwdFyR8nenh Z6sC7pWQxl7hMlkN+lTGSg+Lm8vtnXl1NLjawbQrAmNnEWE2yEZ7uN8SZ8qKAlRV fbpybjpIxNbEWJSeNh887rV7TminDp2wnmzYeRGk96uIMe5pq0IpHUlmCCpIvkOy U6Q6jWtU1GJ1Pkw8XOMcw2YByqeOXdnfDSy6WVJxY5wVO0kfqkfsVJdmhUSLLU3J +8LNuXEFFMauNtme0OffSEx0Q9n+cyNKLDf0cD1c9BjHzrQhfbtDSh1NbWKbBLMQ == X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrudejledgheegucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkffogggtgfesthekredtredtjeenucfhrhhomhepmfhlrghushcu lfgvnhhsvghnuceoihhtshesihhrrhgvlhgvvhgrnhhtrdgukheqnecuggftrfgrthhtvg hrnhepfeejuedukeelieejgfffjeekgfeftdeihefggeeivdeigeegjedtlefgvdeuieek necuffhomhgrihhnpehnvhhmvgigphhrvghsshdrohhrghdpihhnfhhrrgguvggrugdroh hrghenucfkphepkedtrdduieejrdelkedrudeltdenucevlhhushhtvghrufhiiigvpedt necurfgrrhgrmhepmhgrihhlfhhrohhmpehithhssehirhhrvghlvghvrghnthdrughk X-ME-Proxy: From: Klaus Jensen To: qemu-devel@nongnu.org Subject: [PATCH v2] docs: add nvme emulation documentation Date: Thu, 8 Apr 2021 14:30:26 +0200 Message-Id: <20210408123026.410303-1-its@irrelevant.dk> X-Mailer: git-send-email 2.31.1 MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=66.111.4.29; envelope-from=its@irrelevant.dk; helo=out5-smtp.messagingengine.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Keith Busch , Klaus Jensen , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , qemu-block@nongnu.org, Klaus Jensen Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" From: Klaus Jensen Remove the docs/specs/nvme.txt and replace it with proper documentation in docs/system/nvme.rst. Signed-off-by: Klaus Jensen Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- v2: - add descriptions of the simple copy `mssrl`, `mcl` and `msrc` parameters. (philmd) docs/specs/nvme.txt | 23 ----- docs/system/index.rst | 1 + docs/system/nvme.rst | 225 ++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 2 +- 4 files changed, 227 insertions(+), 24 deletions(-) delete mode 100644 docs/specs/nvme.txt create mode 100644 docs/system/nvme.rst diff --git a/docs/specs/nvme.txt b/docs/specs/nvme.txt deleted file mode 100644 index 56d393884e7a..000000000000 --- a/docs/specs/nvme.txt +++ /dev/null @@ -1,23 +0,0 @@ -NVM Express Controller -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -The nvme device (-device nvme) emulates an NVM Express Controller. - - -Reference Specifications ------------------------- - -The device currently implements most mandatory features of NVMe v1.3d, see - - https://nvmexpress.org/resources/specifications/ - -for the specification. - - -Known issues ------------- - -* The accounting numbers in the SMART/Health are reset across power cycles - -* Interrupt Coalescing is not supported and is disabled by default in vola= tion - of the specification. diff --git a/docs/system/index.rst b/docs/system/index.rst index 02d07071810f..b05af716a973 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -23,6 +23,7 @@ Contents: net virtio-net-failover usb + nvme ivshmem linuxboot generic-loader diff --git a/docs/system/nvme.rst b/docs/system/nvme.rst new file mode 100644 index 000000000000..f7f63d6bf615 --- /dev/null +++ b/docs/system/nvme.rst @@ -0,0 +1,225 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +NVMe Emulation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +QEMU provides NVMe emulation through the ``nvme``, ``nvme-ns`` and +``nvme-subsys`` devices. + +See the following sections for specific information on + + * `Adding NVMe Devices`_, `additional namespaces`_ and `NVM subsystems`_. + * Configuration of `Optional Features`_ such as `Controller Memory Buffe= r`_, + `Simple Copy`_, `Zoned Namespaces`_, `metadata`_ and `End-to-End Data + Protection`_, + +Adding NVMe Devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 excep= tions +and limitations: + + * Accounting numbers in the SMART/Health log page are reset when the dev= ice + 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 ad= d the +following parameters: + +.. code-block:: console + + -drive file=3Dnvm.img,if=3Dnone,id=3Dnvm + -device nvme,serial=3Ddeadbeef,drive=3Dnvm + +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 +parameters. + +``max_ioqpairs=3DUINT32`` (default: ``64``) + Set the maximum number of allowed I/O queue pairs. This replaces the + deprecated ``num_queues`` parameter. + +``msix_qsize=3DUINT16`` (default: ``65``) + The number of MSI-X vectors that the device should support. + +``mdts=3DUINT8`` (default: ``7``) + Set the Maximum Data Transfer Size of the device. + +``use-intel-id`` (default: ``off``) + Since QEMU 5.2, the device uses a QEMU allocated "Red Hat" PCI Device and + Vendor ID. Set this to ``on`` to revert to the unallocated Intel ID + previously used. + +Additional Namespaces +--------------------- + +In the simplest possible invocation sketched above, the device only suppor= t a +single namespace with the namespace identifier ``1``. To support multiple +namespaces and additional features, the ``nvme-ns`` device must be used. + +.. code-block:: console + + -device nvme,id=3Dnvme-ctrl-0,serial=3Ddeadbeef + -drive file=3Dnvm-1.img,if=3Dnone,id=3Dnvm-1 + -device nvme-ns,drive=3Dnvm-1 + -drive file=3Dnvm-2.img,if=3Dnone,id=3Dnvm-2 + -device nvme-ns,drive=3Dnvm-2 + +The namespaces defined by the ``nvme-ns`` device will attach to the most +recently defined ``nvme-bus`` that is created by the ``nvme`` device. Name= space +identifers are allocated automatically, starting from ``1``. + +There are a number of parameters available: + +``nsid`` (default: ``0``) + Explicitly set the namespace identifier. + +``uuid`` (default: *autogenerated*) + Set the UUID of the namespace. This will be reported as a "Namespace UUI= D" + descriptor in the Namespace Identification Descriptor List. + +``bus`` + If there are more ``nvme`` devices defined, this parameter may be used to + attach the namespace to a specific ``nvme`` device (identified by an ``i= d`` + parameter on the controller device). + +NVM Subsystems +-------------- + +Additional features becomes available if the controller device (``nvme``) = is +linked to an NVM Subsystem device (``nvme-subsys``). + +The NVM Subsystem emulation allows features such as shared namespaces and +multipath I/O. + +.. code-block:: console + + -device nvme-subsys,id=3Dnvme-subsys-0,nqn=3Dsubsys0 + -device nvme,serial=3Da,subsys=3Dnvme-subsys-0 + -device nvme,serial=3Db,subsys=3Dnvme-subsys-0 + +This will create an NVM subsystem with two controllers. Having controllers +linked to an ``nvme-subsys`` device allows additional ``nvme-ns`` paramete= rs: + +``shared`` (default: ``off``) + Specifies that the namespace will be attached to all controllers in the + subsystem. If set to ``off`` (the default), the namespace will remain a + private namespace and may only be attached to a single controller at a t= ime. + +``detached`` (default: ``off``) + If set to ``on``, the namespace will be be available in the subsystem, b= ut + not attached to any controllers initially. + +Thus, adding + +.. code-block:: console + + -drive file=3Dnvm-1.img,if=3Dnone,id=3Dnvm-1 + -device nvme-ns,drive=3Dnvm-1,nsid=3D1,shared=3Don + -drive file=3Dnvm-2.img,if=3Dnone,id=3Dnvm-2 + -device nvme-ns,drive=3Dnvm-2,nsid=3D3,detached=3Don + +will cause NSID 1 will be a shared namespace (due to ``shared=3Don``) that= is +initially attached to both controllers. NSID 3 will be a private namespace +(i.e. only attachable to a single controller at a time) and will not be +attached to any controller initially (due to ``detached=3Don``). + +Optional Features +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Controller Memory Buffer +------------------------ + +``nvme`` device parameters related to the Controller Memory Buffer support: + +``cmb_size_mb=3DUINT32`` (default: ``0``) + This adds a Controller Memory Buffer of the given size at offset zero in= BAR + 2. + +``legacy-cmb`` (default: ``off``) + 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 ``on`` to behave as a v1.3 device wrt.= the + CMB. + +Simple Copy +----------- + +The device includes support for TP 4065 ("Simple Copy Command"). A number = of +additional ``nvme-ns`` device parameters may be used to control the Copy +command limits: + +``mssrl=3DUINT16`` (default: ``128``) + Set the Maximum Single Source Range Length (``MSSRL``). This is the maxi= mum + number of logical blocks that may be specified in each source range. + +``mcl=3DUINT32`` (default: ``128``) + Set the Maximum Copy Length (``MCL``). This is the maximum number of log= ical + blocks that may be specified in a Copy command (the total for all source + ranges). + +``msrc=3DUINT8`` (default: ``127``) + Set the Maximum Source Range Count (``MSRC``). This is the maximum numbe= r of + source ranges that may be used in a Copy command. This is a 0's based va= lue. + +Zoned Namespaces +---------------- + +A namespaces may be "Zoned" as defined by TP 4053 ("Zoned Namespaces"). Set +``zoned=3Don`` on an ``nvme-ns`` device to configure it as a zoned namespa= ce. + +The namespace may be configured with additional parameters + +``zoned.zone_size=3DSIZE`` (default: ``128MiB``) + Define the zone size (``ZSZE``). + +``zoned.zone_capacity=3DSIZE`` (default: ``0``) + Define the zone capacity (``ZCAP``). If left at the default (``0``), the= zone + capacity will equal the zone size. + +``zoned.descr_ext_size=3DUINT32`` (default: ``0``) + Set the Zone Descriptor Extension Size (``ZDES``). Must be a multiple of= 64 + bytes. + +``zoned.cross_read=3DBOOL`` (default: ``off``) + Set to ``on`` to allow reads to cross zone boundaries. + +``zoned.max_active=3DUINT32`` (default: ``0``) + Set the maximum number of active resources (``MAR``). The default (``0``) + allows all zones to be active. + +``zoned.max_open=3DUINT32`` (default: ``0``) + Set the maximum number of open resources (``MOR``). The default (``0``) + allows all zones to be open. If ``zoned.max_active`` is specified, this = value + must be less than or equal to that. + +Metadata +-------- + +The virtual namespace device supports LBA metadata in the form separate +metadata (``MPTR``-based) and extended LBAs. + +``ms=3DUINT16`` (default: ``0``) + Defines the number of metadata bytes per LBA. + +``mset=3DUINT8`` (default: ``0``) + Set to ``1`` to enable extended LBAs. + +End-to-End Data Protection +-------------------------- + +The virtual namespace device supports DIF- and DIX-based protection inform= ation +(depending on ``mset``). + +``pi=3DUINT8`` (default: ``0``) + Enable protection information of the specified type (type ``1``, ``2`` or + ``3``). + +``pil=3DUINT8`` (default: ``0``) + Controls the location of the protection information within the metadata.= Set + to ``1`` to transfer protection information as the first eight bytes of + metadata. Otherwise, the protection information is transferred as the la= st + eight bytes. diff --git a/MAINTAINERS b/MAINTAINERS index 58f342108e9e..04beb34e7ec4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1974,7 +1974,7 @@ S: Supported F: hw/block/nvme* F: include/block/nvme.h F: tests/qtest/nvme-test.c -F: docs/specs/nvme.txt +F: docs/system/nvme.rst T: git git://git.infradead.org/qemu-nvme.git nvme-next =20 megasas --=20 2.31.1