From patchwork Mon Dec 9 18:30:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900191 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 792CBE7717D for ; Mon, 9 Dec 2024 18:32:36 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXL-0002TL-MQ; Mon, 09 Dec 2024 13:31:15 -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 1tKiXK-0002SN-9C for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:14 -0500 Received: from mail-pf1-x434.google.com ([2607:f8b0:4864:20::434]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXG-0006tC-79 for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:13 -0500 Received: by mail-pf1-x434.google.com with SMTP id d2e1a72fcca58-7259a26ad10so3814230b3a.1 for ; Mon, 09 Dec 2024 10:31:09 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769069; x=1734373869; darn=nongnu.org; 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=KJHfvwnJg5sZrvdjrL2PvGyTWu88t+rIUYQX6WpdBU0=; b=uF9rfbcB0FydaEX23+7mulF5rWb8FqWuB5OLO60rRbDq7+fXK6ZFwo+c4yDO3m5z3Z MoQ2Ep7QGxWV8HGr9AO3KNvp2zxqrMrvdtNYv5IRmbP4/jxbDUhO8f0ApqOoTaHwjaZD OswsE1ujaY9ukFe7EqHqLA/vsEAafUma/AbQ8BmZ+uFMgiLIQivthHtH7RqeTyt3toZj LIr66vaizIVRE9RPv9aQZF09JUxHWRD983HfscZS56eeeCgl/qLwmnKgh3pN3yu9cUHW Hh+6DQ+arGNbv8GKd6PI47Pvj93Mbz945DmohBc7yXVx1czjhwS1hkgweMqhbu6fTdSD abvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769069; x=1734373869; 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=KJHfvwnJg5sZrvdjrL2PvGyTWu88t+rIUYQX6WpdBU0=; b=jaD5TUXOs/PwBiFLR8nXG64RZhsIjVd8BClYSO7VI0BE+7I4txD4Dq5FgZdYIIvuGe DGbBi5/62vv74CIu8a8DdfDqs+xc9bxeqXHtUjePv14dSWrrFKNbsqL+UllIHJC2Bkha jgrQV2tCzpBzXETiOrcyNVxjTfiQllHS4PZIEGzIQ3iTFaogbJpuWN9F+3XHdadote72 OWk2rkwMsahi9gBJzLCMtMndtbpFJ/894QTuntFsUItUj2NMLHlbMXf7nTkhpCrL7YHQ jReh7Objm2p+fewa9vhs9WPULU5ANHQaoi/6OmZZ77yTwa8KONJPibv+dGGTAazPpFvo 9lpQ== X-Gm-Message-State: AOJu0Ywi1gQGkTUb1mCpDHNC9g+Wjqargn9F8mZoIdXl8K2EMHFEv57S cwcO+qv9Xy0UUYmeUtBZqgIY/fKMeWMa3jCkkeObdYe26CRbewwB+I6RwvqZUSpOFmp19BTJdWX WrPg= X-Gm-Gg: ASbGncsvKt8z7ar4FOI4B8R9Ti5yoNNR98yvx9KFkW/wA9WVb8d3BmAqNff+7K1Tjpr pJhJQisY9C9ueuzPVubO2/gvDvmzcp8hTinJRU7w0o10bFcfnwbfVZuMUymQncQF3Qx1MnMhLlY kocBKWdCrYz9mVmpDsO8toqE/nxK1moI0QoaxWr7O1zkvr8riVA4IUPL2nrmBtj3EL09Rf6c51l D7I5DsEtQlBwKcj6HPEH3RR1kPDaoTq3WDh12piFAHbhNYQsUwLScWKIIMstefZMxNIclNd38co Az0QR9FVF7/g X-Google-Smtp-Source: AGHT+IH0W32vCMU/REHgWwitNQj0RdYViGRDdgZtnn1QKAsNMZMXRkehKM+GP8TM3mJLL1QW2KCPyw== X-Received: by 2002:a05:6a00:4513:b0:725:4a1b:38ec with SMTP id d2e1a72fcca58-7288810e22fmr752631b3a.3.1733769068840; Mon, 09 Dec 2024 10:31:08 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:08 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 1/6] docs/devel: remove dead video link for sourcehut submit process Date: Mon, 9 Dec 2024 10:30:59 -0800 Message-Id: <20241209183104.365796-2-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::434; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x434.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Reviewed-by: Thomas Huth Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/devel/submitting-a-patch.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst index 10b062eec26..03b2ac298aa 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -252,10 +252,7 @@ patches to the QEMU mailing list by following these steps: #. Send your patches to the QEMU mailing list using the web-based ``git-send-email`` UI at https://git.sr.ht/~USERNAME/qemu/send-email -`This video -`__ -shows the web-based ``git-send-email`` workflow. Documentation is -available `here +Documentation for sourcehut is available `here `__. .. _cc_the_relevant_maintainer: From patchwork Mon Dec 9 18:31:00 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900194 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 33BD1E7717D for ; Mon, 9 Dec 2024 18:33:27 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXK-0002Sp-S2; Mon, 09 Dec 2024 13:31:14 -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 1tKiXJ-0002Rv-Vb for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:14 -0500 Received: from mail-pf1-x433.google.com ([2607:f8b0:4864:20::433]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXH-0006tT-7s for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:13 -0500 Received: by mail-pf1-x433.google.com with SMTP id d2e1a72fcca58-7258bce5289so3670455b3a.0 for ; Mon, 09 Dec 2024 10:31:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769070; x=1734373870; darn=nongnu.org; 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=oUKq6vEd08BNHFL5xy+IGBW1qUyoIpn1SmzghDG21Ks=; b=suP7GaWbcb/NqWo9BY4r1ChUGurpmSk6CApq7rSSGn5GRz26K4H41FAD9c2jiGSszD JBpqzYI+K0yOlyKtg89Q9kQiQxU+qmc5iGK/RU7wb42YHXP3KgIPuMmEU9G+bwEJdoub to+oktZTVi/vysktOEcSfmIEKAi49jwZl6yU7C3f6LlUkqJLdfiEziI1Ygn2LPDHijIY +odI9T7w/lI7/1B+17F79ed1wSaqWQcYR+SNndx1lrxBkmXkbQSBTaCY3Uk3iRIqLHRZ ymHiLbOSxrMQ+9dXQK2sYNT1293poZ9FmRNAWzG2ctG/VdL0YZSvfh6226VmN1rtjokY MOgQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769070; x=1734373870; 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=oUKq6vEd08BNHFL5xy+IGBW1qUyoIpn1SmzghDG21Ks=; b=Mm6OcgbHrMWrl4SvBYoth53G72MnP24t3mrt3tFeGxDn5cQ53Ie/BO6t//15Kpbjge 0pjI5h7SePkCyt0B48EaOMsSW0VJzX7cdFpEIoBEUjL5kWerDwVQn4z8OqZz4xvH4XeF mjA3A4xfdBRhFfFk42V9kgQUUv3IG0VRWvVn33oSJco+DWydjgv5M2/13QEE+RdVpMs+ pozpm3eXHBvTGnpuu5q+Ypl3MzP0HdPU6z9oE3RzjEmhksPOZUnkG10bOAhSZgjmyH63 mlYkgrfCrTm1nRSWAUOHzBDuoUbImZrA206ZJXTBy+Q6gtLzBvmA0SgwJacWF4RYrZ3i zsgQ== X-Gm-Message-State: AOJu0YwcfTN/3pjTHi6DL1y5tNSE8AGxE5iuchdp9aaxXF7bq6bIesLM CLcQr8cHDhkl9f3PmIJ7abYvCfmkgE7WmnmIoJVVyOkseMv01J3sQ9i4dPaV2pir8NNO9LbiQcF Xseg= X-Gm-Gg: ASbGncs20i6WCc3a+zpSXwt61XEz72GatYjVI+kDhY/4un8uMFeR65LH/oJJnmUmZg8 tNVjN1/ZsgPOOtVWAQTFzaD7lD1FE2AHz6A+uu1awvLUe8MQ4kc9FsQAl5xOJNyG3UQcWW2dPh1 9xrUDL8tk5KvLwEOhqYRNYjP0iRsX0Nkfg6ZpyJdP6vvBE/d9D9JFyWilsZLuxUBgtWaGB4pTIJ SvO41WBAt3/lGTn9z4g6hCGfiKq2GYDvVvxznJPytTjMelkYSrut+YSxB3wBe45X0bjsxz9f+bC ueu+uogs/l1B X-Google-Smtp-Source: AGHT+IGHgMJ38Jmr7nbffgCDllf16U7JHr53zhYSJkDuJ8Dm6v3gmzXLAgJmZrZFftLzkhyV7DOVuA== X-Received: by 2002:a05:6a00:174b:b0:727:3c8f:3707 with SMTP id d2e1a72fcca58-7273c8f3efemr2557724b3a.23.1733769069981; Mon, 09 Dec 2024 10:31:09 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:09 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 2/6] docs/devel: add git-publish for patch submitting Date: Mon, 9 Dec 2024 10:31:00 -0800 Message-Id: <20241209183104.365796-3-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::433; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x433.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/devel/submitting-a-patch.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst index 03b2ac298aa..69df7682c5e 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -235,6 +235,31 @@ to another list.) ``git send-email`` (`step-by-step setup guide works best for delivering the patch without mangling it, but attachments can be used as a last resort on a first-time submission. +.. _use_git_publish: + +Use git-publish +~~~~~~~~~~~~~~~ + +If you already configured git send-email, you can simply use `git-publish +`__ to send series. + +:: + + $ git checkout master -b my-feature + $ # work on new commits, add your 'Signed-off-by' lines to each + $ git publish + $ ... more work, rebase on master, ... + $ git publish # will send a v2 + +Each time you post a series, git-publish will create a local tag with the format +``-v`` to record the patch series. + +When sending patch emails, 'git publish' will consult the output of +'scripts/get_maintainers.pl' and automatically CC anyone listed as maintainers +of the affected code. Generally you should accept the suggested CC list, but +there may sometimes be scenarios where it is appropriate to cut it down (eg on +certain large tree-wide cleanups), or augment it with other interested people. + .. _if_you_cannot_send_patch_emails: If you cannot send patch emails From patchwork Mon Dec 9 18:31:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900195 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 2F9CDE7717D for ; Mon, 9 Dec 2024 18:33:35 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXR-0002XJ-PO; Mon, 09 Dec 2024 13:31:21 -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 1tKiXL-0002T9-Fl for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:15 -0500 Received: from mail-pf1-x434.google.com ([2607:f8b0:4864:20::434]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXI-0006th-Cr for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:15 -0500 Received: by mail-pf1-x434.google.com with SMTP id d2e1a72fcca58-7259d6ae0c8so3963269b3a.0 for ; Mon, 09 Dec 2024 10:31:12 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769071; x=1734373871; darn=nongnu.org; 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=G1VOR+XcM8CwYRfbqrbxazmYwC9oKrYhK/MN/rkEn/Q=; b=zmtqe8GW5ta8RlCwnEZA3M7ZKbPyR17VUuvFkfGEavVzk71//1g+zxyPVTjPaJIWOY 9ql0Knhb1ZjQTGTW9BAEKAYr7et5dhnw+IkxnnNCWNRINJPtPfvUKjxbN1oxueC8P4F3 lTKXRo38UIj8ma8iOZ96JJXoAcE1edSk/jR3GCHg9vm+Lo+VWSD95/oiEM9XE8StLKFm oHj6+jkYXpJ/rgqMYPbDxGBxzXNsRwt73spUqdnxjr9ff+RdqXjf1NxvfNzbEDooQopn kZKdWy60Ef/Y8RwlOBBO1gjuo26+QEjx0y7FozNRbIO1Whb4YYXNMJzkR/EhLE11QUzy GRyA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769071; x=1734373871; 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=G1VOR+XcM8CwYRfbqrbxazmYwC9oKrYhK/MN/rkEn/Q=; b=fvSQJ4g7T4SaO53V/zxwTHbdsvCxCiIyeMDICnbKZWnxUta2fzFww+g42fNnC5MNI5 nATM9eyxzg1nOWOWOw7JOpe+tv3ZWtrV+uwNPT2Jc55l4rBgwICPVt7okzUhApEBZ4bJ TGVCXosMOfIuGt0f2ET2N+rlped0kTesPzjlOP3/w9WF/o8RY28vB+UrOfyKlyFMp6G+ 6NgsTIq9mz6BNnUdF7cpiyUOKUwMgMTnB404wOlPTo8Zqkl0EjFKN9Ej/BbTXUr0NZ9v g+TlNmOG+Izly2iosb3hF/bEiK6JOXgz2rEvB4xr/CalOagTu0MDscHLBFs1BNFRpCmF bFUg== X-Gm-Message-State: AOJu0YyJIFINZ4JclQ4BTTK+XevUALDS1m1kWCrTwFRDZlmCDq/lZePr stFl1J+XxirYoDaA79hwSHlwXHP/UAJoW8vDTR3b0nbsOPBxlr6Lvu2JqXY/mo3pEIuCtZ6kFgw tm0g= X-Gm-Gg: ASbGncsuMEJQjh2UB6WlF0GWARh3NT0lzYh31wGndUmC9xSyI6gF67i1rwActIWWrL2 4yXd8oabtjlUiHivpzxs6IXMhNTLE/DTqd6bMUc7RyPOSwBWBshQFabKJCbs0DrRUbSV/O/H7Yt v6dovB8A8wkUfXFfndkGVH4Qe8ceSOiBz5yonHl7sgL0tGiOe/2wG6WKpCT/I+OqW66NngkepXW DrW7XOl2VZwRVyncuAceV0qQ62lortJNvzT6hGatM6udmmDR4yEq4mwrKzLsaj9nBevoG8rU1OG //MtJDs7nLeH X-Google-Smtp-Source: AGHT+IEXRHQmFLOcJlksi4NjoGEt2qTEb+UNr9ZNna4mBykL2R6hP0+kn6KJCVsSIaIz7h2XZ+rUlg== X-Received: by 2002:a05:6a20:3d87:b0:1d9:c615:d1e6 with SMTP id adf61e73a8af0-1e18700f9d8mr20290552637.0.1733769071164; Mon, 09 Dec 2024 10:31:11 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:10 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 3/6] docs/devel: add b4 for patch retrieval Date: Mon, 9 Dec 2024 10:31:01 -0800 Message-Id: <20241209183104.365796-4-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::434; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x434.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/devel/submitting-a-patch.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst index 69df7682c5e..65c64078cb3 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -433,6 +433,20 @@ For more details on how QEMU's stable process works, refer to the .. _participating_in_code_review: +Retrieve an existing series +--------------------------- + +If you want to apply an existing series on top of your tree, you can simply use +`b4 `__. + +:: + + b4 shazam $msg-id + +The message id is related to the patch series that has been sent to the mailing +list. You need to retrieve the "Message-Id:" header from one of the patches. Any +of them can be used and b4 will apply the whole series. + Participating in Code Review ---------------------------- From patchwork Mon Dec 9 18:31:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900193 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 63E42E7717D for ; Mon, 9 Dec 2024 18:32:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXU-0002Yf-Cl; Mon, 09 Dec 2024 13:31:24 -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 1tKiXO-0002Vi-Up for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:20 -0500 Received: from mail-pf1-x42a.google.com ([2607:f8b0:4864:20::42a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXL-0006uz-Gs for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:18 -0500 Received: by mail-pf1-x42a.google.com with SMTP id d2e1a72fcca58-7259d6ae0c8so3963313b3a.0 for ; Mon, 09 Dec 2024 10:31:14 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769074; x=1734373874; darn=nongnu.org; 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=CBM/p49u2jieahHwz0ZRKkSAG9NHcl7RjE84D7tGV3Y=; b=hpxrpztwav6FAa2osibZzFxDG4EiXbUtzyN1SRBZyBAaAe70jWVJFODhycMiahluJa DswKVJ4TbgAQ+KEpVW+F+K7lZvFT+IthMLfYxgqP9edfEXPECu0GnCOD28tkPx790O0b ceJlq4KLg1dCH7ARBjaBzVJlCM3FwQQHcQBiOtGCBgm5o4T0+DTw57e3mymluiogb3wH pb8XTUwLIKXPsjDNd6GP3U1ZVkVa9YGbYtrCSE6HRtvs2Y1gZW5W5mBeBvw3MJMf1d/r 1fz4MF4eq5ddeDRZICX/0Rk+6bmIdKX5osaJp5J7VlSFEiEILjJSfrUbNq9cv4I9Oy3X Up0A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769074; x=1734373874; 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=CBM/p49u2jieahHwz0ZRKkSAG9NHcl7RjE84D7tGV3Y=; b=kZbkR2hmyLisf9njWbQWFFAsplYZIBYqwtm/uAM7m+5D+V9Ya3lwUtYT1OrcakG3yc 7Q269qVGdm34EI9jGSKRNj6pU/Ktm3UP4jEacFv9an1N4+8z18EHvmo+DvnrQ4aApq4D KFNrK0qQ93nE96RET94vkIBNHfCtjRdSf+qH1pien2+JxGEevgY+BtgKrkDAJFOkRW7j KqLZQimJWGJn9vXLKLSrddGqLnwGGrehTeUXAMAXYLbRyNfBhAqpo1ADiaea2Qwcjeyt Cs0WT1YVtDpsc/tic24OLMBnkZd30tTE7n0Xld8wMwOio7c+CQlGvHZQcF5Qes6arkKq ou9A== X-Gm-Message-State: AOJu0Yyr+GC9yoQTd5bXtFjgMlsgtXGasWphxdQyXmjeWA2Z7KX/woMW ywfRAuQl7fZ5KLLagWylQTpQjoRIh8972vifj3Os5/DzEwyRRJm7QJqF5S1e/fgbWwiPpZeWQaI gT6U= X-Gm-Gg: ASbGnct4ZcZqpv6O/vFGwk4cuk//Cmbm0ietMe3tPTumP2QK0CX6uFF0zZt2nI7ST+2 EXREzRykggmC4ILGYZDHfeGE/EwgzK+a34iUxudfOLWNCkF4znFqZuDRBCcWhuxiL5J3ysUrIQ1 NNuJMOhAeboCOOEj3HZe5gYhnkaggogJV14+Ucq08KzSY//qZ/NNkSdy11dfnc6tNH9Fi3Ak06A Skymgevby7MTbPSv1eVVImEhQ9FHW3aIdvM2mDOQM5g7lbYS0HD+ReTih2OgLCP2192R/n0xFbD IqOd+Yy+Lqzx X-Google-Smtp-Source: AGHT+IG4xVqZ5JAJVqvox16c4c22BfLKT+SrLm8O6qDi0i0+gSqm+GrVLMSA/VkkSOW5NViTFLxw9w== X-Received: by 2002:a05:6a20:c78c:b0:1e0:d848:9e83 with SMTP id adf61e73a8af0-1e1870cc3c8mr23445354637.25.1733769072320; Mon, 09 Dec 2024 10:31:12 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:11 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 4/6] docs/devel: add information on how to setup build environments Date: Mon, 9 Dec 2024 10:31:02 -0800 Message-Id: <20241209183104.365796-5-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::42a; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x42a.google.com X-Spam_score_int: -19 X-Spam_score: -2.0 X-Spam_bar: -- X-Spam_report: (-2.0 / 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, URIBL_SBL_A=0.1 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org MacOS and Linux are straightforward, but Windows needs a bit more details. Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/about/build-platforms.rst | 4 +- docs/devel/build-environment.rst | 118 +++++++++++++++++++++++++++++++ docs/devel/index-build.rst | 1 + 3 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 docs/devel/build-environment.rst diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst index d8b0445157f..482b09819c1 100644 --- a/docs/about/build-platforms.rst +++ b/docs/about/build-platforms.rst @@ -29,6 +29,9 @@ The `Repology`_ site is a useful resource to identify currently shipped versions of software in various operating systems, though it does not cover all distros listed below. +You can find how to install build dependencies for different systems on the +:ref:`setup-build-env` page. + Supported host architectures ---------------------------- @@ -130,7 +133,6 @@ Optional build dependencies cross compilation using ``docker`` or ``podman``, or to use pre-built binaries distributed with QEMU. - Windows ------- diff --git a/docs/devel/build-environment.rst b/docs/devel/build-environment.rst new file mode 100644 index 00000000000..f133ef2e012 --- /dev/null +++ b/docs/devel/build-environment.rst @@ -0,0 +1,118 @@ + +.. _setup-build-env: + +Setup build environment +======================= + +QEMU uses a lot of dependencies on the host system. glib2 is used everywhere in +the code base, and most of the other dependencies are optional. + +We present here simple instructions to enable native builds on most popular +systems. + +You can find additional instructions on `QEMU wiki `_: + +- `Linux `_ +- `MacOS `_ +- `Windows `_ +- `BSD `_ + +Note: Installing dependencies using your package manager build dependencies may +miss out on deps that have been newly introduced in qemu.git. In more, it misses +deps the distribution has decided to exclude. + +Linux +----- + +Fedora +++++++ + +:: + + sudo dnf update && sudo dnf builddep qemu + +Debian/Ubuntu ++++++++++++++ + +You first need to enable `Sources List `_. +Then, use apt to install dependencies: + +:: + + sudo apt update && sudo apt build-dep qemu + +MacOS +----- + +You first need to install `Homebrew `_. Then, use it to +install dependencies: + +:: + + brew update && brew install $(brew deps --include-build qemu) + +Windows +------- + +You first need to install `MSYS2 `_. +MSYS2 offers `different environments `_. +x86_64 environments are based on GCC, while aarch64 is based on Clang. + +We recommend to use MINGW64 for windows-x86_64 and CLANGARM64 for windows-aarch64 +(only available on windows-aarch64 hosts). + +Then, you can open a windows shell, and enter msys2 env using: + +:: + + c:/msys64/msys2_shell.cmd -defterm -here -no-start -mingw64 + # Replace -ucrt64 by -clangarm64 or -ucrt64 for other environments. + +MSYS2 package manager does not offer a built-in way to install build +dependencies. You can start with this list of packages using pacman: + +Note: Dependencies need to be installed again if you use a different MSYS2 +environment. + +:: + + # update MSYS2 itself, you need to reopen your shell at the end. + pacman -Syu + pacman -S \ + base-devel binutils bison diffutils flex git grep make sed \ + ${MINGW_PACKAGE_PREFIX}-toolchain \ + ${MINGW_PACKAGE_PREFIX}-glib2 \ + ${MINGW_PACKAGE_PREFIX}-gtk3 \ + ${MINGW_PACKAGE_PREFIX}-libnfs \ + ${MINGW_PACKAGE_PREFIX}-libssh \ + ${MINGW_PACKAGE_PREFIX}-ninja \ + ${MINGW_PACKAGE_PREFIX}-pixman \ + ${MINGW_PACKAGE_PREFIX}-pkgconf \ + ${MINGW_PACKAGE_PREFIX}-python \ + ${MINGW_PACKAGE_PREFIX}-SDL2 \ + ${MINGW_PACKAGE_PREFIX}-zstd + +If you want to install all dependencies, it's possible to use recipe used to +build QEMU in MSYS2 itself. + +:: + + pacman -S wget + wget https://raw.githubusercontent.com/msys2/MINGW-packages/refs/heads/master/mingw-w64-qemu/PKGBUILD + # Some packages may be missing for your environment, installation will still + # be done though. + makepkg -s PKGBUILD || true + +Build on windows-aarch64 +++++++++++++++++++++++++ + +When trying to cross compile meson for x86_64 using UCRT64 or MINGW64 env, +configure will run into an error because the cpu detected is not correct. + +Meson detects x86_64 processes emulated, so you need to manually set the cpu, +and force a cross compilation (with empty prefix). + +:: + + ./configure --cpu=x86_64 --cross-prefix= + diff --git a/docs/devel/index-build.rst b/docs/devel/index-build.rst index 0023953be36..0745c81a264 100644 --- a/docs/devel/index-build.rst +++ b/docs/devel/index-build.rst @@ -8,6 +8,7 @@ some of the basics if you are adding new files and targets to the build. :maxdepth: 3 build-system + build-environment kconfig docs qapi-code-gen From patchwork Mon Dec 9 18:31:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900197 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id BAF3EE77180 for ; Mon, 9 Dec 2024 18:34:00 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXV-0002Zt-1Z; Mon, 09 Dec 2024 13:31:25 -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 1tKiXO-0002Ve-5J for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:20 -0500 Received: from mail-pf1-x434.google.com ([2607:f8b0:4864:20::434]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXL-0006ur-2N for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:17 -0500 Received: by mail-pf1-x434.google.com with SMTP id d2e1a72fcca58-725ea1e19f0so1169782b3a.3 for ; Mon, 09 Dec 2024 10:31:14 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769074; x=1734373874; darn=nongnu.org; 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=/MuVNprpGhyEcqzXVswBzj9g9gub8HhCEXmUyVLm7RY=; b=uh4UOp4blFDAsEIRCdRweeX6Pt02+5dM23+njhHoeqQBJje3eDJLsAx8aPHBPk2hJe nNKXxRPVAtmai9a+ZxqhnWjWWV9KH0v71Z6KqJEK+660Dj2tDo4B36Y830UPuxXv2Y/5 vLdcCfdHNGnZ6+OVnbEKjLhQMBjrSsfnFCpxT9AGxOu2zYTXEyiUwtHEZmuQWxYQO8lt TcnjuyHHhMYgugxelROSoJKNe0/rriWRkFfwaWJoG+yOkcn3PdplsodP8BntSKVaZoVq NU6V+qe6dxF4Sk2vGD6VI63L8hWNpwUQHE53H9V2XZLccqivmfw5KT6ppM0PoH755Xaq dFVQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769074; x=1734373874; 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=/MuVNprpGhyEcqzXVswBzj9g9gub8HhCEXmUyVLm7RY=; b=Rm2MevILA3QXmn/DEHKX6AD0HtJv36tx7ezg4ziDqncoST5eulDXOU6yMmJnC24FXa /HSf4y1LKHsx6vwx4dVUCUylBvRzfvTKeHVgVq41UGy1xPpjOc7rQXBiP/Z8GF+2ZG2a e0urFZodxXlpkpTcTYA8c26Q1jZHHAiDZ/4rpV8dyGfVuwNIn7sgNGz/4MTDhDSY6gSB bmQeh9ipdKQTTahQpndRztlB7ACiobrnBQgZJSh2cRBcMwpdZa3ttvPNEhUGf3YGsPKu M6ewCBbZZiM5MeBg4bGFdREb1zPoZtXfSBwpu9fTwZylJCFSc1GVLI1tDku4LJ0w5vBd 3WCQ== X-Gm-Message-State: AOJu0YwvORZkcgww/9hCaWif2eX7cxmMLYVSQCVMrF6OjGZ6ctyT/PUB hmmLnq+xXOzV216ETQvfo4e35Qaggv4HZgvWKWyZ8w+U1s3TWm6lGKSTJpX3liywSEZAcF2/yx1 bhZw= X-Gm-Gg: ASbGncvNizSBhxQEXpsJh3cLt7p784PglmWSQ1OxAkQ6N4rjwZCpBc8VbwaBzYPf/iH wyo/ghvxN0vmR2blL5V9NVVDD2/DJeFlPQaJQdsOr8yyQaXo3htwudiQ4WTJ8Ye1hgSn6cPEtUf G3OUyfcmDgDABFfR6vQ4wawX/Qq3yycxGYc4tyEKk7WBf377Vki7uiDi0JMFEVDrH4rP0eHsQ73 miPIVlPK0AiKjFv8ppf4/Nc5wTbJ5d24m4w6xTKjalzFLSzDJqzm/a1zQ9T45nOqtDW4qnfgBgb C90Xg2uaPekM X-Google-Smtp-Source: AGHT+IFBZy/ZfFae6LugQyy+cCBrgxzYtpeocbwn3AownsvcW7RJtnqN2sesSubfVZkKDrXA1L6T4Q== X-Received: by 2002:a05:6a00:2d98:b0:724:e80a:33a with SMTP id d2e1a72fcca58-7273cba05c9mr2576334b3a.23.1733769073538; Mon, 09 Dec 2024 10:31:13 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:13 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 5/6] docs: add a codebase section Date: Mon, 9 Dec 2024 10:31:03 -0800 Message-Id: <20241209183104.365796-6-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::434; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x434.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 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Present the various parts of QEMU and organization of codebase. Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/about/emulation.rst | 2 + docs/devel/codebase.rst | 220 +++++++++++++++++++++++++ docs/devel/decodetree.rst | 2 + docs/devel/ebpf_rss.rst | 2 + docs/devel/index-internals.rst | 2 + docs/devel/index.rst | 1 + docs/devel/migration/main.rst | 2 + docs/devel/qapi-code-gen.rst | 1 + docs/devel/testing/main.rst | 9 +- docs/devel/testing/qtest.rst | 2 + docs/index.rst | 2 + docs/interop/qemu-ga.rst | 2 + docs/system/qemu-block-drivers.rst.inc | 2 + docs/tools/qemu-storage-daemon.rst | 2 + docs/user/main.rst | 6 + 15 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/devel/codebase.rst diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst index 3028d5fff7a..3bc3579434f 100644 --- a/docs/about/emulation.rst +++ b/docs/about/emulation.rst @@ -176,6 +176,8 @@ for that architecture. - System - Tensilica ISS SIMCALL +.. _tcg-plugins: + TCG Plugins ----------- diff --git a/docs/devel/codebase.rst b/docs/devel/codebase.rst new file mode 100644 index 00000000000..4039875ee04 --- /dev/null +++ b/docs/devel/codebase.rst @@ -0,0 +1,220 @@ +======== +Codebase +======== + +This section presents the various parts of QEMU and how the codebase is +organized. + +Beyond giving succint descriptions, the goal is to offer links to various +parts of the documentation/codebase. + +Subsystems +---------- + +An exhaustive list of subsystems and associated files can be found in the +`MAINTAINERS `_ +file. + +Some of the main QEMU subsystems are: + +- `Accelerators` +- Block devices and `disk images` support +- `CI` and `Tests` +- `Devices` & Board models +- `Documentation ` +- `GDB support` +- `Migration` +- `Monitor` +- :ref:`QOM (QEMU Object Model)` +- `System mode` +- :ref:`TCG (Tiny Code Generator)` +- `User mode` (`Linux` & `BSD`) +- User Interfaces + +More documentation on QEMU subsystems can be found on :ref:`internal-subsystem` +page. + +The Grand tour +-------------- + +We present briefly here what every folder in the top directory of the codebase +contains. Hop on! + +The folder name links here will take you to that folder in our gitlab +repository. Other links will take you to more detailed documentation for that +subsystem, where we have it. Unfortunately not every subsystem has documentation +yet, so sometimes the source code is all you have. + +* `accel `_: + Infrastructure and architecture agnostic code related to the various + `accelerators ` supported by QEMU + (TCG, KVM, hvf, whpx, xen, nvmm). + Contains interfaces for operations that will be implemented per + `target `_. +* `audio `_: + Audio (host) support. +* `authz `_: + `QEMU Authorization framework`. +* `backends `_: + Various backends that are used to access resources on the host (e.g. for + random number generation, memory backing or cryptographic functions). +* `block `_: + Block devices and `image formats` implementation. +* `bsd-user `_: + `BSD User mode`. +* build: Where the code built goes by default. You can tell the QEMU build + system to put the built code anywhere else you like. +* `chardev `_: + Various backends used by char devices. +* `common-user `_: + User-mode assembly code for dealing with signals occuring during syscalls. +* `configs `_: + Makefiles defining configurations to build QEMU. +* `contrib `_: + Community contributed devices/plugins/tools. +* `crypto `_: + Cryptographic algorithms used in QEMU. +* `disas `_: + Disassembly functions used by QEMU target code. +* `docs `_: + QEMU Documentation. +* `dump `_: + Code to dump memory of a running VM. +* `ebpf `_: + eBPF program support in QEMU. `virtio-net RSS` uses it. +* `fpu `_: + Floating-point software emulation. +* `fsdev `_: + `VirtFS `_ support. +* `gdbstub `_: + `GDB ` support. +* `gdb-xml `_: + Set of XML files describing architectures and used by `gdbstub `. +* `host `_: + Various architecture specific header files (crypto, atomic, memory + operations). +* `linux-headers `_: + A subset of headers imported from Linux kernel and used for implementing + KVM support and user-mode. +* `linux-user `_: + `User mode ` implementation. Contains one folder per target + architecture. +* `.gitlab-ci.d `_: + `CI ` yaml and scripts. +* `include `_: + All headers associated to different subsystems in QEMU. The hierachy used + mirrors source code organization and naming. +* `hw `_: + `Devices ` and boards emulation. Devices are categorized by + type/protocol/architecture and located in associated subfolder. +* `io `_: + QEMU `I/O channels `_. +* `libdecnumber `_: + Import of gcc library, used to implement decimal number arithmetic. +* `migration `__: + `Migration framework `. +* `monitor `_: + `Monitor ` implementation (HMP & QMP). +* `nbd `_: + QEMU `NBD (Network Block Device) ` server. +* `net `_: + Network (host) support. +* `pc-bios `_: + Contains pre-built firmware binaries and boot images, ready to use in + QEMU without compilation. +* `plugins `_: + :ref:`TCG plugins ` core implementation. Plugins can be found in + `tests `__ + and `contrib `__ + folders. +* `po `_: + Translation files. +* `python `_: + Python part of our build/test system. +* `qapi `_: + `QAPI ` implementation. +* `qobject `_: + QEMU Object implementation. +* `qga `_: + QEMU `Guest agent ` implementation. +* `qom `_: + QEMU :ref:`Object model ` implementation, with monitor associated commands. +* `replay `_: + QEMU :ref:`Record/replay ` implementation. +* `roms `_: + Contains source code for various firmware and ROMs, which can be compiled if + custom or updated versions are needed. +* `rust `_: + Rust integration in QEMU. It contains the new interfaces defined and + associated devices using it. +* `scripts `_: + Collection of scripts used in build and test systems, and various + tools for QEMU codebase and execution traces. +* `scsi `_: + Code related to SCSI support, used by SCSI devices. +* `semihosting `_: + QEMU `Semihosting ` implementation. +* `stats `_: + `Monitor ` stats commands implementation. +* `storage-daemon `_: + QEMU `Storage daemon ` implementation. +* `stubs `_: + Various stubs (empty functions) used to compile QEMU with specific + configurations. +* `subprojects `_: + QEMU submodules used by QEMU build system. +* `system `_: + QEMU `system mode ` implementation (cpu, mmu, boot support). +* `target `_: + Contains code for all target architectures supported (one subfolder + per arch). For every architecture, you can find accelerator specific + implementations. +* `tcg `_: + :ref:`TCG ` related code. + Contains one subfolder per host supported architecture. +* `tests `_: + QEMU `test ` suite + + - `avocado `_: + Functional tests booting full VM using `Avocado framework `. + Those tests will be transformed and moved into + `tests/functional `_ + in the future. + - `data `_: + Data for various tests. + - `decode `_: + Testsuite for :ref:`decodetree ` implementation. + - `docker `_: + Code and scripts to create `containers ` used in `CI `. + - `fp `_: + QEMU testsuite for soft float implementation. + - `functional `_: + `Functional tests ` (full VM boot). + - `lcitool `_: + Generate dockerfiles for CI containers. + - `migration `_: + Test scripts and data for `Migration framework `. + - `multiboot `_: + Test multiboot functionality for x86_64/i386. + - `qapi-schema `_: + Test scripts and data for `QAPI `. + - `qemu-iotests `_: + `Disk image and block tests `. + - `qtest `_: + `Device emulation testing `. + - `tcg `__: + `TCG related tests `. Contains code per architecture + (subfolder) and multiarch tests as well. + - `tsan `_: + `Suppressions ` for thread sanitizer. + - `uefi-test-tools `_: + Test tool for UEFI support. + - `unit `_: + QEMU `Unit tests `. +* `trace `_: + :ref:`Tracing framework `. Used to print information associated to various + events during execution. +* `ui `_: + QEMU User interfaces. +* `util `_: + Utility code used by other parts of QEMU. diff --git a/docs/devel/decodetree.rst b/docs/devel/decodetree.rst index e3392aa7057..98ad33a4870 100644 --- a/docs/devel/decodetree.rst +++ b/docs/devel/decodetree.rst @@ -1,3 +1,5 @@ +.. _decodetree: + ======================== Decodetree Specification ======================== diff --git a/docs/devel/ebpf_rss.rst b/docs/devel/ebpf_rss.rst index 4a68682b31a..ed5d33767bd 100644 --- a/docs/devel/ebpf_rss.rst +++ b/docs/devel/ebpf_rss.rst @@ -1,3 +1,5 @@ +.. _ebpf-rss: + =========================== eBPF RSS virtio-net support =========================== diff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst index ab9fbc44826..bca597c6589 100644 --- a/docs/devel/index-internals.rst +++ b/docs/devel/index-internals.rst @@ -1,3 +1,5 @@ +.. _internal-subsystem: + Internal Subsystem Information ------------------------------ diff --git a/docs/devel/index.rst b/docs/devel/index.rst index a53f1bfda5d..29f032d6a82 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -35,3 +35,4 @@ the :ref:`tcg_internals`. index-api index-internals index-tcg + codebase diff --git a/docs/devel/migration/main.rst b/docs/devel/migration/main.rst index c2857fc2446..cdd4f4a6d7e 100644 --- a/docs/devel/migration/main.rst +++ b/docs/devel/migration/main.rst @@ -1,3 +1,5 @@ +.. _migration: + =================== Migration framework =================== diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 583207a8ec2..3e26d2d1047 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -9,6 +9,7 @@ How to use the QAPI code generator This work is licensed under the terms of the GNU GPL, version 2 or later. See the COPYING file in the top-level directory. +.. _qapi: Introduction ============ diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst index 91f4dc61fb5..9869bcf0341 100644 --- a/docs/devel/testing/main.rst +++ b/docs/devel/testing/main.rst @@ -39,6 +39,8 @@ Before running tests, it is best to build QEMU programs first. Some tests expect the executables to exist and will fail with obscure messages if they cannot find them. +.. _unit-tests: + Unit tests ~~~~~~~~~~ @@ -126,6 +128,8 @@ successfully on various hosts. The following list shows some best practices: #ifdef in the codes. If the whole test suite cannot run on Windows, disable the build in the meson.build file. +.. _qapi-tests: + QAPI schema tests ~~~~~~~~~~~~~~~~~ @@ -160,6 +164,8 @@ check-block are in the "auto" group). See the "QEMU iotests" section below for more information. +.. _qemu-iotests: + QEMU iotests ------------ @@ -679,6 +685,8 @@ The above exitcode=0 has TSan continue without error if any warnings are found. This allows for running the test and then checking the warnings afterwards. If you want TSan to stop and exit with error on warnings, use exitcode=66. +.. _tsan-suppressions: + TSan Suppressions ~~~~~~~~~~~~~~~~~ Keep in mind that for any data race warning, although there might be a data race @@ -901,7 +909,6 @@ You can run the avocado tests simply by executing: See :ref:`checkavocado-ref` for more details. - .. _checktcg-ref: Testing with "make check-tcg" diff --git a/docs/devel/testing/qtest.rst b/docs/devel/testing/qtest.rst index c5b8546b3eb..73ef7702b7b 100644 --- a/docs/devel/testing/qtest.rst +++ b/docs/devel/testing/qtest.rst @@ -1,3 +1,5 @@ +.. _qtest: + ======================================== QTest Device Emulation Testing Framework ======================================== diff --git a/docs/index.rst b/docs/index.rst index 0b9ee9901d9..78285ebd6a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _documentation-root: + ================================ Welcome to QEMU's documentation! ================================ diff --git a/docs/interop/qemu-ga.rst b/docs/interop/qemu-ga.rst index 11f7bae4600..d16cc1b9f07 100644 --- a/docs/interop/qemu-ga.rst +++ b/docs/interop/qemu-ga.rst @@ -1,3 +1,5 @@ +.. _qemu-ga: + QEMU Guest Agent ================ diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc index 384e95ba765..cfe1acb78ae 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -500,6 +500,8 @@ What you should *never* do: - expect it to work when loadvm'ing - write to the FAT directory on the host system while accessing it with the guest system +.. _nbd: + NBD access ~~~~~~~~~~ diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst index ea00149a63a..35ab2d78074 100644 --- a/docs/tools/qemu-storage-daemon.rst +++ b/docs/tools/qemu-storage-daemon.rst @@ -1,3 +1,5 @@ +.. _storage-daemon: + =================== QEMU Storage Daemon =================== diff --git a/docs/user/main.rst b/docs/user/main.rst index 7a126ee8093..80a77f0a0c9 100644 --- a/docs/user/main.rst +++ b/docs/user/main.rst @@ -1,3 +1,5 @@ +.. _user-mode: + QEMU User space emulator ======================== @@ -42,6 +44,8 @@ QEMU was conceived so that ultimately it can emulate itself. Although it is not very useful, it is an important test to show the power of the emulator. +.. _linux-user-mode: + Linux User space emulator ------------------------- @@ -175,6 +179,8 @@ Other binaries * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). +.. _bsd-user-mode: + BSD User space emulator ----------------------- From patchwork Mon Dec 9 18:31:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13900192 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 7BEE5E77180 for ; Mon, 9 Dec 2024 18:32:36 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tKiXT-0002Y5-EQ; Mon, 09 Dec 2024 13:31:23 -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 1tKiXQ-0002Vl-7b for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:20 -0500 Received: from mail-pf1-x42c.google.com ([2607:f8b0:4864:20::42c]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tKiXM-0006vW-4h for qemu-devel@nongnu.org; Mon, 09 Dec 2024 13:31:19 -0500 Received: by mail-pf1-x42c.google.com with SMTP id d2e1a72fcca58-725ec1fa493so1038084b3a.1 for ; Mon, 09 Dec 2024 10:31:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733769075; x=1734373875; darn=nongnu.org; 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=9xVIc4oLbUvffylwzaJFPYw9yLuH5RiCT1RExJQLxZ4=; b=vwr97q+mq4z94mfylVLE0bImTrDjab68brUGrYxaIS7Ov2kjtPMe7WgPJUallA8GMU xsexRLg9sjpVvAER+BCKOVrSunQyMM4dMR2YkVbyau3pOJQ/x1/S71o5lN3m6ujLP4Fp NLF9SM25CaKZpttfxeg3EN9/fWjs96zqbJ5XCnWJCf3v+ru/sYFlo8wtDaiuvFPre1Az 37GcCfPjvyoqB5cylzRaVf93ZAUhzH44WdGKIzqwa4BzPCBG9kjL3IsrIoXjivswCKNf PnYBMH0rw9UCOFXWsX42hqllCHJl/7D3SDkfHzqC7TwnTqHfLIUW8VvM/nronV17gqZZ WvCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733769075; x=1734373875; 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=9xVIc4oLbUvffylwzaJFPYw9yLuH5RiCT1RExJQLxZ4=; b=cI0eiX/u9ozcKeOSH6Xqh8lBWZBgF0tMtAiDBIXe1w6fKo7DnvYY1+XSw3h/FyNB2Z c50XvGIKBQeKSkNshSpx+ooGHqaSFbkPapHgaWQZund4KHahdrSjFR1buXlHRkKvYDYA doOu0Z5flkmbkkcLvnUZcuwdQ7ghXZuBDYchiL5sa/ihRiur1ZrSlP9mWkXEyzbonHIM ZLqELPLWaCphAcQ2N+0R2+GTJzLp0rP69/EpAuSgMwE6k8AaAxhNlmP0tdNF+biFB65y LXBh8q2AI+n12iSFG0jneENiIOWzPXCaQUgFqSVpba0/TzL/jcyu4NCdXf5gylL5NJRr Cu2Q== X-Gm-Message-State: AOJu0YyZuLS7oXK3de/iBFKSN6igjHaQT1TjWD1EKDoJkbtvGqeLD8/+ dFFlIz1E1gjp0eh+QKUhqgfyCoyyQoYiBFB3A9Cw7gD7mgklC/vkZ9pnf9+g8Zh84r4A853o8uc Ho6g= X-Gm-Gg: ASbGncunmI0mLa+vsz/bGXOQ4C1CeNsH1pAaHzFru/NfO80lZUE633FLlWCxUOniFNZ CZgzp10arYsShOjAjJZ+nVNwFtVeZ+74vVwDxsW9jAgxEHttf5ZDYjiLSSavrL+55o3T8PLdFrE SGqI5HUjjh7Wmd7Akgst0AjENQKvh1n2AQv5RKPTEDWRUhzEgsSbIV/HFql0O7HvXTrufPbAFS2 sGzQT0Qq0l1Gup/xbW5vZ67UyqdTFKj3aUHVzV7Z/jfU3vizIXk9pv5/piChF9KsCqb3v4c1iJ5 UnLL7Uhf X-Google-Smtp-Source: AGHT+IHjfQffJ50iazTBBzhllmHF6xbYWowlzIOHel+/fXonYS2uvwElEwLpjvNOHNtFnz++1VPMXg== X-Received: by 2002:a05:6a00:1141:b0:71e:4930:162c with SMTP id d2e1a72fcca58-7273c90aeb1mr2089069b3a.6.1733769074711; Mon, 09 Dec 2024 10:31:14 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-725e2388d37sm3322821b3a.73.2024.12.09.10.31.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Dec 2024 10:31:14 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: manos.pitsidianakis@linaro.org, Andrew Melnychenko , Thomas Huth , Michael Roth , qemu-block@nongnu.org, Jason Wang , =?utf-8?q?Daniel_P?= =?utf-8?q?=2E_Berrang=C3=A9?= , Yuri Benditovich , Kevin Wolf , Peter Xu , qemu-arm@nongnu.org, Peter Maydell , philmd@linaro.org, Fabiano Rosas , Konstantin Kostiuk , Eric Blake , Paolo Bonzini , Vladimir Sementsov-Ogievskiy , Markus Armbruster , gustavo.romero@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Richard Henderson , Pierrick Bouvier Subject: [PATCH v4 6/6] docs: add a glossary Date: Mon, 9 Dec 2024 10:31:04 -0800 Message-Id: <20241209183104.365796-7-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241209183104.365796-1-pierrick.bouvier@linaro.org> References: <20241209183104.365796-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::42c; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pf1-x42c.google.com X-Spam_score_int: -19 X-Spam_score: -2.0 X-Spam_bar: -- X-Spam_report: (-2.0 / 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, URIBL_SBL_A=0.1 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Reviewed-by: Richard Henderson Signed-off-by: Pierrick Bouvier --- docs/devel/control-flow-integrity.rst | 2 + docs/devel/multi-thread-tcg.rst | 2 + docs/glossary.rst | 280 ++++++++++++++++++++++++++ docs/index.rst | 1 + docs/system/arm/virt.rst | 2 + docs/system/images.rst | 2 + docs/tools/qemu-nbd.rst | 2 + 7 files changed, 291 insertions(+) create mode 100644 docs/glossary.rst diff --git a/docs/devel/control-flow-integrity.rst b/docs/devel/control-flow-integrity.rst index e6b73a4fe1a..3d5702fa4cc 100644 --- a/docs/devel/control-flow-integrity.rst +++ b/docs/devel/control-flow-integrity.rst @@ -1,3 +1,5 @@ +.. _cfi: + ============================ Control-Flow Integrity (CFI) ============================ diff --git a/docs/devel/multi-thread-tcg.rst b/docs/devel/multi-thread-tcg.rst index d706c27ea74..7fd0a07633d 100644 --- a/docs/devel/multi-thread-tcg.rst +++ b/docs/devel/multi-thread-tcg.rst @@ -4,6 +4,8 @@ This work is licensed under the terms of the GNU GPL, version 2 or later. See the COPYING file in the top-level directory. +.. _mttcg: + ================== Multi-threaded TCG ================== diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 00000000000..693d9855dd1 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,280 @@ +.. _Glossary: + +-------- +Glossary +-------- + +This section of the manual presents brief definitions of acronyms and terms used +by QEMU developers. + +Accelerator +----------- + +A specific API used to accelerate execution of guest instructions. It can be +hardware-based, through a virtualization API provided by the host OS (kvm, hvf, +whpx, ...), or software-based (tcg). See this description of `supported +accelerators`. + +Board +----- + +Another name for :ref:`machine`. + +Block +----- + +Block drivers are the available `disk formats and front-ends +` available, and block devices `(see Block device section on +options page)` are using them to implement disks for a +virtual machine. + +CFI +--- + +Control Flow Integrity is a hardening technique used to prevent exploits +targeting QEMU by detecting unexpected branches during execution. QEMU `actively +supports` being compiled with CFI enabled. + +Device +------ + +In QEMU, a device is a piece of hardware visible to the guest. Examples include +UARTs, PCI controllers, PCI cards, VGA controllers, and many more. + +QEMU is able to emulate a CPU, and all the hardware interacting with it, +including `many devices`. When QEMU runs a virtual machine +using a hardware-based accelerator, it is responsible for emulating, using +software, all devices. + +EDK2 +---- + +EDK2, as known as `TianoCore `_, is an open source +implementation of UEFI standard. QEMU virtual machines that boot a UEFI firmware +usually use EDK2. + +gdbstub +------- + +QEMU implements a `gdb server `, allowing gdb to attach to it and +debug a running virtual machine, or a program in user-mode. This allows +debugging the guest code that is running inside QEMU. + +glib2 +----- + +`GLib2 `_ is one of the most important libraries we +are using through the codebase. It provides many data structures, macros, string +and thread utilities and portable functions across different OS. It's required +to build QEMU. + +Guest agent +----------- + +The `QEMU Guest Agent ` is a daemon intended to be run within virtual +machines. It provides various services to help QEMU to interact with it. + +.. _guest: + +Guest +----- + +Guest is the architecture of the virtual machine, which is emulated. +See also :ref:`host`. + +Sometimes this is called the :ref:`target` architecture, but that term +can be ambiguous. + +.. _host: + +Host +---- + +Host is the architecture on which QEMU is running on, which is native. +See also :ref:`guest`. + +Hypervisor +---------- + +The formal definition of an hypervisor is a program or API than can be used to +manage a virtual machine. QEMU is a virtualizer, that interacts with various +hypervisors. + +In the context of QEMU, an hypervisor is an API, provided by the Host OS, +allowing to execute virtual machines. Linux implementation is KVM (and supports +Xen as well). For MacOS, it's HVF. Windows defines WHPX. And NetBSD provides +NVMM. + +.. _machine: + +Machine +------- + +QEMU's system emulation models many different types of hardware. A machine model +(sometimes called a board model) is the model of a complete virtual system with +RAM, one or more CPUs, and various devices. It can be selected with the option +``-machine`` of qemu-system. Our machine models can be found on this `page +`. + +Migration +--------- + +QEMU can save and restore the execution of a virtual machine between different +host systems. This is provided by the `Migration framework`. + +NBD +--- + +The `QEMU Network Block Device server ` is a tool that can be used to +mount and access QEMU images, providing functionality similar to a loop device. + +Mailing List +------------ + +This is `where `_ all the +development happens! Changes are posted as series, that all developers can +review and share feedback for. + +For reporting issues, our `GitLab +`_ tracker is the best place. + +.. _softmmu: + +MMU / softmmu +------------- + +The Memory Management Unit is responsible for translating virtual addresses to +physical addresses and managing memory protection. QEMU system mode is named +"softmmu" precisely because it implements this in software, including a TLB +(Translation lookaside buffer), for the guest virtual machine. + +QEMU user-mode does not implement a full software MMU, but "simply" translates +virtual addresses by adding a specific offset, and relying on host MMU/OS +instead. + +Monitor / QMP / HMP +------------------- + +The `QEMU Monitor ` is a text interface which can be used to interact +with a running virtual machine. + +QMP stands for QEMU Monitor Protocol and is a json based interface. +HMP stands for Human Monitor Protocol and is a set of text commands available +for users who prefer natural language to json. + +MTTCG +----- + +Multiple CPU support was first implemented using a round-robin algorithm +running on a single thread. Later on, `Multi-threaded TCG ` was developed +to benefit from multiple cores to speed up execution. + +Plugins +------- + +`TCG Plugins ` is an API used to instrument guest code, in system +and user mode. The end goal is to have a similar set of functionality compared +to `DynamoRIO `_ or `valgrind `_. + +One key advantage of QEMU plugins is that they can be used to perform +architecture agnostic instrumentation. + +Patchew +------- + +`Patchew `_ is a website that tracks patches on the +Mailing List. + +PR +-- + +Once a series is reviewed and accepted by a subsystem maintainer, it will be +included in a PR (Pull Request) that the project maintainer will merge into QEMU +main branch, after running tests. + +The QEMU project doesn't currently expect most developers to directly submit +pull requests. + +QCOW2 +----- + +QEMU Copy On Write is a disk format developed by QEMU. It provides transparent +compression, automatic extension, and many other advantages over a raw image. + +qcow2 is the recommended format to use. + +QEMU +---- + +`QEMU (Quick Emulator) `_ is a generic and open source +machine emulator and virtualizer. + +QOM +--- + +`QEMU Object Model ` is an object oriented API used to define various +devices and hardware in the QEMU codebase. + +Record/replay +------------- + +`Record/replay ` is a feature of QEMU allowing to have a deterministic +and reproducible execution of a virtual machine. + +Rust +---- + +`A new programming language `_, memory safe by +default. There is a work in progress to integrate it in QEMU codebase for +various subsystems. + +System mode +----------- + +QEMU System mode provides a virtual model of an entire machine (CPU, memory and +emulated devices) to run a guest OS. In this mode the CPU may be fully emulated, +or it may work with a hypervisor such as KVM, Xen or Hypervisor.Framework to +allow the guest to run directly on the host CPU. + +QEMU System mode is called :ref:`softmmu ` as well. + +.. _target: + +Target +------ + +The term "target" can be ambiguous. In most places in QEMU it is used as a +synonym for :ref:`guest`. For example the code for emulating Arm CPUs is in +``target/arm/``. However in the :ref:`TCG subsystem ` "target" refers to the +architecture which QEMU is running on, i.e. the :ref:`host`. + +TCG +--- + +TCG is the QEMU `Tiny Code Generator `. It is the JIT (just-in-time) +compiler we use to emulate a guest CPU in software. + +It is one of the accelerators supported by QEMU, and supports a lot of +guest/host architectures. + +User mode +--------- + +QEMU User mode can launch processes compiled for one CPU on another CPU. In this +mode the CPU is always emulated. In this mode, QEMU translate system calls from +guest to host kernel. It is available for Linux and BSD. + +VirtIO +------ + +VirtIO is an open standard used to define and implement virtual devices with a +minimal overhead, defining a set of data structures and hypercalls (similar to +system calls, but targeting an hypervisor, which happens to be QEMU in our +case). It's designed to be more efficient than emulating a real device, by +minimizing the amount of interactions between a guest VM and its hypervisor. + +vhost-user +---------- + +`Vhost-user ` is an interface used to implement VirtIO devices +outside of QEMU itself. diff --git a/docs/index.rst b/docs/index.rst index 78285ebd6a4..5665de85cab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,3 +20,4 @@ Welcome to QEMU's documentation! interop/index specs/index devel/index + glossary diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst index e67e7f0f7c5..11ceb898264 100644 --- a/docs/system/arm/virt.rst +++ b/docs/system/arm/virt.rst @@ -1,3 +1,5 @@ +.. _arm-virt: + 'virt' generic virtual platform (``virt``) ========================================== diff --git a/docs/system/images.rst b/docs/system/images.rst index d000bd6b6f1..a5551173c97 100644 --- a/docs/system/images.rst +++ b/docs/system/images.rst @@ -82,4 +82,6 @@ VM snapshots currently have the following known limitations: - A few device drivers still have incomplete snapshot support so their state is not saved or restored properly (in particular USB). +.. _block-drivers: + .. include:: qemu-block-drivers.rst.inc diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst index 329f44d9895..4f21b7904ac 100644 --- a/docs/tools/qemu-nbd.rst +++ b/docs/tools/qemu-nbd.rst @@ -1,3 +1,5 @@ +.. _qemu-nbd: + ===================================== QEMU Disk Network Block Device Server =====================================