From patchwork Thu Apr 27 15:44:58 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 677517 Delivered-To: patch@linaro.org Received: by 2002:a5d:4a41:0:0:0:0:0 with SMTP id v1csp414311wrs; Thu, 27 Apr 2023 08:45:41 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ6RtuxUIZcAQFXtaEGhQGTD8XnsyjW6hX6MCCcwobel3O3vO02pt85m6KEiMdCLp9kxwax1 X-Received: by 2002:a05:622a:46:b0:3ef:5d90:3c5e with SMTP id y6-20020a05622a004600b003ef5d903c5emr3290464qtw.9.1682610341417; Thu, 27 Apr 2023 08:45:41 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682610341; cv=none; d=google.com; s=arc-20160816; b=I/K5zf1D8jGRBhVyWuQPo23OlyKP6b+fPtWuaH0HxBtGjmlZEk2usG/PhpU/6kTEH3 0xkHZb6LR5YrGOo4FKdXQjvQ7G7c+26rS+CZhb/BPz9VYqMyevhZ5mQJcy6dAiKqIcRq pwA0mMyFVfEdzYYjRcKp0JgDFpk80eunN+NFPvPrBhHp04ejjob/JbfcfBbMTbTtp6/V Pll3ipvsj/Yo2E4vI6sB6GD9pAsT09Z40CBGghsZZce8angBWRoIRecnpxj23jr9K+II gwYPm9vlg+7pKoZNT2pn9KZf/RBO5T+I9YYioG9LbRosHchyut0JJakzxvphV/xZ3TSb QS8A== 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:dkim-signature; bh=SI6uYTd7Q0+IVe4nYn/2huKDCgz0raMlMXhc7QX3q+I=; b=KpO0mQPWnEMiqsWh1ChKRs/eJnDl0Epi2nvI1HLg95rJqIGH8RFxWKsrnA+/DcKSVY ofSAnKsOyFDcYL+dODsT/POLzHOXeJYi3YBSQQ6Y7bqbjyqL+VPrg0yqhXd4rlnIwsdK nDfzrWYGp7b+fj5vBwpZLlGadB1PAvBrmOPNpud5TN6sL9Y8BkTwhDcx4b1rgbrtBBXr EqDXMRVgKkMGM/Wk0asS54B806KqYvFxRyXMjAm1YLHaF9KY0smG70QoKZgSyinIODcv e2x1CYMPU+EgRlBQ4POiyW8ZngT2OkJzKW1zgN7PpXazPkrYyTYBg2u0XeTQgbIeDhIU fpVg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=BS3uaJPo; 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"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id u25-20020a05622a199900b003ecb0b742f3si12486894qtc.88.2023.04.27.08.45.41 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 27 Apr 2023 08:45:41 -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; dkim=pass header.i=@linaro.org header.s=google header.b=BS3uaJPo; 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"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ps3oB-0001sL-QF; Thu, 27 Apr 2023 11:45:23 -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 1ps3o7-0001pr-9I for qemu-devel@nongnu.org; Thu, 27 Apr 2023 11:45:19 -0400 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ps3o4-0004ia-MB for qemu-devel@nongnu.org; Thu, 27 Apr 2023 11:45:18 -0400 Received: by mail-wm1-x32a.google.com with SMTP id 5b1f17b1804b1-3f315735514so29119855e9.1 for ; Thu, 27 Apr 2023 08:45:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1682610316; x=1685202316; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=SI6uYTd7Q0+IVe4nYn/2huKDCgz0raMlMXhc7QX3q+I=; b=BS3uaJPowCtUB+tvsByZoj1Ht+0mVzlaqQ3EoWlo8/52qbjtQt2frhnGqUYB6MDQR9 f+SP3kH2+c6z9fYJAmFmjOKthAmT9xy2tGQJBvV0ZEGmZwLKHi48AnQGX0piFA4q/vwh NYQ7zjJpEr2rK07HaDzXEaIp+gD6HltUgjIcWnctcBRr+MBGz3xzxWfNMFodJEeboDHJ NhA27ICVtosSdssvD/QPMZwgcD0zcpHsGwtmG5kqNUe9HmQ6bt6tX+cmriajYuUPv22s mer0dzvBTvDHMsX9HHiRtZYKDaer7UtrD9cKpqm9rLRMh2g5hlhXYvIZTAXjeQQ/olh+ 75Dg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682610316; x=1685202316; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=SI6uYTd7Q0+IVe4nYn/2huKDCgz0raMlMXhc7QX3q+I=; b=AneRqIsZLrJJ1FCSW2x+r7+t0rG8bKu906NZkWSkHhMp3324do7ln0uOfffdRE2v/T bmNhhIztpQZDAY5LdbAcOLVFvD+Br9oWeSuG/+CyfSIZUURl9MNMSpop8dOZQb7mlYXe h7HhKjwGTJtKdj/fdr2f8WjJ2VG4DtiVHFNFFN4pNCQVm16d4WKfGcSa4xhtbEBdFNJZ 2znoXBfDz4Zd8CLE2/nG7sOPyIpkKPWMr/z1KPhhSh2NckGgEV7bhz4LxQKJCLXoFBm8 9QsUFU1ZvEwlwDM1j19INDPSFolN3l88WT5cwd/vxRFDvRMYm58mUwXoe8i4U6o6UGEF TuqA== X-Gm-Message-State: AC+VfDxE6LkNSOCAmKtHx/G8fJWt4Q7BHVIwMcQrkf0bNqJCHdRilKGo lupcYrnpgu6ENwlokVSjot1Z5g== X-Received: by 2002:a05:600c:3b2a:b0:3f1:73d3:5362 with SMTP id m42-20020a05600c3b2a00b003f173d35362mr4755619wms.13.1682610315818; Thu, 27 Apr 2023 08:45:15 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id s9-20020a1cf209000000b003f321e61c1asm330892wmc.21.2023.04.27.08.45.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 27 Apr 2023 08:45:12 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 4F05A1FFBE; Thu, 27 Apr 2023 16:45:11 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: richard.henderson@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Michael Tokarev , Thomas Huth , Markus Armbruster , Kevin Wolf Subject: [PULL 06/18] qemu-options: finesse the recommendations around -blockdev Date: Thu, 27 Apr 2023 16:44:58 +0100 Message-Id: <20230427154510.1791273-7-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230427154510.1791273-1-alex.bennee@linaro.org> References: <20230427154510.1791273-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32a; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32a.google.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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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 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> diff --git a/qemu-options.hx b/qemu-options.hx index 04c259157a..baa0589733 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,