From patchwork Wed May 17 08:00:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Michael Tokarev X-Patchwork-Id: 682903 Delivered-To: patch@linaro.org Received: by 2002:a5d:4e01:0:0:0:0:0 with SMTP id p1csp230521wrt; Wed, 17 May 2023 01:09:36 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ4sWyEdNl3/qG6CgnV5PW3GtpSEuKfUsj0wGQA44avEnhZfdML2p3IqVJqzmUAN5E3TZdTQ X-Received: by 2002:ad4:5bac:0:b0:619:4232:aa87 with SMTP id 12-20020ad45bac000000b006194232aa87mr54364104qvq.24.1684310976636; Wed, 17 May 2023 01:09:36 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1684310976; cv=none; d=google.com; s=arc-20160816; b=nxnBGJRQqT03ll9PHDWADI637ov1J3Ci6nBi7NbevCYREp0o4wPtUdyyjtuD+CIo9r GrehDSnZMK380c9qRoG4eZH3t9AYXAlFXNw5JW4nmlxGMhpBpGgQlYpmhLrU9RKPs1z5 NwCQYEUvQON6Gd0rDOrZKqresJrz2u78v1a4FwkYx+h8+aYIR7EuiWvegq70lTA187KL 50uyfaOVLeGIT+f/aOWz/8rOIF4m7tRQMkCRtvnPWb28poFQu5SbBQdQD7+FSKcuJbkK AvY7QKIvufWYvE6ZTpyQZuD64kHE0o/UYllNj3UYwDekHjhByDGQiWgJ8akHoHXm99mD 1pSg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from; bh=qX1w5HKe63hOj739JegGghzCFVOwHSxF3hixEYsrhBA=; b=syKdumnAAyCeqHwMm0sjYcDcNFTuvydvKzOx9reO0vVcxTDyD4hfzZmD1fhZPGC1UN ZKSva7j9LoM+AMwQE1y8d+GUn+Ewy/xWQzS0DYYjZlNzCtj2k0nsHKhuTAyghhJmnfKo xzFG46QktvjS85wgiF5U7xQ40l3U87mNTGaj1VISSs5d3QaBQRkm6Zg8IXt+6RnImKg4 T3Ty2nb8tfsJhqSgVTtGpwcG6gntGZUmhZo4s2fNSwFJN1Vp+MWEwtIMumRmZdWZcPWP +049ovT9UM2EHUMVFn+kczEdLhBBWHNDSwxMGCZ+6SHdi14vjjX2ulJRqMVYD0GbuonV zC4Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org" Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id j1-20020ae9c201000000b007578e03b68esi959321qkg.698.2023.05.17.01.09.36 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Wed, 17 May 2023 01:09:36 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org" Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pzC6Y-0002Jf-9x; Wed, 17 May 2023 04:01:50 -0400 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 1pzC6G-00021G-7H; Wed, 17 May 2023 04:01:35 -0400 Received: from isrv.corpit.ru ([86.62.121.231]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pzC6D-0000Yc-Ow; Wed, 17 May 2023 04:01:31 -0400 Received: from tsrv.corpit.ru (tsrv.tls.msk.ru [192.168.177.2]) by isrv.corpit.ru (Postfix) with ESMTP id B26F86750; Wed, 17 May 2023 11:00:57 +0300 (MSK) Received: from tls.msk.ru (mjt.wg.tls.msk.ru [192.168.177.130]) by tsrv.corpit.ru (Postfix) with SMTP id 30CB85E08; Wed, 17 May 2023 11:00:57 +0300 (MSK) Received: (nullmailer pid 3624099 invoked by uid 1000); Wed, 17 May 2023 08:00:56 -0000 From: Michael Tokarev To: qemu-stable@nongnu.org Cc: qemu-devel@nongnu.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Thomas Huth , Markus Armbruster , Kevin Wolf Subject: [PATCH v8.0.1 07/36] qemu-options: finesse the recommendations around -blockdev Date: Wed, 17 May 2023 11:00:27 +0300 Message-Id: <20230517080056.3623993-7-mjt@msgid.tls.msk.ru> X-Mailer: git-send-email 2.39.2 In-Reply-To: <<20230517073442.3622973-0-mjt@msgid.tls.msk.ru> References: <20230517073442.3622973-0-mjt@msgid.tls.msk.ru> MIME-Version: 1.0 Received-SPF: pass client-ip=86.62.121.231; envelope-from=mjt@tls.msk.ru; helo=isrv.corpit.ru X-Spam_score_int: -68 X-Spam_score: -6.9 X-Spam_bar: ------ X-Spam_report: (-6.9 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_HI=-5, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org From: Alex Bennée We are a bit premature in recommending -blockdev/-device as the best way to configure block devices. It seems there are times the more human friendly -drive still makes sense especially when -snapshot is involved. Improve the language to hopefully make things clearer. Suggested-by: Michael Tokarev Signed-off-by: Alex Bennée Reviewed-by: Thomas Huth Cc: Markus Armbruster Cc: Kevin Wolf Message-Id: <20230424092249.58552-7-alex.bennee@linaro.org> (cherry picked from commit c1654c3e37c31fb638597efedcd07d071837b78b) Signed-off-by: Michael Tokarev --- qemu-options.hx | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/qemu-options.hx b/qemu-options.hx index 59bdf67a2c..4b8855a4f7 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -1143,10 +1143,22 @@ have gone through several iterations as the feature set and complexity of the block layer have grown. Many online guides to QEMU often reference older and deprecated options, which can lead to confusion. -The recommended modern way to describe disks is to use a combination of +The most explicit way to describe disks is to use a combination of ``-device`` to specify the hardware device and ``-blockdev`` to describe the backend. The device defines what the guest sees and the -backend describes how QEMU handles the data. +backend describes how QEMU handles the data. It is the only guaranteed +stable interface for describing block devices and as such is +recommended for management tools and scripting. + +The ``-drive`` option combines the device and backend into a single +command line option which is a more human friendly. There is however no +interface stability guarantee although some older board models still +need updating to work with the modern blockdev forms. + +Older options like ``-hda`` are essentially macros which expand into +``-drive`` options for various drive interfaces. The original forms +bake in a lot of assumptions from the days when QEMU was emulating a +legacy PC, they are not recommended for modern configurations. ERST @@ -1639,6 +1651,14 @@ SRST the raw disk image you use is not written back. You can however force the write back by pressing C-a s (see the :ref:`disk images` chapter in the System Emulation Users Guide). + + .. warning:: + snapshot is incompatible with ``-blockdev`` (instead use qemu-img + to manually create snapshot images to attach to your blockdev). + If you have mixed ``-blockdev`` and ``-drive`` declarations you + can use the 'snapshot' property on your drive declarations + instead of this global option. + ERST DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,