From nobody Sun Feb 8 20:12:38 2026 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 3A7E42DC76B; Sun, 26 Oct 2025 12:42:33 +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=1761482555; cv=none; b=dMh9Js+YcpFzoO1LlOcaroSHC4HB4R2h3KkI6HtfauDmJtjKgNsnsHhPPxJ7LDRcxgwv82jrp34iZFT3RB2rB9PhqJ4ZvlCuKuy1U7zXzOTzL+x/ngTTp+xm9bXaeKg9s1AwfyGsNONAFbKrIWUosuCL+T1KIo4D6R2jh0kyq48= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1761482555; c=relaxed/simple; bh=9RlaPYJbqiM2OFxkSIEpzf6QXLP5GS9MehP4KTaVRHk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=NdcvjDV+Fgd4sZHIdU1+YhyTLe7+MibZPQnmRYqOdWI/IW2uaXQvw5UDQvdSLKw0nvTKZVSayE1TDXYBQlbZahGv9iZhumKt2NCTQW9/XKFR7Xet93hFzYOaBf/pwdY8Biv8zBJ4MEPiTzRBfX1NN+aixNxKqA2PaKAPFRqZKDE= 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=WcBO4AJO; 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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=leemhuis.info header.i=@leemhuis.info header.b="WcBO4AJO" 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=OVOHoODjbTBKiS2pRJUZZiaxPXulh2JYJvHA1xkr8fg=; t=1761482553; x=1761914553; b=WcBO4AJOs80Vd0tFMCNg6QkVZIG5ez0L+koWej9CyeeBguc94J7PNxG+er6oS DummpkRzWoIPuSm8oTX28GWdJPU4eouXAzy2SvP18Spz4Z1Q1vJJqLtGd1cOJ5MW4Eaqg2bc6uJNv HgaXxksUOsy6EtpULz4vlVcPwKNinRJeITlCv2FK4mu2MOIBzCJAc1waC3ME1yOpCl7fKajurEeAP QgUmN/LpBJx/2BzZ0i63MlgFrgXRA7Zxfw1smPMKcI9lNpJTF0Xfr2NI4qR0Rn2txyPqmUNtpP0e4 jIaRH29PXXUuaMj+kTOlh/6V7hULYLu29WGEu0jkNyLxiLS9qw==; Received: from [2a02:8108:8984:1d00:a8ad:ebd4:6fc6:160] (helo=luggage.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_X25519__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) id 1vD04o-001mXn-1a; Sun, 26 Oct 2025 13:42:26 +0100 From: Thorsten Leemhuis To: Jonathan Corbet Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org, regressions@lists.linux.dev, linux-kernel@vger.kernel.org Subject: [PATCH v1 11/30] docs: reporting-issues: improve first tainted check Date: Sun, 26 Oct 2025 13:42:02 +0100 Message-ID: X-Mailer: git-send-email 2.51.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: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1761482553;4a80bc7e; X-HE-SMSGID: 1vD04o-001mXn-1a Content-Type: text/plain; charset="utf-8" Fine-tune the instruction regarding the first tainted check. Signed-off-by: Thorsten Leemhuis --- .../admin-guide/reporting-issues.rst | 136 ++++++++++-------- 1 file changed, 76 insertions(+), 60 deletions(-) diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation= /admin-guide/reporting-issues.rst index 19f1ffabf5ae30..452733669debf5 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -84,9 +84,14 @@ following the others is usually in your own interest. =20 [:ref:`details `] =20 +.. _taintone_repisbs: + +* Check if the kernel was already 'tainted' when the issue first occurred:= The + event that resulted in this flag being set might have led to issues that + otherwise would never happen. + + [:ref:`details `] =20 - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. =20 * Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the `Linux Kernel Ma= iling @@ -397,72 +402,83 @@ to set warnings and errors apart. [:ref:`back to step-by-step guide `] =20 =20 +.. _taintone_repiref: + Check 'taint' flag ------------------ =20 - *Check if your kernel was 'tainted' when the issue occurred, as the ev= ent - that made the kernel set this flag might be causing the issue you face= .* + *Check if the kernel was already 'tainted' when the issue first occurred= * [:ref:`... `] =20 The kernel marks itself with a 'taint' flag when something happens that mi= ght -lead to follow-up errors that look totally unrelated. The issue you face m= ight -be such an error if your kernel is tainted. That's why it's in your intere= st to -rule this out early before investing more time into this process. This is = the -only reason why this step is here, as this process later will tell you to -install the latest mainline kernel; you will need to check the taint flag = again -then, as that's when it matters because it's the kernel the report will fo= cus -on. - -On a running system is easy to check if the kernel tainted itself: if ``cat -/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and -everything is fine. Checking that file is impossible in some situations; t= hat's -why the kernel also mentions the taint status when it reports an internal -problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a -non-recoverable error before halting operation (a 'kernel panic'). Look ne= ar -the top of the error messages printed when one of these occurs and search = for a -line starting with 'CPU:'. It should end with 'Not tainted' if the kernel = was -not tainted when it noticed the problem; it was tainted if you see 'Tainte= d:' -followed by a few spaces and some letters. - -If your kernel is tainted, study Documentation/admin-guide/tainted-kernels= .rst -to find out why. Try to eliminate the reason. Often it's caused by one the= se -three things: - - 1. A recoverable error (a 'kernel Oops') occurred and the kernel tainted - itself, as the kernel knows it might misbehave in strange ways after t= hat - point. In that case check your kernel or system log and look for a sec= tion - that starts with this:: +lead to follow-up errors looking totally unrelated. Your issue might +be such an error, in which case there is nothing to report. That is why it= is +in your interest to check the taint status early in the reporting process.= This +is the main reason why this step is here in the guide, as you most likely = will +have to install a different kernel for reporting later -- and then need to +recheck the flag, as that is when it matters. + +To check the tainted flag, execute ``cat /proc/sys/kernel/tainted``: If it +returns '0' everything is fine; if it contains a higher number, it is tain= ted. + +In some situations it is impossible to check that file. That is +why the kernel also mentions the taint status when it reports small (a +'warning' or a 'bug') or big (an 'Oops' or a 'panic') problems. In such ca= ses, +search for a line starting with 'CPU:' near the top of the error messages +printed on the screen or in the log. If the kernel at that point considered +itself to be fine, it will end with 'Not tainted'; if not, you will see +'Tainted:' followed by a few spaces and some letters. + +If your kernel is tainted, check Documentation/admin-guide/tainted-kernels= .rst +to find out why. Note: It is quite possible that the problem you ran into +caused the kernel to taint itself, in which case you are free to ignore the +flag. But if the kernel was tainted beforehand, you might have to eliminat= e the +cause or rule out that it is an influence. + +These are the most frequent reasons why the kernel set the flag: + +1. Some kind of error (like a 'kernel Oops') occurred. The kernel then tai= nts + itself, as it might misbehave in unexpected ways afterwards. + In that case check your kernel or system log and look for a section + starting with:: =20 Oops: 0000 [#1] SMP =20 - That's the first Oops since boot-up, as the '#1' between the brackets = shows. - Every Oops and any other problem that happens after that point might b= e a - follow-up problem to that first Oops, even if both look totally unrela= ted. - Rule this out by getting rid of the cause for the first Oops and repro= ducing - the issue afterwards. Sometimes simply restarting will be enough, some= times - a change to the configuration followed by a reboot can eliminate the O= ops. - But don't invest too much time into this at this point of the process,= as - the cause for the Oops might already be fixed in the newer Linux kernel - version you are going to install later in this process. - - 2. Your system uses a software that installs its own kernel modules, for - example Nvidia's proprietary graphics driver or VirtualBox. The kernel - taints itself when it loads such module from external sources (even if - they are Open Source): they sometimes cause errors in unrelated kernel - areas and thus might be causing the issue you face. You therefore have= to - prevent those modules from loading when you want to report an issue to= the - Linux kernel developers. Most of the time the easiest way to do that i= s: - temporarily uninstall such software including any modules they might h= ave - installed. Afterwards reboot. - - 3. The kernel also taints itself when it's loading a module that resides = in - the staging tree of the Linux kernel source. That's a special area for - code (mostly drivers) that does not yet fulfill the normal Linux kernel - quality standards. When you report an issue with such a module it's - obviously okay if the kernel is tainted; just make sure the module in - question is the only reason for the taint. If the issue happens in an - unrelated area reboot and temporarily block the module from being load= ed - by specifying ``foo.blacklist=3D1`` as kernel parameter (replace 'foo'= with - the name of the module in question). + That is the first Oops since boot-up, as the '#1' between the brackets = shows. + Every later Oops and any other problem that happens afterwards might be + a follow-up issue + that would never have happened otherwise, even if both look totally unr= elated. + Rule this out by eliminating the cause for the first Oops and reproduci= ng + the issue afterwards. Sometimes simply restarting will be enough; other= times + a change to the configuration followed by a reboot can eliminate the Oo= ps. + + Note: Do not invest too much time into this while you are still on an + outdated or vendor kernel: The cause for the Oops might already be fixe= d in + a newer Linux kernel + version you most likely will have to install for reporting while follow= ing + this guide. + +2. Your system uses software that installs externally developed kernel mod= ules, + for example, kernel modules from Nvidia, OpenZFS, VirtualBox, or VMware= . The + kernel taints itself when it loads such 'out-of-tree' modules -- no mat= ter + what license they use, as such modules can cause errors in unrelated ke= rnel + areas and thus might be leading to the issue you face. You therefore ha= ve to + prevent those modules from loading when you want to report an issue to = the + Linux kernel developers. Most of the time the easiest way to do that: + temporarily uninstall such software including any modules they might ha= ve + installed; afterwards reboot. + +3. The kernel taints itself when it loads a module that resides in + the staging section of the Linux kernel source. That is a special area = for + code (mostly drivers) that does not yet fulfill the normal Linux kernel + quality standards. When you report an issue with such a module, it is + totally okay if the kernel is tainted; just make sure the module in + question is the only reason for the taint. If the issue happens in an + unrelated area, it is wise to rule out that it is an influence. To do s= o, + reboot and temporarily block the module from being loaded by specifying + ``foo.blacklist=3D1`` as kernel boot parameter (replace 'foo' with the = name of + the module in question). + +[:ref:`back to step-by-step guide `] =20 =20 Search for existing reports, first run --=20 2.51.0