From patchwork Mon Nov 18 17:23:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878904 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 C1506D591A8 for ; Mon, 18 Nov 2024 17:26:47 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5Ug-00009Y-F4; Mon, 18 Nov 2024 12:24:58 -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 1tD5U4-0008N2-JN for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:23 -0500 Received: from mail-pl1-x636.google.com ([2607:f8b0:4864:20::636]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U0-0002oD-Ar for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:18 -0500 Received: by mail-pl1-x636.google.com with SMTP id d9443c01a7336-20c70abba48so18138895ad.0 for ; Mon, 18 Nov 2024 09:24:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950655; x=1732555455; 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=i4RsMVroYRLEeyBEwglGNgeTU+l2C3LQibeRDMRaXh0=; b=IoOIdnw/6HtZoeZ7VbU0QQX+zDBUq+/LVMkaMgYGd9d3qg6i+eSji1097ASow5K8or MwUxvlUeyw+ESPpjsSozibDv0IdMNvBar0TBdJ95oOvn6frzX73FD7TrlcnYkAkWHVP1 WvexakIBb9f+NWu7tF5EBsSijAt0hauqNI9WLNPgr55hfCVIlO1SHsXj7cPwa14PtSi4 izJShZDrPxDXoJe1e5GAV071noyQclNAvc+tazeVxJpL3p/hRhvc2MX2DwVOoSmm9eEU GG/x0hCQVa+uDF8jpmFR9xgxf1CZPlijZgoKZtAuYXBbEtYtbIphz1opywGSEptOfMth Eq7A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950655; x=1732555455; 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=i4RsMVroYRLEeyBEwglGNgeTU+l2C3LQibeRDMRaXh0=; b=a0KDhOJvoso1Lh9t/a2qDXmeoRPlE1+AXtUWADeYAZiIR9llr+g/ZikxI5w9BDjmFL OCcyxD1cSOH3MX/uaPgqKimzahylQ8CMbeuVGF2GhcLUS8Jv+s/O3XWRsO3Vv/bOV8TJ /44W4APeRAUT+VLhG/YvNV3CAAS6jYQA0iwGKZ9MWUIhi26rJEi4lJnOSjX2L47lsypD DwBMmz7KqefN2vzt5OYufCWcpsJosaVBaSkVdDybPnF1WOS4LdMqn+NwMt1rAFwh2Yu3 A0zWybC7HAbMPOxbn2lsA8lpYeo02wHVVKMinZC91LS1CibQZO0KUNy3uFyMfmcEdOCd vnvg== X-Gm-Message-State: AOJu0YyZqVutFYGxiki6Q2o7832LdBYAFMeXcn7/Eej2Ge0Ze41qcOuA 2OnZsNFmkH9heskthV/vWqFG2QvNbf5nXlebjCvCnK/sF922kbAO0pQEvNZ3mMHbxoO0hVm8yYk vmlXt7w== X-Google-Smtp-Source: AGHT+IFBygmmPIfGUz8O9UWqNtcVccOTwB5Fr5+w+tOYYwbTSp47Wyg/hcvxZd8kCJUQ/HvoeEuAJw== X-Received: by 2002:a17:902:e74e:b0:211:f52d:4dfb with SMTP id d9443c01a7336-211f52d50e8mr141024505ad.34.1731950654881; Mon, 18 Nov 2024 09:24:14 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:14 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 1/7] docs/devel: remove dead video link for sourcehut submit process Date: Mon, 18 Nov 2024 09:23:51 -0800 Message-Id: <20241118172357.475281-2-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::636; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x636.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 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 83e9092b8c0..349c32ee3a9 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 Nov 18 17:23:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878902 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 1F412D591A9 for ; Mon, 18 Nov 2024 17:26:05 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5UR-0008TY-KI; Mon, 18 Nov 2024 12:24:43 -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 1tD5U5-0008NB-RQ for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:24 -0500 Received: from mail-pl1-x62a.google.com ([2607:f8b0:4864:20::62a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U2-0002oY-Gy for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:21 -0500 Received: by mail-pl1-x62a.google.com with SMTP id d9443c01a7336-20c714cd9c8so18860345ad.0 for ; Mon, 18 Nov 2024 09:24:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950656; x=1732555456; 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=QaxpMkzADG4IGRoaMKuDLbk1XxCkXT1oglYVymp2yRk=; b=Mq6U8nG3SIweCq2IKbeoEcsYU5/DftrTO6hPPADcZRArwhKp03HY0BFe73OkppFsO5 nq6X6QRjdio4/vBAlzMLeRhDzcCJd8NgA9DOqrN6weKMsiil+SbV7Xb8W3+mk828WtLH CFiHXqWnxY8bkn23+XQgmrQK1fr+lENkBYXYIgP7k/BM7+zwgmY528QpkH62S3jF/oIy wlbMBnPo6WmnmHmxYA6JPppNopwmdnrYt7tRG8ATF6INMz7I80AZr1EJKEJtF4ncttX+ bZ+icm0gXYZLBHvmTE50ZIjnL7E3IKKIX/vS4vmxnkiaV4aEkmooBZ2MKLz87ckoYdVZ aJ/A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950656; x=1732555456; 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=QaxpMkzADG4IGRoaMKuDLbk1XxCkXT1oglYVymp2yRk=; b=AkDdJ0ehjyLP7fh3HzPEfg6KHyZ8SBxZ3617zi2vrqXNo7W393Jn8NCEW8Id8gwopd j/IS7DpyLjY6WD4If7cxj56mwMza/v1Gh4cK/UGTP9TiqdGt05Nq3sCuFzyJFpUXLlPA obE0OYBOl1ee0c+yb7bf3b706x5U7KwPVZyKhLYDAEFdtFSG8q7Ft2SKBPVujoAbJNg2 b4LGAtNoB2AqzTpWF+60eMWPFsmWX4XMhI/HV6wiR66fqdpXjRx8CZS7Qay7alTmiPA8 deWtY3KO5Y5wiKKK6CTog10Pcl0YgA1urDzLjED3whd9q9CL1ctKAL+Afrj6ZSgvzDf1 uUxQ== X-Gm-Message-State: AOJu0YyUFcuCdAPA8NH/289yt66LURL26GKS9iVV591dEAAj60+8ZdBk aLLoK+5g8+SkNgdvfq9cynVKkmUwwmk0B422JPn/y/M4vxUjNhKR5Lqffy28jHBJOPv7NUL5dTj Lmef6tw== X-Google-Smtp-Source: AGHT+IFnMWEzRgiYq/B3mYM/U/z+PUqF1APKbd5/ZA8bwDsu0j2FORNnIWlcrwKq/X5tQE+U6piRrg== X-Received: by 2002:a17:902:d508:b0:20c:5c13:732e with SMTP id d9443c01a7336-211d0ebf9ffmr195717105ad.38.1731950656051; Mon, 18 Nov 2024 09:24:16 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:15 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 2/7] docs/devel: add git-publish for patch submitting Date: Mon, 18 Nov 2024 09:23:52 -0800 Message-Id: <20241118172357.475281-3-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::62a; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x62a.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 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 349c32ee3a9..953682f20cb 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission. .. _if_you_cannot_send_patch_emails: +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 + If you cannot send patch emails ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From patchwork Mon Nov 18 17:23:53 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878898 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 2E8E8D591A9 for ; Mon, 18 Nov 2024 17:25:28 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5UX-0008VE-Ou; Mon, 18 Nov 2024 12:24:50 -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 1tD5U6-0008NE-VF for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:24 -0500 Received: from mail-pl1-x62c.google.com ([2607:f8b0:4864:20::62c]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U4-0002ow-AQ for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:22 -0500 Received: by mail-pl1-x62c.google.com with SMTP id d9443c01a7336-2124ccf03edso90225ad.2 for ; Mon, 18 Nov 2024 09:24:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950657; x=1732555457; 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=oJI8STVH8Bo0tJY7LAmXxwBqwEyTRfjQjwFSYQdXg1E=; b=fw+0weitW8wMSegB//tppJ2hQYIZNdYcbPQ8cAgvNz8jSGq/gTT8Gy6pVomgHcUywO K/DuemwfMScvAMRZD7EouIfBfaI/o1Pxkq0KYInAGWBImuHJe58EZW+AuTjMzqnffp/M wYbku8pL+b3BwEy/rQBMJh0m6LL9aanPYlev+xBIP/wAW+DcE+bDojbB0gbOqFIRHP3e 1UPQGijnkdfgOhph9KTL0lXBhDUwmIHJ7OHSBzhnwc9jNvs3c8fGPdwS9EU3c96r7Vth Oh8rfD3pOlSBJnVAwyl9qNHN7TjkXIvCv+4pF7XQVpvrqVia5qrFi+uYMK/GpxpJ4xfd GQiA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950657; x=1732555457; 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=oJI8STVH8Bo0tJY7LAmXxwBqwEyTRfjQjwFSYQdXg1E=; b=wZOCO5yqMJ6ZHGZNaEhCb7r+RGdiW8IBDZ/LyQl0blTAa4owB2GP1cyRatb+HzS4y1 fBJFw5kAVLUHDippD50cixIRa2jFA4YAlB1QwZIEAVa3EtDPzF3KsTFS0ZOg1ymhgGCP 3AQcYwLbPt7jkOA7FgMmPtHmuQXYuSWNZNyRLilz8dbVbK5Id3RmvRhSPftrCbvrUzwz I1TknuLt3XKDK1m/z+q6dcWYJf56PbNPc4iExkE7rX/ev8JmCX9TD7EMmDAu/QhnQwd2 K5R6g3vPR++fvo6lvpvmagNjMWHtCVGPf58gtZYXfgiDbpRN6XRTCW8JVx4r5LrfOCQt zAeQ== X-Gm-Message-State: AOJu0YxPP1d5artBeYFHLb9jPvsvCU9HWWiE7p3lW4kehaGh2clGCf+P 8Q8KVhiJNM6BciqqKkDmr5c+w2ijuADWHKJ/+VZtfp1EydsgKwTlSnNJGLeFN/0MykDTWZcXz10 UIktP6w== X-Google-Smtp-Source: AGHT+IGKRu9eW2HfGpfNTqNSZ6X9JKssRl87etJ63B8V8eQW5O/yNx303ObNGLP/peeM6ZoQWUEZEA== X-Received: by 2002:a17:903:188:b0:211:f6e4:d68f with SMTP id d9443c01a7336-211f6e4d9f6mr102645405ad.6.1731950657231; Mon, 18 Nov 2024 09:24:17 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:16 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 3/7] docs/devel: add b4 for patch retrieval Date: Mon, 18 Nov 2024 09:23:53 -0800 Message-Id: <20241118172357.475281-4-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::62c; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x62c.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 Signed-off-by: Pierrick Bouvier --- docs/devel/submitting-a-patch.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst index 953682f20cb..d25c677d996 100644 --- a/docs/devel/submitting-a-patch.rst +++ b/docs/devel/submitting-a-patch.rst @@ -417,6 +417,16 @@ 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 + Participating in Code Review ---------------------------- From patchwork Mon Nov 18 17:23:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878903 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 49CF4D591A8 for ; Mon, 18 Nov 2024 17:26:28 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5UI-0008SF-M8; Mon, 18 Nov 2024 12:24:36 -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 1tD5U7-0008NI-GB for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:26 -0500 Received: from mail-pl1-x62e.google.com ([2607:f8b0:4864:20::62e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U4-0002pE-As for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:23 -0500 Received: by mail-pl1-x62e.google.com with SMTP id d9443c01a7336-20cb47387ceso45685045ad.1 for ; Mon, 18 Nov 2024 09:24:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950658; x=1732555458; 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=zrtTSIAZyM7Cil0D9jbVirGKiaDBwbsx28N7FRyo/s0=; b=emqFSxsRVAIha6htF8B6UkweCjfATd5Z8P0Vo4URNt0ZcoDZR/40b867BWMVnjArse o6/QBsN66YZkLgCgMelAvsMcqdcsE+DKcamy5V8DAcnuL2WC9+Xfz1YMdnP5ZHLs7qpd 1AF5bucs2WlBsKYqRQTuRFkyuW3i0nGdr19lYSlfHaXX0Tz8x4xj5Dt0hp3piRaJnFyn FhcIjRf6WOcjtEMrzrochp3d0o0vY+CIy5NKz6L3pIasrYMqbrpMyxO3+rXwucVExWCF 2TxcSyoSckaN4HGmNqzLJKDMTwPSjvgNHshEKUMgAP1qzdzyI16YYUJU2PgN9B9zo2vN 7sPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950658; x=1732555458; 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=zrtTSIAZyM7Cil0D9jbVirGKiaDBwbsx28N7FRyo/s0=; b=LLSZoqt0oOTgTur+DzyGQ/6K4mS94fCMNpxshoN1T+Z0XkmHnjuz/AOyPhTDhf7mkb gbfzqQYgfnV1swPDpcNfr38a4yGTpP1U+TEKKX9T3HF9hmRy1kqwT+RuCWzBKq/GuU16 3gkCFOkuksRfWoZIK+LpR6MTnQTmHhT97sjieg8mtKCqklMSGYq5BZfrLOcsetlDBR50 ZA6mjuFTrIVdX7DJZT3iifV8psenusDNyULf2jxYLXCWhXQUjQtwg97+Xu00Rh/mrJ3S KIyLpKStTu8Y/Ejw98MN/cb5nnR9NUl/e56Y6x47fQ7IUWnIm57jtzVbxN+iV5wgxGpf rPZw== X-Gm-Message-State: AOJu0Yw8RSN+QwKDYPEIWzizNW2uponQqqXbCaWs9GegTXh/XLxK0XQf D0WjAXtPh7s/l69yhrlaXGjWEySxaFP7zH4u4mxfpK8xQe7Zn5hNK3jT7jGd8J3cf/kLUyhz+6S 4kEqabA== X-Google-Smtp-Source: AGHT+IGHEKlIRWL+XYdRBjSjr+8KS7IdhoUvTf18r/81DSRfBRUnTVVNUgJVrL0Adv0eAFM3HfQNwQ== X-Received: by 2002:a17:902:da92:b0:20c:c694:f6c6 with SMTP id d9443c01a7336-211d0ed25e5mr183981405ad.49.1731950658440; Mon, 18 Nov 2024 09:24:18 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:18 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 4/7] docs/devel: add information on how to setup build environments Date: Mon, 18 Nov 2024 09:23:54 -0800 Message-Id: <20241118172357.475281-5-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::62e; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x62e.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 MacOS and Linux are straightforward, but Windows needs a bit more details. Signed-off-by: Pierrick Bouvier --- docs/about/build-platforms.rst | 4 +- docs/devel/build-environment.rst | 114 +++++++++++++++++++++++++++++++ docs/devel/index-build.rst | 1 + 3 files changed, 118 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 6102f00aec0..c1ea53db834 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..d9a66f5fcc6 --- /dev/null +++ b/docs/devel/build-environment.rst @@ -0,0 +1,114 @@ + +.. _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 `_ + +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 Nov 18 17:23:55 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878901 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 EEBD7D591A9 for ; Mon, 18 Nov 2024 17:25:52 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5UX-0008VP-OJ; Mon, 18 Nov 2024 12:24:50 -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 1tD5U9-0008Nh-Kz for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:26 -0500 Received: from mail-pl1-x633.google.com ([2607:f8b0:4864:20::633]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U5-0002pQ-D5 for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:25 -0500 Received: by mail-pl1-x633.google.com with SMTP id d9443c01a7336-2124a86f4cbso3080225ad.3 for ; Mon, 18 Nov 2024 09:24:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950660; x=1732555460; 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=h9HxfRSColzyRgnWUxT3Gaflq7HL/y/zcwmFE95sLP8=; b=bhsAFaEBDVKCDWyBd6fwyBx6XJb1gOB4LA2QsDfdq8b0q2Ike/Ogkti3RPVtC671m+ P44MHNpYp5EsYMyrN5XqcNC/slS6zSHBC3/oZ+DCPVpHTDKTHkplo8bPK92wBRu4ARNW /UNkq8oLkQde9CSz/jE+XKizXCLeWQPu8UTMABFbDCzMZ8e3MnP5dkajfXKPRHqQCbXk vtWG+jJ9vXIv4OIlK50l0A28Ai39Rp7J0Bvuc1uC9EjBZ44m2HeUQY7QXE5QihcZJfH2 Gkwjog8vk85dRY7+I+DOjUW4g/kjXxhT4ntNCPvbRrXsRKafaVV1Y86i519Mj0n4Y+xJ fD6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950660; x=1732555460; 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=h9HxfRSColzyRgnWUxT3Gaflq7HL/y/zcwmFE95sLP8=; b=v40rFj0J2qFYiwYLh8F/ZjHfvlVIr+1MSV35YPpBIM3AgsEesRSeR5tH6VVIWnxfAA vvidY7Qw8E6gGaz2oGWaOznF/sUSfIaMuh9ItEDEReM4ooLcfyMYGtBS0jJtNrygSe1X uIfc6JtBRr+jSrad30133gVPZY8xo+9LEVjToVJWaw7yitXMpvSq6utygWjrwGJNEuPm hlvQ5qVdbXUqZLis89QMkt1lOWI0UtX82ZAcs+dvzhAk2+35yOaQGz6Jx0ePGjvsGQnV FXi6oPW8be/XJr+LXo/hiXk85I9fheNksmsNzqIrV1KrYMMKgdkPMWEZBL/oP7sP8rqH cSRw== X-Gm-Message-State: AOJu0YweeGD9bhZ0c/baFvuBw14Fm/lnBDy19tQk8RCygqHlimGwJ+99 gyuoIVwB1vOTEZbxRVXfyqDZCh12N6batMSsK1FDgMyN9hVm9SKzB7NIgQRlhM6kRkRo7swifpA T921Zdw== X-Google-Smtp-Source: AGHT+IF7HS6uFcioplhZUs49S35wYy0zZzw62AaMee3JVDFU8J+BCULEA3+acYCmj7LGlhCIzF/JVA== X-Received: by 2002:a17:902:f551:b0:212:13e5:3ba4 with SMTP id d9443c01a7336-21213e543ccmr50232465ad.21.1731950659604; Mon, 18 Nov 2024 09:24:19 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:19 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 5/7] docs: add a codebase section Date: Mon, 18 Nov 2024 09:23:55 -0800 Message-Id: <20241118172357.475281-6-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::633; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x633.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. Signed-off-by: Pierrick Bouvier --- docs/about/emulation.rst | 2 + docs/codebase/index.rst | 211 +++++++++++++++++++++++++ docs/devel/decodetree.rst | 2 + docs/devel/ebpf_rss.rst | 2 + docs/devel/index-internals.rst | 2 + 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 | 3 + 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 + 14 files changed, 247 insertions(+), 1 deletion(-) create mode 100644 docs/codebase/index.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/codebase/index.rst b/docs/codebase/index.rst new file mode 100644 index 00000000000..353830ef175 --- /dev/null +++ b/docs/codebase/index.rst @@ -0,0 +1,211 @@ +======== +Codebase +======== + +This section present the various parts of QEMU and how 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 files associated can be found in +`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` +- `QOM (QEMU Object Model)` +- `System mode` +- `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 of the codebase contains. Hop on! + +* `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 used for device emulation. +* `block `_: + Block devices and `image formats` implementation. +* `bsd-user `_: + `BSD User mode`. +* build: Where the code built goes! +* `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. 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 `_: + `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 `Object model ` implementation, with monitor associated commands. +* `replay `_: + QEMU `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 `_: + `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 `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 `_: + `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/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..cb5e5098b65 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! ================================ @@ -18,3 +20,4 @@ Welcome to QEMU's documentation! interop/index specs/index devel/index + codebase/index 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 Nov 18 17:23:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878899 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 586A5D591A8 for ; Mon, 18 Nov 2024 17:25:28 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5Uc-00005H-VF; Mon, 18 Nov 2024 12:24:55 -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 1tD5UC-0008Po-OO for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:29 -0500 Received: from mail-pl1-x62b.google.com ([2607:f8b0:4864:20::62b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U6-0002q5-JQ for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:27 -0500 Received: by mail-pl1-x62b.google.com with SMTP id d9443c01a7336-20cbcd71012so24157825ad.3 for ; Mon, 18 Nov 2024 09:24:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950661; x=1732555461; 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=VBgtkjSEbYTTKzs2OsUJSbyBpcPy82P3Qfcz05KH5DM=; b=f3piH8QrDbQd5MkOWEaSnkPPHq+h//ZK1rCjfYqHyBv/NEfylr4h5UVClFcoukFnpL fLkuMPPz7iXeokJ6bckSRo0k11xrw512ZYNn3bHPzsx+gPbOcCK1n5OJx7UHCSXT/dSP vHVoH29muIQtXokToC6Pih0sEHVRN1/ylJBcKINGzUg8Fzcn4EDWU7XMu05CDOhQjiwN co9dldBNripKSUGzGIn3Hs4Trl7U01m3roJ1DOHF1q6YuytFF2jpHqT5iAzVCbvNC0DH KjNFde1hUM8//AvxPqjf9IjZS8LwaP3z0GGHQt8tQQkaYcOtlLGdsYJAqZBpjmJybrAE y+fA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950661; x=1732555461; 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=VBgtkjSEbYTTKzs2OsUJSbyBpcPy82P3Qfcz05KH5DM=; b=iufzM1WDfHAwr46F8mo/HRgPKSH2D5WgJ9OzEiUToML+ydE69uoncXPpyWW61GV5Ze bfsY5qWiFs+yVzVwuyRnVhEpFL32dbeiHryeuMNvZVbV4dEnSXMtRdRc1m1cikZ1Vnx7 nAMc157gclYmgfH9vvn1PMT+JzfZxS3mtuEREBN0TdsU0SrsJnCDJ/nJaxZWGo7PmmoF 3gLJYXmJLKnc6beYdhjtU+onrlgLkln6NSI2f5X+C6YoEXPABX4k4H0uSSgbSAwtb2p2 y31XK5dqMtRJ010F02a8UI688uEEqki+kqQ7T3Ot3ne7zHiywjf8ZxivR2DemM4u08XY bzmQ== X-Gm-Message-State: AOJu0YyWeCiaf3X1goUaM5Q5M4Ma5+u4gApR0wlTIeO2r7Md4MhrW/Lm e3hzySclu3AWwokaRUAMYhBhYSpcTDRvLcYahvWw+5zuQ6uhSTA6ERfSn5YHyW4F4Xv5aDM5zDF tbVVnKw== X-Google-Smtp-Source: AGHT+IEtfHUwMv6Qgz1+4IxX3nYSm1Xv9+hPyGeTbVfIa6T3JJYCwtxXSq0Y6cpRHlWh5/YdsgTf/g== X-Received: by 2002:a17:902:d2c1:b0:20c:a174:f77 with SMTP id d9443c01a7336-212348d39c1mr39617695ad.32.1731950660835; Mon, 18 Nov 2024 09:24:20 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:20 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 6/7] docs: add a glossary Date: Mon, 18 Nov 2024 09:23:56 -0800 Message-Id: <20241118172357.475281-7-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::62b; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x62b.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 Signed-off-by: Pierrick Bouvier --- docs/devel/control-flow-integrity.rst | 2 + docs/devel/multi-thread-tcg.rst | 2 + docs/glossary/index.rst | 238 ++++++++++++++++++++++++++ docs/index.rst | 1 + docs/system/arm/virt.rst | 2 + docs/system/images.rst | 2 + docs/tools/qemu-nbd.rst | 2 + 7 files changed, 249 insertions(+) create mode 100644 docs/glossary/index.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/index.rst b/docs/glossary/index.rst new file mode 100644 index 00000000000..a2d4f3eae16 --- /dev/null +++ b/docs/glossary/index.rst @@ -0,0 +1,238 @@ +.. _Glossary: + +-------- +Glossary +-------- + +This section of the manual presents *simply* acronyms and terms QEMU developers +use. + +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 +----- + +QEMU system defines board models for various architectures. It's a description +of a SoC (system-on-chip) with various devices pre-configured, and can be +selected with the option ``-machine`` of qemu-system. +For virtual machines, you'll use ``virt`` board model, designed for this use +case. As an example, for Arm architecture, you can find the `model code +`_ and +associated `documentation `. + +Block +----- + +Block drivers are the available `disk formats ` 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 +------ + +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. It's ran by QEMU to support UEFI for virtual +machines. + +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 to debug +a given architecture without having access to hardware. + +glib2 +----- + +`GLib2 `_ is one of the most important library 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 +----------- + +`QEMU Guest agent ` is a daemon intended to be executed by guest +virtual machines and providing various services to help QEMU to interact with +it. + +Guest/Host +---------- + +Guest is the architecture of the virtual machine, which is emulated. +Host is the architecture on which QEMU is running on, which is native. + +Hypervisor +---------- + +The formal definition of an hypervisor is a program than can be used to manage a +virtual machine. QEMU itself is an hypervisor. + +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. + +Migration +--------- + +QEMU can save and restore the execution of a virtual machine, including across +different machines. This is provided by the `Migration framework`. + +NBD +--- + +`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. + +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 +------------------- + +`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 cpus 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. + +Patchwork +--------- + +`Patchwork `_ 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. + +QCOW +---- + +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. + +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. We didn't see a more efficient way to create debates and tensions in +a community of C programmers since the birth of C++. + +System mode +----------- + +QEMU System mode emulates a full machine, including its cpu, memory and devices. +It can be accelerated to hardware speed by using one of the hypervisors QEMU +supports. It is referenced as softmmu as well. + +TCG +--- + +`Tiny Code Generator ` is an intermediate representation (IR) used to run +guest instructions on host cpu, with both architectures possibly being +different. + +It is one of the accelerator supported by QEMU, and supports a lot of +guest/host architectures. + +User mode +--------- + +QEMU User mode allows to run programs for a guest architecture, on a host +architecture, by translating system calls and using TCG. 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 cb5e5098b65..2cad84cd77c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,3 +21,4 @@ Welcome to QEMU's documentation! specs/index devel/index codebase/index + glossary/index 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 ===================================== From patchwork Mon Nov 18 17:23:57 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 13878900 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 402ACD591A8 for ; Mon, 18 Nov 2024 17:25:42 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tD5Ug-00008v-BW; Mon, 18 Nov 2024 12:24:58 -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 1tD5UE-0008Qe-Ek for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:31 -0500 Received: from mail-pg1-x529.google.com ([2607:f8b0:4864:20::529]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tD5U9-0002qr-D4 for qemu-devel@nongnu.org; Mon, 18 Nov 2024 12:24:30 -0500 Received: by mail-pg1-x529.google.com with SMTP id 41be03b00d2f7-7f43259d220so1485345a12.3 for ; Mon, 18 Nov 2024 09:24:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1731950663; x=1732555463; 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=O5xaWyMs57+hnnqWUIpSm0cVCeYUwv1WfgxLMkRlc7c=; b=kRxe7hahlMiL62pLkLGsVTJudLtvTndyHZoFp6xPyjXAhFLyM4DbaM4BxBZ56Z2SAk jsceYgLNjvk8KHltPvp0XpLjtZmv8GdPT+u7nBMZNGVUdZ6IV6iKECFXu76eidFowX6S hCBsSQLdu94B1HKpwiO9wtafD5mqxQlTJJpJJtCnwQQKH3K1wEsfh7DYtgffM3FpNwDN yxQkjKYcRsXoGxU7CMIFFEex5Hl1AkS4uDiQRjaatKuG7KDPHnCbBpSQOYZFtIXdr3Z7 gOsoDJHMYcPrySNciQheE41mtpTkigiZcpaVqqMXGCbvmvWPJ23ZbQguH/NU1vRCOqPw S2FQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731950663; x=1732555463; 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=O5xaWyMs57+hnnqWUIpSm0cVCeYUwv1WfgxLMkRlc7c=; b=JC4GFZDPoTgW9jI/NYP6f3kY8VlLBvVG00Mp5Ukjvw/9WDTNiWYGEyo+EjSv7ofsqb Oz2BF8TXvSsj0RyCaSDGrQ0j5xgVH6rXDHPsTHXBIV8NeBYq0yCBcxHnjuyv1JGppmx9 gwBGHhnU0N/Z9vp+ATOGTuwC1GFGYNV7QhSBdua71B9sdKogMY03o1ihYTiL3L27JC58 VgSBYfeItNt6T6Pcv7Eodtdz7CIM5+yczWgaFChuDce9BhSMc/xjKt+LVj6IhT0v6ac8 Fuw66CtFBbt21JwhwyB1001YdVbkXn6NE8cKmHMQK8kAfYH0k6VMqMldLNxOFVHtfTZN ZSvg== X-Gm-Message-State: AOJu0Yx9Ci9mvHMQ39iX7G5T0nVRp2ldrmzUiehKnQnfR4UJ70WoGwzE bUZiEfiJXKI6fLK2p4VTg51bWOHWLormDVPZkTi1A8qsFyrcynkzqf5MDZtTGaBYQax6l3+Qni6 81Ly7ng== X-Google-Smtp-Source: AGHT+IFd+isfj+MijvIfhlYm0YwRz6KEGHY0eaL6yeO5vKqUx6emPrFwrqa4l0559t1iCFG6uOulPQ== X-Received: by 2002:a05:6a21:3985:b0:1dc:7907:6d67 with SMTP id adf61e73a8af0-1dc90bf49b3mr24723643637.40.1731950662036; Mon, 18 Nov 2024 09:24:22 -0800 (PST) Received: from linaro.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-211d0f55d04sm59469765ad.264.2024.11.18.09.24.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 18 Nov 2024 09:24:21 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Richard Henderson , Andrew Melnychenko , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Jason Wang , Thomas Huth , alex.bennee@linaro.org, Vladimir Sementsov-Ogievskiy , Fabiano Rosas , Kevin Wolf , Markus Armbruster , Eric Blake , qemu-arm@nongnu.org, Yuri Benditovich , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Michael Roth , Konstantin Kostiuk , Paolo Bonzini , Peter Xu , gustavo.romero@linaro.org, Peter Maydell , Pierrick Bouvier Subject: [PATCH 7/7] docs: add a how to section Date: Mon, 18 Nov 2024 09:23:57 -0800 Message-Id: <20241118172357.475281-8-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241118172357.475281-1-pierrick.bouvier@linaro.org> References: <20241118172357.475281-1-pierrick.bouvier@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::529; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pg1-x529.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 Signed-off-by: Pierrick Bouvier --- docs/devel/build-system.rst | 2 + docs/how-to/index.rst | 146 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 149 insertions(+) create mode 100644 docs/how-to/index.rst diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst index d42045a2325..db444787e37 100644 --- a/docs/devel/build-system.rst +++ b/docs/devel/build-system.rst @@ -1,3 +1,5 @@ +.. _build: + ================================== The QEMU build system architecture ================================== diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst new file mode 100644 index 00000000000..3a9d4d777df --- /dev/null +++ b/docs/how-to/index.rst @@ -0,0 +1,146 @@ +.. _how-to: + +------ +How to +------ + +This section of the manual will give you some commands to do various tasks with +QEMU. It does not intend to be complete, but to be simple. + +Build +----- + +First you need setup your `build environment `. + +Then, you can build QEMU using: + +:: + + git clone https://gitlab.com/qemu-project/qemu + cd qemu + ./configure + ninja -C build + # all binaries are in ./build + +By default, QEMU build is optimized. You may want to switch to debug builds +instead (non optimized, and with more runtime checks enabled): + +:: + + ./configure --enable-debug + +It's recommended to use sanitizers to catch issues when developing your change. + +:: + + ./configure --enable-asan --enable-ubsan + # Of course, you can combine debug and sanitizers if needed + +You can find more information on `build page `. + +Test +---- + +QEMU has a lot of tests, mainly in 4 categories: + +:: + + # run tests related to TCG. They are based on Makefiles. + make check-tcg + # run system tests, running a full VM, with avocado framework + make check-avocado + # run functional tests, running a full VM, integrated with Meson + make check-functional + # run all other tests, integrated with Meson + make check + +You can find more information on `testing page`. + +Use QEMU +-------- + +To create a 20 gigabytes disk image usable with qemu-system: + +:: + + qemu-img create system.img 20g + +To run an x86_64 system emulated, with 4 cpus, 8G of memory and an install iso: + +:: + + qemu-system-x86_64 -smp 4 -m 8G system.img -cdrom install.iso + +To boot directly a Linux Kernel: + +:: + + qemu-system-x86_64 -kernel bzImage -hda system.img -append "root=/dev/hda" + +To boot an aarch64 system emulated, you need to specify a UEFI and associated +pflash. Once started, you can switch to Serial output by clicking on View -> +Serial0. + +:: + + # UEFI can be obtained from debian package qemu-efi-aarch64. + # First, we need to copy a file to save UEFI variables: + # cp /usr/share/AAVMF/AAVMF_VARS.fd . + qemu-system-aarch64 \ + -m 8G \ + -smp 4 \ + -M virt \ + -cpu max \ + -device virtio-blk-pci,drive=root \ + -drive if=none,id=root,file=system.img \ + -drive if=pflash,readonly=on,file=/usr/share/AAVMF/AAVMF_CODE.fd \ + -drive if=pflash,file=AAVMF_VARS.fd \ + -cdrom install.iso + +To run git using QEMU user-mode: + +:: + + qemu-x86_64 /usr/bin/git --version + +Contribute +---------- + +We recommend using `git-publish `_ for +contributing. You need to configure `git send-email +`_ first. + +:: + + git checkout -b my_feature + ... # edit, build, test + # When ready to send the series... + + # Add upstream QEMU repo as a remote. + git remote add upstream https://gitlab.com/qemu-project/qemu + # Fetch all new content. + git fetch -a upstream + + # Rebase your branch on top of upstream master, and include a signoff. + git rebase -i upstream/master --signoff + # Check your patches are correct. + ./scripts/checkpatch.pl $(git merge-base upstream/master HEAD)..HEAD + + # Send your series, you'll be given a chance to edit cover letter for it. + git-publish + + # After review, and other changes, you can send a v2 simply by using: + git-publish + +If you need to apply locally an existing series, you can use `b4 +`_ (installable via pip) to retrieve it: + +:: + + b4 shazam + # message id is an identifier present in email sent. + # when using patchwork, it is the last part of a series url (2024...): + # https://patchew.org/QEMU/20241118021820.4928-1-joel@jms.id.au/ + +More complete information is available on our `Submit a patch page +`. diff --git a/docs/index.rst b/docs/index.rst index 2cad84cd77c..e275a9223dd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,5 +20,6 @@ Welcome to QEMU's documentation! interop/index specs/index devel/index + how-to/index codebase/index glossary/index