From patchwork Mon Sep 27 05:17:59 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Klaus Jensen X-Patchwork-Id: 12519141 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 40883C433F5 for ; Mon, 27 Sep 2021 05:45:54 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id C36D661157 for ; Mon, 27 Sep 2021 05:45:53 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org C36D661157 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=irrelevant.dk Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=nongnu.org Received: from localhost ([::1]:37958 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mUjSa-0006wW-KQ for qemu-devel@archiver.kernel.org; Mon, 27 Sep 2021 01:45:52 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34428) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mUj38-0004hZ-5g; Mon, 27 Sep 2021 01:19:36 -0400 Received: from wnew3-smtp.messagingengine.com ([64.147.123.17]:57839) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mUj36-0000fX-C6; Mon, 27 Sep 2021 01:19:33 -0400 Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.west.internal (Postfix) with ESMTP id D13402B0121F; Mon, 27 Sep 2021 01:19:09 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Mon, 27 Sep 2021 01:19:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=irrelevant.dk; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; s=fm1; bh=Xz3ePiKpJuH2U fpD1osQTpvITJuBpO640F6xyvxELF4=; b=YTUJ4pUu7Ky8H25J2VNHtaUdkZb2T AwM6tPdwG5m2vGUOwPT3hSn55a3cN7dqG/EREkM/981Lud2c7lvuPoQHVdryk3xm RDKf4QmIJqJsVGEcyVbAVY+E/3bxb1OLZDqLKtGIwjJim/VDpHPLwc3Hc1rx+Lnn L4BT417tIWu6Vu/JXLDTR8Mn9d0RgqPAggZhOvhHDRx+MjoH3q0XEz+qZUSptNR6 D6td9dIpKXnnW/sklmpAAg0ULH2+r2tQqvcfJn/TPcQHy59dIm3ifJHNVQiwOPqu yfTpXJ0q7bIqjhY3Ub14k0WsHHX3RRY6iDq3lOO25GXxfymyy9xLq2k2A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:date:from :in-reply-to:message-id:mime-version:references:subject:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; bh=Xz3ePiKpJuH2UfpD1osQTpvITJuBpO640F6xyvxELF4=; b=ltOMuFaz amP9lgJgl3niLwTPWiysLcKAR7tLMZ/HsWQ5RjEjM36LHloMh9vYVxagVLb8fpLL Wq2PNnLk5cAtpmMJRIHgVK6OP5w7u26DGMExZTSdjOPKHrkFPFRMQCukCmieJOEu AOhUfMrjA22Yba4Ro1b11rgoNOZ7vrNFOK58cNilf0PLMsNiKPrkXAqNfOtAg5yT TcAMF6SE9BCpSBmZkbBjRmo7rqgCbVG5VCS45Sw0AYrqN+msdUtvsLnuompeGkre Zz2XJzwMrN6aQlUu8RoFr2xFHY7U3IE8WGjh+UdtvrbmbxdRRbMN/q3IThiOlKuW DwGfFde2sjyEqA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrudejjedgleefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkffojghfggfgsedtkeertdertddtnecuhfhrohhmpefmlhgruhhs ucflvghnshgvnhcuoehithhssehirhhrvghlvghvrghnthdrughkqeenucggtffrrghtth gvrhhnpeeuleetgeeiuefhgfekfefgveejiefgteekiedtgfdtieefhfdthfefueffvefg keenucevlhhushhtvghrufhiiigvpedunecurfgrrhgrmhepmhgrihhlfhhrohhmpehith hssehirhhrvghlvghvrghnthdrughk X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA; Mon, 27 Sep 2021 01:19:07 -0400 (EDT) From: Klaus Jensen To: qemu-devel@nongnu.org Subject: [PATCH RFC v2 16/16] docs: add documentation for experimental nvme emulation Date: Mon, 27 Sep 2021 07:17:59 +0200 Message-Id: <20210927051759.447305-17-its@irrelevant.dk> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20210927051759.447305-1-its@irrelevant.dk> References: <20210927051759.447305-1-its@irrelevant.dk> MIME-Version: 1.0 Received-SPF: pass client-ip=64.147.123.17; envelope-from=its@irrelevant.dk; helo=wnew3-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: Fam Zheng , Kevin Wolf , =?utf-8?q?Dan?= =?utf-8?q?iel_P=2E_Berrang=C3=A9?= , Eduardo Habkost , qemu-block@nongnu.org, =?utf-8?q?Phi?= =?utf-8?q?lippe_Mathieu-Daud=C3=A9?= , Markus Armbruster , Klaus Jensen , Hanna Reitz , Hannes Reinecke , Stefan Hajnoczi , Klaus Jensen , Keith Busch , Paolo Bonzini , Eric Blake Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Klaus Jensen Signed-off-by: Klaus Jensen --- 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.