From nobody Fri Apr 19 16:29:40 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 From nobody Fri Apr 19 16:29:40 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=1675286020; cv=none; d=zohomail.com; s=zohoarc; b=M3Ixv+7+CZa5QVt4uTBch5uklma9URZ5Y6Wq+z17LS2bJhpZ7u1Syuz1x/bBOtSC8zq3DqbuuZfon2yt0HecJkC4WLLQlg+v3PbptppVcqhYYjiJWUTNZIxT+SxHCeyi5GPTiL2vpbRMQF+qu60S8XprJ/yDRhnKF9HlgIZfLFg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1675286020; h=Content-Type: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=CzDLW2wIIEuSeH7MPMjSMTFM/i89K9YuJTi44QgwlR0=; b=R0BCWamVQ6M79+3LSWrnNJRapLc71qs0142jCQsAC2t8zbNNaQ6K2LLYVe3ilzGXa76hkoDKD3Kn0DpKMRClNw1YHHWLYq4mHw1Wl18UoEV/XPp88P+Op7LoBRF1HjgEOA31X71qHf+aiRrFOpNGEEyMTEDW8aXhAdgbrs5SlNg= 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 1675286020754199.94473946959272; Wed, 1 Feb 2023 13:13:40 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNKPf-0001L1-8F; Wed, 01 Feb 2023 16:13:03 -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 1pNKPd-0001IY-Is for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:01 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pNKPb-0003bx-L8 for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:01 -0500 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-189-ASiHeM0NNvic31F5GEs0-w-1; Wed, 01 Feb 2023 16:12:54 -0500 Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4E6CE185A794; Wed, 1 Feb 2023 21:12:54 +0000 (UTC) Received: from localhost (unknown [10.39.192.164]) by smtp.corp.redhat.com (Postfix) with ESMTP id C3AAC492B05; Wed, 1 Feb 2023 21:12:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675285976; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=CzDLW2wIIEuSeH7MPMjSMTFM/i89K9YuJTi44QgwlR0=; b=aRCqfbJlbQr2cxzU0Q+sEU6lgBxcB/ZgZcjAy/xfnqEogpRdsCp/Z+1nhFazQJpu11IRxz 5u2QJMdsbLXIFAp3T53G7snfROBZag8m2vUTquzMEuvDf3ObNDd7buk2WvAXh2YASfEoL8 HZF51pLDkCxcVr+0/yAMlY+iV7PCMDs= X-MC-Unique: ASiHeM0NNvic31F5GEs0-w-1 From: Stefan Hajnoczi To: Cc: , Kevin Wolf , mjt@tls.msk.ru, Stefan Hajnoczi Subject: [PATCH 2/5] docs: differentiate between block driver create and runtime opts Date: Wed, 1 Feb 2023 16:12:31 -0500 Message-Id: <20230201211234.301918-3-stefanha@redhat.com> In-Reply-To: <20230201211234.301918-1-stefanha@redhat.com> References: <20230201211234.301918-1-stefanha@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.9 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.129.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: 1675286021026100001 Options available with qemu-img create -o ... are called create options. They affect how the image file is created on disk. Options available with --blockdev ... are called runtime options. They affect how the open blockdev behaves. The documentation makes no distinction is made between the two. For example, the preallocation filter driver talks about the runtime options while the image format drivers talk about the create options. Be explicit about create vs runtime options. Signed-off-by: Stefan Hajnoczi Reviewed-by: Eric Blake --- docs/system/qemu-block-drivers.rst.inc | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-bloc= k-drivers.rst.inc index dfe5d2293d..be6eec1eb6 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -6,9 +6,11 @@ any of the tools (like ``qemu-img``). This includes the pr= eferred formats raw and qcow2 as well as formats that are supported for compatibility with older QEMU versions or other hypervisors. =20 -Depending on the image format, different options can be passed to -``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option. -This section describes each format and the options that are supported for = it. +Depending on the image format, different options can be passed to ``qemu-i= mg +create`` and ``qemu-img convert`` using the ``-o`` option. These are called +*create options*. Image formats also support different ``--blockdev`` opti= ons. +These are called *runtime options*. This section describes each format and= the +options that are supported for it. =20 .. program:: image-formats .. option:: raw @@ -20,7 +22,7 @@ This section describes each format and the options that a= re supported for it. space. Use ``qemu-img info`` to know the real size used by the image or ``ls -ls`` on Unix/Linux. =20 - Supported options: + Supported create options: =20 .. program:: raw .. option:: preallocation @@ -181,7 +183,7 @@ This section describes each format and the options that= are supported for it. When converting QED images to qcow2, you might want to consider using t= he ``lazy_refcounts=3Don`` option to get a more QED-like behaviour. =20 - Supported options: + Supported create options: =20 .. program:: qed .. option:: backing_file @@ -212,7 +214,7 @@ This section describes each format and the options that= are supported for it. Old QEMU image format with support for backing files, compact image file= s, encryption and compression. =20 - Supported options: + Supported create options: =20 .. program:: qcow .. option:: backing_file @@ -248,7 +250,7 @@ This section describes each format and the options that= are supported for it. =20 LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup =20 - Supported options: + Supported create options: =20 .. program:: luks .. option:: key-secret @@ -289,7 +291,7 @@ This section describes each format and the options that= are supported for it. =20 VirtualBox 1.1 compatible image format. =20 - Supported options: + Supported create options: =20 .. program:: vdi .. option:: static @@ -302,7 +304,7 @@ This section describes each format and the options that= are supported for it. =20 VMware 3 and 4 compatible image format. =20 - Supported options: + Supported create options: =20 .. program: vmdk .. option:: backing_file @@ -332,7 +334,7 @@ This section describes each format and the options that= are supported for it. =20 VirtualPC compatible image format (VHD). =20 - Supported options: + Supported create options: =20 .. program:: vpc .. option:: subformat @@ -345,7 +347,7 @@ This section describes each format and the options that= are supported for it. =20 Hyper-V compatible image format (VHDX). =20 - Supported options: + Supported create options: =20 .. program:: VHDX .. option:: subformat @@ -920,7 +922,7 @@ some additional tasks, hooking io requests. (expanding the protocol file) when writing past the file=E2=80=99s end. = This can be useful for file-systems with slow allocation. =20 - Supported options: + Supported runtime options: =20 .. program:: preallocate .. option:: prealloc-align --=20 2.39.1 From nobody Fri Apr 19 16:29:40 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=1675285998; cv=none; d=zohomail.com; s=zohoarc; b=mPctNP1lL9h5RyNI/OVfhcjhUPZDJ3kVCWYaL8Jcj6sTMquxTmYj5bmfAGvAPcchOCscdyBZ+poZQzG/fOA4R4Z8zXhkI6XR05PbszR7EKe4rZilwGDooIkEkpwgN9vkBg1rVUrzf1oi5N8XowZFX3N9DoEDaK1zHmmTjKB7y0M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1675285998; 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=uHWRR9w1QzyIfUJvtG7FAfTWAnsQnxANw/2ngu7uzmI=; b=XWurZxp1dSf1hbi8jM1MDZb0jKabnIIjedZXLeJm+PQK6xP3iluvcwjg5GldkycZW/GKnQTSQOGviWV9dbR2HKaFNfOnUT9QBBQ6RG2ScKMl0tNCio5sfPZ6fFGOmymvFZDKOuHQ7/5jnz7rSGzqOoWbzETAig2lP2dFLs3CGwM= 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 1675285998416507.56912753993583; Wed, 1 Feb 2023 13:13:18 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNKPg-0001Lc-PX; Wed, 01 Feb 2023 16:13:04 -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 1pNKPe-0001K8-Iy for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:02 -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 1pNKPc-0003ca-Fd for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:02 -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-76-mn2VY8gqPGWksTp_LR4RrQ-1; Wed, 01 Feb 2023 16:12:56 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8140E3C02547; Wed, 1 Feb 2023 21:12:56 +0000 (UTC) Received: from localhost (unknown [10.39.192.164]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0C27A2166B33; Wed, 1 Feb 2023 21:12:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675285979; 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=uHWRR9w1QzyIfUJvtG7FAfTWAnsQnxANw/2ngu7uzmI=; b=GbjVYQVxn93AoSEJf+LMoVZGmgeej/EjdmxiZQKSMC1Z73GB0P9JBhgC+EfzGCEwD4dKjE GsdNcaIo+14DSXGescBucmslzqGxlMNLaiJLTgIX7J92j/PYObkyCdIIknqlGT3b7tJJ4j AHFSNT/D1DK0L5Zj5N/9cfUcZUw6SxU= X-MC-Unique: mn2VY8gqPGWksTp_LR4RrQ-1 From: Stefan Hajnoczi To: Cc: , Kevin Wolf , mjt@tls.msk.ru, Stefan Hajnoczi Subject: [PATCH 3/5] docs: flesh out raw format driver description Date: Wed, 1 Feb 2023 16:12:32 -0500 Message-Id: <20230201211234.301918-4-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.6 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=unavailable 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: 1675285998815100002 Content-Type: text/plain; charset="utf-8" Modernize the description and document the size=3D/offset=3D runtime options. Signed-off-by: Stefan Hajnoczi --- docs/system/qemu-block-drivers.rst.inc | 32 ++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-bloc= k-drivers.rst.inc index be6eec1eb6..ec9ebb2066 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -16,11 +16,11 @@ options that are supported for it. .. option:: raw =20 Raw disk image format. This format has the advantage of - being simple and easily exportable to all other emulators. If your - file system supports *holes* (for example in ext2 or ext3 on - Linux or NTFS on Windows), then only the written sectors will reserve - space. Use ``qemu-img info`` to know the real size used by the - image or ``ls -ls`` on Unix/Linux. + being simple and easily exportable to all other emulators. Modern + file systems support *holes* (for example in btrfs/XFS/ext4 on + Linux or NTFS on Windows) where space is allocated on demand as sectors = are + written. Use ``qemu-img info`` to know the real size used by the image or + ``ls -ls`` on Unix/Linux. =20 Supported create options: =20 @@ -33,6 +33,28 @@ options that are supported for it. for image by writing data to underlying storage. This data may or may not be zero, depending on the storage location. =20 + Supported runtime options: + + .. program:: raw + .. option:: offset + + The byte position in the underlying file where the virtual disk starts. + This is handy when you want to present just a single partition from a + physical disk as the virtual disk. This option is usually used in + conjunction with the ``size`` option. + + .. option:: size + + Limit the virtual disk size to the given number of bytes, regardless o= f how + large the underlying file is. This option is usually used in conjuncti= on + with the ``offset`` option. + + Note the raw format can be omitted when no runtime options are being use= d. In + that case the raw format does nothing besides forwarding I/O requests to= the + protocol blockdev. You can improve performance slightly by eliminating + ``--blockdev raw,file=3Dfile0,node-name=3Ddrive0`` and renaming the "fil= e0" + blockdev to "drive0". + .. program:: image-formats .. option:: qcow2 =20 --=20 2.39.1 From nobody Fri Apr 19 16:29:40 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=1675286029; cv=none; d=zohomail.com; s=zohoarc; b=Kq4VF1cs9knzCi1bpu0fiwHXfFXBPUIPoEdljmaL2C9LvkPI6JQAOtKbsrFsJNcwkzHjk38DW2o/SHQaRrB46BupPYT8iOFxL+wTjW7Bv1qIM2KTbcTAKFpFJbcUcEuJKgcSU+9hrkX3ZdDIRkXaOvWEEhleKxDOBv6Ei00Mxuo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1675286029; 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=ym5PB7wFVphQx6AdIHDJ9zSbsu6D0R9a9T5xuWH3qmU=; b=Jj6Sa3zRa/KfIyEW1jhgYEODwTWROxE4E03PSSlaG05bOKd6ywaxHmF2OGzWuYQK+e6oZ6uvFlUyyaFkv8nRPBQOqR+k480KToKZJEnBRlc3fVlbSXoYxdFGwgf4tjqbY1g0QrZqij6QYM8ELgoc2gaXDgPGHNuQ5yhKtTEIEhQ= 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 1675286029658704.7946864773998; Wed, 1 Feb 2023 13:13:49 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNKPi-0001Qv-FS; Wed, 01 Feb 2023 16:13:06 -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 1pNKPg-0001Lk-U6 for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:04 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pNKPf-0003eK-6G for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:04 -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-455-EPFxP8d2O12P_aCi6-HqfQ-1; Wed, 01 Feb 2023 16:12:59 -0500 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9763C1C05AF9; Wed, 1 Feb 2023 21:12:58 +0000 (UTC) Received: from localhost (unknown [10.39.192.164]) by smtp.corp.redhat.com (Postfix) with ESMTP id F068A492B00; Wed, 1 Feb 2023 21:12:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675285982; 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=ym5PB7wFVphQx6AdIHDJ9zSbsu6D0R9a9T5xuWH3qmU=; b=bkHgNzr07/SkAec3L/Cw0OnGfzVd6H81dIDdBXad0AARv2CZsDHNMXAZ3R/ZDWHjNRiHdp U8vjCpLphfzS0XRQHTgv0z+fOf+9KDTsbFZfwdhXapmPwjwIuuM6dqTXSnx1a+RqGLrfsD 86Z5SNxZVFW/nMO1VINYn6M21S7g7yM= X-MC-Unique: EPFxP8d2O12P_aCi6-HqfQ-1 From: Stefan Hajnoczi To: Cc: , Kevin Wolf , mjt@tls.msk.ru, Stefan Hajnoczi Subject: [PATCH 4/5] docs: flesh out qcow2 format driver description Date: Wed, 1 Feb 2023 16:12:33 -0500 Message-Id: <20230201211234.301918-5-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.10 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.129.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: 1675286031088100001 Content-Type: text/plain; charset="utf-8" Put the create options in alphabetical order, add compression_type and extended_l2, and also mention the common runtime options. I did not add rarely-used runtime options because I think it's too much information. Signed-off-by: Stefan Hajnoczi Reviewed-by: Eric Blake --- docs/system/qemu-block-drivers.rst.inc | 91 ++++++++++++++++++++------ 1 file changed, 70 insertions(+), 21 deletions(-) diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-bloc= k-drivers.rst.inc index ec9ebb2066..af72817763 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -59,13 +59,27 @@ options that are supported for it. .. option:: qcow2 =20 QEMU image format, the most versatile format. Use it to have smaller - images (useful if your filesystem does not supports holes, for example - on Windows), zlib based compression and support of multiple VM + images (useful if your filesystem does not support holes, for example + on Windows), zlib/zstd compression and support of multiple VM snapshots. =20 - Supported options: + Supported create options: =20 .. program:: qcow2 + .. option:: backing_file + + File name of a base image (see ``create`` subcommand) + + .. option:: backing_fmt + + Image format of the base image + + .. option:: cluster_size + + Changes the qcow2 cluster size (must be between 512 and 2M). Smaller c= luster + sizes can improve the image file size whereas larger cluster sizes gen= erally + provide better performance. + .. option:: compat =20 Determines the qcow2 version to use. ``compat=3D0.10`` uses the @@ -74,13 +88,9 @@ options that are supported for it. newer understand (this is the default). Amongst others, this includes zero clusters, which allow efficient copy-on-read for sparse images. =20 - .. option:: backing_file + .. option:: compression_type =20 - File name of a base image (see ``create`` subcommand) - - .. option:: backing_fmt - - Image format of the base image + Selects the compression algorithm (zlib or zstd). =20 .. option:: encryption =20 @@ -150,19 +160,11 @@ options that are supported for it. Amount of time, in milliseconds, to use for PBKDF algorithm per key sl= ot. Defaults to ``2000``. Only used when ``encrypt.format=3Dluks``. =20 - .. option:: cluster_size + .. option:: extended_l2 =20 - Changes the qcow2 cluster size (must be between 512 and 2M). Smaller c= luster - sizes can improve the image file size whereas larger cluster sizes gen= erally - provide better performance. - - .. option:: preallocation - - Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``, - ``full``). An image with preallocated metadata is initially larger but= can - improve performance when the image needs to grow. ``falloc`` and ``ful= l`` - preallocations are like the same options of ``raw`` format, but sets up - metadata also. + Enables the Extended L2 Entries feature that divides each cluster into= 32 + separately allocated sub-clusters. A larger cluster size can be used, = thus + reducing metadata overhead, while still allowing fine-grained allocati= on. =20 .. option:: lazy_refcounts =20 @@ -196,6 +198,53 @@ options that are supported for it. filename`` to check if the NOCOW flag is set or not (Capital 'C' is NOCOW flag). =20 + .. option:: preallocation + + Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``, + ``full``). An image with preallocated metadata is initially larger but= can + improve performance when the image needs to grow. ``falloc`` and ``ful= l`` + preallocations are like the same options of ``raw`` format, but sets up + metadata also. + + Supported runtime options: + + .. program:: qcow2 + .. option:: cache-clean-interval + + Clean unused cache entries after this time (in seconds). + + .. option:: cache-size + + Maximum combined metadata (L2 tables and refcount blocks) cache size. + + .. option:: encrypt.key-secret + + ID of secret providing qcow2 AES key or LUKS passphrase. + + .. option:: l2-cache-size + + Maximum L2 table cache size. + + .. option:: l2-cache-entry-size + + Size of each entry in the L2 cache. + + .. option:: pass-discard-request + + Pass guest discard requests to the layer below (on/off). + + .. option:: pass-discard-snapshot + + Generate discard requests when snapshot related space is freed (on/off= ). + + .. option:: pass-discard-other + + Generate discard requests when other clusters are freed (on/off). + + .. option:: refcount-cache-size + + Maximum refcount block cache size. + .. program:: image-formats .. option:: qed =20 --=20 2.39.1 From nobody Fri Apr 19 16:29:40 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=1675286023; cv=none; d=zohomail.com; s=zohoarc; b=VnENn3G8FNBJDQ5Y8NdbRR1fssU3qQr7np70cj6e7LeB0p+M2z+CHok04dygUQMjhMfS0o7QW/q89tMA4DNuia83hduhdE96ZTKfl2wUU4AaWZ3IyPD7izOQBZ84HqiyF2frNd4/ToBrQX0fUHCH1KABe2CCs3S6xgBdTNYanGI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1675286023; 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=ybriR74drHlRAEAQF8rbl5sN7iUBs3zLUCO6HyZbwMU=; b=A9S86ZYwbSMdXs6PM+Aa8bLH6A71dfChDfs5mnH9YIOaAEyvb4au5cKaRWyyyzc0G5IZyy1gnEyQD1QaZMCXjx7G5XCdjX1J07jFznAZIowOpkD+tLJcAbYFZqB3Vh26DXgA1ScY3EN1kceFrMeYOes/Q14wLqSO6/DsJ4peW7k= 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 1675286023606727.1722508286435; Wed, 1 Feb 2023 13:13:43 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pNKPl-0001XX-J0; Wed, 01 Feb 2023 16:13:09 -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 1pNKPk-0001WO-Ae for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:08 -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 1pNKPi-0003gO-8z for qemu-devel@nongnu.org; Wed, 01 Feb 2023 16:13:07 -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-202-V-LhywrRPz6ukhDLkrgZ9A-1; Wed, 01 Feb 2023 16:13:01 -0500 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 2AFA03C02550; Wed, 1 Feb 2023 21:13:01 +0000 (UTC) Received: from localhost (unknown [10.39.192.164]) by smtp.corp.redhat.com (Postfix) with ESMTP id A05C42026D4B; Wed, 1 Feb 2023 21:13:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1675285985; 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=ybriR74drHlRAEAQF8rbl5sN7iUBs3zLUCO6HyZbwMU=; b=VasPufCKncUaK7cwj8yzo5NSZqaPq6Vl9kCzCYN9xxpSUhWKI8hB9VBne1BDFJ4O6YNV7g VpFKZmaFh9cy3e+NHD4Ss4rh0hVzQjpGdCxtEQs7gKwxa8m1wTkkBmeVTHM0b5+fBmeFVj hEyw5IJx49jCgZpkx1Jo3ebAUIGX0C4= X-MC-Unique: V-LhywrRPz6ukhDLkrgZ9A-1 From: Stefan Hajnoczi To: Cc: , Kevin Wolf , mjt@tls.msk.ru, Stefan Hajnoczi Subject: [PATCH 5/5] docs: add throttle filter description Date: Wed, 1 Feb 2023 16:12:34 -0500 Message-Id: <20230201211234.301918-6-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.4 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=unavailable 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: 1675286025062100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Stefan Hajnoczi Reviewed-by: Eric Blake --- docs/system/qemu-block-drivers.rst.inc | 110 +++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-bloc= k-drivers.rst.inc index af72817763..ea4be5c210 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -1004,3 +1004,113 @@ some additional tasks, hooking io requests. .. option:: prealloc-size =20 How much to preallocate (in bytes), default 128M. + +.. program:: filter-drivers +.. option:: throttle + + The throttle filter driver rate limits I/O requests so that the given IO= PS + and bandwidth values are not exceeded. Limits are specified using the + following syntax:: + + --object '{"driver":"throttle-group","id":"tg0","limits":{"iops-total= ":2048,"bps-total":10485760}}' + + The following throttle group limits are available: + + .. program:: throttle-group + .. option:: iops-total + + Limit total I/O operations per second. + + .. option:: iops-total-max + + I/O operations burst. + + .. option:: iops-total-max-length + + Length of the ``iops-total-max`` burst period, in seconds. It must onl= y be + set if ``iops-total-max`` is set as well. + + .. option:: iops-read + + Limit read operations per second. + + .. option:: iops-read-max + + I/O operations read burst. + + .. option:: iops-read-max-length + + Length of the ``iops-read-max`` burst period, in seconds. It must only= be + set if ``iops-read-max`` is set as well. + + .. option:: iops-write + + Limit write operations per second. + + .. option:: iops-write-max + + I/O operations write burst. + + .. option:: iops-write-max-length + + Length of the ``iops-write-max`` burst period, in seconds. It must onl= y be + set if ``iops-write-max`` is set as well. + + .. option:: bps-total + + Limit total bytes per second. + + .. option:: bps-total-max + + Total bytes burst. + + .. option:: bps-total-max-length + + Length of the ``bps-total-max`` burst period, in seconds. It must only= be + set if ``bps-total-max`` is set as well. + + .. option:: bps-read + + Limit read bytes per second. + + .. option:: bps-read-max + + Total bytes read burst. + + .. option:: bps-read-max-length + + Length of the ``bps-read-max`` burst period, in seconds. It must only = be + set if ``bps-read-max`` is set as well. + + .. option:: bps-write + + Limit write bytes per second. + + .. option:: bps-write-max + + Total bytes write burst. + + .. option:: bps-write-max-length + + Length of the ``bps-write-max`` burst period, in seconds. It must only= be + set if ``bps-write-max`` is set as well. + + .. option:: iops-size + + IOPS are counted as a multiple of this value, in bytes. For example, a= 16 + KB read request is counted as 4 IOPS when ``iops-size`` is 4 KB. + + Throttle groups are defined separately from throttle blockdevs so they c= an be + shared by multiple blockdevs. + + Note that the location of the throttle blockdev in the graph is signific= ant. + Usually it will be one of the topmost nodes so that guest I/O requests a= re + throttled. When the throttle blockdev is located below a format driver i= t may + see a different I/O pattern due to image format metadata I/O. + + Supported runtime options: + + .. program:: throttle + .. option:: throttle-group + + The id of the throttle group object that defines the I/O limits. --=20 2.39.1