From nobody Mon Sep 16 18:59:56 2024 Delivered-To: importer2@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer2=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1675285988; cv=none; d=zohomail.com; s=zohoarc; b=jfwMaPd7Zh+4ZpxBHzIccJU5cXHc/SelbnPASHjstwEyOaJclah3bsgEP7L252bcYpOP/zR1XTuoQGilBBNOgsaSKfGwVnQF3NIDKXIPLxwOenfcrAw+hxl9vqVAOvADB6FHPENlZ2IK20pV9UnNitaUmgi8yBfoDVl1hT4zYOs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1675285988; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=y5wYHOszkMSH4MPcMrCHnqX4jCL6PCb/Iyd63wcqVs4=; b=X4wS/D9axU7CfiHMsARdHCxRM+6hdSFaBEmociZUUj8sj78z1LGP6vVcmQ+ofnwdeE7BTzzTuWeRxWFtBr13DXZyIljgY1fdqhzR+luXhRJp4VATTK8CVK/3wSAzU8eHqDe+7UNLoPwfXyf7V9DPHQFN4vNG5RiDHAhOeu7v3y8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer2=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1675285988289822.1354632559378; Wed, 1 Feb 2023 13:13:08 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNKPd-0001Jf-MQ; Wed, 01 Feb 2023 16:13:01 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pNKPb-0001CT-SW for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:12:59 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pNKPW-0003bi-Q0 for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:12:55 -0500 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-180-b-ipRZ4CPKiW4H1N1yDK3g-1; Wed, 01 Feb 2023 16:12:52 -0500 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9FE721C05AD6; Wed, 1 Feb 2023 21:12:51 +0000 (UTC) Received: from localhost (unknown [10.39.192.164]) by smtp.corp.redhat.com (Postfix) with ESMTP id 29C93140EBF4; Wed, 1 Feb 2023 21:12:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675285974; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=y5wYHOszkMSH4MPcMrCHnqX4jCL6PCb/Iyd63wcqVs4=; b=S3G9Cxo4iGJqDmYPC4S5d+J/Ng1lLVUoa85w+JnzFfBOAipEyQJ0dmb7jHivIRrAoGOw/E 9XMGaSg5oUr5Z7NodZmR7jCWchslYVq77FSFQ/yvb9rbtuvI7Dgwd2nryvLwT/wJcubDF+ OkAjNy9k1rX7YZybtmJwZcqlVi9s1xA= X-MC-Unique: b-ipRZ4CPKiW4H1N1yDK3g-1 From: Stefan Hajnoczi To: Cc: , Kevin Wolf , mjt@tls.msk.ru, Stefan Hajnoczi Subject: [PATCH 1/5] docs: expand introduction to disk images Date: Wed, 1 Feb 2023 16:12:30 -0500 Message-Id: <20230201211234.301918-2-stefanha@redhat.com> In-Reply-To: <20230201211234.301918-1-stefanha@redhat.com> References: <20230201211234.301918-1-stefanha@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.7 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+importer2=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=stefanha@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer2=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer2=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1675285988786100001 Content-Type: text/plain; charset="utf-8" Explain --blockdev, the graph, protocols, formats, and filters. Also mention the relationship between --blockdev and --drive, since new users are likely to hit both syntaxes. Signed-off-by: Stefan Hajnoczi --- docs/system/images.rst | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/system/images.rst b/docs/system/images.rst index d000bd6b6f..dc73acf8c9 100644 --- a/docs/system/images.rst +++ b/docs/system/images.rst @@ -3,9 +3,38 @@ Disk Images ----------- =20 -QEMU supports many disk image formats, including growable disk images -(their size increase as non empty sectors are written), compressed and -encrypted disk images. +QEMU supports many different types of storage protocols, disk image file +formats, and filter block drivers. *Protocols* provide access to storage s= uch +as local files or NBD exports. *Formats* implement file formats that are u= seful +for sharing disk image files and add functionality like snapshots. *Filter= s* +add behavior like I/O throttling. + +These features are composable in a graph. Each graph node is called a +*blockdev*. This makes it possible to construct many different storage +configurations. The simplest example is accessing a raw image file:: + + --blockdev file,filename=3Dtest.img,node-name=3Ddrive0 + +A qcow2 image file throttled to 10 MB/s is specified like this:: + + --object throttle-group,x-bps-total=3D10485760,id=3Dtg0 \ + --blockdev file,filename=3Dvm.qcow2,node-name=3Dfile0 \ + --blockdev qcow2,file=3Dfile0,node-name=3Dqcow0 \ + --blockdev throttle,file=3Dqcow0,throttle-group=3Dtg0,node-name=3Ddrive0 + +Blockdevs are not directly visible to guests. Guests use emulated storage +controllers like a virtio-blk device to access a blockdev:: + + --device virtio-blk-pci,drive=3Ddrive0 + +Note that QEMU has an older ``--drive`` syntax that is somewhat similar to +``--blockdev``. ``--blockdev`` is preferred because ``--drive`` mixes stor= age +controller and blockdev definitions in a single option that cannot express +everything. When a "drive" or "device" is required by a command-line optio= n or +QMP command, a blockdev node-name can be used. + +The remainder of this chapter covers the block drivers and how to work with +disk images. =20 .. _disk_005fimages_005fquickstart: =20 --=20 2.39.1