From patchwork Mon Apr 24 09:22:37 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: 676561 Delivered-To: patch@linaro.org Received: by 2002:a5d:4a41:0:0:0:0:0 with SMTP id v1csp2054736wrs; Mon, 24 Apr 2023 02:25:04 -0700 (PDT) X-Google-Smtp-Source: AKy350aJrY5VYbWnEn4bGYpCp1lQ3qDr1D0P5n1eujyRZ1MVJDJlvQg/mvjG6ynai0SvcQbv9xcF X-Received: by 2002:a05:622a:d2:b0:3ef:37e3:cc5d with SMTP id p18-20020a05622a00d200b003ef37e3cc5dmr23026376qtw.17.1682328304512; Mon, 24 Apr 2023 02:25:04 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682328304; cv=none; d=google.com; s=arc-20160816; b=0aI9m218m70SF4r9hWT4+ZB6d4/NfPDXWz3JNoKKw/MWnyQPBmuy1+k+NN0hv1iqBN KM6A+IP8ckmzo9D1/XxQ+Z6wa/R/L9d16h5KD0D8036PzP0OOEQhbs4PTJVDumrZV9Zd 9SGxeN01eR1KE5/ezEF92Zp8vUxVMi+f3HXpaRkNxpi27R7wRe86Jttw6QhZTA4Pqlu2 BYp5ZFinZp70FS7z7t7nQftkux4WcrnC3/P+wAqOEIL36GN+nGBEhiRWBG0DkRGlLCJT 8SSAPDi7JatJqAQNd7z3G7B7s9FxbLLAPvsrWUqOSLpoWW+rNhV4jX8AuqEWzX9GcoWI Yonw== 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=lZgm+vGcTA1V9BHjB7oPcAA/f7caN4cqjQx2QPPAA1g=; b=axsoVGjfozAFLAtEd34jEbWXpylvUF37MK+pIw7Fwt9IS+56D5f/ul7W1v9olxs/N+ BIKfcAjS3jza4ncU6W1Y7zVAJoLlcIro8yOxC5nEqM6xX1LVnm0NoBbb9/4cv398QbRD xEzwJo77XYLJp8ZTDwhDsa9aMCBj9Y7EmVKrwEXZcPiPsw6W/bp0TAAFvNnYDubTDwFc DrYUeIlsQp0RW8QQnpUfxxJHBJ8TW/4vhv/zGyD6o2JWdhSzAZ5dK0ANQAleeDyB66vV o5WSEBGsyrAblUs1dbrPOO+RHsiW6EjPhCkCt5+xVe2Bpn6VKsFXwXIiRIGORQDolfQP MXSQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=nsNVKmcQ; 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 g9-20020ac85d49000000b003e3874d7b5dsi6701181qtx.721.2023.04.24.02.25.04 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 24 Apr 2023 02:25:04 -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=nsNVKmcQ; 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 1pqsQ3-0007Xr-7a; Mon, 24 Apr 2023 05:23:35 -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 1pqsPb-0007Ei-Gh for qemu-devel@nongnu.org; Mon, 24 Apr 2023 05:23:07 -0400 Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pqsPP-0004mU-OO for qemu-devel@nongnu.org; Mon, 24 Apr 2023 05:23:07 -0400 Received: by mail-wm1-x335.google.com with SMTP id 5b1f17b1804b1-3f19afc4fbfso19027795e9.2 for ; Mon, 24 Apr 2023 02:22:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1682328174; x=1684920174; 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=lZgm+vGcTA1V9BHjB7oPcAA/f7caN4cqjQx2QPPAA1g=; b=nsNVKmcQvjG9yzQn35Z8ya1Aiv0aVEam3dE+syo8uSwP0o6H7d+2jyvTGdGIm+7nZI 7e1hi3Fa+f+YRbZ1oevdZiiE5O4wMolQbAPNUm+Sr1uEGaB+OlCSC3IuzGptaw2sh6eS n2GOe3ajQb7oNODrLZPyF+omRIVNq9XQ8eUx56nHw8lArSj1fdtgcjhhUFZlwr7tFrCA nW0OFJokZTiJ2eCOcTnHpyL425a1KvPpfvkF7+2N7tE/OQ9g35DFbfD5xwbVvH4IHexm 2sMpQOnEdVdDB1x8oFwpsemTbRVjER5575TT+sPvlMujP00fa9oByChTdS40DJe3wGt9 vJwQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682328174; x=1684920174; 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=lZgm+vGcTA1V9BHjB7oPcAA/f7caN4cqjQx2QPPAA1g=; b=PmLQYGT3jPLqrzIvmlkDzf9U4PjDPwLwzmhRsKnLYYebEpOROTZ8BXDjfj+pS+9DqV OZWyw13BXRPIpwBZuyiy8Y1WNj6BYdlT02ip58kFH0tFRfD5QTNjwG4MKyRFrbRRMNCQ kj5RuFJsvysQqd359Qy1bMPLyhqQV+KcVhtTCa8SrlwQWLDccQaLjCC3wo8FGA7M9T2K L/z378MAnsjsL96+U4SCVCYBdAmcNr5TAw2vHJA/XqO4+pCe+6HKcshoQIb8z4LMcms5 Oye7ZKZ31ZYhikEqBAfdqU2p2ckJHx+P0spyf1h+jg6mFnNtovdLLbpsZqxQpugvwW2d oSww== X-Gm-Message-State: AAQBX9fiZEYUB8V1w7u0dW4BbKQAf1pVuBmpiDzJcome1MClkiFoDy1I f9emkt3GgzX3DfwuslREVpgLzA== X-Received: by 2002:a7b:cc98:0:b0:3f1:6ebe:d598 with SMTP id p24-20020a7bcc98000000b003f16ebed598mr7049943wma.7.1682328174013; Mon, 24 Apr 2023 02:22:54 -0700 (PDT) Received: from zen.linaroharston ([85.9.250.243]) by smtp.gmail.com with ESMTPSA id l2-20020a1c7902000000b003f193d7c6b7sm8205288wme.41.2023.04.24.02.22.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 24 Apr 2023 02:22:53 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id 2550C1FFBE; Mon, 24 Apr 2023 10:22:50 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: qemu-devel@nongnu.org Cc: Wainer dos Santos Moschetta , Beraldo Leal , Thomas Huth , =?utf-8?q?Alex_Benn=C3=A9e?= , "Edgar E. Iglesias" , Paolo Bonzini , Aurelien Jarno , Peter Maydell , Juan Quintela , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Richard Henderson , Joel Stanley , Leif Lindholm , Markus Armbruster , Radoslaw Biernacki , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , John Snow , Andrew Jeffery , David Hildenbrand , Bastian Koppelmann , Max Filippov , qemu-s390x@nongnu.org, Cleber Rosa , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , =?utf-8?q?Dani?= =?utf-8?q?el_P=2E_Berrang=C3=A9?= , qemu-arm@nongnu.org, Eduardo Habkost , Ilya Leoshkevich , Michael Tokarev , Kevin Wolf Subject: [PATCH 06/18] qemu-options: finesse the recommendations around -blockdev Date: Mon, 24 Apr 2023 10:22:37 +0100 Message-Id: <20230424092249.58552-7-alex.bennee@linaro.org> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230424092249.58552-1-alex.bennee@linaro.org> References: <20230424092249.58552-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::335; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x335.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 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,