Received: by 2002:ab2:3350:0:b0:1f4:6588:b3a7 with SMTP id o16csp1813344lqe; Tue, 9 Apr 2024 00:32:14 -0700 (PDT) X-Forwarded-Encrypted: i=3; AJvYcCXAhY5FSjibpcZYbE4tz6EXNmFbwIXel01SGIEycZpJYX0FFWB7q60zaW6yifHJFrbjmPXXZbcN3lTD6sb3/SVRzpeNMWDamBLFwvE0Kw== X-Google-Smtp-Source: AGHT+IFzE7XLmO2DDQNj3KMjz4wzAzxPZL/io7/3Exp91ws5ZjeKlTuHQvo1gq60jmrm/Pa2Od2W X-Received: by 2002:aca:1712:0:b0:3c5:f8b7:caca with SMTP id j18-20020aca1712000000b003c5f8b7cacamr3499419oii.0.1712647933850; Tue, 09 Apr 2024 00:32:13 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1712647933; cv=pass; d=google.com; s=arc-20160816; b=owLEBeb2YUeAAq/BGep2mMNG57w4AAj9JXXvfPxJ9PrXSqK1OW97HuOlGdpUfJpsY9 IGFJyY5ZXIdmXtPKDkF3OE7RbnB6HQUGpRD/AmUQ8yNBQClolFBGn1VNezanMjlYIpiK mj7z1cYa/bUeiZ6LAtiDUyQEI8e4MY1isQBN1zcLIVJFKFLzmsL3c7Nbd89BuA8sezPy suqH1JJ3KlQYc7MHsckeYozEPbLagMkHq+N9dt9XiUkv8O5CsGDIa3CepvaestGl8Kxw jMeLX4+465OPULMmdAn0OL5uiqmdcaqGPfTk4QlSSA8Pxk3oiE1ft4R4wq+O3ktgXyld dhjA== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=LGeHfhhpbX0NVOpB0WHhcEnxl/s/Lvh5IZ1Wpx5G0xY=; fh=LLgfFQ/VTqeVL5ku4k8M8FUiQpAxJbhBgNJC+lG8y0k=; b=HQ/9SZlknTFCNFYB+8UtWvh7d6jkfY8gUl3rOQRa8OqQYN+iPw5whNx+OJe9ze0Zpf 0HK8h3WeuEqz3RVzhFw5Q05O0NqOcnxN9xUWZVhgzvHYs0N4+LgTZJcq87d1P6q8WUjB 2OAXTSKVaNn8/KgXoTQq8LGOqt7DhQu/A1dqi4G/ht2/eagRSVHqF2n8g1d1b/97X0UY 285rdGW5uHgEtWUJLgSmVRD70mRhRpOTtK9e27glO47MiKVu3Yz8L8baMFA+/zOvoGy4 xTsAg1Qrbwtsbi1gqVtZrI9nO/9OnyDrdPbH9iH7FYRD7lVFgWv1ENMf3qNoOIbK6xfB Xjgg==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@leemhuis.info header.s=he214686 header.b=HZquhLkV; arc=pass (i=1 spf=pass spfdomain=leemhuis.info dkim=pass dkdomain=leemhuis.info); spf=pass (google.com: domain of linux-kernel+bounces-136358-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-136358-linux.lists.archive=gmail.com@vger.kernel.org" Return-Path: Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [2604:1380:45d1:ec00::1]) by mx.google.com with ESMTPS id ow42-20020a05620a822a00b0078be2397abdsi9589506qkn.347.2024.04.09.00.32.13 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Apr 2024 00:32:13 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel+bounces-136358-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@leemhuis.info header.s=he214686 header.b=HZquhLkV; arc=pass (i=1 spf=pass spfdomain=leemhuis.info dkim=pass dkdomain=leemhuis.info); spf=pass (google.com: domain of linux-kernel+bounces-136358-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-136358-linux.lists.archive=gmail.com@vger.kernel.org" Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 55FF31C21576 for ; Tue, 9 Apr 2024 07:32:13 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 8B3F67E78E; Tue, 9 Apr 2024 07:30:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=leemhuis.info header.i=@leemhuis.info header.b="HZquhLkV" Received: from wp530.webpack.hosteurope.de (wp530.webpack.hosteurope.de [80.237.130.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 931AA7BAFE; Tue, 9 Apr 2024 07:30:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.237.130.52 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1712647858; cv=none; b=ZKgsvupKV+F8TWpNZwFbXKxEQBj1+FPfCq2U8fkMnboiDqB02WZkCPJYIFZBpob5T1JQxoQEPkZitOQpFGkaf0ZoRbkapz7ijAweJkNrEhld2TyzeDMIcvswRwGUxbLgBBgW5Sibu4Z66UuZ8sLiabacRFAOCWUZZzs49LxXL90= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1712647858; c=relaxed/simple; bh=j4STcrPuuHe6kQK78UyT+7uWG0z053vYmOT+DzSljc0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TQDqU65Mx1vfC86alXYOjxRP5phiG4NsSOFjPOJGNGXwf7f3LcRK+PbOS59wckdq0yNFeBpp0LVquSKvqB/gkpKzaFoT0LFcnI1ODoqUGOtEqu3aDQjDAk2UTXB57pzLj2pHkofmmNF/ATQdFPVEJ9bqrHP+WWe3vADEZW5an2E= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=leemhuis.info; spf=pass smtp.mailfrom=leemhuis.info; dkim=pass (2048-bit key) header.d=leemhuis.info header.i=@leemhuis.info header.b=HZquhLkV; arc=none smtp.client-ip=80.237.130.52 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=leemhuis.info Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=leemhuis.info DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=leemhuis.info; s=he214686; h=Content-Transfer-Encoding:MIME-Version: References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:From:Sender: Reply-To:Subject:Date:Message-ID:To:Cc:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:In-Reply-To: References; bh=LGeHfhhpbX0NVOpB0WHhcEnxl/s/Lvh5IZ1Wpx5G0xY=; t=1712647855; x=1713079855; b=HZquhLkVzd1582+mrANxa+lFQZY0BrVsFfvIINnOBWD/HER7bPjXZCcX72yGq a76cdVIs+LJnJcgV5VymzRPuC8ZBTnHcL3pSLpSSL0AXTwdBcVs/KaNOzpoY4N/lR38xonLRvdhqk nS9ZcuPHcaq5uSjgwoY0fxZnPR7pXTkSiZiuqMipjhqI1O/wG1/5FcdMEM8IwxY8TCGOyCAYLWqa4 7cIlA1fY2KlUAIwH3gI4q2C9R+OLbBvPh5sngAWkOB+6yJ/ntr5RPAIGeVUIqUfqjZiSndvoNrVh2 Zj1A26eb9uAYVRs8rQEJia2jSpjJyaItkE1naC7YXyJqHS1q+Q==; Received: from ip4d148da6.dynamic.kabel-deutschland.de ([77.20.141.166] helo=truhe.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) id 1ru5wR-0006Ld-6C; Tue, 09 Apr 2024 09:30:51 +0200 From: Thorsten Leemhuis To: Jonathan Corbet Cc: regressions@lists.linux.dev, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Bagas Sanjaya , =?UTF-8?q?Petr=20Tesa=C5=99=C3=ADk?= Subject: [PATCH v2 4/6] docs: verify/bisect: explain testing reverts, patches and newer code Date: Tue, 9 Apr 2024 09:30:47 +0200 Message-ID: X-Mailer: git-send-email 2.44.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1712647855;18e5c630; X-HE-SMSGID: 1ru5wR-0006Ld-6C Rename 'Supplementary tasks' to 'Complementary tasks' while introducing a section 'Optional tasks: test reverts, patches, or later versions': the latter is something readers occasionally will have to do after reporting a bug and thus is best covered here. Signed-off-by: Thorsten Leemhuis --- .../verify-bugs-and-bisect-regressions.rst | 128 ++++++++++++++++-- 1 file changed, 115 insertions(+), 13 deletions(-) diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index 355c2cea5230d9..1987c827211fce 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -160,7 +160,7 @@ will be considered the 'good' release and used to prepare the .config file. this step (e.g. build, install, boot, and test a kernel to then tell Git the outcome). Do so again and again until Git shows which commit broke things. If you run short of disk space during this process, check the - section 'Supplementary tasks: cleanup during and after the process' + section 'Complementary tasks: cleanup during and after the process' below. d) Once your finished the bisection, put a few things away:: @@ -182,7 +182,7 @@ will be considered the 'good' release and used to prepare the .config file. kernel; just this time skip the first command copying the base .config file over, as that already has been taken care off. -* **Supplementary tasks**: cleanup during and after the process. +* **Complementary tasks**: cleanup during and after the process. a) To avoid running out of disk space during a bisection, you might need to remove some kernels you built earlier. You most likely want to keep those @@ -205,6 +205,18 @@ will be considered the 'good' release and used to prepare the .config file. the kernels you built earlier and later you might want to keep around for a week or two. +* **Optional task**: test a debug patch or a proposed fix later:: + + git fetch mainline + git switch --discard-changes --detach mainline/master + git apply /tmp/foobars-proposed-fix-v1.patch + cp ~/kernel-config-working .config + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1' + + Build, install, and boot a kernel as described in *segment 1, section b* -- + but this time omit the first command copying the build configuration over, + as that has been taken care of already. + .. _introguide_bissbs: Step-by-step guide on how to verify bugs and bisect regressions @@ -232,7 +244,9 @@ developers are obliged to act upon. :ref:`Segment 3: perform a bisection and validate the result `. - :ref:`Supplementary tasks: cleanup during and after following this guide `. + :ref:`Complementary tasks: cleanup during and after following this guide `. + + :ref:`Optional tasks: test reverts, patches, or later versions `. The steps in each segment illustrate the important aspects of the process, while a comprehensive reference section holds additional details for almost all of the @@ -669,7 +683,7 @@ be a waste of time. [:ref:`details `] Do you follow this guide to verify if a problem is present in the code currently supported by Linux kernel developers? Then you are done at this point. If you later want to remove the kernel you just built, check out -:ref:`Supplementary tasks: cleanup during and after following this guide `. +:ref:`Complementary tasks: cleanup during and after following this guide `. In case you face a regression, move on and execute at least the next segment as well. @@ -888,7 +902,7 @@ each kernel on commodity x86 machines. .. _introclosure_bissbs: -Supplementary tasks: cleanup during and after the bisection +Complementary tasks: cleanup during and after the bisection ----------------------------------------------------------- During and after following this guide you might want or need to remove some of @@ -950,6 +964,81 @@ space might run out. [:ref:`details `] +.. _introoptional_bissbs: + +Optional: test reverts, patches, or later versions +-------------------------------------------------- + +While or after reporting a bug, you might want or potentially will be asked to +test reverts, debug patches, proposed fixes, or other versions. In that case +follow these instructions. + +* Update your Git clone and check out the latest code. + + * In case you want to test mainline, fetch its latest changes before checking + its code out:: + + git fetch mainline + git switch --discard-changes --detach mainline/master + + * In case you want to test a stable or longterm kernel, first add the branch + holding the series you are interested in (6.2 in the example), unless you + already did so earlier:: + + git remote set-branches --add stable linux-6.2.y + + Then fetch the latest changes and check out the latest version from the + series:: + + git fetch stable + git switch --discard-changes --detach stable/linux-6.2.y + +* Copy your kernel build configuration over:: + + cp ~/kernel-config-working .config + +* Your next step depends on what you want to do: + + * In case you just want to test the latest codebase, head to the next step, + you are already all set. + + * In case you want to test if a revert fixes an issue, revert one or multiple + changes by specifying their commit ids:: + + git revert --no-edit cafec0cacaca0 + + Now give that kernel a special tag to facilitates its identification and + prevent accidentally overwriting another kernel:: + + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted' + + * In case you want to test a patch, store the patch in a file like + '/tmp/foobars-proposed-fix-v1.patch' and apply it like this:: + + git apply /tmp/foobars-proposed-fix-v1.patch + + In case of multiple patches, repeat this step with the others. + + Now give that kernel a special tag to facilitates its identification and + prevent accidentally overwriting another kernel:: + + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1' + +* Build a kernel using the familiar commands, just without copying the kernel + build configuration over, as that has been taken care of already:: + + make olddefconfig && + make -j $(nproc --all) + # * Check if the free space suffices holding another kernel: + df -h /boot/ /lib/modules/ + sudo make modules_install + command -v installkernel && sudo make install + make -s kernelrelease | tee -a ~/kernels-built + reboot + +* Now verify you booted the newly built kernel and check it. + +[:ref:`details `] .. _submit_improvements: @@ -1986,20 +2075,33 @@ build artifacts and the Linux sources, but will leave the Git repository (~/linux/.git/) behind -- a simple ``git reset --hard`` thus will bring the sources back. -Removing the repository as well would likely be unwise at this point: there is a -decent chance developers will ask you to build another kernel to perform -additional tests. This is often required to debug an issue or check proposed -fixes. Before doing so you want to run the ``git fetch mainline`` command again -followed by ``git checkout mainline/master`` to bring your clone up to date and -checkout the latest codebase. Then apply the patch using ``git apply -`` or ``git am `` and build yet another kernel using the -familiar commands. +Removing the repository as well would likely be unwise at this point: there +is a decent chance developers will ask you to build another kernel to +perform additional tests -- like testing a debug patch or a proposed fix. +Details on how to perform those can be found in the section :ref:`Optional +tasks: test reverts, patches, or later versions `. Additional tests are also the reason why you want to keep the ~/kernel-config-working file around for a few weeks. [:ref:`back to step-by-step guide `] +.. _introoptional_bisref: + +Test reverts, patches, or later versions +---------------------------------------- + + *While or after reporting a bug, you might want or potentially will be asked + to test reverts, patches, proposed fixes, or other versions.* + [:ref:`... `] + +All the commands used in this section should be pretty straight forward, so +there is not much to add except one thing: when setting a kernel tag as +instructed, ensure it is not much longer than the one used in the example, as +problems will arise if the kernelrelease identifier exceeds 63 characters. + +[:ref:`back to step-by-step guide `]. + Additional reading material =========================== -- 2.44.0