From patchwork Mon Apr 17 13:43:21 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: 673828 Delivered-To: patch@linaro.org Received: by 2002:adf:fcce:0:0:0:0:0 with SMTP id f14csp1515541wrs; Mon, 17 Apr 2023 06:45:17 -0700 (PDT) X-Google-Smtp-Source: AKy350Z9XAwPIMhm6aNsJLuRpTJzdkdnsQLXWW39GWpJX96LW255hsYX1xLdPqV0Dl6wo5G29bFU X-Received: by 2002:a05:6214:3007:b0:5ef:6bbe:3d38 with SMTP id ke7-20020a056214300700b005ef6bbe3d38mr7203950qvb.52.1681739117091; Mon, 17 Apr 2023 06:45:17 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1681739117; cv=none; d=google.com; s=arc-20160816; b=oheEfAfI+ME/9vZG9fvYqo1d+1hjVJC6/6HFQPMpwK+Hm6gUp+IUHkzxs8GEdVmT3/ NOeKkr4ZmzIvldMyUIDSah+k9jYYKDW391KM04qTeryniWk+JHTxQm5+FSogiV0rzFMQ L61sASKosxna2NmTOAloR71PTNh+RfBQRFiJD4vP6oR/geJ8pGA2v7YO7/+KcwFBvwAw 2oyzlUSk+/7DEwqLdItY/zw22u+eJXWuliOkiF5eNEKk5+ywTw1ma5fCDQxtOPf5eHaI XPCW2YSFFpP4mDzlJT4HBR2NS+MfIR+bPCGMgQh3QugB2QHgEL33QNO7f64Xd2lNcmz5 OJKw== 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=OSKTGeVvxMRFHaTMOhie+UZrwE1FFDQH+ewlD3woTE0=; b=u1NiUyt+FoJe50Dh5iy0l3D0/G25k0XOaWp3P/8rkBpYsqTfd52V2LeaYkswMzsYdY 3NkPXfa/SBih7ebi09A+JUfzqczQMmoZGB115UJIQ3ai6CEsdCodBX3g1sP1wPCJdFnv Dm+yqjEpVALc0VV1EdguAyaL5O1nQ65x7dqaIXy5gy1rY/qA5QgMAM8q7rWRx2eMpoQU 3rpCypjPuWARPhV9aji7xpwOKIqps9ZgbmO9Y2JIP+f3/Y3NiFOqCupOZrkjAomSXuC3 voo0EezQ6hWm9ZFSXk4gKe1CzcnFoti93mcivB1824p7qafgxyMN+nkyJPBJWKdeOxb/ s3wg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=AVo8XnOh; 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 g8-20020a0562141cc800b005e87698491dsi5480507qvd.132.2023.04.17.06.45.16 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 17 Apr 2023 06:45:17 -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=AVo8XnOh; 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 1poP8u-0000yN-Nm; Mon, 17 Apr 2023 09:43:40 -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 1poP8p-0000wb-UQ for qemu-devel@nongnu.org; Mon, 17 Apr 2023 09:43:36 -0400 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1poP8n-0006Rh-NH for qemu-devel@nongnu.org; Mon, 17 Apr 2023 09:43:35 -0400 Received: by mail-wm1-x334.google.com with SMTP id 5b1f17b1804b1-3f09b4a1584so10389955e9.2 for ; Mon, 17 Apr 2023 06:43:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1681739012; x=1684331012; 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=OSKTGeVvxMRFHaTMOhie+UZrwE1FFDQH+ewlD3woTE0=; b=AVo8XnOhDxYTKD/J4AYoOcoEduuUCixW25KFn9VpVoHvxgIfp6GgCp5AXB+ZnSa9Q6 MPraOhNaexi81nM/lxjVPtb6FaoPup+U8LSySkkuvK5L1TTK1Wj4rY/b9rcofvOGU1zV FzFDTRmCQSXAldXzOQ/9tMHyhs/9mEDc+1y5eXXG8VqYWCQ8NZdIlQb4iOpFN7xZjfpj Fq7U7Qb24BHYqvjL5JC9+0sQ6mN1TFt8iVmmYjQFfFj00/IQtdbGnfLejsRlSGx4kKGm QhEeq7Rqm+eIiSyztNT0Ts+0Wu8bkQwDqkexLHbZ1sPxqjogsUBesKGRW6HGC9kvcWhQ oNVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1681739012; x=1684331012; 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=OSKTGeVvxMRFHaTMOhie+UZrwE1FFDQH+ewlD3woTE0=; b=HEHkdW/PJlN3L7gyd9P+RLHFu9mPN7ujgxAvsiRO80z5h43bFVBbgd1HCNT9OJIude 6DT9Cr2uAloyIVVCbBD8AWZGIqMrZVtXa6Co+wv25mO9n4nWNnTCT871bQTBagrNlokw yhctZ8BIZXSNMi5Vans3Eaikp2cMHQvhfZOuiqJDGIsBHFYlcFXMpye/J6Xv8i7Kgwdh iuQMd/tEg3++nTk8B8HJ1ZXHjdhwKQ6wrfxNrZO1FUpdijNycuRTwLYeVb8i/8TjT1fM OYmRO5QuBgWqbh3IKytEuxw8eROufXzuN40FrZdgIrZyisiLX7QXoIH/+IVAT1v1IRch ssUA== X-Gm-Message-State: AAQBX9dLXx7vqk/JfSHUF9ao2oSm4lPran4rAkaS+UdlSZWGC40SnMbB zW2kIXjpkQxU+R9AO7cI1CD5hw== X-Received: by 2002:a5d:564a:0:b0:2cf:efc7:19ad with SMTP id j10-20020a5d564a000000b002cfefc719admr6087233wrw.53.1681739012267; Mon, 17 Apr 2023 06:43:32 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id e11-20020a056000120b00b002e45f6ffe63sm10570412wrx.26.2023.04.17.06.43.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 17 Apr 2023 06:43:28 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 719411FFBE; Mon, 17 Apr 2023 14:43:22 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Peter Maydell , Bastian Koppelmann , Markus Armbruster , Beraldo Leal , =?utf-8?q?Alex_Benn=C3=A9e?= , Thomas Huth , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Cleber Rosa , Radoslaw Biernacki , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Leif Lindholm , John Snow , Paolo Bonzini , Wainer dos Santos Moschetta , qemu-arm@nongnu.org, Michael Tokarev , Kevin Wolf Subject: [PATCH v4 6/6] qemu-options: finesse the recommendations around -blockdev Date: Mon, 17 Apr 2023 14:43:21 +0100 Message-Id: <20230417134321.3627231-7-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230417134321.3627231-1-alex.bennee@linaro.org> References: <20230417134321.3627231-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::334; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x334.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: <20230330101141.30199-5-alex.bennee@linaro.org> --- v3 - more re-wording to try and approach consensus - add explicit warning to -snapshot option --- 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,