On 12/17/18 7:20 AM, Thorsten Leemhuis wrote:
>
> Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
> ---
> Documentation/admin-guide/tainted-kernels.rst | 105 ++++++++++++++++--
> 1 file changed, 96 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst
> index 28a869c509a0..aabd307a178a 100644
> --- a/Documentation/admin-guide/tainted-kernels.rst
> +++ b/Documentation/admin-guide/tainted-kernels.rst
> @@ -1,10 +1,102 @@
> Tainted kernels
> ---------------
>
> -Some oops reports contain the string **'Tainted: '** after the program
> -counter. This indicates that the kernel has been tainted by some
> -mechanism. The string is followed by a series of position-sensitive
> -characters, each representing a particular tainted value.
> +The kernel will mark itself as 'tainted' when something occurs that
> +might be relevant later when investigating problems. Don't worry
> +yourself too much about this, most of the time it's not a problem to run
> +a tainted kernel; the information is mainly of interest once someone
> +wants to investigate some problem, as its real cause might be the event
> +that got the kernel tainted. That's why the kernel will remain tainted
> +even after you undo what caused the taint (i.e. unload a proprietary
> +kernel module), to indicate the kernel remains not trustworthy. That's
> +also why the kernel will print the tainted state when it noticed
notices
> +ainternal problem (a 'kernel bug'), a recoverable error ('kernel oops')
an internal
> +or a nonrecoverable error ('kernel panic') and writes debug information
> +about this to the logs ``dmesg`` outputs. It's also possible to check
> +the tainted state at runtime through a file in ``/proc/``.
> +
> +
> +Tainted flag in bugs, oops or panics messages
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +You find the tainted state near the top after the list of loaded
> +modules. The state is part of the line that begins with mentioning CPU
> +('CPU:'), Process ID ('PID:'), and a shorted name of the executed
shortened
> +command ('Comm:') that triggered the event. When followed by **'Not
> +tainted: '** the kernel was not tainted at the time of the event; if it
> +was, then it will print **'Tainted: '** and characters either letters or
> +blanks. The meaning of those characters is explained in below table. The
in the table below. The
> +output for example might state '``Tainted: P WO``' when the kernel got
> +tainted earlier because a proprietary Module (``P``) was loaded, a
> +warning occurred (``W``), and an externally-built module was loaded
> +(``O``). To decode other letters use below table.
use the table below.
> +
> +
> +Decoding tainted state at runtime
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +At runtime, you can query the tainted state by reading
> +``/proc/sys/kernel/tainted``. If that returns ``0``, the kernel is not
> +tainted; any other number indicates the reasons why it is. You might
> +find that number in below table if there was only one reason that got
in the table below for the
> +the kernel tainted. If there were multiple reasons you need to decode
kernel to be tainted. reasons,
> +the number, as it is a bitfield, where each bit indicates the absence or
> +presence of a particular type of taint. You can use the following python
> +command to decode::
> +
> + $ python3 -c 'from pprint import pprint; from itertools import zip_longest; pprint(list(zip_longest(range(1,17), reversed(bin(int(open("/proc/sys/kernel/tainted").read()))[2:]),fillvalue="0")))'
> + [(1, '1'),
> + (2, '0'),
> + (3, '0'),
> + (4, '0'),
> + (5, '0'),
> + (6, '0'),
> + (7, '0'),
> + (8, '0'),
> + (9, '0'),
> + (10, '1'),
> + (11, '0'),
> + (12, '0'),
> + (13, '1'),
> + (14, '0'),
> + (15, '0'),
> + (16, '0')]
> +
> +In this case ``/proc/sys/kernel/tainted`` contained ``4609``, as the
> +kernel got tainted because a proprietary Module (Bit 1) got loaded, a
> +warning occurred (Bit 10), and an externally-built module got loaded
> +(Bit 13). To decode other bits use below table.
use the table below.
> +
> +
> +Table for decoding tainted state
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +=== === ====== ========================================================
> +Bit Log Int Reason that got the kernel tainted
> +=== === ====== ========================================================
> + 1) G/P 0 proprietary module got loaded
> + 2) _/F 2 module was force loaded
> + 3) _/S 4 SMP kernel oops on a officially SMP incapable processor
> + 4) _/R 8 module was force unloaded
> + 5) _/M 16 processor reported a Machine Check Exception (MCE)
> + 6) _/B 32 bad page referenced or some unexpected page flags
> + 7) _/U 64 taint requested by userspace application
> + 8) _/D 128 kernel died recently, i.e. there was an OOPS or BUG
> + 9) _/A 256 ACPI table overridden by user
> +10) _/W 512 kernel issued warning
> +11) _/C 1024 staging driver got loaded
> +12) _/I 2048 workaround for bug in platform firmware in use
> +13) _/O 4096 externally-built ("out-of-tree") module got loaded
> +14) _/E 8192 unsigned module was loaded
> +15) _/L 16384 soft lockup occurred
> +16) _/K 32768 Kernel live patched
> +=== === ====== ========================================================
> +
> +Note: To make reading easier ``_`` is representing a blank in this
> +table.
> +
> +More detailed explanation for tainting
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> 1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
> any proprietary module has been loaded. Modules without a
> @@ -52,8 +144,3 @@ characters, each representing a particular tainted value.
>
> 16) ``K`` if the kernel has been live patched.
>
> -The primary reason for the **'Tainted: '** string is to tell kernel
> -debuggers if this is a clean kernel or if anything unusual has
> -occurred. Tainting is permanent: even if an offending module is
> -unloaded, the tainted value remains to indicate that the kernel is not
> -trustworthy.
>
thanks for the update.
--
~Randy
